@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/project/projectMembershipMatches.d.mts

@@ -0,0 +1,26 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+import type { TtscWatchInputState } from "../watch/TtscWatchInputState.mjs";
+/**
+ * Whether a project's root-file membership still equals what a generation
+ * recorded (samchon/ttsc#1419).
+ *
+ * The project is walked again under the recorded policy, the same walk the
+ * transform proves a generation with, and its digest compared. A walk that
+ * could not observe every directory coherently cannot prove anything, so it
+ * answers `false`: the host re-runs the module, and the transform decides.
+ *
+ * @param root The project root the membership belongs to.
+ * @param state The recorded membership.
+ * @param filesystem The filesystem to walk.
+ * @evidence contracts/common.md#principled-implementation Re-enumeration under the recorded policy must be complete before its membership digest may equal the captured value; an incomplete walk cannot authorize reuse.
+ * @evidence contracts/common.md#clear-and-simple-design The operation delegates enumeration and digest construction to their existing owners and combines only completeness with identity comparison.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A matching partial directory set or quiet watcher is not substituted for a coherent membership observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the recorded-policy premise and conservative false result on incomplete observation; parameter tags identify the root, state and filesystem seam.
+ * @evidence contracts/portability.md#os-neutral-implementation The same injected native filesystem view is used for re-enumeration, while recorded policy preserves the compiler's case and root rules; this comparison introduces no separate platform assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Walk results live only through this comparison and no handle, task or historical snapshot is retained here.
+ * @evidence contracts/performance.md#efficient-algorithms One current walk feeds one digest comparison, and incompleteness short-circuits digest construction. Native observations and admission inspect visited directory/entry and path populations; membership lists and final paths are sorted by the walk. Digest construction scans all directory records, sorts relevant address/signature pairs and encodes the policy's keys and text through its shared owner. Walk and serialization collections are temporary to this fallback.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The policy and captured digest are already supplied comparison inputs; this fallback coordinates no completed or in-flight current walk across requests. Mutable directory membership requires current observations, while the calling observer owns condition sharing and any event-authorized omission of the fallback.
+ */
+export declare function projectMembershipMatches(root: string, state: Extract<TtscWatchInputState, {
+    codec: "membership";
+}>, filesystem?: TtscTransformFilesystemOperations): boolean;

package/lib/core/transform/project/projectMembershipMatches.d.ts

@@ -0,0 +1,26 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import type { TtscWatchInputState } from "../watch/TtscWatchInputState";
+/**
+ * Whether a project's root-file membership still equals what a generation
+ * recorded (samchon/ttsc#1419).
+ *
+ * The project is walked again under the recorded policy, the same walk the
+ * transform proves a generation with, and its digest compared. A walk that
+ * could not observe every directory coherently cannot prove anything, so it
+ * answers `false`: the host re-runs the module, and the transform decides.
+ *
+ * @param root The project root the membership belongs to.
+ * @param state The recorded membership.
+ * @param filesystem The filesystem to walk.
+ * @evidence contracts/common.md#principled-implementation Re-enumeration under the recorded policy must be complete before its membership digest may equal the captured value; an incomplete walk cannot authorize reuse.
+ * @evidence contracts/common.md#clear-and-simple-design The operation delegates enumeration and digest construction to their existing owners and combines only completeness with identity comparison.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A matching partial directory set or quiet watcher is not substituted for a coherent membership observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the recorded-policy premise and conservative false result on incomplete observation; parameter tags identify the root, state and filesystem seam.
+ * @evidence contracts/portability.md#os-neutral-implementation The same injected native filesystem view is used for re-enumeration, while recorded policy preserves the compiler's case and root rules; this comparison introduces no separate platform assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Walk results live only through this comparison and no handle, task or historical snapshot is retained here.
+ * @evidence contracts/performance.md#efficient-algorithms One current walk feeds one digest comparison, and incompleteness short-circuits digest construction. Native observations and admission inspect visited directory/entry and path populations; membership lists and final paths are sorted by the walk. Digest construction scans all directory records, sorts relevant address/signature pairs and encodes the policy's keys and text through its shared owner. Walk and serialization collections are temporary to this fallback.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The policy and captured digest are already supplied comparison inputs; this fallback coordinates no completed or in-flight current walk across requests. Mutable directory membership requires current observations, while the calling observer owns condition sharing and any event-authorized omission of the fallback.
+ */
+export declare function projectMembershipMatches(root: string, state: Extract<TtscWatchInputState, {
+    codec: "membership";
+}>, filesystem?: TtscTransformFilesystemOperations): boolean;

package/lib/core/transform/project/projectMembershipMatches.js

