@wrtnlabs/evidence 0.0.0

package/lib/internal/TreeSitterAssets.js

@@ -0,0 +1,367 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeSitterAssets = void 0;
+const _isTypeUint32_1 = __importStar(require("typia/lib/internal/_isTypeUint32"));
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const node_path_1 = __importDefault(require("node:path"));
+const typia_1 = __importDefault(require("typia"));
+const EvidenceParserError_1 = require("../parsers/EvidenceParserError");
+const TreeSitterAssetCache_1 = require("./TreeSitterAssetCache");
+const TreeSitterAssetScope_1 = require("./TreeSitterAssetScope");
+const parser_grammars_json_1 = __importDefault(require("./parser-grammars.json"));
+/**
+ * Reads compiled grammar provenance and lazily acquires verified pinned bytes.
+ *
+ * Metadata validation occurs before cache-key or URL use so a corrupted package
+ * catalog cannot redirect filesystem writes or downloads outside the asset boundary.
+ */
+class TreeSitterAssets {
+    /**
+     * Caches grammar bytes under the inherited and constructor-provided acquisition controls.
+     *
+     * The constructor creates this instance after merging scope controls with local
+     * overrides, so every bytes request follows the same policy.
+     */
+    cache;
+    /**
+     * Captures optional acquisition overrides without accessing grammar assets.
+     *
+     * Scope controls supply defaults, and explicit constructor options take precedence
+     * before a later bytes call resolves a cache entry or download.
+     */
+    constructor(options = {}) {
+        this.cache = new TreeSitterAssetCache_1.TreeSitterAssetCache({
+            ...TreeSitterAssetScope_1.TreeSitterAssetScope.current(),
+            ...options,
+        });
+    }
+    /**
+     * Returns validated grammar metadata without initializing WASM or acquiring bytes.
+     *
+     * Consumers can inspect the compiled catalog safely because readManifest rejects
+     * invalid records before they are returned.
+     */
+    async list() {
+        return this.readManifest();
+    }
+    /**
+     * Resolves one validated pinned grammar by its catalog ID.
+     *
+     * This lookup does not prepare or load the WASM bytes; unknown IDs become an
+     * asset-manifest error with repair guidance.
+     */
+    async grammar(id) {
+        const grammar = (await this.list()).find((entry) => entry.id === id);
+        if (grammar === undefined)
+            throw new EvidenceParserError_1.EvidenceParserError("asset-manifest", id, `The parser catalog has no ${id} grammar. Restore the package's pinned catalog.`);
+        return grammar;
+    }
+    /**
+     * Obtains a caller-owned copy of verified grammar bytes from the immutable cache.
+     *
+     * Input is cloned and validated before cache acquisition, preventing unsafe
+     * metadata from selecting a filesystem key or network destination.
+     */
+    async bytes(input) {
+        const grammar = structuredClone((() => {
+            const _ao0 = (input, _path, _exceptionable = true) => ("string" === typeof input.id || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".id",
+                expected: "string",
+                value: input.id
+            }, _errorFactory)) && ("string" === typeof input.repository || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".repository",
+                expected: "string",
+                value: input.repository
+            }, _errorFactory)) && ("string" === typeof input.version || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".version",
+                expected: "string",
+                value: input.version
+            }, _errorFactory)) && ("string" === typeof input.commit || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".commit",
+                expected: "string",
+                value: input.commit
+            }, _errorFactory)) && (("object" === typeof input.wasm && null !== input.wasm || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".wasm",
+                expected: "IEvidenceGrammarAsset",
+                value: input.wasm
+            }, _errorFactory)) && _ao1(input.wasm, _path + ".wasm", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".wasm",
+                expected: "IEvidenceGrammarAsset",
+                value: input.wasm
+            }, _errorFactory)) && (("object" === typeof input.license && null !== input.license || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".license",
+                expected: "IEvidenceGrammarAsset",
+                value: input.license
+            }, _errorFactory)) && _ao1(input.license, _path + ".license", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".license",
+                expected: "IEvidenceGrammarAsset",
+                value: input.license
+            }, _errorFactory));
+            const _ao1 = (input, _path, _exceptionable = true) => ("string" === typeof input.file || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".file",
+                expected: "string",
+                value: input.file
+            }, _errorFactory)) && ("string" === typeof input.url || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".url",
+                expected: "string",
+                value: input.url
+            }, _errorFactory)) && ("string" === typeof input.sha256 && (RegExp("^[0-9a-f]{64}$").test(input.sha256) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".sha256",
+                expected: "string & Pattern<\"^[0-9a-f]{64}$\">",
+                value: input.sha256
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".sha256",
+                expected: "(string & Pattern<\"^[0-9a-f]{64}$\">)",
+                value: input.sha256
+            }, _errorFactory)) && ("number" === typeof input.size && (_isTypeUint32_1._isTypeUint32(input.size) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".size",
+                expected: "number & Type<\"uint32\">",
+                value: input.size
+            }, _errorFactory)) && (1 <= input.size || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".size",
+                expected: "number & Minimum<1>",
+                value: input.size
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".size",
+                expected: "(number & Type<\"uint32\"> & Minimum<1>)",
+                value: input.size
+            }, _errorFactory));
+            const _io0 = input => "string" === typeof input.id && "string" === typeof input.repository && "string" === typeof input.version && "string" === typeof input.commit && ("object" === typeof input.wasm && null !== input.wasm && _io1(input.wasm)) && ("object" === typeof input.license && null !== input.license && _io1(input.license));
+            const _io1 = input => "string" === typeof input.file && "string" === typeof input.url && ("string" === typeof input.sha256 && RegExp("^[0-9a-f]{64}$").test(input.sha256)) && ("number" === typeof input.size && (_isTypeUint32_1._isTypeUint32(input.size) && 1 <= input.size));
+            const __is = input => "object" === typeof input && null !== input && _io0(input);
+            let _errorFactory;
+            return (input, errorFactory) => {
+                if (false === __is(input)) {
+                    _errorFactory = errorFactory;
+                    ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceGrammar",
+                        value: input
+                    }, _errorFactory)) && _ao0(input, _path + "", true) || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceGrammar",
+                        value: input
+                    }, _errorFactory))(input, "$input", true);
+                }
+                return input;
+            };
+        })()(input));
+        this.validate(grammar);
+        return this.cache.bytes(grammar);
+    }
+    /**
+     * Validates the packaged grammar pins and rejects duplicate identifiers.
+     *
+     * list delegates here before exposing metadata, ensuring each grammar has safe
+     * provenance paths and credential-free HTTPS asset URLs. The pins are imported
+     * from parser-grammars.json as a plain module; no payload bytes are read here.
+     */
+    readManifest() {
+        try {
+            const entries = (() => {
+                const _ao0 = (input, _path, _exceptionable = true) => ("string" === typeof input.id || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".id",
+                    expected: "string",
+                    value: input.id
+                }, _errorFactory)) && ("string" === typeof input.repository || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".repository",
+                    expected: "string",
+                    value: input.repository
+                }, _errorFactory)) && ("string" === typeof input.version || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".version",
+                    expected: "string",
+                    value: input.version
+                }, _errorFactory)) && ("string" === typeof input.commit || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".commit",
+                    expected: "string",
+                    value: input.commit
+                }, _errorFactory)) && (("object" === typeof input.wasm && null !== input.wasm || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".wasm",
+                    expected: "IEvidenceGrammarAsset",
+                    value: input.wasm
+                }, _errorFactory)) && _ao1(input.wasm, _path + ".wasm", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".wasm",
+                    expected: "IEvidenceGrammarAsset",
+                    value: input.wasm
+                }, _errorFactory)) && (("object" === typeof input.license && null !== input.license || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".license",
+                    expected: "IEvidenceGrammarAsset",
+                    value: input.license
+                }, _errorFactory)) && _ao1(input.license, _path + ".license", true && _exceptionable) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".license",
+                    expected: "IEvidenceGrammarAsset",
+                    value: input.license
+                }, _errorFactory));
+                const _ao1 = (input, _path, _exceptionable = true) => ("string" === typeof input.file || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".file",
+                    expected: "string",
+                    value: input.file
+                }, _errorFactory)) && ("string" === typeof input.url || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".url",
+                    expected: "string",
+                    value: input.url
+                }, _errorFactory)) && ("string" === typeof input.sha256 && (RegExp("^[0-9a-f]{64}$").test(input.sha256) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".sha256",
+                    expected: "string & Pattern<\"^[0-9a-f]{64}$\">",
+                    value: input.sha256
+                }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".sha256",
+                    expected: "(string & Pattern<\"^[0-9a-f]{64}$\">)",
+                    value: input.sha256
+                }, _errorFactory)) && ("number" === typeof input.size && (_isTypeUint32_1._isTypeUint32(input.size) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".size",
+                    expected: "number & Type<\"uint32\">",
+                    value: input.size
+                }, _errorFactory)) && (1 <= input.size || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".size",
+                    expected: "number & Minimum<1>",
+                    value: input.size
+                }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                    method: "typia.assert",
+                    path: _path + ".size",
+                    expected: "(number & Type<\"uint32\"> & Minimum<1>)",
+                    value: input.size
+                }, _errorFactory));
+                const _io0 = input => "string" === typeof input.id && "string" === typeof input.repository && "string" === typeof input.version && "string" === typeof input.commit && ("object" === typeof input.wasm && null !== input.wasm && _io1(input.wasm)) && ("object" === typeof input.license && null !== input.license && _io1(input.license));
+                const _io1 = input => "string" === typeof input.file && "string" === typeof input.url && ("string" === typeof input.sha256 && RegExp("^[0-9a-f]{64}$").test(input.sha256)) && ("number" === typeof input.size && (_isTypeUint32_1._isTypeUint32(input.size) && 1 <= input.size));
+                const __is = input => Array.isArray(input) && input.every(elem => "object" === typeof elem && null !== elem && _io0(elem));
+                let _errorFactory;
+                return (input, errorFactory) => {
+                    if (false === __is(input)) {
+                        _errorFactory = errorFactory;
+                        ((input, _path, _exceptionable = true) => (Array.isArray(input) || _assertGuard_1._assertGuard(true, {
+                            method: "typia.assert",
+                            path: _path + "",
+                            expected: "Array<IEvidenceGrammar>",
+                            value: input
+                        }, _errorFactory)) && input.every((elem, _index2) => ("object" === typeof elem && null !== elem || _assertGuard_1._assertGuard(true, {
+                            method: "typia.assert",
+                            path: _path + "[" + _index2 + "]",
+                            expected: "IEvidenceGrammar",
+                            value: elem
+                        }, _errorFactory)) && _ao0(elem, _path + "[" + _index2 + "]", true) || _assertGuard_1._assertGuard(true, {
+                            method: "typia.assert",
+                            path: _path + "[" + _index2 + "]",
+                            expected: "IEvidenceGrammar",
+                            value: elem
+                        }, _errorFactory)) || _assertGuard_1._assertGuard(true, {
+                            method: "typia.assert",
+                            path: _path + "",
+                            expected: "Array<IEvidenceGrammar>",
+                            value: input
+                        }, _errorFactory))(input, "$input", true);
+                    }
+                    return input;
+                };
+            })()(structuredClone(parser_grammars_json_1.default));
+            const ids = new Set();
+            for (const entry of entries) {
+                if (ids.has(entry.id))
+                    throw new Error(`Duplicate grammar ID: ${entry.id}`);
+                ids.add(entry.id);
+                this.validate(entry);
+            }
+            return entries;
+        }
+        catch (cause) {
+            throw new EvidenceParserError_1.EvidenceParserError("asset-manifest", "grammar-catalog", "The compiled grammar catalog is invalid. Restore this package's parser metadata.", undefined, { cause });
+        }
+    }
+    /**
+     * Rejects unsafe asset metadata before it chooses a filesystem key or network destination.
+     *
+     * Both grammar WASM and license records require relative provenance paths and
+     * credential-free HTTPS URLs to remain within the asset trust boundary.
+     */
+    validate(grammar) {
+        for (const asset of [grammar.wasm, grammar.license]) {
+            this.location(asset.file);
+            const url = new URL(asset.url);
+            if (url.protocol !== "https:" ||
+                url.username !== "" ||
+                url.password !== "")
+                throw new EvidenceParserError_1.EvidenceParserError("asset-manifest", grammar.id, "Parser assets require an HTTPS URL without credentials.");
+        }
+    }
+    /**
+     * Requires a provenance path to remain relative on every supported platform.
+     *
+     * This lexical validation rejects empty, absolute, and parent-traversing paths
+     * without requiring the referenced asset file to exist locally.
+     */
+    location(file) {
+        if (file === "" ||
+            file.replaceAll("\\", "/").split("/").includes("..") ||
+            node_path_1.default.posix.isAbsolute(file) ||
+            node_path_1.default.win32.isAbsolute(file))
+            throw new EvidenceParserError_1.EvidenceParserError("asset-manifest", file, "A grammar provenance path must be relative and cannot traverse parent directories.");
+    }
+}
+exports.TreeSitterAssets = TreeSitterAssets;

