Skip to Content
FoundationsThe Cradle substrate

The Cradle substrate

The Cradle is Nebbos’s data substrate. Every artifact your tenant produces — a memory shard, a KG node, a session report, a task row, an audit event — lands in it, indexed together, addressable through the same shared-scope selectors.

This page is for developers integrating against Nebbos. It documents the five-layer stack, the row-level isolation model, the MCP consultation contract, and the endpoints your code will call. If you want the conceptual overview, read Architecture. If you want the schema, read Data model reference.

The five layers

LayerContentsRead scopeWrite authorityRetention
1 · Root doctrineRatified doctrine, Constitution articles, governance corpusAll tenants (identical)Platform ratification onlyImmutable except by superseding article
2 · TenantTenant memory, tool registry, tenant policyTenant-scoped (RLS)Tenant admin + delegated tokensTenant-configurable
3 · UserUser memory, per-user preferences, signature emojiUser-scoped (RLS)User + tenant-admin under sovereignty rulesUser-configurable
4 · AgentPearl per-department memory, skill catalog, per-invocation stateDepartment-scopedAgent + tenant-adminTenant retention policy
5 · SessionSession shards, turn-scoped state, ephemeral wave framesSession-scopedSession actorTTL, minutes to hours

Higher layers reference vocabulary defined at Layer 1. Writes that introduce unresolvable references return 422 Unprocessable Entity with error code reference_chain_broken.

Row-level isolation

Every scoped table in the Cradle ships with three RLS statements. Applied to tasks as example:

ALTER TABLE tasks ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON tasks USING (tenant_id = current_setting('app.current_tenant_id')::uuid); CREATE POLICY bypass_all ON tasks USING (current_setting('app.bypass_all', true)::boolean) WITH CHECK (current_setting('app.bypass_all', true)::boolean);

bypass_all is stored but not enforced by default. It activates only when a session-level GUC sets app.bypass_all=true, and every activation lands as an audit event. Application code never sets this GUC; only administrative migrations do.

Tables that carry the RLS three-statement pattern:

TableScope columnNotes
tenantsidPublic read for provisioning; write restricted to platform
entity_nodetenant_id, shared_scopeThe 3-tier fanout carrier
userstenant_idForeign key to entity_node
projectstenant_id
taskstenant_idThree mandatory fields: grounded_in_feedback[], justification, verification
audit_eventstenant_idHash-chained per tenant; tamper-detection via merkle walk
ai_usage_eventstenant_idPer-LLM-call telemetry; source of truth for billing
tenant_toolstenant_idTools this tenant may invoke; server-side enforced

Layer read/write endpoints

All endpoints are prefixed /api/v1/. Unprefixed paths (/openapi.json, /auth/service-token) are bootstrap-only and MUST NOT be called from integration code.

LayerReadWrite
1 · Root doctrineGET /api/v1/governance/doctrinePlatform ratification only (out-of-band)
2 · Tenant memoryGET /api/v1/tenants/{tenant_id}/memoryPOST /api/v1/tenants/{tenant_id}/memory
2 · Tenant toolsGET /api/v1/tenants/{tenant_id}/toolsPOST /api/v1/tenants/{tenant_id}/tools:register
3 · User memoryGET /api/v1/users/{user_id}/memoryPOST /api/v1/users/{user_id}/memory
4 · Pearl memoryGET /api/v1/pearls/{pearl_id}/contextPOST /api/v1/pearls/{pearl_id}/observations
5 · Session shardsGET /api/v1/sessions/{session_id}/shardsPOST /api/v1/sessions/{session_id}/shards

Every write requires a delegation token in the Authorization: Bearer <token> header. Delegation tokens carry an act= claim naming the human delegator. Tokens expire in 15 minutes; refresh via POST /api/v1/auth/refresh.

Response shape for any layer read (abbreviated):

{ "layer": 2, "scope": { "tenant_id": "01H...", "shared_scope": "tenant:acme" }, "entries": [ { "id": "01H...", "slug": "policy-t2-code-tasks-use-qwen", "kind": "policy", "authored_at": "2026-09-27T12:34:56Z", "author_triple": {"user": "u_...", "tenant": "t_...", "session": "s_..."}, "body": { "...": "..." }, "references": ["doctrine:sovereignty_mode", "doctrine:t2_task_class"] } ], "reference_chain_status": "resolved" }

If any references[] entry cannot resolve at Layer 1, the response returns reference_chain_status: "broken" and enumerates the missing references. Writes with broken references return 422.

MCP consultation contract

