@playola-radio/slipstream 0.1.0

package/dist/display-fold.js

@@ -0,0 +1,332 @@
+/**
+ * `display-fold.v1` — the canonical display projection of a session's published
+ * records (D1): attributions, evidence, coverage, and gaps. Nothing else. Baseline
+ * inventory and task grouping are deliberately outside this contract, so agreement
+ * on these four components is never whole-session parity.
+ *
+ * Pure and I/O-free: a function of already-parsed records, composing the existing
+ * public folds (`foldAttributions`, `foldEvidence`) rather than re-deriving them.
+ * DISPLAY-FOLD.md is the normative description; the hand-written corpus under
+ * contracts/display-fold/v1/ is its executable form.
+ */
+import { foldAttributions, foldEvidence } from "./attribution.js";
+export const DISPLAY_FOLD_CONTRACT = 'display-fold.v1';
+const ATTRIBUTION = 'slipstream.change.attribution.v1';
+const EVIDENCE = 'slipstream.harness.evidence.v1';
+const COVERAGE = 'slipstream.enrichment.coverage.v1';
+const GAP = 'slipstream.capture.gap.v1';
+/** A family this contract interprets, at any version — including a dotted suffix
+ * like `v1.0`, which must be refused as unsupported rather than silently treated
+ * as an unrelated, unknown type. Only an exact `1` is supported. */
+const CONSUMED_FAMILY = /^slipstream\.(?:file\.changed|change\.attribution|harness\.evidence|enrichment\.coverage|capture\.gap)\.v(.+)$/;
+const SEQ = /^[1-9][0-9]*$/;
+const HARNESSES = ['claude-code', 'codex'];
+const BASES = ['tool-start', 'tool-end', 'record-time'];
+const STATUSES = ['heuristic', 'ambiguous', 'unknown'];
+const ATTRIBUTION_REASONS = ['single-candidate', 'multiple-candidates', 'no-matching-evidence', 'observation-interval-unavailable'];
+const COVERAGE_STATES = ['pending', 'readable', 'degraded', 'unavailable'];
+const ISSUE_KINDS = ['missing', 'inaccessible', 'malformed', 'unsupported', 'discovery-limited'];
+const GAP_REASONS = ['coalesced', 'baseline-unreadable', 'watcher-error', 'restart', 'storage'];
+/** Exact string order by UTF-16 code units — never `localeCompare`, never normalized. */
+function compareStr(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Numeric order of canonical decimal strings of any length. */
+function compareSeq(a, b) {
+    return a.length - b.length || compareStr(a, b);
+}
+function compareIdentity(a, b) {
+    return compareStr(a.source, b.source) || compareSeq(a.seq, b.seq);
+}
+function compareStrings(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        const c = compareStr(a[i], b[i]);
+        if (c !== 0)
+            return c;
+    }
+    return 0;
+}
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function oneOf(v, values) {
+    return typeof v === 'string' && values.includes(v);
+}
+function isSeq(v) {
+    return typeof v === 'string' && SEQ.test(v);
+}
+function isEvidenceKey(v) {
+    return (isObj(v) && oneOf(v.harness, HARNESSES) && typeof v.harness_session_id === 'string' && typeof v.record_id === 'string');
+}
+/** Structural JSON-value equality: object key order is irrelevant, array order is not.
+ * Iterative, so a deeply nested field the fold never reads cannot overflow the stack. */
+function jsonEqual(a, b) {
+    const pending = [[a, b]];
+    for (let pair = pending.pop(); pair; pair = pending.pop()) {
+        const [x, y] = pair;
+        if (x === y)
+            continue;
+        if (Array.isArray(x)) {
+            if (!Array.isArray(y) || x.length !== y.length)
+                return false;
+            x.forEach((v, i) => pending.push([v, y[i]]));
+        }
+        else if (isObj(x) && isObj(y)) {
+            const keys = Object.keys(x);
+            if (keys.length !== Object.keys(y).length || !keys.every((k) => Object.hasOwn(y, k)))
+                return false;
+            for (const k of keys)
+                pending.push([x[k], y[k]]);
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+}
+function identityOf(r) {
+    if (!isObj(r) || typeof r.source !== 'string' || r.source === '' || !isSeq(r.seq))
+        return undefined;
+    return { source: r.source, seq: r.seq };
+}
+function attributionValid(d) {
+    return (isSeq(d.change_seq) &&
+        isSeq(d.policy_seq) &&
+        oneOf(d.status, STATUSES) &&
+        oneOf(d.reason, ATTRIBUTION_REASONS) &&
+        Array.isArray(d.evidence_seqs) &&
+        d.evidence_seqs.every(isSeq) &&
+        (d.excluded_conflicts === undefined || (Array.isArray(d.excluded_conflicts) && d.excluded_conflicts.every(isEvidenceKey))));
+}
+function evidenceProblem(d) {
+    const ts = d.timestamp;
+    const scope = d.file_scope;
+    const scopeValid = isObj(scope) &&
+        ((scope.kind === 'paths' && Array.isArray(scope.paths) && scope.paths.every((p) => typeof p === 'string')) ||
+            (scope.kind === 'unknown' && typeof scope.reason === 'string'));
+    if (!isEvidenceKey(d.evidence_key) ||
+        typeof d.tool_name !== 'string' ||
+        !isObj(ts) ||
+        !oneOf(ts.basis, BASES) ||
+        typeof ts.at_ms !== 'number' ||
+        !Number.isInteger(ts.at_ms) ||
+        !scopeValid) {
+        return 'invalid-record';
+    }
+    if (ts.at_ms < 0 || ts.at_ms > Number.MAX_SAFE_INTEGER)
+        return 'timestamp-out-of-range';
+    return undefined;
+}
+function coverageValid(d) {
+    return (oneOf(d.harness, HARNESSES) &&
+        oneOf(d.state, COVERAGE_STATES) &&
+        (d.issues === undefined ||
+            (Array.isArray(d.issues) && d.issues.every((i) => isObj(i) && oneOf(i.kind, ISSUE_KINDS) && typeof i.detail === 'string'))));
+}
+function gapValid(d) {
+    const scope = d.scope;
+    return (oneOf(d.reason, GAP_REASONS) &&
+        isObj(scope) &&
+        (scope.kind === 'session' || ((scope.kind === 'directory' || scope.kind === 'path') && typeof scope.path === 'string')) &&
+        (d.episode_id === undefined || typeof d.episode_id === 'string'));
+}
+/** What is wrong with an identified record, judged only on the fields this contract interprets. */
+function recordProblem(r) {
+    const { type, data } = r;
+    if (typeof type !== 'string' || !isObj(data))
+        return 'invalid-record';
+    switch (type) {
+        case ATTRIBUTION:
+            return attributionValid(data) ? undefined : 'invalid-record';
+        case EVIDENCE:
+            return evidenceProblem(data);
+        case COVERAGE:
+            return coverageValid(data) ? undefined : 'invalid-record';
+        case GAP:
+            return gapValid(data) ? undefined : 'invalid-record';
+        default:
+            return undefined;
+    }
+}
+function first(items, compare) {
+    return items.reduce((min, x) => (min === undefined || compare(x, min) < 0 ? x : min), undefined);
+}
+function projectKey(k) {
+    return { harness: k.harness, harness_session_id: k.harness_session_id, record_id: k.record_id };
+}
+function keyTuple(k) {
+    return [k.harness, k.harness_session_id, k.record_id];
+}
+function foldAttributionRows(records) {
+    const rows = [];
+    for (const { seq, source, data } of foldAttributions(records).values()) {
+        const row = {
+            source,
+            change_seq: data.change_seq,
+            attribution_seq: seq.toString(),
+            policy_seq: data.policy_seq,
+            status: data.status,
+            reason: data.reason,
+            evidence_seqs: [...data.evidence_seqs].sort(compareSeq),
+        };
+        if (data.excluded_conflicts !== undefined) {
+            row.excluded_conflicts = data.excluded_conflicts
+                .map((k) => projectKey(k))
+                .sort((a, b) => compareStrings(keyTuple(a), keyTuple(b)));
+        }
+        rows.push(row);
+    }
+    return rows.sort((a, b) => compareStr(a.source, b.source) || compareSeq(a.change_seq, b.change_seq));
+}
+/** Evidence is folded per source (D8): the same evidence key in two sessions is two invocations. */
+function foldEvidenceRows(records) {
+    const bySource = new Map();
+    for (const r of records) {
+        if (r.type !== EVIDENCE)
+            continue;
+        const group = bySource.get(r.source);
+        if (group)
+            group.push(r);
+        else
+            bySource.set(r.source, [r]);
+    }
+    const rows = [];
+    for (const [source, group] of bySource) {
+        for (const inv of foldEvidence(group).values()) {
+            rows.push({
+                source,
+                ...projectKey(inv.key),
+                evidence_seqs: inv.evidenceSeqs.map(String),
+                min_at_ms: inv.minAtMs,
+                max_at_ms: inv.maxAtMs,
+                known_paths: [...inv.knownPaths],
+                conflicted: inv.conflicted,
+            });
+        }
+    }
+    return rows.sort((a, b) => compareStrings([a.source, ...keyTuple(a)], [b.source, ...keyTuple(b)]));
+}
+/** Highest seq per `(source, harness)` replaces wholesale. No record means health is unknown — no row. */
+function foldCoverageRows(records) {
+    const latest = new Map();
+    for (const r of records) {
+        if (r.type !== COVERAGE)
+            continue;
+        const k = JSON.stringify([r.source, r.data.harness]);
+        const cur = latest.get(k);
+        if (!cur || compareSeq(r.seq, cur.seq) > 0)
+            latest.set(k, r);
+    }
+    const rows = [];
+    for (const { source, seq, data } of latest.values()) {
+        const row = { source, harness: data.harness, seq, state: data.state };
+        if (data.issues !== undefined) {
+            row.issues = data.issues
+                .map((i) => ({ kind: i.kind, detail: i.detail }))
+                .sort((a, b) => compareStrings([a.kind, a.detail], [b.kind, b.detail]));
+        }
+        rows.push(row);
+    }
+    return rows.sort((a, b) => compareStrings([a.source, a.harness], [b.source, b.harness]));
+}
+/** Published gaps only, as recorded — never inferred, healed, or scored. */
+function foldGapRows(records) {
+    const rows = [];
+    for (const { source, seq, type, data } of records) {
+        if (type !== GAP)
+            continue;
+        const scope = data.scope;
+        const row = {
+            source,
+            seq,
+            reason: data.reason,
+            scope: scope.kind === 'session' ? { kind: 'session' } : { kind: scope.kind, path: scope.path },
+        };
+        if (data.episode_id !== undefined)
+            row.episode_id = data.episode_id;
+        rows.push(row);
+    }
+    return rows.sort(compareIdentity);
+}
+/**
+ * Fold parsed records into the canonical display state, or refuse with a
+ * distinguishable reason. A refusal carries no state: a partial fold is never
+ * presented as good. Precedence is invalid > corrupt > unsupported, and within a
+ * class the smallest `(source, seq)` is reported, so the result never depends on
+ * delivery order.
+ */
+export function foldDisplay(records) {
+    let unidentified = false;
+    const invalid = [];
+    const conflicts = [];
+    const seen = new Map();
+    const unique = [];
+    for (const r of records) {
+        const id = identityOf(r);
+        if (!id) {
+            unidentified = true;
+            continue;
+        }
+        const problem = recordProblem(r);
+        if (problem)
+            invalid.push({ ...id, reason: problem });
+        const k = JSON.stringify([id.source, id.seq]);
+        if (!seen.has(k)) {
+            seen.set(k, r);
+            if (!problem)
+                unique.push(r);
+        }
+        else if (!jsonEqual(seen.get(k), r)) {
+            conflicts.push(id);
+        }
+    }
+    const contract = DISPLAY_FOLD_CONTRACT;
+    if (unidentified)
+        return { contract, result: 'invalid', error: { reason: 'invalid-record' } };
+    const bad = first(invalid, (a, b) => compareIdentity(a, b) || compareStr(a.reason, b.reason));
+    if (bad)
+        return { contract, result: 'invalid', error: { reason: bad.reason, source: bad.source, seq: bad.seq } };
+    const conflict = first(conflicts, compareIdentity);
+    if (conflict)
+        return { contract, result: 'corrupt', error: { reason: 'conflicting-records', ...conflict } };
+    const unsupported = first(unique.filter((r) => {
+        const version = CONSUMED_FAMILY.exec(r.type)?.[1];
+        return version !== undefined && version !== '1';
+    }), compareIdentity);
+    if (unsupported) {
+        const { source, seq, type } = unsupported;
+        return { contract, result: 'unsupported', error: { reason: 'unsupported-event-version', source, seq, type } };
+    }
+    return {
+        contract,
+        result: 'ok',
+        state: {
+            attributions: foldAttributionRows(unique),
+            evidence: foldEvidenceRows(unique),
+            coverage: foldCoverageRows(unique),
+            gaps: foldGapRows(unique),
+        },
+    };
+}
+/**
+ * Canonical serialization: object keys sorted by UTF-16 code units, array order
+ * kept, no whitespace, `JSON.stringify` string escaping (lone surrogates escaped),
+ * numbers only as safe integers. Anything else is a caller bug and throws rather
+ * than being coerced.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value))
+            throw new TypeError(`canonicalJson: ${value} is not a safe integer`);
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+    if (isObj(value)) {
+        const keys = Object.keys(value).sort(compareStr);
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+    }
+    throw new TypeError(`canonicalJson: unsupported ${typeof value}`);
+}

package/dist/engine.js

@@ -0,0 +1,112 @@
+import { sep } from 'node:path';
+import { snapshotsEqual } from "./snapshot.js";
+/**
+ * Per-path serialized capture. Each path compares the freshly-read snapshot
+ * against the *last committed* snapshot — never against whatever is on disk
+ * when the read runs — so racing writes cannot corrupt the recorded `before`.
+ * Notifies arriving while a path is being processed coalesce into a single
+ * follow-up cycle; a state skipped that way is surfaced as a capture gap.
+ */
+export function createEngine({ reader, log, now = Date.now }) {
+    const committed = new Map();
+    const pending = new Map(); // path -> earliest observed_at_ms
+    const coalesced = new Set();
+    const processing = new Set();
+    const inflight = new Set();
+    const baselineUnknown = new Set(); // dirs whose baseline scan failed
+    const setBaseline = (path, snapshot) => {
+        committed.set(path, snapshot);
+    };
+    const markBaselineUnknown = (relDir) => {
+        baselineUnknown.add(relDir);
+    };
+    // The prior state of a path we never baselined is honestly unknown when its
+    // directory could not be scanned; elsewhere, no baseline means it did not
+    // exist yet.
+    const priorFor = (path) => {
+        for (const prefix of baselineUnknown) {
+            if (prefix === '' || path === prefix || path.startsWith(prefix + sep)) {
+                return { kind: 'unavailable', reason: 'baseline-unknown' };
+            }
+        }
+        return { kind: 'absent' };
+    };
+    const notify = (path, observedAtMs) => {
+        const prior = pending.get(path);
+        pending.set(path, prior === undefined ? observedAtMs : Math.min(prior, observedAtMs));
+        if (processing.has(path)) {
+            coalesced.add(path); // a notify landed while this path was being read
+            return;
+        }
+        processing.add(path);
+        // A processing failure (e.g. the log poisoned itself after a write error)
+        // must be surfaced, never left as an unhandled rejection that crashes the
+        // watcher. The log's own failure is the durable signal; this is the console.
+        const task = processLoop(path)
+            .catch((err) => {
+            console.error(`slipstream: capture processing error for ${path}: ${err.message}`);
+        })
+            .finally(() => inflight.delete(task));
+        inflight.add(task);
+    };
+    const handleOnce = async (path, observedAtMs, wasCoalesced) => {
+        const after = await reader.read(path);
+        // Close the observation interval the instant acquisition finishes. A regressed
+        // clock (end < start) is recorded truthfully, never clamped into a fabricated
+        // interval — interpretation handles the inversion, capture does not lie.
+        const endMs = now();
+        const before = committed.get(path) ?? priorFor(path);
+        if (snapshotsEqual(before, after)) {
+            // Nothing to record — but if we coalesced, an intermediate state may have
+            // existed and been lost. Surface that honestly rather than silently.
+            if (wasCoalesced) {
+                await log.append({
+                    type: 'slipstream.capture.gap.v1',
+                    occurred_at_ms: observedAtMs,
+                    data: { scope: { kind: 'path', path }, reason: 'coalesced' },
+                });
+            }
+            return;
+        }
+        await log.append({
+            type: 'slipstream.file.changed.v1',
+            occurred_at_ms: observedAtMs,
+            data: {
+                path,
+                before,
+                after,
+                observation: 'watcher',
+                coalesced: wasCoalesced,
+                observed_interval_ms: { start_ms: observedAtMs, end_ms: endMs },
+            },
+        });
+        committed.set(path, after);
+    };
+    const processLoop = async (path) => {
+        try {
+            // No `await` may sit between the emptiness check and processing.delete
+            // below, or a concurrent notify could be dropped. Both are synchronous.
+            for (;;) {
+                const observedAtMs = pending.get(path);
+                if (observedAtMs === undefined)
+                    break;
+                pending.delete(path);
+                const wasCoalesced = coalesced.delete(path);
+                await handleOnce(path, observedAtMs, wasCoalesced);
+            }
+        }
+        finally {
+            processing.delete(path);
+        }
+    };
+    const drain = async () => {
+        while (inflight.size > 0) {
+            await Promise.all([...inflight]);
+        }
+    };
+    const resetNotifications = () => {
+        pending.clear();
+        coalesced.clear();
+    };
+    return { setBaseline, markBaselineUnknown, notify, drain, resetNotifications };
+}

package/dist/entrypoint.js

@@ -0,0 +1,17 @@
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+/**
+ * True when this module is the process entrypoint (run directly), false when it
+ * is merely imported. Node's ESM loader resolves symlinks for `import.meta.url`,
+ * but `process.argv[1]` keeps the path exactly as invoked — so a symlinked or
+ * `npm link`-ed launcher must be realpath'd before comparing, or the guard
+ * wrongly decides "imported" and the program silently does nothing.
+ */
+export function isMainModule(moduleUrl, argvPath) {
+    try {
+        return moduleUrl === pathToFileURL(realpathSync(argvPath)).href;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/event.js

@@ -0,0 +1,79 @@
+/**
+ * The event schema is Slipstream's public interface (CLAUDE.md). Every record in
+ * `events.jsonl` is one CloudEvents 1.0 structured JSON object per line. We use
+ * the envelope directly — no SDK — and keep Slipstream-specific fields in `data`.
+ *
+ * Freeze rules for v1 (see schemas/):
+ * - `seq` is a contiguous per-session decimal string ("1", "2", ...) expressing
+ *   commit order. `id` equals `seq` — CloudEvents identity is (source, id), so a
+ *   second UUID adds nothing.
+ * - The version lives in `type` (`slipstream.<name>.v1`), never in `specversion`
+ *   (which versions CloudEvents itself).
+ * - `time` is the observation/occurrence instant (RFC3339, ms precision). It is
+ *   never used for ordering — `seq` is. It is not durable-completion time.
+ * - `session_id` lives inside `data`, not as a top-level extension attribute:
+ *   CloudEvents extension names cannot contain underscores.
+ * - Forward compatibility is a contract, not just syntax: consumers ignore
+ *   unknown `data` fields and unknown event types (while still advancing their
+ *   seq cursor), and v1 fields never change meaning. `task_hint_id` arrives as
+ *   an optional additive `data` field on `file.changed` — no version bump.
+ * - `subject` is the one CloudEvents envelope attribute Slipstream sets: the
+ *   task declaration `slipstream.task.started.v1` carries `subject: "task/<id>"`
+ *   (ruling D2). It is optional and absent on every other event type.
+ */
+export const SPEC_VERSION = '1.0';
+export const DATA_CONTENT_TYPE = 'application/json';
+export const SOURCE_PREFIX = 'urn:slipstream:session:';
+export function sourceFor(sessionId) {
+    return `${SOURCE_PREFIX}${sessionId}`;
+}
+export const EVENT_TYPES = [
+    'slipstream.session.started.v1',
+    'slipstream.file.baselined.v1',
+    'slipstream.capture.baseline.completed.v1',
+    'slipstream.file.changed.v1',
+    'slipstream.capture.gap.v1',
+    'slipstream.session.resumed.v1',
+    'slipstream.task.started.v1',
+    'slipstream.harness.evidence.v1',
+    'slipstream.change.attribution.v1',
+    'slipstream.enrichment.configured.v1',
+    'slipstream.enrichment.coverage.v1',
+];
+/** The `data` field into which each type mirrors the observation instant (epoch
+ * ms). Types absent here carry only the envelope `time` (baseline records are
+ * attach-time bookkeeping, not observations of an instant). */
+const AT_MS_FIELD = {
+    'slipstream.session.started.v1': 'started_at_ms',
+    'slipstream.file.changed.v1': 'observed_at_ms',
+    'slipstream.capture.gap.v1': 'observed_at_ms',
+    'slipstream.session.resumed.v1': 'resumed_at_ms',
+};
+/**
+ * Build the full CloudEvents envelope for an input at a given sequence and
+ * session. Pure: no I/O, no clock — `seq` and time are supplied by the caller
+ * (the log), so ordering and timestamps are never invented here.
+ */
+export function buildEnvelope(input, seq, sessionId) {
+    const seqStr = seq.toString();
+    const atMsField = AT_MS_FIELD[input.type];
+    // The only envelope `subject` Slipstream sets (ruling D2): a task declaration
+    // is subject `task/<task_id>`. Every other event omits it — an absent field,
+    // never an empty string.
+    const subject = input.type === 'slipstream.task.started.v1' ? `task/${input.data.task_id}` : undefined;
+    return {
+        specversion: SPEC_VERSION,
+        id: seqStr,
+        source: sourceFor(sessionId),
+        type: input.type,
+        datacontenttype: DATA_CONTENT_TYPE,
+        seq: seqStr,
+        time: new Date(input.occurred_at_ms).toISOString(),
+        ...(subject !== undefined ? { subject } : {}),
+        data: {
+            session_id: sessionId,
+            ...input.data,
+            ...(atMsField ? { [atMsField]: input.occurred_at_ms } : {}),
+        },
+    };
+}

package/dist/evidence-ingest.js

@@ -0,0 +1,60 @@
+import { evidenceKeyString, variantSignature } from "./attribution.js";
+const DEFAULT_MAX_PENDING = 256;
+const DEFAULT_MAX_QUEUED_BYTES = 1024 * 1024;
+const EVIDENCE = 'slipstream.harness.evidence.v1';
+export function createEvidenceIngestor(opts) {
+    const { append, now } = opts;
+    const maxPending = opts.maxPending ?? DEFAULT_MAX_PENDING;
+    const maxQueuedBytes = opts.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
+    // key -> the variant signatures already durable under it.
+    const committed = new Map();
+    let tail = Promise.resolve();
+    let pending = 0;
+    let queuedBytes = 0;
+    const record = (keyStr, sig) => {
+        let set = committed.get(keyStr);
+        if (!set) {
+            set = new Set();
+            committed.set(keyStr, set);
+        }
+        set.add(sig);
+    };
+    const seed = (events) => {
+        for (const e of events) {
+            if (e.type !== EVIDENCE)
+                continue;
+            record(evidenceKeyString(e.data.evidence_key), variantSignature(e.data));
+        }
+    };
+    // Runs one at a time (serialized by the tail), so the committed index is
+    // guaranteed to reflect every earlier append: this check cannot race.
+    const doIngest = async (evidence) => {
+        const keyStr = evidenceKeyString(evidence.evidence_key);
+        const sig = variantSignature(evidence);
+        if (committed.get(keyStr)?.has(sig))
+            return { status: 'duplicate' };
+        const event = await append({ type: EVIDENCE, occurred_at_ms: now(), data: evidence });
+        record(keyStr, sig);
+        return { status: 'appended', seq: BigInt(event.seq) };
+    };
+    const ingest = (caller) => {
+        // Snapshot at the boundary: the caller may mutate its object after we return,
+        // but the record we persist (and mirror in memory) must be the fact as ingested.
+        const evidence = structuredClone(caller);
+        // Admission is synchronous: no `await` sits between the bound check and the
+        // reservation, so concurrent callers can never collectively over-admit.
+        const size = Buffer.byteLength(JSON.stringify(evidence));
+        if (pending + 1 > maxPending || queuedBytes + size > maxQueuedBytes) {
+            return Promise.resolve({ status: 'rejected', reason: 'queue-full', retryable: true });
+        }
+        pending += 1;
+        queuedBytes += size;
+        const result = tail.then(() => doIngest(evidence));
+        tail = result.catch(() => undefined); // keep the chain alive past a failed append
+        return result.finally(() => {
+            pending -= 1;
+            queuedBytes -= size;
+        });
+    };
+    return { ingest, seed };
+}

package/dist/harness-context/claude.js

@@ -0,0 +1,42 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+/**
+ * Claude Code identity adapter (fail-closed).
+ *
+ * Per the SC3 probe (tools/identity-probe/FINDINGS.md): Claude Code exposes a
+ * FRESH `CLAUDE_CODE_SESSION_ID` (a real UUID) plus `CLAUDE_PROJECT_DIR` in the
+ * subprocess environment at `initialize` — before any tool declaration — and the
+ * tool-call `_meta` carries NO identity. So the binding is the env triple,
+ * observed once and cached; a session without both vars fails closed on every
+ * call rather than guessing from cwd/PID.
+ *
+ * The worktree is canonicalized with the SAME realpath policy the daemon applies
+ * at attach, so a symlinked project dir reports the durable root the daemon stored
+ * (idempotent — the daemon re-canonicalizes defensively). realpath runs
+ * synchronously here: this is a one-shot capture at subprocess startup.
+ */
+export function claudeIdentity(env) {
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        return { unresolved: 'CLAUDE_CODE_SESSION_ID is absent from the environment' };
+    }
+    const projectDir = env.CLAUDE_PROJECT_DIR;
+    if (typeof projectDir !== 'string' || projectDir.length === 0) {
+        return { unresolved: 'CLAUDE_PROJECT_DIR is absent from the environment' };
+    }
+    // A relative project dir would be resolved against the forwarder's CWD, which is
+    // never a binding input; require an absolute path and fail closed otherwise.
+    if (!isAbsolute(projectDir)) {
+        return { unresolved: `CLAUDE_PROJECT_DIR ${projectDir} is not an absolute path` };
+    }
+    let worktree = projectDir;
+    try {
+        worktree = realpathSync(projectDir);
+    }
+    catch {
+        // The path does not resolve on this host; send the raw value. The daemon
+        // re-canonicalizes and compares, so an unresolvable path simply fails to match
+        // rather than being silently accepted — no honesty loss here.
+    }
+    return { harness: 'claude-code', harness_session_id: sessionId, worktree };
+}