@@ -0,0 +1,35 @@
+'use strict';
+
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var projectMembershipDigest = require('./projectMembershipDigest.js');
+var walkProjectInputs = require('./walkProjectInputs.js');
+
+/**
+ * Whether a project's root-file membership still equals what a generation
+ * recorded (samchon/ttsc#1419).
+ *
+ * The project is walked again under the recorded policy, the same walk the
+ * transform proves a generation with, and its digest compared. A walk that
+ * could not observe every directory coherently cannot prove anything, so it
+ * answers `false`: the host re-runs the module, and the transform decides.
+ *
+ * @param root The project root the membership belongs to.
+ * @param state The recorded membership.
+ * @param filesystem The filesystem to walk.
+ * @evidence contracts/common.md#principled-implementation Re-enumeration under the recorded policy must be complete before its membership digest may equal the captured value; an incomplete walk cannot authorize reuse.
+ * @evidence contracts/common.md#clear-and-simple-design The operation delegates enumeration and digest construction to their existing owners and combines only completeness with identity comparison.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A matching partial directory set or quiet watcher is not substituted for a coherent membership observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the recorded-policy premise and conservative false result on incomplete observation; parameter tags identify the root, state and filesystem seam.
+ * @evidence contracts/portability.md#os-neutral-implementation The same injected native filesystem view is used for re-enumeration, while recorded policy preserves the compiler's case and root rules; this comparison introduces no separate platform assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Walk results live only through this comparison and no handle, task or historical snapshot is retained here.
+ * @evidence contracts/performance.md#efficient-algorithms One current walk feeds one digest comparison, and incompleteness short-circuits digest construction. Native observations and admission inspect visited directory/entry and path populations; membership lists and final paths are sorted by the walk. Digest construction scans all directory records, sorts relevant address/signature pairs and encodes the policy's keys and text through its shared owner. Walk and serialization collections are temporary to this fallback.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The policy and captured digest are already supplied comparison inputs; this fallback coordinates no completed or in-flight current walk across requests. Mutable directory membership requires current observations, while the calling observer owns condition sharing and any event-authorized omission of the fallback.
+ */
+function projectMembershipMatches(root, state, filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    const walked = walkProjectInputs.walkProjectInputs(root, filesystem, state.policy);
+    return (walked.complete &&
+        projectMembershipDigest.projectMembershipDigest(state.policy, walked.directories) === state.digest);
+}
+
+exports.projectMembershipMatches = projectMembershipMatches;
+//# sourceMappingURL=projectMembershipMatches.js.map

package/lib/core/transform/project/projectMembershipMatches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectMembershipMatches.js","sources":["../../../../src/core/transform/project/projectMembershipMatches.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","walkProjectInputs","projectMembershipDigest"],"mappings":";;;;;;AAMA;;;;;;;;;;;;;;;;;;;;AAoBG;AACG,SAAU,wBAAwB,CACtC,IAAY,EACZ,KAA4D,EAC5D,aAAgDA,2DAA6B,EAAA;AAE7E,IAAA,MAAM,MAAM,GAAGC,mCAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;IAChE,QACE,MAAM,CAAC,QAAQ;AACf,QAAAC,+CAAuB,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,KAAK,CAAC,MAAM;AAE9E;;;;"}

package/lib/core/transform/project/projectMembershipMatches.mjs

@@ -0,0 +1,33 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { projectMembershipDigest } from './projectMembershipDigest.mjs';
+import { walkProjectInputs } from './walkProjectInputs.mjs';
+
+/**
+ * Whether a project's root-file membership still equals what a generation
+ * recorded (samchon/ttsc#1419).
+ *
+ * The project is walked again under the recorded policy, the same walk the
+ * transform proves a generation with, and its digest compared. A walk that
+ * could not observe every directory coherently cannot prove anything, so it
+ * answers `false`: the host re-runs the module, and the transform decides.
+ *
+ * @param root The project root the membership belongs to.
+ * @param state The recorded membership.
+ * @param filesystem The filesystem to walk.
+ * @evidence contracts/common.md#principled-implementation Re-enumeration under the recorded policy must be complete before its membership digest may equal the captured value; an incomplete walk cannot authorize reuse.
+ * @evidence contracts/common.md#clear-and-simple-design The operation delegates enumeration and digest construction to their existing owners and combines only completeness with identity comparison.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A matching partial directory set or quiet watcher is not substituted for a coherent membership observation.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the recorded-policy premise and conservative false result on incomplete observation; parameter tags identify the root, state and filesystem seam.
+ * @evidence contracts/portability.md#os-neutral-implementation The same injected native filesystem view is used for re-enumeration, while recorded policy preserves the compiler's case and root rules; this comparison introduces no separate platform assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Walk results live only through this comparison and no handle, task or historical snapshot is retained here.
+ * @evidence contracts/performance.md#efficient-algorithms One current walk feeds one digest comparison, and incompleteness short-circuits digest construction. Native observations and admission inspect visited directory/entry and path populations; membership lists and final paths are sorted by the walk. Digest construction scans all directory records, sorts relevant address/signature pairs and encodes the policy's keys and text through its shared owner. Walk and serialization collections are temporary to this fallback.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The policy and captured digest are already supplied comparison inputs; this fallback coordinates no completed or in-flight current walk across requests. Mutable directory membership requires current observations, while the calling observer owns condition sharing and any event-authorized omission of the fallback.
+ */
+function projectMembershipMatches(root, state, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const walked = walkProjectInputs(root, filesystem, state.policy);
+    return (walked.complete &&
+        projectMembershipDigest(state.policy, walked.directories) === state.digest);
+}
+
+export { projectMembershipMatches };
+//# sourceMappingURL=projectMembershipMatches.mjs.map

