@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/tracker/createHostInputMutationTracker.mjs

@@ -0,0 +1,455 @@
+import path from 'node:path';
+import { pluginSourceCovers } from 'ttsc/plugin-source';
+import { createHostPathIdentityContext } from '../filesystem/createHostPathIdentityContext.mjs';
+import { normalizeHostInputName } from '../filesystem/normalizeHostInputName.mjs';
+import { pathIdentityKey } from '../filesystem/pathIdentityKey.mjs';
+import { relativeToProject } from '../filesystem/relativeToProject.mjs';
+import { hostInputRealpath } from '../inputs/hostInputRealpath.mjs';
+import { missingPathProbe } from '../inputs/missingPathProbe.mjs';
+import { registerBrokeredMutationTracker } from './broker/registerBrokeredMutationTracker.mjs';
+import { usesWatchBroker } from './broker/usesWatchBroker.mjs';
+import { closeDirectoryWatches } from './closeDirectoryWatches.mjs';
+import { openDirectoryWatch } from './openDirectoryWatch.mjs';
+import { pathTraversesSymbolicLink } from './pathTraversesSymbolicLink.mjs';
+import { recordProjectChange } from './recordProjectChange.mjs';
+import { recordProjectMutation } from './recordProjectMutation.mjs';
+import { settleOpenedDirectoryWatches } from './settleOpenedDirectoryWatches.mjs';
+import { trackedInputScope } from './trackedInputScope.mjs';
+import { watchLocationIdentity } from './watchLocationIdentity.mjs';
+
+/** Maximum unrelated roots watched before snapshot validation takes over. */
+const MAX_HOST_INPUT_WATCH_SCOPES = 16;
+/**
+ * Watch exact universal inputs, or their nearest existing parent if missing,
+ * and record only the events that can change what the compiler observed about
+ * them (samchon/ttsc#1384).
+ *
+ * Relevance comes from each input's {@link TtscTrackedInputScope}: an event on
+ * the path itself, a rename of an ancestor, and below the path only what its
+ * scope admits. A directory the resolver merely probed for existence, such as
+ * `node_modules`, therefore no longer collects every write beneath it, and a
+ * replaced ancestor directory, which reports only itself, is no longer missed.
+ *
+ * Linked components, symlink or hard-linked files and uncertain identities keep
+ * metadata validation. Too many unrelated watch roots disable notification
+ * authority rather than dropping inputs from validation.
+ *
+ * Path parsing follows the supplied filesystem's platform. An unknown case
+ * policy keeps input metadata validation; a foreign view supplies its own watch
+ * capability rather than opening a host-native handle for foreign paths.
+ * Unmatched native event spellings withdraw notification authority; metadata
+ * establishes the resulting change verdict. Each named event also rechecks its
+ * identity against a fresh native view. A changed alias or case policy
+ * withdraws authority instead of reusing the generation's earlier identity
+ * observation for a new target.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Compiler observation scopes govern admitted events; physical identity and
+ *   link checks govern whether notification silence may replace metadata reads.
+ *   Uncertain name equivalence sets unverified without inventing membership change.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One constructor builds coverage, scoped classification and owned locations;
+ *   both local listeners and broker sinks use the same classifier and lifecycle.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The sixteen-root limit withdraws authority rather than ignoring dependencies;
+ *   links and unknown attribution fall back to actual validation, not patched paths.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs distinguish event scope from coverage authority and explain
+ *   fallback boundaries; local comments give identity reasons under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral coverage uses one filesystem identity context, native realpaths,
+ *   explicit view path grammar, supplied case capability and watched-directory
+ *   identities; lexical aliases and junctions
+ *   cannot certify quiet old physical targets as current inputs.
+ *   Unicode spelling and native alternate names cannot be excluded merely by
+ *   comparing event code units with the indexed names.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Sets and directory maps index inputs, scopes and ancestors; shared ancestry
+ *   walks avoid rescanning common components. Event classification follows its
+ *   ancestor chain plus relevant scoped roots instead of reopening the graph.
+ *   Name uncertainty scans event text and uses indexed location flags; withdrawn
+ *   authority incurs the owning validators' current native metadata work.
+ *   Each named event has a call-local identity transaction for its path and
+ *   directory; native resolution and directory-case observation are repeated
+ *   because earlier event identities do not establish current equivalence.
+ *   Native resolution, string keys and admission predicates retain their path
+ *   costs, while recursive backend population follows admitted directories.
+ *   Construction arrays and indexes grow with input paths, distinct ancestors
+ *   and grouped locations. Fresh event maps and native case-probe listings are
+ *   temporary; the generation memo separately retains queried historical paths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   One construction shares physical identities, link-component checks and
+ *   grouped locations; native subscriptions and scope-aware drains share only
+ *   valid current owners, while every delivery rechecks watched identities.
+ *   Named events revalidate the generation memo before using it. A changed
+ *   physical key or directory case policy withdraws notification proof rather
+ *   than silently moving earlier event witnesses to a new native target.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A generation owns input indexes and admitted native locations, with at most
+ *   sixteen unrelated roots and an eight-path mutation sample. Close withdraws
+ *   authority and retires owned handles; failed construction remains untrusted
+ *   and its caller must retire any handles already acquired.
+ *   A recursive root can own many backend directory watches; sixteen roots is
+ *   not a bound on those handles or retained path bytes. Indexes remain reachable
+ *   with the tracker until its generation releases the object.
+ *   The retained identity context also grows with distinct event paths and
+ *   ancestors queried during this generation; it has no internal eviction or
+ *   independent historical-path bound.
+ */
+async function createHostInputMutationTracker(inputs, filesystem, covered, events = "all", preferredRoot, 
+/**
+ * The event scope of each input, keyed by its resolved spelling, derived from
+ * the compiler's observations. An input missing here is classified from the
+ * filesystem.
+ */
+scopes) {
+    const paths = (filesystem.platform ?? process.platform) === "win32"
+        ? path.win32
+        : path.posix;
+    const identities = createHostPathIdentityContext(filesystem);
+    // The project root in both of its spellings: an input the compiler reported
+    // physically is the project's as much as one spelled as the project was
+    // named, and the root's observer is opened once, under the name.
+    const internal = preferredRoot === undefined
+        ? undefined
+        : {
+            physical: identities.resolve(paths.resolve(preferredRoot)).path,
+            spelling: paths.resolve(preferredRoot),
+        };
+    const internalRoot = internal?.spelling;
+    const linkedAncestors = new Map();
+    const authoritative = new Set([...covered]
+        .map((input) => paths.resolve(input))
+        .filter((input) => {
+        // An unmeasured directory policy cannot certify equivalence between
+        // reported event spellings and inputs. Preserve metadata validation.
+        if (identities.caseSensitive(paths.dirname(input)) === undefined) {
+            return false;
+        }
+        // A link between the input and the directory watched for it, whose
+        // observer follows it: the project root for an input inside the
+        // project, the input's own nearest existing directory outside it. The
+        // watched directory and its ancestors are re-checked by identity on
+        // every delivery instead (`verifyLocations`), so a link there
+        // withdraws the tracker rather than moving the input silently. Native
+        // temporary roots and linked workspaces can have aliases above them.
+        const watched = internal !== undefined &&
+            relativeToProject(input, internal, filesystem.platform) !== undefined
+            ? internalRoot
+            : filesystem.exists(input)
+                ? paths.dirname(input)
+                : missingPathProbe(input, filesystem).directory;
+        if (pathTraversesSymbolicLink(input, filesystem, linkedAncestors, watched)) {
+            return false;
+        }
+        try {
+            // A lexical symlink can keep its own directory silent while a target
+            // elsewhere changes or appears. Its joined metadata proof must stay
+            // on the validation path, including while the link is broken.
+            const lexical = filesystem.lstat(input);
+            if (lexical.isSymbolicLink() ||
+                (lexical.isFile() && lexical.nlink > 1n))
+                return false;
+        }
+        catch (error) {
+            let missing = false;
+            try {
+                const code = error?.code;
+                missing = code === "ENOENT" || code === "ENOTDIR";
+            }
+            catch { }
+            if (!missing)
+                return false;
+            // A genuinely absent lexical path is covered by its nearest existing
+            // ancestor and remains eligible for notification proof.
+        }
+        const target = hostInputRealpath(input, filesystem);
+        return (target === null ||
+            pathIdentityKey(target, identities) ===
+                pathIdentityKey(input, identities));
+    }));
+    // Every tracked path with its event scope. A missing input is tracked as its
+    // first missing component, whose creation can arrive through any descendant.
+    const tracked = new Map();
+    // Every ancestor of a tracked path, whose rename moves the path with it.
+    const ancestors = new Set();
+    const walkedAncestors = new Set();
+    const track = (file, scope) => {
+        const key = pathIdentityKey(file, identities);
+        // A path observed two ways keeps every answer either observation needs.
+        const current = tracked.get(key) ?? new Set();
+        current.add(scope);
+        tracked.set(key, current);
+        for (let child = paths.resolve(file), parent = paths.dirname(child); parent !== child && !walkedAncestors.has(parent); child = parent, parent = paths.dirname(child)) {
+            // Every ancestor above one already walked is already recorded.
+            walkedAncestors.add(parent);
+            ancestors.add(pathIdentityKey(parent, identities));
+        }
+    };
+    const locationsByDirectory = new Map();
+    // The directories below `internalRoot` its recursive observer must hear, for
+    // a backend that watches directory by directory (samchon/ttsc#1389): every
+    // directory leading to a tracked path, a `children` path itself, and all of
+    // a `subtree` path. Nothing else under the root can change an answer.
+    const internalDirectories = new Set();
+    const internalSubtrees = [];
+    // Every plugin source directory, inside the root or not, whose directories a
+    // directory-level backend watches but for those the plugin build passes over
+    // (samchon/ttsc#1487).
+    const trees = [];
+    const admitInternal = (probed, scope) => {
+        for (let directory = paths.dirname(probed); internal !== undefined &&
+            (relativeToProject(directory, internal, filesystem.platform) ?? "") !==
+                ""; directory = paths.dirname(directory)) {
+            const key = pathIdentityKey(directory, identities);
+            // Every directory above one already admitted is admitted as well.
+            if (internalDirectories.has(key))
+                break;
+            internalDirectories.add(key);
+        }
+        if (scope === "children") {
+            internalDirectories.add(pathIdentityKey(probed, identities));
+        }
+        else if (scope === "subtree") {
+            internalSubtrees.push(probed);
+        }
+        else if (scope === "tree") {
+            trees.push(probed);
+        }
+    };
+    const watchDirectory = (directory, name, recursive, uncertainNames = false) => {
+        const directoryIdentity = identities.resolve(directory);
+        let location = locationsByDirectory.get(directoryIdentity.key);
+        if (location === undefined) {
+            location = {
+                directory: directoryIdentity.path,
+                ...(name === undefined ? {} : { names: new Set() }),
+                ...(recursive ? { recursive: true } : {}),
+            };
+            locationsByDirectory.set(directoryIdentity.key, location);
+        }
+        if (recursive)
+            location.recursive = true;
+        if (uncertainNames ||
+            /[^\x00-\x7f]/.test(directory) ||
+            (name !== undefined && /[^\x00-\x7f]/.test(name))) {
+            location.uncertainNames = true;
+        }
+        if (name === undefined) {
+            // Some input needs every entry of this directory reported.
+            delete location.names;
+        }
+        else {
+            location.names?.add(normalizeHostInputName(name, identities.caseSensitive(directoryIdentity.path) !== false));
+        }
+    };
+    for (const input of inputs) {
+        const absolute = paths.resolve(input);
+        const exists = filesystem.exists(absolute);
+        const probe = exists
+            ? { directory: paths.dirname(absolute), name: paths.basename(absolute) }
+            : missingPathProbe(absolute, filesystem);
+        const probed = paths.resolve(probe.directory, probe.name);
+        const scope = exists
+            ? (scopes?.get(absolute) ??
+                trackedInputScope(absolute, undefined, filesystem))
+            : "subtree";
+        track(probed, scope);
+        if (internal !== undefined &&
+            internalRoot !== undefined &&
+            relativeToProject(absolute, internal, filesystem.platform) !== undefined) {
+            watchDirectory(internalRoot, undefined, true, /[^\x00-\x7f]/.test(probed));
+            admitInternal(probed, scope);
+            continue;
+        }
+        // A plugin's source outside the project is watched as a whole subtree of
+        // its own, since any file below it can move its state; its parent would
+        // report only the directory's own entry.
+        if (scope === "tree") {
+            watchDirectory(probed, undefined, true);
+            trees.push(probed);
+            continue;
+        }
+        if (scope === "subtree" && exists) {
+            // Unknown observations can depend on children outside the project too.
+            // A parent-only subscription cannot certify this subtree. A non-directory
+            // or inaccessible root fails acquisition and withdraws notification proof.
+            watchDirectory(probed, undefined, true);
+            internalSubtrees.push(probed);
+        }
+        watchDirectory(probe.directory, probe.name, false);
+        // A listing changes through the entries of the directory itself, which a
+        // watch on its parent never reports.
+        if (scope === "children") {
+            watchDirectory(probed, undefined, false);
+        }
+    }
+    const locations = [...locationsByDirectory.values()];
+    const tracker = {
+        changes: new Set(),
+        changesOmitted: false,
+        close: () => {
+            tracker.failed = true;
+        },
+        // Coverage is the caller's claim, and it is required rather than derived
+        // from the input list: an input is watched by its exact name here, but only
+        // the caller knows whether the path leading to it is watched as well, which
+        // is what a later validation needs before it trusts the watcher instead of
+        // probing the path again. Deriving it here would hand that claim to every
+        // future caller by default (samchon/ttsc#1261).
+        covered: authoritative,
+        contentAuthoritative: filesystem.watch === undefined,
+        failed: false,
+        membershipChanged: false,
+        overlaps: (input, changed) => identities.isWithin(input, changed) ||
+            identities.isWithin(changed, input),
+    };
+    if (locations.length > MAX_HOST_INPUT_WATCH_SCOPES) {
+        // A graph spread over unrelated external roots cannot be folded into one
+        // recursive observer without watching an arbitrarily broad filesystem
+        // ancestor. Decline the notification proof and use the recorded snapshots;
+        // descriptor count must never scale with an adversarial input graph.
+        tracker.failed = true;
+        return tracker;
+    }
+    // The identity each watch opened on; a location that no longer resolves to
+    // it withdraws the tracker's authority (see `verifyLocations`).
+    const opened = locations.map((location) => ({
+        directory: location.directory,
+        identity: watchLocationIdentity(location.directory, filesystem),
+    }));
+    if (opened.some((location) => location.identity === undefined)) {
+        tracker.failed = true;
+        return tracker;
+    }
+    tracker.verifyLocations = (seen) => {
+        if (tracker.failed)
+            return;
+        for (const location of opened) {
+            if (watchLocationIdentity(location.directory, filesystem, seen) !==
+                location.identity) {
+                tracker.failed = true;
+                return;
+            }
+        }
+    };
+    /**
+     * The one event decision both backends share, so the in-process listener and
+     * the watch broker cannot disagree about the same event (samchon/ttsc#1384).
+     * A rename-only tracker drops every other event before it is classified, and
+     * an event the backend could not attribute to a name may concern any input
+     * below the watched directory, so it always counts.
+     */
+    const classify = (directory, filename, eventType) => {
+        // An event the backend could not attribute to a name is its notice that
+        // events may have been lost below the directory, as a Windows buffer
+        // overflow reports, so it counts as a mutation of any kind, before the
+        // rename-only filter could drop it (samchon/ttsc#1424).
+        if (filename === null)
+            return "mutation";
+        const rename = eventType === "rename";
+        if (events === "rename" && !rename)
+            return undefined;
+        const changed = paths.resolve(directory, filename);
+        const current = createHostPathIdentityContext(filesystem);
+        const key = pathIdentityKey(changed, identities);
+        if (key !== pathIdentityKey(changed, current) ||
+            pathIdentityKey(directory, identities) !==
+                pathIdentityKey(directory, current) ||
+            identities.caseSensitive(directory) !== current.caseSensitive(directory)) {
+            // The memo retains the generation's and earlier events' identities for
+            // overlap checks. A later alias cannot reuse those observations, and
+            // refreshing them would reinterpret the already recorded witnesses.
+            tracker.unverified = true;
+            return undefined;
+        }
+        const location = locationsByDirectory.get(pathIdentityKey(directory, identities));
+        if ((/[^\x00-\x7f]/.test(filename) || location?.uncertainNames === true) &&
+            location?.names?.has(normalizeHostInputName(filename, identities.caseSensitive(directory) !== false)) !== true) {
+            // A different Unicode spelling, or an ASCII alias of a Unicode input,
+            // needs native metadata. It does not establish a membership mutation.
+            tracker.unverified = true;
+            return undefined;
+        }
+        const verdict = rename ? "mutation" : "change";
+        const own = tracked.get(key);
+        if (own !== undefined) {
+            // Only a read or an unknown subtree hears its own content change.
+            if (rename ||
+                own.has("content") ||
+                own.has("subtree") ||
+                own.has("tree")) {
+                return verdict;
+            }
+            return undefined;
+        }
+        // Moving or replacing an ancestor moves the input without an event on it.
+        if (rename && ancestors.has(key))
+            return "mutation";
+        for (let child = changed, parent = paths.dirname(child); parent !== child; child = parent, parent = paths.dirname(child)) {
+            const scopes = tracked.get(pathIdentityKey(parent, identities));
+            if (scopes === undefined)
+                continue;
+            if (scopes.has("subtree"))
+                return verdict;
+            if (scopes.has("tree") &&
+                pluginSourceCovers(parent, changed, "entry", filesystem.platform)) {
+                return verdict;
+            }
+            if (scopes.has("children") && child === changed && rename) {
+                return "mutation";
+            }
+        }
+        // A missing native alias cannot be recovered by current realpath. Neither
+        // ASCII spelling nor OS name proves this event unrelated to a tracked path.
+        // Keep exact metadata validation without inventing a membership mutation.
+        tracker.unverified = true;
+        return undefined;
+    };
+    if (usesWatchBroker(filesystem)) {
+        await registerBrokeredMutationTracker(tracker, locations.map((location) => ({
+            directory: location.directory,
+            ...(location.recursive === true
+                ? { recursive: true }
+                : location.names === undefined
+                    ? {}
+                    : { names: [...location.names] }),
+        })), events === "all", filesystem, {
+            filters: { classify },
+            ...(preferredRoot === undefined ? {} : { probeRoot: preferredRoot }),
+        });
+        return tracker;
+    }
+    const watchers = [];
+    tracker.close = () => {
+        tracker.failed = true;
+        closeDirectoryWatches(watchers);
+    };
+    for (const location of locations) {
+        try {
+            watchers.push(openDirectoryWatch(filesystem, location.directory, (eventType, filename) => {
+                const verdict = classify(location.directory, filename, eventType);
+                const changed = filename === null
+                    ? location.directory
+                    : paths.join(location.directory, filename);
+                if (verdict === "mutation")
+                    recordProjectMutation(tracker, changed);
+                else if (verdict === "change")
+                    recordProjectChange(tracker, changed);
+            }, () => {
+                tracker.failed = true;
+            }, location.recursive === true, (directory) => internalDirectories.has(pathIdentityKey(directory, identities)) ||
+                internalSubtrees.some((subtree) => identities.isWithin(subtree, directory)) ||
+                trees.some((tree) => identities.isWithin(tree, directory) &&
+                    pluginSourceCovers(tree, directory, "directory", filesystem.platform))));
+        }
+        catch {
+            tracker.failed = true;
+        }
+    }
+    await settleOpenedDirectoryWatches(tracker, watchers, filesystem);
+    return tracker;
+}
+
+export { createHostInputMutationTracker };
+//# sourceMappingURL=createHostInputMutationTracker.mjs.map