package/lib/internal/TreeSitterRange.d.ts

@@ -0,0 +1,17 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceSourceRange } from "../structures/IEvidenceSourceRange";
+/**
+ * Converts web-tree-sitter UTF-16, zero-based coordinates into Evidence source ranges.
+ *
+ * Adapters use this boundary to preserve parser offsets while exposing Evidence's
+ * one-based line and column positions for diagnostics, hosts, and unit sites.
+ */
+export declare namespace TreeSitterRange {
+    /**
+     * Returns the node's half-open range in Evidence coordinate conventions.
+     *
+     * Offsets remain the parser's UTF-16 string indices, while rows and columns are
+     * incremented to the one-based positions expected by Evidence consumers.
+     */
+    function from(node: Node): IEvidenceSourceRange;
+}

package/lib/internal/TreeSitterRange.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeSitterRange = void 0;
+/**
+ * Converts web-tree-sitter UTF-16, zero-based coordinates into Evidence source ranges.
+ *
+ * Adapters use this boundary to preserve parser offsets while exposing Evidence's
+ * one-based line and column positions for diagnostics, hosts, and unit sites.
+ */
+var TreeSitterRange;
+(function (TreeSitterRange) {
+    /**
+     * Returns the node's half-open range in Evidence coordinate conventions.
+     *
+     * Offsets remain the parser's UTF-16 string indices, while rows and columns are
+     * incremented to the one-based positions expected by Evidence consumers.
+     */
+    function from(node) {
+        return {
+            start: {
+                offset: node.startIndex,
+                line: node.startPosition.row + 1,
+                column: node.startPosition.column + 1,
+            },
+            end: {
+                offset: node.endIndex,
+                line: node.endPosition.row + 1,
+                column: node.endPosition.column + 1,
+            },
+        };
+    }
+    TreeSitterRange.from = from;
+})(TreeSitterRange || (exports.TreeSitterRange = TreeSitterRange = {}));