package/lib/core/transform/project/projectMembershipMatches.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectMembershipMatches.mjs","sources":["../../../../src/core/transform/project/projectMembershipMatches.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA;;;;;;;;;;;;;;;;;;;;AAoBG;AACG,SAAU,wBAAwB,CACtC,IAAY,EACZ,KAA4D,EAC5D,aAAgD,6BAA6B,EAAA;AAE7E,IAAA,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;IAChE,QACE,MAAM,CAAC,QAAQ;AACf,QAAA,uBAAuB,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,KAAK,CAAC,MAAM;AAE9E;;;;"}

package/lib/core/transform/project/reportsProgramMembership.d.cts

@@ -0,0 +1,41 @@
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy.cjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Whether one directory event can be a change to the program's membership.
+ *
+ * Configured root selection and exclusions determine lexical relevance. This
+ * answer does not establish that a rejected native event spelling has no alias
+ * among program inputs; the owning tracker handles that authority separately.
+ *
+ * A name that could be a program input counts, unless it sits under a directory
+ * the walk never descends into. A name that could not still counts when the
+ * path is now a directory, because the walk's watches were opened for the
+ * directories that existed when the generation was captured, so a directory
+ * created since is not watched and the sources that may appear in it would
+ * otherwise be invisible. A directory the configuration excludes is the
+ * exception: the walk cannot see inside it, so the tracker must not either, or
+ * emptying and recreating an `outDir` costs a compile per build. A path below a
+ * name the walk skips never counts for the same reason. Callers handle
+ * unattributable events separately; this predicate classifies a named path.
+ *
+ * @evidence contracts/common.md#principled-implementation The same root-file and directory-exclusion policy classifies named event locations as the walk; current directory kind admits newly created source-containing subtrees while removed source filenames remain classifiable.
+ * @evidence contracts/common.md#clear-and-simple-design Policy gates precede one optional lstat, then filename classification handles deletion without requiring a current entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Output events are ignored by actual compiler admission and configured containment, not by broad directory-name exceptions that could hide real inputs.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain creation, deletion and output exclusion; the final sentence distinguishes caller-owned unattributable events from this named-path predicate.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative paths and separators classify event components, and the injected lstat view distinguishes directories from deleted filenames; no platform-wide lowercase rule substitutes for compiler admission.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Relative-path construction and splitting allocate text and segment
+ *   references proportional to the event path. Early policy gates precede at
+ *   most one native lstat. Root matching includes configured patterns, path
+ *   components and spelling variants; exclusion scans configured directory
+ *   paths, and filename eligibility scans the supplied extensions. Repeated
+ *   root questions share the matching owner's immutable-policy compilation,
+ *   while the current kind observation remains local to this event.
+ *   Wildcard component matching merges token states with work bounded by
+ *   pattern and candidate code-point dimensions; literal tests retain text cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function reportsProgramMembership(root: string, location: string, filename: string, policy: ITtscProjectMembershipPolicy, filesystem: TtscTransformFilesystemOperations): boolean;

package/lib/core/transform/project/reportsProgramMembership.d.mts

