@animus-ui/next-plugin 0.1.7 → 0.1.9

package/dist/singleton.d.ts

@@ -10,6 +10,74 @@ export declare function getSharedExternalDirs(): string[];
 export declare function setSharedExternalDirs(dirs: string[]): void;
 export declare function getSharedExternalEntries(): Map<string, string>;
 export declare function setSharedExternalEntries(entries: Map<string, string>): void;
+/** Structural view of the owning session a forwarded watch batch targets —
+ *  kept minimal (and defined here, not imported) so the singleton never
+ *  depends on the session module it serves. */
+export interface WatchBatchTarget {
+    ingestForwardedBatch(changes: {
+        modifiedFiles?: ReadonlySet<string>;
+        removedFiles?: ReadonlySet<string>;
+    }): Promise<void>;
+}
+/**
+ * The session that completed the full pipeline and holds system state — the
+ * only instance that can run watch analysis. Each MultiCompiler child holds
+ * its own session AND its own watcher with its own modified set; a
+ * non-owning session forwards its batch here instead of dropping it (a file
+ * only that compiler watches would otherwise never be analyzed).
+ */
+export declare function getOwningWatchSession(): WatchBatchTarget | null;
+export declare function setOwningWatchSession(session: WatchBatchTarget | null): void;
+/**
+ * Per-file analyzed content hashes of the last published analysis (relPath →
+ * contentHash of the exact bytes analyzed) — the loader's witness for the
+ * unconditional catching-up guard (openspec:
+ * next-webpack-served-transform-coherence, design D4). Includes files
+ * analyzed with ZERO animus entries: analyzed identity is membership in the
+ * analysis input set, not manifest entry count.
+ */
+export declare function getAnalyzedHashes(): ReadonlyMap<string, string> | null;
+export declare function setAnalyzedHashes(hashes: Map<string, string>): void;
+/**
+ * Session identity is per Next INVOCATION — one process, however many
+ * compiler instances it holds (openspec:
+ * next-turbopack-served-transform-coherence, design D2). The first
+ * ExtractionSession constructed in a process claims a fresh randomUUID;
+ * every later instance (client/server/RSC compilers each construct one)
+ * adopts it, so all compilers alias, watch-ignore, and publish ONE
+ * session-scoped artifact tree. Separate invocations (`next dev` +
+ * `next build` co-writing) are separate processes and therefore separate
+ * sessions by construction.
+ */
+export declare function claimProcessSessionId(): string;
+/**
+ * Absolute session artifact directory of the OWNING session's last
+ * publication — the webpack loader's source for the session-scoped epoch
+ * dependency path (the loader shares the process with the pipeline; the
+ * Turbopack loader instead receives the directory via its options).
+ */
+export declare function getSessionArtifactDir(): string | null;
+export declare function setSessionArtifactDir(dir: string): void;
+/**
+ * Canonical replacement epoch of the last published analysis
+ * (`hashReplacementPlans(snapshotFilePlans(manifest), systemPropsContent)`
+ * — openspec: next-webpack-served-transform-coherence, design D5; the
+ * served system-props module rides as the served-dependency witness so
+ * offline system-props changes move the epoch). Published by the
+ * owning session AFTER the manifest so a reader that observes the epoch
+ * always observes at least that generation's manifest. (Session
+ * attribution lives on the DISK epoch artifact — no in-process mirror.)
+ */
+export declare function getReplacementEpoch(): string | null;
+export declare function setReplacementEpoch(epoch: string): void;
+/**
+ * The one in-flight watch-analysis transaction (design D3): the first
+ * compiler entering a watch batch runs analysis + publication; every other
+ * compiler (client/server/RSC — each holds its own session instance) joins
+ * this promise instead of proceeding against a pre-transaction generation.
+ */
+export declare function getWatchTransaction(): Promise<void> | null;
+export declare function setWatchTransaction(transaction: Promise<void> | null): void;
 export type AnimusEngine = 'v2';
 /** Engine selection travels through the singleton so non-owning compiler
  *  instances and the webpack loader honor the same choice as the owner. */
