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
| Layer | Contents | Read scope | Write authority | Retention |
|---|---|---|---|---|
| 1 · Root doctrine | Ratified doctrine, Constitution articles, governance corpus | All tenants (identical) | Platform ratification only | Immutable except by superseding article |
| 2 · Tenant | Tenant memory, tool registry, tenant policy | Tenant-scoped (RLS) | Tenant admin + delegated tokens | Tenant-configurable |
| 3 · User | User memory, per-user preferences, signature emoji | User-scoped (RLS) | User + tenant-admin under sovereignty rules | User-configurable |
| 4 · Agent | Pearl per-department memory, skill catalog, per-invocation state | Department-scoped | Agent + tenant-admin | Tenant retention policy |
| 5 · Session | Session shards, turn-scoped state, ephemeral wave frames | Session-scoped | Session actor | TTL, 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:
| Table | Scope column | Notes |
|---|---|---|
tenants | id | Public read for provisioning; write restricted to platform |
entity_node | tenant_id, shared_scope | The 3-tier fanout carrier |
users | tenant_id | Foreign key to entity_node |
projects | tenant_id | |
tasks | tenant_id | Three mandatory fields: grounded_in_feedback[], justification, verification |
audit_events | tenant_id | Hash-chained per tenant; tamper-detection via merkle walk |
ai_usage_events | tenant_id | Per-LLM-call telemetry; source of truth for billing |
tenant_tools | tenant_id | Tools 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.
| Layer | Read | Write |
|---|---|---|
| 1 · Root doctrine | GET /api/v1/governance/doctrine | Platform ratification only (out-of-band) |
| 2 · Tenant memory | GET /api/v1/tenants/{tenant_id}/memory | POST /api/v1/tenants/{tenant_id}/memory |
| 2 · Tenant tools | GET /api/v1/tenants/{tenant_id}/tools | POST /api/v1/tenants/{tenant_id}/tools:register |
| 3 · User memory | GET /api/v1/users/{user_id}/memory | POST /api/v1/users/{user_id}/memory |
| 4 · Pearl memory | GET /api/v1/pearls/{pearl_id}/context | POST /api/v1/pearls/{pearl_id}/observations |
| 5 · Session shards | GET /api/v1/sessions/{session_id}/shards | POST /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:
- Load Layer 1 (governance) — read from
/api/v1/governance/doctrine, cached per session with 60-second TTL. - Load Layer 2 (tenant) — read from
/api/v1/tenants/{tenant_id}/memoryscoped to the caller’s tenant. - Load Layer 3 (user), Layer 4 (agent), Layer 5 (session) as applicable to the caller.
- Apply the five-voice authority ranking (see below); higher voice wins on conflict.
- Execute the tool; emit an
audit_eventsrow with(user, tenant, session)attribution + tool name + input hash + output hash.
The five-voice authority ranking:
| Rank | Voice | Data source |
|---|---|---|
| 1 | Governance | Layer 1 doctrine |
| 2 | Tenant admin | Layer 2 tenant policy |
| 3 | User | Layer 3 user memory (elevates above tenant-admin on personal-data sovereignty) |
| 4 | Pearl | Layer 4 agent policy |
| 5 | Session | Layer 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
| Failure | HTTP | Error code | Recovery |
|---|---|---|---|
| Layer 1 unreachable | 503 | governance_unreachable | Retry with exponential backoff; consult /status for platform state |
| Reference chain broken | 422 | reference_chain_broken | Extend Layer 1 before landing the higher-layer write |
| Cross-tenant read without capability_link | 403 | capability_link_missing | Re-establish grant via POST /api/v1/capability-links |
| Audit chain gap | 500 | audit_chain_gap | Do not trust downstream reports; open POST /api/v1/audit/investigate |
| Delegation token expired | 401 | token_expired | Refresh via POST /api/v1/auth/refresh |
| Tenant-tool not registered | 403 | tenant_tool_not_registered | Tenant admin registers via register_tenant_tool |
| RLS bypass attempted without GUC | 403 | rls_denied | Application 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
- Architecture overview — where the Cradle sits in the stack
- Security model — RLS boundaries, delegation semantics, capability_link grants
- LLM routing architecture — how the router consults the Cradle at call time
- Data model reference — schema
- Row-level isolation — RLS three-statement pattern in depth
- Audit chain — hash-chain verification + tamper detection
- API reference — full endpoint contracts (auto-generated page pending)