usesteady 0.1.0-alpha.1

package/dist/src/ucp/mappers/map-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-safety.d.ts","sourceRoot":"","sources":["../../../../src/ucp/mappers/map-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAiB,OAAO,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CASxF"}

package/dist/src/ucp/mappers/map-safety.js

@@ -0,0 +1,22 @@
+/**
+ * Mapper: SafetyResult → SafetyEnvelope.
+ *
+ * Maps exactly from SafetyResult (src/safety/types.ts).
+ * Includes inspection fields (detectorId, matchedPattern) when present.
+ * "allow" results carry only the verdict — no reason or note.
+ *
+ * Optional fields use conditional spreading — never explicit undefined.
+ * See: src/ucp/types.ts — "PROTOCOL INVARIANT: Payloads must be undefined-free"
+ */
+import { createSafetyEnvelope } from "../envelope.js";
+export function mapSafetyToEnvelope(result, refs) {
+    const payload = {
+        verdict: result.verdict,
+        ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        ...(result.detectorId !== undefined ? { detectorId: result.detectorId } : {}),
+        ...(result.matchedPattern !== undefined ? { matchedPattern: result.matchedPattern } : {}),
+        ...(result.note !== undefined ? { note: result.note } : {}),
+    };
+    return createSafetyEnvelope(payload, refs);
+}
+//# sourceMappingURL=map-safety.js.map

package/dist/src/ucp/mappers/map-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-safety.js","sourceRoot":"","sources":["../../../../src/ucp/mappers/map-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAItD,MAAM,UAAU,mBAAmB,CAAC,MAAoB,EAAE,IAAc;IACtE,MAAM,OAAO,GAAkB;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAY,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAU,MAAM,CAAC,MAAM,EAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,GAAG,CAAC,MAAM,CAAC,UAAU,KAAQ,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAM,MAAM,CAAC,UAAU,EAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,GAAG,CAAC,MAAM,CAAC,IAAI,KAAc,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAY,MAAM,CAAC,IAAI,EAAW,CAAC,CAAC,CAAC,EAAE,CAAC;KACxF,CAAC;IACF,OAAO,oBAAoB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC"}

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

