@celestea/core 2.7.1

package/contracts/data-files/prompts.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "prompts.json + <CELESTEA_HOME>/workspaces/<ws>/prompts.json (section registry)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): src/prompts.rs:126-165",
+    "doc": "docs/data-files.md §3"
+  },
+  "path": {
+    "global": "<cwd>/prompts.json (CELESTEA_PROMPTS_FILE)",
+    "workspace": "<CELESTEA_HOME>/workspaces/<ws>/prompts.json (W880; legacy <workspace path>/.celestea/prompts.json and <workspace path>/.celestea-prompts.json readable)",
+    "mode": "0644 (no key)"
+  },
+  "notes": [
+    "New file, no migration. Missing/unreadable -> default empty; MALFORMED -> warn + default empty (the registry must never break compose/UI).",
+    "Persist: pretty JSON + .json.tmp + rename (no fsync, no 0600).",
+    "Four levels: builtin (10 code constants, order 100..1000) -> global.sections -> ws.sections -> bound prompt's section_overrides.",
+    "Existing sections keep their original order and only swap the template; new sections get ORDER_FALLBACK=2000; sort by (order,id); empty/whitespace templates dropped; join with '\\n\\n'; truncate to PROMPT_MAX_LEN=8192 bytes on a char boundary.",
+    "resolve_prompt: session-bound id (ws then global) -> if not found return None (NO default fallback); else ws.default_prompt -> global.default_prompt -> None.",
+    "is_default does NOT participate in the resolution chain; only default_prompt decides."
+  ],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "sections": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "id",
+            "name",
+            "template",
+            "order"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "template": {
+              "type": "string"
+            },
+            "order": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "prompts": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "id",
+            "name"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9._-]{1,128}$"
+            },
+            "name": {
+              "type": "string"
+            },
+            "section_overrides": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "default": {}
+            },
+            "is_default": {
+              "type": "boolean",
+              "default": false
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "default_prompt": {
+        "type": [
+          "string",
+          "null"
+        ],
+        "default": null
+      }
+    },
+    "additionalProperties": true
+  },
+  "validation": {
+    "promptId": "1-128 chars of [A-Za-z0-9._-]",
+    "template": [
+      "<=8192 bytes",
+      "every '{{' must close",
+      "variables must be in the whitelist"
+    ],
+    "templateErrors": [
+      "template exceeds the 8192 byte cap ({n} bytes)",
+      "undefined prompt variable '{{name}}'",
+      "unclosed '{{' in template"
+    ]
+  },
+  "interpolation": {
+    "syntax": "{{name}} (name trimmed; no aliases, no escaping)",
+    "vars": [
+      "model",
+      "provider",
+      "base_url",
+      "workspace",
+      "session",
+      "tools",
+      "context_window",
+      "max_output_tokens",
+      "date"
+    ]
+  },
+  "writeOrder": [
+    "409 check (no write)",
+    "persist",
+    "compose_and_swap",
+    "on compose failure write the old file back"
+  ],
+  "memoryOverride": {
+    "slot": "USER_OVERRIDE via POST /api/config system_prompt",
+    "rule": "non-empty = fully bypass registry assembly; empty = clear and fall back to default_system_prompt(); assembled prompts are NEVER treated as an override"
+  },
+  "generatedAt": "2026-09-10T01:20:00Z"
+}