@@ -0,0 +1,41 @@
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy.mjs";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Whether one directory event can be a change to the program's membership.
+ *
+ * Configured root selection and exclusions determine lexical relevance. This
+ * answer does not establish that a rejected native event spelling has no alias
+ * among program inputs; the owning tracker handles that authority separately.
+ *
+ * A name that could be a program input counts, unless it sits under a directory
+ * the walk never descends into. A name that could not still counts when the
+ * path is now a directory, because the walk's watches were opened for the
+ * directories that existed when the generation was captured, so a directory
+ * created since is not watched and the sources that may appear in it would
+ * otherwise be invisible. A directory the configuration excludes is the
+ * exception: the walk cannot see inside it, so the tracker must not either, or
+ * emptying and recreating an `outDir` costs a compile per build. A path below a
+ * name the walk skips never counts for the same reason. Callers handle
+ * unattributable events separately; this predicate classifies a named path.
+ *
+ * @evidence contracts/common.md#principled-implementation The same root-file and directory-exclusion policy classifies named event locations as the walk; current directory kind admits newly created source-containing subtrees while removed source filenames remain classifiable.
+ * @evidence contracts/common.md#clear-and-simple-design Policy gates precede one optional lstat, then filename classification handles deletion without requiring a current entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Output events are ignored by actual compiler admission and configured containment, not by broad directory-name exceptions that could hide real inputs.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain creation, deletion and output exclusion; the final sentence distinguishes caller-owned unattributable events from this named-path predicate.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative paths and separators classify event components, and the injected lstat view distinguishes directories from deleted filenames; no platform-wide lowercase rule substitutes for compiler admission.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Relative-path construction and splitting allocate text and segment
+ *   references proportional to the event path. Early policy gates precede at
+ *   most one native lstat. Root matching includes configured patterns, path
+ *   components and spelling variants; exclusion scans configured directory
+ *   paths, and filename eligibility scans the supplied extensions. Repeated
+ *   root questions share the matching owner's immutable-policy compilation,
+ *   while the current kind observation remains local to this event.
+ *   Wildcard component matching merges token states with work bounded by
+ *   pattern and candidate code-point dimensions; literal tests retain text cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function reportsProgramMembership(root: string, location: string, filename: string, policy: ITtscProjectMembershipPolicy, filesystem: TtscTransformFilesystemOperations): boolean;

package/lib/core/transform/project/reportsProgramMembership.d.ts

@@ -0,0 +1,41 @@
+import type { ITtscProjectMembershipPolicy } from "../../tsconfig/ITtscProjectMembershipPolicy";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Whether one directory event can be a change to the program's membership.
+ *
+ * Configured root selection and exclusions determine lexical relevance. This
+ * answer does not establish that a rejected native event spelling has no alias
+ * among program inputs; the owning tracker handles that authority separately.
+ *
+ * A name that could be a program input counts, unless it sits under a directory
+ * the walk never descends into. A name that could not still counts when the
+ * path is now a directory, because the walk's watches were opened for the
+ * directories that existed when the generation was captured, so a directory
+ * created since is not watched and the sources that may appear in it would
+ * otherwise be invisible. A directory the configuration excludes is the
+ * exception: the walk cannot see inside it, so the tracker must not either, or
+ * emptying and recreating an `outDir` costs a compile per build. A path below a
+ * name the walk skips never counts for the same reason. Callers handle
+ * unattributable events separately; this predicate classifies a named path.
+ *
+ * @evidence contracts/common.md#principled-implementation The same root-file and directory-exclusion policy classifies named event locations as the walk; current directory kind admits newly created source-containing subtrees while removed source filenames remain classifiable.
+ * @evidence contracts/common.md#clear-and-simple-design Policy gates precede one optional lstat, then filename classification handles deletion without requiring a current entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Output events are ignored by actual compiler admission and configured containment, not by broad directory-name exceptions that could hide real inputs.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain creation, deletion and output exclusion; the final sentence distinguishes caller-owned unattributable events from this named-path predicate.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative paths and separators classify event components, and the injected lstat view distinguishes directories from deleted filenames; no platform-wide lowercase rule substitutes for compiler admission.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Relative-path construction and splitting allocate text and segment
+ *   references proportional to the event path. Early policy gates precede at
+ *   most one native lstat. Root matching includes configured patterns, path
+ *   components and spelling variants; exclusion scans configured directory
+ *   paths, and filename eligibility scans the supplied extensions. Repeated
+ *   root questions share the matching owner's immutable-policy compilation,
+ *   while the current kind observation remains local to this event.
+ *   Wildcard component matching merges token states with work bounded by
+ *   pattern and candidate code-point dimensions; literal tests retain text cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function reportsProgramMembership(root: string, location: string, filename: string, policy: ITtscProjectMembershipPolicy, filesystem: TtscTransformFilesystemOperations): boolean;

package/lib/core/transform/project/reportsProgramMembership.js

