@skill-harness/adapters 0.11.0 → 0.13.0

package/README.md

@@ -1,7 +1,8 @@
 # @skill-harness/adapters
 
 Harness adapters for [skill-harness](https://github.com/mojomanyana/skill-harness):
-the `pi` runner + `claude-code` judge routing.
+the `pi` runner + `claude-code` judge routing, the frozen pi-daddy 0.17/v2
+normalizer, and the separately pinned production ledger-v3 normalizer.
 
 Internal — use the `skill-harness` CLI. See the repo for docs.
 

package/dist/archive-access.d.ts

@@ -0,0 +1,58 @@
+export interface ArchiveAccessPolicy {
+    archiveRoot: string;
+    id: string;
+    expiresAt: number;
+    maxCalls: number;
+    maxBytes: number;
+    purposes: string[];
+}
+export interface ArchiveConsent {
+    manifestId: string;
+    purpose: string;
+    expiresAt: number;
+}
+export interface GovernedArchiveRoute {
+    directory: string;
+    purpose: string;
+}
+export declare function createArchiveAccess(path: string, raw: ArchiveAccessPolicy, permissions: string[]): {
+    inspect: () => {
+        policy: ArchiveAccessPolicy;
+        lastObservedNow: number;
+        consents: {
+            id: unknown;
+            grant: ArchiveConsent;
+            state: string;
+        }[];
+        calls: number;
+        bytes: number;
+        pending: number;
+    };
+    previewConsent: (g: ArchiveConsent) => string;
+    previewRevocation: (id: string) => string;
+    consent(raw: ArchiveConsent, permissions: string[], now: number): string;
+    revoke(id: string, permissions: string[], now: number): void;
+    read(manifestId: string, purpose: string, maxBytes: number, now?: number): import("./evidence-archive.js").ArchiveRead;
+};
+/** Shared cooperative access owner. No history deletion, authentication, OS
+ * deadline guarantee, or reinterpretation of legacy raw archive APIs. */
+export declare function openArchiveAccess(path: string): {
+    inspect: () => {
+        policy: ArchiveAccessPolicy;
+        lastObservedNow: number;
+        consents: {
+            id: unknown;
+            grant: ArchiveConsent;
+            state: string;
+        }[];
+        calls: number;
+        bytes: number;
+        pending: number;
+    };
+    previewConsent: (g: ArchiveConsent) => string;
+    previewRevocation: (id: string) => string;
+    consent(raw: ArchiveConsent, permissions: string[], now: number): string;
+    revoke(id: string, permissions: string[], now: number): void;
+    read(manifestId: string, purpose: string, maxBytes: number, now?: number): import("./evidence-archive.js").ArchiveRead;
+};
+export declare function readGovernedArchive(root: string, manifestId: string, maxBytes: number, route: GovernedArchiveRoute, now?: number): import("./evidence-archive.js").ArchiveRead;

package/dist/archive-access.js

@@ -0,0 +1,61 @@
+import { learningCopy, learningHash, learningJournal, registerLearningStore, verifyLearningStore } from './learning-journal.js';
+import { readArchiveSource } from './evidence-archive.js';
+export function createArchiveAccess(path, raw, permissions) {
+    const policy = learningCopy(raw), binding = learningHash(policy);
+    if (!permissions.includes(binding))
+        throw Error('exact archive policy permission required');
+    validate(policy);
+    registerLearningStore(policy.archiveRoot, 'access', learningHash(policy.id), path, binding);
+    learningJournal(path, { type: 'archive-access-v1', policy, binding });
+    return openArchiveAccess(path);
+}
+function validate(p) { if (typeof p.id !== 'string' || !p.id.length || p.id.length > 128 || !Number.isSafeInteger(p.expiresAt) || p.expiresAt < 0 || !Number.isSafeInteger(p.maxCalls) || p.maxCalls < 1 || p.maxCalls > 1024 || !Number.isSafeInteger(p.maxBytes) || p.maxBytes < 1 || p.maxBytes > 64 * 1024 * 1024 || !Array.isArray(p.purposes) || !p.purposes.length || p.purposes.length > 16 || new Set(p.purposes).size !== p.purposes.length || p.purposes.some(s => typeof s !== 'string' || !s.length || s.length > 128))
+    throw Error('bounded archive access policy required'); }
+/** Shared cooperative access owner. No history deletion, authentication, OS
+ * deadline guarantee, or reinterpretation of legacy raw archive APIs. */
+export function openArchiveAccess(path) {
+    const journal = learningJournal(path), first = journal.read()[0].value, policy = learningCopy(first.policy);
+    validate(policy);
+    if (first.type !== 'archive-access-v1' || learningHash(policy) !== first.binding)
+        throw Error('archive policy changed');
+    const history = () => { verifyLearningStore(policy.archiveRoot, 'access', learningHash(policy.id), path, String(first.binding)); return journal.read(); };
+    const clock = (now) => { const rows = history(); if (!Number.isSafeInteger(now) || now < Math.max(0, ...rows.map(e => Number(e.value.now ?? 0))))
+        throw Error('archive access clock rewind'); journal.append(rows.at(-1).id, { type: 'clock', now }); if (now >= policy.expiresAt)
+        throw Error('archive access expired'); };
+    const consent = (raw) => { const g = learningCopy(raw); if (!/^[a-f0-9]{64}$/.test(g.manifestId) || !policy.purposes.includes(g.purpose) || !Number.isSafeInteger(g.expiresAt) || g.expiresAt < 0 || g.expiresAt > policy.expiresAt)
+        throw Error('consent outside policy'); return g; };
+    const digest = (g) => learningHash({ policy: String(first.binding), consent: consent(g) });
+    const revokeDigest = (id) => learningHash({ policy: String(first.binding), revoke: id });
+    const inspect = () => { const rows = history(), claims = rows.filter(e => e.value.type === 'read-claim'), lastObservedNow = Math.max(0, ...rows.map(e => Number(e.value.now ?? 0))); return { policy: learningCopy(policy), lastObservedNow, consents: rows.filter(e => e.value.type === 'consented').map(e => { const grant = e.value.grant; return { id: e.value.consentId, grant: learningCopy(grant), state: rows.some(r => r.value.type === 'revoked' && r.value.consentId === e.value.consentId) ? 'revoked' : lastObservedNow >= Math.min(policy.expiresAt, grant.expiresAt) ? 'expired' : 'not-revoked-at-last-observed-clock' }; }), calls: claims.length, bytes: claims.reduce((n, e) => { const settled = rows.find(s => s.value.type === 'read-settled' && s.value.claim === e.id); return n + Number(settled ? settled.value.bytes : e.value.reserved); }, 0), pending: claims.filter(e => !rows.some(s => s.value.type === 'read-settled' && s.value.claim === e.id)).length }; };
+    return { inspect, previewConsent: digest, previewRevocation: revokeDigest,
+        consent(raw, permissions, now) { clock(now); const g = consent(raw), id = digest(g), rows = history(); if (!permissions.includes(id) || now >= g.expiresAt)
+            throw Error('exact current consent permission required'); if (rows.some(e => e.value.type === 'revoked' && e.value.consentId === id))
+            throw Error('consent revoked'); if (!rows.some(e => e.value.type === 'consented' && e.value.consentId === id))
+            journal.append(rows.at(-1).id, { type: 'consented', consentId: id, grant: g, now }); return id; },
+        revoke(id, permissions, now) { clock(now); const rows = history(); if (!permissions.includes(revokeDigest(id)) || !rows.some(e => e.value.type === 'consented' && e.value.consentId === id))
+            throw Error('exact revocation permission required'); if (!rows.some(e => e.value.type === 'revoked' && e.value.consentId === id))
+            journal.append(rows.at(-1).id, { type: 'revoked', consentId: id, now }); },
+        read(manifestId, purpose, maxBytes, now = Date.now()) {
+            clock(now);
+            const rows = history(), valid = rows.filter(e => e.value.type === 'consented').filter(e => { const g = e.value.grant; return g.manifestId === manifestId && g.purpose === purpose && now < g.expiresAt && !rows.some(r => r.value.type === 'revoked' && r.value.consentId === e.value.consentId); });
+            if (valid.length !== 1)
+                throw Error('unique active manifest/purpose consent required');
+            if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > 8 * 1024 * 1024)
+                throw Error('archive read bound');
+            const used = inspect();
+            if (used.calls >= policy.maxCalls || maxBytes > policy.maxBytes - used.bytes)
+                throw Error('shared archive budget exhausted');
+            const claim = journal.append(rows.at(-1).id, { type: 'read-claim', manifestId, purpose, consentId: valid[0].value.consentId, reserved: maxBytes, now });
+            const result = readArchiveSource(policy.archiveRoot, manifestId, maxBytes);
+            journal.append(claim.id, { type: 'read-settled', claim: claim.id, bytes: result.status === 'available' ? result.bytes.length : 0, status: result.status, now });
+            return result;
+        },
+    };
+}
+export function readGovernedArchive(root, manifestId, maxBytes, route, now = Date.now()) {
+    const access = openArchiveAccess(route.directory);
+    if (access.inspect().policy.archiveRoot !== root)
+        throw Error('governed archive root mismatch');
+    return access.read(manifestId, route.purpose, maxBytes, now);
+}
+//# sourceMappingURL=archive-access.js.map