package/contracts/data-files/providers.schema.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "providers.json (+ public_view)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): src/providers.rs:52-86 (Provider/ProviderModel), 219-241 (public_view)",
+    "doc": "docs/data-files.md §2"
+  },
+  "path": {
+    "default": "<cwd>/providers.json",
+    "envOverride": "CELESTEA_PROVIDERS_FILE",
+    "mode": "0600 (plaintext api_key)"
+  },
+  "notes": [
+    "NO version field and NO migration logic. id/name/base_url/request_format have no serde(default): a missing field is a deserialization failure.",
+    "ProviderModel deliberately does NOT derive Debug so a key can never be printed.",
+    "open(): missing file -> empty store; malformed JSON -> HARD error (never overwrite an unreadable file with an empty store).",
+    "save(): pretty JSON -> .tmp -> OpenOptions mode 0600 -> write_all + sync_all -> rename. Every save resets 0600.",
+    "W804 (multimodal P0 section 7): models[].input_modalities / output_modalities are ADDITIVE optional fields (additionalProperties is already true). Missing = the optimistic default input [\"text\",\"image\"], output [\"text\"]; publicView exposes both so the frontend can disable the image entry only for a model EXPLICITLY configured without \"image\"."
+  ],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "providers": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "id",
+            "name",
+            "base_url",
+            "request_format"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "identity; same id = overwrite"
+            },
+            "name": {
+              "type": "string",
+              "description": "display name only"
+            },
+            "note": {
+              "type": "string",
+              "default": ""
+            },
+            "base_url": {
+              "type": "string"
+            },
+            "request_format": {
+              "type": "string",
+              "enum": [
+                "chat_completions",
+                "responses",
+                "anthropic_messages"
+              ]
+            },
+            "api_key": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "PLAINTEXT secret; only this file may contain it"
+            },
+            "models": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "id",
+                  "name"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "reasoning_efforts": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "default": [],
+                    "description": "free strings, no enum validation"
+                  },
+                  "context_window": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ]
+                  },
+                  "max_output_tokens": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ]
+                  },
+                  "input_modalities": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "default": [
+                      "text",
+                      "image"
+                    ],
+                    "description": "W804 OPTIMISTIC DEFAULT: absent = [\"text\",\"image\"]. A model is assumed vision-capable; configuring [\"text\"] is the ONLY way to disable the image entry points. The code never hard-codes a capability."
+                  },
+                  "output_modalities": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "default": [
+                      "text"
+                    ],
+                    "description": "W804 default: [\"text\"]. Models do not return images over chat-completions in P0."
+                  }
+                },
+                "additionalProperties": true
+              }
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "default_model": {
+        "type": [
+          "string",
+          "null"
+        ],
+        "default": null
+      }
+    },
+    "required": [
+      "providers"
+    ],
+    "additionalProperties": true
+  },
+  "publicView": {
+    "note": "The api_key KEY IS ABSENT from every response (not null/empty). Tests assert the response text contains neither the key nor the string \"api_key\".",
+    "fields": [
+      "id",
+      "name",
+      "note",
+      "base_url",
+      "request_format",
+      "models[].id",
+      "models[].name",
+      "models[].reasoning_efforts",
+      "models[].context_window",
+      "models[].max_output_tokens",
+      "models[].input_modalities",
+      "models[].output_modalities",
+      "is_default",
+      "has_key"
+    ],
+    "is_default": "default_model matches any of the provider's model ids (every provider listing that id gets true)",
+    "has_key": "api_key exists and is a non-empty string (UNtrimmed)",
+    "excluded": [
+      "api_key"
+    ]
+  },
+  "updateSemantics": {
+    "api_key": "absent/null/blank = KEEP the stored key (the only keep-on-default field)",
+    "models": "absent = CLEAR to []",
+    "note": "absent = CLEAR to \"\"",
+    "request_format": "absent = reset to chat_completions (silently reverts a stored anthropic_messages)",
+    "name": "absent = fall back to id"
+  },
+  "keylessBorrow": {
+    "rule": "provider has no key AND normalized base_url (trim + strip trailing '/') equals the CURRENT generation's base_url -> borrow the engine's own key for that request only (never persisted, never echoed, never logged)",
+    "codeRef": "src/providers.rs:523-553"
+  },
+  "generatedAt": "2026-09-10T01:20:00Z"
+}

