usesteady 0.1.0-alpha.1

package/dist/src/ucp/persistence/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../../../src/ucp/persistence/reader.ts"],"names":[],"mappings":"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"}

package/dist/src/ucp/persistence/store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * UCP Persistence Store — raw file operations.
+ *
+ * Provides append-only JSONL logging and a lightweight JSON index for
+ * UCP envelopes. All operations are synchronous, deterministic, and
+ * filesystem-only — no database, no network, no async queues.
+ *
+ * ── File layout ──────────────────────────────────────────────────────────────
+ *
+ *   <storeDir>/
+ *     envelopes.log    # append-only JSONL — one envelope per line
+ *     index.json       # lightweight in-memory index (rebuildable)
+ *     index.json.tmp   # transient during atomic index write (never left behind)
+ *
+ * ── Design invariants ────────────────────────────────────────────────────────
+ *
+ *   1. The log is append-only. Lines are never rewritten or deleted.
+ *   2. Each line is stableStringify(envelope) — canonical, deterministic bytes.
+ *   3. The index is a projection of the log. It can always be rebuilt from scratch.
+ *   4. Index writes are atomic: write to .tmp, then rename. No partial index state.
+ *   5. Duplicate envelope ids are tolerated: second occurrence does not overwrite
+ *      the first in byId (first-write-wins for offset).
+ *   6. Corrupt lines in the log are skipped silently during rebuild.
+ *   7. This module has ZERO authority. It never affects mode, execution, or replay.
+ */
+import type { UCPEnvelope } from "../types.js";
+export declare const LOG_FILENAME = "envelopes.log";
+export declare const INDEX_FILENAME = "index.json";
+/**
+ * UCPIndex — lightweight projection of the log file.
+ *
+ * byId     — envelope id → byte offset in envelopes.log (seek position)
+ * byType   — envelope type → [id, ...] (insertion order)
+ * byRoot   — refs.rootId → [id, ...] (all envelopes in this intent chain)
+ * byParent — refs.parentId → [id, ...] (direct children of a parent envelope)
+ */
+export type UCPIndex = {
+    readonly byId: Record<string, number>;
+    readonly byType: Record<string, string[]>;
+    readonly byRoot: Record<string, string[]>;
+    readonly byParent: Record<string, string[]>;
+};
+export declare function emptyIndex(): UCPIndex;
+export declare function ensureStoreDir(storeDir: string): void;
+/**
+ * Append one envelope to the JSONL log.
+ * Returns the byte offset at which the envelope was written
+ * (i.e., the file size before the append).
+ *
+ * Uses stableStringify — output is canonical and deterministic.
+ * Same envelope always produces the same bytes.
+ */
+export declare function appendEnvelope(storeDir: string, envelope: UCPEnvelope<unknown>): number;
+/**
+ * Load the index from disk. Returns an empty index if the file does not exist
+ * or cannot be parsed.
+ */
+export declare function loadIndex(storeDir: string): UCPIndex;
+/**
+ * Add one envelope's index entries and atomically write the updated index.
+ *
+ * First-write-wins for byId: if the envelope id is already present, the stored
+ * offset is not overwritten. All other indexes (byType, byRoot, byParent) always
+ * append the id, preserving insertion order.
+ */
+export declare function updateIndex(storeDir: string, envelope: UCPEnvelope<unknown>, offset: number): void;
+/**
+ * Rebuild the entire index by scanning the log file from the beginning.
+ * Corrupt or unparseable lines are skipped with a console.warn.
+ * The rebuilt index is written atomically and returned.
+ *
+ * Use this when:
+ *   - index.json is missing or corrupt
+ *   - the log and index are suspected to be out of sync
+ */
+export declare function rebuildIndex(storeDir: string): UCPIndex;
+//# sourceMappingURL=store.d.ts.map

package/dist/src/ucp/persistence/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/ucp/persistence/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAaH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,eAAO,MAAM,YAAY,kBAAoB,CAAC;AAC9C,eAAO,MAAM,cAAc,eAAe,CAAC;AAI3C;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,UAAU,IAAI,QAAQ,CAErC;AAID,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIrD;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,MAAM,CAavF;AAID;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAQpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAgCvD"}