Every MCP tool invocation consults the layer stack at call time. Contract:

  1. Load Layer 1 (governance) — read from /api/v1/governance/doctrine, cached per session with 60-second TTL.
  2. Load Layer 2 (tenant) — read from /api/v1/tenants/{tenant_id}/memory scoped to the caller’s tenant.
  3. Load Layer 3 (user), Layer 4 (agent), Layer 5 (session) as applicable to the caller.
  4. Apply the five-voice authority ranking (see below); higher voice wins on conflict.
  5. Execute the tool; emit an audit_events row with (user, tenant, session) attribution + tool name + input hash + output hash.

The five-voice authority ranking:

RankVoiceData source
1GovernanceLayer 1 doctrine
2Tenant adminLayer 2 tenant policy
3UserLayer 3 user memory (elevates above tenant-admin on personal-data sovereignty)
4PearlLayer 4 agent policy
5SessionLayer 5 session shard

MCP tools that read the Cradle

Grouped by consumption surface. Full contracts are auto-generated from openapi.json (API reference page pending).

Task and project surface: create_task, get_task, update_task_status, update_task_project, list_tasks, create_project, get_project, list_projects, assign_project_layers.

Department and Pearl surface: list_departments, describe_pearl, query_pearl, compare_departments, get_active_signals, acknowledge_signal, get_predictions.

Audit surface: audit_event_list, audit_event_get, audit_event_hash_chain_verify.

Tenant-tool surface: register_tenant_tool, list_tenant_tools, update_tenant_tool_visibility, unregister_tenant_tool.

Introspection surface: list_available_tools, whoami, get_context.

Friction and improvement surface: nebos_friction_capture, nebos_substrate_improvement_task_create.

Every write-tier tool call requires a delegation token; server-side HITL gates fire on acknowledge_signal regardless of client claims.

Attribution triple

Every tool call made through the Nebbos MCP writes an audit record. actor_id is who acted and delegated_by is the person an agent acted for; the session, tool, redacted parameters and outcome are in the record’s payload:

{ "id": "0d6c5e1a-...", "event_type": "agent.tool_call", "actor_type": "agent", "actor_id": "...", "delegated_by": "...", "occurred_at": "2026-11-09T12:34:56Z", "hash": "9f2c...", "previous_hash": "41ab..." }

Check the chain: the platform walks each client’s whole chain daily; read the newest result with the get_audit_chain_status MCP tool or GET /api/v1/security/audit-chain. A broken result names the first broken link and its reason; investigate that range before trusting downstream reports. See The audit chain.

Shared surfaces render attribution at entity level (“Nebbos”, “platform operator”, “tenant admin”). Personal-identity resolution requires capability_link grants (access-control detail page pending).

The improvement loop

The Cradle grows through this loop:

Programmatic entry points:

  • File a friction row: POST /api/v1/friction — body { "kind": "...", "context": "...", "suggested_fix": "..." } → returns { "friction_id": "..." }.
  • Convert friction to substrate improvement task: POST /api/v1/tasks/from-friction/{friction_id}.
  • Query outstanding friction: GET /api/v1/friction?status=open&limit=50.

Failure modes

FailureHTTPError codeRecovery
Layer 1 unreachable503governance_unreachableRetry with exponential backoff; consult /status for platform state
Reference chain broken422reference_chain_brokenExtend Layer 1 before landing the higher-layer write
Cross-tenant read without capability_link403capability_link_missingRe-establish grant via POST /api/v1/capability-links
Audit chain gap500audit_chain_gapDo not trust downstream reports; open POST /api/v1/audit/investigate
Delegation token expired401token_expiredRefresh via POST /api/v1/auth/refresh
Tenant-tool not registered403tenant_tool_not_registeredTenant admin registers via register_tenant_tool
RLS bypass attempted without GUC403rls_deniedApplication code must not set bypass_all; use scoped queries

Portability and export

Every tenant’s Cradle can be exported end-to-end:

# Full export — includes Layer 2-5 for this tenant + Layer 1 as-of-timestamp curl -X POST https://api.nebbos.ai/api/v1/tenants/{tenant_id}/export \ -H "Authorization: Bearer $NEBBOS_TOKEN" \ -d '{"format": "jsonl", "include": ["memory", "tools", "audit", "tasks"]}'

Response: {"export_id": "...", "download_url": "..."} (URL valid for 24h). The export is a signed archive; verify against download_url + ".sig".

Re-import into another Nebbos deployment: POST /api/v1/tenants/{tenant_id}/import with the same archive. Layer 1 identity is checked; if the target deployment’s Layer 1 diverges, imported references that no longer resolve are flagged in the import response.

Reading paths