package/contracts/data-files/registry-tsv.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "/tmp/celestea-workers-registry.tsv (worker registry)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): /src/celestea_harness/crates/workers/src/types.rs:50-97, registry.rs:158-230",
+    "doc": "docs/DEVELOPMENT.md §2.6"
+  },
+  "path": {
+    "default": "/tmp/celestea-workers-registry.tsv",
+    "studio": "<data dir>/worker-registry.tsv (env `CELESTEA_WORKER_REGISTRY`; an EMPTY value = in-memory only, `tsvPath: null`)",
+    "ownershipRule": "E §2.2.1: the studio and the DSH-side plugin (`celestea-studio-ts`'s own table vs `celes-worker-spawn`'s `workerBase/registry.tsv`) are TWO tables and MUST NEVER write each other's (R2-1, asserted by B6). Inside the studio's table, `host=` tells the rows of its sessions apart."
+  },
+  "format": {
+    "type": "tsv",
+    "columns": [
+      "wid",
+      "started_at",
+      "status",
+      "extra"
+    ],
+    "separator": "\\t",
+    "lineTerminator": "\\n",
+    "trailingNewline": true,
+    "parse": "split('\\t'); wid/started_at trimmed; empty wid or started_at -> row skipped; unknown status -> row skipped (bad rows never crash)",
+    "statusValues": [
+      "RUNNING",
+      "DONE",
+      "FAILED"
+    ],
+    "extra": "free text; k=v tokens separated by whitespace (extra itself may contain spaces). state=<in-turn|idle> marks a RUNNING row's phase. report_to=<target> drives receipt wakeup. proc=<pid> marks the writing process (W234 row ownership).",
+    "atomicWrite": "tmp file in the same dir (<name>.tmp-<pid>-<seq>) then rename over the target",
+    "viewRule": "summarize() only counts rows written by THIS registry: `proc=<pid>` (W234) and, when the registry declares a host conversation, `host=<sid>` (W787). A row with NO `host=` token is kept when `proc` matches (a legacy / directly-upserted row). Stale cross-process rows are invisible to by_status/by_state/workers and are not matched by a wid filter",
+    "writeRule": "W787: one table carries the rows of EVERY studio session, so a write MERGES with the rows other session registries already wrote (`mergeTableRows`) before the atomic tmp+rename — writing the in-memory view alone would delete a sibling session's worker"
+  },
+  "extraTokens": {
+    "note": "W787 (E §2.2.2): the token vocabulary, appended WITHOUT changing the column count — an older parser only sees a longer `extra`, which is what makes the change backward compatible (B7 round-trip).",
+    "known": [
+      "sess=<session id>",
+      "title=<short title, whitespace folded to `-`>",
+      "driven=<yes|no>",
+      "workspace=<name>",
+      "provider=<id>",
+      "model=<id>",
+      "effort=<level>",
+      "report_to=<session id>",
+      "mode=<standard|execution>",
+      "brief=<folded brief, <=300 chars>",
+      "retries=<n>",
+      "fail=<reason>",
+      "ended_at=<utc stamp>",
+      "proc=<pid>",
+      "state=<in-turn|idle>",
+      "host=<session id>",
+      "attempt=<n>",
+      "lease=<pid>@<unix>",
+      "receipt=<wid>:<attempt>"
+    ],
+    "whitelist": ["host", "attempt", "lease", "receipt"],
+    "added": {
+      "host": "the HOST conversation that dispatched the worker (E §2.2.2, closes G2-6); it is also the per-session ownership discriminator now that one process shares ONE table",
+      "attempt": "which try this row is: the FIRST spawn is 0 and a re-dispatch adds one (§5.2, the cross-capability convention that the usage ledger and the model fallback already use; §2.2.2's local `first = 1` wording is superseded by the ruling). It names the report file (`results/<wid>-<short>-a<attempt>.md`) and keys the receipt (`receipt:<wid>:<attempt>`); a row with no token at all is a pre-W787 first try, i.e. 0",
+      "lease": "`<pid>@<unix>` of the owning process and when it last touched the row; renewed on every driver state change. Absent (a legacy row) falls back to `proc=`",
+      "receipt": "the idempotency key `<wid>:<attempt>` of the receipt this row already DELIVERED — a second closeLoop for the same attempt is a no-op (E §2.2.3)"
+    },
+    "roundTrip": "tests/contracts.test.ts round-trips a row carrying ALL four new tokens through serializeRegistryTsv -> parseRegistryTsv byte-for-byte (B7)"
+  },
+  "columns": {
+    "wid": "worker id (e.g. W101)",
+    "started_at": "UTC timestamp (e.g. 2026-09-06_17:54:53Z)",
+    "status": "RUNNING|DONE|FAILED",
+    "extra": "key=value tokens"
+  },
+  "generatedAt": "2026-09-10T01:20:00Z"
+}