package/dist/archive-checkpoint.d.ts

@@ -0,0 +1,47 @@
+import { type ArchiveRead, type ArchiveSourceInput, type ArchiveRetention } from "./evidence-archive.js";
+export type SnapshotChange = "initial" | "append" | "replaced" | "unknown";
+export interface ArchiveCheckpoint {
+    version: "archive-checkpoint-v1";
+    sourceId: string;
+    sourceManifestId: string;
+    sourceSha256: string;
+    sourceBytes: number;
+    previousCheckpointId: string | null;
+    lineage: string;
+    declaredParser: {
+        id: string;
+        version: string;
+    };
+    reader: "jsonl-syntax-v1";
+    retention: ArchiveRetention;
+    change: SnapshotChange;
+    syntax: "complete" | "partial" | "error" | "unavailable";
+    completeBytes: number;
+    pendingBytes: number;
+    invalidLines: number;
+    issues: string[];
+    activeBranch: null;
+    acceptance: "not-assessed";
+}
+export interface ArchivedRecord {
+    id: string;
+    line: number;
+    start: number;
+    end: number;
+    value: unknown;
+}
+export interface CheckpointRead {
+    checkpoint: ArchiveCheckpoint;
+    source: ArchiveRead;
+    records: ArchivedRecord[];
+}
+/** Restart from the immutable checkpoint ID. This never advances a worker or invokes a gate. */
+export declare function readArchiveCheckpoint(root: string, checkpointId: string): CheckpointRead;
+/** Caller supplies an explicit snapshot, policy and prior receipt. No inferred active branch or acceptance. */
+export declare function ingestArchiveSnapshot(root: string, input: ArchiveSourceInput & {
+    previousCheckpointId?: string;
+}): CheckpointRead & {
+    checkpointId: string;
+    change: SnapshotChange | "repeat";
+    newRecords: ArchivedRecord[];
+};

