--- name: internal/storage-tiers kind: knowledge description: Where crouter state belongs when-and-why-to-read: When locating crtr state or deciding where a new file belongs, this reference should be read so files are found or placed in the storage tier with the right ownership and durability. short-form: The two crtr storage tiers — scope root for durable user/repo content and canvas home for node-graph runtime state, node artifacts, and human tickets. --- # Where everything lives (the two storage tiers) crtr state is split into two tiers with distinct ownership and durability. This is the routing contract; precise resolver behavior lives in `src/core/scope.ts` and `src/core/canvas/paths.ts`. ## 1. Scope root — durable user/repo content and prepared support material `~/.crouter/` (user scope) or `/.crouter/` (project scope), resolved by `src/core/scope.ts`. Durable content includes `memory/`, `prompts/`, `plugins/`, `marketplaces/`, `personas/`, and `config.json`; user-authored content belongs to the user scope and repo-authored content to the project scope. `prompts/.md` becomes `/` in every node, with nested paths becoming colon-namespaced commands and the nearest resolved scope winning. `~/.crouter/support//` is user-scope prepared local diagnostic material. A reference contains the prepared support bundle and manifest for explicit handling; it is not `memory/`, project memory, a node context artifact, or a project-scoped support store. Preparation is local and zero-egress; submission is an explicit operation to its verified destination. Invocation, output, and artifact details belong on the relevant command leaf `-h` surfaces. User-wide content with no cwd dimension also belongs here: `~/.crouter/profile-defaults.json` maps realpath'd directories to their selected profile, and `~/.crouter/prompt-reviews/` holds prompt-review exports. ## 2. Canvas home — node-graph runtime state, node artifacts, and bounded diagnostics `~/.crouter/canvas/` (overridable with `CRTR_HOME`) is the cwd-agnostic node-graph home. `canvas.db` is the SQLite WAL topology store for nodes and edges, including durable tmux-pane focus. `nodes//` owns `meta.json`, `context/`, `mode/`, `reports/`, `messages/`, `inbox.jsonl`, `transcript.jsonl`, `session.ptr`, and `job/` state. Humanloop ticket files (`deck.json`, `run.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live directly in a terminal human bridge node directory; the one registered inbox root is `nodes/`. Mode-switch specifications and plans are ordinary node-context artifacts. They share the node's lifetime and are removed when that node is reaped. ### Canonical event streams Canonical diagnostics are bounded NDJSON `EventEnvelope` streams. The synchronous rotating writer retains one active file plus `.1` and `.2` generations at 5 MiB each, and each complete record is bounded to 64 KiB including its newline. Each long-lived daemon, broker, or web process binds one fixed source and writes only that source's file; no caller selects an arbitrary destination. - `nodes//job/log.jsonl` is the node broker's canonical event stream. A broker-bound event carries that node identity; daemon events about a node stay in the daemon stream instead. - `/crtrd.log` is the root daemon's canonical event stream. It contains daemon-owned events, including node-scoped data carried as `node_id` fields. - `/web..log.jsonl` is the canonical stream for one web host/port. `stream_id` is deterministic: the first 16 lowercase hexadecimal characters of SHA-256 over normalized lowercase host (IPv6 brackets removed and wildcard aliases mapped to `localhost`), a NUL, and the decimal port. ### Current state and raw residue `nodes//job/fault` is mutable current fault state, not event history. `nodes//job/telemetry.json` is current node telemetry, not a log; both remain runtime state under the canvas home and are read as state rather than merged into canonical history. `/crtrd.err` and `nodes//job/broker.log` are raw process/stdout-stderr residue for runtime warnings, third-party output, and last-resort evidence when canonical emission cannot complete. They are not canonical streams, are not parsed as event envelopes, and do not become JSON event output. The contributor rule: durable user or repo content → scope root; node-graph state, node-authored deliverables, human tickets, current state, canonical streams, and raw residue → canvas home. Runtime install generations under `~/.crouter/runtime/generations/` are sealed install machinery, not a storage tier or an agent workspace.