package/contracts/data-files/session.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "<session-dir>/session.json (Studio session metadata)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): src/workspaces.rs:1001-1014, 1206-1218",
+    "doc": "docs/data-files.md §1.5"
+  },
+  "path": {
+    "default": "<session-dir>/session.json (optional; canonical <CELESTEA_HOME>/workspaces/<ws>/sessions/<session-dir>/, legacy <workspace path>/<session-dir>/ and <workspace path>/.celestea/sessions/<session-dir>/ readable)"
+  },
+  "notes": [
+    "The engine NEVER reads this file; cli-main.jsonl is the conversation history.",
+    "Writers: POST /api/sessions (always, from W779: `title` is mandatory at creation), /rename (updates `title` in place) and /branch (writes the new session's own `title` over the inherited keys). Nothing is written when every field is empty (pre-W779 sessions with no model/prompt/mode).",
+    "Written with a plain std::fs::write (NOT atomic, no fsync).",
+    "Missing/corrupt -> None (tolerated).",
+    "W779: `rename` moves the directory AND rewrites `title` (the directory name is the sanitized title, so the file is the only place the original survives); `branch` copies model/prompt/mode and writes its own `title` (default `<parent display name>-分支`) instead of copying the file verbatim; the whole directory still follows a rename.",
+    "W779: `title` is the ORIGINAL, un-sanitized session title (CJK, spaces preserved) — the display name the GUI shows. Absent -> the caller falls back to the directory name with its `-<secs>.<nanos>[-N]` creation suffix stripped (`stripCreationSuffix`); the directory name itself is unchanged (it stays sanitized + timestamped for uniqueness).",
+    "W779: a non-string `title` is ignored on read (like an unknown `mode`); an empty `title` is never written.",
+    "POST /api/config does NOT write it back: the session-level model is decided at creation time.",
+    "W729: `mode` (standard|execution) is fixed at creation; DEFAULT = standard and it is NOT written (a session without the key behaves exactly as before).",
+    "W729: an unknown `mode` value is ignored on read (behaves like a missing key); POST /api/sessions rejects it with 400 `invalid mode: <v>` before anything is created.",
+    "additionalProperties: true is kept: a hand-written unknown key never breaks a session."
+  ],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "model": {
+        "type": "string",
+        "description": "model id override; invalid value -> 400 invalid session model: {e} on activate"
+      },
+      "prompt": {
+        "type": "string",
+        "description": "bound prompt id (section_overrides of that prompt are applied last)"
+      },
+      "mode": {
+        "type": "string",
+        "enum": [
+          "standard",
+          "execution"
+        ],
+        "description": "session working mode (W729): standard = call tools directly; execution = prefer one run_code program per dependent sequence. Absent = standard; the default is never written."
+      },
+      "title": {
+        "type": "string",
+        "description": "W779: display name of the session, verbatim as created/renamed (NOT sanitized, may contain CJK/spaces). Absent -> the GUI strips the creation suffix from the directory name."
+      }
+    },
+    "additionalProperties": true
+  },
+  "generatedAt": "2026-09-10T01:20:00Z"
+}