package/lib/internal/TreeSitterRuntime.d.ts

@@ -0,0 +1,17 @@
+import { Language } from "web-tree-sitter";
+import type { IEvidenceGrammar } from "../structures/IEvidenceGrammar";
+/**
+ * Initializes the WASM binding once and shares immutable loaded grammar modules.
+ *
+ * web-tree-sitter offers no language disposal API, so cache keys use verified
+ * byte digests and instances are intentionally process-lifetime resources.
+ */
+export declare namespace TreeSitterRuntime {
+    /**
+     * Returns the language module for verified grammar bytes after engine initialization.
+     *
+     * The runtime key is the grammar digest, so equivalent metadata objects share
+     * one process-lifetime Language instance regardless of object identity.
+     */
+    function language(grammar: IEvidenceGrammar, bytes: Uint8Array): Promise<Language>;
+}

package/lib/internal/TreeSitterRuntime.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeSitterRuntime = void 0;
+const promises_1 = require("node:fs/promises");
+const tstl_1 = require("tstl");
+const web_tree_sitter_1 = require("web-tree-sitter");
+const EvidenceParserError_1 = require("../parsers/EvidenceParserError");
+/**
+ * Initializes the WASM binding once and shares immutable loaded grammar modules.
+ *
+ * web-tree-sitter offers no language disposal API, so cache keys use verified
+ * byte digests and instances are intentionally process-lifetime resources.
+ */
+var TreeSitterRuntime;
+(function (TreeSitterRuntime) {
+    /**
+     * Returns the language module for verified grammar bytes after engine initialization.
+     *
+     * The runtime key is the grammar digest, so equivalent metadata objects share
+     * one process-lifetime Language instance regardless of object identity.
+     */
+    async function language(grammar, bytes) {
+        await initialization.get();
+        return languages.get(grammar, bytes);
+    }
+    TreeSitterRuntime.language = language;
+    /**
+     * Initializes the installed web-tree-sitter engine once on first use.
+     *
+     * Loading the packaged core WASM from its resolved path avoids cwd-sensitive
+     * fetches, and failures become runtime-initialization diagnostics.
+     */
+    const initialization = new tstl_1.Singleton(async () => {
+        try {
+            // Supplying local bytes avoids cwd-sensitive URLs and any runtime fetch fallback.
+            const wasmBinary = await (0, promises_1.readFile)(require.resolve("web-tree-sitter/web-tree-sitter.wasm"));
+            await web_tree_sitter_1.Parser.init({ wasmBinary });
+        }
+        catch (cause) {
+            throw new EvidenceParserError_1.EvidenceParserError("runtime-initialization", "web-tree-sitter", "Cannot initialize the packaged WASM runtime. Inspect the installed core asset and underlying error.", undefined, { cause });
+        }
+    });
+    /**
+     * Shares one grammar Language load per immutable WASM digest.
+     *
+     * The singleton compares digest strings rather than input objects because all
+     * callers with the same verified bytes can safely reuse one loaded module.
+     */
+    const languages = new tstl_1.VariadicSingleton(async (grammar, bytes) => {
+        try {
+            return await web_tree_sitter_1.Language.load(bytes);
+        }
+        catch (cause) {
+            throw new EvidenceParserError_1.EvidenceParserError("grammar-incompatible", grammar.wasm.file, `Cannot link grammar ${grammar.id} (${grammar.version}) with web-tree-sitter. Supply a compatible pinned grammar/runtime pair.`, undefined, { cause });
+        }
+    }, ([grammar]) => (0, tstl_1.hash)(grammar.wasm.sha256), ([left], [right]) => left.wasm.sha256 === right.wasm.sha256);
+})(TreeSitterRuntime || (exports.TreeSitterRuntime = TreeSitterRuntime = {}));