@@ -0,0 +1,24 @@
+/**
+ * UCP Persistence — public API.
+ *
+ * Phase 4A — store + write:
+ *   persistEnvelope   — fire-and-forget facade (callers use this)
+ *   appendEnvelope    — raw log append (returns byte offset)
+ *   loadIndex / updateIndex / rebuildIndex — index management
+ *
+ * Phase 4B — reader + query:
+ *   readEnvelopeAt    — seek to byte offset, parse one envelope
+ *   readAllEnvelopes  — full log scan
+ *   getEnvelopeById   — O(1) id lookup via index
+ *   getByType         — type-filtered bulk lookup
+ *   getChain          — full intent provenance chain via byRoot
+ *   getArtifactByRunId / getTraceByArtifactId / getReplayByArtifactId
+ *   getTimeline       — complete run reconstruction from intentId
+ */
+export type { UCPIndex } from "./store.js";
+export { LOG_FILENAME, INDEX_FILENAME, emptyIndex, ensureStoreDir, appendEnvelope, loadIndex, updateIndex, rebuildIndex, } from "./store.js";
+export { persistEnvelope } from "./write.js";
+export { readEnvelopeAt, readAllEnvelopes } from "./reader.js";
+export type { RunTimeline } from "./query.js";
+export { getEnvelopeById, getByType, getChain, getArtifactByRunId, getTraceByArtifactId, getReplayByArtifactId, getReminderExecutionByResponseId, getTimeline, } from "./query.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ucp/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,EACd,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EACL,eAAe,EACf,SAAS,EACT,QAAQ,EACR,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,gCAAgC,EAChC,WAAW,GACZ,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * UCP Persistence — public API.
+ *
+ * Phase 4A — store + write:
+ *   persistEnvelope   — fire-and-forget facade (callers use this)
+ *   appendEnvelope    — raw log append (returns byte offset)
+ *   loadIndex / updateIndex / rebuildIndex — index management
+ *
+ * Phase 4B — reader + query:
+ *   readEnvelopeAt    — seek to byte offset, parse one envelope
+ *   readAllEnvelopes  — full log scan
+ *   getEnvelopeById   — O(1) id lookup via index
+ *   getByType         — type-filtered bulk lookup
+ *   getChain          — full intent provenance chain via byRoot
+ *   getArtifactByRunId / getTraceByArtifactId / getReplayByArtifactId
+ *   getTimeline       — complete run reconstruction from intentId
+ */
+export { LOG_FILENAME, INDEX_FILENAME, emptyIndex, ensureStoreDir, appendEnvelope, loadIndex, updateIndex, rebuildIndex, } from "./store.js";
+export { persistEnvelope } from "./write.js";
+export { readEnvelopeAt, readAllEnvelopes } from "./reader.js";
+export { getEnvelopeById, getByType, getChain, getArtifactByRunId, getTraceByArtifactId, getReplayByArtifactId, getReminderExecutionByResponseId, getTimeline, } from "./query.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/ucp/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,EACd,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/D,OAAO,EACL,eAAe,EACf,SAAS,EACT,QAAQ,EACR,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,gCAAgC,EAChC,WAAW,GACZ,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,164 @@
+/**
+ * UCP Persistence Query Layer — navigation over the UCP envelope history.
+ *
+ * Every query function in this module ONLY follows explicit refs (parentId, rootId)
+ * or field values stored in the payload. No relationship is inferred.
+ *
+ * ── Design constraints ────────────────────────────────────────────────────────
+ *
+ *   1. Refs-only navigation — getChain follows refs.rootId, child lookups follow
+ *      refs.parentId. No structural inference beyond what refs declare.
+ *
+ *   2. No caching — each call reads from disk via reader.ts. Caching is deferred.
+ *
+ *   3. Type-narrowed returns — artifact/trace/replay queries return typed aliases.
+ *      Narrowing is done by checking envelope.type before casting — never blindly.
+ *
+ *   4. Null-safe — all queries return null or empty array rather than throwing
+ *      when data is missing or corrupt.
+ *
+ *   5. Zero mutation — returned envelopes are the exact parsed records; nothing
+ *      is modified, sorted, or enriched by this layer.
+ *
+ *   6. No authority — queries are read-only observability tools. They must not
+ *      affect any runtime, intake, or execution behavior.
+ *
+ * ── Query function summary ────────────────────────────────────────────────────
+ *
+ *   getEnvelopeById                  — load one envelope by id (uses byId index offset)
+ *   getByType                        — load all envelopes for a type (uses byType index)
+ *   getChain                         — load all envelopes for an intent (uses byRoot index)
+ *   getArtifactByRunId               — find artifact by payload.runId
+ *   getTraceByArtifactId             — find execution trace parented to an artifact env
+ *   getReplayByArtifactId            — find replay report parented to an artifact env
+ *   getReminderExecutionByResponseId — find reminder execution parented to a response env
+ *   getTimeline                      — full run reconstruction from an intentId
+ *
+ * ── Provenance chain (how envelopes link) ─────────────────────────────────────
+ *
+ *   ucp.intent.v1                — no refs (it is the root)
+ *   ucp.response.v1              — parentId = intentId,    rootId = intentId
+ *   ucp.artifact.v1              — rootId = intentId
+ *   ucp.execution_trace.v1       — parentId = artifactEnvId, rootId = intentId
+ *   ucp.replay_report.v1         — parentId = artifactEnvId, rootId = intentId
+ *   ucp.reminder_execution.v1    — parentId = responseEnvId, rootId = intentId
+ *
+ *   byRoot[intentId] covers: response + artifact + trace + replay + reminder_execution
+ *   byParent[artifactEnvId] covers: trace + replay
+ *   byParent[responseEnvId] covers: reminder_execution
+ */
+import type { UCPEnvelope, UCPType, ArtifactPayload, ArtifactEnvelope, ExecutionTracePayload, ExecutionTraceEnvelope, ReplayReportPayload, ReplayReportEnvelope, ReminderExecutionPayload, ReminderExecutionEnvelope } from "../types.js";
+/**
+ * Load one envelope by its content-addressed id.
+ * Uses the byId byte-offset index for O(1) file seek.
+ *
+ * Returns null if the id is not in the index or the record is corrupt.
+ */
+export declare function getEnvelopeById(storeDir: string, id: string): UCPEnvelope<unknown> | null;
+/**
+ * Load all envelopes of a specific UCPType.
+ * Uses byType index to identify ids, then resolves each via byId offset.
+ *
+ * Returns envelopes in index order (which matches append/log order).
+ * Corrupt or missing records are skipped silently.
+ */
+export declare function getByType(storeDir: string, type: UCPType): UCPEnvelope<unknown>[];
+/**
+ * Load the full provenance chain for an intent.
+ *
+ * Returns the intent envelope itself plus every envelope that declares
+ * refs.rootId === intentId. This covers: response, artifact, trace, replay.
+ *
+ * Envelopes are returned in log order (chronological).
+ *
+ * Returns an empty array if intentId is not found in the index.
+ */
+export declare function getChain(storeDir: string, intentId: string): UCPEnvelope<unknown>[];
+/**
+ * Find the artifact envelope whose payload.runId matches.
+ *
+ * Uses byType["ucp.artifact.v1"] to limit the scan to artifact envelopes only.
+ * Does NOT scan the full log. Returns null if no match is found.
+ *
+ * IMPORTANT: follows stored field values only — does not infer runId from context.
+ */
+export declare function getArtifactByRunId(storeDir: string, runId: string): ArtifactEnvelope | null;
+/**
+ * Find the execution trace envelope that is a direct child of `artifactEnvId`.
+ *
+ * A trace envelope declares refs.parentId === artifactEnvId.
+ * Returns null if not found.
+ */
+export declare function getTraceByArtifactId(storeDir: string, artifactEnvId: string): ExecutionTraceEnvelope | null;
+/**
+ * Find the replay report envelope that is a direct child of `artifactEnvId`.
+ *
+ * A replay envelope declares refs.parentId === artifactEnvId.
+ * Returns null if not found.
+ */
+export declare function getReplayByArtifactId(storeDir: string, artifactEnvId: string): ReplayReportEnvelope | null;
+/**
+ * Find the reminder execution envelope that is a direct child of `responseEnvId`.
+ *
+ * A reminder execution envelope declares refs.parentId === responseEnvId.
+ * Returns null if not found.
+ *
+ * Navigation: byParent[responseEnvId], filtered by type === "ucp.reminder_execution.v1".
+ */
+export declare function getReminderExecutionByResponseId(storeDir: string, responseEnvId: string): ReminderExecutionEnvelope | null;
+/**
+ * A complete run timeline reconstructed from the UCP log.
+ *
+ * All fields may be null — a field is null when the corresponding envelope
+ * has not yet been persisted, or was not found in the index.
+ *
+ * null does NOT mean failure — it means that phase of the run is not (yet) recorded.
+ *
+ * ── Branch structure ──────────────────────────────────────────────────────────
+ *
+ *   Standard execution branch:
+ *     intent → response → artifact → trace + replay
+ *
+ *   Reminder execution branch (Phase 6):
+ *     intent → response → reminderExecution
+ *
+ *   Both branches may be null — they are mutually exclusive in practice but
+ *   the type system does not enforce exclusivity (both fields may be non-null
+ *   if a run somehow produced both, though this should not occur).
+ */
+export type RunTimeline = {
+    /** The originating intent, if found. */
+    readonly intent: UCPEnvelope<unknown> | null;
+    /** The response envelope (mode + reason + guidance), if found. */
+    readonly response: UCPEnvelope<unknown> | null;
+    /** The artifact envelope (runId + goal + checksum), if found. */
+    readonly artifact: ArtifactEnvelope | null;
+    /** The execution trace envelope (traceHash + kinds), if found. */
+    readonly trace: ExecutionTraceEnvelope | null;
+    /** The replay report envelope (verdict + counts), if found. */
+    readonly replay: ReplayReportEnvelope | null;
+    /**
+     * The reminder execution envelope (verdict + time classification), if found.
+     *
+     * Present for runs that went through the reminder execution path (Phase 6).
+     * null for all standard (non-reminder) runs.
+     *
+     * Navigation: byRoot[intentId] scan → type === "ucp.reminder_execution.v1".
+     */
+    readonly reminderExecution: ReminderExecutionEnvelope | null;
+};
+/**
+ * Reconstruct a full run timeline from an intent envelope id.
+ *
+ * Navigation is strictly refs-based:
+ *   1. intentId          → intent envelope (byId lookup)
+ *   2. byRoot[intentId]  → all descendants; typed by envelope.type
+ *   3. artifact env id   → trace and replay (byParent lookup)
+ *   4. byRoot scan       → reminderExecution (type === "ucp.reminder_execution.v1")
+ *
+ * No inference. No relationship reconstruction beyond what refs declare.
+ * Returns a RunTimeline where missing envelopes are null.
+ */
+export declare function getTimeline(storeDir: string, intentId: string): RunTimeline;
+export type { ArtifactPayload, ExecutionTracePayload, ReplayReportPayload, ReminderExecutionPayload };
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/ucp/persistence/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAIrB;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAQ,MAAM,GACf,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAK7B;AAID;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAM,OAAO,GAChB,WAAW,CAAC,OAAO,CAAC,EAAE,CAWxB;AAID;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAG,MAAM,EACjB,QAAQ,EAAG,MAAM,GAChB,WAAW,CAAC,OAAO,CAAC,EAAE,CAoBxB;AAID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAK,MAAM,GACf,gBAAgB,GAAG,IAAI,CAezB;AAID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAQ,MAAM,EACtB,aAAa,EAAG,MAAM,GACrB,sBAAsB,GAAG,IAAI,CAa/B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAQ,MAAM,EACtB,aAAa,EAAG,MAAM,GACrB,oBAAoB,GAAG,IAAI,CAa7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAO,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,yBAAyB,GAAG,IAAI,CAalC;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAa,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAW,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAW,gBAAgB,GAAG,IAAI,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAc,sBAAsB,GAAG,IAAI,CAAC;IAC1D,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAa,oBAAoB,GAAG,IAAI,CAAC;IACxD;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,EAAE,yBAAyB,GAAG,IAAI,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,WAAW,CAsBb;AAGD,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,CAAC"}

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

