@animus-ui/next-plugin 0.1.6 → 0.1.8

package/dist/turbopack-loader.cjs

@@ -1,14 +1,45 @@
-const require_loader_core = require("./loader-core-CbaYNhBu.cjs");
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_session_paths = require("./session-paths-CZoi19NW.cjs");
+const require_loader_core = require("./loader-core-C40WbC6s.cjs");
 let _animus_ui_extract_pipeline = require("@animus-ui/extract/pipeline");
 let fs = require("fs");
+fs = __toESM(fs);
 let path = require("path");
 //#region src/turbopack-loader.ts
 let engine = null;
 let sentSources = null;
 let driftWarned = false;
+/** Hydration identity: `${commitPath}:${contentHash(commitRaw)}` — the
+*  commit CONTENT keys hydration; mtime/size never do (design D1). */
 let hydratedKey = null;
 let hydratedManifestJson = null;
-let hydrateFailedWarned = false;
+/** Committed per-file analyzed content hashes (from the inputs). */
+let hydratedFileHashes = null;
 const engineModuleId = "@animus-ui/extract";
 const engineApi = (0, _animus_ui_extract_pipeline.createV2EngineApi)({
 	label: "animus-next-turbopack",
@@ -30,61 +61,222 @@ const engineApi = (0, _animus_ui_extract_pipeline.createV2EngineApi)({
 		}
 	}
 });
