@animus-ui/extract 0.1.9 → 0.1.11

package/dist/session.mjs

@@ -0,0 +1,2110 @@
+import { A as createSourceIngestor, B as extractSystemFilePackages, C as resolveLightningTargets, E as resolveAssetFile, G as staleDistIncludesMessage, H as firstOwners, J as createSourceIdentity, K as unresolvableIncludesMessage, N as withoutInvalidOriginals, O as findAssetSpecifiers, P as DEFAULT_EXTENSIONS, R as collectExternalPackageSources, S as postProcessCss, T as enforceExternalTokenContracts, U as isExcludedPackageRelativePath, V as findPackageRoot, X as sharesVolumeRoot, Y as isPathWithinRoot, Z as discoverFiles, _ as runProjectAnalysis, a as snapshotFilePlans, at as createExcludeMatcher, c as formatRustTimingWaterfall, f as loadSystemConfig, g as clearEngineCache, gt as assembleStylesheet, i as hashReplacementPlans, k as substituteAssetPlaceholders, l as buildSystemPropsModule, lt as mergeExternalKeyframes, m as serializeStaticCss, o as assertNoErrorDiagnostics, ot as resolveMode, pt as createV2EngineApi, q as walkPackageSources, t as toWatchKeys, ut as contentHash, yt as __require, z as excludeCollectedPackages } from "./pipeline-lkbOoyAr.mjs";
+import { randomUUID } from "crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync } from "fs";
+import { basename, extname, join, relative, resolve } from "path";
+//#region session/session-paths.ts
+/**
+* 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). */
+const REPLACEMENT_EPOCH_ARTIFACT = "replacements-epoch";
+/** Virtual module id of the emitted system-props module — session
+*  vocabulary shared by the orchestrator and the Turbopack config
+*  assembly (hoisted here so the session home stays framework-free). */
+const TURBOPACK_SYSTEM_PROPS_ID = "virtual:animus/system-props";
+/** Session-dir-relative name of the analysis-commit transaction artifact
+*  (design D1). */
+const ANALYSIS_COMMIT_ARTIFACT = "analysis-commit";
+/** Session-dir-relative name of the analysis-status artifact (design D3). */
+const ANALYSIS_STATUS_ARTIFACT = "analysis-status.json";
+/** Session-dir-relative name of the manifest payload artifact. */
+const MANIFEST_ARTIFACT = "manifest.json";
+/** Session-dir-relative name of the analysis-inputs payload artifact
+*  (Turbopack loader-worker hydration corpus). */
+const ANALYSIS_INPUTS_ARTIFACT = "analysis-inputs.json";
+/** Session-dir-relative name of the emitted stylesheet artifact. */
+const STYLES_ARTIFACT = "styles.css";
+/** Session-dir-relative name of the emitted system-props module. */
+const SYSTEM_PROPS_ARTIFACT = "system-props.js";
+/** Session-dir-relative directory holding copied asset() files. */
+const SESSION_ASSETS_DIR = "assets";
+/** The standalone CLI's published-set commit record, written into the flat
+*  `.animus/` tree (openspec: standalone-extraction-cli D3). Shared here so
+*  the CLI writer and the session's start hygiene agree on ONE name — the
+*  hygiene confinement gate keys on this record, and a renamed literal on
+*  either side would silently re-arm deletion of the CLI's published output. */
+const CLI_COMMIT_ARTIFACT = "commit.json";
+/** The standalone CLI's single-writer advisory lock in the flat `.animus/`
+*  tree. A live holder means a CLI invocation owns that tree right now. */
+const CLI_LOCK_ARTIFACT = "lock.json";
+/** Root of every session-scoped artifact tree for a project. */
+function sessionsRootDir(rootDir) {
+	return join(rootDir, ".animus", "sessions");
+}
+/** One session's artifact directory (design D2: session-scoped trees,
+*  no global pointer). */
+function sessionArtifactDir(rootDir, sessionId) {
+	return join(sessionsRootDir(rootDir), sessionId);
+}
+/** 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. */
+function replacementEpochPath(sessionDir) {
+	return join(sessionDir, REPLACEMENT_EPOCH_ARTIFACT);
+}
+/** Absolute path of a session's analysis-commit artifact. */
+function analysisCommitPath(sessionDir) {
+	return join(sessionDir, ANALYSIS_COMMIT_ARTIFACT);
+}
+/** Absolute path of a session's analysis-status artifact. */
+function analysisStatusPath(sessionDir) {
+	return join(sessionDir, ANALYSIS_STATUS_ARTIFACT);
+}
+/** Absolute path of a session's manifest artifact. */
+function manifestPath(sessionDir) {
+	return join(sessionDir, MANIFEST_ARTIFACT);
+}
+/** Absolute path of a session's analysis-inputs artifact. */
+function analysisInputsPath(sessionDir) {
+	return join(sessionDir, ANALYSIS_INPUTS_ARTIFACT);
+}
+/** Absolute path of a session's stylesheet artifact. */
+function stylesPath(sessionDir) {
+	return join(sessionDir, STYLES_ARTIFACT);
+}
+/** Absolute path of a session's system-props module artifact. */
+function systemPropsPath(sessionDir) {
+	return join(sessionDir, SYSTEM_PROPS_ARTIFACT);
+}
+/** 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). */
+function envelopeJsonArtifact(payload, envelopeJson) {
+	const trimmed = payload.trimStart();
+	if (!trimmed.startsWith("{")) return payload;
+	if (trimmed.slice(1).trimStart().startsWith("}")) return `{"__animusSession":${envelopeJson}}`;
+	return `{"__animusSession":${envelopeJson},${trimmed.slice(1)}`;
+}
+/** Trailing-comment side-band for the CSS artifact (a leading comment
+*  would displace the @layer declaration consumers pin at offset 0). */
+function envelopeCssArtifact(payload, envelopeJson) {
+	return `${payload}\n/* __animusSession ${envelopeJson} */\n`;
+}
+/** Matches the CSS artifact's envelope side-band. */
+const ENVELOPE_CSS_COMMENT_RE = /\/\* __animusSession (\{.*\}) \*\//;
+/** 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. */
+function readJsonEnvelope(bytes) {
+	return JSON.parse(bytes).__animusSession;
+}
+/** Envelope of the CSS artifact's side-band comment, or undefined when the
+*  side-band is absent. THROWS on an unparseable envelope body. */
+function readCssEnvelope(bytes) {
+	const match = bytes.match(ENVELOPE_CSS_COMMENT_RE);
+	return match ? JSON.parse(match[1]) : void 0;
+}
+//#endregion
+//#region session/published-set.ts
+/**
+* The CLI published-set contract, shared logic (openspec:
+* standalone-extraction-cli D3): ONE implementation of "does this flat
+* artifact set verify against its commit record" and ONE collector for the
+* session's copied asset() files — consumed by the CLI writer
+* (staging/verification) and the session's start hygiene (confinement
+* gate). Two copies of either had already drifted once: the hygiene copy
+* verified payloads as UTF-8 strings while the writer hashed raw bytes, so
+* any asset-carrying set (fonts are not UTF-8) could never verify and a
+* legitimately published set was classified as debris.
+*/
+/**
+* Recompute every payload hash recorded in the directory's commit record
+* and compare — raw bytes on both sides, matching the writer's hashing
+* domain. Returns failure lines; empty means the set verifies. An absent
+* or unparsable record is itself a failure (the record is written LAST, so
+* a torn or aborted publish cannot verify).
+*/
+function verifyCommitRecord(dir) {
+	let record;
+	try {
+		record = JSON.parse(readFileSync(join(dir, CLI_COMMIT_ARTIFACT), "utf-8"));
+	} catch (error) {
+		return [`commit record unreadable: ${String(error)}`];
+	}
+	if (record.schema !== 1 || typeof record.payloads !== "object" || record.payloads === null) return ["commit record is not a schema-1 payload record"];
+	const failures = [];
+	for (const [name, entry] of Object.entries(record.payloads)) try {
+		if (contentHash(readFileSync(join(dir, name))) !== entry?.hash) failures.push(`${name}: bytes do not match the commit record`);
+	} catch (error) {
+		failures.push(`${name}: unreadable (${String(error)})`);
+	}
+	return failures;
+}
+/**
+* Snapshot the session's copied asset() files (sorted by name) — read
+* BEFORE the session tree is disposed. The emitted stylesheet references
+* them as `./assets/<name>`, so every driver must publish them beside its
+* stylesheet or the urls dangle.
+*/
+function collectSessionAssets(sessionDir) {
+	if (!sessionDir) return [];
+	const dir = join(sessionDir, SESSION_ASSETS_DIR);
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).sort().map((name) => ({
+		name,
+		bytes: readFileSync(join(dir, name))
+	}));
+}
+//#endregion
+//#region session/resolve-packages.ts
+/**
+* Resolve external DS package specifiers to rootDir-relative entry paths.
+* Node-generic (no webpack APIs): Pass 1 walks the consumer's workspaces for
+* matching package names; Pass 2 falls back to `require.resolve`. Specifiers
+* that resolve nowhere are simply omitted (spec: silent skip).
+*/
+function resolvePackagesByName(rootDir, names) {
+	if (names.length === 0) return {};
+	const nameSet = new Set(names);
+	const resolved = /* @__PURE__ */ new Set();
+	const packageMap = {};
+	try {
+		const rootPkg = JSON.parse(readFileSync(join(rootDir, "package.json"), "utf-8"));
+		const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages ?? [];
+		for (const ws of workspaces) {
+			const wsDir = resolve(rootDir, ws);
+			if (!existsSync(wsDir)) continue;
+			try {
+				const pkg = JSON.parse(readFileSync(join(wsDir, "package.json"), "utf-8"));
+				const name = pkg.name || "";
+				if (nameSet.has(name)) {
+					const entryPath = resolve(wsDir, pkg.main || pkg.module || "index.ts");
+					if (existsSync(entryPath)) {
+						packageMap[name] = relative(rootDir, entryPath);
+						resolved.add(name);
+					}
+				}
+			} catch {}
+		}
+	} catch {}
+	for (const name of nameSet) {
+		if (resolved.has(name)) continue;
+		try {
+			packageMap[name] = relative(rootDir, __require.resolve(name, { paths: [rootDir] }));
+		} catch {}
+	}
+	return packageMap;
+}
+//#endregion
+//#region session/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 getSharedSystemProps() {
+	return globalThis[SHARED_SYSTEM_PROPS_KEY] || "";
+}
+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 OWNING_WATCH_SESSION_KEY = "__animus_owning_watch_session__";
+const EXCLUSIVE_SESSION_OWNER_KEY = "__animus_exclusive_session_owner__";
+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);
+const owningWatchSessionSlot = globalSlot(OWNING_WATCH_SESSION_KEY);
+/**
+* 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).
+*/
+function getOwningWatchSession() {
+	return owningWatchSessionSlot.get();
+}
+function setOwningWatchSession(session) {
+	owningWatchSessionSlot.set(session);
+}
+/**
+* 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;
+}
+/**
+* Exclusive-ownership claim over the process-global session state — the
+* hard form of the invariant `claimProcessSessionId` documents softly. The
+* shared slots above (manifest, css, artifact dir) plus the one session id
+* mean two CONCURRENT drive loops in one process (a webpack MultiCompiler
+* array config, parallel rollup array builds, two programmatic CLI runs)
+* would share one session directory, overwrite each other's manifests, and
+* delete each other's live trees on dispose. Drivers that run the loop
+* exclusively (the unplugin host) claim for the build's lifetime and
+* release on dispose; SEQUENTIAL claim/release cycles are legal. The Next
+* multi-compiler adoption path stays the non-exclusive default. Throws
+* naming both hosts and the remediation on overlap. The key lives in
+* `SINGLETON_GLOBAL_KEYS`, so per-test global resets clear a leaked claim.
+*/
+function claimExclusiveSessionOwner(label) {
+	const store = globalThis;
+	const active = store[EXCLUSIVE_SESSION_OWNER_KEY];
+	if (typeof active === "string") throw new Error(`[animus] a second Animus host ("${label}") started while "${active}" is still active in this process. The extraction session is process-global (one session tree, one manifest), so concurrent hosts would clobber each other's analysis. Run one Animus-enabled config per process, or make the builds sequential.`);
+	store[EXCLUSIVE_SESSION_OWNER_KEY] = label;
+	return () => {
+		if (store[EXCLUSIVE_SESSION_OWNER_KEY] === label) delete store[EXCLUSIVE_SESSION_OWNER_KEY];
+	};
+}
+/**
+* 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",
+	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;
+		}
+	}
+});
+const ENGINE_API_OVERRIDE_KEY = "__animus_engine_api_override__";
+function engineApi() {
+	const override = globalThis[ENGINE_API_OVERRIDE_KEY];
+	return override ? override() : v2EngineApi();
+}
+//#endregion
+//#region session/timing.ts
+/**
+* Verbose build-timing waterfall: JS phases, analysis sub-phases, and the
+* shared Rust phase table. `ANIMUS_TIMING_JSON=1` additionally dumps a
+* machine-readable merged record.
+*/
+function logBuildTimings(bt, rustTiming, log, verbose) {
+	if (!verbose) return;
+	const pad = (label, width) => label + " ".repeat(Math.max(0, width - label.length));
+	for (const [key, label] of [
+		["systemLoad", "system-load"],
+		["fileDiscovery", "file-discovery"],
+		["fileRead", "file-read+hash"],
+		["packageResolve", "pkg-resolve"],
+		["analysis", "analysis"]
+	]) {
+		const ms = bt[key] ?? 0;
+		if (ms === 0 && !Object.hasOwn(bt, key)) continue;
+		log(`  ${pad(label, 17)}${String(ms).padStart(5)}ms`);
+		if (key === "analysis") for (const [sk, sl] of [
+			["jsonSerialize", "json-serialize"],
+			["rustExtract", "rust-extract"],
+			["jsonParse", "json-parse"]
+		]) {
+			const sms = bt[sk] ?? 0;
+			log(`    ${pad(sl, 15)}${String(sms).padStart(5)}ms`);
+			if (sk === "rustExtract" && rustTiming) for (const line of formatRustTimingWaterfall(rustTiming, {
+				indent: "      ",
+				labelWidth: 13
+			})) log(line);
+		}
+	}
+	log(`  total             ${String(bt.total).padStart(5)}ms`);
+	if (process.env.ANIMUS_TIMING_JSON === "1") {
+		const merged = {};
+		for (const [k, v] of Object.entries(bt)) merged[`buildStart.${k}`] = v;
+		if (rustTiming) {
+			for (const [k, v] of Object.entries(rustTiming)) if (typeof v === "number") merged[`rust.${k}`] = v;
+		}
+		console.error(`[animus:timing] ${JSON.stringify(merged)}`);
+	}
+}
+//#endregion
+//#region session/extraction-session.ts
+/**
+* Module id the Rust emitter injects for the extracted stylesheet — also the
+* exact resolve.alias key with-animus registers for it, which the adapter's
+* alias harvesting must skip.
+*/
+const ANIMUS_CSS_MODULE_ID = ".animus/styles.css";
+/** Retention window for sibling session directories (design D2). */
+const SESSION_DIR_MAX_AGE_MS = 1440 * 60 * 1e3;
+/** Watchdog added to the debounce ceiling for status deadlines (D3). */
+const STATUS_WATCHDOG_MS = 2e3;
+/** Flat legacy `.animus/` artifacts removed at session start — unreachable
+*  by session-scoped loaders. The standalone CLI still publishes the three
+*  payload names flat; its verified/live sets are fenced off inside
+*  `runSessionStartHygiene`. */
+const LEGACY_FLAT_ARTIFACTS = [
+	MANIFEST_ARTIFACT,
+	ANALYSIS_INPUTS_ARTIFACT,
+	STYLES_ARTIFACT,
+	SYSTEM_PROPS_ARTIFACT,
+	REPLACEMENT_EPOCH_ARTIFACT,
+	ANALYSIS_COMMIT_ARTIFACT,
+	ANALYSIS_STATUS_ARTIFACT
+];
+/**
+* Bundler-agnostic extraction pipeline: system loading, source discovery
+* and ingestion, external-package collection, analysis, stylesheet and
+* system-props emission, and watch-cycle diffing.
+*
+* The webpack adapter (plugin.ts) owns only bundler wiring: hook
+* registration, alias harvesting from the compiler config, in-memory asset
+* replacement, and translating watch events into `handleWatchUpdate`
+* change sets. Keeping this class free of webpack types is deliberate — a
+* future Turbopack integration must drive the same session from outside
+* the bundler (Turbopack has no compiler-hook surface), reusing everything
+* here unchanged.
+*
+* Outputs are published through the package singleton (shared CSS,
+* manifest, system props) and written to `.animus/` on disk.
+*/
+var ExtractionSession = class {
+	/** Set by the adapter before any pipeline run. */
+	rootDir = null;
+	/** Serialized path aliases, harvested by the adapter from bundler config. */
+	pathAliasesJson = null;
+	assetCopyCache = /* @__PURE__ */ new Map();
+	/** Physical asset files registered with the host watcher. */
+	assetDependencyPaths = /* @__PURE__ */ new Set();
+	assetDependencyKeys = /* @__PURE__ */ new Set();
+	/** Emitter identity override for the system-props module id. Webpack mode
+	*  (null) injects the absolute `.animus/system-props.js` path, resolved by
+	*  NormalModuleReplacement; Turbopack rejects absolute-path imports, so
+	*  its driver sets the virtual id that `resolveAlias` maps to disk. */
+	systemPropsModuleId = null;
+	/** Whether the analysis-inputs hydration corpus is serialized + written.
+	*  False (webpack mode): the loader shares the pipeline process and reads
+	*  the manifest from memory — the corpus is never persisted. True is set
+	*  by the Turbopack orchestration driver, whose isolated loader workers
+	*  replay it (spec: next-turbopack-integration, "Manifest disk artifact" /
+	*  "Webpack mode skips the hydration corpus"). */
+	persistAnalysisInputs = false;
+	/** Absolute directory prefixes for external DS packages (loader allowlisting). */
+	externalPackageDirs = [];
+	/** Absolute package dir → owning specifier (cross-source correlation). */
+	externalDirOwners = {};
+	/** rootDir-relative external file → owning specifier (correlation join). */
+	externalFileOwners = {};
+	/** External package specifier → absolute source entry path. */
+	externalSourceEntries = /* @__PURE__ */ new Map();
+	/** SourceId derivation authority for the current generation (openspec:
+	*  external-source-watch-ingestion, design D2) — canonical roots
+	*  realpath'd once per full pipeline; alias→SourceId associations
+	*  recorded while files exist so deletion resolves through the cache. */
+	sourceIdentity = null;
+	/** Canonical admitted external root → declared specifiers (set-valued
+	*  ownership, design D2; duplicate specifiers resolving to one canonical
+	*  root share it). Engine watch wiring and tests read this. */
+	externalRootOwners = /* @__PURE__ */ new Map();
+	/** Canonical external root → the extension set its collection walk used
+	*  (widened for dist-only roots); rewalks and classification share it. */
+	externalRootExtensions = /* @__PURE__ */ new Map();
+	/** Canonical admitted external watch roots — the engine-side watch
+	*  surface (webpack contextDependencies / Turbopack watchers). */
+	externalWatchRoots = [];
+	/** Canonical external root → (raw sourceKey → {raw content hash, recorded
+	*  abs spelling}): the previous-generation inventory a dirty-root rewalk
+	*  diffs against (design D3). Raw hashes — MDX preprocessing never skews
+	*  the diff; the recorded abs path is a registered deletion alias, so a
+	*  reconstructed deletion always resolves through cached identity. */
+	externalInventory = /* @__PURE__ */ new Map();
+	/** Sticky diagnostics (design D5/D7): stable key → message, re-surfaced
+	*  on every full pipeline until the underlying condition clears. */
+	stickyDiagnostics = /* @__PURE__ */ new Map();
+	/** Volume-membership predicate for the cross-volume gate (design D5).
+	*  Injected seam: the shared predicate only discriminates on Windows
+	*  (win32 semantics are unit-tested via path.win32), so runtime tests
+	*  drive the gate through this. */
+	sharesProjectVolume = sharesVolumeRoot;
+	/** Orchestrator seams (openspec: external-source-watch-ingestion, design
+	*  D4). `onExternalRootResolved` fires per volume-admitted external root
+	*  DURING collection — after resolution, BEFORE that root's sources are
+	*  walked — so a watching host can open its handle with no blind gap
+	*  between scan and watch. `onExternalRootsCommitted` fires once after a
+	*  successful full-pipeline publication with the complete admitted
+	*  canonical root set (the host's promote/replay/close-old phase; a
+	*  failed pipeline never fires it, so the host rolls back). */
+	onExternalRootResolved = null;
+	onExternalRootsCommitted = null;
+	options;
+	staticCssJson;
+	system = null;
+	/** Discovery-time keyframes diagnostics awaiting the shared surfacing pass. */
+	externalKeyframesDiagnostics = [];
+	/** Full package-resolution map from the last full pipeline — replayed by
+	*  incremental passes (sourceEntries alone omits dist-resolved packages). */
+	lastPackageMap = {};
+	fileCache = /* @__PURE__ */ new Map();
+	analysisEntryCache = /* @__PURE__ */ new Map();
+	sourceOwnership = {};
+	systemDependencyKeys = /* @__PURE__ */ new Set();
+	/** Loader-reported dependency paths for bundler watch registration. */
+	systemDependencyPaths = [];
+	systemDependencyHashes = /* @__PURE__ */ new Map();
+	lastSystemPropsHash = null;
+	/** Per-payload write guards: payloadHash gates rewrites (byte-identical
+	*  payloads leave disk untouched); diskHash is the hash of the CURRENT
+	*  disk bytes (envelope included) recorded in the analysis-commit. null =
+	*  not yet seeded (first publication reads the artifact's envelope so a
+	*  same-session restart never rewrites byte-identical artifacts). */
+	artifactRecords = {
+		manifest: null,
+		inputs: null,
+		styles: null
+	};
+	/** Last written analysis-commit; null = seeded from disk on first use. */
+	lastCommit = null;
+	/** Session identity — claimed once per PROCESS (one Next invocation),
+	*  adopted by every subsequent session instance so all compilers share
+	*  one artifact tree (design D2: `next dev`/`next build` co-writing are
+	*  separate processes and therefore separate sessions). */
+	sessionId = claimProcessSessionId();
+	/** Epoch value of the last published analysis; null = not yet known
+	*  (seeded from the session dir's artifact on first publication so a
+	*  same-session restart with unchanged plans never rewrites bytes). */
+	lastEpochValue = null;
+	/** Watcher debounce ceiling feeding status deadlines (design D3). */
+	debounceCeilingMs = 75;
+	/** Test seam: observes every session-artifact write (name, content)
+	*  post-rename — write ORDER is part of the transaction contract. */
+	onArtifactWrite = null;
+	/** Status attempt bookkeeping (design D3). */
+	statusAttemptId = 0;
+	statusAttemptOpen = false;
+	/** Monotonic first-emission witness (openspec: standalone-extraction-cli,
+	*  watch readiness): flips true once the first complete publication
+	*  succeeds and never regresses — every later status write (idle AND
+	*  failed) carries it, so readiness stays observable across attempts. */
+	firstEmissionComplete = false;
+	/** Debounce-window observations pending analysis (sourceKey → hash). */
+	debouncePending = /* @__PURE__ */ new Map();
+	/** Session-start hygiene (pruning + legacy cleanup) runs once. */
+	sessionStartHygieneDone = false;
+	lcssTargets = null;
+	constructor(options) {
+		this.options = options;
+		this.staticCssJson = serializeStaticCss(options.staticCss);
+	}
+	/** This session's artifact directory. Requires `rootDir` to be set. */
+	get sessionDir() {
+		return sessionArtifactDir(this.rootDir, this.sessionId);
+	}
+	get verbose() {
+		return this.options.verbose === true || process.env.ANIMUS_DEBUG === "1" || process.env.ANIMUS_DEBUG === "true";
+	}
+	log(msg) {
+		if (this.verbose) console.error(`[animus] ${msg}`);
+	}
+	warn(msg) {
+		console.warn(`[animus] ${msg}`);
+	}
+	now() {
+		return this.verbose ? performance.now() : 0;
+	}
+	elapsed(t) {
+		return this.verbose ? Math.round(performance.now() - t) : 0;
+	}
+	/** Lazily-computed scan config (options are constructor-fixed, so the
+	*  derivation is stable for the session's lifetime). */
+	/** Diagnostic prefix label — drivers set their own so a host's errors
+	*  never masquerade as another driver's (inc 05 review S1). The default
+	*  keeps the Next plugin's historical prefix. */
+	driverLabel = "animus-next";
+	/** Per-specifier discovery outcomes from the last full collection —
+	*  driver-consumed reporting surface (the CLI's summary). */
+	lastExternalOutcomes = [];
+	/** Component count of the last published analysis, or null before the
+	*  first — the CLI's publish path reads this instead of re-parsing the
+	*  manifest JSON every cycle. */
+	lastComponentCount = null;
+	/** Driver-owned STRUCTURAL exclusions (a CLI outDir inside the root),
+	*  joined to the never-replaceable set — never the user `exclude` list,
+	*  whose presence would flip the replace semantics and silently drop the
+	*  replaceable defaults. Set before the first pipeline run (the scan
+	*  config is memoized). */
+	structuralExclude = [];
+	scanConfigMemo = null;
+	/** Per-pattern exclusion hit counts from this session's matcher —
+	*  driver-consumed reporting surface (dead-pattern visibility). */
+	getExcludeStats() {
+		return this.resolveScanConfig().excludeMatcher.stats();
+	}
+	/** Resolve the scan configuration from options — the single source of the
+	*  exclude/extension policy shared by the full and incremental pipelines. */
+	resolveScanConfig() {
+		if (this.scanConfigMemo === null) {
+			const extensionsSet = new Set(this.options.extensions ?? DEFAULT_EXTENSIONS);
+			this.scanConfigMemo = {
+				excludeMatcher: createExcludeMatcher(this.options.exclude, this.structuralExclude),
+				extensionsSet
+			};
+		}
+		return this.scanConfigMemo;
+	}
+	/**
+	* Watch entry point: one single-flight analysis transaction per event
+	* batch (openspec: next-webpack-served-transform-coherence, design D3).
+	* The first entering session runs the transaction; every concurrent
+	* entry — same session re-entered, or another compiler's session
+	* (client/server/RSC each hold their own instance) — joins the in-flight
+	* promise, so no compiler proceeds against a generation older than the
+	* one the transaction publishes. A rejected transaction rejects every
+	* joiner; the gate always clears.
+	*/
+	async handleWatchUpdate(changes) {
+		const inflight = getWatchTransaction();
+		if (inflight) {
+			await inflight;
+			return;
+		}
+		if (!this.system) {
+			const owner = getOwningWatchSession();
+			const hasBatch = (changes.modifiedFiles?.size ?? 0) > 0 || (changes.removedFiles?.size ?? 0) > 0;
+			if (owner && owner !== this && hasBatch) await owner.ingestForwardedBatch(changes);
+			return;
+		}
+		const transaction = this.processWatchUpdate(changes);
+		setWatchTransaction(transaction);
+		try {
+			await transaction;
+		} finally {
+			setWatchTransaction(null);
+		}
+	}
+	/**
+	* Owner-side entry for a batch observed by a NON-OWNING compiler's
+	* watcher. Serializes behind any in-flight transaction, then runs the
+	* forwarded batch as its own transaction — never drops it (a forwarded
+	* batch has no other delivery; content-hash diffing makes an
+	* already-covered batch a cheap no-op).
+	*/
+	async ingestForwardedBatch(changes) {
+		if (!this.system) return;
+		for (;;) {
+			const inflight = getWatchTransaction();
+			if (!inflight) break;
+			await inflight;
+		}
+		const transaction = this.processWatchUpdate(changes);
+		setWatchTransaction(transaction);
+		try {
+			await transaction;
+		} finally {
+			setWatchTransaction(null);
+		}
+	}
+	/**
+	* Incremental watch pass: geological reset when the system file changed,
+	* otherwise content-hash diffing restricted to the watcher's change sets
+	* (falling back to a full discovery walk when no sets are provided).
+	*/
+	async processWatchUpdate(changes) {
+		const rootDir = this.rootDir;
+		try {
+			changes = this.reconcileExternalRoots(changes);
+		} catch (err) {
+			this.warn(`external root reconciliation failed: ${String(err)}`);
+		}
+		const changed = [...changes.modifiedFiles ?? [], ...changes.removedFiles ?? []];
+		let assetChanged = false;
+		let systemHit;
+		try {
+			if (!changes.modifiedFiles && !changes.removedFiles) for (const [dep, hash] of this.systemDependencyHashes) {
+				let current = "";
+				try {
+					current = contentHash(readFileSync(dep, "utf-8"));
+				} catch {}
+				if (current !== hash) {
+					systemHit = dep;
+					break;
+				}
+			}
+			else systemHit = changed.find((path) => toWatchKeys(path).some((key) => this.systemDependencyKeys.has(key)));
+		} catch (err) {
+			this.warn(`HMR geological-reset check failed: ${String(err)}`);
+		}
+		if (systemHit) {
+			this.log(`geological reset: system dependency changed (${relative(rootDir, systemHit)})`);
+			this.resetForHmr();
+			try {
+				const promise = this.runFullPipeline(this.pendingFromBatch(changes));
+				setAnalysisPromise(promise);
+				await promise;
+			} catch (err) {
+				try {
+					this.beginStatusAttempt();
+					this.writeAnalysisStatus("failed", this.pendingFromBatch(changes), String(err));
+				} catch (statusErr) {
+					this.warn(`failed-status write failed: ${String(statusErr)}`);
+				}
+				throw err;
+			}
+			return;
+		}
+		if (changed.some((path) => toWatchKeys(path).some((key) => this.assetDependencyKeys.has(key)))) {
+			this.assetCopyCache.clear();
+			assetChanged = true;
+		}
+		const { excludeMatcher, extensionsSet } = this.resolveScanConfig();
+		const priorCacheEntries = /* @__PURE__ */ new Map();
+		const priorExternalFileOwners = { ...this.externalFileOwners };
+		const recordPrior = (key) => {
+			if (!priorCacheEntries.has(key)) priorCacheEntries.set(key, this.fileCache.get(key) ?? null);
+		};
+		const inventoryUpdates = [];
+		const ownerRemovals = [];
+		let removedAny = false;
+		if (changes.removedFiles) for (const removedPath of changes.removedFiles) {
+			let key;
+			let owningRoot = null;
+			if (isPathWithinRoot(rootDir, removedPath)) key = relative(rootDir, removedPath);
+			else {
+				const resolved = this.sourceIdentity?.resolveDeletedSourceId(removedPath);
+				if (!resolved) continue;
+				key = resolved.sourceKey;
+				owningRoot = resolved.owningRoot;
+			}
+			recordPrior(key);
+			if (this.fileCache.delete(key)) {
+				removedAny = true;
+				if (owningRoot) {
+					inventoryUpdates.push({
+						root: owningRoot,
+						key,
+						hash: null,
+						abs: removedPath
+					});
+					ownerRemovals.push(key, key + ".tsx");
+				}
+			}
+		}
+		let targets;
+		if (changes.modifiedFiles) {
+			targets = [];
+			for (const modifiedPath of changes.modifiedFiles) {
+				const classified = this.classifyWatchPath(modifiedPath, {
+					excludeMatcher,
+					extensionsSet
+				});
+				if (classified) targets.push({
+					abs: modifiedPath,
+					...classified
+				});
+			}
+		} else targets = discoverFiles(rootDir, rootDir, excludeMatcher, extensionsSet).map((abs) => ({
+			abs,
+			key: relative(rootDir, abs),
+			owningRoot: null
+		}));
+		const changedPaths = [];
+		for (const target of targets) {
+			const relPath = target.key;
+			let source;
+			try {
+				source = readFileSync(target.abs, "utf-8");
+			} catch {
+				continue;
+			}
+			const rawHash = contentHash(source);
+			const cached = this.fileCache.get(relPath);
+			const hash = rawHash;
+			if (!cached || cached.hash !== hash) {
+				changedPaths.push(relPath);
+				recordPrior(relPath);
+				this.fileCache.set(relPath, {
+					hash,
+					source
+				});
+				if (target.owningRoot) {
+					const owner = this.externalRootOwners.get(target.owningRoot)?.values().next().value;
+					if (owner !== void 0) this.externalFileOwners[relPath] ??= owner;
+					inventoryUpdates.push({
+						root: target.owningRoot,
+						key: target.key,
+						hash: rawHash,
+						abs: target.abs
+					});
+				}
+			}
+		}
+		if (changedPaths.length > 0 || removedAny || assetChanged) {
+			const pending = changedPaths.map((rel) => [rel, this.fileCache.get(rel).hash]);
+			let ingested;
+			try {
+				this.beginStatusAttempt();
+				ingested = await this.ingestAccepted();
+				this.externalFileOwners = this.projectExternalFileOwners(ingested, this.externalFileOwners);
+				resetAnalysisPromise();
+				const promise = this.runIncrementalPipeline(ingested.analysisEntries, pending);
+				setAnalysisPromise(promise);
+				await promise;
+			} catch (err) {
+				for (const [key, prior] of priorCacheEntries) if (prior === null) this.fileCache.delete(key);
+				else this.fileCache.set(key, prior);
+				this.externalFileOwners = priorExternalFileOwners;
+				if (this.statusAttemptOpen) {
+					this.debouncePending.clear();
+					this.writeAnalysisStatus("failed", pending, String(err));
+				}
+				throw err;
+			}
+			this.publishSourceIngestion(ingested);
+			for (const update of inventoryUpdates) {
+				let inventory = this.externalInventory.get(update.root);
+				if (!inventory) {
+					inventory = /* @__PURE__ */ new Map();
+					this.externalInventory.set(update.root, inventory);
+				}
+				if (update.hash === null) inventory.delete(update.key);
+				else inventory.set(update.key, {
+					hash: update.hash,
+					abs: update.abs
+				});
+			}
+			for (const key of ownerRemovals) delete this.externalFileOwners[key];
+		} else if (this.statusAttemptOpen) {
+			this.debouncePending.clear();
+			this.writeAnalysisStatus("idle", []);
+		}
+	}
+	/** The shared ingestion policy point (vite-plugin parity BY CODE): the
+	*  capability guard, facts memo, and warn-dedupe lifecycle live in the
+	*  pipeline; this host holds only its prefix, strict flag, and warn sink. */
+	sourceIngestor = createSourceIngestor({
+		engineApi: () => engineApi(),
+		prefix: "[animus-next]",
+		strict: () => !!this.options.strict,
+		warn: (message) => this.warn(message)
+	});
+	/** Prepare one raw-source corpus through the shared adaptation boundary. */
+	async ingestRawSources(entries) {
+		return this.sourceIngestor.ingest(entries);
+	}
+	/** Ingest and apply the shared per-file quarantine: one invalid original
+	*  (an `.mdx` with the optional peer absent, an unsupported `.svelte`
+	*  shape) warns and drops; the rest of the corpus still analyzes. Strict
+	*  mode throws from the shared policy — callers route that into their own
+	*  status/rollback handling. */
+	async ingestAccepted(entries) {
+		const ingested = await this.ingestRawSources(entries ?? this.buildRawEntriesFromCache());
+		return withoutInvalidOriginals(ingested, this.surfaceSourceDiagnostics(ingested.diagnostics));
+	}
+	/** Surface parser diagnostics under the shared strict/warn policy. */
+	surfaceSourceDiagnostics(diagnostics) {
+		return this.sourceIngestor.surfaceDiagnostics(diagnostics);
+	}
+	/**
+	* Correlate diagnostics emitted against generated children back to the
+	* external package owning their raw original.
+	*/
+	projectExternalFileOwners(result, rawOwners) {
+		const projected = {};
+		for (const owner of Object.values(result.ownership)) {
+			const packageOwner = rawOwners[owner.originalPath];
+			if (!packageOwner) continue;
+			projected[owner.originalPath] = packageOwner;
+			for (const analysisPath of owner.analysisPaths) projected[analysisPath] = packageOwner;
+		}
+		return projected;
+	}
+	/** Publish the raw cache and complete parser projection atomically. */
+	publishSourceIngestion(result) {
+		this.sourceIngestor.markPublished(result);
+		this.fileCache = new Map(result.originalEntries.map((entry) => [entry.path, {
+			hash: entry.hash,
+			source: entry.source
+		}]));
+		this.analysisEntryCache = new Map(result.analysisEntries.map((entry) => [entry.path, {
+			hash: entry.hash,
+			source: entry.source
+		}]));
+		this.sourceOwnership = result.ownership;
+	}
+	async runFullPipeline(pending = []) {
+		const pipelineStart = this.now();
+		const bt = {};
+		this.runSessionStartHygiene();
+		setSessionArtifactDir(this.sessionDir);
+		const rootDir = this.rootDir;
+		const priorSourceState = this.snapshotSourceState();
+		const resolvedSystemPath = resolve(rootDir, this.options.system);
+		let t = this.now();
+		this.system = loadSystemConfig(engineApi, {
+			systemPath: resolvedSystemPath,
+			rootDir,
+			prefix: this.options.prefix
+		});
+		this.assetCopyCache.clear();
+		this.assetDependencyPaths.clear();
+		this.assetDependencyKeys.clear();
+		{
+			const deps = this.system.dependencies ?? [];
+			const keys = /* @__PURE__ */ new Set();
+			for (const key of toWatchKeys(resolvedSystemPath)) keys.add(key);
+			for (const dep of deps) for (const key of toWatchKeys(dep)) keys.add(key);
+			this.systemDependencyKeys = keys;
+			this.systemDependencyPaths = deps;
+			const hashes = /* @__PURE__ */ new Map();
+			for (const dep of deps.length > 0 ? deps : [resolvedSystemPath]) try {
+				hashes.set(dep, contentHash(readFileSync(dep, "utf-8")));
+			} catch {
+				hashes.set(dep, "");
+			}
+			this.systemDependencyHashes = hashes;
+		}
+		bt.systemLoad = this.elapsed(t);
+		t = this.now();
+		const { excludeMatcher, extensionsSet } = this.resolveScanConfig();
+		const files = discoverFiles(rootDir, rootDir, excludeMatcher, extensionsSet);
+		bt.fileDiscovery = this.elapsed(t);
+		t = this.now();
+		const rawEntries = [];
+		for (const filePath of files) {
+			const source = readFileSync(filePath, "utf-8");
+			const relPath = relative(rootDir, filePath);
+			const hash = contentHash(source);
+			rawEntries.push({
+				path: relPath,
+				source,
+				hash
+			});
+		}
+		bt.fileRead = this.elapsed(t);
+		t = this.now();
+		const packageNames = extractSystemFilePackages(resolvedSystemPath);
+		const preResolved = resolvePackagesByName(rootDir, packageNames);
+		const rawExternalFiles = /* @__PURE__ */ new Map();
+		const collected = await collectExternalPackageSources({
+			specifiers: packageNames,
+			resolveSpecifier: (name) => preResolved[name] ? resolve(rootDir, preResolved[name]) : null,
+			rootDir,
+			extensionsSet,
+			hasEntry: (relPath) => rawEntries.some((e) => e.path === relPath),
+			onSourceRead: (source, _relPath, absPath) => {
+				rawExternalFiles.set(absPath, contentHash(source));
+			},
+			onUnreadable: (relPath, err) => this.warn(`skipped unreadable package file ${relPath}: ${String(err)}`),
+			onPackageResolved: (_specifier, packageDir) => {
+				if (!this.onExternalRootResolved) return;
+				if (!this.sharesProjectVolume(rootDir, packageDir)) return;
+				let canonical = packageDir;
+				try {
+					canonical = realpathSync(packageDir);
+				} catch {}
+				this.onExternalRootResolved(canonical);
+			}
+		});
+		this.lastExternalOutcomes = collected.outcomes;
+		for (const record of collected.outcomes) if (record.outcome === "empty") this.warn(`include '${record.specifier}' resolved but discovered no component sources`);
+		const unresolvableMessage = unresolvableIncludesMessage(collected.outcomes);
+		if (unresolvableMessage !== null) {
+			if (this.options.strict) throw new Error(unresolvableMessage);
+			this.warn(unresolvableMessage);
+		}
+		const staleDistMessage = staleDistIncludesMessage(collected.outcomes);
+		if (staleDistMessage !== null) {
+			if (this.options.strict) throw new Error(staleDistMessage);
+			this.warn(staleDistMessage);
+		}
+		const rejectedSpecifiers = /* @__PURE__ */ new Set();
+		const crossVolumeDetails = [];
+		for (const [dir, specifiers] of Object.entries(collected.dirOwnerSets)) {
+			if (this.sharesProjectVolume(rootDir, dir)) continue;
+			for (const specifier of specifiers) rejectedSpecifiers.add(specifier);
+			crossVolumeDetails.push(`${specifiers.join(", ")} → ${dir}`);
+		}
+		this.stickyDiagnostics.delete("cross-volume");
+		if (rejectedSpecifiers.size > 0) {
+			const message = `ANIMUS_EXTERNAL_CROSS_VOLUME_UNSUPPORTED: external package source root(s) on a different volume than the project root (${rootDir}): ${crossVolumeDetails.join("; ")} — cross-volume workspace sources are unsupported; the package(s) are excluded from extraction and watching`;
+			if (this.options.strict) throw new Error(`[${this.driverLabel}] ${message}`);
+			this.stickyDiagnostics.set("cross-volume", message);
+		}
+		for (const message of this.stickyDiagnostics.values()) this.warn(message);
+		const admitted = excludeCollectedPackages(collected, rejectedSpecifiers, rootDir);
+		try {
+			const identity = createSourceIdentity(rootDir);
+			this.externalRootOwners = /* @__PURE__ */ new Map();
+			this.externalRootExtensions = /* @__PURE__ */ new Map();
+			for (const [dir, specifiers] of Object.entries(admitted.dirOwnerSets)) {
+				const canonical = identity.registerExternalRoot(dir);
+				const owners = this.externalRootOwners.get(canonical) ?? /* @__PURE__ */ new Set();
+				for (const specifier of specifiers) owners.add(specifier);
+				this.externalRootOwners.set(canonical, owners);
+				const exts = admitted.dirExtensions[dir];
+				if (exts) this.externalRootExtensions.set(canonical, new Set(exts));
+			}
+			this.sourceIdentity = identity;
+			this.externalWatchRoots = identity.externalRoots();
+			this.externalInventory = /* @__PURE__ */ new Map();
+			for (const [absPath, rawHash] of rawExternalFiles) {
+				const resolved = identity.resolveSourceId(absPath);
+				if (!resolved?.owningRoot) continue;
+				let inventory = this.externalInventory.get(resolved.owningRoot);
+				if (!inventory) {
+					inventory = /* @__PURE__ */ new Map();
+					this.externalInventory.set(resolved.owningRoot, inventory);
+				}
+				inventory.set(resolved.sourceKey, {
+					hash: rawHash,
+					abs: absPath
+				});
+			}
+			const packageMap = admitted.packageMap;
+			this.lastPackageMap = packageMap;
+			this.externalDirOwners = firstOwners(admitted.dirOwnerSets);
+			this.externalFileOwners = admitted.fileOwners;
+			this.externalSourceEntries = admitted.sourceEntries;
+			for (const entry of admitted.entries) {
+				const hash = contentHash(entry.source);
+				rawEntries.push({
+					path: entry.path,
+					source: entry.source,
+					hash
+				});
+			}
+			this.externalPackageDirs = admitted.packageDirs;
+			if (this.system && admitted.keyframesScanEntries.size > 0) {
+				const api = engineApi();
+				const merge = mergeExternalKeyframes((entry, root) => api.scanKeyframesExports(entry, root), this.system.keyframesJson, admitted.keyframesScanEntries.values(), this.rootDir);
+				this.system.keyframesJson = merge.keyframesJson;
+				this.externalKeyframesDiagnostics = merge.diagnostics;
+			} else this.externalKeyframesDiagnostics = [];
+			bt.packageResolve = this.elapsed(t);
+			this.beginStatusAttempt();
+			let accepted;
+			try {
+				accepted = await this.ingestAccepted(rawEntries);
+			} catch (err) {
+				this.debouncePending.clear();
+				this.writeAnalysisStatus("failed", pending, String(err));
+				throw err;
+			}
+			this.externalFileOwners = this.projectExternalFileOwners(accepted, this.externalFileOwners);
+			bt.fileCount = accepted.analysisEntries.length;
+			clearEngineCache(engineApi);
+			await this.analyzeAndEmit(accepted.analysisEntries, packageMap, false, bt, pipelineStart, pending);
+			this.publishSourceIngestion(accepted);
+			setSharedExternalDirs(admitted.packageDirs);
+			setSharedExternalEntries(admitted.sourceEntries);
+			this.onExternalRootsCommitted?.(this.externalWatchRoots);
+			setOwningWatchSession(this);
+		} catch (err) {
+			this.restoreSourceState(priorSourceState);
+			throw err;
+		}
+	}
+	/** The per-generation source state runFullPipeline mutates, captured as
+	*  ONE object so the restore below cannot omit a member. The three
+	*  deep-copied fields are the ones later steps mutate in place rather
+	*  than reassign; everything else is rebound wholesale on success. */
+	snapshotSourceState() {
+		return {
+			sourceIdentity: this.sourceIdentity,
+			externalRootOwners: new Map([...this.externalRootOwners].map(([root, owners]) => [root, new Set(owners)])),
+			externalRootExtensions: new Map(this.externalRootExtensions),
+			externalWatchRoots: [...this.externalWatchRoots],
+			externalInventory: new Map([...this.externalInventory].map(([root, inventory]) => [root, new Map(inventory)])),
+			lastPackageMap: this.lastPackageMap,
+			externalDirOwners: this.externalDirOwners,
+			externalFileOwners: this.externalFileOwners,
+			externalSourceEntries: this.externalSourceEntries,
+			externalPackageDirs: this.externalPackageDirs,
+			externalKeyframesDiagnostics: this.externalKeyframesDiagnostics
+		};
+	}
+	restoreSourceState(snapshot) {
+		Object.assign(this, snapshot);
+	}
+	/**
+	* Reset analysis state for HMR geological reset. Payload write guards go
+	* back to null so the next publication reseeds them from the disk
+	* envelopes — a byte-identical post-reset artifact is still not
+	* rewritten.
+	*/
+	resetForHmr() {
+		resetAnalysisPromise();
+		this.artifactRecords = {
+			manifest: null,
+			inputs: null,
+			styles: null
+		};
+		this.lastSystemPropsHash = null;
+	}
+	/**
+	* The (sourceKey, observedSourceHash) pairs of a watch batch — cheap
+	* evidence for the status file's pending set on the geological-reset
+	* path, where the batch's component edits ride along with the system
+	* edit (design D3: loaders wait only on observed inputs).
+	*/
+	pendingFromBatch(changes) {
+		const { excludeMatcher, extensionsSet } = this.resolveScanConfig();
+		const pending = [];
+		for (const path of changes.modifiedFiles ?? []) {
+			const classified = this.classifyWatchPath(path, {
+				excludeMatcher,
+				extensionsSet
+			});
+			if (!classified) continue;
+			try {
+				pending.push([classified.key, contentHash(readFileSync(path, "utf-8"))]);
+			} catch {}
+		}
+		return pending;
+	}
+	/**
+	* Root-dirty inventory reconciliation (design D3): partition the
+	* watcher's change sets into explicit FILE events and external ROOT hits
+	* (a reported path that IS an admitted root, or a directory inside one),
+	* rewalk each dirty root through the shared discovery policy, diff the
+	* SourceId+raw-hash inventory against the previous generation, and merge
+	* the reconstructed created/edited/deleted deltas with the explicit
+	* events (identity-level dedup happens downstream at the cache gate).
+	* Deletion falls out of the inventory diff — webpack may report only the
+	* directory (probe-proven).
+	*/
+	reconcileExternalRoots(changes) {
+		const identity = this.sourceIdentity;
+		if (!identity) return changes;
+		if (!changes.modifiedFiles && !changes.removedFiles) return changes;
+		if (this.externalWatchRoots.length === 0) return changes;
+		const { extensionsSet } = this.resolveScanConfig();
+		const dirtyRoots = /* @__PURE__ */ new Set();
+		const modified = /* @__PURE__ */ new Set();
+		const removed = /* @__PURE__ */ new Set();
+		const rootHitFor = (path) => {
+			const containing = identity.containingExternalRoot(path);
+			if (!containing) return null;
+			try {
+				return statSync(path).isDirectory() ? containing : null;
+			} catch {
+				return identity.resolveDeletedSourceId(path) ? null : containing;
+			}
+		};
+		for (const path of changes.modifiedFiles ?? []) {
+			const root = rootHitFor(path);
+			if (root) dirtyRoots.add(root);
+			else modified.add(path);
+		}
+		for (const path of changes.removedFiles ?? []) {
+			const root = rootHitFor(path);
+			if (root) dirtyRoots.add(root);
+			else removed.add(path);
+		}
+		for (const root of dirtyRoots) {
+			const previous = this.externalInventory.get(root) ?? /* @__PURE__ */ new Map();
+			const seen = /* @__PURE__ */ new Set();
+			const walked = walkPackageSources(root, this.externalRootExtensions.get(root) ?? extensionsSet);
+			if (walked.length === 0 && previous.size > 0) this.warn(`external root rewalk found no files under ${root} while its inventory holds ${previous.size} — reconciling as full deletion`);
+			for (const abs of walked) {
+				const resolved = identity.resolveSourceId(abs);
+				if (!resolved || resolved.owningRoot !== root) continue;
+				seen.add(resolved.sourceKey);
+				let rawHash;
+				try {
+					rawHash = contentHash(readFileSync(abs, "utf-8"));
+				} catch {
+					continue;
+				}
+				if (previous.get(resolved.sourceKey)?.hash !== rawHash) modified.add(abs);
+			}
+			for (const [key, entry] of previous) if (!seen.has(key)) removed.add(entry.abs);
+		}
+		return {
+			modifiedFiles: modified,
+			removedFiles: removed
+		};
+	}
+	/**
+	* Route one watcher-reported path (design D1/D2): a project-root member
+	* (lexical containment — existing local semantics preserved; consumer
+	* exclude patterns apply) or an admitted external member (identity
+	* resolution with symlink-escape rejection; package-relative excludes
+	* mirror the collection walk's filters — guardrail G1, one policy).
+	* Returns null for dropped paths.
+	*/
+	classifyWatchPath(absPath, scan) {
+		const ext = extname(absPath);
+		const rootDir = this.rootDir;
+		if (isPathWithinRoot(rootDir, absPath)) {
+			if (!scan.extensionsSet.has(ext)) return null;
+			const rel = relative(rootDir, absPath);
+			if (scan.excludeMatcher.matches(absPath, rel)) return null;
+			return {
+				key: rel,
+				owningRoot: null
+			};
+		}
+		const resolved = this.sourceIdentity?.resolveSourceId(absPath);
+		if (!resolved) return null;
+		if (resolved.owningRoot === null) {
+			if (!scan.extensionsSet.has(ext)) return null;
+			if (scan.excludeMatcher.matches(resolved.sourceKey, resolved.sourceKey)) return null;
+			return {
+				key: resolved.sourceKey,
+				owningRoot: null
+			};
+		}
+		if (!(this.externalRootExtensions.get(resolved.owningRoot) ?? scan.extensionsSet).has(ext)) return null;
+		if (isExcludedPackageRelativePath(resolved.pathInRoot)) return null;
+		return {
+			key: resolved.sourceKey,
+			owningRoot: resolved.owningRoot
+		};
+	}
+	/** Build full raw originals for one shared adaptation attempt. */
+	buildRawEntriesFromCache() {
+		const entries = [];
+		for (const [path, { hash, source }] of this.fileCache) entries.push({
+			path,
+			source,
+			hash
+		});
+		return entries;
+	}
+	/**
+	* Run incremental pipeline with cache-aware file entries.
+	* Reuses system config from the last full pipeline run.
+	*/
+	async runIncrementalPipeline(fileEntries, pending = []) {
+		const bt = {};
+		const pipelineStart = this.now();
+		await this.analyzeAndEmit(fileEntries, this.lastPackageMap, true, bt, pipelineStart, pending);
+	}
+	/**
+	* Shared analysis + emit core for both pipelines — the single call site
+	* that routes every manifest through the shared `runProjectAnalysis`,
+	* reachable from both runFullPipeline (production) and
+	* runIncrementalPipeline (HMR).
+	*
+	* Owns diagnostic surfacing, CSS assembly + styles.css write guard,
+	* system-props module emit, and the timing log. The engine's own
+	* `dev_mode` (reconciliation pruning) is derived separately via
+	* `engineDevMode` — an explicit `mode` option overrides the pipeline
+	* path there. For everything else the `devMode` flag is the ONLY
+	* behavioral fork:
+	*
+	* - `false` (production): computes bt.analysis + logs the extraction
+	*   report, and writes system-props.js UNCONDITIONALLY (no
+	*   lastSystemPropsHash guard).
+	* - `true` (HMR): skips the report log, and guards the system-props.js
+	*   write by lastSystemPropsHash.
+	*
+	* The disk artifacts land under the session directory in transaction
+	* order (design D1): manifest → analysis-inputs (Turbopack orchestration
+	* only) → styles.css → system-props → analysis-commit →
+	* replacements-epoch (last, only when moved). The analysis-status file walks starting → analyzing →
+	* committing → idle around the attempt, landing in `failed` (with the
+	* diagnostic) on any throw (design D3).
+	*/
+	async analyzeAndEmit(fileEntries, packageMap, devMode, bt, pipelineStart, pending = []) {
+		this.beginStatusAttempt();
+		this.debouncePending.clear();
+		this.writeAnalysisStatus("starting", pending);
+		try {
+			await this.analyzeAndEmitAttempt(fileEntries, packageMap, devMode, bt, pipelineStart, pending);
+			this.firstEmissionComplete = true;
+			this.writeAnalysisStatus("idle", []);
+		} catch (err) {
+			this.writeAnalysisStatus("failed", pending, String(err));
+			throw err;
+		}
+	}
+	/**
+	* The engine's `dev_mode` flag (retain all components vs reconciliation
+	* pruning) is an EMISSION decision, so an explicit `mode` option wins over
+	* the pipeline path (core-options: `mode` "decides emitted bytes …
+	* engine devMode"). Without an explicit mode the historical per-pipeline
+	* default applies: full = production pruning, incremental = dev retention.
+	* A pinned-production watch must not flip to unpruned CSS on its first
+	* incremental republication, and a pinned-development full build must
+	* retain all components.
+	*/
+	engineDevMode(pipelineDefault) {
+		if (this.options.mode !== void 0) return this.options.mode === "development";
+		return pipelineDefault;
+	}
+	async analyzeAndEmitAttempt(fileEntries, packageMap, devMode, bt, pipelineStart, pending) {
+		const system = this.system;
+		const analysisOptions = {
+			fileEntries,
+			packageMap,
+			system,
+			emitter: {
+				runtimeImport: "@animus-ui/system/runtime",
+				cssModuleId: ANIMUS_CSS_MODULE_ID,
+				systemPropsModuleId: this.systemPropsModuleId ?? systemPropsPath(this.sessionDir)
+			},
+			pathAliasesJson: this.pathAliasesJson,
+			staticCssJson: this.staticCssJson,
+			externalDirs: this.externalPackageDirs.map((dir) => relative(this.rootDir, dir)),
+			devMode: this.engineDevMode(devMode)
+		};
+		this.writeAnalysisStatus("analyzing", pending);
+		const result = runProjectAnalysis(engineApi, {
+			...analysisOptions,
+			warn: (message) => this.warn(message),
+			strict: this.options.strict,
+			extraDiagnostics: this.externalKeyframesDiagnostics
+		});
+		assertNoErrorDiagnostics(result.manifest?.diagnostics);
+		enforceExternalTokenContracts({
+			diagnostics: result.manifest?.diagnostics,
+			fileOwners: this.externalFileOwners,
+			dirOwners: this.externalDirOwners,
+			sourceThemeManifestsJson: system.sourceThemeManifestsJson,
+			strict: this.options.strict,
+			prefix: `[${this.driverLabel}]`,
+			warn: (message) => this.warn(message)
+		});
+		bt.jsonSerialize = result.timings.serializeMs;
+		bt.rustExtract = result.timings.extractMs;
+		bt.jsonParse = result.timings.parseMs;
+		const manifest = result.manifest;
+		this.lastComponentCount = Object.keys(manifest?.components ?? {}).length;
+		if (!devMode) {
+			bt.analysis = (bt.jsonSerialize ?? 0) + (bt.rustExtract ?? 0) + (bt.jsonParse ?? 0);
+			if (manifest?.report) this.log(`Extracted ${manifest.report.components_extracted ?? "?"}/${manifest.report.components_total ?? "?"} components (${bt.analysis}ms)`);
+		}
+		const globalCss = this.substituteAssetReferences(result.globalCss, devMode);
+		const { declaration, variables, body } = assembleStylesheet({
+			layers: this.options.layers,
+			variableCss: system.variableCss,
+			globalCss,
+			componentCss: result.componentCss,
+			split: true
+		});
+		if (this.lcssTargets === null) this.lcssTargets = resolveLightningTargets(this.options.targets, this.rootDir);
+		const fullCss = [
+			declaration,
+			variables,
+			postProcessCss(body, {
+				minify: this.options.minify ?? resolveMode(this.options.mode, () => process.env.NODE_ENV === "production" ? "production" : "development").mode === "production",
+				targets: this.lcssTargets,
+				warnFn: (msg) => this.warn(msg)
+			})
+		].filter(Boolean).join("\n");
+		setSharedCss(fullCss);
+		const systemPropsContent = buildSystemPropsModule({
+			systemPropMapJson: JSON.stringify(manifest?.system_prop_map ?? {}),
+			groupRegistryJson: system.groupRegistryJson,
+			dynamicProps: manifest?.dynamic_props ?? {}
+		});
+		setSharedSystemProps(systemPropsContent);
+		setManifestJson(result.manifestJson);
+		setAnalyzedHashes(new Map(fileEntries.map((entry) => [entry.path, entry.hash])));
+		this.writeAnalysisStatus("committing", pending);
+		const epoch = hashReplacementPlans(snapshotFilePlans(manifest), systemPropsContent);
+		if (this.lastCommit === null) this.lastCommit = this.seedCommitFromDisk();
+		const generation = (this.lastCommit?.generation ?? 0) + 1;
+		this.publishPayloadArtifact("manifest", MANIFEST_ARTIFACT, result.manifestJson, epoch, generation, envelopeJsonArtifact);
+		if (this.persistAnalysisInputs) this.publishPayloadArtifact("inputs", ANALYSIS_INPUTS_ARTIFACT, JSON.stringify({
+			analyzedHashes: Object.fromEntries(fileEntries.map((entry) => [entry.path, entry.hash])),
+			...result.inputs
+		}), epoch, generation, envelopeJsonArtifact);
+		this.publishPayloadArtifact("styles", STYLES_ARTIFACT, fullCss, epoch, generation, envelopeCssArtifact);
+		if (devMode) {
+			const systemPropsHash = contentHash(systemPropsContent);
+			if (systemPropsHash !== this.lastSystemPropsHash) {
+				this.writeSessionArtifact(SYSTEM_PROPS_ARTIFACT, systemPropsContent);
+				this.lastSystemPropsHash = systemPropsHash;
+			}
+		} else this.writeSessionArtifact(SYSTEM_PROPS_ARTIFACT, systemPropsContent);
+		this.publishAnalysisCommit(epoch, generation);
+		this.publishReplacementEpoch(epoch);
+		bt.total = this.elapsed(pipelineStart);
+		logBuildTimings(bt, manifest?.timing, (msg) => this.log(msg), this.verbose);
+	}
+	/** Open a status attempt (attemptId increments once per burst — a
+	*  debouncing pre-write and the analysis that follows share one id). */
+	beginStatusAttempt() {
+		if (!this.statusAttemptOpen) {
+			this.statusAttemptId += 1;
+			this.statusAttemptOpen = true;
+		}
+	}
+	/** Write the session's analysis-status artifact (design D3). Terminal
+	*  states (idle/failed) close the attempt. */
+	writeAnalysisStatus(state, pending, diagnostic) {
+		const status = {
+			schema: 2,
+			sessionId: this.sessionId,
+			attemptId: this.statusAttemptId,
+			state,
+			pending,
+			deadlineAt: Date.now() + this.debounceCeilingMs + STATUS_WATCHDOG_MS,
+			...diagnostic !== void 0 ? { diagnostic } : {},
+			ready: this.firstEmissionComplete
+		};
+		this.writeSessionArtifact(ANALYSIS_STATUS_ARTIFACT, JSON.stringify(status));
+		if (state === "idle" || state === "failed") this.statusAttemptOpen = false;
+	}
+	/**
+	* Orchestrator seam (Turbopack watcher): record watch events observed
+	* during the debounce window so a loader running ahead of the analysis
+	* has positive evidence to wait on (design D3 'debouncing'). Paths are
+	* filtered by the scan config and hashed at observation time.
+	*/
+	noteDebouncedWatchEvents(absPaths) {
+		if (!this.rootDir) return;
+		const additions = this.pendingFromBatch({ modifiedFiles: new Set(absPaths) });
+		if (additions.length === 0) return;
+		this.beginStatusAttempt();
+		for (const [key, hash] of additions) this.debouncePending.set(key, hash);
+		if (this.debounceStatusWriteScheduled) return;
+		this.debounceStatusWriteScheduled = true;
+		queueMicrotask(() => {
+			this.debounceStatusWriteScheduled = false;
+			if (this.debouncePending.size === 0) return;
+			try {
+				this.writeAnalysisStatus("debouncing", [...this.debouncePending.entries()]);
+			} catch (err) {
+				this.warn(`debounce status write failed: ${String(err)}`);
+			}
+		});
+	}
+	/** One pending microtask flushes a burst of debounce observations. */
+	debounceStatusWriteScheduled = false;
+	/**
+	* Write one payload artifact into the session directory, enveloped with
+	* `{sessionId, generation, replacementEpoch, payloadHash}` and rewritten
+	* only when the PAYLOAD bytes changed (byte-identical re-analyses leave
+	* disk untouched — spec: "Unchanged manifest is not rewritten"). The
+	* recorded diskHash (hash of the enveloped bytes) feeds the
+	* analysis-commit.
+	*/
+	publishPayloadArtifact(key, name, payload, epoch, generation, wrap) {
+		const payloadHash = contentHash(payload);
+		if (this.artifactRecords[key] === null) this.artifactRecords[key] = this.seedPayloadRecord(key, name);
+		const record = this.artifactRecords[key];
+		if (record !== null && record.payloadHash === payloadHash) return;
+		const envelope = {
+			sessionId: this.sessionId,
+			generation,
+			replacementEpoch: epoch,
+			payloadHash
+		};
+		const bytes = wrap(payload, JSON.stringify(envelope));
+		this.writeSessionArtifact(name, bytes);
+		this.artifactRecords[key] = {
+			payloadHash,
+			diskHash: contentHash(bytes)
+		};
+	}
+	/** Reconstruct a payload write guard from the on-disk artifact's envelope
+	*  (same-session restart: a byte-identical payload must not rewrite). */
+	seedPayloadRecord(key, name) {
+		let bytes;
+		try {
+			bytes = readFileSync(join(this.sessionDir, name), "utf-8");
+		} catch {
+			return null;
+		}
+		let envelope;
+		try {
+			envelope = key === "styles" ? readCssEnvelope(bytes) : readJsonEnvelope(bytes);
+		} catch {
+			return null;
+		}
+		if (!envelope || typeof envelope.payloadHash !== "string") return null;
+		return {
+			payloadHash: envelope.payloadHash,
+			diskHash: contentHash(bytes)
+		};
+	}
+	/** Last analysis-commit persisted in this session's directory, or null. */
+	seedCommitFromDisk() {
+		try {
+			const parsed = JSON.parse(readFileSync(analysisCommitPath(this.sessionDir), "utf-8"));
+			return parsed.schema === 1 && parsed.sessionId === this.sessionId && typeof parsed.generation === "number" ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Publish the analysis-commit — the transaction identity (design D1).
+	* Written AFTER every payload and BEFORE the epoch; skipped entirely when
+	* the payload set (disk hashes) and epoch are unchanged, so a no-op
+	* re-analysis neither re-keys loader-worker hydration nor burns a
+	* generation.
+	*/
+	publishAnalysisCommit(epoch, generation) {
+		const manifestHash = this.artifactRecords.manifest?.diskHash ?? "";
+		const inputsHash = this.persistAnalysisInputs ? this.artifactRecords.inputs?.diskHash ?? "" : void 0;
+		const stylesHash = this.artifactRecords.styles?.diskHash ?? "";
+		const prev = this.lastCommit;
+		if (prev !== null && prev.manifestHash === manifestHash && prev.inputsHash === inputsHash && prev.stylesHash === stylesHash && prev.replacementEpoch === epoch) return;
+		const commit = {
+			schema: 1,
+			sessionId: this.sessionId,
+			generation,
+			replacementEpoch: epoch,
+			manifestHash,
+			...inputsHash !== void 0 ? { inputsHash } : {},
+			stylesHash
+		};
+		this.writeSessionArtifact(ANALYSIS_COMMIT_ARTIFACT, JSON.stringify(commit));
+		this.lastCommit = commit;
+	}
+	/**
+	* Publish the canonical replacement epoch: maintain the session-scoped
+	* disk witness `{schema, sessionId, epoch}`, rewritten ONLY when the
+	* epoch VALUE changes so style-only analyses and same-session restarts
+	* leave bytes and mtime untouched, then expose the value through the
+	* singleton for the plugin's needBuild fan-out and the loader's catch-up
+	* re-check. Every VALUE move also reconciles sibling sessions' epoch
+	* artifacts (below) — the webpack cold-cache validity witness.
+	*/
+	publishReplacementEpoch(epoch) {
+		const onDisk = this.diskEpochValue();
+		if (this.lastEpochValue === null) this.lastEpochValue = onDisk;
+		if (epoch !== onDisk) this.writeSessionArtifact(REPLACEMENT_EPOCH_ARTIFACT, JSON.stringify({
+			schema: 1,
+			sessionId: this.sessionId,
+			epoch
+		}));
+		if (epoch !== this.lastEpochValue) {
+			this.lastEpochValue = epoch;
+			this.reconcileSiblingEpochs(epoch);
+		}
+		setReplacementEpoch(epoch);
+	}
+	/**
+	* Sibling epoch reconciliation — the cross-session half of the webpack
+	* persistent-cache witness (spec: dev-served-transform-coherence,
+	* "Offline change invalidates restored modules"). Restored-module
+	* snapshots reference the epoch artifact of the session that BUILT them;
+	* with session-scoped trees that file would otherwise sit untouched
+	* forever, keeping stale snapshots valid. Whenever this session's epoch
+	* value moves, delete every sibling epoch artifact that disagrees (their
+	* snapshots must invalidate — restore-on-demand then rebuilds from the
+	* current generation) and leave agreeing siblings byte-untouched (warm
+	* restores stay valid). Deleting a stale artifact is pruning, not a
+	* foreign-session write; races with concurrent sessions are tolerated
+	* (S14).
+	*/
+	/** Sibling ids already reconciled away (artifact deleted or absent) —
+	*  nothing left to invalidate for them on later moves. */
+	reconciledSiblingIds = /* @__PURE__ */ new Set();
+	/** sessions-root listing memo, keyed by the root dir's mtime — a new or
+	*  pruned sibling DIRECTORY moves it; agreeing siblings stay listed. */
+	siblingListing = null;
+	reconcileSiblingEpochs(epoch) {
+		const rootPath = sessionsRootDir(this.rootDir);
+		let entries;
+		try {
+			const mtimeMs = statSync(rootPath).mtimeMs;
+			if (this.siblingListing?.mtimeMs === mtimeMs) entries = this.siblingListing.entries;
+			else {
+				entries = readdirSync(rootPath);
+				this.siblingListing = {
+					mtimeMs,
+					entries
+				};
+			}
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry === this.sessionId) continue;
+			if (this.reconciledSiblingIds.has(entry)) continue;
+			const siblingEpochPath = join(rootPath, entry, REPLACEMENT_EPOCH_ARTIFACT);
+			try {
+				if (JSON.parse(readFileSync(siblingEpochPath, "utf-8")).epoch === epoch) continue;
+			} catch (err) {
+				if (err?.code === "ENOENT") {
+					this.reconciledSiblingIds.add(entry);
+					continue;
+				}
+			}
+			try {
+				unlinkSync(siblingEpochPath);
+			} catch {}
+			this.reconciledSiblingIds.add(entry);
+		}
+	}
+	/** Epoch value held by this session's on-disk artifact, or null when
+	*  absent, unreadable, or not the expected schema. */
+	diskEpochValue() {
+		try {
+			const parsed = JSON.parse(readFileSync(replacementEpochPath(this.sessionDir), "utf-8"));
+			return parsed.schema === 1 && typeof parsed.epoch === "string" ? parsed.epoch : null;
+		} catch {
+			return null;
+		}
+	}
+	/** True when the flat `.animus/` advisory lock names a live pid — a CLI
+	*  invocation (build mid-publish, or a whole watch run) owns the flat
+	*  tree right now, and any instantaneous inconsistency is its in-flight
+	*  write, not debris. */
+	cliWriterHoldsLock(animusDir) {
+		let holder;
+		try {
+			holder = JSON.parse(readFileSync(join(animusDir, CLI_LOCK_ARTIFACT), "utf-8"));
+		} catch {
+			return false;
+		}
+		if (typeof holder.pid !== "number") return false;
+		try {
+			process.kill(holder.pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Session-start hygiene (design D2): delete legacy flat artifacts
+	*  (unreachable by session-scoped loaders; the standalone CLI is the one
+	*  remaining writer of flat payload names, and its live output is
+	*  fenced off below) and prune sibling session directories older than
+	*  the retention window — never the own dir, tolerating races with
+	*  concurrently-pruning sessions (S14). */
+	runSessionStartHygiene() {
+		if (this.sessionStartHygieneDone) return;
+		this.sessionStartHygieneDone = true;
+		const animusDir = join(this.rootDir, ".animus");
+		const isCliPublishedSet = this.cliWriterHoldsLock(animusDir) || verifyCommitRecord(animusDir).length === 0;
+		const cliPublishedNames = [
+			MANIFEST_ARTIFACT,
+			STYLES_ARTIFACT,
+			SYSTEM_PROPS_ARTIFACT
+		];
+		for (const name of LEGACY_FLAT_ARTIFACTS) {
+			if (isCliPublishedSet && cliPublishedNames.includes(name)) continue;
+			try {
+				unlinkSync(join(animusDir, name));
+			} catch {}
+		}
+		if (!isCliPublishedSet) try {
+			unlinkSync(join(animusDir, CLI_COMMIT_ARTIFACT));
+		} catch {}
+		let entries;
+		try {
+			entries = readdirSync(sessionsRootDir(this.rootDir));
+		} catch {
+			return;
+		}
+		const cutoff = Date.now() - SESSION_DIR_MAX_AGE_MS;
+		for (const entry of entries) {
+			if (entry === this.sessionId) continue;
+			const dir = join(sessionsRootDir(this.rootDir), entry);
+			try {
+				if (statSync(dir).mtimeMs < cutoff) rmSync(dir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+		}
+	}
+	/** Ensure the session directory exists and write one artifact into it.
+	*  Write-then-rename so cross-process readers (Turbopack loader workers)
+	*  can never observe a torn half-written file. The tmp name carries the
+	*  pid — Next dev evaluates the config in more than one process, and two
+	*  sessions writing the same artifact must not race on one tmp path. */
+	writeSessionArtifact(name, content) {
+		const dir = this.sessionDir;
+		mkdirSync(dir, { recursive: true });
+		const tmpPath = join(dir, `.${name}.${process.pid}.tmp`);
+		writeFileSync(tmpPath, content);
+		renameSync(tmpPath, join(dir, name));
+		this.onArtifactWrite?.(name, content);
+	}
+	/**
+	* asset() placeholder substitution (global-styles-system): resolve each
+	* referenced specifier through Node resolution, copy the bytes into the
+	* session directory's `assets/` under a content-hashed name, and
+	* substitute a RELATIVE url — relative to the session-scoped styles.css,
+	* which sits beside `assets/`, so the emitted `./assets/<file>` form is
+	* unchanged. The stylesheet is processed by Next's own CSS pipeline
+	* (webpack and Turbopack alike), which applies its native asset handling
+	* — publicPath and output hashing — to relative url() references.
+	* Unsubstitutable specifiers warn and emit literally in non-strict mode,
+	* fail the build under `strict: true`.
+	*/
+	substituteAssetReferences(globalCss, devMode) {
+		const specifiers = findAssetSpecifiers(globalCss);
+		const assetsDir = join(this.sessionDir, SESSION_ASSETS_DIR);
+		const expected = /* @__PURE__ */ new Set();
+		this.assetDependencyPaths.clear();
+		this.assetDependencyKeys.clear();
+		const urlBySpecifier = /* @__PURE__ */ new Map();
+		for (const specifier of specifiers) {
+			const cached = this.assetCopyCache.get(specifier);
+			if (cached && existsSync(join(assetsDir, cached.fileName))) try {
+				const current = statSync(cached.sourcePath);
+				if (current.mtimeMs === cached.mtimeMs && current.size === cached.size) {
+					this.trackAssetDependency(cached.sourcePath);
+					expected.add(cached.fileName);
+					urlBySpecifier.set(specifier, cached.url);
+					continue;
+				}
+			} catch {}
+			const resolvedPath = this.resolveAssetSpecifier(specifier);
+			if (!resolvedPath) {
+				const message = `unresolvable asset() specifier: ${specifier}`;
+				if (this.options.strict) throw new Error(`[${this.driverLabel}] ${message}`);
+				this.warn(message);
+				urlBySpecifier.set(specifier, specifier);
+				continue;
+			}
+			const bytes = readFileSync(resolvedPath);
+			const sourceStat = statSync(resolvedPath);
+			this.trackAssetDependency(resolvedPath);
+			const ext = extname(resolvedPath);
+			const fileName = `${basename(resolvedPath, ext)}.${contentHash(bytes).slice(0, 8)}${ext}`;
+			expected.add(fileName);
+			if (!existsSync(assetsDir)) mkdirSync(assetsDir, { recursive: true });
+			const assetPath = join(assetsDir, fileName);
+			if (!existsSync(assetPath)) writeFileSync(assetPath, bytes);
+			const url = `./${SESSION_ASSETS_DIR}/${fileName}`;
+			urlBySpecifier.set(specifier, url);
+			this.assetCopyCache.set(specifier, {
+				sourcePath: resolvedPath,
+				mtimeMs: sourceStat.mtimeMs,
+				size: sourceStat.size,
+				fileName,
+				url
+			});
+		}
+		if (!devMode) pruneStaleAssets(assetsDir, expected);
+		return substituteAssetPlaceholders(globalCss, urlBySpecifier);
+	}
+	trackAssetDependency(path) {
+		this.assetDependencyPaths.add(path);
+		for (const key of toWatchKeys(path)) this.assetDependencyKeys.add(key);
+	}
+	/**
+	* Resolve an asset specifier to an absolute file via the shared pipeline
+	* resolver (host aliases → Node resolution → package root), with one
+	* session-local last resort: an already-discovered source entry's package
+	* root (dist-less workspace kits the shared resolver cannot see).
+	*/
+	resolveAssetSpecifier(specifier) {
+		const resolved = resolveAssetFile(specifier, this.rootDir, this.pathAliasesJson);
+		if (resolved) return resolved;
+		const segments = specifier.split("/");
+		const packageName = specifier.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
+		const subpath = specifier.slice(packageName.length + 1);
+		if (!subpath) return null;
+		const sourceEntry = this.externalSourceEntries.get(packageName) ?? [...this.externalSourceEntries].find(([declared]) => declared === packageName || declared.startsWith(`${packageName}/`))?.[1];
+		if (sourceEntry) {
+			const candidate = join(findPackageRoot(sourceEntry), subpath);
+			if (existsSync(candidate)) return candidate;
+		}
+		return null;
+	}
+};
+/**
+* Sync `.animus/assets/` to the current build's content-hashed file set:
+* anything else in the directory is a superseded revision (the copies are
+* content-addressed and never overwritten) or the leftover of an asset()
+* reference that no longer exists. Failures are tolerated per entry — Next
+* dev evaluates the config in more than one process, and a concurrent
+* session may have removed (or be about to rewrite) the same file; every
+* pass rewrites whatever of its own set is missing, so races self-heal.
+*/
+function pruneStaleAssets(assetsDir, expected) {
+	if (!existsSync(assetsDir)) return;
+	let entries;
+	try {
+		entries = readdirSync(assetsDir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (expected.has(entry)) continue;
+		try {
+			unlinkSync(join(assetsDir, entry));
+		} catch {}
+	}
+}
+//#endregion
+//#region session/turbopack-orchestrator.ts
+/**
+* Out-of-band pipeline orchestration for Turbopack (spec:
+* next-turbopack-integration). Turbopack exposes no compiler hooks, so the
+* pipeline runs during next.config resolution and, in dev, from a
+* filesystem watcher — the bundler only ever sees the `.animus/` disk
+* artifacts.
+*/
+/** Run the full pipeline with the Turbopack emitter identity: the virtual
+*  system-props id (Turbopack rejects the webpack path's absolute-path
+*  imports). Turbopack orchestration persists the analysis-inputs
+*  hydration corpus — its isolated loader workers replay it (spec:
+*  next-turbopack-integration, "Manifest disk artifact"; webpack mode
+*  skips the corpus). */
+async function runSessionPipeline(session) {
+	session.systemPropsModuleId = TURBOPACK_SYSTEM_PROPS_ID;
+	session.persistAnalysisInputs = true;
+	await session.runFullPipeline();
+}
+const activeWatcherRoots = /* @__PURE__ */ new Set();
+const IGNORED_SEGMENTS = new Set([
+	".animus",
+	".next",
+	"node_modules"
+]);
+/**
+* Start the dev watcher: fs.watch per eligible top-level directory (plus a
+* non-recursive watch on the root itself), debounced into
+* existence-partitioned modified/removed sets feeding
+* `session.handleWatchUpdate` (serialized — updates never overlap).
+* Generated and vendored trees (`.animus`, `.next`, node_modules) are never
+* registered with the OS — recursive registration of those trees exhausts
+* inotify/kqueue descriptors (EMFILE/ENOSPC) on large projects.
+* Idempotent per project root; unref'd so it never holds the process open.
+* Asynchronous FSWatcher errors degrade to no-watch with a warning instead
+* of crashing the dev server. Returns a close handle, or null when this
+* root is already watched or the platform lacks recursive fs.watch (Linux
+* before Node 20 — degrades to no-watch with a warning).
+*/
+function startTurbopackWatcher(session, rootDir, debounceMs = 75, watchFn = watch) {
+	if (activeWatcherRoots.has(rootDir)) return null;
+	activeWatcherRoots.add(rootDir);
+	if (typeof session.noteDebouncedWatchEvents === "function") session.debounceCeilingMs = debounceMs;
+	const pendingPaths = /* @__PURE__ */ new Set();
+	const watchers = /* @__PURE__ */ new Map();
+	let timer = null;
+	let updateChain = Promise.resolve();
+	let closed = false;
+	let died = false;
+	const externalWatchers = /* @__PURE__ */ new Map();
+	let pendingOpened = /* @__PURE__ */ new Map();
+	let capturedDuringSnapshot = [];
+	const externalDiagnosticKey = (root) => `external-watch:${root}`;
+	const failureReason = (err) => {
+		const code = err?.code;
+		if (code === "EMFILE" || code === "ENFILE" || code === "ENOSPC" || code === "EPERM") return `capacity(${code})`;
+		if (/inotify|too many/i.test(String(err))) return "capacity";
+		return code ?? "error";
+	};
+	const degradeExternalRoot = (root, err) => {
+		externalWatchers.get(root)?.close();
+		externalWatchers.delete(root);
+		pendingOpened.get(root)?.close();
+		pendingOpened.delete(root);
+		const message = `ANIMUS_EXTERNAL_WATCH_UNAVAILABLE root=${relative(rootDir, root)} reason=${failureReason(err)} effect=changes in this workspace source may require restart`;
+		session.stickyDiagnostics?.set(externalDiagnosticKey(root), message);
+		console.warn(`[animus-extract] ${message}`);
+	};
+	const flush = () => {
+		timer = null;
+		const modifiedFiles = /* @__PURE__ */ new Set();
+		const removedFiles = /* @__PURE__ */ new Set();
+		for (const path of pendingPaths) (existsSync(path) ? modifiedFiles : removedFiles).add(path);
+		pendingPaths.clear();
+		updateChain = updateChain.then(() => session.handleWatchUpdate({
+			modifiedFiles,
+			removedFiles
+		}).catch((err) => {
+			console.warn(`[animus-extract] Turbopack watch update failed: ${String(err)}`);
+		}).then(() => {
+			if (pendingOpened.size > 0 || capturedDuringSnapshot.length > 0) rollbackPendingExternal();
+		}));
+	};
+	const rollbackPendingExternal = () => {
+		for (const watcher of pendingOpened.values()) watcher.close();
+		pendingOpened = /* @__PURE__ */ new Map();
+		capturedDuringSnapshot = [];
+	};
+	const closeAll = () => {
+		if (closed) return;
+		closed = true;
+		if (timer) clearTimeout(timer);
+		timer = null;
+		for (const watcher of watchers.values()) watcher.close();
+		watchers.clear();
+		for (const watcher of externalWatchers.values()) watcher.close();
+		externalWatchers.clear();
+		rollbackPendingExternal();
+		session.onExternalRootResolved = null;
+		session.onExternalRootsCommitted = null;
+		activeWatcherRoots.delete(rootDir);
+	};
+	const onWatcherError = (err) => {
+		died = true;
+		closeAll();
+		console.warn(`[animus-extract] Turbopack dev watcher failed (${String(err)}); source edits require a dev-server restart`);
+		handle.onDied?.();
+	};
+	const enqueuePath = (abs) => {
+		pendingPaths.add(abs);
+		try {
+			session.noteDebouncedWatchEvents?.([abs]);
+		} catch (err) {
+			console.warn(`[animus-extract] Turbopack debounce status update failed: ${String(err)}`);
+		}
+		if (!timer) {
+			timer = setTimeout(flush, debounceMs);
+			timer.unref?.();
+		}
+	};
+	const onEvent = (baseDir, filename) => {
+		if (closed || !filename) return;
+		const rel = filename.toString();
+		if (rel.split(/[\\/]/).some((segment) => IGNORED_SEGMENTS.has(segment))) return;
+		const abs = join(baseDir, rel);
+		if (baseDir === rootDir && !watchers.has(abs)) try {
+			if (statSync(abs).isDirectory()) addWatcher(abs, true);
+		} catch {}
+		enqueuePath(abs);
+	};
+	/** External-root event path: fenced by watcher identity ({watcherRootId,
+	*  generation} — a handle that is neither current nor pending belongs to
+	*  a retired generation and its events are rejected), `filename == null`
+	*  marks the ROOT dirty for rediscovery, and events observed while the
+	*  root's generation is still snapshotting are buffered for replay. */
+	const onExternalEvent = (root, self, filename) => {
+		if (closed) return;
+		const watcher = self();
+		const active = watcher !== void 0 && externalWatchers.get(root) === watcher;
+		const isPending = watcher !== void 0 && pendingOpened.get(root) === watcher;
+		if (!active && !isPending) return;
+		let abs;
+		if (filename == null) abs = root;
+		else {
+			const rel = filename.toString();
+			if (rel.split(/[\\/]/).some((segment) => IGNORED_SEGMENTS.has(segment))) return;
+			abs = rel === "" ? root : join(root, rel);
+		}
+		if (isPending && !active) {
+			capturedDuringSnapshot.push(abs);
+			return;
+		}
+		enqueuePath(abs);
+	};
+	/** Open one external-root watcher into `into` (the committed set at
+	*  startup, the pending set during reset reconciliation). Failures
+	*  degrade ONLY this root (design D7); node_modules-resident roots are
+	*  documented unwatchable and never registered (guardrail G2). */
+	const openExternalWatcher = (root, into) => {
+		if (root.split(/[\\/]/).includes("node_modules")) return;
+		try {
+			let watcher;
+			watcher = watchFn(root, { recursive: true }, (_event, filename) => onExternalEvent(root, () => watcher, filename));
+			watcher.on("error", (err) => degradeExternalRoot(root, err));
+			watcher.unref?.();
+			into.set(root, watcher);
+			session.stickyDiagnostics?.delete(externalDiagnosticKey(root));
+		} catch (err) {
+			degradeExternalRoot(root, err);
+		}
+	};
+	const addWatcher = (dir, recursive) => {
+		const watcher = watchFn(dir, { recursive }, (_event, filename) => onEvent(dir, filename));
+		watcher.on("error", onWatcherError);
+		watcher.unref?.();
+		watchers.set(dir, watcher);
+	};
+	try {
+		addWatcher(rootDir, false);
+		for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+			if (!entry.isDirectory() || IGNORED_SEGMENTS.has(entry.name)) continue;
+			addWatcher(join(rootDir, entry.name), true);
+		}
+	} catch (err) {
+		closeAll();
+		console.warn(`[animus-extract] Turbopack dev watcher unavailable (${String(err)}); source edits require a dev-server restart`);
+		return null;
+	}
+	for (const root of session.externalWatchRoots ?? []) openExternalWatcher(root, externalWatchers);
+	session.onExternalRootResolved = (root) => {
+		if (closed) return;
+		if (externalWatchers.has(root) || pendingOpened.has(root)) return;
+		openExternalWatcher(root, pendingOpened);
+	};
+	session.onExternalRootsCommitted = (roots) => {
+		if (closed) return;
+		const admitted = new Set(roots);
+		for (const [root, watcher] of pendingOpened) externalWatchers.set(root, watcher);
+		pendingOpened = /* @__PURE__ */ new Map();
+		for (const [root, watcher] of [...externalWatchers]) if (!admitted.has(root)) {
+			watcher.close();
+			externalWatchers.delete(root);
+		}
+		for (const abs of capturedDuringSnapshot.splice(0)) enqueuePath(abs);
+	};
+	const handle = {
+		close: closeAll,
+		get died() {
+			return died;
+		},
+		onDied: null,
+		settle: () => updateChain
+	};
+	return handle;
+}
+//#endregion
+export { ANIMUS_CSS_MODULE_ID, CLI_COMMIT_ARTIFACT, CLI_LOCK_ARTIFACT, ExtractionSession, MANIFEST_ARTIFACT, SESSION_ASSETS_DIR, STYLES_ARTIFACT, SYSTEM_PROPS_ARTIFACT, TURBOPACK_SYSTEM_PROPS_ID, analysisCommitPath, analysisInputsPath, analysisStatusPath, claimExclusiveSessionOwner, collectSessionAssets, engineApi, getAnalysisPromise, getAnalyzedHashes, getManifestJson, getReplacementEpoch, getSessionArtifactDir, getSharedCss, getSharedExternalDirs, getSharedExternalEntries, getSharedSystemProps, manifestPath, pruneStaleAssets, readJsonEnvelope, replacementEpochPath, runSessionPipeline, sessionArtifactDir, setAnalysisPromise, setSharedEngine, startTurbopackWatcher, stylesPath, systemPropsPath, verifyCommitRecord };