@animus-ui/extract 0.1.7 → 0.1.8

package/dist/correlate-external-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"correlate-external-tokens.d.ts","sourceRoot":"","sources":["../pipeline/correlate-external-tokens.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAejE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,wBAAwB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA+D3B;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,WAAW,EAAE,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC9C,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,yDAAyD;IACzD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACxC,GAAG,MAAM,EAAE,CAyBX;AAWD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,WAAW,EAAE,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC9C,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,wBAAwB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,IAAI,CAwBP"}
+{"version":3,"file":"correlate-external-tokens.d.ts","sourceRoot":"","sources":["../pipeline/correlate-external-tokens.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAejE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,wBAAwB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA+D3B;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,WAAW,EAAE,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC9C,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,yDAAyD;IACzD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACxC,GAAG,MAAM,EAAE,CAyBX;AAWD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,WAAW,EAAE,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC9C,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,wBAAwB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,IAAI,CAwBP"}

package/dist/discover-packages.d.ts

@@ -12,6 +12,16 @@ export declare function findPackageRoot(absEntryPath: string): string;
  * repo path containing 'dist') must still have its sources discovered.
  */
 export declare const PACKAGE_SRC_EXCLUDES: string[];
+/** True when a PACKAGE-RELATIVE path matches a package-source exclusion
+ *  fragment (the "within the package" filter — see PACKAGE_SRC_EXCLUDES). */
+export declare function isExcludedPackageRelativePath(rel: string): boolean;
+/**
+ * THE package-source walk (guardrail G1 — one policy): shared discovery with
+ * no consumer patterns, then exclusion by package-relative path so fragments
+ * in the package's own location can't blank out its sources. Used by the
+ * collector, hosts' dirty-root rewalks, and watch-path classification alike.
+ */
+export declare function walkPackageSources(packageDir: string, extensionsSet: ReadonlySet<string>): string[];
 /**
  * What one declared include specifier produced, so callers can tell a package
  * that contributed sources apart from one that silently contributed nothing.
@@ -38,6 +48,14 @@ export interface ExternalPackageOutcome {
      */
     fileCount: number;
 }