package/lib/core/transform/tracker/createHostInputMutationTracker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHostInputMutationTracker.mjs","sources":["../../../../src/core/transform/tracker/createHostInputMutationTracker.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/lib/core/transform/tracker/createProjectMutationTracker.d.cts

@@ -0,0 +1,75 @@
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy.cjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+import type { TtscProjectDirectorySnapshot } from "../project/TtscProjectDirectorySnapshot.cjs";
+import type { TtscProjectMutationTracker } from "./TtscProjectMutationTracker.cjs";
+/**
+ * Watch the admitted project directory tree for changes after generation.
+ *
+ * Membership policy distinguishes root-set changes from content writes. The
+ * watched root's physical identity is verified on delivery, because an old
+ * watcher can remain attached after its lexical directory is replaced.
+ *
+ * Directory ancestry uses the observing view's path grammar. Disjoint volumes
+ * or unknown root case policy withdraw notification authority and leave the
+ * recorded-state validator responsible for proof. A named event rejected by
+ * lexical membership policy can still be a native alias of a program path. It
+ * withdraws notification authority without asserting a structural change;
+ * recorded-state validation supplies the actual verdict. Content witnesses
+ * preserve captured native input aliases, then reject only an observed normal
+ * directory excluded in both lexical and native spellings. Unknown, missing and
+ * linked ancestry remains conservative. Membership rejection still withdraws
+ * notification authority even when content is outside the walk. Named events
+ * also compare current native identity and case policy with the retained
+ * identity transaction. Retargeting withdraws notification authority without
+ * changing the meaning of earlier recorded event spellings.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The project walk and membership policy own structural relevance; content
+ *   witnesses remain separate, and missing watched-root identity withdraws coverage.
+ *   A lexical nonmatch is uncertainty rather than native alias exclusion.
+ *   Changed native identity premises also withdraw notification proof while
+ *   membership and content witnesses keep their independent classifications.
+ *   Content exclusion requires normal directory identity and both policy
+ *   spellings; captured native input aliases remain content witnesses.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One root, directory index and filter set define the tracker; broker and local
+ *   paths share those decisions rather than duplicating backend-specific policies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Unknown events conservatively invalidate membership; excluded trees follow
+ *   the supplied project policy, not a test-shaped path blacklist or watcher patch.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs separate scope, membership and replacement authority;
+ *   local identity comments explain the reason under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral relevance uses the view's path grammar, identity context and native
+ *   directory identity rather than platform-wide case folding or alias prefixes.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Known directory keys provide expected-constant admission checks; common-root
+ *   discovery follows ancestor depth and the observer visits admitted directories
+ *   instead of opening one watch per program file or excluded dependency entry.
+ *   Construction scans directory paths to find the root and build the index;
+ *   temporary path arrays and the index grow with that population. Event filters
+ *   include path text, supplied membership patterns and native metadata work.
+ *   Each named event resolves its path and directory in a fresh transaction,
+ *   including native ancestor and case-probe listing costs when required.
+ *   Construction indexes captured input identities. An uncaptured possible
+ *   content path may inspect each ancestor with two lstat calls and realpath
+ *   until a proven exclusion; identity resolution and policy matching retain
+ *   their native-query/pattern costs. No file bytes or extra watcher are read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   One retained identity context and known-directory index serve event overlap;
+ *   process-wide native producers share watches where their backend permits it,
+ *   while root identity is refreshed for each delivery's verification memo.
+ *   Named events recheck current identity before relying on the retained memo;
+ *   changing its entries would reinterpret earlier witnesses, so mismatches
+ *   withdraw authority instead. A quiet stream alone cannot restore that proof.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Generation-owned directory/input-identity indexes and watched coverage grow with the walk;
+ *   diagnostic paths stay bounded at eight. Close marks failed before retiring
+ *   all acquired local handles or the broker registration.
+ *   A recursive root can own many admitted backend directory handles. The
+ *   identity memo grows with distinct queried event paths and ancestors and has
+ *   no historical-path eviction; its indexes survive until the generation
+ *   releases the tracker. Fresh event maps and case listings are temporary.
+ */
+export declare function createProjectMutationTracker(directories: readonly TtscProjectDirectorySnapshot[], covered: ReadonlySet<string>, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): Promise<TtscProjectMutationTracker>;