package/lib/internal/WatchDependencySet.d.ts

@@ -0,0 +1,31 @@
+import type { IEvidenceCheckAnalysis } from "../structures/IEvidenceCheckAnalysis";
+import type { IEvidenceSourceDependency } from "../structures/IEvidenceSourceDependency";
+/**
+ * Builds deterministic watch dependency sets from an analysis snapshot.
+ *
+ * Merging upgrades duplicate paths to recursive monitoring, preserving the
+ * broader invalidation boundary without retaining duplicate watcher requests.
+ */
+export declare namespace WatchDependencySet {
+    /**
+     * Combines configuration dependencies with every loaded claim and reference inventory.
+     *
+     * Watch setup uses the merged result so edits to configuration, selected claims,
+     * or selected reference sources can invalidate the published analysis.
+     */
+    function analysis(value: IEvidenceCheckAnalysis, configuration: IEvidenceSourceDependency[]): IEvidenceSourceDependency[];
+    /**
+     * Normalizes, deduplicates, and orders dependency paths for stable snapshots.
+     *
+     * Duplicate paths retain recursive monitoring when any source requires it,
+     * preserving the broadest invalidation boundary in the returned set.
+     */
+    function merge(...groups: IEvidenceSourceDependency[][]): IEvidenceSourceDependency[];
+    /**
+     * Checks whether available dependencies cover every required path at equal or broader recursion.
+     *
+     * A recursive requirement cannot be satisfied by an exact watch, while a
+     * recursive available dependency can satisfy an exact requirement for its path.
+     */
+    function contains(available: IEvidenceSourceDependency[], required: IEvidenceSourceDependency[]): boolean;
+}