@@ -0,0 +1,240 @@
+/**
+ * UCP Persistence Query Layer — navigation over the UCP envelope history.
+ *
+ * Every query function in this module ONLY follows explicit refs (parentId, rootId)
+ * or field values stored in the payload. No relationship is inferred.
+ *
+ * ── Design constraints ────────────────────────────────────────────────────────
+ *
+ *   1. Refs-only navigation — getChain follows refs.rootId, child lookups follow
+ *      refs.parentId. No structural inference beyond what refs declare.
+ *
+ *   2. No caching — each call reads from disk via reader.ts. Caching is deferred.
+ *
+ *   3. Type-narrowed returns — artifact/trace/replay queries return typed aliases.
+ *      Narrowing is done by checking envelope.type before casting — never blindly.
+ *
+ *   4. Null-safe — all queries return null or empty array rather than throwing
+ *      when data is missing or corrupt.
+ *
+ *   5. Zero mutation — returned envelopes are the exact parsed records; nothing
+ *      is modified, sorted, or enriched by this layer.
+ *
+ *   6. No authority — queries are read-only observability tools. They must not
+ *      affect any runtime, intake, or execution behavior.
+ *
+ * ── Query function summary ────────────────────────────────────────────────────
+ *
+ *   getEnvelopeById                  — load one envelope by id (uses byId index offset)
+ *   getByType                        — load all envelopes for a type (uses byType index)
+ *   getChain                         — load all envelopes for an intent (uses byRoot index)
+ *   getArtifactByRunId               — find artifact by payload.runId
+ *   getTraceByArtifactId             — find execution trace parented to an artifact env
+ *   getReplayByArtifactId            — find replay report parented to an artifact env
+ *   getReminderExecutionByResponseId — find reminder execution parented to a response env
+ *   getTimeline                      — full run reconstruction from an intentId
+ *
+ * ── Provenance chain (how envelopes link) ─────────────────────────────────────
+ *
+ *   ucp.intent.v1                — no refs (it is the root)
+ *   ucp.response.v1              — parentId = intentId,    rootId = intentId
+ *   ucp.artifact.v1              — rootId = intentId
+ *   ucp.execution_trace.v1       — parentId = artifactEnvId, rootId = intentId
+ *   ucp.replay_report.v1         — parentId = artifactEnvId, rootId = intentId
+ *   ucp.reminder_execution.v1    — parentId = responseEnvId, rootId = intentId
+ *
+ *   byRoot[intentId] covers: response + artifact + trace + replay + reminder_execution
+ *   byParent[artifactEnvId] covers: trace + replay
+ *   byParent[responseEnvId] covers: reminder_execution
+ */
+import { loadIndex } from "./store.js";
+import { readEnvelopeAt } from "./reader.js";
+// ─── Single-envelope lookup ───────────────────────────────────────────────────
+/**
+ * Load one envelope by its content-addressed id.
+ * Uses the byId byte-offset index for O(1) file seek.
+ *
+ * Returns null if the id is not in the index or the record is corrupt.
+ */
+export function getEnvelopeById(storeDir, id) {
+    const index = loadIndex(storeDir);
+    const offset = index.byId[id];
+    if (offset === undefined)
+        return null;
+    return readEnvelopeAt(storeDir, offset);
+}
+// ─── Type-based bulk lookup ───────────────────────────────────────────────────
+/**
+ * Load all envelopes of a specific UCPType.
+ * Uses byType index to identify ids, then resolves each via byId offset.
+ *
+ * Returns envelopes in index order (which matches append/log order).
+ * Corrupt or missing records are skipped silently.
+ */
+export function getByType(storeDir, type) {
+    const index = loadIndex(storeDir);
+    const ids = index.byType[type] ?? [];
+    const results = [];
+    for (const id of ids) {
+        const env = getEnvelopeById(storeDir, id);
+        if (env !== null)
+            results.push(env);
+    }
+    return results;
+}
+// ─── Chain navigation (byRoot) ────────────────────────────────────────────────
+/**
+ * Load the full provenance chain for an intent.
+ *
+ * Returns the intent envelope itself plus every envelope that declares
+ * refs.rootId === intentId. This covers: response, artifact, trace, replay.
+ *
+ * Envelopes are returned in log order (chronological).
+ *
+ * Returns an empty array if intentId is not found in the index.
+ */
+export function getChain(storeDir, intentId) {
+    const index = loadIndex(storeDir);
+    const results = [];
+    // The intent envelope itself has no refs — it is the root.
+    // It lives in byId but not in byRoot (nothing has rootId = intentId for the intent itself).
+    const intentOffset = index.byId[intentId];
+    if (intentOffset !== undefined) {
+        const intentEnv = readEnvelopeAt(storeDir, intentOffset);
+        if (intentEnv !== null)
+            results.push(intentEnv);
+    }
+    // All descendant envelopes: their refs.rootId === intentId
+    const childIds = index.byRoot[intentId] ?? [];
+    for (const id of childIds) {
+        const env = getEnvelopeById(storeDir, id);
+        if (env !== null)
+            results.push(env);
+    }
+    return results;
+}
+// ─── Artifact lookup ──────────────────────────────────────────────────────────
+/**
+ * Find the artifact envelope whose payload.runId matches.
+ *
+ * Uses byType["ucp.artifact.v1"] to limit the scan to artifact envelopes only.
+ * Does NOT scan the full log. Returns null if no match is found.
+ *
+ * IMPORTANT: follows stored field values only — does not infer runId from context.
+ */
+export function getArtifactByRunId(storeDir, runId) {
+    const index = loadIndex(storeDir);
+    const ids = index.byType["ucp.artifact.v1"] ?? [];
+    for (const id of ids) {
+        const env = getEnvelopeById(storeDir, id);
+        if (env === null)
+            continue;
+        if (env.type !== "ucp.artifact.v1")
+            continue;
+        // Type-narrow: payload has runId because type === "ucp.artifact.v1"
+        const payload = env.payload;
+        if (payload.runId === runId)
+            return env;
+    }
+    return null;
+}
+// ─── Children of an artifact (byParent) ──────────────────────────────────────
+/**
+ * Find the execution trace envelope that is a direct child of `artifactEnvId`.
+ *
+ * A trace envelope declares refs.parentId === artifactEnvId.
+ * Returns null if not found.
+ */
+export function getTraceByArtifactId(storeDir, artifactEnvId) {
+    const index = loadIndex(storeDir);
+    const childIds = index.byParent[artifactEnvId] ?? [];
+    for (const id of childIds) {
+        const env = getEnvelopeById(storeDir, id);
+        if (env === null)
+            continue;
+        if (env.type === "ucp.execution_trace.v1") {
+            return env;
+        }
+    }
+    return null;
+}
+/**
+ * Find the replay report envelope that is a direct child of `artifactEnvId`.
+ *
+ * A replay envelope declares refs.parentId === artifactEnvId.
+ * Returns null if not found.
+ */
+export function getReplayByArtifactId(storeDir, artifactEnvId) {
+    const index = loadIndex(storeDir);
+    const childIds = index.byParent[artifactEnvId] ?? [];
+    for (const id of childIds) {
+        const env = getEnvelopeById(storeDir, id);
+        if (env === null)
+            continue;
+        if (env.type === "ucp.replay_report.v1") {
+            return env;
+        }
+    }
+    return null;
+}
+/**
+ * Find the reminder execution envelope that is a direct child of `responseEnvId`.
+ *
+ * A reminder execution envelope declares refs.parentId === responseEnvId.
+ * Returns null if not found.
+ *
+ * Navigation: byParent[responseEnvId], filtered by type === "ucp.reminder_execution.v1".
+ */
+export function getReminderExecutionByResponseId(storeDir, responseEnvId) {
+    const index = loadIndex(storeDir);
+    const childIds = index.byParent[responseEnvId] ?? [];
+    for (const id of childIds) {
+        const env = getEnvelopeById(storeDir, id);
+        if (env === null)
+            continue;
+        if (env.type === "ucp.reminder_execution.v1") {
+            return env;
+        }
+    }
+    return null;
+}
+/**
+ * Reconstruct a full run timeline from an intent envelope id.
+ *
+ * Navigation is strictly refs-based:
+ *   1. intentId          → intent envelope (byId lookup)
+ *   2. byRoot[intentId]  → all descendants; typed by envelope.type
+ *   3. artifact env id   → trace and replay (byParent lookup)
+ *   4. byRoot scan       → reminderExecution (type === "ucp.reminder_execution.v1")
+ *
+ * No inference. No relationship reconstruction beyond what refs declare.
+ * Returns a RunTimeline where missing envelopes are null.
+ */
+export function getTimeline(storeDir, intentId) {
+    const chain = getChain(storeDir, intentId);
+    let intent = null;
+    let response = null;
+    let artifact = null;
+    let reminderExecution = null;
+    for (const env of chain) {
+        switch (env.type) {
+            case "ucp.intent.v1":
+                intent = env;
+                break;
+            case "ucp.response.v1":
+                response = env;
+                break;
+            case "ucp.artifact.v1":
+                artifact = env;
+                break;
+            case "ucp.reminder_execution.v1":
+                reminderExecution = env;
+                break;
+        }
+    }
+    // Trace and replay are children of the artifact envelope (standard execution branch)
+    const trace = artifact !== null ? getTraceByArtifactId(storeDir, artifact.id) : null;
+    const replay = artifact !== null ? getReplayByArtifactId(storeDir, artifact.id) : null;
+    return { intent, response, artifact, trace, replay, reminderExecution };
+}
+//# sourceMappingURL=query.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * UCP Persistence Reader — low-level log file reads.
+ *
+ * Provides two read primitives:
+ *   readEnvelopeAt   — seek to a byte offset, read one line, parse one envelope
+ *   readAllEnvelopes — scan the full log, parse all valid lines
+ *
+ * ── Design constraints ────────────────────────────────────────────────────────
+ *
+ *   1. Read-only — these functions never write to disk.
+ *   2. Null-safe — missing file or corrupt line returns null / is skipped.
+ *   3. No caching — each call reads from disk. Caching is a Phase 4C concern.
+ *   4. No inference — returns raw parsed envelope exactly as stored.
+ *
+ * ── Performance note ──────────────────────────────────────────────────────────
+ *
+ *   readEnvelopeAt uses openSync/readSync to seek without loading the full file.
+ *   Chunk size of 64 KB covers virtually all real envelope sizes. For unusually
+ *   large payloads, the chunk is extended automatically.
+ *
+ *   readAllEnvelopes reads the full file once and splits by newline.
+ *   This is correct for Phase 4B; rotation / streaming is a future concern.
+ */
+import type { UCPEnvelope } from "../types.js";
+/**
+ * Read and parse the envelope stored at `offset` bytes in envelopes.log.
+ *
+ * Returns null if:
+ *   - The log file does not exist
+ *   - The offset is beyond the end of file
+ *   - The line at that offset is not valid JSON
+ *
+ * Does NOT verify the envelope hash. Integrity checks are a query-layer concern.
+ */
+export declare function readEnvelopeAt(storeDir: string, offset: number): UCPEnvelope<unknown> | null;
+/**
+ * Read and parse all valid envelopes from envelopes.log.
+ *
+ * Corrupt or unparseable lines are skipped silently.
+ * Returns envelopes in log order (chronological, oldest first).
+ */
+export declare function readAllEnvelopes(storeDir: string): UCPEnvelope<unknown>[];
+//# sourceMappingURL=reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../../src/ucp/persistence/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAqC5F;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,EAAE,CAkBzE"}

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