package/dist/archive-checkpoint.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { parseArchivedJsonl, readArchiveSource, retainArchiveSource, } from "./evidence-archive.js";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const SHA = /^[a-f0-9]{64}$/;
+const LIMIT = 8 * 1024 * 1024;
+const parserEqual = (a, b) => a.id === b.id && a.version === b.version;
+function reject() { throw new Error("invalid archive checkpoint"); }
+function parseCheckpoint(bytes) {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const v = JSON.parse(text);
+    if (JSON.stringify(v) !== text)
+        reject();
+    const names = ["version", "sourceId", "sourceManifestId", "sourceSha256", "sourceBytes", "previousCheckpointId", "lineage", "declaredParser", "reader", "retention", "change", "syntax", "completeBytes", "pendingBytes", "invalidLines", "issues", "activeBranch", "acceptance"];
+    if (!v || Object.keys(v).length !== names.length || Object.keys(v).some(k => !names.includes(k))
+        || v.version !== "archive-checkpoint-v1" || v.reader !== "jsonl-syntax-v1"
+        || typeof v.sourceId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(v.sourceId)
+        || ![v.sourceManifestId, v.sourceSha256, v.lineage].every(h => typeof h === "string" && SHA.test(h))
+        || !(v.previousCheckpointId === null || (typeof v.previousCheckpointId === "string" && SHA.test(v.previousCheckpointId)))
+        || ![v.sourceBytes, v.completeBytes, v.pendingBytes, v.invalidLines].every(n => Number.isSafeInteger(n) && n >= 0 && n <= LIMIT)
+        || v.completeBytes + v.pendingBytes !== v.sourceBytes
+        || !v.declaredParser || Object.keys(v.declaredParser).sort().join() !== "id,version"
+        || ![v.declaredParser.id, v.declaredParser.version].every(s => typeof s === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(s))
+        || !["exact", "redacted", "reference-only"].includes(v.retention)
+        || !["initial", "append", "replaced", "unknown"].includes(v.change)
+        || !["complete", "partial", "error", "unavailable"].includes(v.syntax)
+        || (v.retention === "reference-only" && (v.syntax !== "unavailable" || v.completeBytes !== 0 || v.invalidLines !== 0))
+        || !Array.isArray(v.issues) || v.issues.length > 16 || v.issues.some(i => typeof i !== "string" || i.length > 128)
+        || v.activeBranch !== null || v.acceptance !== "not-assessed")
+        reject();
+    return v;
+}
+function records(checkpoint, source) {
+    if (source.status !== "available")
+        return [];
+    const parsed = parseArchivedJsonl(source.bytes);
+    return parsed.records.map(record => ({
+        ...record, id: hash(JSON.stringify([checkpoint.sourceId, checkpoint.lineage, record.start, hash(source.bytes.subarray(record.start, record.end))])),
+    }));
+}
+/** Restart from the immutable checkpoint ID. This never advances a worker or invokes a gate. */
+export function readArchiveCheckpoint(root, checkpointId) {
+    const stored = readArchiveSource(root, checkpointId);
+    if (stored.status !== "available" || stored.reference.retention !== "exact")
+        reject();
+    const checkpoint = parseCheckpoint(stored.bytes);
+    const source = readArchiveSource(root, checkpoint.sourceManifestId);
+    if (source.status === "available") {
+        const ref = source.reference;
+        if (ref.sourceId !== checkpoint.sourceId || ref.sha256 !== checkpoint.sourceSha256 || ref.bytes !== checkpoint.sourceBytes
+            || ref.retention !== checkpoint.retention || !parserEqual(ref.parser, checkpoint.declaredParser))
+            reject();
+        const actual = parseArchivedJsonl(source.bytes);
+        if (actual.status !== checkpoint.syntax || actual.completeBytes !== checkpoint.completeBytes
+            || actual.pendingBytes !== checkpoint.pendingBytes || actual.errors.length !== checkpoint.invalidLines)
+            reject();
+    }
+    return { checkpoint, source, records: records(checkpoint, source) };
+}
+/** Caller supplies an explicit snapshot, policy and prior receipt. No inferred active branch or acceptance. */
+export function ingestArchiveSnapshot(root, input) {
+    // Inspect the prior bytes BEFORE storing this snapshot, so reacquisition cannot disguise a prior gap.
+    const previous = input.previousCheckpointId ? readArchiveCheckpoint(root, input.previousCheckpointId) : undefined;
+    if (previous && previous.checkpoint.sourceId !== input.sourceId)
+        throw new Error("checkpoint source mismatch");
+    const captured = retainArchiveSource(root, input);
+    const source = readArchiveSource(root, captured.manifestId);
+    const issues = [];
+    let change = previous ? "unknown" : "initial";
+    let lineage = captured.manifestId;
+    if (previous) {
+        if (!parserEqual(previous.checkpoint.declaredParser, captured.reference.parser) || previous.checkpoint.retention !== input.retention) {
+            issues.push("parser-or-representation-changed");
+        }
+        else if (previous.source.status !== "available") {
+            issues.push("previous-content-unavailable");
+        }
+        else if (input.retention !== "exact") {
+            issues.push("non-exact-continuity-unknown");
+        }
+        else if (source.status === "available") {
+            if (captured.manifestId === previous.checkpoint.sourceManifestId) {
+                return { ...previous, checkpointId: input.previousCheckpointId, change: "repeat", newRecords: [] };
+            }
+            if (source.bytes.length >= previous.source.bytes.length && source.bytes.subarray(0, previous.source.bytes.length).equals(previous.source.bytes)) {
+                change = "append";
+                lineage = previous.checkpoint.lineage;
+            }
+            else {
+                change = "replaced";
+                issues.push("source-replaced");
+            }
+        }
+    }
+    if (input.retention === "redacted")
+        issues.push("redacted-representation");
+    if (source.status !== "available")
+        issues.push("content-not-retained");
+    const syntax = source.status === "available" ? parseArchivedJsonl(source.bytes) : undefined;
+    const checkpoint = {
+        version: "archive-checkpoint-v1", sourceId: input.sourceId,
+        sourceManifestId: captured.manifestId, sourceSha256: captured.reference.sha256, sourceBytes: captured.reference.bytes,
+        previousCheckpointId: input.previousCheckpointId ?? null, lineage,
+        declaredParser: captured.reference.parser, reader: "jsonl-syntax-v1", retention: input.retention, change,
+        syntax: syntax?.status ?? "unavailable", completeBytes: syntax?.completeBytes ?? 0,
+        pendingBytes: syntax?.pendingBytes ?? captured.reference.bytes, invalidLines: syntax?.errors.length ?? 0,
+        issues, activeBranch: null, acceptance: "not-assessed",
+    };
+    const result = retainArchiveSource(root, {
+        sourceId: `checkpoint-${hash(input.sourceId)}`, parser: { id: "archive-checkpoint", version: "1" },
+        retention: "exact", bytes: Buffer.from(JSON.stringify(checkpoint)),
+    });
+    const all = records(checkpoint, source);
+    return { checkpointId: result.manifestId, checkpoint, source, records: all, change,
+        newRecords: change === "append" ? all.filter(record => record.start >= previous.checkpoint.completeBytes) : all };
+}
+//# sourceMappingURL=archive-checkpoint.js.map