package/lib/internal/WatchDependencySet.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WatchDependencySet = void 0;
+const SourcePath_1 = require("./SourcePath");
+/**
+ * Builds deterministic watch dependency sets from an analysis snapshot.
+ *
+ * Merging upgrades duplicate paths to recursive monitoring, preserving the
+ * broader invalidation boundary without retaining duplicate watcher requests.
+ */
+var WatchDependencySet;
+(function (WatchDependencySet) {
+    /**
+     * Combines configuration dependencies with every loaded claim and reference inventory.
+     *
+     * Watch setup uses the merged result so edits to configuration, selected claims,
+     * or selected reference sources can invalidate the published analysis.
+     */
+    function analysis(value, configuration) {
+        return merge(configuration, value.graphInput.claims.flatMap((claim) => [
+            ...claim.inventory.dependencies,
+            ...claim.references.flatMap((reference) => reference.inventory.dependencies),
+        ]));
+    }
+    WatchDependencySet.analysis = analysis;
+    /**
+     * Normalizes, deduplicates, and orders dependency paths for stable snapshots.
+     *
+     * Duplicate paths retain recursive monitoring when any source requires it,
+     * preserving the broadest invalidation boundary in the returned set.
+     */
+    function merge(...groups) {
+        const output = new Map();
+        for (const dependency of groups.flat()) {
+            const location = SourcePath_1.SourcePath.slash(dependency.path);
+            const previous = output.get(location);
+            output.set(location, {
+                path: location,
+                recursive: dependency.recursive || previous?.recursive === true,
+            });
+        }
+        return Array.from(output.values()).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    }
+    WatchDependencySet.merge = merge;
+    /**
+     * Checks whether available dependencies cover every required path at equal or broader recursion.
+     *
+     * A recursive requirement cannot be satisfied by an exact watch, while a
+     * recursive available dependency can satisfy an exact requirement for its path.
+     */
+    function contains(available, required) {
+        const lookup = new Map(available.map((dependency) => [dependency.path, dependency.recursive]));
+        return required.every((dependency) => {
+            const recursive = lookup.get(dependency.path);
+            return recursive !== undefined && (!dependency.recursive || recursive);
+        });
+    }
+    WatchDependencySet.contains = contains;
+})(WatchDependencySet || (exports.WatchDependencySet = WatchDependencySet = {}));