@@ -0,0 +1,104 @@
+/**
+ * UCP Persistence Reader — low-level log file reads.
+ *
+ * Provides two read primitives:
+ *   readEnvelopeAt   — seek to a byte offset, read one line, parse one envelope
+ *   readAllEnvelopes — scan the full log, parse all valid lines
+ *
+ * ── Design constraints ────────────────────────────────────────────────────────
+ *
+ *   1. Read-only — these functions never write to disk.
+ *   2. Null-safe — missing file or corrupt line returns null / is skipped.
+ *   3. No caching — each call reads from disk. Caching is a Phase 4C concern.
+ *   4. No inference — returns raw parsed envelope exactly as stored.
+ *
+ * ── Performance note ──────────────────────────────────────────────────────────
+ *
+ *   readEnvelopeAt uses openSync/readSync to seek without loading the full file.
+ *   Chunk size of 64 KB covers virtually all real envelope sizes. For unusually
+ *   large payloads, the chunk is extended automatically.
+ *
+ *   readAllEnvelopes reads the full file once and splits by newline.
+ *   This is correct for Phase 4B; rotation / streaming is a future concern.
+ */
+import { existsSync, openSync, readSync, closeSync, readFileSync, } from "fs";
+import { join } from "path";
+import { LOG_FILENAME } from "./store.js";
+// ─── Single-envelope seek read ────────────────────────────────────────────────
+const INITIAL_CHUNK_BYTES = 65_536; // 64 KB — enough for all realistic envelope sizes
+/**
+ * Read and parse the envelope stored at `offset` bytes in envelopes.log.
+ *
+ * Returns null if:
+ *   - The log file does not exist
+ *   - The offset is beyond the end of file
+ *   - The line at that offset is not valid JSON
+ *
+ * Does NOT verify the envelope hash. Integrity checks are a query-layer concern.
+ */
+export function readEnvelopeAt(storeDir, offset) {
+    const logPath = join(storeDir, LOG_FILENAME);
+    if (!existsSync(logPath))
+        return null;
+    const fd = openSync(logPath, "r");
+    try {
+        let chunkSize = INITIAL_CHUNK_BYTES;
+        let line = null;
+        while (line === null) {
+            const buffer = Buffer.alloc(chunkSize);
+            const bytesRead = readSync(fd, buffer, 0, chunkSize, offset);
+            if (bytesRead === 0)
+                return null; // offset beyond EOF
+            const text = buffer.slice(0, bytesRead).toString("utf8");
+            const newlineIdx = text.indexOf("\n");
+            if (newlineIdx !== -1) {
+                // Found end of line within the chunk
+                line = text.slice(0, newlineIdx);
+            }
+            else if (bytesRead < chunkSize) {
+                // EOF reached before newline — the file ends without trailing newline
+                line = text;
+            }
+            else {
+                // Line exceeds chunk size — double and retry
+                chunkSize *= 2;
+            }
+        }
+        if (line.trim() === "")
+            return null;
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// ─── Full log scan ────────────────────────────────────────────────────────────
+/**
+ * Read and parse all valid envelopes from envelopes.log.
+ *
+ * Corrupt or unparseable lines are skipped silently.
+ * Returns envelopes in log order (chronological, oldest first).
+ */
+export function readAllEnvelopes(storeDir) {
+    const logPath = join(storeDir, LOG_FILENAME);
+    if (!existsSync(logPath))
+        return [];
+    const raw = readFileSync(logPath, "utf8");
+    const lines = raw.split("\n");
+    const results = [];
+    for (const line of lines) {
+        if (line.trim() === "")
+            continue;
+        try {
+            results.push(JSON.parse(line));
+        }
+        catch {
+            // Corrupt line — skip
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=reader.js.map