@@ -0,0 +1,82 @@
+'use strict';
+
+var path = require('node:path');
+var matchesProjectRootFile = require('../../tsconfig/matchesProjectRootFile.js');
+var insideExcludedProjectDirectory = require('./insideExcludedProjectDirectory.js');
+var isIgnoredProjectEntry = require('./isIgnoredProjectEntry.js');
+var isPossibleProgramFileName = require('./isPossibleProgramFileName.js');
+
+/**
+ * Whether one directory event can be a change to the program's membership.
+ *
+ * Configured root selection and exclusions determine lexical relevance. This
+ * answer does not establish that a rejected native event spelling has no alias
+ * among program inputs; the owning tracker handles that authority separately.
+ *
+ * A name that could be a program input counts, unless it sits under a directory
+ * the walk never descends into. A name that could not still counts when the
+ * path is now a directory, because the walk's watches were opened for the
+ * directories that existed when the generation was captured, so a directory
+ * created since is not watched and the sources that may appear in it would
+ * otherwise be invisible. A directory the configuration excludes is the
+ * exception: the walk cannot see inside it, so the tracker must not either, or
+ * emptying and recreating an `outDir` costs a compile per build. A path below a
+ * name the walk skips never counts for the same reason. Callers handle
+ * unattributable events separately; this predicate classifies a named path.
+ *
+ * @evidence contracts/common.md#principled-implementation The same root-file and directory-exclusion policy classifies named event locations as the walk; current directory kind admits newly created source-containing subtrees while removed source filenames remain classifiable.
+ * @evidence contracts/common.md#clear-and-simple-design Policy gates precede one optional lstat, then filename classification handles deletion without requiring a current entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Output events are ignored by actual compiler admission and configured containment, not by broad directory-name exceptions that could hide real inputs.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain creation, deletion and output exclusion; the final sentence distinguishes caller-owned unattributable events from this named-path predicate.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative paths and separators classify event components, and the injected lstat view distinguishes directories from deleted filenames; no platform-wide lowercase rule substitutes for compiler admission.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Relative-path construction and splitting allocate text and segment
+ *   references proportional to the event path. Early policy gates precede at
+ *   most one native lstat. Root matching includes configured patterns, path
+ *   components and spelling variants; exclusion scans configured directory
+ *   paths, and filename eligibility scans the supplied extensions. Repeated
+ *   root questions share the matching owner's immutable-policy compilation,
+ *   while the current kind observation remains local to this event.
+ *   Wildcard component matching merges token states with work bounded by
+ *   pattern and candidate code-point dimensions; literal tests retain text cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function reportsProgramMembership(root, location, filename, policy, filesystem) {
+    const platform = filesystem.platform ?? process.platform;
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    if (pathApi
+        .relative(root, location)
+        .split(pathApi.sep)
+        .some((segment) => isIgnoredProjectEntry.isIgnoredProjectEntry(segment, policy))) {
+        return false;
+    }
+    if (!matchesProjectRootFile.matchesProjectRootFile(location, policy, false, platform) &&
+        !matchesProjectRootFile.matchesProjectRootFile(location, policy, true, platform)) {
+        return false;
+    }
+    try {
+        if (filesystem.lstat(location).isDirectory()) {
+            return (matchesProjectRootFile.matchesProjectRootFile(location, policy, true, platform) &&
+                !insideExcludedProjectDirectory.insideExcludedProjectDirectory(location, policy, false, platform));
+        }
+    }
+    catch {
+        // Deleted file names still need classification below.
+    }
+    if (isPossibleProgramFileName.isPossibleProgramFileName(filename, policy)) {
+        // A name the program could admit. It still says nothing if it lies inside a
+        // directory the walk never descends into, because the digest cannot see
+        // there either and the tracker must not be the one side that reacts.
+        return (matchesProjectRootFile.matchesProjectRootFile(location, policy, false, platform) &&
+            !insideExcludedProjectDirectory.insideExcludedProjectDirectory(location, policy, true, platform));
+    }
+    // Removed directories report their source removals through their own watch.
+    // A non-source file name cannot introduce program membership.
+    return false;
+}
+
+exports.reportsProgramMembership = reportsProgramMembership;
+//# sourceMappingURL=reportsProgramMembership.js.map

package/lib/core/transform/project/reportsProgramMembership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reportsProgramMembership.js","sources":["../../../../src/core/transform/project/reportsProgramMembership.ts"],"sourcesContent":[null],"names":["isIgnoredProjectEntry","matchesProjectRootFile","insideExcludedProjectDirectory","isPossibleProgramFileName"],"mappings":";;;;;;;;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;AACG,SAAU,wBAAwB,CACtC,IAAY,EACZ,QAAgB,EAChB,QAAgB,EAChB,MAAoC,EACpC,UAA6C,EAAA;IAE7C,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ;AACxD,IAAA,MAAM,OAAO,GAAG,QAAQ,KAAK,OAAO,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;AAC9D,IAAA,IACE;AACG,SAAA,QAAQ,CAAC,IAAI,EAAE,QAAQ;AACvB,SAAA,KAAK,CAAC,OAAO,CAAC,GAAG;AACjB,SAAA,IAAI,CAAC,CAAC,OAAO,KAAKA,2CAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,EAC5D;AACA,QAAA,OAAO,KAAK;IACd;IACA,IACE,CAACC,6CAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;QAC1D,CAACA,6CAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,EACzD;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI;QACF,IAAI,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE;YAC5C,QACEA,6CAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC;gBACxD,CAACC,6DAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;QAEtE;IACF;AAAE,IAAA,MAAM;;IAER;AACA,IAAA,IAAIC,mDAAyB,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE;;;;QAI/C,QACEF,6CAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;YACzD,CAACC,6DAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC;IAErE;;;AAGA,IAAA,OAAO,KAAK;AACd;;;;"}

package/lib/core/transform/project/reportsProgramMembership.mjs

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { matchesProjectRootFile } from '../../tsconfig/matchesProjectRootFile.mjs';
+import { insideExcludedProjectDirectory } from './insideExcludedProjectDirectory.mjs';
+import { isIgnoredProjectEntry } from './isIgnoredProjectEntry.mjs';
+import { isPossibleProgramFileName } from './isPossibleProgramFileName.mjs';
+
+/**
+ * Whether one directory event can be a change to the program's membership.
+ *
+ * Configured root selection and exclusions determine lexical relevance. This
+ * answer does not establish that a rejected native event spelling has no alias
+ * among program inputs; the owning tracker handles that authority separately.
+ *
+ * A name that could be a program input counts, unless it sits under a directory
+ * the walk never descends into. A name that could not still counts when the
+ * path is now a directory, because the walk's watches were opened for the
+ * directories that existed when the generation was captured, so a directory
+ * created since is not watched and the sources that may appear in it would
+ * otherwise be invisible. A directory the configuration excludes is the
+ * exception: the walk cannot see inside it, so the tracker must not either, or
+ * emptying and recreating an `outDir` costs a compile per build. A path below a
+ * name the walk skips never counts for the same reason. Callers handle
+ * unattributable events separately; this predicate classifies a named path.
+ *
+ * @evidence contracts/common.md#principled-implementation The same root-file and directory-exclusion policy classifies named event locations as the walk; current directory kind admits newly created source-containing subtrees while removed source filenames remain classifiable.
+ * @evidence contracts/common.md#clear-and-simple-design Policy gates precede one optional lstat, then filename classification handles deletion without requiring a current entry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Output events are ignored by actual compiler admission and configured containment, not by broad directory-name exceptions that could hide real inputs.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain creation, deletion and output exclusion; the final sentence distinguishes caller-owned unattributable events from this named-path predicate.
+ * @evidence contracts/portability.md#os-neutral-implementation Native relative paths and separators classify event components, and the injected lstat view distinguishes directories from deleted filenames; no platform-wide lowercase rule substitutes for compiler admission.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Relative-path construction and splitting allocate text and segment
+ *   references proportional to the event path. Early policy gates precede at
+ *   most one native lstat. Root matching includes configured patterns, path
+ *   components and spelling variants; exclusion scans configured directory
+ *   paths, and filename eligibility scans the supplied extensions. Repeated
+ *   root questions share the matching owner's immutable-policy compilation,
+ *   while the current kind observation remains local to this event.
+ *   Wildcard component matching merges token states with work bounded by
+ *   pattern and candidate code-point dimensions; literal tests retain text cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function reportsProgramMembership(root, location, filename, policy, filesystem) {
+    const platform = filesystem.platform ?? process.platform;
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    if (pathApi
+        .relative(root, location)
+        .split(pathApi.sep)
+        .some((segment) => isIgnoredProjectEntry(segment, policy))) {
+        return false;
+    }
+    if (!matchesProjectRootFile(location, policy, false, platform) &&
+        !matchesProjectRootFile(location, policy, true, platform)) {
+        return false;
+    }
+    try {
+        if (filesystem.lstat(location).isDirectory()) {
+            return (matchesProjectRootFile(location, policy, true, platform) &&
+                !insideExcludedProjectDirectory(location, policy, false, platform));
+        }
+    }
+    catch {
+        // Deleted file names still need classification below.
+    }
+    if (isPossibleProgramFileName(filename, policy)) {
+        // A name the program could admit. It still says nothing if it lies inside a
+        // directory the walk never descends into, because the digest cannot see
+        // there either and the tracker must not be the one side that reacts.
+        return (matchesProjectRootFile(location, policy, false, platform) &&
+            !insideExcludedProjectDirectory(location, policy, true, platform));
+    }
+    // Removed directories report their source removals through their own watch.
+    // A non-source file name cannot introduce program membership.
+    return false;
+}
+
+export { reportsProgramMembership };
+//# sourceMappingURL=reportsProgramMembership.mjs.map

package/lib/core/transform/project/reportsProgramMembership.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reportsProgramMembership.mjs","sources":["../../../../src/core/transform/project/reportsProgramMembership.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCG;AACG,SAAU,wBAAwB,CACtC,IAAY,EACZ,QAAgB,EAChB,QAAgB,EAChB,MAAoC,EACpC,UAA6C,EAAA;IAE7C,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ;AACxD,IAAA,MAAM,OAAO,GAAG,QAAQ,KAAK,OAAO,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;AAC9D,IAAA,IACE;AACG,SAAA,QAAQ,CAAC,IAAI,EAAE,QAAQ;AACvB,SAAA,KAAK,CAAC,OAAO,CAAC,GAAG;AACjB,SAAA,IAAI,CAAC,CAAC,OAAO,KAAK,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,EAC5D;AACA,QAAA,OAAO,KAAK;IACd;IACA,IACE,CAAC,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;QAC1D,CAAC,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,EACzD;AACA,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI;QACF,IAAI,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE;YAC5C,QACE,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC;gBACxD,CAAC,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;QAEtE;IACF;AAAE,IAAA,MAAM;;IAER;AACA,IAAA,IAAI,yBAAyB,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE;;;;QAI/C,QACE,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;YACzD,CAAC,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC;IAErE;;;AAGA,IAAA,OAAO,KAAK;AACd;;;;"}

package/lib/core/transform/project/toProjectKey.d.cts

@@ -0,0 +1,30 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+/**
+ * Return the key a file is recorded under in a generation's project hashes.
+ *
+ * Inside the project root the key is the root-relative path. Outside it, the
+ * key is the file's full identity. Both use forward slashes and the
+ * filesystem's identity rules, so two spellings of one file map to one key
+ * within the compiler's path protocol. Literal backslashes are interpreted as
+ * separators by that protocol rather than encoded as POSIX filename
+ * characters.
+ *
+ * @evidence contracts/common.md#principled-implementation The supplied native identity context decides containment and address equivalence; inside-root identities become relative keys while outside-root identities retain their full address.
+ * @evidence contracts/common.md#clear-and-simple-design The operation separates native identity from slash protocol encoding and delegates each to its existing helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native case and link policy are not replaced with a universal lowercase rule or substring-only containment.
+ * @evidence contracts/common.md#meaningful-documentation The native comment identifies both key namespaces and explains why equivalent spellings share a key under the filesystem's actual identity policy.
+ * @evidence contracts/portability.md#os-neutral-implementation The existing filesystem identity context owns directory case capabilities, links and root containment; forward slashes are applied only to the compiler hash-key protocol after native identity is established.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Root and file identity plus containment share one resolver transaction;
+ *   memoized identities avoid repeated native observations inside isWithin.
+ *   Normalization and key slicing scale with their path spelling lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   A supplied identity context shares its path and case observations within
+ *   the caller's filesystem transaction. An omitted context is fresh, so
+ *   unrelated generations do not inherit historical native answers.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A supplied transaction remains caller-owned. The default context is
+ *   local to this call and is released on return or throw, with entries driven
+ *   by these two paths and their observed ancestors rather than project history.
+ */
+export declare function toProjectKey(root: string, file: string, identities?: FilesystemPathIdentityContext): string;