package/lib/internal/WatchDependencySnapshot.d.ts

@@ -0,0 +1,38 @@
+import type { IEvidenceSourceDependency } from "../structures/IEvidenceSourceDependency";
+/**
+ * Immutable filesystem versions used to validate a watch attempt before publication.
+ *
+ * Versions include symlink and directory-entry state because either can change
+ * which source is read; a content-only check would miss resolution changes.
+ */
+export declare class WatchDependencySnapshot {
+    private readonly versions;
+    /**
+     * Creates a snapshot from already captured dependency version strings.
+     *
+     * capture and select are the only constructors because callers must not invent
+     * values that would falsely validate a watch attempt.
+     */
+    private constructor();
+    /**
+     * Captures every dependency asynchronously, encoding inaccessible paths as observable failures.
+     *
+     * Watch publication compares this baseline with a later capture so deletion,
+     * permission failure, and repair all count as distinct filesystem states.
+     */
+    static capture(dependencies: IEvidenceSourceDependency[]): Promise<WatchDependencySnapshot>;
+    /**
+     * States whether two snapshots cover the same dependencies at the same versions.
+     *
+     * Watch attempts publish only when this equality holds, preventing output from
+     * describing a source state that changed during analysis.
+     */
+    equals(other: WatchDependencySnapshot): boolean;
+    /**
+     * Returns a dependency subset captured by this stable baseline.
+     *
+     * Every requested key must exist in the baseline; omission throws rather than
+     * allowing a narrower snapshot to validate unrelated watch work.
+     */
+    select(dependencies: IEvidenceSourceDependency[]): WatchDependencySnapshot;
+}