package/lib/core/transform/tracker/createProjectMutationTracker.d.mts

@@ -0,0 +1,75 @@
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy.mjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+import type { TtscProjectDirectorySnapshot } from "../project/TtscProjectDirectorySnapshot.mjs";
+import type { TtscProjectMutationTracker } from "./TtscProjectMutationTracker.mjs";
+/**
+ * Watch the admitted project directory tree for changes after generation.
+ *
+ * Membership policy distinguishes root-set changes from content writes. The
+ * watched root's physical identity is verified on delivery, because an old
+ * watcher can remain attached after its lexical directory is replaced.
+ *
+ * Directory ancestry uses the observing view's path grammar. Disjoint volumes
+ * or unknown root case policy withdraw notification authority and leave the
+ * recorded-state validator responsible for proof. A named event rejected by
+ * lexical membership policy can still be a native alias of a program path. It
+ * withdraws notification authority without asserting a structural change;
+ * recorded-state validation supplies the actual verdict. Content witnesses
+ * preserve captured native input aliases, then reject only an observed normal
+ * directory excluded in both lexical and native spellings. Unknown, missing and
+ * linked ancestry remains conservative. Membership rejection still withdraws
+ * notification authority even when content is outside the walk. Named events
+ * also compare current native identity and case policy with the retained
+ * identity transaction. Retargeting withdraws notification authority without
+ * changing the meaning of earlier recorded event spellings.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The project walk and membership policy own structural relevance; content
+ *   witnesses remain separate, and missing watched-root identity withdraws coverage.
+ *   A lexical nonmatch is uncertainty rather than native alias exclusion.
+ *   Changed native identity premises also withdraw notification proof while
+ *   membership and content witnesses keep their independent classifications.
+ *   Content exclusion requires normal directory identity and both policy
+ *   spellings; captured native input aliases remain content witnesses.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One root, directory index and filter set define the tracker; broker and local
+ *   paths share those decisions rather than duplicating backend-specific policies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Unknown events conservatively invalidate membership; excluded trees follow
+ *   the supplied project policy, not a test-shaped path blacklist or watcher patch.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs separate scope, membership and replacement authority;
+ *   local identity comments explain the reason under the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   OS-neutral relevance uses the view's path grammar, identity context and native
+ *   directory identity rather than platform-wide case folding or alias prefixes.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Known directory keys provide expected-constant admission checks; common-root
+ *   discovery follows ancestor depth and the observer visits admitted directories
+ *   instead of opening one watch per program file or excluded dependency entry.
+ *   Construction scans directory paths to find the root and build the index;
+ *   temporary path arrays and the index grow with that population. Event filters
+ *   include path text, supplied membership patterns and native metadata work.
+ *   Each named event resolves its path and directory in a fresh transaction,
+ *   including native ancestor and case-probe listing costs when required.
+ *   Construction indexes captured input identities. An uncaptured possible
+ *   content path may inspect each ancestor with two lstat calls and realpath
+ *   until a proven exclusion; identity resolution and policy matching retain
+ *   their native-query/pattern costs. No file bytes or extra watcher are read.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   One retained identity context and known-directory index serve event overlap;
+ *   process-wide native producers share watches where their backend permits it,
+ *   while root identity is refreshed for each delivery's verification memo.
+ *   Named events recheck current identity before relying on the retained memo;
+ *   changing its entries would reinterpret earlier witnesses, so mismatches
+ *   withdraw authority instead. A quiet stream alone cannot restore that proof.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Generation-owned directory/input-identity indexes and watched coverage grow with the walk;
+ *   diagnostic paths stay bounded at eight. Close marks failed before retiring
+ *   all acquired local handles or the broker registration.
+ *   A recursive root can own many admitted backend directory handles. The
+ *   identity memo grows with distinct queried event paths and ancestors and has
+ *   no historical-path eviction; its indexes survive until the generation
+ *   releases the tracker. Fresh event maps and case listings are temporary.
+ */
+export declare function createProjectMutationTracker(directories: readonly TtscProjectDirectorySnapshot[], covered: ReadonlySet<string>, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): Promise<TtscProjectMutationTracker>;