@animus-ui/next-plugin 0.1.6 → 0.1.8

package/dist/session-paths.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Session-scoped artifact names, path derivations, and the analysis-status
+ * shape (openspec: next-turbopack-served-transform-coherence, design D1–D3)
+ * — shared by the session writer (extraction-session), the webpack
+ * plugin/loader, and the Turbopack loader.
+ *
+ * Deliberately free of singleton/session imports: the Turbopack loader
+ * executes in isolated worker processes and its module graph must stay
+ * worker-local (guardrail G1) — this module is pure path/shape vocabulary.
+ */
+/** Session-dir-relative name of the replacement-epoch disk witness
+ *  (openspec: next-webpack-served-transform-coherence, design D2;
+ *  session-scoped by next-turbopack-served-transform-coherence D2). */
+export declare const REPLACEMENT_EPOCH_ARTIFACT = "replacements-epoch";
+/** Session-dir-relative name of the analysis-commit transaction artifact
+ *  (design D1). */
+export declare const ANALYSIS_COMMIT_ARTIFACT = "analysis-commit";
+/** Session-dir-relative name of the analysis-status artifact (design D3). */
+export declare const ANALYSIS_STATUS_ARTIFACT = "analysis-status.json";
+/** Session-dir-relative name of the manifest payload artifact. */
+export declare const MANIFEST_ARTIFACT = "manifest.json";
+/** Session-dir-relative name of the analysis-inputs payload artifact
+ *  (Turbopack loader-worker hydration corpus). */
+export declare const ANALYSIS_INPUTS_ARTIFACT = "analysis-inputs.json";
+/** Session-dir-relative name of the emitted stylesheet artifact. */
+export declare const STYLES_ARTIFACT = "styles.css";
+/** Session-dir-relative name of the emitted system-props module. */
+export declare const SYSTEM_PROPS_ARTIFACT = "system-props.js";
+/** Session-dir-relative directory holding copied asset() files. */
+export declare const SESSION_ASSETS_DIR = "assets";
+/** Root of every session-scoped artifact tree for a project. */
+export declare function sessionsRootDir(rootDir: string): string;
+/** One session's artifact directory (design D2: session-scoped trees,
+ *  no global pointer). */
+export declare function sessionArtifactDir(rootDir: string, sessionId: string): string;
+/** Absolute path of a session's replacement-epoch artifact — the single
+ *  derivation shared by the session writer, the webpack plugin's
+ *  watch-ignore entry, and both loaders' file dependencies. Takes the
+ *  SESSION directory (not the project root) since the artifact was
+ *  relocated into the session tree. */
+export declare function replacementEpochPath(sessionDir: string): string;
+/** Absolute path of a session's analysis-commit artifact. */
+export declare function analysisCommitPath(sessionDir: string): string;
+/** Absolute path of a session's analysis-status artifact. */
+export declare function analysisStatusPath(sessionDir: string): string;
+/** Absolute path of a session's manifest artifact. */
+export declare function manifestPath(sessionDir: string): string;
+/** Absolute path of a session's analysis-inputs artifact. */
+export declare function analysisInputsPath(sessionDir: string): string;
+/** Absolute path of a session's stylesheet artifact. */
+export declare function stylesPath(sessionDir: string): string;
+/** Absolute path of a session's system-props module artifact. */
+export declare function systemPropsPath(sessionDir: string): string;
+/** Session-scoped analysis-status shape (design D3). Successful loader
+ *  invocations never depend on it; it exists so a loader observing a
+ *  source/commit mismatch can decide — on evidence — whether to wait. */
+export interface AnalysisStatus {
+    schema: 1;
+    sessionId: string;
+    attemptId: number;
+    state: 'starting' | 'debouncing' | 'analyzing' | 'committing' | 'idle' | 'failed';
+    /** [(rootDir-relative sourceKey, observed content hash)] of the batch. */
+    pending: Array<[string, string]>;
+    /** Epoch-ms deadline for the active attempt (debounce ceiling + 2s). */
+    deadlineAt: number;
+    diagnostic?: string;
+}
+/** analysis-commit artifact shape (design D1: the transaction identity —
+ *  hashes are of the DISK payload bytes, envelope included). `inputsHash`
+ *  is present only when the hydration corpus is persisted (Turbopack
+ *  orchestration); webpack-mode commits omit it (spec:
+ *  next-turbopack-integration, "Webpack mode skips the hydration corpus"). */
+export interface AnalysisCommit {
+    schema: 1;
+    sessionId: string;
+    generation: number;
+    replacementEpoch: string;
+    manifestHash: string;
+    inputsHash?: string;
+    stylesHash: string;
+}
+/** Envelope embedded in every payload artifact (design D2: sessionId in
+ *  every artifact; payloadHash lets a same-session restart seed its write
+ *  guards without byte-reconstructing the payload). */
+export interface SessionEnvelope {
+    sessionId: string;
+    generation: number;
+    replacementEpoch: string;
+    payloadHash: string;
+}
+/** Splice the session envelope into a JSON-object payload as a leading
+ *  `__animusSession` field, byte-preserving the payload's own content
+ *  (parse/re-stringify could reformat engine-emitted JSON). */
+export declare function envelopeJsonArtifact(payload: string, envelopeJson: string): string;
+/** Trailing-comment side-band for the CSS artifact (a leading comment
+ *  would displace the @layer declaration consumers pin at offset 0). */
+export declare function envelopeCssArtifact(payload: string, envelopeJson: string): string;
+/** Matches the CSS artifact's envelope side-band. */
+export declare const ENVELOPE_CSS_COMMENT_RE: RegExp;
+/** Envelope of a JSON artifact's bytes, or undefined when the artifact
+ *  carries none. THROWS on unparseable bytes — callers decide whether a
+ *  torn artifact fails closed or degrades. */
+export declare function readJsonEnvelope(bytes: string): SessionEnvelope | undefined;
+/** Envelope of the CSS artifact's side-band comment, or undefined when the
+ *  side-band is absent. THROWS on an unparseable envelope body. */
+export declare function readCssEnvelope(bytes: string): SessionEnvelope | undefined;
+//# sourceMappingURL=session-paths.d.ts.map

