@fusengine/harness 0.1.80 → 0.1.83

package/dist/store-Dw08Amqh.mjs

@@ -0,0 +1,845 @@
+import { c as ttlLabel } from "./dotenv-DoqNlALG.mjs";
+import { n as fuseHarnessHome } from "./home-state-oUGFB4ds.mjs";
+import { a as writeJsonFile, i as readJsonFile, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
+import { i as resolveSessions } from "./doc-helpers-CWZegVdR.mjs";
+import { t as routeReferences } from "./router-PKVNBHge.mjs";
+import { t as resolveSkillPath } from "./skill-path-DhBGlQe3.mjs";
+import { dirname, join } from "node:path";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHmac, randomBytes } from "node:crypto";
+//#region src/policy/skill-source.ts
+/**
+* Framework -> SKILL.md doc source for the APEX Check-1 non-routed deny —
+* parity with the Python plugin's enforce-helpers.ts `getSkillSource()`
+* (10-entry map, fallback "mcp__context7__query-docs"). The map is ported
+* faithfully as skill NAMES only: disk paths are resolved DYNAMICALLY via
+* {@link resolveSkillPath} (proprietary rule — no static path table; installed
+* plugin dir names differ from upstream's `react-expert/...`, and a hardcoded
+* table drifts from what is actually installed).
+*/
+/**
+* Fallback doc source when no SKILL.md can be promised: the consigne to query
+* context7 (a TOOL name, not a path) — parity enforce-helpers.ts:51.
+*/
+const CONTEXT7_SOURCE = "mcp__context7__query-docs";
+/**
+* Framework -> sub-skill dir name, faithful to the Python
+* `getSkillSource` map (enforce-helpers.ts:39-50, all 10 entries).
+*/
+const SKILL_NAMES = {
+	react: "react-19",
+	nextjs: "nextjs-16",
+	swift: "swiftui-components",
+	laravel: "laravel-eloquent",
+	tailwind: "tailwindcss-v4",
+	generic: "solid-generic",
+	java: "solid-java",
+	go: "solid-go",
+	ruby: "solid-ruby",
+	rust: "solid-rust"
+};
+/**
+* The doc source a Check-1 deny may promise for `framework` (parity
+* `getSkillSource`): the REAL installed SKILL.md absolute path when it exists
+* on disk, else {@link CONTEXT7_SOURCE}. `resolveSkillPath` returns a
+* `/SKILL.md`-suffixed path ONLY on an `existsSync` hit; its
+* `${PLUGINS_DIR}/<name>` not-found fallback (no marketplace installed, or a
+* mapped skill absent on disk — e.g. upstream's `swiftui-components`) is
+* converted to the context7 consigne here, because a deny must never promise
+* a nonexistent path (every option a deny offers must actually unblock).
+* @param framework - Detected framework (the `detectFramework()` domain).
+* @param pluginsDirOverride - Marketplace plugins dir override (tests).
+*/
+function getSkillSource(framework, pluginsDirOverride) {
+	const name = SKILL_NAMES[framework];
+	if (!name) return CONTEXT7_SOURCE;
+	const path = resolveSkillPath(name, pluginsDirOverride);
+	return path.endsWith("/SKILL.md") ? path : CONTEXT7_SOURCE;
+}
+//#endregion
+//#region src/policy/apex-authorization.ts
+/**
+* Credit a doc consultation onto one framework's auth entry (parity
+* track-doc-consultation.py): the once-per-session Check-2 fields
+* (`doc_sessions` + `sources`) plus the per-framework Check-1 stamp
+* (`sessions` + `doc_consulted`). Pure.
+*/
+function creditDocConsultation(prev, sessionId, source, nowIso) {
+	const p = prev ?? {};
+	const add = (list, v) => v && !list.includes(v) ? [...list, v] : list;
+	return {
+		...p,
+		sessions: add(resolveSessions(p), sessionId),
+		doc_sessions: add(p.doc_sessions ?? [], sessionId),
+		sources: add(p.sources ?? (p.source ? [p.source] : []), source),
+		doc_consulted: nowIso
+	};
+}
+/**
+* Check 1 (parity enforce-apex-phases.ts isAuthorized): the framework's doc or
+* skill was consulted in THIS session (resolveSessions) AND the stamp is
+* younger than the TTL (FUSE_ENFORCE_TTL_SEC via src/config/ttl.ts).
+*/
+function isAuthorized(auth, sessionId, now, ttlMs) {
+	if (!auth?.doc_consulted || !resolveSessions(auth).includes(sessionId)) return false;
+	const readEpoch = Date.parse(auth.doc_consulted);
+	return !Number.isNaN(readEpoch) && now - readEpoch < ttlMs;
+}
+/**
+* A fresh same-session `skills/**.md` read whose path names the framework also
+* satisfies Check 1 (parity track-doc-consultation.py, which stamps
+* `doc_consulted` on `skills/.*\.md` Reads; the harness records those Reads in
+* `refsRead`/`refsReadAt` instead, and the track file is per-session).
+*/
+function skillReadAuthorized(ctx, now, ttlMs) {
+	const nameRe = new RegExp(`\\b(${{
+		laravel: "laravel|php",
+		tailwind: "tailwindcss?"
+	}[ctx.framework] ?? ctx.framework})\\b`, "i");
+	return (ctx.refsRead ?? []).some((p) => {
+		if (!/skills\/.*\.md$/i.test(p) || !nameRe.test(p)) return false;
+		const at = ctx.refsReadAt?.[p];
+		return at !== void 0 && now - at < ttlMs;
+	});
+}
+/**
+* Gate (Check 1): deny until the framework's doc/skill is freshly consulted.
+* The deny lists the routed SOLID refs when refs are loaded (parity
+* formatRoutedDeny), else the framework's skill source (parity getSkillSource:
+* a real installed SKILL.md path, or the context7 consigne). The RUNTIME
+* caller persists `state.target` on deny (recordTarget, parity :80-81) so
+* recordDoc can cross-credit this framework on the next doc consultation.
+*/
+const apexAuthorizationGate = (ctx) => {
+	const windowMs = ctx.windowMs ?? 120 * 1e3;
+	const now = ctx.now ?? Date.now();
+	if (isAuthorized(ctx.authorizations?.[ctx.framework], ctx.sessionId, now, windowMs)) return null;
+	if (skillReadAuthorized(ctx, now, windowMs)) return null;
+	const ttl = ttlLabel(Math.round(windowMs / 1e3));
+	const title = `APEX: ${ctx.framework} documentation required`;
+	const routed = ctx.refs?.length ? routeReferences(ctx.refs, ctx.filePath, ctx.content) : null;
+	if (!routed) {
+		const src = getSkillSource(ctx.framework);
+		return {
+			kind: "block",
+			title,
+			reason: `APEX: Read doc first (expires every ${ttl}) for ${ctx.framework}! Source: ${src}`,
+			actions: [src === "mcp__context7__query-docs" ? `Query ${CONTEXT7_SOURCE} for ${ctx.framework} docs` : `Read ${src}`]
+		};
+	}
+	const optional = routed.optional.map((r) => r.meta.filePath);
+	return {
+		kind: "block",
+		title,
+		reason: [
+			`APEX: Read ALL SOLID references below (including Optional), then retry (expires every ${ttl}) for ${ctx.framework}.`,
+			`Editing: ${ctx.filePath}`,
+			...optional.length ? [`Optional: ${optional.join(", ")}`] : [],
+			`Full skill: ${routed.skillPath}`
+		].join("\n"),
+		actions: routed.required.map((r) => r.meta.filePath)
+	};
+};
+//#endregion
+//#region src/tracking/session-state.ts
+/** A fresh, empty track. */
+function emptyTrack() {
+	return {
+		authorizations: {},
+		refsRead: [],
+		agents: [],
+		trivialEdits: []
+	};
+}
+/**
+* Record a doc consultation (Context7/Exa/web) for a framework in this session:
+* the Check-2 credit (`doc_sessions` + `sources`) plus the Check-1 stamp
+* (`sessions` + `doc_consulted` = ISO of `now`). PARITY track-doc-consultation.py
+* :62-70 — a `target` left by a Check-1 deny (enforce-apex-phases.ts:80) is
+* cross-credited on EVERY consultation, with NO TTL on `target.set_at`, and the
+* target PERSISTS (only the next deny replaces it via {@link recordTarget});
+* single-shot clearing or TTL-gating the target re-opened the deny loop when a
+* consultation landed > TTL after the deny. Immutable.
+*/
+function recordDoc(track, framework, sessionId, source, now = Date.now()) {
+	const nowIso = new Date(now).toISOString();
+	const authorizations = {
+		...track.authorizations,
+		[framework]: creditDocConsultation(track.authorizations[framework], sessionId, source, nowIso)
+	};
+	const t = track.target;
+	if (t && t.framework !== framework) authorizations[t.framework] = creditDocConsultation(track.authorizations[t.framework], sessionId, source, nowIso);
+	return {
+		...track,
+		authorizations
+	};
+}
+/** Set the pending doc-credit target (written by the runtime on a Check-1 deny). Immutable. */
+function recordTarget(track, target) {
+	return {
+		...track,
+		target
+	};
+}
+/**
+* Record that a SOLID reference file was read (deduped). Immutable. When `now`
+* (epoch ms — the tool event's own timestamp, never a fresh `Date.now()`) is
+* supplied, the read is stamped in `refsReadAt`, refreshed on re-reads so the
+* LATEST read drives the SOLID TTL (parity track-solid-reads.py, which appends
+* a timestamped entry per read; require-solid-read.py checks the most recent).
+* Callers that omit `now` keep the legacy untimestamped behavior.
+*/
+function recordRefRead(track, path, now) {
+	const refsRead = track.refsRead.includes(path) ? track.refsRead : [...track.refsRead, path];
+	if (now === void 0) return refsRead === track.refsRead ? track : {
+		...track,
+		refsRead
+	};
+	return {
+		...track,
+		refsRead,
+		refsReadAt: {
+			...track.refsReadAt,
+			[path]: now
+		}
+	};
+}
+/** Record an agent/tool call with a timestamp + optional quality. Immutable. */
+function recordAgent(track, name, ts, quality) {
+	const entry = quality ? {
+		name,
+		ts,
+		quality
+	} : {
+		name,
+		ts
+	};
+	return {
+		...track,
+		agents: [...track.agents, entry]
+	};
+}
+/** True when ALL of `names` ran within `windowMs` with non-insufficient quality. */
+function agentsFresh(track, names, windowMs, now) {
+	const cutoff = now - windowMs;
+	return names.every((n) => track.agents.some((a) => a.name === n && a.ts > cutoff && a.quality !== "insufficient"));
+}
+/** Record a trivial edit timestamp (sliding window; old evicted). Immutable. */
+function recordTrivialEdit(track, ts, windowMs, now) {
+	const cutoff = now - windowMs;
+	return {
+		...track,
+		trivialEdits: [...(track.trivialEdits ?? []).filter((t) => t > cutoff), ts]
+	};
+}
+/** Count trivial edits within the sliding window. */
+function trivialCount(track, windowMs, now) {
+	const cutoff = now - windowMs;
+	return (track.trivialEdits ?? []).filter((t) => t > cutoff).length;
+}
+/** Set the brainstorm-required flag (from creation-intent detection). Immutable. */
+function recordBrainstormRequired(track, required) {
+	return {
+		...track,
+		brainstormRequired: required
+	};
+}
+//#endregion
+//#region src/tracking/integrity.ts
+/**
+* @module integrity
+* HMAC-SHA256 tamper-evident wrapping for {@link SessionTrack}.
+*
+* Failure policy: ONLY a MAC mismatch causes fail-closed (returns null).
+* The nonce is included in the signed payload and written to disk for advisory
+* diagnostics, but is NOT checked during verification — concurrent hook
+* invocations (PostToolUse, SubagentStop, …) legitimately load the same
+* envelope after the nonce watermark advances; a monotonic check would trigger
+* spurious fail-closed behaviour mid-session.
+*
+* The machine key is readable by the same agent process, so this deters naive
+* out-of-band tampering — not a determined re-sign. Item B (transcript-grounded
+* freshness) is the primary guarantee.
+* @packageDocumentation
+*/
+const HARNESS_DIR = fuseHarnessHome();
+const KEY_PATH = join(HARNESS_DIR, ".key");
+const NONCE_PATH = join(HARNESS_DIR, ".nonce");
+/** Load (or create on first use) the per-machine HMAC key stored at mode 0600. */
+function loadOrCreateKey() {
+	mkdirSync(HARNESS_DIR, { recursive: true });
+	if (existsSync(KEY_PATH)) return readFileSync(KEY_PATH, "utf8").trim();
+	const candidate = randomBytes(32).toString("hex");
+	try {
+		writeFileSync(KEY_PATH, candidate, {
+			encoding: "utf8",
+			mode: 384,
+			flag: "wx"
+		});
+		return candidate;
+	} catch (e) {
+		if (e.code !== "EEXIST") throw e;
+	}
+	for (let i = 0; i < 5; i++) {
+		const existing = readFileSync(KEY_PATH, "utf8").trim();
+		if (existing) return existing;
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+	}
+	const key = readFileSync(KEY_PATH, "utf8").trim();
+	if (!key) throw new Error("fuse: empty .key after write contention");
+	return key;
+}
+/**
+* Persist the last-seen nonce for advisory diagnostics (mode 0600).
+* Never read during {@link verifyTrack} — see module JSDoc for rationale.
+*/
+function writeLastNonce(nonce) {
+	mkdirSync(HARNESS_DIR, { recursive: true });
+	writeFileSync(NONCE_PATH, String(nonce), {
+		encoding: "utf8",
+		mode: 384
+	});
+}
+/** Compute HMAC-SHA256 over `"${nonce}:${data}"` (nonce: envelope number or journal per-line string). */
+function computeMac(key, data, nonce) {
+	return createHmac("sha256", key).update(`${nonce}:${data}`).digest("hex");
+}
+/**
+* Sign a {@link SessionTrack} into a tamper-evident envelope. The nonce
+* (`Date.now()`) is embedded in the MAC to bind the timestamp to the payload.
+*/
+function signTrack(track) {
+	const key = loadOrCreateKey();
+	const data = JSON.stringify(track);
+	const nonce = Date.now();
+	return {
+		data,
+		nonce,
+		mac: computeMac(key, data, nonce)
+	};
+}
+/**
+* Verify a {@link TrackEnvelope}. Returns the parsed {@link SessionTrack} on
+* success, or `null` ONLY on MAC mismatch / parse failure (fail-closed on
+* tampering). The nonce is NOT checked — see module JSDoc.
+*/
+function verifyTrack(envelope) {
+	try {
+		const key = loadOrCreateKey();
+		if (envelope.mac !== computeMac(key, envelope.data, envelope.nonce)) return null;
+		return JSON.parse(envelope.data);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/tracking/track-lock.ts
+/**
+* Cross-process lock for session-track read-modify-write. The ~11-hook
+* fan-out races plain `loadTrack → mutate → saveTrack` (writes silently
+* lost — `refsRead` was the only mitigated channel, via its journal). This
+* lockfile (`wx`, atomic create) serializes the whole RMW:
+* - retry is bounded in TOTAL time (400 ms, far under any hook timeout);
+* - after the budget, NEVER crash: stderr is logged and the caller skips the
+*   write — a named lost write beats a fail-open crash (hook fail-open
+*   semantics preserved);
+* - an orphaned lockfile (dead process) is reclaimed after a 10 s TTL, so a
+*   crash mid-write never blocks a project forever.
+*/
+/** Orphaned lockfile lifetime before reclamation. */
+const LOCK_TTL_MS = 1e4;
+/** Delay between two lock acquisition attempts. */
+const RETRY_STEP_MS = 8;
+/** Sentinel returned by {@link withTrackLock} when the lock could not be taken. */
+const LOCK_FAILED = Symbol("track-lock-failed");
+/** True when the lockfile is older than the TTL (orphaned by a dead process). */
+function isStale$1(lock) {
+	try {
+		return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS;
+	} catch {
+		return false;
+	}
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* Run `fn` under the track lock of `dir`, or skip with a stderr note.
+* @param dir - The track state directory (lockfile lives inside).
+* @param fn - The protected read-modify-write.
+* @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
+*/
+async function withTrackLock(dir, fn) {
+	mkdirSync(dir, { recursive: true });
+	const lock = join(dir, "track.lock");
+	const deadline = Date.now() + 400;
+	for (;;) try {
+		closeSync(openSync(lock, "wx"));
+		break;
+	} catch {
+		if (isStale$1(lock)) {
+			try {
+				unlinkSync(lock);
+			} catch {}
+			continue;
+		}
+		if (Date.now() >= deadline) {
+			process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
+			return LOCK_FAILED;
+		}
+		await sleep(RETRY_STEP_MS);
+	}
+	try {
+		return await fn();
+	} finally {
+		try {
+			unlinkSync(lock);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/tracking/track-lock-sync.ts
+/**
+* Synchronous twin of {@link withTrackLock} for lifecycle paths that CANNOT
+* float async work (the SubagentStop dispatch runs synchronously in a
+* short-lived hook process — an async write could be dropped before exit,
+* see `evidence-harvest-io.ts`). Same semantics: `wx` lockfile, bounded total
+* retry, named skipped write on contention, stale reclamation. The wait uses
+* `Atomics.wait` (allowed on the main thread in both Node and Bun).
+*/
+/** Block the thread for `ms` (bounded by the caller's total budget). */
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** True when the lockfile is older than the TTL (orphaned by a dead process). */
+function isStale(lock) {
+	try {
+		return Date.now() - statSync(lock).mtimeMs > LOCK_TTL_MS;
+	} catch {
+		return false;
+	}
+}
+/**
+* Run `fn` under the track lock of `dir`, synchronously.
+* @param dir - The track state directory (lockfile lives inside).
+* @param fn - The protected read-modify-write.
+* @returns `fn`'s result, or {@link LOCK_FAILED} when the lock stayed busy.
+*/
+function withTrackLockSync(dir, fn) {
+	mkdirSync(dir, { recursive: true });
+	const lock = join(dir, "track.lock");
+	const deadline = Date.now() + 400;
+	for (;;) try {
+		closeSync(openSync(lock, "wx"));
+		break;
+	} catch {
+		if (isStale(lock)) {
+			try {
+				unlinkSync(lock);
+			} catch {}
+			continue;
+		}
+		if (Date.now() >= deadline) {
+			process.stderr.write(`harness: track lock busy, write skipped (${lock})\n`);
+			return LOCK_FAILED;
+		}
+		sleepSync(8);
+	}
+	try {
+		return fn();
+	} finally {
+		try {
+			unlinkSync(lock);
+		} catch {}
+	}
+}
+/**
+* Blocking twin of {@link withTrackLockSync}: NEVER skips — spins (1 ms step)
+* until the lock is acquired. Used by the journal append path (track-journal
+* `appendEvent`): an append must wait out an in-flight compaction (same
+* `track.lock`), never race its rename/fold/unlink, never be skipped — a lost
+* write is not an option. The stale-lock TTL (dead-process reclamation) is the
+* only anti-deadlock guard. Do NOT use on paths that may already hold the lock.
+*/
+function withTrackLockSyncBlocking(dir, fn) {
+	mkdirSync(dir, { recursive: true });
+	const lock = join(dir, "track.lock");
+	for (;;) try {
+		closeSync(openSync(lock, "wx"));
+		break;
+	} catch {
+		if (isStale(lock)) try {
+			unlinkSync(lock);
+		} catch {}
+		sleepSync(1);
+	}
+	try {
+		return fn();
+	} finally {
+		try {
+			unlinkSync(lock);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/tracking/track-journal.ts
+/**
+* @module track-journal
+* Append-only, per-line-signed event journal for {@link SessionTrack} — the
+* fan-out-immune replacement for the locked RMW (generalises the freshness/
+* ref-journal.ts pattern to every field). Appends serialise on a SHORT
+* BLOCKING track lock (never skipped, sub-ms wait — see appendEvent) so they
+* can never race the rename-atomic compaction: zero lost write. Per-line HMAC
+* (same key/scheme as integrity.ts): a tampered line is dropped, never the
+* whole file (fail-closed PER LINE).
+* @packageDocumentation
+*/
+/** Hard cap per line — short lines stay non-interleaved under O_APPEND. */
+const MAX_LINE = 32 * 1024;
+/** Trivial-edit sliding window for the fold (mirrors gate.ts DEFAULT_WINDOW_MS). */
+const TRIVIAL_WINDOW_MS = 12e4;
+/** Sign one event: an oversized STRING value is truncated then re-signed (never an unsigned partial line); an oversized non-string is dropped (null). */
+function signEvent(field, op, value, ts) {
+	let data = JSON.stringify({
+		field,
+		op,
+		value,
+		ts
+	});
+	if (data.length > MAX_LINE - 256) {
+		if (typeof value !== "string") return null;
+		value = value.slice(0, Math.max(0, value.length - (data.length - (MAX_LINE - 256))));
+		data = JSON.stringify({
+			field,
+			op,
+			value,
+			ts
+		});
+	}
+	const nonce = randomBytes(8).toString("hex");
+	return {
+		v: 1,
+		field,
+		op,
+		value,
+		ts,
+		nonce,
+		mac: computeMac(loadOrCreateKey(), data, nonce)
+	};
+}
+/** Append one signed event line under the BLOCKING track lock (same `track.lock` as the compaction — an append can never straddle rename/fold/unlink; never skipped). Fail-open on I/O error. */
+function appendEvent(logPath, field, op, value, ts) {
+	try {
+		const ev = signEvent(field, op, value, ts);
+		if (!ev) return false;
+		withTrackLockSyncBlocking(dirname(logPath), () => appendFileSync(logPath, JSON.stringify(ev) + "\n", "utf8"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+const union = (a, b) => [.../* @__PURE__ */ new Set([...a ?? [], ...b ?? []])];
+/** Merge one auth entry: non-empty list fields union, scalars of the later-folded (newer) event win. */
+function mergeAuth(p, e) {
+	const b = p ?? {}, out = {
+		...b,
+		...e
+	};
+	const sessions = union(b.sessions, e.sessions);
+	if (sessions.length) out.sessions = sessions;
+	const docSessions = union(b.doc_sessions, e.doc_sessions);
+	if (docSessions.length) out.doc_sessions = docSessions;
+	const sources = union(b.sources ?? (b.source ? [b.source] : []), e.sources ?? (e.source ? [e.source] : []));
+	if (sources.length) out.sources = sources;
+	const readPaths = union(b.read_paths, e.read_paths);
+	if (readPaths.length) out.read_paths = readPaths;
+	return out;
+}
+/**
+* Replay events over `base` (the legacy snapshot — emptyTrack when absent).
+* Deterministic CRDT fold with a STABLE sort on ts (log order breaks ties):
+* refsRead = dedup union; refsReadAt = per-key max; agents/receipts =
+* ts-ordered append, never deduped; authorizations = per-key merge (list
+* unions); trivialEdits = union re-filtered by the sliding window;
+* target/brainstormRequired = last-writer-wins on ts.
+*/
+function foldEvents(events, base = emptyTrack()) {
+	const t = {
+		...base,
+		refsRead: [...base.refsRead],
+		agents: [...base.agents],
+		authorizations: { ...base.authorizations },
+		trivialEdits: []
+	};
+	const at = { ...base.refsReadAt };
+	const receipts = [...base.receipts ?? []];
+	const trivial = new Set(base.trivialEdits ?? []);
+	let targetTs = base.target ? Date.parse(base.target.set_at) || 0 : 0, brainstormTs = 0;
+	for (const ev of [...events].sort((a, b) => a.ts - b.ts)) if (ev.field === "refsRead") {
+		const p = String(ev.value);
+		if (!t.refsRead.includes(p)) t.refsRead.push(p);
+	} else if (ev.field === "refsReadAt") {
+		const [p, ts] = ev.value;
+		if ((at[p] ?? -1) < ts) at[p] = ts;
+	} else if (ev.field === "agents") t.agents.push(ev.value);
+	else if (ev.field === "receipts") receipts.push(ev.value);
+	else if (ev.field === "authorizations") {
+		const m = ev.value;
+		t.authorizations[m.key] = mergeAuth(t.authorizations[m.key], m.entry);
+	} else if (ev.field === "trivialEdits") trivial.add(Number(ev.value));
+	else if (ev.field === "target" && ev.ts >= targetTs) {
+		t.target = ev.value;
+		targetTs = ev.ts;
+	} else if (ev.field === "brainstormRequired" && ev.ts >= brainstormTs) {
+		t.brainstormRequired = Boolean(ev.value);
+		brainstormTs = ev.ts;
+	}
+	if (Object.keys(at).length) t.refsReadAt = at;
+	if (receipts.length) t.receipts = receipts;
+	const maxT = Math.max(0, ...trivial);
+	t.trivialEdits = [...trivial].filter((x) => x > maxT - TRIVIAL_WINDOW_MS).sort((a, b) => a - b);
+	return t;
+}
+//#endregion
+//#region src/tracking/track-diff.ts
+/** Elements of `next` beyond the longest prefix shared with `prev` (append-only arrays). */
+function tail(prev, next) {
+	let i = 0;
+	while (i < prev.length && i < next.length && JSON.stringify(prev[i]) === JSON.stringify(next[i])) i++;
+	return next.slice(i);
+}
+/** Multiset of added numbers (next counts minus prev counts). */
+function added(xs, ys) {
+	const left = /* @__PURE__ */ new Map();
+	for (const x of xs) left.set(x, (left.get(x) ?? 0) + 1);
+	const out = [];
+	for (const y of ys) {
+		const n = left.get(y) ?? 0;
+		if (n > 0) left.set(y, n - 1);
+		else out.push(y);
+	}
+	return out;
+}
+/** Events replaying `next` over `prev` (empty when the mutation was a no-op). */
+function diffTrackEvents(prev, next, now) {
+	if (prev === next) return [];
+	const out = [];
+	for (const p of next.refsRead) if (!prev.refsRead.includes(p)) out.push({
+		field: "refsRead",
+		op: "add",
+		value: p,
+		ts: next.refsReadAt?.[p] ?? now
+	});
+	for (const [p, ts] of Object.entries(next.refsReadAt ?? {})) if (ts !== prev.refsReadAt?.[p]) out.push({
+		field: "refsReadAt",
+		op: "max",
+		value: [p, ts],
+		ts
+	});
+	for (const a of tail(prev.agents, next.agents)) out.push({
+		field: "agents",
+		op: "append",
+		value: a,
+		ts: a.ts ?? now
+	});
+	for (const r of tail(prev.receipts ?? [], next.receipts ?? [])) out.push({
+		field: "receipts",
+		op: "append",
+		value: r,
+		ts: r.ts ?? now
+	});
+	for (const [key, entry] of Object.entries(next.authorizations)) if (JSON.stringify(entry) !== JSON.stringify(prev.authorizations[key])) out.push({
+		field: "authorizations",
+		op: "merge",
+		value: {
+			key,
+			entry
+		},
+		ts: Date.parse(entry.doc_consulted ?? "") || now
+	});
+	for (const ts of added(prev.trivialEdits ?? [], next.trivialEdits ?? [])) out.push({
+		field: "trivialEdits",
+		op: "add",
+		value: ts,
+		ts
+	});
+	if (next.target && JSON.stringify(next.target) !== JSON.stringify(prev.target)) out.push({
+		field: "target",
+		op: "set",
+		value: next.target,
+		ts: Date.parse(next.target.set_at) || now
+	});
+	if (next.brainstormRequired !== prev.brainstormRequired) out.push({
+		field: "brainstormRequired",
+		op: "set",
+		value: next.brainstormRequired,
+		ts: now
+	});
+	return out;
+}
+/** The journal log path twin of a track snapshot path. */
+function journalLogPath(trackPath) {
+	return trackPath.replace(/\.json$/, ".log");
+}
+/** Parse & MAC-verify journal text; malformed or tampered lines are skipped. */
+function parseEvents(text) {
+	const key = loadOrCreateKey(), out = [];
+	for (const line of text.split("\n")) {
+		if (!line) continue;
+		try {
+			const ev = JSON.parse(line);
+			if (ev?.v !== 1 || typeof ev.nonce !== "string" || typeof ev.ts !== "number") continue;
+			if (ev.mac !== computeMac(key, JSON.stringify({
+				field: ev.field,
+				op: ev.op,
+				value: ev.value,
+				ts: ev.ts
+			}), ev.nonce)) continue;
+			out.push(ev);
+		} catch {}
+	}
+	return out;
+}
+/** Read & verify every event of a log; absent/unreadable → [] (fail-open read). */
+function readEvents(logPath) {
+	try {
+		return parseEvents(readFileSync(logPath, "utf8"));
+	} catch {
+		return [];
+	}
+}
+/** Verified legacy snapshot only (fail-closed → emptyTrack), sync. */
+function readSnapshotSync(file) {
+	try {
+		return verifyTrack(JSON.parse(readFileSync(file, "utf8"))) ?? emptyTrack();
+	} catch {
+		return emptyTrack();
+	}
+}
+/** Sync snapshot ⊕ journal read for the sync gates; `journal=false` = legacy kill-switch path. */
+function readTrackSync(file, journal) {
+	const base = readSnapshotSync(file);
+	return journal ? foldEvents(readEvents(journalLogPath(file)), base) : base;
+}
+/** Fold a whole log file into the signed snapshot (signTrack + nonce, unchanged). */
+function foldIntoSnapshot(file, logPath) {
+	const envelope = signTrack(foldEvents(readEvents(logPath), readSnapshotSync(file)));
+	atomicWrite(file, JSON.stringify(envelope, null, 2));
+	writeLastNonce(envelope.nonce);
+}
+/** Rename-atomic compaction: rename captures the WHOLE log, fold, unlink. A crash leaves `.folding` (recovered first next run); on fold failure BEFORE commit the log is renamed back — never a lost event, and never an event in BOTH snapshot and log (no double-count). */
+function compactSync(file) {
+	const log = journalLogPath(file), folding = `${log}.folding`;
+	if (existsSync(folding)) {
+		foldIntoSnapshot(file, folding);
+		unlinkSync(folding);
+	}
+	renameSync(log, folding);
+	let committed = false;
+	try {
+		foldIntoSnapshot(file, folding);
+		committed = true;
+		unlinkSync(folding);
+	} catch (err) {
+		if (!committed) try {
+			renameSync(folding, log);
+		} catch {}
+		else try {
+			unlinkSync(folding);
+		} catch {}
+		throw err;
+	}
+}
+/** Trigger compaction past the cap (`FUSE_TRACK_COMPACT_BYTES` overrides {@link COMPACT_BYTES}), under the existing lock (skipped on contention). */
+async function maybeCompactJournal(file) {
+	try {
+		const cap = Number(process.env.FUSE_TRACK_COMPACT_BYTES) || 131072;
+		if (statSync(journalLogPath(file)).size < cap) return;
+	} catch {
+		return;
+	}
+	await withTrackLock(dirname(file), async () => {
+		try {
+			compactSync(file);
+		} catch {}
+	});
+}
+//#endregion
+//#region src/tracking/store.ts
+/**
+* @module store
+* Session-track persistence — TWO modes behind an env kill-switch:
+* - JOURNAL (default): writes append signed event lines to `track-<sid>.log`
+*   (O_APPEND, lock-free — see track-journal.ts), reads fold the log over the
+*   legacy `track-<sid>.json` snapshot. No lock on the hot path ⇒ the fan-out
+*   can no longer lose a write to "track lock busy, write skipped" — compaction
+*   included (it is rename-atomic, see track-compact.ts).
+* - LEGACY (`FUSE_TRACK_JOURNAL=0`): the original locked read-modify-write,
+*   kept fully intact below as the instant rollback (G1) — no redeploy needed.
+*   NOTE: =0 does NOT honour the uncompacted journal (the track reads as its
+*   last snapshot, possibly EMPTY); the events are recoverable by switching
+*   back to journal mode — never delete a `.log` during a =0 rollback.
+* The flag is read at CALL time so the switch is live.
+* @packageDocumentation
+*/
+/** Journal mode is the default; `FUSE_TRACK_JOURNAL=0` reverts to the legacy locked RMW (see the module NOTE: =0 ignores the uncompacted journal — recoverable, keep the `.log`). */
+function trackJournalEnabled() {
+	return process.env.FUSE_TRACK_JOURNAL !== "0";
+}
+/** Verified legacy snapshot (fail closed: absent/corrupt/tampered → emptyTrack). */
+async function loadSnapshot(file) {
+	const envelope = await readJsonFile(file);
+	if (!envelope) return emptyTrack();
+	return verifyTrack(envelope) ?? emptyTrack();
+}
+/**
+* Load a session track: the verified legacy snapshot (the migration base — an
+* old `track-<sid>.json` with no log reads exactly as before) with the journal
+* folded on top. Fail closed on tampering (envelope MAC, per-line MAC).
+*/
+async function loadTrack(file) {
+	const base = await loadSnapshot(file);
+	if (!trackJournalEnabled()) return base;
+	return foldEvents(readEvents(journalLogPath(file)), base);
+}
+/** Journal-mode write: append the mutation's events, then maybe compact. */
+async function appendDiff(file, prev, next) {
+	const log = journalLogPath(file);
+	let ok = true;
+	for (const ev of diffTrackEvents(prev, next, Date.now())) ok = appendEvent(log, ev.field, ev.op, ev.value, ev.ts) && ok;
+	await maybeCompactJournal(file);
+	return ok;
+}
+/**
+* Persist a session track. Journal mode appends the diff as signed events;
+* legacy mode signs and persists the tamper-evident envelope, then writes the
+* advisory nonce watermark.
+*/
+async function saveTrack(file, track) {
+	if (trackJournalEnabled()) {
+		await appendDiff(file, await loadTrack(file), track);
+		return;
+	}
+	const envelope = signTrack(track);
+	await writeJsonFile(file, envelope);
+	writeLastNonce(envelope.nonce);
+}
+/**
+* Mutate a session track. Journal mode: load (snapshot ⊕ log), run `mutate`,
+* append the resulting events — lock-free, so a write is only ever lost to a
+* genuine I/O error (reported as `false`). Legacy mode: locked RMW; on lock
+* contention the write is SKIPPED (fail-open, stderr logged) and `false` is
+* returned — a named lost write, never a crash.
+* @param file - The session track file.
+* @param mutate - Pure mutation over the freshly loaded track.
+* @returns True when the write landed.
+*/
+async function withTrack(file, mutate) {
+	if (trackJournalEnabled()) {
+		const track = await loadTrack(file);
+		return appendDiff(file, track, await mutate(track));
+	}
+	return await withTrackLock(dirname(file), async () => {
+		await saveTrack(file, await mutate(await loadTrack(file)));
+	}) !== LOCK_FAILED;
+}
+//#endregion
+export { apexAuthorizationGate as C, trivialCount as S, recordBrainstormRequired as _, journalLogPath as a, recordTarget as b, appendEvent as c, signTrack as d, verifyTrack as f, recordAgent as g, emptyTrack as h, withTrack as i, withTrackLockSync as l, agentsFresh as m, saveTrack as n, readTrackSync as o, writeLastNonce as p, trackJournalEnabled as r, diffTrackEvents as s, loadTrack as t, LOCK_FAILED as u, recordDoc as v, recordTrivialEdit as x, recordRefRead as y };