@wrtnlabs/evidence 0.0.0

package/lib/commands/EvidenceCommandError.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invalid CLI syntax detected before configuration or source loading.
+ *
+ * The command parser uses this error for unknown, repeated, missing, or incompatible
+ * arguments. Buffered execution turns it into actionable failure output so malformed
+ * commands cannot trigger an unrelated project analysis.
+ */
+export declare class EvidenceCommandError extends Error {
+    /**
+     * Records the concrete argument failure for command-level repair guidance.
+     *
+     * The caller supplies the offending option or operation context; the command
+     * boundary adds the general help instruction when rendering the failure.
+     */
+    constructor(message: string);
+}

package/lib/commands/EvidenceCommandError.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCommandError = void 0;
+/**
+ * Invalid CLI syntax detected before configuration or source loading.
+ *
+ * The command parser uses this error for unknown, repeated, missing, or incompatible
+ * arguments. Buffered execution turns it into actionable failure output so malformed
+ * commands cannot trigger an unrelated project analysis.
+ */
+class EvidenceCommandError extends Error {
+    /**
+     * Records the concrete argument failure for command-level repair guidance.
+     *
+     * The caller supplies the offending option or operation context; the command
+     * boundary adds the general help instruction when rendering the failure.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "EvidenceCommandError";
+    }
+}
+exports.EvidenceCommandError = EvidenceCommandError;

package/lib/commands/EvidenceWatcher.d.ts

@@ -0,0 +1,134 @@
+import type { IEvidenceSourceDependency } from "../structures/IEvidenceSourceDependency";
+import type { IEvidenceWatchOptions } from "../structures/IEvidenceWatchOptions";
+import type { EvidenceWatchPublisher } from "../typings/EvidenceWatchPublisher";
+/**
+ * Rechecks active dependencies and publishes stable results in sequence.
+ *
+ * Start one watch loop per instance and supply an awaited publisher. Each attempt
+ * reevaluates configuration and source dependencies, then verifies that its input
+ * snapshots stayed stable before publishing. Failed attempts retain dependencies
+ * needed to observe repairs; parser acquisition also retries without a file edit.
+ *
+ * Close stops future publication, interrupts pending delays, and cancels this
+ * watcher's asset subscriptions. Await the watch promise to observe completion
+ * of any analysis or publisher already in progress.
+ *
+ * @example
+ * const watcher: EvidenceWatcher = new EvidenceWatcher("evidence.config.ts");
+ * const watching: Promise<void> = watcher.watch(
+ *   async (cycle: EvidenceWatchCycle): Promise<void> => {
+ *     console.log(cycle.cycle, cycle.status);
+ *   },
+ * );
+ * // When the application shuts down:
+ * await watcher.close();
+ * await watching;
+ */
+export declare class EvidenceWatcher {
+    /**
+     * Absolute configuration anchor captured before observation begins.
+     *
+     * Later changes to process cwd cannot redirect configuration or dependency scans.
+     */
+    private readonly configFile;
+    /**
+     * Interval between dependency snapshots during idle observation.
+     *
+     * Close can interrupt the pending delay rather than waiting out this interval.
+     */
+    private readonly pollIntervalMilliseconds;
+    /**
+     * Quiet interval used to coalesce related filesystem edits.
+     *
+     * A changed snapshot restarts settling; zero permits immediate reevaluation.
+     */
+    private readonly debounceMilliseconds;
+    /**
+     * Retry interval for parser assets that may recover without a filesystem edit.
+     *
+     * Only acquisition-related failures activate this timer; other stable failures
+     * wait for a dependency change.
+     */
+    private readonly parserRetryMilliseconds;
+    /**
+     * Cancellation owner for parser acquisitions within this watch loop.
+     *
+     * Closing aborts these subscriptions without cancelling unrelated subscribers
+     * that may share the underlying asset transfer.
+     */
+    private readonly cancellation;
+    /**
+     * Dependencies whose changes can trigger the next evaluation.
+     *
+     * Failures retain previously known paths and newly discovered candidates so
+     * missing imports or targets can recover after repair.
+     */
+    private active;
+    /**
+     * Whether the instance has already entered its single allowed watch loop.
+     *
+     * The guard prevents concurrent loops from sharing cycle and dependency state.
+     */
+    private started;
+    /**
+     * Shutdown state checked between asynchronous analysis and publication phases.
+     *
+     * A completed attempt is discarded if shutdown was requested before publication.
+     */
+    private closed;
+    /**
+     * Resolver that interrupts the current polling or settling delay.
+     *
+     * Each delay clears only its own resolver so stale completion cannot erase a
+     * newer wake callback.
+     */
+    private wake;
+    /**
+     * Sequence number of the most recently admitted publication.
+     *
+     * Stable failures advance the sequence like normal reports; unstable attempts
+     * repeat before a new number is committed.
+     */
+    private cycles;
+    /**
+     * Captures the configuration anchor and validates observation timing.
+     *
+     * Construction prepares fallback dependencies but does not evaluate configuration
+     * or start polling. Omitted timing options use the documented watch defaults.
+     */
+    constructor(configFile?: string, options?: IEvidenceWatchOptions);
+    /**
+     * Returns the current dependency set without exposing mutable watcher state.
+     *
+     * Before the first analysis this contains configuration fallback paths; after
+     * evaluation it includes discovered inputs and repair dependencies.
+     */
+    dependencies(): IEvidenceSourceDependency[];
+    /**
+     * Publishes an initial check and subsequent stable reevaluations until shutdown.
+     *
+     * The publisher is awaited, preserving cycle order and applying backpressure.
+     * Starting twice or after close rejects. Analysis failures become cycle data;
+     * a publisher exception escapes and closes the loop in cleanup.
+     */
+    watch(publish: EvidenceWatchPublisher): Promise<void>;
+    /**
+     * Requests shutdown and wakes any polling or settling delay immediately.
+     *
+     * Asset subscriptions owned by this watcher are cancelled. This method does not
+     * join the active watch loop; await its watch promise to finish outstanding
+     * analysis or publication work.
+     */
+    close(): Promise<void>;
+    private evaluate;
+    private evaluateStable;
+    private settle;
+    private pause;
+    /**
+     * Reads shutdown state after asynchronous boundaries.
+     *
+     * The loop checks this before starting another phase or publishing a completed
+     * attempt, since close can run while an awaited operation is pending.
+     */
+    private isClosed;
+}

package/lib/commands/EvidenceWatcher.js

@@ -0,0 +1,500 @@
+"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.EvidenceWatcher = 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 ConfigDependencyScanner_1 = require("../internal/ConfigDependencyScanner");
+const TreeSitterAssetScope_1 = require("../internal/TreeSitterAssetScope");
+const EvidenceParserError_1 = require("../parsers/EvidenceParserError");
+const SourcePath_1 = require("../internal/SourcePath");
+const WatchDependencySet_1 = require("../internal/WatchDependencySet");
+const WatchDependencySnapshot_1 = require("../internal/WatchDependencySnapshot");
+const EvidenceChecker_1 = require("../EvidenceChecker");
+/**
+ * Rechecks active dependencies and publishes stable results in sequence.
+ *
+ * Start one watch loop per instance and supply an awaited publisher. Each attempt
+ * reevaluates configuration and source dependencies, then verifies that its input
+ * snapshots stayed stable before publishing. Failed attempts retain dependencies
+ * needed to observe repairs; parser acquisition also retries without a file edit.
+ *
+ * Close stops future publication, interrupts pending delays, and cancels this
+ * watcher's asset subscriptions. Await the watch promise to observe completion
+ * of any analysis or publisher already in progress.
+ *
+ * @example
+ * const watcher: EvidenceWatcher = new EvidenceWatcher("evidence.config.ts");
+ * const watching: Promise<void> = watcher.watch(
+ *   async (cycle: EvidenceWatchCycle): Promise<void> => {
+ *     console.log(cycle.cycle, cycle.status);
+ *   },
+ * );
+ * // When the application shuts down:
+ * await watcher.close();
+ * await watching;
+ */
+class EvidenceWatcher {
+    /**
+     * Absolute configuration anchor captured before observation begins.
+     *
+     * Later changes to process cwd cannot redirect configuration or dependency scans.
+     */
+    configFile;
+    /**
+     * Interval between dependency snapshots during idle observation.
+     *
+     * Close can interrupt the pending delay rather than waiting out this interval.
+     */
+    pollIntervalMilliseconds;
+    /**
+     * Quiet interval used to coalesce related filesystem edits.
+     *
+     * A changed snapshot restarts settling; zero permits immediate reevaluation.
+     */
+    debounceMilliseconds;
+    /**
+     * Retry interval for parser assets that may recover without a filesystem edit.
+     *
+     * Only acquisition-related failures activate this timer; other stable failures
+     * wait for a dependency change.
+     */
+    parserRetryMilliseconds;
+    /**
+     * Cancellation owner for parser acquisitions within this watch loop.
+     *
+     * Closing aborts these subscriptions without cancelling unrelated subscribers
+     * that may share the underlying asset transfer.
+     */
+    cancellation = new AbortController();
+    /**
+     * Dependencies whose changes can trigger the next evaluation.
+     *
+     * Failures retain previously known paths and newly discovered candidates so
+     * missing imports or targets can recover after repair.
+     */
+    active;
+    /**
+     * Whether the instance has already entered its single allowed watch loop.
+     *
+     * The guard prevents concurrent loops from sharing cycle and dependency state.
+     */
+    started = false;
+    /**
+     * Shutdown state checked between asynchronous analysis and publication phases.
+     *
+     * A completed attempt is discarded if shutdown was requested before publication.
+     */
+    closed = false;
+    /**
+     * Resolver that interrupts the current polling or settling delay.
+     *
+     * Each delay clears only its own resolver so stale completion cannot erase a
+     * newer wake callback.
+     */
+    wake;
+    /**
+     * Sequence number of the most recently admitted publication.
+     *
+     * Stable failures advance the sequence like normal reports; unstable attempts
+     * repeat before a new number is committed.
+     */
+    cycles = 0;
+    /**
+     * Captures the configuration anchor and validates observation timing.
+     *
+     * Construction prepares fallback dependencies but does not evaluate configuration
+     * or start polling. Omitted timing options use the documented watch defaults.
+     */
+    constructor(configFile = "evidence.config.ts", options = {}) {
+        const checked = (() => {
+            const _ao0 = (input, _path, _exceptionable = true) => (undefined === input.pollIntervalMilliseconds || "number" === typeof input.pollIntervalMilliseconds && (_isTypeUint32_1._isTypeUint32(input.pollIntervalMilliseconds) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".pollIntervalMilliseconds",
+                expected: "number & Type<\"uint32\">",
+                value: input.pollIntervalMilliseconds
+            }, _errorFactory)) && (1 <= input.pollIntervalMilliseconds || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".pollIntervalMilliseconds",
+                expected: "number & Minimum<1>",
+                value: input.pollIntervalMilliseconds
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".pollIntervalMilliseconds",
+                expected: "((number & Type<\"uint32\"> & Minimum<1>) | undefined)",
+                value: input.pollIntervalMilliseconds
+            }, _errorFactory)) && (undefined === input.debounceMilliseconds || "number" === typeof input.debounceMilliseconds && (_isTypeUint32_1._isTypeUint32(input.debounceMilliseconds) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".debounceMilliseconds",
+                expected: "number & Type<\"uint32\">",
+                value: input.debounceMilliseconds
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".debounceMilliseconds",
+                expected: "((number & Type<\"uint32\">) | undefined)",
+                value: input.debounceMilliseconds
+            }, _errorFactory)) && (undefined === input.parserRetryMilliseconds || "number" === typeof input.parserRetryMilliseconds && (_isTypeUint32_1._isTypeUint32(input.parserRetryMilliseconds) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".parserRetryMilliseconds",
+                expected: "number & Type<\"uint32\">",
+                value: input.parserRetryMilliseconds
+            }, _errorFactory)) && (1 <= input.parserRetryMilliseconds || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".parserRetryMilliseconds",
+                expected: "number & Minimum<1>",
+                value: input.parserRetryMilliseconds
+            }, _errorFactory)) || _assertGuard_1._assertGuard(_exceptionable, {
+                method: "typia.assert",
+                path: _path + ".parserRetryMilliseconds",
+                expected: "((number & Type<\"uint32\"> & Minimum<1>) | undefined)",
+                value: input.parserRetryMilliseconds
+            }, _errorFactory));
+            const _io0 = input => (undefined === input.pollIntervalMilliseconds || "number" === typeof input.pollIntervalMilliseconds && (_isTypeUint32_1._isTypeUint32(input.pollIntervalMilliseconds) && 1 <= input.pollIntervalMilliseconds)) && (undefined === input.debounceMilliseconds || "number" === typeof input.debounceMilliseconds && _isTypeUint32_1._isTypeUint32(input.debounceMilliseconds)) && (undefined === input.parserRetryMilliseconds || "number" === typeof input.parserRetryMilliseconds && (_isTypeUint32_1._isTypeUint32(input.parserRetryMilliseconds) && 1 <= input.parserRetryMilliseconds));
+            const __is = input => "object" === typeof input && null !== input && false === Array.isArray(input) && _io0(input);
+            let _errorFactory;
+            return (input, errorFactory) => {
+                if (false === __is(input)) {
+                    _errorFactory = errorFactory;
+                    ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input && false === Array.isArray(input) || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceWatchOptions",
+                        value: input
+                    }, _errorFactory)) && _ao0(input, _path + "", true) || _assertGuard_1._assertGuard(true, {
+                        method: "typia.assert",
+                        path: _path + "",
+                        expected: "IEvidenceWatchOptions",
+                        value: input
+                    }, _errorFactory))(input, "$input", true);
+                }
+                return input;
+            };
+        })()(options);
+        this.configFile = node_path_1.default.resolve(configFile);
+        this.pollIntervalMilliseconds = checked.pollIntervalMilliseconds ?? 250;
+        this.debounceMilliseconds = checked.debounceMilliseconds ?? 100;
+        this.parserRetryMilliseconds = checked.parserRetryMilliseconds ?? 5_000;
+        this.active = configurationFallback(this.configFile);
+    }
+    /**
+     * Returns the current dependency set without exposing mutable watcher state.
+     *
+     * Before the first analysis this contains configuration fallback paths; after
+     * evaluation it includes discovered inputs and repair dependencies.
+     */
+    dependencies() {
+        return structuredClone(this.active);
+    }
+    /**
+     * Publishes an initial check and subsequent stable reevaluations until shutdown.
+     *
+     * The publisher is awaited, preserving cycle order and applying backpressure.
+     * Starting twice or after close rejects. Analysis failures become cycle data;
+     * a publisher exception escapes and closes the loop in cleanup.
+     */
+    async watch(publish) {
+        if (this.started)
+            throw new Error("An Evidence watcher can be started only once.");
+        if (this.closed)
+            throw new Error("A closed Evidence watcher cannot be started.");
+        this.started = true;
+        try {
+            let attempt = await this.evaluate();
+            if (this.isClosed())
+                return;
+            this.active = attempt.dependencies;
+            this.cycles = attempt.cycle.cycle;
+            await publish(attempt.cycle);
+            let baseline = attempt.snapshot;
+            // Acquisition can recover while source snapshots remain identical. Keep
+            // that retry deadline independent from ordinary filesystem invalidation.
+            let retryAt = attempt.retryParser
+                ? Date.now() + this.parserRetryMilliseconds
+                : Infinity;
+            while (!this.isClosed()) {
+                await this.pause(this.pollIntervalMilliseconds);
+                if (this.isClosed())
+                    break;
+                const changed = await WatchDependencySnapshot_1.WatchDependencySnapshot.capture(this.active);
+                if (changed.equals(baseline) && Date.now() < retryAt)
+                    continue;
+                await this.settle(changed);
+                if (this.isClosed())
+                    break;
+                attempt = await this.evaluate();
+                if (this.isClosed())
+                    break;
+                this.active = attempt.dependencies;
+                this.cycles = attempt.cycle.cycle;
+                await publish(attempt.cycle);
+                baseline = attempt.snapshot;
+                retryAt = attempt.retryParser
+                    ? Date.now() + this.parserRetryMilliseconds
+                    : Infinity;
+            }
+        }
+        finally {
+            this.closed = true;
+            this.wake = undefined;
+        }
+    }
+    /**
+     * Requests shutdown and wakes any polling or settling delay immediately.
+     *
+     * Asset subscriptions owned by this watcher are cancelled. This method does not
+     * join the active watch loop; await its watch promise to finish outstanding
+     * analysis or publication work.
+     */
+    async close() {
+        this.closed = true;
+        this.cancellation.abort();
+        this.wake?.();
+    }
+    /**
+     * Runs an attempt under this watcher's execution-local asset cancellation.
+     *
+     * An inherited caller signal remains effective alongside watcher shutdown, and
+     * the scope reaches parsers created by configuration scanning as well as analysis.
+     */
+    async evaluate() {
+        const inherited = TreeSitterAssetScope_1.TreeSitterAssetScope.current().signal;
+        const signal = inherited === undefined
+            ? this.cancellation.signal
+            : AbortSignal.any([inherited, this.cancellation.signal]);
+        return TreeSitterAssetScope_1.TreeSitterAssetScope.run({ signal }, () => this.evaluateStable());
+    }
+    /**
+     * Repeats analysis until dependency discovery and source snapshots agree.
+     *
+     * Newly discovered paths enlarge the observed boundary before acceptance. Input
+     * changes during evaluation cause another attempt, while stable failures retain
+     * enough dependency state for a later repair to trigger reevaluation.
+     */
+    async evaluateStable() {
+        for (;;) {
+            if (this.isClosed()) {
+                const snapshot = await WatchDependencySnapshot_1.WatchDependencySnapshot.capture(this.active);
+                return {
+                    cycle: failureCycle(this.cycles + 1, this.configFile, new Error("The Evidence watcher was closed.")),
+                    dependencies: this.active,
+                    snapshot,
+                    retryParser: false,
+                };
+            }
+            const beforeConfig = await scanConfiguration(this.configFile);
+            const candidates = WatchDependencySet_1.WatchDependencySet.merge(this.active, beforeConfig.dependencies);
+            const before = await WatchDependencySnapshot_1.WatchDependencySnapshot.capture(candidates);
+            let analysis;
+            let analysisCause;
+            try {
+                analysis = await EvidenceChecker_1.EvidenceChecker.analyze(this.configFile);
+            }
+            catch (cause) {
+                analysisCause = cause;
+            }
+            const afterConfig = await scanConfiguration(this.configFile);
+            const scanCause = afterConfig.cause;
+            const cause = analysisCause ?? scanCause;
+            // A failed evaluation cannot replace the previous dependency set with a
+            // smaller partial discovery, or repairing a lost input might never wake us.
+            const active = analysis === undefined
+                ? WatchDependencySet_1.WatchDependencySet.merge(this.active, afterConfig.dependencies)
+                : cause === undefined
+                    ? WatchDependencySet_1.WatchDependencySet.analysis(analysis, afterConfig.dependencies)
+                    : WatchDependencySet_1.WatchDependencySet.merge(this.active, afterConfig.dependencies, WatchDependencySet_1.WatchDependencySet.analysis(analysis, []));
+            const retryParser = parserFailure(cause) ||
+                (analysis !== undefined &&
+                    analysis.report.diagnostics.some((diagnostic) => /(?:^|-)asset-(?:download|cache|corrupt)$/u.test(diagnostic.code)));
+            if (!WatchDependencySet_1.WatchDependencySet.contains(candidates, active)) {
+                this.active = active;
+                // A preparation failure already proves this cycle incomplete. Publish it
+                // before retrying, while still recording every newly discovered dependency.
+                if (!retryParser)
+                    continue;
+            }
+            const after = await WatchDependencySnapshot_1.WatchDependencySnapshot.capture(WatchDependencySet_1.WatchDependencySet.merge(candidates, active));
+            // Compare the same pre-analysis boundary. A report built across two source
+            // versions must be retried rather than published as a stable cycle.
+            if (!before.equals(after.select(candidates))) {
+                this.active = active;
+                continue;
+            }
+            const number = this.cycles + 1;
+            const cycle = analysis !== undefined && cause === undefined
+                ? checkCycle(number, analysis)
+                : failureCycle(number, this.configFile, cause);
+            return {
+                cycle,
+                dependencies: active,
+                snapshot: after.select(active),
+                retryParser,
+            };
+        }
+    }
+    /**
+     * Waits until watched inputs remain unchanged for one quiet interval.
+     *
+     * Further edits restart the interval. Shutdown and zero debounce skip additional
+     * waiting so the outer loop can handle cancellation or evaluate immediately.
+     */
+    async settle(initial) {
+        let previous = initial;
+        while (!this.isClosed() && this.debounceMilliseconds !== 0) {
+            await this.pause(this.debounceMilliseconds);
+            if (this.isClosed())
+                return previous;
+            const current = await WatchDependencySnapshot_1.WatchDependencySnapshot.capture(this.active);
+            if (current.equals(previous))
+                return current;
+            previous = current;
+        }
+        return previous;
+    }
+    /**
+     * Waits for a deadline or an explicit shutdown wake, whichever occurs first.
+     *
+     * One completion closure owns timer cleanup and resolver removal, avoiding a
+     * double completion when close races the timer callback.
+     */
+    async pause(milliseconds) {
+        if (this.isClosed())
+            return;
+        await new Promise((resolve) => {
+            let settled = false;
+            const complete = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (this.wake === complete)
+                    this.wake = undefined;
+                resolve(undefined);
+            };
+            const timer = setTimeout(complete, milliseconds);
+            this.wake = complete;
+        });
+    }
+    /**
+     * Reads shutdown state after asynchronous boundaries.
+     *
+     * The loop checks this before starting another phase or publishing a completed
+     * attempt, since close can run while an awaited operation is pending.
+     */
+    isClosed() {
+        return this.closed;
+    }
+}
+exports.EvidenceWatcher = EvidenceWatcher;
+/**
+ * Preserves discovered configuration dependencies even when scanning throws.
+ *
+ * Missing or malformed imports must remain observable for recovery; propagating
+ * only the exception would discard the scanner's partial dependency knowledge.
+ */
+async function scanConfiguration(configFile) {
+    const scanner = new ConfigDependencyScanner_1.ConfigDependencyScanner(configFile);
+    try {
+        return { dependencies: await scanner.scan() };
+    }
+    catch (cause) {
+        return { dependencies: scanner.list(), cause };
+    }
+}
+/**
+ * Wraps a fresh report with its watch publication sequence.
+ *
+ * Outcome fields are copied from the report so stream consumers and full-report
+ * consumers observe the same completeness and failure semantics.
+ */
+function checkCycle(cycle, analysis) {
+    return {
+        schemaVersion: 1,
+        command: "check",
+        watch: true,
+        cycle,
+        status: analysis.report.status,
+        success: analysis.report.success,
+        exitCode: analysis.report.exitCode,
+        report: analysis.report,
+    };
+}
+/**
+ * Builds a watch result when no normal report can represent the attempt.
+ *
+ * The envelope retains configuration context and repair guidance while allowing
+ * the watcher to continue observing the dependencies of this failed cycle.
+ */
+function failureCycle(cycle, configFile, cause) {
+    return {
+        schemaVersion: 1,
+        command: "check",
+        watch: true,
+        cycle,
+        status: "failed",
+        success: false,
+        exitCode: 2,
+        configFile,
+        message: cause instanceof Error ? cause.message : String(cause),
+        repair: "Correct the current configuration, dependency, or source failure. Parser acquisition failures retry automatically; other failures retry after the next filesystem change.",
+    };
+}
+/**
+ * Identifies parser preparation failures eligible for timed recovery.
+ *
+ * Download, cache, and integrity failures can change independently of watched
+ * inputs; source syntax or configuration errors instead wait for an edit.
+ */
+function parserFailure(cause) {
+    return (cause instanceof EvidenceParserError_1.EvidenceParserError &&
+        ["asset-download", "asset-cache", "asset-corrupt"].includes(cause.code));
+}
+/**
+ * Seeds observation before a configuration dependency graph is available.
+ *
+ * Watching the configuration path and its directory permits recovery when the
+ * file or a nearby imported input is initially missing or cannot be evaluated.
+ */
+function configurationFallback(configFile) {
+    const normalized = SourcePath_1.SourcePath.slash(configFile);
+    return [
+        { path: normalized, recursive: false },
+        { path: SourcePath_1.SourcePath.slash(node_path_1.default.dirname(normalized)), recursive: true },
+    ];
+}