package/lib/core/transform/project/toProjectKey.d.mts

@@ -0,0 +1,30 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+/**
+ * Return the key a file is recorded under in a generation's project hashes.
+ *
+ * Inside the project root the key is the root-relative path. Outside it, the
+ * key is the file's full identity. Both use forward slashes and the
+ * filesystem's identity rules, so two spellings of one file map to one key
+ * within the compiler's path protocol. Literal backslashes are interpreted as
+ * separators by that protocol rather than encoded as POSIX filename
+ * characters.
+ *
+ * @evidence contracts/common.md#principled-implementation The supplied native identity context decides containment and address equivalence; inside-root identities become relative keys while outside-root identities retain their full address.
+ * @evidence contracts/common.md#clear-and-simple-design The operation separates native identity from slash protocol encoding and delegates each to its existing helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native case and link policy are not replaced with a universal lowercase rule or substring-only containment.
+ * @evidence contracts/common.md#meaningful-documentation The native comment identifies both key namespaces and explains why equivalent spellings share a key under the filesystem's actual identity policy.
+ * @evidence contracts/portability.md#os-neutral-implementation The existing filesystem identity context owns directory case capabilities, links and root containment; forward slashes are applied only to the compiler hash-key protocol after native identity is established.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Root and file identity plus containment share one resolver transaction;
+ *   memoized identities avoid repeated native observations inside isWithin.
+ *   Normalization and key slicing scale with their path spelling lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   A supplied identity context shares its path and case observations within
+ *   the caller's filesystem transaction. An omitted context is fresh, so
+ *   unrelated generations do not inherit historical native answers.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A supplied transaction remains caller-owned. The default context is
+ *   local to this call and is released on return or throw, with entries driven
+ *   by these two paths and their observed ancestors rather than project history.
+ */
+export declare function toProjectKey(root: string, file: string, identities?: FilesystemPathIdentityContext): string;