package/dist/session-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-paths.d.ts","sourceRoot":"","sources":["../src/session-paths.ts"],"names":[],"mappings":"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"}

package/dist/singleton-372wiSRr.mjs

@@ -0,0 +1,202 @@
+import { S as __require } from "./session-paths-DfYIPDcM.mjs";
+import { createV2EngineApi } from "@animus-ui/extract/pipeline";
+import { randomUUID } from "crypto";
+//#region src/singleton.ts
+/**
+* Module-scope singleton for sharing analysis state between the webpack plugin and loader.
+*
+* Uses globalThis to survive the ESM/CJS module boundary: the plugin is loaded via ESM
+* (next.config.ts import) while the loader is loaded by webpack via require(). Without
+* globalThis, each module system gets its own singleton instance.
+*/
+const MANIFEST_KEY = "__animus_manifest_json__";
+const PROMISE_KEY = "__animus_analysis_promise__";
+const SHARED_CSS_KEY = "__animus_shared_css__";
+const SHARED_SYSTEM_PROPS_KEY = "__animus_shared_system_props__";
+const SHARED_EXTERNAL_DIRS_KEY = "__animus_external_pkg_dirs__";
+const SHARED_EXTERNAL_ENTRIES_KEY = "__animus_external_source_entries__";
+function getManifestJson() {
+	return globalThis[MANIFEST_KEY];
+}
+function setManifestJson(json) {
+	globalThis[MANIFEST_KEY] = json;
+}
+function getAnalysisPromise() {
+	return globalThis[PROMISE_KEY];
+}
+function setAnalysisPromise(promise) {
+	globalThis[PROMISE_KEY] = promise;
+}
+function resetAnalysisPromise() {
+	globalThis[PROMISE_KEY] = null;
+}
+function getSharedCss() {
+	return globalThis[SHARED_CSS_KEY] || "";
+}
+function setSharedCss(css) {
+	globalThis[SHARED_CSS_KEY] = css;
+}
+function setSharedSystemProps(content) {
+	globalThis[SHARED_SYSTEM_PROPS_KEY] = content;
+}
+function getSharedExternalDirs() {
+	return globalThis[SHARED_EXTERNAL_DIRS_KEY] || [];
+}
+function setSharedExternalDirs(dirs) {
+	globalThis[SHARED_EXTERNAL_DIRS_KEY] = dirs;
+}
+function getSharedExternalEntries() {
+	return globalThis[SHARED_EXTERNAL_ENTRIES_KEY] || /* @__PURE__ */ new Map();
+}
+function setSharedExternalEntries(entries) {
+	globalThis[SHARED_EXTERNAL_ENTRIES_KEY] = entries;
+}
+/** One typed globalThis slot — the single accessor shape every
+*  singleton-published value shares (null when unset). */
+function globalSlot(key) {
+	const store = globalThis;
+	return {
+		get: () => store[key] ?? null,
+		set: (value) => {
+			store[key] = value;
+		}
+	};
+}
+const ANALYZED_HASHES_KEY = "__animus_analyzed_hashes__";
+const REPLACEMENT_EPOCH_KEY = "__animus_replacement_epoch__";
+const WATCH_TRANSACTION_KEY = "__animus_watch_transaction__";
+const PROCESS_SESSION_ID_KEY = "__animus_process_session_id__";
+const SESSION_ARTIFACT_DIR_KEY = "__animus_session_artifact_dir__";
+const analyzedHashesSlot = globalSlot(ANALYZED_HASHES_KEY);
+const replacementEpochSlot = globalSlot(REPLACEMENT_EPOCH_KEY);
+const watchTransactionSlot = globalSlot(WATCH_TRANSACTION_KEY);
+const sessionArtifactDirSlot = globalSlot(SESSION_ARTIFACT_DIR_KEY);
+/**
+* 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.
+*/
+function getAnalyzedHashes() {
+	return analyzedHashesSlot.get();
+}
+function setAnalyzedHashes(hashes) {
+	analyzedHashesSlot.set(hashes);
+}
+/**
+* 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.
+*/
+function claimProcessSessionId() {
+	const store = globalThis;
+	const existing = store[PROCESS_SESSION_ID_KEY];
+	if (typeof existing === "string" && existing.length > 0) return existing;
+	const fresh = randomUUID();
+	store[PROCESS_SESSION_ID_KEY] = fresh;
+	return fresh;
+}
+/**
+* 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).
+*/
+function getSessionArtifactDir() {
+	return sessionArtifactDirSlot.get();
+}
+function setSessionArtifactDir(dir) {
+	sessionArtifactDirSlot.set(dir);
+}
+/**
+* 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.)
+*/
+function getReplacementEpoch() {
+	return replacementEpochSlot.get();
+}
+function setReplacementEpoch(epoch) {
+	replacementEpochSlot.set(epoch);
+}
+/**
+* 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.
+*/
+function getWatchTransaction() {
+	return watchTransactionSlot.get();
+}
+function setWatchTransaction(transaction) {
+	watchTransactionSlot.set(transaction);
+}
+const ENGINE_KEY = "__animus_engine__";
+/** Engine selection travels through the singleton so non-owning compiler
+*  instances and the webpack loader honor the same choice as the owner. */
+function setSharedEngine(engine) {
+	globalThis[ENGINE_KEY] = engine;
+}
+function getSharedEngine() {
+	return globalThis[ENGINE_KEY] || "v2";
+}
+/** Single engine choke-point for every native extraction call. Return type
+*  mirrors the untyped `require` the call sites previously used — the NAPI
+*  module's own .d.ts is the authoritative surface. */
+function requireEngine() {
+	return __require("@animus-ui/extract");
+}
+const V2_ENGINE_KEY = "__animus_v2_engine__";
+/**
+* Engine-agnostic API over both engines (extract-v2-spine row 13). The
+* v2 leg adapts the v1 function surface onto a stateful ExtractEngine
+* (hoisted to `createV2EngineApi` in @animus-ui/extract/pipeline — the
+* single authoritative copy shared with vite-plugin). The engine INSTANCE,
+* its analyze-time sources, and the one-shot drift flag all live on
+* globalThis for the same reason the manifest does — the ESM plugin and the
+* CJS webpack loader must see one engine (and one drift warning) across the
+* double-load. (The next-plugin is already process-singleton by design:
+* manifest, css, and system props share the same globalThis keys.)
+* loadSystemModule is exported by both bindings from one engine-neutral
+* Rust crate, so the default path no longer loads the v1 binary.
+*/
+const V2_SENT_SOURCES_KEY = "__animus_v2_sent_sources__";
+const V2_DRIFT_WARNED_KEY = "__animus_v2_drift_warned__";
+const v2EngineApi = createV2EngineApi({
+	label: "animus-next",
+	isV2: () => getSharedEngine() === "v2",
+	loadNativeEngine: requireEngine,
+	passThroughUnknownPaths: true,
+	store: {
+		getEngine: () => globalThis[V2_ENGINE_KEY],
+		setEngine: (engine) => {
+			globalThis[V2_ENGINE_KEY] = engine;
+		},
+		getSentSources: () => globalThis[V2_SENT_SOURCES_KEY] ?? null,
+		setSentSources: (sources) => {
+			globalThis[V2_SENT_SOURCES_KEY] = sources;
+		},
+		getDriftWarned: () => Boolean(globalThis[V2_DRIFT_WARNED_KEY]),
+		setDriftWarned: (value) => {
+			globalThis[V2_DRIFT_WARNED_KEY] = value;
+		}
+	}
+});
+function engineApi() {
+	return v2EngineApi();
+}
+//#endregion
+export { setWatchTransaction as C, setSharedSystemProps as S, setSessionArtifactDir as _, getManifestJson as a, setSharedExternalDirs as b, getSharedCss as c, getWatchTransaction as d, resetAnalysisPromise as f, setReplacementEpoch as g, setManifestJson as h, getAnalyzedHashes as i, getSharedExternalDirs as l, setAnalyzedHashes as m, engineApi as n, getReplacementEpoch as o, setAnalysisPromise as p, getAnalysisPromise as r, getSessionArtifactDir as s, claimProcessSessionId as t, getSharedExternalEntries as u, setSharedCss as v, setSharedExternalEntries as x, setSharedEngine as y };