@@ -20,4 +88,9 @@ export declare function getSharedEngine(): AnimusEngine;
  *  module's own .d.ts is the authoritative surface. */
 export declare function requireEngine(): any;
 export declare function engineApi(): any;
+/**
+ * Every globalThis key this module owns — the single authority test
+ * harnesses snapshot/clear per test (never re-declare this list).
+ */
+export declare const SINGLETON_GLOBAL_KEYS: readonly ["__animus_manifest_json__", "__animus_analysis_promise__", "__animus_shared_css__", "__animus_shared_system_props__", "__animus_external_pkg_dirs__", "__animus_external_source_entries__", "__animus_analyzed_hashes__", "__animus_replacement_epoch__", "__animus_watch_transaction__", "__animus_process_session_id__", "__animus_session_artifact_dir__", "__animus_owning_watch_session__", "__animus_engine__", "__animus_v2_engine__", "__animus_v2_sent_sources__", "__animus_v2_drift_warned__"];
 //# sourceMappingURL=singleton.d.ts.map

package/dist/singleton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../src/singleton.ts"],"names":[],"mappings":"AAkBA,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAIzD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAE/D;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAMhD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAE1D;AAED,wBAAgB,wBAAwB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM9D;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAG3E;AAID,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC;AAEhC;2EAC2E;AAC3E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;uDAEuD;AAEvD,wBAAgB,aAAa,IAAI,GAAG,CAInC;AAoDD,wBAAgB,SAAS,IAAI,GAAG,CAE/B"}
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../src/singleton.ts"],"names":[],"mappings":"AAmBA,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAIzD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAE/D;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAMhD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAE1D;AAED,wBAAgB,wBAAwB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM9D;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAG3E;AA6BD;;+CAE+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB,CAAC,OAAO,EAAE;QAC5B,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACpC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,GAAG,IAAI,CAE/D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAEtE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAO9C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAEnD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAE3E;AAID,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC;AAEhC;2EAC2E;AAC3E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;uDAEuD;AAEvD,wBAAgB,aAAa,IAAI,GAAG,CAInC;AAoDD,wBAAgB,SAAS,IAAI,GAAG,CAE/B;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qfAiBxB,CAAC"}

package/dist/turbopack-config.d.ts

@@ -36,13 +36,18 @@ export declare function resolveTurbopackMode(options: AnimusNextOptions, env?: R
  * (file-level allowlisting lives in the loader via manifest lookup — Next 15
  * rules have no condition algebra) plus resolve aliases for the virtual
  * system-props id, the emitter's stylesheet id, and each collected external
- * package specifier redirected to its source entry.
+ * package specifier redirected to its source entry. Loader options carry
+ * the session identity (design D2: an options-borne, JSON-serializable
+ * Turbopack task input — restart-cold by construction), and the artifact
+ * aliases point into the session-scoped tree.
  */
 export declare function buildTurbopackConfig(args: {
     rootDir: string;
     loaderPath: string;
     options: AnimusNextOptions;
     externalSourceEntries: ReadonlyMap<string, string>;
+    sessionId: string;
+    sessionDir: string;
 }): TurbopackConfigFragment;
 /**
  * Locate the Turbopack loader module: built dist first, source fallback for

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

@@ -1 +1 @@
-{"version":3,"file":"turbopack-config.d.ts","sourceRoot":"","sources":["../src/turbopack-config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;gEAGgE;AAChE,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE;;wBAEwB;AACxB,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpD,GAAG,uBAAuB,CA8B1B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMpE"}
+{"version":3,"file":"turbopack-config.d.ts","sourceRoot":"","sources":["../src/turbopack-config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;gEAGgE;AAChE,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE;;wBAEwB;AACxB,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAMT;AAQD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,uBAAuB,CA0C1B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMpE"}

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"}