package/contracts/data-files/usage-ledger.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "usage-ledger.jsonl (append-only cost & usage ledger, one JSON object per line)",
+  "source": {
+    "design": "/src/celestea_studio-ts/docs/iteration-e-capabilities.md §3.2.1/§3.2.3 (W728 P0)",
+    "code": "packages/runtime/src/ledger.ts, packages/runtime/src/ledger-llm.ts"
+  },
+  "path": {
+    "default": "<data dir>/usage-ledger.jsonl (<data dir> = dirname(workspacesFile))",
+    "envOverride": "CELESTEA_USAGE_LEDGER_FILE",
+    "disableSwitch": "CELESTEA_USAGE_LEDGER=off|0|false|no",
+    "mode": "0600"
+  },
+  "format": {
+    "type": "jsonl",
+    "lineTerminator": "\n",
+    "appendOnly": true,
+    "rewrite": "never: a line is appended once and never edited, reordered or compacted (rotation would be a P1 concern and is NOT implemented)",
+    "write": "one writeSync per record on an O_APPEND descriptor, so two processes cannot interleave a line",
+    "idempotencyKey": "(session, turn_id, step, attempt) — a key already booked is skipped, not rewritten",
+    "grain": "one row per model STEP (kind ok|error) plus one turn_total row per turn",
+    "noBodyRule": "a row never contains prompt/message text, tool arguments or credentials; only counters, ids, names and prices"
+  },
+  "kinds": {
+    "ok": "a response arrived; usage is the provider's own counters (or null when the provider sent no usage frame, then billed_unknown=true)",
+    "error": "the step failed (non-2xx / timeout / torn stream); usage carries the counters observed before the failure, or null",
+    "turn_total": "the summary row of one turn: Σ of its step rows (token equality with the details is an assertion, §3.4 C2)"
+  },
+  "schema": {
+    "$defs": {
+      "usage": {
+        "type": ["object", "null"],
+        "required": ["prompt_tokens", "completion_tokens", "total_tokens"],
+        "properties": {
+          "prompt_tokens": { "type": "integer", "minimum": 0 },
+          "completion_tokens": { "type": "integer", "minimum": 0 },
+          "total_tokens": { "type": "integer", "minimum": 0 },
+          "cache_read": { "type": "integer", "minimum": 0 },
+          "reasoning_tokens": { "type": "integer", "minimum": 0 }
+        },
+        "additionalProperties": true
+      },
+      "cost": {
+        "type": ["object", "null"],
+        "required": ["in", "out", "cache", "total"],
+        "properties": {
+          "in": { "type": "number", "description": "cost of the UNCACHED input only: max(0, prompt_tokens - cache_read) x the `in` price. prompt_tokens already contains the cache-hit region, so this is NOT prompt_tokens x `in`" },
+          "out": { "type": "number", "description": "completion_tokens x the `out` price" },
+          "cache": { "type": "number", "description": "cache_read x the `cache_read` price; the hit region is charged HERE only, never also at the `in` price" },
+          "total": { "type": "number", "description": "in + out + cache (each component rounded to 6 decimals)" }
+        },
+        "additionalProperties": false
+      },
+      "price": {
+        "type": ["object", "null"],
+        "required": ["version", "currency", "unit", "in", "out", "cache_read"],
+        "description": "the snapshot THIS row was priced with (a frozen copy, not a reference)"
+      },
+      "step": {
+        "type": "object",
+        "required": ["v", "ts", "kind", "session", "turn", "turn_id", "step", "attempt", "usage", "billed_unknown", "priced_by"],
+        "properties": {
+          "v": { "const": 1 },
+          "ts": { "type": "integer", "description": "unix seconds" },
+          "kind": { "enum": ["ok", "error"] },
+          "session": { "type": "string", "description": "\"<workspace>/<session>\" (data-file self-description)" },
+          "turn": { "type": ["integer", "null"], "description": "turn number parsed from turn_id; null = a call outside a driven turn (worker/summarizer)" },
+          "turn_id": { "type": ["string", "null"] },
+          "step": { "type": "integer", "minimum": 1, "description": "1-based step index within the turn; (turn, step) is strictly increasing" },
+          "attempt": { "type": "integer", "minimum": 0, "description": "0 = first attempt; retries/fallbacks increment (§5.2). P0 writes 0" },
+          "provider": { "type": ["string", "null"], "description": "providers.json row id of the target" },
+          "model": { "type": ["string", "null"] },
+          "base_url_host": { "type": ["string", "null"] },
+          "usage": { "$ref": "#/schema/$defs/usage" },
+          "billed_unknown": { "type": "boolean", "description": "true = no usage frame arrived: the cost is UNKNOWN, never 0" },
+          "error_kind": { "enum": ["generate", "stream", "timeout", null] },
+          "http_status": { "type": ["integer", "null"], "description": "W723 LlmError.httpStatus (null = no response arrived)" },
+          "retryable": { "type": ["boolean", "null"], "description": "W723 LlmError.retryable; null = not structurally known (mid-stream)" },
+          "price": { "$ref": "#/schema/$defs/price" },
+          "cost": { "$ref": "#/schema/$defs/cost", "description": "null when unpriced or unbilled — NOT a zero" },
+          "priced_by": { "enum": ["table", "record", "unpriced"] },
+          "fallback_from": { "type": ["string", "null"], "description": "target name this attempt fell over from (capability 4, P1)" }
+        },
+        "additionalProperties": false
+      },
+      "turn_total": {
+        "type": "object",
+        "required": ["v", "ts", "kind", "session", "turn", "turn_id", "steps", "attempts", "usage", "cost_complete", "priced_by", "unpriced_models", "billed_unknown_steps", "outcome"],
+        "properties": {
+          "v": { "const": 1 },
+          "ts": { "type": "integer" },
+          "kind": { "const": "turn_total" },
+          "session": { "type": "string" },
+          "turn": { "type": ["integer", "null"] },
+          "turn_id": { "type": ["string", "null"] },
+          "steps": { "type": "integer", "minimum": 1, "description": "step rows contributing to this turn" },
+          "attempts": { "type": "integer", "minimum": 1, "description": "Σ(attempt+1) over those rows" },
+          "usage": { "$ref": "#/schema/$defs/usage", "description": "Σ of the contributing rows' usage (token equality asserted)" },
+          "cost": { "$ref": "#/schema/$defs/cost", "description": "Σ over the PRICED rows; see cost_complete" },
+          "cost_complete": { "type": "boolean", "description": "false = at least one row was unpriced or unbilled, so total is a floor, not the whole cost" },
+          "priced_by": { "enum": ["table", "record", "unpriced"] },
+          "unpriced_models": { "type": "array", "items": { "type": "string" } },
+          "billed_unknown_steps": { "type": "integer", "minimum": 0 },
+          "outcome": { "enum": ["completed", "cancelled", "step_limit", "interrupted", "error"], "description": "the turn's terminal state (the log's own turn_end outcome)" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "oneOf": [{ "$ref": "#/schema/$defs/step" }, { "$ref": "#/schema/$defs/turn_total" }]
+  },
+  "generatedAt": "2026-09-11T00:00:00Z"
+}

package/contracts/data-files/workspaces.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "workspaces.json (v2)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): src/workspaces.rs:122-140 (RegistryData)",
+    "doc": "docs/data-files.md §1"
+  },
+  "path": {
+    "default": "<cwd>/workspaces.json",
+    "envOverride": "CELESTEA_WORKSPACES_FILE",
+    "mode": "0644 (no key)"
+  },
+  "notes": [
+    "NO version field. \"v2\" is a naming convention only: the workspace key is the registered path's folder basename and is NEVER stored.",
+    "Unknown fields are tolerated (no deny_unknown_fields).",
+    "There is no archive-state field: archiving is a pure filesystem move into the canonical <CELESTEA_HOME>/workspaces/<ws>/archive/ (W880; legacy .celestea-archived/ and .celestea/archive/ readable), and the default scanner skips dot-dirs.",
+    "Write: to_string_pretty -> <path>.json.tmp -> rename (atomic, NO fsync)."
+  ],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "workspaces": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "path"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "absolute registered directory"
+            }
+          },
+          "additionalProperties": true
+        },
+        "default": []
+      },
+      "active_session": {
+        "type": [
+          "string",
+          "null"
+        ],
+        "description": "\"<workspace-basename>/<session-dir>\"; null when unset",
+        "default": null
+      }
+    },
+    "required": [],
+    "additionalProperties": true
+  },
+  "legacyV1": {
+    "name": "tolerated on load, used for the name->basename mapping, never written back"
+  },
+  "hardErrors": {
+    "malformed": "workspaces.json '<path>' is malformed: {e} (startup exits 1; the unreadable registry is never overwritten)",
+    "duplicateBasename": "two workspaces resolve to the same folder name '{base}' (workspace keys must be unique basenames; rename one folder)"
+  },
+  "sessionId": {
+    "shape": "<workspace-basename>/<session-dir>",
+    "rules": "exactly one '/', both sides non-empty, session segment has no '/' and is sanitized (separators/control/whitespace -> '_', CJK preserved); empty/'.'/'..'/leading-dot rejected; dir.parent() is one of the live-session roots (canonical <CELESTEA_HOME>/workspaces/<ws>/sessions, slice-A <ws>/.celestea/sessions, or the workspace path)"
+  },
+  "generatedAt": "2026-09-10T01:20:00Z"
+}