package/lib/core/transform/project/toProjectKey.d.ts

@@ -0,0 +1,30 @@
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+/**
+ * Return the key a file is recorded under in a generation's project hashes.
+ *
+ * Inside the project root the key is the root-relative path. Outside it, the
+ * key is the file's full identity. Both use forward slashes and the
+ * filesystem's identity rules, so two spellings of one file map to one key
+ * within the compiler's path protocol. Literal backslashes are interpreted as
+ * separators by that protocol rather than encoded as POSIX filename
+ * characters.
+ *
+ * @evidence contracts/common.md#principled-implementation The supplied native identity context decides containment and address equivalence; inside-root identities become relative keys while outside-root identities retain their full address.
+ * @evidence contracts/common.md#clear-and-simple-design The operation separates native identity from slash protocol encoding and delegates each to its existing helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native case and link policy are not replaced with a universal lowercase rule or substring-only containment.
+ * @evidence contracts/common.md#meaningful-documentation The native comment identifies both key namespaces and explains why equivalent spellings share a key under the filesystem's actual identity policy.
+ * @evidence contracts/portability.md#os-neutral-implementation The existing filesystem identity context owns directory case capabilities, links and root containment; forward slashes are applied only to the compiler hash-key protocol after native identity is established.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Root and file identity plus containment share one resolver transaction;
+ *   memoized identities avoid repeated native observations inside isWithin.
+ *   Normalization and key slicing scale with their path spelling lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   A supplied identity context shares its path and case observations within
+ *   the caller's filesystem transaction. An omitted context is fresh, so
+ *   unrelated generations do not inherit historical native answers.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A supplied transaction remains caller-owned. The default context is
+ *   local to this call and is released on return or throw, with entries driven
+ *   by these two paths and their observed ancestors rather than project history.
+ */
+export declare function toProjectKey(root: string, file: string, identities?: FilesystemPathIdentityContext): string;