package/dist/archive-facts.d.ts

@@ -0,0 +1,19 @@
+import type { WorkSignalFacts } from '@skill-harness/core';
+import { type GovernedArchiveRoute } from './archive-access.js';
+/** Operational fixed-order fact adapter, not arbitrary model/host fact inference.
+ * The caller supplies independent scope/source pins; all actual bytes use consent. */
+export declare function readFixedOrderFacts(root: string, manifestId: string, route: GovernedArchiveRoute, raw: {
+    producerCommit: string;
+    scopeDigest: string;
+    population: string;
+    obligations: string[];
+}, now?: number): {
+    facts: WorkSignalFacts;
+    source: {
+        manifestId: string;
+        sha256: string;
+        producerCommit: string;
+    };
+    unknownNodes: any;
+    acceptance: "not-assessed";
+};

package/dist/archive-facts.js

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+import { readGovernedArchive } from './archive-access.js';
+import { learningCopy } from './learning-journal.js';
+/** Operational fixed-order fact adapter, not arbitrary model/host fact inference.
+ * The caller supplies independent scope/source pins; all actual bytes use consent. */
+export function readFixedOrderFacts(root, manifestId, route, raw, now = Date.now()) {
+    const expected = learningCopy(raw);
+    if (!/^[a-f0-9]{40}$/.test(expected.producerCommit) || !/^[a-f0-9]{64}$/.test(expected.scopeDigest) || typeof expected.population !== 'string' || !expected.population.length || expected.population.length > 512 || /[\u0000-\u001f\u007f]/.test(expected.population) || !Array.isArray(expected.obligations) || expected.obligations.length > 128 || expected.obligations.some(h => !/^[a-f0-9]{64}$/.test(h)))
+        throw Error('explicit fact source/scope pins required');
+    const read = readGovernedArchive(root, manifestId, 1024 * 1024, route, now);
+    if (read.status !== 'available' || read.reference.retention !== 'exact' || read.reference.parser.id !== 'factory-order-readback' || read.reference.parser.version !== '1')
+        throw Error('exact governed order readback required');
+    const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(read.bytes));
+    if (value.kind !== 'actual-fixed-profile-order' || value.producerCommit !== expected.producerCommit || !Array.isArray(value.nodes) || !value.nodes.length || value.nodes.length > 128 || value.nodes.some((n) => !n || !expected.obligations.includes(n.obligation?.digest) || typeof n.state !== 'string'))
+        throw Error('order facts source/scope mismatch');
+    const digest = createHash('sha256').update(read.bytes).digest('hex');
+    const facts = { scopeDigest: expected.scopeDigest, version: 'fixed-order-facts-v1', population: expected.population, expectedWaits: [], checkpoints: [], violations: value.nodes.filter((n) => n.state === 'exhausted').map((n) => ({ obligationDigest: n.obligation.digest, status: 'FAIL', evidence: digest })), priorAccepted: [] };
+    return { facts, source: { manifestId, sha256: digest, producerCommit: expected.producerCommit }, unknownNodes: value.nodes.filter((n) => !['satisfied', 'exhausted'].includes(n.state)).length, acceptance: 'not-assessed' };
+}
+//# sourceMappingURL=archive-facts.js.map

