@celestea/core 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @celestea/core
+
+The semantic kernel of the TypeScript rewrite: the frozen contract types, the
+model-visible message model, the serde-exact `SessionEvent` codec, and the
+plugin seams every other package is built on.
+
+Ports (1:1, field names are contract):
+
+| TS module | Legacy source |
+|---|---|
+| `message.ts` | `crates/core/src/message.rs` (Role / Content / ToolCall / Message / Usage) |
+| `stream.ts` | `crates/core/src/message.rs` + `llm.rs` (ModelRequest / StreamEvent / LlmError) |
+| `session-event.ts` | `crates/core/src/session_log.rs` (SessionEvent serde, TurnOutcome) |
+| `session-log.ts` | `crates/core/src/session_log.rs` (SessionLog trait) |
+| `plugin.ts` | `crates/core/src/plugin.rs` (+ `registry.rs` NamedRegistry) |
+| `context.ts` | `crates/core/src/context.rs` |
+| `event-bus.ts` | `crates/core/src/event_bus.rs` |
+| `llm.ts` | `crates/core/src/llm.rs` |
+| `tool.ts` | `crates/core/src/tool.rs` |
+| `agent.ts` | `crates/core/src/agent.rs` |
+| `types.ts` | P0 frozen contracts (SSE envelope, endpoints, providers, workers) |
+
+## Dependency rule
+
+**`core` imports nothing from the other packages.** It declares seams only; the
+concrete implementations live in sibling packages and are plugged in at compose
+time (`examples` below). Consumers import from the package root
+(`@celestea/core`) — never a deep path.
+
+## Public API (via `index.ts` only)
+
+- **Data model** — `Role`, `Content`, `ToolCall`, `Message` (+ `Message.user`,
+  `Message.assistantText`, `Message.assistantToolCall`, `Message.toolResult`),
+  helpers (`messageText`, `messageToolCalls`, `toolCallIds`, `hasToolCalls`),
+  `Usage` (`usageAdd`, `usageSum`, `usageIsEmpty`, `cacheHitRatio`),
+  `ToolSpec` / `ToolDecision` (in `types.ts`).
+- **SessionEvent** — the union in `types.ts`; `validateSessionEvent`,
+  `parseSessionEvent`, `serializeSessionEvent` (serde-exact: tag first,
+  declaration order, `parent_id` omitted when absent, `value`/`error`/`outcome`
+  always written), `effectiveOutcome`, `outcomePhase`, `outcomeError`.
+- **Seams** — `Plugin`, `Context`, `EventBus`, `SessionLog`, `Llm`, `Tool`,
+  `ToolGuard`, `ToolRegistry`, `AgentLoop`, plus the well-known service tokens
+  `SESSION_LOG_SERVICE`, `EVENT_BUS_SERVICE`, `LLM_SERVICE`,
+  `LLM_REGISTRY_SERVICE`, `TOOL_REGISTRY_SERVICE`, `TOOL_GUARD_SERVICE`,
+  `AGENT_LOOP_SERVICE`.
+- **JSON** — `serdeJsonString` (serde_json-compatible text: sorted object keys,
+  `None` → `null`), `firstJsonDiff`, `stableStringify`.
+- **SSE bus** — `createSseBus` / `SseBus` (SDK-side broadcast; renamed from the
+  P0 `EventBus` so `EventBus` now means the engine seam).
+
+## Extension points (everything is a plugin)
+
+```ts
+import { Context, mountPlugins, SESSION_LOG_SERVICE, definePlugin } from "@celestea/core";
+import { inMemorySessionLogPlugin } from "@celestea/session";
+
+const ctx = mountPlugins(Context.root(), [
+  definePlugin("my-events", (c) => c.provide(EVENT_BUS_SERVICE, createEventBus())),
+  inMemorySessionLogPlugin(),
+]);
+
+const log = ctx.require(SESSION_LOG_SERVICE);   // SessionLog seam, not a concrete class
+const scoped = ctx.scoped();                    // per-agent scope, falls back to the parent
+```
+
+Registration is append-only with **last-wins** semantics (`Context.provide`,
+`NamedRegistry`, `LlmRegistry`), so a test or a preset can shadow a service
+without touching the composition root. `EventBus` has three independent modes:
+`on`/`emit` (broadcast), `bail`/`runBail` (first non-`undefined` answer
+short-circuits) and `waterfall`/`runWaterfall` (transform chain).
+
+## File layout
+
+```
+src/types.ts         303  P0 frozen contracts (SessionEvent union, SSE, endpoints)
+src/session-event.ts 216  serde-exact SessionEvent codec + TurnOutcome helpers
+src/redact.ts        204  fixture/report secret redaction (P0)
+src/message.ts       188  Role / Content / ToolCall / Message / Usage
+src/contracts/       163  frozen contract-file loaders
+src/json.ts          132  JSON helpers + serde_json-compatible text
+src/sse-bus.ts       109  SDK-side SSE broadcast bus
+src/event-bus.ts     102  engine EventBus seam
+src/tool.ts           70  Tool / ToolGuard / ToolRegistry seams
+src/context.ts        66  Context service container
+src/plugin.ts         64  Plugin seam + NamedRegistry
+src/stream.ts         56  ModelRequest / StreamEvent / LlmError
+src/agent.ts          50  AgentLoop seam + AgentConfig
+src/llm.ts            43  Llm seam + LlmRegistry
+src/session-log.ts    34  SessionLog seam
+src/index.ts          46  the only public entry point
+```
+
+Every file stays well under 400 lines and every function under 80 lines
+(`createRedactor` in the pre-existing P0 `redact.ts` is the one 94-line
+exception — flagged for a later split, out of the P1 scope).

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

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "checkpoint.json (per-session crash / shutdown sidecar)",
+  "source": {
+    "design": "/src/celestea_studio-ts/docs/iteration-e-capabilities.md §1.2.2/§1.2.3 (E-P0③)",
+    "code": "packages/session/src/checkpoint.ts, packages/session/src/checkpoint-recovery.ts, packages/runtime/src/recovery.ts"
+  },
+  "path": {
+    "default": "<session dir>/checkpoint.json (<session dir> = <workspace>/<session>)",
+    "mode": "0600",
+    "write": "<path>.tmp-<pid> -> rename (atomic), pretty-printed JSON, trailing newline",
+    "writeTimings": "turn_start (one row appended), turn_end (one row appended), any lane change (P1: push / drain / restore), clean shutdown"
+  },
+  "purpose": {
+    "kept": "the two facts the log cannot express: WHO was running (pid/boot_id/clean_shutdown) and WHICH turn was open (open_turn)",
+    "notKept": "everything derivable from cli-main.jsonl (turn counter, history, last outcome) — the log stays the single source of truth (K4)",
+    "neverWritten": "the sidecar never rewrites a log row; the only repair is ONE appended turn_end{outcome:\"interrupted\"}, recorded in repaired[]"
+  },
+  "failureSemantics": {
+    "missing": "no checkpoint: recovery does not touch the log at all (a dangling turn_start may belong to another live process)",
+    "unparsable": "the WHOLE file is ignored + observed on stderr; behaviour is exactly 'missing' (never read as a clean exit)",
+    "unknownVersion": "ignored + observed (same as unparsable)",
+    "sessionMismatch": "ignored + observed: the sidecar was copied/renamed and cannot describe this directory",
+    "writeFailure": "reported on stderr and swallowed: checkpointing is observation and can never fail a turn"
+  },
+  "open_turn": {
+    "meaning": "the turn THIS process started and has not closed yet (null = no turn is open)",
+    "repairCondition": "open_turn.id has a turn_start row in cli-main.jsonl AND no turn_end row for that id (double signature)",
+    "idempotency": "the second boot sees the appended turn_end and only clears open_turn: the log is byte-identical (assertion A2)"
+  },
+  "clean_shutdown": {
+    "true": "the process left through Runtime.shutdown(); the next boot repairs NOTHING, whatever the log looks like",
+    "false": "written by every activity (turn_start, turn_end); a crash therefore leaves the last value false"
+  },
+  "schema": {
+    "type": "object",
+    "required": ["version", "session", "pid", "boot_id", "updated_at", "clean_shutdown", "open_turn", "last_outcome", "degraded", "lanes", "delivered_ids", "repaired"],
+    "properties": {
+      "version": { "const": 1, "description": "sidecar schema version (NOT a data-file format version; any other value voids the file)" },
+      "session": { "type": "string", "description": "\"<workspace>/<session>\" self-description; a mismatch voids the file" },
+      "pid": { "type": "integer", "description": "process that wrote the file" },
+      "boot_id": { "type": "string", "pattern": "^b-[0-9a-f]{8}$", "description": "one id per process start (process-wide constant)" },
+      "updated_at": { "type": "integer", "description": "unix seconds of the last write" },
+      "clean_shutdown": { "type": "boolean" },
+      "open_turn": {
+        "type": ["object", "null"],
+        "required": ["id", "started_at"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^turn-\\d+$" },
+          "started_at": { "type": "integer", "description": "unix seconds" }
+        },
+        "additionalProperties": false
+      },
+      "last_outcome": { "enum": ["completed", "cancelled", "error", "step_limit", "interrupted", null], "description": "redundant with the log (operator convenience); the log wins on any conflict" },
+      "degraded": {
+        "type": "object",
+        "required": ["log_write_errors"],
+        "properties": { "log_write_errors": { "type": "integer", "minimum": 0, "description": "PersistentSessionLog.writeErrorCount() sampled at every write; non-zero means disk and memory diverged" } },
+        "additionalProperties": false
+      },
+      "lanes": {
+        "type": "object",
+        "required": ["next_turn", "next_step"],
+        "description": "E §1.3 P1 ① (W787): the two injection lanes exactly as the inbox holds them — a message that was ACCEPTED and not yet injected. Written on every lane change (push / drain), so a crash loses at most the newest change (G1-4: a user's message used to vanish silently). Restoring is deliberately silent: a message queued by a dead process was already announced by it.",
+        "properties": {
+          "next_turn": { "type": "array", "items": { "$ref": "#/schema/$defs/lane_message" } },
+          "next_step": { "type": "array", "items": { "$ref": "#/schema/$defs/lane_message" } }
+        },
+        "additionalProperties": false
+      },
+      "delivered_ids": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "E §1.3 P1 ① (W787): the bounded (512, oldest-first) ledger of injection ids this session already ACCEPTED. It is the cross-process half of the idempotency key (capability 2's `receipt:<wid>:<attempt>`), so a receipt replayed after a restart is still dropped as a duplicate (B3)."
+      },
+      "repaired": {
+        "type": "array",
+        "description": "every log row THIS engine appended for recovery; empty on a healthy session (assertion A2: length stays 1 after a second boot)",
+        "items": {
+          "type": "object",
+          "required": ["at", "action", "turn_id"],
+          "properties": {
+            "at": { "type": "integer" },
+            "action": { "const": "synthesize_turn_end" },
+            "turn_id": { "type": "string", "pattern": "^turn-\\d+$" }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "additionalProperties": false
+  },
+  "$defs": {
+    "lane_message": {
+      "type": "object",
+      "required": ["text", "from", "at", "lane", "kind", "id", "source"],
+      "properties": {
+        "text": { "type": "string" },
+        "from": { "type": "string", "description": "attribution label (empty = the user)" },
+        "at": { "type": "integer" },
+        "lane": { "enum": ["next-turn", "next-step"] },
+        "kind": { "type": "string", "description": "InjectionKind (user / receipt / relay / stimulus)" },
+        "id": { "type": "string", "description": "idempotency key (empty = never deduplicated)" },
+        "source": { "type": "object", "description": "the delivery envelope (kind / form / sender), verbatim" },
+        "duplicate": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "generatedAt": "2026-09-11T00:00:00Z"
+}

package/contracts/data-files/cli-main-jsonl-precompact.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "<session-dir>/cli-main.jsonl.precompact (single-copy backup)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): src/compact.rs (rewrite_atomic)",
+    "doc": "docs/data-files.md §4.4"
+  },
+  "notes": [
+    "Single copy, OVERWRITTEN on every /compact. The only manual rollback channel.",
+    "Byte format is identical to cli-main.jsonl (JSONL of SessionEvent).",
+    "Not written unless a compaction actually happens (needs >=9 complete turns)."
+  ],
+  "format": {
+    "type": "jsonl",
+    "eventSchema": {
+      "$ref": "./session-event.schema.json"
+    }
+  },
+  "compaction": {
+    "threshold": 8,
+    "keepTurns": 4,
+    "result": "turn-1 = summary round (user_message '【上下文压缩】<summary<=20000 chars>' + assistant_message '上下文已压缩，以上为历史摘要。' + turn_end completed); turn-2..turn-(K+1) = the last K complete turns verbatim with only turn_start/turn_end ids renumbered",
+    "dropped": "the unclosed tail turn and any events before the first turn_start",
+    "writeGuarantee": "backup -> tmp + sync_all -> rename (fsync'd, unlike the other data files); failure deletes the tmp"
+  },
+  "generatedAt": "2026-09-10T01:20:00Z"
+}

package/contracts/data-files/cli-main-jsonl.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "<session-dir>/cli-main.jsonl (engine v1 session log)",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): /src/celestea_harness/crates/core/src/session_log.rs:44-85",
+    "doc": "docs/data-files.md §4"
+  },
+  "path": {
+    "default": "<workspace path>/<session-dir>/cli-main.jsonl",
+    "envOverride": "CELESTEA_SESSION_DIR points at the session DIR"
+  },
+  "eventSchema": {
+    "$ref": "./session-event.schema.json"
+  },
+  "parse": {
+    "blankLines": "skipped",
+    "tornTail": "STOP at the first unparsable line; the rest of the file is ignored (never treated as content)"
+  },
+  "writer": "engine PersistentSessionLog (Studio never appends); /compact rewrites it atomically after backing up to cli-main.jsonl.precompact",
+  "attachments": "W804: a user_message row MAY carry an `attachments` array of content-addressed ImageRefs (see session-event.schema.json $defs/AttachmentRef). The image BYTES are NOT in this file: they live at <session-dir>/attachments/<sha256>.<ext>. No base64 / data: URL is ever written here.",
+  "generatedAt": "2026-09-10T01:20:00Z"
+}

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

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "fallbacks.json (model fallback chain, sidecar config)",
+  "source": {
+    "design": "/src/celestea_studio-ts/docs/iteration-e-capabilities.md §4.2.4 (E-P1, W785)",
+    "code": "packages/llm/src/fallback-config.ts (parseConfig/loadFallbackConfig), apps/studio/src/runtime/fallback-host.ts"
+  },
+  "path": {
+    "default": "<data dir>/fallbacks.json",
+    "alternate": "CELESTEA_LLM_FALLBACKS = the same JSON inline (wins over the file)",
+    "switch": "CELESTEA_LLM_FALLBACK=on|1|true|yes; anything else (and absent) = OFF, and the file is not even read",
+    "mode": "read-only (never written by the engine; operational input like pricing.json)"
+  },
+  "purpose": {
+    "kept": "the target chain (name/provider/model/base_url/api-key ENV NAME) and the retry/cooldown policy",
+    "notKept": "no credential VALUE is ever stored or logged (only `apiKeyEnv` names, §4.5 R4-3); the chain is deliberately NOT part of the frozen 12-key Profile (§4.2.4)",
+    "fallback": "when the file is missing/unparsable the engine assembles the chain from the composed profile alone and REPORTS the problem in /api/status.fallback.problems (never silently 'no fallback')"
+  },
+  "schema": {
+    "type": "object",
+    "required": ["targets"],
+    "additionalProperties": false,
+    "properties": {
+      "version": { "type": "integer", "const": 1 },
+      "enabled": { "type": "boolean" },
+      "targets": {
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "object",
+          "required": ["name", "model"],
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string", "minLength": 1, "description": "stable target name: ledger `fallback_from`, SSE frame `from`/`to`, audit line" },
+            "provider": { "type": "string", "description": "providers.json row id (defaults to `name`)" },
+            "model": { "type": "string", "minLength": 1 },
+            "baseUrl": { "type": "string", "description": "absent = the composed profile's base_url" },
+            "apiKeyEnv": { "type": "string", "description": "ENV VAR NAME of this target's key; absent = the profile's api_key_env" }
+          }
+        }
+      },
+      "policy": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "maxAttempts": { "type": "integer", "minimum": 1, "default": 2 },
+          "cooldownMs": { "type": "integer", "minimum": 0, "default": 60000 },
+          "failureThreshold": { "type": "integer", "minimum": 1, "default": 3 },
+          "notRetryableStatuses": { "type": "array", "items": { "type": "integer" }, "default": [400, 401, 403, 404, 422] },
+          "retryableStatuses": { "type": "array", "items": { "type": "integer" }, "default": [408, 425, 429, 500, 502, 503, 504] },
+          "respectRetryAfter": { "type": "boolean", "default": true }
+        }
+      }
+    }
+  },
+  "example": {
+    "version": 1,
+    "enabled": true,
+    "targets": [
+      { "name": "primary", "provider": "celestea", "model": "deepseek-chat" },
+      { "name": "backup", "provider": "基元", "model": "gpt-x", "baseUrl": "https://backup.example/v1", "apiKeyEnv": "BACKUP_API_KEY" }
+    ],
+    "policy": { "maxAttempts": 2, "cooldownMs": 60000, "failureThreshold": 3 }
+  },
+  "visibility": {
+    "sse": "one `status` frame with phase:\"fallback\" (+ from/to/reason/attempt/effective_model); the event NAME set is unchanged (K5)",
+    "statusline": "/api/status gains `effective_model` and `fallback{active,chain,effective_model,last_reason,targets,problems}` (optional additive fields)",
+    "audit": "<data dir>/fallbacks-audit.jsonl (authoritative, append-only, rotated at 16 MiB) + best-effort POST /api/audit when CELESTEA_AUDIT_URL is set",
+    "ledger": "one row per ATTEMPT in usage-ledger.jsonl (`attempt` + `fallback_from`)"
+  }
+}