package/dist/{singleton-DH7yeWZa.cjs → singleton-D4vhawsW.cjs}

@@ -1,4 +1,6 @@
+require("./turbopack-loader.cjs");
 let _animus_ui_extract_pipeline = require("@animus-ui/extract/pipeline");
+let crypto = require("crypto");
 //#region src/singleton.ts
 /**
 * Module-scope singleton for sharing analysis state between the webpack plugin and loader.
@@ -49,6 +51,99 @@ function getSharedExternalEntries() {
 function setSharedExternalEntries(entries) {
 	globalThis[SHARED_EXTERNAL_ENTRIES_KEY] = entries;
 }
+/** One typed globalThis slot — the single accessor shape every
+*  singleton-published value shares (null when unset). */
+function globalSlot(key) {
+	const store = globalThis;
+	return {
+		get: () => store[key] ?? null,
+		set: (value) => {
+			store[key] = value;
+		}
+	};
+}
+const ANALYZED_HASHES_KEY = "__animus_analyzed_hashes__";
+const REPLACEMENT_EPOCH_KEY = "__animus_replacement_epoch__";
+const WATCH_TRANSACTION_KEY = "__animus_watch_transaction__";
+const PROCESS_SESSION_ID_KEY = "__animus_process_session_id__";
+const SESSION_ARTIFACT_DIR_KEY = "__animus_session_artifact_dir__";
+const analyzedHashesSlot = globalSlot(ANALYZED_HASHES_KEY);
+const replacementEpochSlot = globalSlot(REPLACEMENT_EPOCH_KEY);
+const watchTransactionSlot = globalSlot(WATCH_TRANSACTION_KEY);
+const sessionArtifactDirSlot = globalSlot(SESSION_ARTIFACT_DIR_KEY);
+/**
+* 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.
+*/
+function getAnalyzedHashes() {
+	return analyzedHashesSlot.get();
+}
+function setAnalyzedHashes(hashes) {
+	analyzedHashesSlot.set(hashes);
+}
+/**
+* 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.
+*/
+function claimProcessSessionId() {
+	const store = globalThis;
+	const existing = store[PROCESS_SESSION_ID_KEY];
+	if (typeof existing === "string" && existing.length > 0) return existing;
+	const fresh = (0, crypto.randomUUID)();
+	store[PROCESS_SESSION_ID_KEY] = fresh;
+	return fresh;
+}
+/**
+* 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).
+*/
+function getSessionArtifactDir() {
+	return sessionArtifactDirSlot.get();
+}
+function setSessionArtifactDir(dir) {
+	sessionArtifactDirSlot.set(dir);
+}
+/**
+* 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.)
+*/
+function getReplacementEpoch() {
+	return replacementEpochSlot.get();
+}
+function setReplacementEpoch(epoch) {
+	replacementEpochSlot.set(epoch);
+}
+/**
+* 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.
+*/
+function getWatchTransaction() {
+	return watchTransactionSlot.get();
+}
+function setWatchTransaction(transaction) {
+	watchTransactionSlot.set(transaction);
+}
 const ENGINE_KEY = "__animus_engine__";
 /** Engine selection travels through the singleton so non-owning compiler
 *  instances and the webpack loader honor the same choice as the owner. */