-/**
-* Hydrate this worker's engine from the `.animus/` artifact pair — the v2
-* engine serves transforms only from analyze-retained state, so a fresh
-* worker replays the persisted analysis inputs once (and again whenever
-* either artifact changes; keyed by mtime+size of both). The persisted
-* manifest is a hard prerequisite (spec: next-turbopack-integration /
-* Stateless per-file transformation — absent or unreadable
-* `.animus/manifest.json` means passthrough, even when analysis inputs
-* exist). Returns the manifest JSON, or null (caller passes through).
-*/
-function hydrate(rootDir) {
-	const inputsPath = (0, path.join)(rootDir, ".animus", "analysis-inputs.json");
-	const manifestPath = (0, path.join)(rootDir, ".animus", "manifest.json");
-	let inputsStat;
-	let manifestStat;
+let fsImpl = fs;
+/** @internal test seam — pass null to restore the real fs. */
+function __setTurbopackLoaderFsForTests(fs$1) {
+	fsImpl = fs$1 ?? fs;
+}
+/** Epoch artifact paths SEEN on disk (per-worker) — the artifact is never
+*  deleted once written, so a positive probe is stable; negatives re-probe. */
+const epochSeenPaths = /* @__PURE__ */ new Set();
+/** @internal test seam — drop worker-local hydration state. */
+function __resetTurbopackLoaderStateForTests() {
+	hydratedKey = null;
+	hydratedManifestJson = null;
+	hydratedFileHashes = null;
+	epochSeenPaths.clear();
+}
+function readFileOrNull(path$1) {
 	try {
-		inputsStat = (0, fs.statSync)(inputsPath, { bigint: true });
-		manifestStat = (0, fs.statSync)(manifestPath, { bigint: true });
+		return fsImpl.readFileSync(path$1, "utf-8");
 	} catch {
 		return null;
 	}
-	const key = `${inputsPath}:${inputsStat.mtimeNs}:${inputsStat.size}:${manifestStat.mtimeNs}:${manifestStat.size}`;
-	if (key === hydratedKey && hydratedManifestJson !== null) return hydratedManifestJson;
-	try {
-		JSON.parse((0, fs.readFileSync)(manifestPath, "utf-8"));
-		const inputs = JSON.parse((0, fs.readFileSync)(inputsPath, "utf-8"));
+}
+const SEQLOCK_RETRIES = 5;
+/**
+* Seqlock-style artifact read: commit C0 → payloads → hash verification
+* against C0 → commit re-read; accept only if unchanged, else retry
+* (bounded) — a torn or mismatched set is never consumed (design D1).
+* Hydration replays the committed analysis inputs once per commit content.
+*/
+function hydrateSession(sessionDir, sessionId) {
+	const commitPath = require_session_paths.analysisCommitPath(sessionDir);
+	for (let attempt = 0; attempt < SEQLOCK_RETRIES; attempt++) {
+		const c0raw = readFileOrNull(commitPath);
+		if (c0raw === null) return { kind: "absent" };
+		let c0;
+		try {
+			c0 = JSON.parse(c0raw);
+		} catch {
+			continue;
+		}
+		if (c0.sessionId !== sessionId) return {
+			kind: "foreign",
+			artifactSessionId: String(c0.sessionId)
+		};
+		const key = `${commitPath}:${(0, _animus_ui_extract_pipeline.contentHash)(c0raw)}`;
+		if (key === hydratedKey && hydratedManifestJson !== null && hydratedFileHashes !== null) return {
+			kind: "ok",
+			hydration: {
+				manifestJson: hydratedManifestJson,
+				fileHashes: hydratedFileHashes,
+				commitRaw: c0raw
+			}
+		};
+		const manifestRaw = readFileOrNull(require_session_paths.manifestPath(sessionDir));
+		const inputsRaw = readFileOrNull(require_session_paths.analysisInputsPath(sessionDir));
+		if (manifestRaw === null || inputsRaw === null) continue;
+		if ((0, _animus_ui_extract_pipeline.contentHash)(manifestRaw) !== c0.manifestHash || (0, _animus_ui_extract_pipeline.contentHash)(inputsRaw) !== c0.inputsHash) continue;
+		if (readFileOrNull(commitPath) !== c0raw) continue;
+		let inputs;
+		let fileHashes;
+		try {
+			const envelopeSession = require_session_paths.readJsonEnvelope(manifestRaw)?.sessionId;
+			if (envelopeSession !== void 0 && envelopeSession !== sessionId) return {
+				kind: "foreign",
+				artifactSessionId: String(envelopeSession)
+			};
+			const inputsParsed = JSON.parse(inputsRaw);
+			inputs = inputsParsed;
+			fileHashes = inputsParsed.analyzedHashes ? new Map(Object.entries(inputsParsed.analyzedHashes)) : new Map(JSON.parse(inputs.filesJson).map((entry) => [entry.path, entry.hash ?? (0, _animus_ui_extract_pipeline.contentHash)(entry.source)]));
+		} catch {
+			return { kind: "torn" };
+		}
 		const { analyzeProject } = engineApi();
 		hydratedManifestJson = analyzeProject(...(0, _animus_ui_extract_pipeline.buildAnalyzeProjectArgs)(inputs));
+		hydratedFileHashes = fileHashes;
 		hydratedKey = key;
-		return hydratedManifestJson;
-	} catch (e) {
-		if (!hydrateFailedWarned) {
-			hydrateFailedWarned = true;
-			console.warn(`[animus-extract] Turbopack worker hydration failed (${String(e)}); sources pass through untransformed`);
-		}
+		return {
+			kind: "ok",
+			hydration: {
+				manifestJson: hydratedManifestJson,
+				fileHashes,
+				commitRaw: c0raw
+			}
+		};
+	}
+	return { kind: "torn" };
+}
+function readStatus(sessionDir) {
+	const raw = readFileOrNull(require_session_paths.analysisStatusPath(sessionDir));
+	if (raw === null) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
 		return null;
 	}
 }
+const CATCHUP_POLL_INITIAL_MS = 10;
+const CATCHUP_POLL_MAX_MS = 25;
+const CATCHUP_WAIT_MARGIN_MS = 50;
+const CATCHUP_WATCHDOG_MS = 2e3;
+/** The loader cannot read the orchestrator's configured debounce, so its
+*  own ceiling assumes the default watcher debounce. */
+const DEFAULT_DEBOUNCE_CEILING_MS = 75;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const ACTIVE_STATES = new Set([
+	"starting",
+	"debouncing",
+	"analyzing",
+	"committing"
+]);
 /**
 * Turbopack loader for Animus source transformation. Derives everything
-* from the incoming source, its JSON-serializable options, and the
-* `.animus/` disk artifacts written by the out-of-band orchestrator.
+* from the incoming source, its JSON-serializable options (carrying the
+* session identity), and the session's COMMITTED disk artifacts written by
+* the out-of-band orchestrator. Async by contract — the evidence-based
+* catch-up (design D3) waits, bounded, for an imminent commit.
 */
 function animusTurbopackLoader(source) {
-	const opts = this.getOptions?.() ?? {};
-	const rootDir = opts.rootDir ?? this.rootContext;
-	const manifestJson = hydrate(rootDir);
-	if (!manifestJson) return source;
-	return require_loader_core.transformWithManifest({
+	if (typeof this.async !== "function") throw new Error("[animus-extract] the Animus Turbopack loader requires an async-capable loader runner (this.async is unavailable)");
+	const callback = this.async();
+	runLoader(this, source).then((code) => callback(null, code), (err) => callback(err instanceof Error ? err : new Error(String(err))));
+}
+async function runLoader(ctx, source) {
+	const opts = ctx.getOptions?.() ?? {};
+	const rootDir = opts.rootDir ?? ctx.rootContext;
+	const sessionId = opts.sessionId;
+	const sessionDir = opts.sessionDir ?? (sessionId !== void 0 ? require_session_paths.sessionArtifactDir(rootDir, sessionId) : void 0);
+	if (sessionId === void 0 || sessionDir === void 0) return source;
+	const commitPath = require_session_paths.analysisCommitPath(sessionDir);
+	const statusPath = require_session_paths.analysisStatusPath(sessionDir);
+	const epochPath = require_session_paths.replacementEpochPath(sessionDir);
+	if (typeof ctx.addDependency === "function" && (epochSeenPaths.has(epochPath) || fsImpl.existsSync(epochPath))) {
+		epochSeenPaths.add(epochPath);
+		ctx.addDependency(epochPath);
+	}
+	const filename = (0, path.relative)(rootDir, ctx.resourcePath);
+	/** EVERY failing path registers the commit + status artifacts as
+	*  dependencies BEFORE throwing (the loader-runner sends dependency IPC
+	*  ahead of the error check upstream), so a landing commit or status
+	*  transition re-triggers the invocation — the documented
+	*  read→registration race makes this a recovery aid, never the primary
+	*  wakeup (design D3). Successful paths add NO commit/status dependency. */
+	const coverageFailure = (message) => {
+		ctx.addDependency?.(commitPath);
+		ctx.addDependency?.(statusPath);
+		return new Error(message);
+	};
+	const transform = (manifestJson) => require_loader_core.transformWithManifest({
 		source,
-		filename: (0, path.relative)(rootDir, this.resourcePath),
+		filename,
 		manifestJson,
 		engineApi,
 		opts
 	});
+	const outcome = hydrateSession(sessionDir, sessionId);
+	if (outcome.kind === "foreign") throw coverageFailure(`ANIMUS_FOREIGN_SESSION: artifacts under ${sessionDir} belong to session ${outcome.artifactSessionId}, not ${sessionId} — refusing to transform from a foreign generation`);
+	if (outcome.kind === "torn") throw coverageFailure(`ANIMUS_ARTIFACT_READ_TORN: could not obtain a consistent committed artifact set for ${filename} after ${SEQLOCK_RETRIES} attempts`);
+	let sourceHash = null;
+	if (outcome.kind === "ok") {
+		const analyzedHash = outcome.hydration.fileHashes.get(filename);
+		if (analyzedHash === void 0) return transform(outcome.hydration.manifestJson);
+		sourceHash = (0, _animus_ui_extract_pipeline.contentHash)(source);
+		if (analyzedHash === sourceHash) return transform(outcome.hydration.manifestJson);
+	}
+	return awaitCoverage({
+		source,
+		sourceHash: sourceHash ?? (0, _animus_ui_extract_pipeline.contentHash)(source),
+		filename,
+		sessionId,
+		sessionDir,
+		coverageFailure,
+		transform
+	});
+}
+/**
+* The catch-up decision table (design D3 — implemented verbatim). Waits —
+* polled, bounded — ONLY in the two evidence states: commit absent while an
+* attempt is active, or the active attempt's pending set contains this file
+* at its current hash. Everything else fails immediately with its stable
+* diagnostic. The moment a commit lands that covers the input, the seqlock
+* hydration consumes it and the transform proceeds with no diagnostic.
+*/
+async function awaitCoverage(args) {
+	const { source, sourceHash, filename, sessionId, sessionDir, coverageFailure, transform } = args;
+	const ceiling = Date.now() + DEFAULT_DEBOUNCE_CEILING_MS + CATCHUP_WATCHDOG_MS + CATCHUP_WAIT_MARGIN_MS;
+	let poll = CATCHUP_POLL_INITIAL_MS;
+	for (;;) {
+		const outcome = hydrateSession(sessionDir, sessionId);
+		if (outcome.kind === "foreign") throw coverageFailure(`ANIMUS_FOREIGN_SESSION: artifacts under ${sessionDir} belong to session ${outcome.artifactSessionId}, not ${sessionId}`);
+		if (outcome.kind === "ok") {
+			const analyzedHash = outcome.hydration.fileHashes.get(filename);
+			if (analyzedHash !== void 0 && analyzedHash === sourceHash) return transform(outcome.hydration.manifestJson);
+		}
+		const commitPresent = outcome.kind === "ok";
+		const status = readStatus(sessionDir);
+		if (status === null) {
+			if (!commitPresent) return source;
+			throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} is not covered by the committed analysis and no analysis-status exists for session ${sessionId} — is the animus orchestrator running?`);
+		}
+		if (status.sessionId !== sessionId) throw coverageFailure(`ANIMUS_FOREIGN_SESSION: analysis-status belongs to session ${status.sessionId}, not ${sessionId}`);
+		if (status.state === "failed") throw coverageFailure(`ANIMUS_ANALYSIS_FAILED: the analysis covering ${filename} failed: ${status.diagnostic ?? "unknown analysis error"}`);
+		if (status.state === "idle" || !ACTIVE_STATES.has(status.state)) throw coverageFailure(`ANIMUS_ANALYSIS_NOT_SCHEDULED: ${filename} changed but no analysis attempt is scheduled for it (watcher miss?)`);
+		if (commitPresent) {
+			if (!(status.pending ?? []).some(([key, hash]) => key === filename && hash === sourceHash)) throw coverageFailure(`ANIMUS_ANALYSIS_NOT_SCHEDULED: the active analysis attempt (${status.attemptId}) has not observed ${filename} at its current content`);
+		}
+		const now = Date.now();
+		if (typeof status.deadlineAt === "number" && now > status.deadlineAt) throw coverageFailure(`ANIMUS_ANALYSIS_STALLED: analysis attempt ${status.attemptId} exceeded its deadline while ${filename} waited for coverage`);
+		if (now > ceiling) throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} changed after the committed analysis; timed out waiting for the commit to advance — retrying on the next invalidation`);
+		await sleep(poll);
+		poll = CATCHUP_POLL_MAX_MS;
+	}
 }
 //#endregion
-module.exports = animusTurbopackLoader;
+exports.__resetTurbopackLoaderStateForTests = __resetTurbopackLoaderStateForTests;
+exports.__setTurbopackLoaderFsForTests = __setTurbopackLoaderFsForTests;
+exports.__toESM = __toESM;
+exports.default = animusTurbopackLoader;

package/dist/turbopack-loader.d.ts

@@ -1,16 +1,39 @@
+import * as nodeFs from 'fs';
 import type { LoaderPolicyOptions } from './loader-core';
+/** JSON-serializable loader options (Turbopack forwards them across process
+ *  boundaries). The session identity is a REAL task input (design D2):
+ *  restarts mint a new session id, so cross-session cache reuse is
+ *  impossible by construction — restart-cold is normative. */
+export interface TurbopackLoaderOptions extends LoaderPolicyOptions {
+    rootDir?: string;
+    sessionId?: string;
+    sessionDir?: string;
+}
+type LoaderCallback = (err: Error | null, content?: string) => void;
 type LoaderContext = {
     resourcePath: string;
     rootContext: string;
-    getOptions: () => LoaderPolicyOptions & {
-        rootDir?: string;
-    };
+    getOptions: () => TurbopackLoaderOptions;
+    /** File-dependency registration (Turbopack loader-runner IPC sends
+     *  dependencies BEFORE the error check — throw-after-addDependency is a
+     *  sound recovery primitive; see design D3). */
+    addDependency?: (file: string) => void;
+    /** Async-completion handle (webpack loader convention) — required: the
+     *  evidence-based catch-up wait cannot run synchronously. */
+    async?: () => LoaderCallback;
 };
+type LoaderFs = Pick<typeof nodeFs, 'readFileSync' | 'existsSync'>;
+/** @internal test seam — pass null to restore the real fs. */
+export declare function __setTurbopackLoaderFsForTests(fs: LoaderFs | null): void;
+/** @internal test seam — drop worker-local hydration state. */
+export declare function __resetTurbopackLoaderStateForTests(): void;
 /**
  * Turbopack loader for Animus source transformation. Derives everything
- * from the incoming source, its JSON-serializable options, and the
- * `.animus/` disk artifacts written by the out-of-band orchestrator.
+ * from the incoming source, its JSON-serializable options (carrying the
+ * session identity), and the session's COMMITTED disk artifacts written by
+ * the out-of-band orchestrator. Async by contract — the evidence-based
+ * catch-up (design D3) waits, bounded, for an imminent commit.
  */
-export default function animusTurbopackLoader(this: LoaderContext, source: string): string;
+export default function animusTurbopackLoader(this: LoaderContext, source: string): void;
 export {};
 //# sourceMappingURL=turbopack-loader.d.ts.map

package/dist/turbopack-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turbopack-loader.d.ts","sourceRoot":"","sources":["../src/turbopack-loader.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAMzD,KAAK,aAAa,GAAG;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D,CAAC;AAgGF;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,GACb,MAAM,CAeR"}
+{"version":3,"file":"turbopack-loader.d.ts","sourceRoot":"","sources":["../src/turbopack-loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,MAAM,IAAI,CAAC;AAc7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAOzD;;;8DAG8D;AAC9D,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpE,KAAK,aAAa,GAAG;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,sBAAsB,CAAC;IACzC;;oDAEgD;IAChD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;iEAC6D;IAC7D,KAAK,CAAC,EAAE,MAAM,cAAc,CAAC;CAC9B,CAAC;AAgDF,KAAK,QAAQ,GAAG,IAAI,CAAC,OAAO,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;AAGnE,8DAA8D;AAC9D,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAExE;AAMD,+DAA+D;AAC/D,wBAAgB,mCAAmC,IAAI,IAAI,CAK1D;AAkKD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CAcN"}

package/dist/turbopack-loader.mjs

@@ -1,15 +1,18 @@
-import { t as __require } from "./chunk-y_GBKt04.mjs";
+import { S as __require, _ as replacementEpochPath, d as analysisStatusPath, g as readJsonEnvelope, l as analysisCommitPath, m as manifestPath, u as analysisInputsPath, v as sessionArtifactDir } from "./session-paths-DfYIPDcM.mjs";
 import { t as transformWithManifest } from "./loader-core-D6Tm_b8F.mjs";
-import { buildAnalyzeProjectArgs, createV2EngineApi } from "@animus-ui/extract/pipeline";
-import { readFileSync, statSync } from "fs";
-import { join, relative } from "path";
+import { buildAnalyzeProjectArgs, contentHash, createV2EngineApi } from "@animus-ui/extract/pipeline";
+import * as nodeFs from "fs";
+import { relative } from "path";
 //#region src/turbopack-loader.ts
 let engine = null;
 let sentSources = null;
 let driftWarned = false;
+/** Hydration identity: `${commitPath}:${contentHash(commitRaw)}` — the
+*  commit CONTENT keys hydration; mtime/size never do (design D1). */
 let hydratedKey = null;
 let hydratedManifestJson = null;
-let hydrateFailedWarned = false;
+/** Committed per-file analyzed content hashes (from the inputs). */
+let hydratedFileHashes = null;
 const engineModuleId = "@animus-ui/extract";
 const engineApi = createV2EngineApi({
 	label: "animus-next-turbopack",
@@ -31,61 +34,219 @@ const engineApi = createV2EngineApi({
 		}
 	}
 });
-/**
-* Hydrate this worker's engine from the `.animus/` artifact pair — the v2
-* engine serves transforms only from analyze-retained state, so a fresh
-* worker replays the persisted analysis inputs once (and again whenever
-* either artifact changes; keyed by mtime+size of both). The persisted
-* manifest is a hard prerequisite (spec: next-turbopack-integration /
-* Stateless per-file transformation — absent or unreadable
-* `.animus/manifest.json` means passthrough, even when analysis inputs
-* exist). Returns the manifest JSON, or null (caller passes through).
-*/
-function hydrate(rootDir) {
-	const inputsPath = join(rootDir, ".animus", "analysis-inputs.json");
-	const manifestPath = join(rootDir, ".animus", "manifest.json");
-	let inputsStat;
-	let manifestStat;
+let fsImpl = nodeFs;
+/** @internal test seam — pass null to restore the real fs. */
+function __setTurbopackLoaderFsForTests(fs) {
+	fsImpl = fs ?? nodeFs;
+}
+/** Epoch artifact paths SEEN on disk (per-worker) — the artifact is never
+*  deleted once written, so a positive probe is stable; negatives re-probe. */
+const epochSeenPaths = /* @__PURE__ */ new Set();
+/** @internal test seam — drop worker-local hydration state. */
+function __resetTurbopackLoaderStateForTests() {
+	hydratedKey = null;
+	hydratedManifestJson = null;
+	hydratedFileHashes = null;
+	epochSeenPaths.clear();
+}
+function readFileOrNull(path) {
 	try {
-		inputsStat = statSync(inputsPath, { bigint: true });
-		manifestStat = statSync(manifestPath, { bigint: true });
+		return fsImpl.readFileSync(path, "utf-8");
 	} catch {
 		return null;
 	}
-	const key = `${inputsPath}:${inputsStat.mtimeNs}:${inputsStat.size}:${manifestStat.mtimeNs}:${manifestStat.size}`;
-	if (key === hydratedKey && hydratedManifestJson !== null) return hydratedManifestJson;
-	try {
-		JSON.parse(readFileSync(manifestPath, "utf-8"));
-		const inputs = JSON.parse(readFileSync(inputsPath, "utf-8"));
+}
+const SEQLOCK_RETRIES = 5;
+/**
+* Seqlock-style artifact read: commit C0 → payloads → hash verification
+* against C0 → commit re-read; accept only if unchanged, else retry
+* (bounded) — a torn or mismatched set is never consumed (design D1).
+* Hydration replays the committed analysis inputs once per commit content.
+*/
+function hydrateSession(sessionDir, sessionId) {
+	const commitPath = analysisCommitPath(sessionDir);
+	for (let attempt = 0; attempt < SEQLOCK_RETRIES; attempt++) {
+		const c0raw = readFileOrNull(commitPath);
+		if (c0raw === null) return { kind: "absent" };
+		let c0;
+		try {
+			c0 = JSON.parse(c0raw);
+		} catch {
+			continue;
+		}
+		if (c0.sessionId !== sessionId) return {
+			kind: "foreign",
+			artifactSessionId: String(c0.sessionId)
+		};
+		const key = `${commitPath}:${contentHash(c0raw)}`;
+		if (key === hydratedKey && hydratedManifestJson !== null && hydratedFileHashes !== null) return {
+			kind: "ok",
+			hydration: {
+				manifestJson: hydratedManifestJson,
+				fileHashes: hydratedFileHashes,
+				commitRaw: c0raw
+			}
+		};
+		const manifestRaw = readFileOrNull(manifestPath(sessionDir));
+		const inputsRaw = readFileOrNull(analysisInputsPath(sessionDir));
+		if (manifestRaw === null || inputsRaw === null) continue;
+		if (contentHash(manifestRaw) !== c0.manifestHash || contentHash(inputsRaw) !== c0.inputsHash) continue;
+		if (readFileOrNull(commitPath) !== c0raw) continue;
+		let inputs;
+		let fileHashes;
+		try {
+			const envelopeSession = readJsonEnvelope(manifestRaw)?.sessionId;
+			if (envelopeSession !== void 0 && envelopeSession !== sessionId) return {
+				kind: "foreign",
+				artifactSessionId: String(envelopeSession)
+			};
+			const inputsParsed = JSON.parse(inputsRaw);
+			inputs = inputsParsed;
+			fileHashes = inputsParsed.analyzedHashes ? new Map(Object.entries(inputsParsed.analyzedHashes)) : new Map(JSON.parse(inputs.filesJson).map((entry) => [entry.path, entry.hash ?? contentHash(entry.source)]));
+		} catch {
+			return { kind: "torn" };
+		}
 		const { analyzeProject } = engineApi();
 		hydratedManifestJson = analyzeProject(...buildAnalyzeProjectArgs(inputs));
+		hydratedFileHashes = fileHashes;
 		hydratedKey = key;
-		return hydratedManifestJson;
-	} catch (e) {
-		if (!hydrateFailedWarned) {
-			hydrateFailedWarned = true;
-			console.warn(`[animus-extract] Turbopack worker hydration failed (${String(e)}); sources pass through untransformed`);
-		}
+		return {
+			kind: "ok",
+			hydration: {
+				manifestJson: hydratedManifestJson,
+				fileHashes,
+				commitRaw: c0raw
+			}
+		};
+	}
+	return { kind: "torn" };
+}
+function readStatus(sessionDir) {
+	const raw = readFileOrNull(analysisStatusPath(sessionDir));
+	if (raw === null) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
 		return null;
 	}
 }
+const CATCHUP_POLL_INITIAL_MS = 10;
+const CATCHUP_POLL_MAX_MS = 25;
+const CATCHUP_WAIT_MARGIN_MS = 50;
+const CATCHUP_WATCHDOG_MS = 2e3;
+/** The loader cannot read the orchestrator's configured debounce, so its
+*  own ceiling assumes the default watcher debounce. */
+const DEFAULT_DEBOUNCE_CEILING_MS = 75;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const ACTIVE_STATES = new Set([
+	"starting",
+	"debouncing",
+	"analyzing",
+	"committing"
+]);
 /**
 * Turbopack loader for Animus source transformation. Derives everything
-* from the incoming source, its JSON-serializable options, and the
-* `.animus/` disk artifacts written by the out-of-band orchestrator.
+* from the incoming source, its JSON-serializable options (carrying the
+* session identity), and the session's COMMITTED disk artifacts written by
+* the out-of-band orchestrator. Async by contract — the evidence-based
+* catch-up (design D3) waits, bounded, for an imminent commit.
 */
 function animusTurbopackLoader(source) {
-	const opts = this.getOptions?.() ?? {};
-	const rootDir = opts.rootDir ?? this.rootContext;
-	const manifestJson = hydrate(rootDir);
-	if (!manifestJson) return source;
-	return transformWithManifest({
+	if (typeof this.async !== "function") throw new Error("[animus-extract] the Animus Turbopack loader requires an async-capable loader runner (this.async is unavailable)");
+	const callback = this.async();
+	runLoader(this, source).then((code) => callback(null, code), (err) => callback(err instanceof Error ? err : new Error(String(err))));
+}
+async function runLoader(ctx, source) {
+	const opts = ctx.getOptions?.() ?? {};
+	const rootDir = opts.rootDir ?? ctx.rootContext;
+	const sessionId = opts.sessionId;
+	const sessionDir = opts.sessionDir ?? (sessionId !== void 0 ? sessionArtifactDir(rootDir, sessionId) : void 0);
+	if (sessionId === void 0 || sessionDir === void 0) return source;
+	const commitPath = analysisCommitPath(sessionDir);
+	const statusPath = analysisStatusPath(sessionDir);
+	const epochPath = replacementEpochPath(sessionDir);
+	if (typeof ctx.addDependency === "function" && (epochSeenPaths.has(epochPath) || fsImpl.existsSync(epochPath))) {
+		epochSeenPaths.add(epochPath);
+		ctx.addDependency(epochPath);
+	}
+	const filename = relative(rootDir, ctx.resourcePath);
+	/** EVERY failing path registers the commit + status artifacts as
+	*  dependencies BEFORE throwing (the loader-runner sends dependency IPC
+	*  ahead of the error check upstream), so a landing commit or status
+	*  transition re-triggers the invocation — the documented
+	*  read→registration race makes this a recovery aid, never the primary
+	*  wakeup (design D3). Successful paths add NO commit/status dependency. */
+	const coverageFailure = (message) => {
+		ctx.addDependency?.(commitPath);
+		ctx.addDependency?.(statusPath);
+		return new Error(message);
+	};
+	const transform = (manifestJson) => transformWithManifest({
 		source,
-		filename: relative(rootDir, this.resourcePath),
+		filename,
 		manifestJson,
 		engineApi,
 		opts
 	});
+	const outcome = hydrateSession(sessionDir, sessionId);
+	if (outcome.kind === "foreign") throw coverageFailure(`ANIMUS_FOREIGN_SESSION: artifacts under ${sessionDir} belong to session ${outcome.artifactSessionId}, not ${sessionId} — refusing to transform from a foreign generation`);
+	if (outcome.kind === "torn") throw coverageFailure(`ANIMUS_ARTIFACT_READ_TORN: could not obtain a consistent committed artifact set for ${filename} after ${SEQLOCK_RETRIES} attempts`);
+	let sourceHash = null;
+	if (outcome.kind === "ok") {
+		const analyzedHash = outcome.hydration.fileHashes.get(filename);
+		if (analyzedHash === void 0) return transform(outcome.hydration.manifestJson);
+		sourceHash = contentHash(source);
+		if (analyzedHash === sourceHash) return transform(outcome.hydration.manifestJson);
+	}
+	return awaitCoverage({
+		source,
+		sourceHash: sourceHash ?? contentHash(source),
+		filename,
+		sessionId,
+		sessionDir,
+		coverageFailure,
+		transform
+	});
+}
+/**
+* The catch-up decision table (design D3 — implemented verbatim). Waits —
+* polled, bounded — ONLY in the two evidence states: commit absent while an
+* attempt is active, or the active attempt's pending set contains this file
+* at its current hash. Everything else fails immediately with its stable
+* diagnostic. The moment a commit lands that covers the input, the seqlock
+* hydration consumes it and the transform proceeds with no diagnostic.
+*/
+async function awaitCoverage(args) {
+	const { source, sourceHash, filename, sessionId, sessionDir, coverageFailure, transform } = args;
+	const ceiling = Date.now() + DEFAULT_DEBOUNCE_CEILING_MS + CATCHUP_WATCHDOG_MS + CATCHUP_WAIT_MARGIN_MS;
+	let poll = CATCHUP_POLL_INITIAL_MS;
+	for (;;) {
+		const outcome = hydrateSession(sessionDir, sessionId);
+		if (outcome.kind === "foreign") throw coverageFailure(`ANIMUS_FOREIGN_SESSION: artifacts under ${sessionDir} belong to session ${outcome.artifactSessionId}, not ${sessionId}`);
+		if (outcome.kind === "ok") {
+			const analyzedHash = outcome.hydration.fileHashes.get(filename);
+			if (analyzedHash !== void 0 && analyzedHash === sourceHash) return transform(outcome.hydration.manifestJson);
+		}
+		const commitPresent = outcome.kind === "ok";
+		const status = readStatus(sessionDir);
+		if (status === null) {
+			if (!commitPresent) return source;
+			throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} is not covered by the committed analysis and no analysis-status exists for session ${sessionId} — is the animus orchestrator running?`);
+		}
+		if (status.sessionId !== sessionId) throw coverageFailure(`ANIMUS_FOREIGN_SESSION: analysis-status belongs to session ${status.sessionId}, not ${sessionId}`);
+		if (status.state === "failed") throw coverageFailure(`ANIMUS_ANALYSIS_FAILED: the analysis covering ${filename} failed: ${status.diagnostic ?? "unknown analysis error"}`);
+		if (status.state === "idle" || !ACTIVE_STATES.has(status.state)) throw coverageFailure(`ANIMUS_ANALYSIS_NOT_SCHEDULED: ${filename} changed but no analysis attempt is scheduled for it (watcher miss?)`);
+		if (commitPresent) {
+			if (!(status.pending ?? []).some(([key, hash]) => key === filename && hash === sourceHash)) throw coverageFailure(`ANIMUS_ANALYSIS_NOT_SCHEDULED: the active analysis attempt (${status.attemptId}) has not observed ${filename} at its current content`);
+		}
+		const now = Date.now();
+		if (typeof status.deadlineAt === "number" && now > status.deadlineAt) throw coverageFailure(`ANIMUS_ANALYSIS_STALLED: analysis attempt ${status.attemptId} exceeded its deadline while ${filename} waited for coverage`);
+		if (now > ceiling) throw coverageFailure(`ANIMUS_ANALYSIS_CATCHING_UP: ${filename} changed after the committed analysis; timed out waiting for the commit to advance — retrying on the next invalidation`);
+		await sleep(poll);
+		poll = CATCHUP_POLL_MAX_MS;
+	}
 }
 //#endregion
-export { animusTurbopackLoader as default };
+export { __resetTurbopackLoaderStateForTests, __setTurbopackLoaderFsForTests, animusTurbopackLoader as default };