package/dist/archive-observer.d.ts

@@ -0,0 +1,21 @@
+import { ingestPolicySource } from "./archive-policy.js";
+export interface ArchiveObserverOptions {
+    policyPath: string;
+    sourceId: string;
+    intervalMs: number;
+    maxPolls: number;
+    previousCheckpointId?: string;
+    signal?: AbortSignal;
+    /** Optional synchronous metadata consumer, never a worker hook. Its failure does not stop capture. */
+    onObservation?: (value: ReturnType<typeof ingestPolicySource>) => void;
+}
+/** Bounded external file observation. No worker process, socket, session API, prompt or control channel is used. */
+export declare function observeArchiveSource(options: ArchiveObserverOptions): Promise<{
+    observerId: `${string}-${string}-${string}-${string}-${string}`;
+    polls: number;
+    lastCheckpointId: string | null;
+    receiptId: string;
+    stopped: "aborted" | "poll-limit" | "policy-change";
+    gaps: string[];
+    workerInteractions: 0;
+}>;

package/dist/archive-observer.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { archivePolicyBinding, ingestPolicySource } from "./archive-policy.js";
+import { retainArchiveSource } from "./evidence-archive.js";
+function cadence(ms, signal) {
+    return new Promise(resolve => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const finish = () => { clearTimeout(timer); signal?.removeEventListener("abort", finish); resolve(); };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener("abort", finish, { once: true });
+    });
+}
+/** Bounded external file observation. No worker process, socket, session API, prompt or control channel is used. */
+export async function observeArchiveSource(options) {
+    if (!Number.isSafeInteger(options.intervalMs) || options.intervalMs < 1 || options.intervalMs > 60000
+        || !Number.isSafeInteger(options.maxPolls) || options.maxPolls < 1 || options.maxPolls > 128)
+        throw new Error("bounded observer interval/poll count required");
+    const binding = archivePolicyBinding(options.policyPath, options.sourceId), observerId = randomUUID(), startedAt = new Date().toISOString();
+    let lastCheckpointId = options.previousCheckpointId ?? null, polls = 0, receiptId = "", consumer = options.onObservation;
+    let stopped = "poll-limit", terminal = false;
+    const gaps = new Set();
+    const records = [];
+    const persist = () => retainArchiveSource(binding.archiveRoot, {
+        sourceId: `observer-${observerId}`, parser: { id: "archive-observer", version: "1" }, retention: "exact",
+        bytes: Buffer.from(JSON.stringify({ version: "archive-observer-v1", observerId, policySha256: binding.policySha256, sourceId: binding.sourceId,
+            startedAt, polls, lastCheckpointId, state: terminal ? "terminal" : "running", stopped: terminal ? stopped : null, gaps: [...gaps].sort(), records, workerInteractions: 0, continuity: "bounded-observations-not-complete-live-coverage" })),
+    }).manifestId;
+    for (let i = 0; i < options.maxPolls; i++) {
+        if (options.signal?.aborted) {
+            stopped = "aborted";
+            break;
+        }
+        try {
+            if (archivePolicyBinding(options.policyPath, options.sourceId).policySha256 !== binding.policySha256)
+                throw new Error("changed");
+        }
+        catch {
+            gaps.add("policy-changed-or-unavailable");
+            stopped = "policy-change";
+            break;
+        }
+        polls++;
+        try {
+            const observation = ingestPolicySource(options.policyPath, options.sourceId, lastCheckpointId ?? undefined, binding.policySha256);
+            lastCheckpointId = observation.checkpointId;
+            records.push({ poll: polls, at: new Date().toISOString(), checkpointId: lastCheckpointId, state: "captured" });
+            if (consumer) {
+                try {
+                    const returned = consumer(observation);
+                    if (returned && typeof returned.then === "function") {
+                        gaps.add("async-consumer-outcome-unobserved");
+                        consumer = undefined;
+                        // The unsupported asynchronous outcome is already an explicit durable gap; never await it on capture.
+                        void Promise.resolve(returned).catch(() => undefined);
+                    }
+                }
+                catch {
+                    gaps.add("observation-consumer-failed");
+                    consumer = undefined;
+                }
+            }
+        }
+        catch {
+            gaps.add("source-observation-failed");
+            records.push({ poll: polls, at: new Date().toISOString(), checkpointId: lastCheckpointId, state: "gap" });
+        }
+        receiptId = persist();
+        if (i + 1 < options.maxPolls)
+            await cadence(options.intervalMs, options.signal);
+    }
+    if (options.signal?.aborted)
+        stopped = "aborted";
+    terminal = true;
+    receiptId = persist();
+    return { observerId, polls, lastCheckpointId, receiptId, stopped, gaps: [...gaps].sort(), workerInteractions: 0 };
+}
+//# sourceMappingURL=archive-observer.js.map