@@ -104,6 +199,12 @@ function engineApi() {
 	return v2EngineApi();
 }
 //#endregion
+Object.defineProperty(exports, "claimProcessSessionId", {
+	enumerable: true,
+	get: function() {
+		return claimProcessSessionId;
+	}
+});
 Object.defineProperty(exports, "engineApi", {
 	enumerable: true,
 	get: function() {
@@ -116,12 +217,30 @@ Object.defineProperty(exports, "getAnalysisPromise", {
 		return getAnalysisPromise;
 	}
 });
+Object.defineProperty(exports, "getAnalyzedHashes", {
+	enumerable: true,
+	get: function() {
+		return getAnalyzedHashes;
+	}
+});
 Object.defineProperty(exports, "getManifestJson", {
 	enumerable: true,
 	get: function() {
 		return getManifestJson;
 	}
 });
+Object.defineProperty(exports, "getReplacementEpoch", {
+	enumerable: true,
+	get: function() {
+		return getReplacementEpoch;
+	}
+});
+Object.defineProperty(exports, "getSessionArtifactDir", {
+	enumerable: true,
+	get: function() {
+		return getSessionArtifactDir;
+	}
+});
 Object.defineProperty(exports, "getSharedCss", {
 	enumerable: true,
 	get: function() {
@@ -140,6 +259,12 @@ Object.defineProperty(exports, "getSharedExternalEntries", {
 		return getSharedExternalEntries;
 	}
 });
+Object.defineProperty(exports, "getWatchTransaction", {
+	enumerable: true,
+	get: function() {
+		return getWatchTransaction;
+	}
+});
 Object.defineProperty(exports, "resetAnalysisPromise", {
 	enumerable: true,
 	get: function() {
@@ -152,12 +277,30 @@ Object.defineProperty(exports, "setAnalysisPromise", {
 		return setAnalysisPromise;
 	}
 });
+Object.defineProperty(exports, "setAnalyzedHashes", {
+	enumerable: true,
+	get: function() {
+		return setAnalyzedHashes;
+	}
+});
 Object.defineProperty(exports, "setManifestJson", {
 	enumerable: true,
 	get: function() {
 		return setManifestJson;
 	}
 });
+Object.defineProperty(exports, "setReplacementEpoch", {
+	enumerable: true,
+	get: function() {
+		return setReplacementEpoch;
+	}
+});
+Object.defineProperty(exports, "setSessionArtifactDir", {
+	enumerable: true,
+	get: function() {
+		return setSessionArtifactDir;
+	}
+});
 Object.defineProperty(exports, "setSharedCss", {
 	enumerable: true,
 	get: function() {
@@ -188,3 +331,9 @@ Object.defineProperty(exports, "setSharedSystemProps", {
 		return setSharedSystemProps;
 	}
 });
+Object.defineProperty(exports, "setWatchTransaction", {
+	enumerable: true,
+	get: function() {
+		return setWatchTransaction;
+	}
+});

package/dist/singleton.d.ts

@@ -10,6 +10,56 @@ 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;
+/**
+ * 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 +70,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_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;AA4BD;;;;;;;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,kdAgBxB,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"}