package/lib/core/transform/project/toProjectKey.js

@@ -0,0 +1,45 @@
+'use strict';
+
+var createHostPathIdentityContext = require('../filesystem/createHostPathIdentityContext.js');
+var normalizePath = require('../filesystem/normalizePath.js');
+var pathIdentityKey = require('../filesystem/pathIdentityKey.js');
+
+/**
+ * Return the key a file is recorded under in a generation's project hashes.
+ *
+ * Inside the project root the key is the root-relative path. Outside it, the
+ * key is the file's full identity. Both use forward slashes and the
+ * filesystem's identity rules, so two spellings of one file map to one key
+ * within the compiler's path protocol. Literal backslashes are interpreted as
+ * separators by that protocol rather than encoded as POSIX filename
+ * characters.
+ *
+ * @evidence contracts/common.md#principled-implementation The supplied native identity context decides containment and address equivalence; inside-root identities become relative keys while outside-root identities retain their full address.
+ * @evidence contracts/common.md#clear-and-simple-design The operation separates native identity from slash protocol encoding and delegates each to its existing helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native case and link policy are not replaced with a universal lowercase rule or substring-only containment.
+ * @evidence contracts/common.md#meaningful-documentation The native comment identifies both key namespaces and explains why equivalent spellings share a key under the filesystem's actual identity policy.
+ * @evidence contracts/portability.md#os-neutral-implementation The existing filesystem identity context owns directory case capabilities, links and root containment; forward slashes are applied only to the compiler hash-key protocol after native identity is established.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Root and file identity plus containment share one resolver transaction;
+ *   memoized identities avoid repeated native observations inside isWithin.
+ *   Normalization and key slicing scale with their path spelling lengths.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   A supplied identity context shares its path and case observations within
+ *   the caller's filesystem transaction. An omitted context is fresh, so
+ *   unrelated generations do not inherit historical native answers.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A supplied transaction remains caller-owned. The default context is
+ *   local to this call and is released on return or throw, with entries driven
+ *   by these two paths and their observed ancestors rather than project history.
+ */
+function toProjectKey(root, file, identities = createHostPathIdentityContext.createHostPathIdentityContext()) {
+    const rootKey = pathIdentityKey.pathIdentityKey(root, identities);
+    const fileKey = pathIdentityKey.pathIdentityKey(file, identities);
+    if (!identities.isWithin(root, file)) {
+        return normalizePath.normalizePath(fileKey);
+    }
+    return normalizePath.normalizePath(fileKey.slice(rootKey.length).replace(/^[/\\]+/, ""));
+}
+
+exports.toProjectKey = toProjectKey;
+//# sourceMappingURL=toProjectKey.js.map

package/lib/core/transform/project/toProjectKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toProjectKey.js","sources":["../../../../src/core/transform/project/toProjectKey.ts"],"sourcesContent":[null],"names":["createHostPathIdentityContext","pathIdentityKey","normalizePath"],"mappings":";;;;;;AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;AACG,SAAU,YAAY,CAC1B,IAAY,EACZ,IAAY,EACZ,UAAA,GAA4CA,2DAA6B,EAAE,EAAA;IAE3E,MAAM,OAAO,GAAGC,+BAAe,CAAC,IAAI,EAAE,UAAU,CAAC;IACjD,MAAM,OAAO,GAAGA,+BAAe,CAAC,IAAI,EAAE,UAAU,CAAC;IACjD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;AACpC,QAAA,OAAOC,2BAAa,CAAC,OAAO,CAAC;IAC/B;AACA,IAAA,OAAOA,2BAAa,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AAC5E;;;;"}