package/contracts/data-files/index.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Celestea Studio data-file schemas (format freeze)",
+  "generatedAt": "2026-09-10T01:20:00Z",
+  "doc": "docs/data-files.md",
+  "freezeRule": "Migration period: NO format changes. Do not add a `version` field (it would let the two implementations diverge).",
+  "files": [
+    {
+      "file": "workspaces.json",
+      "schema": "workspaces.schema.json",
+      "version": "v2 (naming convention; no version field)",
+      "mode": "0644"
+    },
+    {
+      "file": "providers.json",
+      "schema": "providers.schema.json",
+      "version": "none",
+      "mode": "0600",
+      "secret": true
+    },
+    {
+      "file": "prompts.json",
+      "schema": "prompts.schema.json",
+      "version": "none",
+      "mode": "0644"
+    },
+    {
+      "file": "<CELESTEA_HOME>/workspaces/<ws>/prompts.json",
+      "schema": "prompts.schema.json",
+      "version": "none",
+      "mode": "0644",
+      "note": "W880: the workspace-scoped prompt registry. Legacy <ws>/.celestea/prompts.json and <ws>/.celestea-prompts.json stay readable as fallbacks; the canonical file wins on read and is the only write target."
+    },
+    {
+      "file": "session.json",
+      "schema": "session.schema.json",
+      "version": "none",
+      "mode": "0644"
+    },
+    {
+      "file": "cli-main.jsonl",
+      "schema": "cli-main-jsonl.schema.json",
+      "version": "engine v1 SessionEvent",
+      "mode": "0644"
+    },
+    {
+      "file": "cli-main.jsonl.precompact",
+      "schema": "cli-main-jsonl-precompact.schema.json",
+      "version": "engine v1 SessionEvent",
+      "mode": "0644"
+    },
+    {
+      "file": "/tmp/celestea-workers-registry.tsv",
+      "schema": "registry-tsv.schema.json",
+      "version": "4-column TSV",
+      "mode": "0644"
+    },
+    {
+      "file": "<data dir>/worker-registry.tsv",
+      "schema": "registry-tsv.schema.json",
+      "version": "4-column TSV (same format as /tmp/celestea-workers-registry.tsv)",
+      "mode": "0644",
+      "note": "W787 (E §2.2.1/§2.3 P0 ①): the STUDIO's own worker table — `<data dir>/worker-registry.tsv`, env `CELESTEA_WORKER_REGISTRY`, empty value = in-memory only (`tsvPath: null`). It is a SEPARATE table from the DSH-side plugin's `workerBase/registry.tsv`; neither side ever writes the other's (R2-1, asserted by B6)."
+    },
+    {
+      "file": "pricing.json",
+      "schema": "pricing.schema.json",
+      "version": "price snapshot (its own `version` is the price source's, not a data-file format version)",
+      "mode": "0644"
+    },
+    {
+      "file": "usage-ledger.jsonl",
+      "schema": "usage-ledger.schema.json",
+      "version": "ledger v1 (per-row `v`)",
+      "mode": "0600"
+    },
+    {
+      "file": "checkpoint.json",
+      "schema": "checkpoint.schema.json",
+      "version": "sidecar v1 (its own `version: 1` is the SIDECAR schema, not a data-file format version)",
+      "mode": "0600"
+    },
+    {
+      "file": "fallbacks.json",
+      "schema": "fallbacks.schema.json",
+      "version": "sidecar v1 (`version: 1` is the sidecar's own field, not a data-file format version)",
+      "mode": "read-only (never written by the engine)"
+    }
+  ],
+  "durability": {
+    "workspaces.json": "tmp+rename, no fsync",
+    "providers.json": "tmp+rename+0600, fsync (errors ignored)",
+    "prompts.json": "tmp+rename, no fsync",
+    "cli-main.jsonl (engine)": "engine-owned",
+    "cli-main.jsonl (compact rewrite)": "backup -> tmp+sync_all -> rename",
+    "session.json": "plain write, NOT atomic",
+    "registry.tsv": "tmp+rename (the write MERGES with the rows other session registries already wrote: one table carries every studio session, §2.2.1)",
+    "pricing.json": "read-only snapshot (never written by the engine); missing/unparsable -> empty table (every model unpriced)",
+    "usage-ledger.jsonl": "append-only, one writeSync per record on an O_APPEND fd (no fsync); rotated at 16 MiB to `<path>.1` (replaced), read() reads the current file only (W785 §3.3 P1 ④)",
+    "checkpoint.json": "tmp-<pid> + rename, mode 0600, no fsync (observation only: a lost sidecar reads as 'no checkpoint', which is fail-safe)",
+    "fallbacks.json": "read-only sidecar config (never written by the engine); missing/unparsable -> chain assembled from the composed profile + the problem reported in /api/status.fallback.problems"
+  },
+  "roundTripRequirement": "Every file needs a read -> write -> re-read round-trip test; both implementations must agree byte-for-byte on the written form.",
+  "attachments": {
+    "location": "<session-dir>/attachments/<sha256>.<ext>",
+    "kind": "binary image objects (PNG/JPEG/WebP/GIF), content-addressed; NEVER JSON",
+    "introduced": "W804 (multimodal P0 section 5): read_image and POST /api/turn inline uploads; the session log stores only ImageRef references (no base64)",
+    "lifecycle": "moves/archives/deletes with the session directory (rename); P0 does no GC",
+    "fixtures": "excluded: attachment bytes never enter fixtures/ (scripts/export-golden.ts hard rule)",
+    "schema": "none (binary; the JSONL reference shape is frozen by session-event.schema.json $defs/AttachmentRef)"
+  },
+  "ledger": {
+    "implemented": "W728 P0 (iteration E §3): step-granular append-only ledger + pricing snapshot + unpriced marking; W785 P1: GET /api/usage/ledger aggregate view (session|turn|model|day + since/until) + /api/status.cost + 16 MiB rotation",
+    "notImplemented": "scripts/sync-pricing.ts (the price snapshot is operator-supplied), SSE status.cost_delta, three-way reconciliation + budget stop-loss (P1/P2)"
+  },
+  "recovery": {
+    "implemented": "E-P0③ (§1.3 P0): checkpoint.json sidecar + idempotent boot synthesis of `turn_end: interrupted` + turnNo restored from the log; E-P1①②③ (§1.3 P1, W787): lane + delivered_ids persistence (the sidecar's `lanes`/`delivered_ids`), `GET /api/status.recovery` (pure addition, still no endpoint) and the degraded-log audit line (`<data dir>/recovery-audit.jsonl`)",
+    "notImplemented": "step-level resume and the tool side-effect table (§1.3 P2)"
+  },
+  "workerRegistry": {
+    "implemented": "E §2.3 P0 (W787): `<data dir>/worker-registry.tsv` (`CELESTEA_WORKER_REGISTRY`, `null` = in-memory) + `host=`/`attempt=`/`lease=` tokens + boot observation (`stale[]`/`orphans[]` on GET /api/worker/status, `<data dir>/recovery-audit.jsonl`) with NO re-dispatch; E §2.3 P1: attempt-ized report names (`results/<wid>-<short>-a<attempt>.md`) + `receipt=<wid>:<attempt>` idempotency (registry row and host inbox)",
+    "notImplemented": "E §2.3 P2 (auto-adopt / re-dispatch behind `CELESTEA_WORKER_RECOVER=1`, lease heartbeat, `autoDelete` interaction) and the optional read-only view of the DSH-side plugin's table"
+  }
+}

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

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "pricing.json (model price snapshot for the usage ledger)",
+  "source": {
+    "design": "/src/celestea_studio-ts/docs/iteration-e-capabilities.md §3.2.2 (W728 P0)",
+    "code": "packages/runtime/src/pricing.ts",
+    "priceOfRecord": "newapi owns the price of record (LTS biz/newapi.md I1–I3); this snapshot is an engine-side ESTIMATE"
+  },
+  "path": {
+    "default": "<data dir>/pricing.json (<data dir> = dirname(workspacesFile))",
+    "envOverride": "CELESTEA_PRICING_FILE"
+  },
+  "notes": [
+    "NO version field of the data-file kind: `version` here is the PRICE SNAPSHOT version (a date/label from the price source), and it is copied into every ledger row that was priced with it — an old row is never re-priced.",
+    "A model absent from `models` is NOT priced as 0: the ledger writes priced_by=\"unpriced\" and cost.total=null (never a silent zero).",
+    "A missing or unparsable file is an EMPTY table: every model is unpriced; the reason is reported on stderr and never thrown.",
+    "The engine only computes tokens/1e6 × unit price. Group multipliers, expressions and cache-discount algebra stay on the platform side (no second billing implementation)."
+  ],
+  "schema": {
+    "type": "object",
+    "required": ["version", "currency", "models"],
+    "properties": {
+      "version": { "type": "string", "description": "price snapshot version/label, e.g. \"2026-09-11\"" },
+      "effective_from": { "type": ["integer", "null"], "description": "unix seconds the snapshot is effective from" },
+      "currency": { "type": "string", "description": "display currency of every unit price (no conversion is ever done)" },
+      "unit": { "const": "per_mtok", "description": "the only unit the engine understands (price per million tokens)" },
+      "models": {
+        "type": "object",
+        "description": "model id -> unit prices",
+        "additionalProperties": {
+          "type": "object",
+          "required": ["in", "out"],
+          "properties": {
+            "in": { "type": "number", "minimum": 0, "description": "price of one UNCACHED prompt token; the provider's prompt_tokens already contains the cache-hit region, which is priced by cache_read only" },
+            "out": { "type": "number", "minimum": 0 },
+            "cache_read": { "type": "number", "minimum": 0, "default": 0, "description": "price of one cache-HIT (cache-read) token; charged once, never on top of the `in` price" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "source": {
+        "type": "object",
+        "description": "where the snapshot came from (P1 sync script): kind/ref/synced_at",
+        "additionalProperties": true
+      }
+    },
+    "additionalProperties": true
+  },
+  "example": {
+    "version": "2026-09-11",
+    "effective_from": 1759968000,
+    "currency": "CNY",
+    "unit": "per_mtok",
+    "models": {
+      "deepseek-chat": { "in": 1.0, "out": 2.0, "cache_read": 0.1 },
+      "deepseek-reasoner": { "in": 2.0, "out": 8.0, "cache_read": 0.2 }
+    },
+    "source": {
+      "kind": "manual",
+      "ref": "/src/CelesteaTeamAPI/newapi-ops/PRICING-ARCHITECTURE.md",
+      "synced_at": 1760000000
+    }
+  },
+  "generatedAt": "2026-09-11T00:00:00Z"
+}