package/dist/src/ucp/persistence/store.js

@@ -0,0 +1,177 @@
+/**
+ * UCP Persistence Store — raw file operations.
+ *
+ * Provides append-only JSONL logging and a lightweight JSON index for
+ * UCP envelopes. All operations are synchronous, deterministic, and
+ * filesystem-only — no database, no network, no async queues.
+ *
+ * ── File layout ──────────────────────────────────────────────────────────────
+ *
+ *   <storeDir>/
+ *     envelopes.log    # append-only JSONL — one envelope per line
+ *     index.json       # lightweight in-memory index (rebuildable)
+ *     index.json.tmp   # transient during atomic index write (never left behind)
+ *
+ * ── Design invariants ────────────────────────────────────────────────────────
+ *
+ *   1. The log is append-only. Lines are never rewritten or deleted.
+ *   2. Each line is stableStringify(envelope) — canonical, deterministic bytes.
+ *   3. The index is a projection of the log. It can always be rebuilt from scratch.
+ *   4. Index writes are atomic: write to .tmp, then rename. No partial index state.
+ *   5. Duplicate envelope ids are tolerated: second occurrence does not overwrite
+ *      the first in byId (first-write-wins for offset).
+ *   6. Corrupt lines in the log are skipped silently during rebuild.
+ *   7. This module has ZERO authority. It never affects mode, execution, or replay.
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, renameSync, statSync, } from "fs";
+import { join } from "path";
+import { stableStringify } from "../hashes.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const LOG_FILENAME = "envelopes.log";
+export const INDEX_FILENAME = "index.json";
+export function emptyIndex() {
+    return { byId: {}, byType: {}, byRoot: {}, byParent: {} };
+}
+// ─── Directory setup ──────────────────────────────────────────────────────────
+export function ensureStoreDir(storeDir) {
+    if (!existsSync(storeDir)) {
+        mkdirSync(storeDir, { recursive: true });
+    }
+}
+// ─── Log operations ───────────────────────────────────────────────────────────
+/**
+ * Append one envelope to the JSONL log.
+ * Returns the byte offset at which the envelope was written
+ * (i.e., the file size before the append).
+ *
+ * Uses stableStringify — output is canonical and deterministic.
+ * Same envelope always produces the same bytes.
+ */
+export function appendEnvelope(storeDir, envelope) {
+    ensureStoreDir(storeDir);
+    const logPath = join(storeDir, LOG_FILENAME);
+    const line = stableStringify(envelope) + "\n";
+    let offset = 0;
+    if (existsSync(logPath)) {
+        offset = statSync(logPath).size;
+    }
+    appendFileSync(logPath, line, "utf8");
+    return offset;
+}
+// ─── Index operations ─────────────────────────────────────────────────────────
+/**
+ * Load the index from disk. Returns an empty index if the file does not exist
+ * or cannot be parsed.
+ */
+export function loadIndex(storeDir) {
+    const indexPath = join(storeDir, INDEX_FILENAME);
+    if (!existsSync(indexPath))
+        return emptyIndex();
+    try {
+        return JSON.parse(readFileSync(indexPath, "utf8"));
+    }
+    catch {
+        return emptyIndex();
+    }
+}
+/**
+ * Add one envelope's index entries and atomically write the updated index.
+ *
+ * First-write-wins for byId: if the envelope id is already present, the stored
+ * offset is not overwritten. All other indexes (byType, byRoot, byParent) always
+ * append the id, preserving insertion order.
+ */
+export function updateIndex(storeDir, envelope, offset) {
+    const index = loadIndex(storeDir);
+    const next = addToIndex(index, envelope, offset);
+    writeIndexAtomic(storeDir, next);
+}
+/**
+ * Rebuild the entire index by scanning the log file from the beginning.
+ * Corrupt or unparseable lines are skipped with a console.warn.
+ * The rebuilt index is written atomically and returned.
+ *
+ * Use this when:
+ *   - index.json is missing or corrupt
+ *   - the log and index are suspected to be out of sync
+ */
+export function rebuildIndex(storeDir) {
+    const logPath = join(storeDir, LOG_FILENAME);
+    if (!existsSync(logPath)) {
+        const empty = emptyIndex();
+        writeIndexAtomic(storeDir, empty);
+        return empty;
+    }
+    const raw = readFileSync(logPath, "utf8");
+    const lines = raw.split("\n");
+    let index = emptyIndex();
+    let byteOffset = 0;
+    for (const line of lines) {
+        const lineBytes = Buffer.byteLength(line, "utf8");
+        if (line.trim() !== "") {
+            try {
+                const envelope = JSON.parse(line);
+                index = addToIndex(index, envelope, byteOffset);
+            }
+            catch {
+                console.warn(`[ucp-persist] rebuildIndex: skipping corrupt line at offset ${byteOffset}`);
+            }
+        }
+        // Each line in the log ends with \n — account for it.
+        byteOffset += lineBytes + 1;
+    }
+    writeIndexAtomic(storeDir, index);
+    return index;
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Pure function — returns a new UCPIndex with the envelope's entries added.
+ * Does not mutate the input index.
+ */
+function addToIndex(index, envelope, offset) {
+    const byId = { ...index.byId };
+    const byType = { ...index.byType };
+    const byRoot = { ...index.byRoot };
+    const byParent = { ...index.byParent };
+    // byId — first-write-wins: preserve the offset of the first occurrence.
+    if (!(envelope.id in byId)) {
+        byId[envelope.id] = offset;
+    }
+    // byType
+    if (!byType[envelope.type])
+        byType[envelope.type] = [];
+    if (!byType[envelope.type].includes(envelope.id)) {
+        byType[envelope.type] = [...byType[envelope.type], envelope.id];
+    }
+    // byRoot (only if refs.rootId present)
+    const rootId = envelope.refs?.rootId;
+    if (rootId) {
+        if (!byRoot[rootId])
+            byRoot[rootId] = [];
+        if (!byRoot[rootId].includes(envelope.id)) {
+            byRoot[rootId] = [...byRoot[rootId], envelope.id];
+        }
+    }
+    // byParent (only if refs.parentId present)
+    const parentId = envelope.refs?.parentId;
+    if (parentId) {
+        if (!byParent[parentId])
+            byParent[parentId] = [];
+        if (!byParent[parentId].includes(envelope.id)) {
+            byParent[parentId] = [...byParent[parentId], envelope.id];
+        }
+    }
+    return { byId, byType, byRoot, byParent };
+}
+/**
+ * Atomically write index to disk: write to a .tmp file, then rename.
+ * This guarantees the index is never left in a partial state.
+ */
+function writeIndexAtomic(storeDir, index) {
+    ensureStoreDir(storeDir);
+    const indexPath = join(storeDir, INDEX_FILENAME);
+    const tmpPath = indexPath + ".tmp";
+    writeFileSync(tmpPath, JSON.stringify(index, null, 2), "utf8");
+    renameSync(tmpPath, indexPath);
+}
+//# sourceMappingURL=store.js.map

package/dist/src/ucp/persistence/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../src/ucp/persistence/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,GACT,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,iFAAiF;AAEjF,MAAM,CAAC,MAAM,YAAY,GAAK,eAAe,CAAC;AAC9C,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAmB3C,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAC5D,CAAC;AAED,iFAAiF;AAEjF,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,QAA8B;IAC7E,cAAc,CAAC,QAAQ,CAAC,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAE7C,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAE9C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;IAClC,CAAC;IAED,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IACjD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,UAAU,EAAE,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAa,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,QAA8B,EAAE,MAAc;IAC1F,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,IAAI,GAAI,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAK,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE9B,IAAI,KAAK,GAAa,UAAU,EAAE,CAAC;IACnC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAElD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;gBAC1D,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,IAAI,CAAC,+DAA+D,UAAU,EAAE,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;QAED,sDAAsD;QACtD,UAAU,IAAI,SAAS,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AAEjF;;;GAGG;AACH,SAAS,UAAU,CAAC,KAAe,EAAE,QAA8B,EAAE,MAAc;IACjF,MAAM,IAAI,GAAO,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,MAAM,GAAK,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;IACrC,MAAM,MAAM,GAAK,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IAEvC,wEAAwE;IACxE,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;IAC7B,CAAC;IAED,SAAS;IACT,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAClD,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,uCAAuC;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACrC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACzC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QACjD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/C,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,QAAgB,EAAE,KAAe;IACzD,cAAc,CAAC,QAAQ,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IACjD,MAAM,OAAO,GAAK,SAAS,GAAG,MAAM,CAAC;IACrC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/D,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACjC,CAAC"}

package/dist/src/ucp/persistence/write.d.ts

@@ -0,0 +1,48 @@
+/**
+ * UCP Persistence — persistEnvelope facade.
+ *
+ * This is the single public call site for persisting a UCP envelope.
+ * It wraps the raw store operations in a try/catch so that persistence
+ * failures NEVER surface as execution failures.
+ *
+ * Callers (server.ts, CLI shell) must call this inside a fire-and-forget
+ * async block — this module itself is synchronous.
+ *
+ * ── Authority ────────────────────────────────────────────────────────────────
+ *
+ *   persistEnvelope is zero-authority.
+ *   A persistence failure must never:
+ *     - cause a run to fail
+ *     - change mode or execution behavior
+ *     - surface to the renderer
+ *
+ *   The only observable side effect of failure is a console.warn line.
+ */
+import type { UCPEnvelope } from "../types.js";
+/**
+ * Persist one UCP envelope to the store directory.
+ *
+ * Appends to envelopes.log and updates index.json atomically.
+ * Never throws — errors are swallowed with console.warn.
+ *
+ * Use for: post-execution envelopes where a persistence failure must not
+ * block or change system behavior (fire-and-forget semantics).
+ *
+ * @param storeDir  Absolute path to the UCP store directory.
+ * @param envelope  The UCP envelope to persist.
+ */
+export declare function persistEnvelope(storeDir: string, envelope: UCPEnvelope<unknown>): void;
+/**
+ * Persist one UCP envelope to the store directory, throwing on failure.
+ *
+ * Unlike persistEnvelope, this function DOES throw if persistence fails.
+ * Use for: pre-delivery gates where a persistence failure must block the
+ * subsequent action (e.g., cursor handoff — delivery must not proceed if
+ * the provenance record cannot be written).
+ *
+ * @param storeDir  Absolute path to the UCP store directory.
+ * @param envelope  The UCP envelope to persist.
+ * @throws          If appending or indexing fails for any reason.
+ */
+export declare function persistEnvelopeOrThrow(storeDir: string, envelope: UCPEnvelope<unknown>): void;
+//# sourceMappingURL=write.d.ts.map

package/dist/src/ucp/persistence/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../../src/ucp/persistence/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAUtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAG7F"}

package/dist/src/ucp/persistence/write.js

@@ -0,0 +1,59 @@
+/**
+ * UCP Persistence — persistEnvelope facade.
+ *
+ * This is the single public call site for persisting a UCP envelope.
+ * It wraps the raw store operations in a try/catch so that persistence
+ * failures NEVER surface as execution failures.
+ *
+ * Callers (server.ts, CLI shell) must call this inside a fire-and-forget
+ * async block — this module itself is synchronous.
+ *
+ * ── Authority ────────────────────────────────────────────────────────────────
+ *
+ *   persistEnvelope is zero-authority.
+ *   A persistence failure must never:
+ *     - cause a run to fail
+ *     - change mode or execution behavior
+ *     - surface to the renderer
+ *
+ *   The only observable side effect of failure is a console.warn line.
+ */
+import { appendEnvelope, updateIndex } from "./store.js";
+/**
+ * Persist one UCP envelope to the store directory.
+ *
+ * Appends to envelopes.log and updates index.json atomically.
+ * Never throws — errors are swallowed with console.warn.
+ *
+ * Use for: post-execution envelopes where a persistence failure must not
+ * block or change system behavior (fire-and-forget semantics).
+ *
+ * @param storeDir  Absolute path to the UCP store directory.
+ * @param envelope  The UCP envelope to persist.
+ */
+export function persistEnvelope(storeDir, envelope) {
+    try {
+        const offset = appendEnvelope(storeDir, envelope);
+        updateIndex(storeDir, envelope, offset);
+    }
+    catch (err) {
+        console.warn(`[ucp-persist] Failed to persist envelope id=${envelope.id.slice(0, 8)}… type=${envelope.type}:`, err);
+    }
+}
+/**
+ * Persist one UCP envelope to the store directory, throwing on failure.
+ *
+ * Unlike persistEnvelope, this function DOES throw if persistence fails.
+ * Use for: pre-delivery gates where a persistence failure must block the
+ * subsequent action (e.g., cursor handoff — delivery must not proceed if
+ * the provenance record cannot be written).
+ *
+ * @param storeDir  Absolute path to the UCP store directory.
+ * @param envelope  The UCP envelope to persist.
+ * @throws          If appending or indexing fails for any reason.
+ */
+export function persistEnvelopeOrThrow(storeDir, envelope) {
+    const offset = appendEnvelope(storeDir, envelope);
+    updateIndex(storeDir, envelope, offset);
+}
+//# sourceMappingURL=write.js.map

package/dist/src/ucp/persistence/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../../src/ucp/persistence/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,QAA8B;IAC9E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAClD,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CACV,+CAA+C,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,QAAQ,CAAC,IAAI,GAAG,EAChG,GAAG,CACJ,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB,EAAE,QAA8B;IACrF,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAClD,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/dist/src/ucp/projection.d.ts

@@ -0,0 +1,146 @@
+/**
+ * UCP Seam Projection — Phase 2 integration layer.
+ *
+ * UCPSeamProjection is the formal shape the shell layer exposes to surfaces
+ * (CLI, web UI, or any other consumer). It is PROVABLY derived from a
+ * UCPBundle — never constructed independently.
+ *
+ * ── Why this exists ───────────────────────────────────────────────────────────
+ *
+ * Before Phase 2, the seam exposed `PresentationOutput` — a manually maintained
+ * type that mirrored intake results but had no formal link to UCP.
+ *
+ * UCPSeamProjection replaces that. Every field maps to a specific envelope:
+ *
+ *   mode           ← bundle.response.payload.mode
+ *   badge          ← derived from mode (display only)
+ *   headline       ← bundle.intentInterpretation?.payload.summary
+ *                    OR bundle.changeInterpretation?.payload.summary
+ *                    OR bundle.response.payload.reason
+ *   category       ← human label from intentInterpretation or changeInterpretation
+ *   confidence     ← human label from intentInterpretation or changeInterpretation
+ *   steps          ← bundle.response.payload.guidance.nextSteps[].label  (enriched form)
+ *   missing        ← bundle.response.payload.guidance.missing
+ *   certaintyLevel ← derived: execute+change→certain, guide+intent→inferred, else→unknown
+ *   debugTrace     ← bundle.debugTrace.payload (all trace fields from the envelope)
+ *
+ *   envelopeIds    ← { intentId, responseId, traceId } from bundle envelope .id fields
+ *                    This is the PROOF FIELD.
+ *                    A consumer can verify that this projection came from a real UCPBundle
+ *                    by checking that envelopeIds.responseId is a valid sha256 hex string
+ *                    and matches bundle.response.id for the same input.
+ *
+ * ── Invariants ────────────────────────────────────────────────────────────────
+ *
+ *   1. projectUCPBundle is a pure function. Same bundle → same projection.
+ *   2. mode is sourced from bundle.response.payload.mode — it cannot drift.
+ *   3. envelopeIds are content-addressed. Same input → same IDs.
+ *   4. No field may be invented. Every field is derived from a named envelope.
+ *   5. A renderer MUST route on projection.mode, never on any other field.
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────
+ *
+ *   Not a pipeline layer. Not a decision layer. Not a transport format.
+ *   It is a formal, testable projection function: f(UCPBundle) → UCPSeamProjection.
+ */
+import type { ResponseMode } from "../intake/types.js";
+import type { DebugTracePayload } from "./types.js";
+import type { UCPBundle } from "../intake/intake-service.js";
+/**
+ * Three content-addressed sha256 envelope IDs that prove this projection
+ * was derived from a real UCPBundle.
+ *
+ * These IDs are deterministic:
+ *   Same input → same intentId, responseId, traceId.
+ *
+ * A consumer verifying authenticity checks:
+ *   envelopeIds.responseId.match(/^[0-9a-f]{64}$/) — it is a valid SHA-256
+ */
+export type UCPProjectionEnvelopeIds = {
+    /** bundle.intent.id — content-addressed from the raw input string. */
+    readonly intentId: string;
+    /** bundle.response.id — content-addressed from mode + reason + intentState. */
+    readonly responseId: string;
+    /** bundle.debugTrace.id — content-addressed from all trace fields. */
+    readonly traceId: string;
+};
+/**
+ * The formal shape exposed to seam consumers (renderers, IPC callers).
+ *
+ * This type is structurally compatible with the legacy PresentationOutput
+ * and UICoreIntakeResult but carries the additional envelopeIds proof field.
+ *
+ * Consumers that only care about rendering can ignore envelopeIds.
+ * Consumers verifying UCP provenance should check it.
+ */
+export type UCPSeamProjection = {
+    /**
+     * Source: bundle.response.payload.mode
+     * THE ONLY ROUTING AUTHORITY. Consumers MUST route on this field.
+     */
+    readonly mode: ResponseMode;
+    /**
+     * Source: derived from mode using MODE_BADGES lookup.
+     * Display only. Does not affect routing.
+     */
+    readonly badge: string;
+    /**
+     * Source (priority order):
+     *   1. bundle.intentInterpretation.payload.summary  (guide + bridge)
+     *   2. bundle.changeInterpretation.payload.summary  (execute + structured patch)
+     *   3. bundle.response.payload.reason               (fallback for all modes)
+     */
+    readonly headline: string;
+    /**
+     * Source: derived from mode + interpretation envelope presence.
+     *   "certain"  → mode="execute" AND bundle.changeInterpretation exists
+     *   "inferred" → mode="guide"   AND bundle.intentInterpretation exists
+     *   "unknown"  → all other cases
+     */
+    readonly certaintyLevel: "certain" | "inferred" | "unknown";
+    /**
+     * Source: human label derived from:
+     *   - bundle.intentInterpretation.payload.category  (guide mode)
+     *   - bundle.changeInterpretation.payload.category  (execute mode)
+     * Absent when no interpretation envelope is present.
+     */
+    readonly category?: string;
+    /**
+     * Source: human label derived from whichever interpretation envelope fired.
+     * Absent when no interpretation envelope is present.
+     */
+    readonly confidence?: string;
+    /**
+     * Source: bundle.response.payload.guidance.nextSteps[].label
+     * This is the ENRICHED, ordering-applied form — not the raw CompletionResult.
+     * Includes interpretation-improved labels and session-ordered steps.
+     * Present only when mode === "guide".
+     */
+    readonly steps?: ReadonlyArray<string>;
+    /**
+     * Source: bundle.response.payload.guidance.missing
+     * Present only when mode === "guide".
+     */
+    readonly missing?: ReadonlyArray<string>;
+    /**
+     * Source: bundle.debugTrace.payload (all 6 trace fields from the envelope).
+     * Zero authority. Developer-facing observability only.
+     */
+    readonly debugTrace?: DebugTracePayload;
+    /**
+     * Proof field: three content-addressed envelope IDs.
+     * These IDs are sha256 hashes. Same input → same IDs (content-addressed).
+     * Their presence proves this projection came from a UCPBundle.
+     */
+    readonly envelopeIds: UCPProjectionEnvelopeIds;
+};
+/**
+ * Project a UCPBundle into a UCPSeamProjection.
+ *
+ * Pure function — same bundle → same projection, always.
+ * No side effects. No I/O. No randomness.
+ *
+ * Every output field documents its source envelope in the type definition above.
+ */
+export declare function projectUCPBundle(bundle: UCPBundle): UCPSeamProjection;
+//# sourceMappingURL=projection.d.ts.map

package/dist/src/ucp/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../src/ucp/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAI7D;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAI,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAK,MAAM,CAAC;CAC7B,CAAC;AAIF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAE5D;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAExC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAC;CAChD,CAAC;AAmCF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAyErE"}