+/**
+ * Resolve an absolute-path specifier (a relative `includes` entry already
+ * resolved against the system file) without a bundler: the path itself when it
+ * is a file, otherwise the extension and directory-index candidates built from
+ * the caller's extension set. Used only as a fallback — a bundler resolver that
+ * answers first still wins, since it also knows aliases and `.js`→`.ts` mapping.
+ */
+export declare function resolveAbsolutePathSpecifier(absSpecifier: string, extensionsSet: ReadonlySet<string>): string | null;
 export interface CollectedExternalPackages {
     /** New file entries (rootDir-relative, preprocessed) for the analysis set. */
     entries: Array<{
@@ -48,10 +66,20 @@ export interface CollectedExternalPackages {
     packageMap: Record<string, string>;
     /** specifier → absolute src/index.ts path, only for packages with one. */
     sourceEntries: Map<string, string>;
+    /** specifier → absolute entry to scan for branded `Keyframes` collections —
+     *  one per admitted specifier, whatever the package's shape: the redirected
+     *  source entry when src/ serves it, the resolved (dist) entry otherwise.
+     *  Keyed separately from `sourceEntries` because that map doubles as the
+     *  hosts' module-resolution redirect and stays src-only by contract. */
+    keyframesScanEntries: Map<string, string>;
     /** Absolute directories for bundler loader allowlisting (src/ or dist entry dir). */
     packageDirs: string[];
-    /** Absolute package dir → owning specifier (cross-source correlation). */
-    dirOwners: Record<string, string>;
+    /** Absolute package dir → EVERY declared specifier that claimed it, in
+     *  declaration order (set-valued ownership — openspec:
+     *  external-source-watch-ingestion, design D2). The first-wins
+     *  single-value view correlation consumers key on derives via
+     *  `firstOwners`. */
+    dirOwnerSets: Record<string, string[]>;
     /** rootDir-relative file path → owning specifier, for files THIS collection
      *  pushed (first-contributing specifier wins; files the caller's own set
      *  already supplied stay unattributed — they are consumer-owned). */
@@ -95,7 +123,27 @@ export declare function collectExternalPackageSources(opts: {
     } | null>;
     /** Called when a discovered file cannot be read; the file is skipped. */
     onUnreadable: (relPath: string, error: unknown) => void;
+    /**
+     * Called once per specifier immediately after its package dir is derived
+     * and BEFORE that package's sources are walked (openspec:
+     * external-source-watch-ingestion, design D4 — a host can open its
+     * watcher with no blind gap between scan and watch).
+     */
+    onPackageResolved?: (specifier: string, packageDir: string) => void;
 }): Promise<CollectedExternalPackages>;
+/** First-declared specifier per package dir — the single-value ownership
+ *  view correlation consumers key on, derived from `dirOwnerSets`. */
+export declare function firstOwners(dirOwnerSets: Record<string, string[]>): Record<string, string>;
+/**
+ * Excise a set of rejected specifiers from a collection result ATOMICALLY
+ * (openspec: external-source-watch-ingestion, design D5): the returned copy
+ * carries no entries, package-map targets, source entries, package dirs, or
+ * ownership for the rejected packages — a package dir is removed only when
+ * EVERY specifier that claimed it is rejected (a dir-level rejection, such
+ * as the cross-volume gate, always rejects them together). Outcome records
+ * are reporting inputs, not membership, and pass through untouched.
+ */
+export declare function excludeCollectedPackages(collected: CollectedExternalPackages, rejectedSpecifiers: ReadonlySet<string>, rootDir: string): CollectedExternalPackages;
 /**
  * Extract external DS package names from inheritance declarations in the
  * system file.

package/dist/discover-packages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover-packages.d.ts","sourceRoot":"","sources":["../pipeline/discover-packages.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAWF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,YAAY,CAAC;IAC9D;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAqFD,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,qFAAqF;IACrF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;yEAEqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,6BAA6B,CAAC,IAAI,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iFAAiF;IACjF,gBAAgB,EAAE,CAChB,SAAS,EAAE,MAAM,KACd,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC;;;OAGG;IACH,cAAc,EAAE,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACzD,yEAAyE;IACzE,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACzD,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAyMrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,sBAAsB,EAAE,GACjC,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,sBAAsB,EAAE,GACjC,MAAM,GAAG,IAAI,CAMf;AAED,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CAoN1E"}
+{"version":3,"file":"discover-packages.d.ts","sourceRoot":"","sources":["../pipeline/discover-packages.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAKhC,CAAC;AAEF;6EAC6E;AAC7E,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,GACjC,MAAM,EAAE,CAIV;AAWD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,YAAY,CAAC;IAC9D;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,GACjC,MAAM,GAAG,IAAI,CAOf;AAyDD,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;;4EAIwE;IACxE,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,qFAAqF;IACrF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;yBAIqB;IACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC;;yEAEqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,6BAA6B,CAAC,IAAI,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iFAAiF;IACjF,gBAAgB,EAAE,CAChB,SAAS,EAAE,MAAM,KACd,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC;;;OAGG;IACH,cAAc,EAAE,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACzD,yEAAyE;IACzE,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACxD;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CACrE,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA+MrC;AAED;sEACsE;AACtE,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,yBAAyB,EACpC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,yBAAyB,CAsD3B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,sBAAsB,EAAE,GACjC,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,sBAAsB,EAAE,GACjC,MAAM,GAAG,IAAI,CAMf;AAED,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CAoN1E"}

package/dist/index.cjs

@@ -24,13 +24,14 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let crypto = require("crypto");
 let fs = require("fs");
 let path = require("path");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = __toESM(node_path);
 let module$1 = require("module");
 let browserslist = require("browserslist");
 browserslist = __toESM(browserslist);
 let lightningcss = require("lightningcss");
 let _animus_ui_properties = require("@animus-ui/properties");
-let node_fs = require("node:fs");
-let node_path = require("node:path");
 //#region pipeline/assemble-stylesheet.ts
 /**
 * The 7 Animus cascade layers. Always prefixed with `anm-` to avoid
@@ -337,6 +338,126 @@ function discoverFiles(dir, rootDir, excludePatterns, extensionsSet) {
 	return results;
 }
 //#endregion
+//#region pipeline/source-identity.ts
+/**
+* SourceId derivation authority + allowlist membership (openspec:
+* external-source-watch-ingestion, design D1/D2/D5).
+*
+* One shared derivation produces the canonical source identity consumed by
+* discovery, watch ingestion, ownership, deletion pruning, and diagnostics
+* — raw event paths are lookup INPUTS only, so event spelling (symlink
+* alias vs canonical, lexical vs realpath) can never fork identity.
+*
+* The containment and volume helpers are pure and path-API-injectable so
+* Windows semantics are unit-testable via `path.win32` on any host; runtime
+* callers use the ambient platform implementation.
+*/
+/**
+* Structural containment: `target` is the root itself or a descendant of it,
+* decided by `relative()` shape — never by string prefixing, so `/ui` can
+* never claim `/ui-old`, and a cross-drive win32 target (whose relative()
+* result is absolute) is never contained.
+*/
+function isPathWithinRoot(root, target, pathApi = node_path.default) {
+	const rel = pathApi.relative(root, target);
+	return rel === "" || !pathApi.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + pathApi.sep);
+}
+/**
+* Cross-volume gate (design D5): two paths share a platform path root
+* (win32 drive letter or UNC share; always true on posix). Compared
+* case-insensitively — win32 drive letters are case-insensitive.
+*/
+function sharesVolumeRoot(a, b, pathApi = node_path.default) {
+	const volumeOf = (p) => pathApi.parse(pathApi.resolve(p)).root.toLowerCase();
+	return volumeOf(a) === volumeOf(b);
+}
+function canonicalize(p) {
+	try {
+		return (0, node_fs.realpathSync)(p);
+	} catch {
+		return null;
+	}
+}
+function createSourceIdentity(rootDir) {
+	const normalizedRootDir = node_path.default.normalize(rootDir);
+	const canonicalRootDir = canonicalize(normalizedRootDir) ?? normalizedRootDir;
+	const roots = [];
+	const aliases = /* @__PURE__ */ new Map();
+	const owningRecord = (canonicalPath) => {
+		let owner = null;
+		for (const record of roots) {
+			if (!isPathWithinRoot(record.canonical, canonicalPath)) continue;
+			if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+		}
+		return owner;
+	};
+	return {
+		rootDir: normalizedRootDir,
+		canonicalRootDir,
+		registerExternalRoot(root) {
+			const asRegistered = node_path.default.normalize(root);
+			const canonical = canonicalize(asRegistered) ?? asRegistered;
+			const existing = roots.find((record) => record.canonical === canonical);
+			if (existing) return existing.canonical;
+			roots.push({
+				asRegistered,
+				canonical
+			});
+			return canonical;
+		},
+		externalRoots() {
+			return roots.map((record) => record.canonical);
+		},
+		resolveSourceId(inputPath) {
+			const lexical = node_path.default.normalize(inputPath);
+			const canonical = canonicalize(lexical);
+			if (canonical === null) return null;
+			const owner = owningRecord(canonical);
+			const ownedBy = (record) => {
+				const pathInRoot = node_path.default.relative(record.canonical, canonical);
+				return {
+					sourceKey: node_path.default.relative(normalizedRootDir, node_path.default.join(record.asRegistered, pathInRoot)),
+					owningRoot: record.canonical,
+					pathInRoot
+				};
+			};
+			const ownerIsMoreSpecific = owner !== null && owner.canonical.length > canonicalRootDir.length;
+			let resolved;
+			if (!ownerIsMoreSpecific && isPathWithinRoot(canonicalRootDir, canonical)) {
+				const key = node_path.default.relative(canonicalRootDir, canonical);
+				resolved = {
+					sourceKey: key,
+					owningRoot: null,
+					pathInRoot: key
+				};
+			} else if (owner) resolved = ownedBy(owner);
+			else return null;
+			aliases.set(lexical, resolved);
+			aliases.set(canonical, resolved);
+			return resolved;
+		},
+		resolveDeletedSourceId(inputPath) {
+			return aliases.get(node_path.default.normalize(inputPath)) ?? null;
+		},
+		containingExternalRoot(inputPath) {
+			const lexical = node_path.default.normalize(inputPath);
+			let owner = null;
+			for (const record of roots) {
+				if (!(isPathWithinRoot(record.canonical, lexical) || isPathWithinRoot(record.asRegistered, lexical))) continue;
+				if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+			}
+			if (owner) return owner.canonical;
+			const canonical = canonicalize(lexical);
+			if (canonical === null) return null;
+			for (const record of roots) {
+				if (!isPathWithinRoot(record.canonical, canonical)) continue;
+				if (!owner || record.canonical.length > owner.canonical.length) owner = record;
+			}
+			return owner?.canonical ?? null;
+		}
+	};
+}
+//#endregion
 //#region pipeline/discover-packages.ts
 /**
 * Walk up from a resolved package entry file to the nearest directory
@@ -361,6 +482,20 @@ const PACKAGE_SRC_EXCLUDES = [
 	".test.",
 	".spec."
 ];
+/** True when a PACKAGE-RELATIVE path matches a package-source exclusion
+*  fragment (the "within the package" filter — see PACKAGE_SRC_EXCLUDES). */
+function isExcludedPackageRelativePath(rel) {
+	return PACKAGE_SRC_EXCLUDES.some((pattern) => rel.includes(pattern));
+}
+/**
+* THE package-source walk (guardrail G1 — one policy): shared discovery with
+* no consumer patterns, then exclusion by package-relative path so fragments
+* in the package's own location can't blank out its sources. Used by the
+* collector, hosts' dirty-root rewalks, and watch-path classification alike.
+*/
+function walkPackageSources(packageDir, extensionsSet) {
+	return discoverFiles(packageDir, packageDir, [], extensionsSet).filter((absPath) => !isExcludedPackageRelativePath((0, path.relative)(packageDir, absPath)));
+}
 /** Exclusions for the compiled-output fallback when a package does not ship src/. */
 const PACKAGE_OUTPUT_EXCLUDES = [
 	"node_modules",
@@ -369,9 +504,9 @@ const PACKAGE_OUTPUT_EXCLUDES = [
 	".d.ts",
 	".map"
 ];
-const isFile = (path$2) => {
+const isFile = (path$3) => {
 	try {
-		return (0, fs.statSync)(path$2).isFile();
+		return (0, fs.statSync)(path$3).isFile();
 	} catch {
 		return false;
 	}
@@ -399,7 +534,7 @@ function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
 	if ((0, path.isAbsolute)(specifier)) {
 		const resolved = resolveAbsolutePathSpecifier(specifier, extensionsSet);
 		if (!resolved) return null;
-		return !(0, path.relative)(srcDir, resolved).startsWith("..") ? resolved : null;
+		return isPathWithinRoot(srcDir, resolved) ? resolved : null;
 	}
 	const packageName = bareSpecifierPackageName(specifier);
 	return resolveAbsolutePathSpecifier((0, path.join)(srcDir, specifier.slice(packageName.length + 1) || "index"), extensionsSet);
@@ -413,7 +548,7 @@ function sourceEntryForSpecifier(specifier, srcDir, extensionsSet) {
 * file's mtime is readable. Detection only — reporting is the caller's policy.
 */
 function distEntryIsStale(absEntry, srcDir, srcFiles) {
-	if (!(0, path.relative)(srcDir, absEntry).startsWith("..")) return false;
+	if (isPathWithinRoot(srcDir, absEntry)) return false;
 	let distMtime;
 	try {
 		distMtime = (0, fs.statSync)(absEntry).mtimeMs;
@@ -445,15 +580,19 @@ function distEntryIsStale(absEntry, srcDir, srcFiles) {
 * them — any warning or gate is the caller's policy.
 */
 async function collectExternalPackageSources(opts) {
-	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable } = opts;
+	const { specifiers, resolveSpecifier, rootDir, extensionsSet, hasEntry, preprocessFile, onUnreadable, onPackageResolved } = opts;
 	const entries = [];
 	const pushed = /* @__PURE__ */ new Set();
 	const packageMap = {};
 	const sourceEntries = /* @__PURE__ */ new Map();
+	const keyframesScanEntries = /* @__PURE__ */ new Map();
 	const packageDirs = [];
-	const dirOwners = {};
+	const dirOwnerSets = {};
 	const fileOwners = {};
 	const outcomes = [];
+	const claimDir = (dir, specifier) => {
+		(dirOwnerSets[dir] ??= []).push(specifier);
+	};
 	const alreadyIngested = (relPath) => hasEntry(relPath) || pushed.has(relPath);
 	for (const specifier of specifiers) {
 		let absEntry;
@@ -476,12 +615,14 @@ async function collectExternalPackageSources(opts) {
 		let staleDist = false;
 		if ((0, fs.existsSync)(srcDir)) {
 			packageDirs.push(srcDir);
-			dirOwners[srcDir] ??= specifier;
+			claimDir(srcDir, specifier);
+			onPackageResolved?.(specifier, srcDir);
 			const srcEntry = sourceEntryForSpecifier(specifier, srcDir, extensionsSet);
 			if (srcEntry) {
 				packageMap[specifier] = (0, path.relative)(rootDir, srcEntry);
 				sourceEntries.set(specifier, srcEntry);
 			} else packageMap[specifier] = (0, path.relative)(rootDir, absEntry);
+			keyframesScanEntries.set(specifier, srcEntry ?? absEntry);
 			if (!(0, path.isAbsolute)(specifier)) {
 				const packageName = bareSpecifierPackageName(specifier);
 				if (packageName !== specifier && !(packageName in packageMap)) {
@@ -489,13 +630,11 @@ async function collectExternalPackageSources(opts) {
 					if (rootEntry) {
 						packageMap[packageName] = (0, path.relative)(rootDir, rootEntry);
 						sourceEntries.set(packageName, rootEntry);
+						keyframesScanEntries.set(packageName, rootEntry);
 					}
 				}
 			}
-			const pkgFiles = discoverFiles(srcDir, srcDir, [], extensionsSet).filter((absPath) => {
-				const inPkg = (0, path.relative)(srcDir, absPath);
-				return !PACKAGE_SRC_EXCLUDES.some((pattern) => inPkg.includes(pattern));
-			});
+			const pkgFiles = walkPackageSources(srcDir, extensionsSet);
 			staleDist = distEntryIsStale(absEntry, srcDir, pkgFiles);
 			for (const pkgFile of pkgFiles) {
 				const relPath = (0, path.relative)(rootDir, pkgFile);
@@ -523,8 +662,10 @@ async function collectExternalPackageSources(opts) {
 		} else {
 			const outputDir = (0, path.dirname)(absEntry);
 			packageDirs.push(outputDir);
-			dirOwners[outputDir] ??= specifier;
+			claimDir(outputDir, specifier);
+			onPackageResolved?.(specifier, outputDir);
 			packageMap[specifier] = (0, path.relative)(rootDir, absEntry);
+			keyframesScanEntries.set(specifier, absEntry);
 			const outputExtensions = new Set(extensionsSet);
 			outputExtensions.add((0, path.extname)(absEntry));
 			const outputFiles = discoverFiles(outputDir, outputDir, [], outputExtensions).filter((file) => {
@@ -566,12 +707,71 @@ async function collectExternalPackageSources(opts) {
 		entries,
 		packageMap,
 		sourceEntries,
+		keyframesScanEntries,
 		packageDirs,
-		dirOwners,
+		dirOwnerSets,
 		fileOwners,
 		outcomes
 	};
 }
+/** First-declared specifier per package dir — the single-value ownership
+*  view correlation consumers key on, derived from `dirOwnerSets`. */
+function firstOwners(dirOwnerSets) {
+	const owners = {};
+	for (const [dir, specifiers] of Object.entries(dirOwnerSets)) if (specifiers.length > 0) owners[dir] = specifiers[0];
+	return owners;
+}
+/**
+* Excise a set of rejected specifiers from a collection result ATOMICALLY
+* (openspec: external-source-watch-ingestion, design D5): the returned copy
+* carries no entries, package-map targets, source entries, package dirs, or
+* ownership for the rejected packages — a package dir is removed only when
+* EVERY specifier that claimed it is rejected (a dir-level rejection, such
+* as the cross-volume gate, always rejects them together). Outcome records
+* are reporting inputs, not membership, and pass through untouched.
+*/
+function excludeCollectedPackages(collected, rejectedSpecifiers, rootDir) {
+	if (rejectedSpecifiers.size === 0) return collected;
+	const rejectedDirs = Object.entries(collected.dirOwnerSets).filter(([, specs]) => specs.every((s) => rejectedSpecifiers.has(s))).map(([dir]) => dir);
+	const underRejectedDir = (absPath) => rejectedDirs.some((dir) => isPathWithinRoot(dir, absPath));
+	const targetRejected = (specifier, absTarget) => rejectedSpecifiers.has(specifier) || underRejectedDir(absTarget);
+	const packageMap = {};
+	for (const [specifier, relTarget] of Object.entries(collected.packageMap)) {
+		if (targetRejected(specifier, (0, path.resolve)(rootDir, relTarget))) continue;
+		packageMap[specifier] = relTarget;
+	}
+	const sourceEntries = /* @__PURE__ */ new Map();
+	for (const [specifier, absEntry] of collected.sourceEntries) {
+		if (targetRejected(specifier, absEntry)) continue;
+		sourceEntries.set(specifier, absEntry);
+	}
+	const keyframesScanEntries = /* @__PURE__ */ new Map();
+	for (const [specifier, absEntry] of collected.keyframesScanEntries) {
+		if (targetRejected(specifier, absEntry)) continue;
+		keyframesScanEntries.set(specifier, absEntry);
+	}
+	const dirOwnerSets = {};
+	for (const [dir, specs] of Object.entries(collected.dirOwnerSets)) {
+		const kept = specs.filter((s) => !rejectedSpecifiers.has(s));
+		if (kept.length === 0) continue;
+		dirOwnerSets[dir] = kept;
+	}
+	const fileOwners = {};
+	for (const [relPath, owner] of Object.entries(collected.fileOwners)) {
+		if (rejectedSpecifiers.has(owner)) continue;
+		fileOwners[relPath] = owner;
+	}
+	return {
+		entries: collected.entries.filter((entry) => !rejectedSpecifiers.has(collected.fileOwners[entry.path])),
+		packageMap,
+		sourceEntries,
+		keyframesScanEntries,
+		packageDirs: collected.packageDirs.filter((dir) => !rejectedDirs.includes(dir)),
+		dirOwnerSets,
+		fileOwners,
+		outcomes: collected.outcomes
+	};
+}
 /**
 * Extract external DS package names from inheritance declarations in the
 * system file.
@@ -941,7 +1141,7 @@ function buildSourceTokenIndex(opts) {
 		if ((0, fs.existsSync)((0, path.join)(packageRoot, "package.json"))) addOwnerDir(packageRoot, specifier);
 	}
 	for (const [modulePath, exports] of Object.entries(manifests)) {
-		const owner = realDirOwners.find(({ dir }) => modulePath === dir || modulePath.startsWith(dir + path.sep));
+		const owner = realDirOwners.find(({ dir }) => isPathWithinRoot(dir, modulePath));
 		if (!owner) continue;
 		let tokens = index.get(owner.specifier);
 		if (!tokens) {
@@ -1082,16 +1282,42 @@ function postProcessCss(css, opts) {
 /** Stable code for selector forms with no substitutable subject.
 *  Mirrors the Rust constant in `extract-v2/src/eval.rs`. */
 const SELECTOR_UNSUPPORTED_SUBJECT = "animus.selector.unsupported-subject";
+/** Unresolved-parent chain-drop message (mirrors the Rust diagnostic in
+*  `extract-v2` — the ONE encoding of this message shape; consumers match
+*  through the helpers below, never their own regex copies). */
+const UNRESOLVED_PARENT_RE = /chain dropped: could not resolve parent component '([^']+)'/;
+/** True when the diagnostic reports a chain dropped for an unresolved
+*  parent component. */
+function isUnresolvedParentDrop(diagnostic) {
+	return typeof diagnostic?.message === "string" && UNRESOLVED_PARENT_RE.test(diagnostic.message);
+}
+/** The parent binding named by an unresolved-parent drop, or null when the
+*  diagnostic is not one. */
+function unresolvedParentName(diagnostic) {
+	if (typeof diagnostic?.message !== "string") return null;
+	return UNRESOLVED_PARENT_RE.exec(diagnostic.message)?.[1] ?? null;
+}
 /** True when the selector string carries at least one substitutable `&`
 *  subject outside quoted text (mirrors the Rust `selector_subject` walk —
 *  ancestor, leading, and repeated subjects all count; a `&` inside a
 *  quoted attribute value does not). */
 function hasSelectorSubject(value) {
 	let quote = null;
-	for (const c of value) if (quote !== null) {
-		if (c === quote) quote = null;
-	} else if (c === "\"" || c === "'") quote = c;
-	else if (c === "&") return true;
+	let escaped = false;
+	for (const c of value) {
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (c === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote !== null) {
+			if (c === quote) quote = null;
+		} else if (c === "\"" || c === "'") quote = c;
+		else if (c === "&") return true;
+	}
 	return false;
 }
 /**
@@ -1509,17 +1735,17 @@ function stripJsonc(text) {
 	}
 	return out.replace(/,(\s*[}\]])/g, "$1");
 }
-function readConfig(path$1) {
+function readConfig(path$2) {
 	let raw;
 	try {
-		raw = (0, fs.readFileSync)(path$1, "utf-8");
+		raw = (0, fs.readFileSync)(path$2, "utf-8");
 	} catch {
 		return null;
 	}
 	try {
 		const json = JSON.parse(stripJsonc(raw));
 		return {
-			dir: (0, path.dirname)(path$1),
+			dir: (0, path.dirname)(path$2),
 			compilerOptions: json.compilerOptions ?? {},
 			extends: json.extends
 		};
@@ -1664,6 +1890,79 @@ async function preprocessMdx(source, filename) {
 	}
 }
 //#endregion
+//#region pipeline/replacement-plans.ts
+const snapshotByManifest = /* @__PURE__ */ new WeakMap();
+function snapshotFilePlans(manifest) {
+	const memoKey = manifest !== null && typeof manifest === "object" ? manifest : null;
+	if (memoKey) {
+		const cached = snapshotByManifest.get(memoKey);
+		if (cached) return cached;
+	}
+	const entriesByFile = /* @__PURE__ */ new Map();
+	for (const [id, desc] of Object.entries(manifest?.components ?? {})) {
+		const file = desc.file;
+		if (!file) continue;
+		const list = entriesByFile.get(file) ?? [];
+		list.push([id, desc.replacement ?? ""]);
+		entriesByFile.set(file, list);
+	}
+	const snapshot = /* @__PURE__ */ new Map();
+	for (const [file, entries] of entriesByFile) {
+		entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+		snapshot.set(file, JSON.stringify(entries));
+	}
+	if (memoKey) snapshotByManifest.set(memoKey, snapshot);
+	return snapshot;
+}
+/**
+* Rel paths whose plan changed between two snapshots: absent→present,
+* present→absent, and any change to membership or replacement content.
+* `exclude` drops one path (the changed file itself on the edit path — its
+* own modules are already in the update set).
+*/
+function diffFilePlans(prev, next, opts) {
+	const changed = /* @__PURE__ */ new Set();
+	for (const [file, plan] of next) if (prev.get(file) !== plan) changed.add(file);
+	for (const file of prev.keys()) if (!next.has(file)) changed.add(file);
+	if (opts?.exclude) changed.delete(opts.exclude);
+	return [...changed].sort();
+}
+/** Domain prefix keeping the epoch hash disjoint from every other
+*  contentHash use in the pipeline (design D5). */
+const REPLACEMENT_PLANS_DOMAIN = "animus-replacement-plans-v1\0";
+/** Section marker for the served-dependency witness. Leads with NUL: every
+*  plan entry ends `…\0` and neither file paths nor plan JSON contain NUL,
+*  so `\0\0` is unreachable from entry serialization alone — a snapshot can
+*  never forge the witness section. */
+const SERVED_DEPENDENCY_DOMAIN = "\0animus-served-dependency-v1\0";
+/**
+* Canonical replacement epoch: contentHash over the domain-prefixed, sorted
+* canonical serialization of a file-plan snapshot — each entry contributes
+* `file + '\0' + plan + '\0'` (unambiguous: neither file paths nor the
+* JSON plan strings contain NUL). Byte-identical plans → identical epoch;
+* any membership/replacement/absent↔present change moves it.
+*
+* `servedDependencyWitness` extends the epoch to content the plans cannot
+* see but restored modules depend on: transformed modules import the
+* session's served system-props artifact, so a consumer passes that
+* artifact's content here and an offline change to it moves the epoch —
+* invalidating persistent-cache snapshots that reference the old epoch
+* artifact. Absence and empty-string are distinct values.
+*
+* This is THE epoch definition — integrations consume this hash (or the
+* snapshot diff) and never define their own. Epoch values compare only for
+* equality (a moved value invalidates), so the serialization is free to
+* evolve with a domain bump: sessions running different serializations
+* simply disagree once and rebuild.
+*/
+function hashReplacementPlans(snapshot, servedDependencyWitness) {
+	const entries = [...snapshot.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	let serialized = REPLACEMENT_PLANS_DOMAIN;
+	for (const [file, plan] of entries) serialized += file + "\0" + plan + "\0";
+	if (servedDependencyWitness !== void 0) serialized += SERVED_DEPENDENCY_DOMAIN + servedDependencyWitness;
+	return contentHash(serialized);
+}
+//#endregion
 //#region pipeline/utils.ts
 /** Convert camelCase CSS property names to kebab-case. */
 function camelToKebab(str) {
@@ -1733,27 +2032,40 @@ exports.camelToKebab = camelToKebab;
 exports.clearEngineCache = clearEngineCache;
 exports.collectExternalPackageSources = collectExternalPackageSources;
 exports.contentHash = contentHash;
+exports.createSourceIdentity = createSourceIdentity;
 exports.createV2EngineApi = createV2EngineApi;
+exports.diffFilePlans = diffFilePlans;
 exports.discoverFiles = discoverFiles;
 exports.enforceExternalTokenContracts = enforceExternalTokenContracts;
+exports.excludeCollectedPackages = excludeCollectedPackages;
 exports.extractSystemFilePackages = extractSystemFilePackages;
 exports.findAssetSpecifiers = findAssetSpecifiers;
 exports.findPackageRoot = findPackageRoot;
+exports.firstOwners = firstOwners;
 exports.formatRustTimingWaterfall = formatRustTimingWaterfall;
+exports.hashReplacementPlans = hashReplacementPlans;
+exports.isExcludedPackageRelativePath = isExcludedPackageRelativePath;
+exports.isPathWithinRoot = isPathWithinRoot;
+exports.isUnresolvedParentDrop = isUnresolvedParentDrop;
 exports.loadSystemConfig = loadSystemConfig;
 exports.mergeExternalKeyframes = mergeExternalKeyframes;
 exports.postProcessCss = postProcessCss;
 exports.preprocessMdx = preprocessMdx;
 exports.readTsconfigAliasPairs = readTsconfigAliasPairs;
+exports.resolveAbsolutePathSpecifier = resolveAbsolutePathSpecifier;
 exports.resolveAssetFile = resolveAssetFile;
 exports.resolveLightningTargets = resolveLightningTargets;
 exports.resolveThroughPathAliases = resolveThroughPathAliases;
 exports.runProjectAnalysis = runProjectAnalysis;
 exports.serializeStaticCss = serializeStaticCss;
+exports.sharesVolumeRoot = sharesVolumeRoot;
+exports.snapshotFilePlans = snapshotFilePlans;
 exports.staleDistIncludesMessage = staleDistIncludesMessage;
 exports.stripLeadingLayerDeclaration = stripLeadingLayerDeclaration;
 exports.substituteAssetPlaceholders = substituteAssetPlaceholders;
 exports.surfaceManifestDiagnostics = surfaceManifestDiagnostics;
 exports.toWatchKeys = toWatchKeys;
 exports.unresolvableIncludesMessage = unresolvableIncludesMessage;
+exports.unresolvedParentName = unresolvedParentName;
 exports.validateLayerOrder = validateLayerOrder;
+exports.walkPackageSources = walkPackageSources;

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export { KEYFRAMES_EXPORT_COLLISION, KEYFRAMES_EXTERNAL_ENTRY_FAILED, mergeExter
 export type { ExternalKeyframesMerge } from './external-keyframes';
 export { discoverFiles } from './discover-files';
 export type { CollectedExternalPackages, ExternalPackageOutcome, } from './discover-packages';
-export { collectExternalPackageSources, extractSystemFilePackages, findPackageRoot, staleDistIncludesMessage, unresolvableIncludesMessage, } from './discover-packages';
+export { collectExternalPackageSources, excludeCollectedPackages, extractSystemFilePackages, findPackageRoot, firstOwners, isExcludedPackageRelativePath, resolveAbsolutePathSpecifier, staleDistIncludesMessage, unresolvableIncludesMessage, walkPackageSources, } from './discover-packages';
+export type { ResolvedSourceId, SourceIdentity } from './source-identity';
+export { createSourceIdentity, isPathWithinRoot, sharesVolumeRoot, } from './source-identity';
 export { findAssetSpecifiers, substituteAssetPlaceholders, } from './asset-placeholders';
 export { resolveAssetFile, resolveThroughPathAliases } from './resolve-asset';
 export { enforceExternalTokenContracts } from './correlate-external-tokens';
@@ -29,10 +31,12 @@ export { readTsconfigAliasPairs } from './tsconfig-paths';
 export type { DynamicPropConfigEntry, DynamicPropMeta, } from './dynamic-prop-config';
 export { buildDynamicPropConfig } from './dynamic-prop-config';
 export type { ManifestDiagnostic } from './manifest-diagnostics';
-export { surfaceManifestDiagnostics } from './manifest-diagnostics';
+export { isUnresolvedParentDrop, surfaceManifestDiagnostics, unresolvedParentName, } from './manifest-diagnostics';
 export type { DefaultExtension, PreprocessMdxResult } from './mdx-preprocessor';
 export { DEFAULT_EXTENSIONS, preprocessMdx } from './mdx-preprocessor';
 export { applyPrefix } from './prefix';
+export type { FilePlanSnapshot } from './replacement-plans';
+export { diffFilePlans, hashReplacementPlans, snapshotFilePlans, } from './replacement-plans';
 export { applyUnitFallback } from './unit-fallback';
 export { camelToKebab } from './utils';
 export { toWatchKeys } from './watch-keys';