package/dist/archive-policy.d.ts

@@ -0,0 +1,107 @@
+import { type ArchiveRetention } from "./evidence-archive.js";
+export interface PolicySource {
+    id: string;
+    path: string;
+    parser: {
+        id: string;
+        version: string;
+    };
+    contentPolicy?: "manifest-only" | "referenced-blobs";
+}
+export interface ArchiveIngestionPolicy {
+    version: "archive-policy-v1" | "archive-policy-v2";
+    id: string;
+    revision: string;
+    sourceRoot: string;
+    archiveRoot: string;
+    maxBytes: number;
+    retention: ArchiveRetention;
+    expiresAt: string;
+    sources: PolicySource[];
+}
+/** Host-only policy binding for bounded external observation; no source bytes are read. */
+export declare function archivePolicyBinding(policyPath: string, sourceId: string): Readonly<{
+    policySha256: string;
+    archiveRoot: string;
+    sourceId: string;
+    archiveSourceId: string;
+    expiresAt: string;
+}>;
+/** Explicit operator-selected file policy. Not a credential, authorization attestation or hostile-agent sandbox. */
+export declare function ingestPolicySource(policyPath: string, sourceId: string, previousCheckpointId?: string, expectedPolicySha256?: string): {
+    change: string;
+    policyReceiptId: string;
+    kind: "execution-retention-v2";
+    checkpointId: string;
+    policySha256: string;
+    sourceId: string;
+    archiveSourceId: string;
+    sourceSha256: string;
+    sourceStatus: "available";
+    retention: "exact";
+    syntax: "not-applicable";
+    runtime: "running" | "terminal";
+    content: Record<"session" | "stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result", {
+        status: "available" | "missing" | "mismatch";
+        sha256: string | null;
+        bytes: number | null;
+    }>;
+    activeBranch: null;
+    coverage: "partial";
+    issueCount: number;
+    acceptance: "not-assessed";
+} | {
+    sourceId: string;
+    archiveSourceId: string;
+    change: import("./archive-checkpoint.js").SnapshotChange | "repeat";
+    policyReceiptId: string;
+    checkpointId: string;
+    policySha256: string;
+    sourceSha256: string;
+    sourceStatus: "available" | "missing" | "error";
+    retention: ArchiveRetention;
+    syntax: "error" | "complete" | "partial" | "unavailable";
+    completeBytes: number;
+    pendingBytes: number;
+    invalidLines: number;
+    issues: string[];
+    activeBranch: null;
+    acceptance: "not-assessed";
+};
+/** Metadata-only CLI/read-model output; no payload, local path or policy file is exported. */
+export declare function inspectPolicyCheckpoint(policyPath: string, sourceId: string, checkpointId: string): {
+    kind: "execution-retention-v2";
+    checkpointId: string;
+    policySha256: string;
+    sourceId: string;
+    archiveSourceId: string;
+    sourceSha256: string;
+    sourceStatus: "available";
+    retention: "exact";
+    syntax: "not-applicable";
+    runtime: "running" | "terminal";
+    content: Record<"session" | "stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result", {
+        status: "available" | "missing" | "mismatch";
+        sha256: string | null;
+        bytes: number | null;
+    }>;
+    activeBranch: null;
+    coverage: "partial";
+    issueCount: number;
+    acceptance: "not-assessed";
+} | {
+    sourceId: string;
+    archiveSourceId: string;
+    checkpointId: string;
+    policySha256: string;
+    sourceSha256: string;
+    sourceStatus: "available" | "missing" | "error";
+    retention: ArchiveRetention;
+    syntax: "error" | "complete" | "partial" | "unavailable";
+    completeBytes: number;
+    pendingBytes: number;
+    invalidLines: number;
+    issues: string[];
+    activeBranch: null;
+    acceptance: "not-assessed";
+};