@ttsc/unplugin 0.30.3 → 0.31.0

package/lib/core/transform/inputs/inputMetadataEvidence.d.mts

@@ -0,0 +1,24 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+import type { TtscInputMetadataEvidence } from "./TtscInputMetadataEvidence.mjs";
+/**
+ * Observe lexical-link and target metadata together with clock separability. An
+ * unavailable link target retains a missing-target signature and cannot
+ * authorize notification-only or metadata-only reuse. Unavailable lexical
+ * metadata returns undefined rather than representing a proven missing input.
+ *
+ * The caller must refresh the filesystem's device clock references before the
+ * content read whose reuse is being proven; this observer does not mint them.
+ *
+ * @evidence contracts/common.md#principled-implementation Link and target identity, size and stamps capture different mutation paths; a missing target stays distinct, and both observed stamps must pass the same-device strict clock-separability predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One metadata record carries signature, notification authority and separability as independent facts; clock acquisition and later content-reuse decisions remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Symlinks and multiply linked files cannot acquire blanket watcher authority, and broken-link state is not rewritten into a lexical-parent missing-path proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state unavailable-target behavior, unavailable metadata and clock-reference ordering; separated tags and distinct member comments follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral evidence reads actual bigint device, inode, link count and nanosecond stamps through the supplied following/nonfollowing capabilities rather than assuming OS-wide clock precision or watcher coverage.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One lstat suffices for ordinary inputs; only symbolic links need a target
+ *   stat. Fixed-field signatures and device lookups avoid file-byte reads while
+ *   native path resolution and bigint formatting retain component/digit costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This captures the evidence consumed by reuse coordinators; it neither stores completed content work nor decides equivalence across deliveries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The result holds primitive evidence only; device clock references belong to their filesystem owner and this function acquires no retained handle or task.
+ */
+export declare function inputMetadataEvidence(file: string, filesystem?: TtscTransformFilesystemOperations): TtscInputMetadataEvidence | undefined;

package/lib/core/transform/inputs/inputMetadataEvidence.d.ts

@@ -0,0 +1,24 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import type { TtscInputMetadataEvidence } from "./TtscInputMetadataEvidence";
+/**
+ * Observe lexical-link and target metadata together with clock separability. An
+ * unavailable link target retains a missing-target signature and cannot
+ * authorize notification-only or metadata-only reuse. Unavailable lexical
+ * metadata returns undefined rather than representing a proven missing input.
+ *
+ * The caller must refresh the filesystem's device clock references before the
+ * content read whose reuse is being proven; this observer does not mint them.
+ *
+ * @evidence contracts/common.md#principled-implementation Link and target identity, size and stamps capture different mutation paths; a missing target stays distinct, and both observed stamps must pass the same-device strict clock-separability predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One metadata record carries signature, notification authority and separability as independent facts; clock acquisition and later content-reuse decisions remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Symlinks and multiply linked files cannot acquire blanket watcher authority, and broken-link state is not rewritten into a lexical-parent missing-path proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state unavailable-target behavior, unavailable metadata and clock-reference ordering; separated tags and distinct member comments follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral evidence reads actual bigint device, inode, link count and nanosecond stamps through the supplied following/nonfollowing capabilities rather than assuming OS-wide clock precision or watcher coverage.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One lstat suffices for ordinary inputs; only symbolic links need a target
+ *   stat. Fixed-field signatures and device lookups avoid file-byte reads while
+ *   native path resolution and bigint formatting retain component/digit costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This captures the evidence consumed by reuse coordinators; it neither stores completed content work nor decides equivalence across deliveries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The result holds primitive evidence only; device clock references belong to their filesystem owner and this function acquires no retained handle or task.
+ */
+export declare function inputMetadataEvidence(file: string, filesystem?: TtscTransformFilesystemOperations): TtscInputMetadataEvidence | undefined;

package/lib/core/transform/inputs/inputMetadataEvidence.js

@@ -0,0 +1,92 @@
+'use strict';
+
+var stampSeparable = require('../clock/stampSeparable.js');
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+
+/**
+ * Observe lexical-link and target metadata together with clock separability. An
+ * unavailable link target retains a missing-target signature and cannot
+ * authorize notification-only or metadata-only reuse. Unavailable lexical
+ * metadata returns undefined rather than representing a proven missing input.
+ *
+ * The caller must refresh the filesystem's device clock references before the
+ * content read whose reuse is being proven; this observer does not mint them.
+ *
+ * @evidence contracts/common.md#principled-implementation Link and target identity, size and stamps capture different mutation paths; a missing target stays distinct, and both observed stamps must pass the same-device strict clock-separability predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One metadata record carries signature, notification authority and separability as independent facts; clock acquisition and later content-reuse decisions remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Symlinks and multiply linked files cannot acquire blanket watcher authority, and broken-link state is not rewritten into a lexical-parent missing-path proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state unavailable-target behavior, unavailable metadata and clock-reference ordering; separated tags and distinct member comments follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral evidence reads actual bigint device, inode, link count and nanosecond stamps through the supplied following/nonfollowing capabilities rather than assuming OS-wide clock precision or watcher coverage.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One lstat suffices for ordinary inputs; only symbolic links need a target
+ *   stat. Fixed-field signatures and device lookups avoid file-byte reads while
+ *   native path resolution and bigint formatting retain component/digit costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This captures the evidence consumed by reuse coordinators; it neither stores completed content work nor decides equivalence across deliveries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The result holds primitive evidence only; device clock references belong to their filesystem owner and this function acquires no retained handle or task.
+ */
+function inputMetadataEvidence(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        const link = filesystem.lstat(file);
+        let target = link;
+        if (link.isSymbolicLink()) {
+            try {
+                target = filesystem.statBigInt(file);
+            }
+            catch {
+                // Keep a broken link in the existing-input manifest. Its own metadata
+                // stays stable while the target is missing, and the first successful
+                // stat after the target appears changes this signature. Treating it as
+                // a plain missing path would watch/list only the link's parent, which
+                // cannot observe a target created in another directory. It carries no
+                // readable bytes, so it never needs to be separable.
+                return {
+                    signature: [
+                        link.dev,
+                        link.ino,
+                        link.mode,
+                        link.size,
+                        link.mtimeNs,
+                        link.ctimeNs,
+                        "missing-target",
+                    ].join(":"),
+                    notificationAuthoritative: false,
+                    separable: false,
+                };
+            }
+        }
+        return {
+            signature: [
+                link.dev,
+                link.ino,
+                link.nlink,
+                link.mode,
+                link.size,
+                link.mtimeNs,
+                link.ctimeNs,
+                target.dev,
+                target.ino,
+                target.nlink,
+                target.mode,
+                target.size,
+                target.mtimeNs,
+                target.ctimeNs,
+            ].join(":"),
+            // A write through a hardlink outside the watched tree changes this inode
+            // without notifying either the original directory or a watcher opened on
+            // the original path. Keep such files on metadata validation. Symlinks are
+            // likewise governed by the target path, outside the lexical observer.
+            notificationAuthoritative: !link.isSymbolicLink() &&
+                !(link.isFile() && (link.nlink > 1n || target.nlink > 1n)),
+            // Both halves must be separable: a write remints the target's stamp, a
+            // link retarget the link's own, and either one hiding inside its recorded
+            // tick would evade the skipped content and realpath comparisons.
+            separable: stampSeparable.stampSeparable(filesystem, link) && stampSeparable.stampSeparable(filesystem, target),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+
+exports.inputMetadataEvidence = inputMetadataEvidence;
+//# sourceMappingURL=inputMetadataEvidence.js.map

package/lib/core/transform/inputs/inputMetadataEvidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputMetadataEvidence.js","sources":["../../../../src/core/transform/inputs/inputMetadataEvidence.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","stampSeparable"],"mappings":";;;;;AAKA;;;;;;;;;;;;;;;;;;;;AAoBG;SACa,qBAAqB,CACnC,IAAY,EACZ,aAAgDA,2DAA6B,EAAA;AAE7E,IAAA,IAAI;QACF,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;QACnC,IAAI,MAAM,GAAG,IAAI;AACjB,QAAA,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE;AACzB,YAAA,IAAI;AACF,gBAAA,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;YACtC;AAAE,YAAA,MAAM;;;;;;;gBAON,OAAO;AACL,oBAAA,SAAS,EAAE;AACT,wBAAA,IAAI,CAAC,GAAG;AACR,wBAAA,IAAI,CAAC,GAAG;AACR,wBAAA,IAAI,CAAC,IAAI;AACT,wBAAA,IAAI,CAAC,IAAI;AACT,wBAAA,IAAI,CAAC,OAAO;AACZ,wBAAA,IAAI,CAAC,OAAO;wBACZ,gBAAgB;qBACjB,CAAC,IAAI,CAAC,GAAG,CAAC;AACX,oBAAA,yBAAyB,EAAE,KAAK;AAChC,oBAAA,SAAS,EAAE,KAAK;iBACjB;YACH;QACF;QACA,OAAO;AACL,YAAA,SAAS,EAAE;AACT,gBAAA,IAAI,CAAC,GAAG;AACR,gBAAA,IAAI,CAAC,GAAG;AACR,gBAAA,IAAI,CAAC,KAAK;AACV,gBAAA,IAAI,CAAC,IAAI;AACT,gBAAA,IAAI,CAAC,IAAI;AACT,gBAAA,IAAI,CAAC,OAAO;AACZ,gBAAA,IAAI,CAAC,OAAO;AACZ,gBAAA,MAAM,CAAC,GAAG;AACV,gBAAA,MAAM,CAAC,GAAG;AACV,gBAAA,MAAM,CAAC,KAAK;AACZ,gBAAA,MAAM,CAAC,IAAI;AACX,gBAAA,MAAM,CAAC,IAAI;AACX,gBAAA,MAAM,CAAC,OAAO;AACd,gBAAA,MAAM,CAAC,OAAO;aACf,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;AAMX,YAAA,yBAAyB,EACvB,CAAC,IAAI,CAAC,cAAc,EAAE;AACtB,gBAAA,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;;;;AAK5D,YAAA,SAAS,EACPC,6BAAc,CAAC,UAAU,EAAE,IAAI,CAAC,IAAIA,6BAAc,CAAC,UAAU,EAAE,MAAM,CAAC;SACzE;IACH;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;;;;"}

package/lib/core/transform/inputs/inputMetadataEvidence.mjs

@@ -0,0 +1,90 @@
+import { stampSeparable } from '../clock/stampSeparable.mjs';
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+
+/**
+ * Observe lexical-link and target metadata together with clock separability. An
+ * unavailable link target retains a missing-target signature and cannot
+ * authorize notification-only or metadata-only reuse. Unavailable lexical
+ * metadata returns undefined rather than representing a proven missing input.
+ *
+ * The caller must refresh the filesystem's device clock references before the
+ * content read whose reuse is being proven; this observer does not mint them.
+ *
+ * @evidence contracts/common.md#principled-implementation Link and target identity, size and stamps capture different mutation paths; a missing target stays distinct, and both observed stamps must pass the same-device strict clock-separability predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One metadata record carries signature, notification authority and separability as independent facts; clock acquisition and later content-reuse decisions remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Symlinks and multiply linked files cannot acquire blanket watcher authority, and broken-link state is not rewritten into a lexical-parent missing-path proof.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state unavailable-target behavior, unavailable metadata and clock-reference ordering; separated tags and distinct member comments follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral evidence reads actual bigint device, inode, link count and nanosecond stamps through the supplied following/nonfollowing capabilities rather than assuming OS-wide clock precision or watcher coverage.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One lstat suffices for ordinary inputs; only symbolic links need a target
+ *   stat. Fixed-field signatures and device lookups avoid file-byte reads while
+ *   native path resolution and bigint formatting retain component/digit costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This captures the evidence consumed by reuse coordinators; it neither stores completed content work nor decides equivalence across deliveries.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The result holds primitive evidence only; device clock references belong to their filesystem owner and this function acquires no retained handle or task.
+ */
+function inputMetadataEvidence(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    try {
+        const link = filesystem.lstat(file);
+        let target = link;
+        if (link.isSymbolicLink()) {
+            try {
+                target = filesystem.statBigInt(file);
+            }
+            catch {
+                // Keep a broken link in the existing-input manifest. Its own metadata
+                // stays stable while the target is missing, and the first successful
+                // stat after the target appears changes this signature. Treating it as
+                // a plain missing path would watch/list only the link's parent, which
+                // cannot observe a target created in another directory. It carries no
+                // readable bytes, so it never needs to be separable.
+                return {
+                    signature: [
+                        link.dev,
+                        link.ino,
+                        link.mode,
+                        link.size,
+                        link.mtimeNs,
+                        link.ctimeNs,
+                        "missing-target",
+                    ].join(":"),
+                    notificationAuthoritative: false,
+                    separable: false,
+                };
+            }
+        }
+        return {
+            signature: [
+                link.dev,
+                link.ino,
+                link.nlink,
+                link.mode,
+                link.size,
+                link.mtimeNs,
+                link.ctimeNs,
+                target.dev,
+                target.ino,
+                target.nlink,
+                target.mode,
+                target.size,
+                target.mtimeNs,
+                target.ctimeNs,
+            ].join(":"),
+            // A write through a hardlink outside the watched tree changes this inode
+            // without notifying either the original directory or a watcher opened on
+            // the original path. Keep such files on metadata validation. Symlinks are
+            // likewise governed by the target path, outside the lexical observer.
+            notificationAuthoritative: !link.isSymbolicLink() &&
+                !(link.isFile() && (link.nlink > 1n || target.nlink > 1n)),
+            // Both halves must be separable: a write remints the target's stamp, a
+            // link retarget the link's own, and either one hiding inside its recorded
+            // tick would evade the skipped content and realpath comparisons.
+            separable: stampSeparable(filesystem, link) && stampSeparable(filesystem, target),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+
+export { inputMetadataEvidence };
+//# sourceMappingURL=inputMetadataEvidence.mjs.map

package/lib/core/transform/inputs/inputMetadataEvidence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputMetadataEvidence.mjs","sources":["../../../../src/core/transform/inputs/inputMetadataEvidence.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;;;;;;;AAoBG;SACa,qBAAqB,CACnC,IAAY,EACZ,aAAgD,6BAA6B,EAAA;AAE7E,IAAA,IAAI;QACF,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;QACnC,IAAI,MAAM,GAAG,IAAI;AACjB,QAAA,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE;AACzB,YAAA,IAAI;AACF,gBAAA,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;YACtC;AAAE,YAAA,MAAM;;;;;;;gBAON,OAAO;AACL,oBAAA,SAAS,EAAE;AACT,wBAAA,IAAI,CAAC,GAAG;AACR,wBAAA,IAAI,CAAC,GAAG;AACR,wBAAA,IAAI,CAAC,IAAI;AACT,wBAAA,IAAI,CAAC,IAAI;AACT,wBAAA,IAAI,CAAC,OAAO;AACZ,wBAAA,IAAI,CAAC,OAAO;wBACZ,gBAAgB;qBACjB,CAAC,IAAI,CAAC,GAAG,CAAC;AACX,oBAAA,yBAAyB,EAAE,KAAK;AAChC,oBAAA,SAAS,EAAE,KAAK;iBACjB;YACH;QACF;QACA,OAAO;AACL,YAAA,SAAS,EAAE;AACT,gBAAA,IAAI,CAAC,GAAG;AACR,gBAAA,IAAI,CAAC,GAAG;AACR,gBAAA,IAAI,CAAC,KAAK;AACV,gBAAA,IAAI,CAAC,IAAI;AACT,gBAAA,IAAI,CAAC,IAAI;AACT,gBAAA,IAAI,CAAC,OAAO;AACZ,gBAAA,IAAI,CAAC,OAAO;AACZ,gBAAA,MAAM,CAAC,GAAG;AACV,gBAAA,MAAM,CAAC,GAAG;AACV,gBAAA,MAAM,CAAC,KAAK;AACZ,gBAAA,MAAM,CAAC,IAAI;AACX,gBAAA,MAAM,CAAC,IAAI;AACX,gBAAA,MAAM,CAAC,OAAO;AACd,gBAAA,MAAM,CAAC,OAAO;aACf,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;AAMX,YAAA,yBAAyB,EACvB,CAAC,IAAI,CAAC,cAAc,EAAE;AACtB,gBAAA,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;;;;AAK5D,YAAA,SAAS,EACP,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,cAAc,CAAC,UAAU,EAAE,MAAM,CAAC;SACzE;IACH;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;;;;"}

package/lib/core/transform/inputs/inputMetadataSignature.d.cts

@@ -0,0 +1,20 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Extract the current lexical-path and target metadata signature, or undefined
+ * when metadata cannot be observed. Matching signatures alone do not authorize
+ * content reuse: the caller must also establish clock separability and
+ * coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional extraction preserves unavailable evidence instead of inventing a missing-path signature, while metadata semantics stay with inputMetadataEvidence.
+ * @evidence contracts/common.md#clear-and-simple-design This adapter exposes just the signature to callers that own their separate reuse conditions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Signature equality is not promoted into unconditional byte equality or silent-watcher proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose corrects the signature-only reuse implication and states unavailable metadata, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral metadata comes from the supplied following and nonfollowing capabilities; this wrapper adds no path or case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a string.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Delegated evidence performs one nonfollowing metadata read and at most one
+ *   target read, plus fixed-field bigint formatting and clock-device lookups.
+ *   Native path resolution and output digit lengths contribute real cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A signature is recomputed per proof; whether it may stand for content is decided by its callers against a fresh clock reference.
+ */
+export declare function inputMetadataSignature(file: string, filesystem?: TtscTransformFilesystemOperations): string | undefined;

package/lib/core/transform/inputs/inputMetadataSignature.d.mts

@@ -0,0 +1,20 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Extract the current lexical-path and target metadata signature, or undefined
+ * when metadata cannot be observed. Matching signatures alone do not authorize
+ * content reuse: the caller must also establish clock separability and
+ * coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional extraction preserves unavailable evidence instead of inventing a missing-path signature, while metadata semantics stay with inputMetadataEvidence.
+ * @evidence contracts/common.md#clear-and-simple-design This adapter exposes just the signature to callers that own their separate reuse conditions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Signature equality is not promoted into unconditional byte equality or silent-watcher proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose corrects the signature-only reuse implication and states unavailable metadata, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral metadata comes from the supplied following and nonfollowing capabilities; this wrapper adds no path or case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a string.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Delegated evidence performs one nonfollowing metadata read and at most one
+ *   target read, plus fixed-field bigint formatting and clock-device lookups.
+ *   Native path resolution and output digit lengths contribute real cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A signature is recomputed per proof; whether it may stand for content is decided by its callers against a fresh clock reference.
+ */
+export declare function inputMetadataSignature(file: string, filesystem?: TtscTransformFilesystemOperations): string | undefined;

package/lib/core/transform/inputs/inputMetadataSignature.d.ts

@@ -0,0 +1,20 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Extract the current lexical-path and target metadata signature, or undefined
+ * when metadata cannot be observed. Matching signatures alone do not authorize
+ * content reuse: the caller must also establish clock separability and
+ * coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional extraction preserves unavailable evidence instead of inventing a missing-path signature, while metadata semantics stay with inputMetadataEvidence.
+ * @evidence contracts/common.md#clear-and-simple-design This adapter exposes just the signature to callers that own their separate reuse conditions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Signature equality is not promoted into unconditional byte equality or silent-watcher proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose corrects the signature-only reuse implication and states unavailable metadata, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral metadata comes from the supplied following and nonfollowing capabilities; this wrapper adds no path or case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a string.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Delegated evidence performs one nonfollowing metadata read and at most one
+ *   target read, plus fixed-field bigint formatting and clock-device lookups.
+ *   Native path resolution and output digit lengths contribute real cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A signature is recomputed per proof; whether it may stand for content is decided by its callers against a fresh clock reference.
+ */
+export declare function inputMetadataSignature(file: string, filesystem?: TtscTransformFilesystemOperations): string | undefined;

package/lib/core/transform/inputs/inputMetadataSignature.js

@@ -0,0 +1,29 @@
+'use strict';
+
+var DEFAULT_FILESYSTEM_OPERATIONS = require('../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.js');
+var inputMetadataEvidence = require('./inputMetadataEvidence.js');
+
+/**
+ * Extract the current lexical-path and target metadata signature, or undefined
+ * when metadata cannot be observed. Matching signatures alone do not authorize
+ * content reuse: the caller must also establish clock separability and
+ * coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional extraction preserves unavailable evidence instead of inventing a missing-path signature, while metadata semantics stay with inputMetadataEvidence.
+ * @evidence contracts/common.md#clear-and-simple-design This adapter exposes just the signature to callers that own their separate reuse conditions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Signature equality is not promoted into unconditional byte equality or silent-watcher proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose corrects the signature-only reuse implication and states unavailable metadata, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral metadata comes from the supplied following and nonfollowing capabilities; this wrapper adds no path or case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a string.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Delegated evidence performs one nonfollowing metadata read and at most one
+ *   target read, plus fixed-field bigint formatting and clock-device lookups.
+ *   Native path resolution and output digit lengths contribute real cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A signature is recomputed per proof; whether it may stand for content is decided by its callers against a fresh clock reference.
+ */
+function inputMetadataSignature(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS.DEFAULT_FILESYSTEM_OPERATIONS) {
+    return inputMetadataEvidence.inputMetadataEvidence(file, filesystem)?.signature;
+}
+
+exports.inputMetadataSignature = inputMetadataSignature;
+//# sourceMappingURL=inputMetadataSignature.js.map

package/lib/core/transform/inputs/inputMetadataSignature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputMetadataSignature.js","sources":["../../../../src/core/transform/inputs/inputMetadataSignature.ts"],"sourcesContent":[null],"names":["DEFAULT_FILESYSTEM_OPERATIONS","inputMetadataEvidence"],"mappings":";;;;;AAIA;;;;;;;;;;;;;;;;;AAiBG;SACa,sBAAsB,CACpC,IAAY,EACZ,aAAgDA,2DAA6B,EAAA;IAE7E,OAAOC,2CAAqB,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,SAAS;AAC3D;;;;"}

package/lib/core/transform/inputs/inputMetadataSignature.mjs

@@ -0,0 +1,27 @@
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { inputMetadataEvidence } from './inputMetadataEvidence.mjs';
+
+/**
+ * Extract the current lexical-path and target metadata signature, or undefined
+ * when metadata cannot be observed. Matching signatures alone do not authorize
+ * content reuse: the caller must also establish clock separability and
+ * coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional extraction preserves unavailable evidence instead of inventing a missing-path signature, while metadata semantics stay with inputMetadataEvidence.
+ * @evidence contracts/common.md#clear-and-simple-design This adapter exposes just the signature to callers that own their separate reuse conditions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Signature equality is not promoted into unconditional byte equality or silent-watcher proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose corrects the signature-only reuse implication and states unavailable metadata, with separated tags following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral metadata comes from the supplied following and nonfollowing capabilities; this wrapper adds no path or case assumptions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing; it returns a string.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Delegated evidence performs one nonfollowing metadata read and at most one
+ *   target read, plus fixed-field bigint formatting and clock-device lookups.
+ *   Native path resolution and output digit lengths contribute real cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A signature is recomputed per proof; whether it may stand for content is decided by its callers against a fresh clock reference.
+ */
+function inputMetadataSignature(file, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    return inputMetadataEvidence(file, filesystem)?.signature;
+}
+
+export { inputMetadataSignature };
+//# sourceMappingURL=inputMetadataSignature.mjs.map

package/lib/core/transform/inputs/inputMetadataSignature.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputMetadataSignature.mjs","sources":["../../../../src/core/transform/inputs/inputMetadataSignature.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;AAiBG;SACa,sBAAsB,CACpC,IAAY,EACZ,aAAgD,6BAA6B,EAAA;IAE7E,OAAO,qBAAqB,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,SAAS;AAC3D;;;;"}

package/lib/core/transform/inputs/matchesGraphInputObservation.d.cts

@@ -0,0 +1,18 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Report whether replay found no changed recorded compiler predicates.
+ * Unrecorded predicates impose no condition. The failure collector performs the
+ * complete observation even though this adapter returns only a boolean.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty failure list means each explicitly recorded predicate matched its replay; absent predicates do not create extra obligations.
+ * @evidence contracts/common.md#clear-and-simple-design The boolean adapter uses the same failure collector as diagnostic callers instead of a competing predicate replay implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acceptance is derived from actual replay failures, not a quiet watcher or a cached boolean independent of current observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absent-predicate and complete-replay semantics, using separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay receives the same filesystem operations and identity context as the observation owner; the adapter adds no native spelling assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms It returns whether graphInputObservationFailures found nothing, which replays only the recorded predicates.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+export declare function matchesGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem: TtscTransformFilesystemOperations, identities: FilesystemPathIdentityContext): boolean;

package/lib/core/transform/inputs/matchesGraphInputObservation.d.mts

@@ -0,0 +1,18 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Report whether replay found no changed recorded compiler predicates.
+ * Unrecorded predicates impose no condition. The failure collector performs the
+ * complete observation even though this adapter returns only a boolean.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty failure list means each explicitly recorded predicate matched its replay; absent predicates do not create extra obligations.
+ * @evidence contracts/common.md#clear-and-simple-design The boolean adapter uses the same failure collector as diagnostic callers instead of a competing predicate replay implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acceptance is derived from actual replay failures, not a quiet watcher or a cached boolean independent of current observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absent-predicate and complete-replay semantics, using separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay receives the same filesystem operations and identity context as the observation owner; the adapter adds no native spelling assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms It returns whether graphInputObservationFailures found nothing, which replays only the recorded predicates.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+export declare function matchesGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem: TtscTransformFilesystemOperations, identities: FilesystemPathIdentityContext): boolean;

package/lib/core/transform/inputs/matchesGraphInputObservation.d.ts

@@ -0,0 +1,18 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+import type { FilesystemPathIdentityContext } from "ttsc/path-identity";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Report whether replay found no changed recorded compiler predicates.
+ * Unrecorded predicates impose no condition. The failure collector performs the
+ * complete observation even though this adapter returns only a boolean.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty failure list means each explicitly recorded predicate matched its replay; absent predicates do not create extra obligations.
+ * @evidence contracts/common.md#clear-and-simple-design The boolean adapter uses the same failure collector as diagnostic callers instead of a competing predicate replay implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acceptance is derived from actual replay failures, not a quiet watcher or a cached boolean independent of current observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absent-predicate and complete-replay semantics, using separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay receives the same filesystem operations and identity context as the observation owner; the adapter adds no native spelling assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms It returns whether graphInputObservationFailures found nothing, which replays only the recorded predicates.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+export declare function matchesGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem: TtscTransformFilesystemOperations, identities: FilesystemPathIdentityContext): boolean;

package/lib/core/transform/inputs/matchesGraphInputObservation.js

@@ -0,0 +1,25 @@
+'use strict';
+
+var graphInputObservationFailures = require('./graphInputObservationFailures.js');
+
+/**
+ * Report whether replay found no changed recorded compiler predicates.
+ * Unrecorded predicates impose no condition. The failure collector performs the
+ * complete observation even though this adapter returns only a boolean.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty failure list means each explicitly recorded predicate matched its replay; absent predicates do not create extra obligations.
+ * @evidence contracts/common.md#clear-and-simple-design The boolean adapter uses the same failure collector as diagnostic callers instead of a competing predicate replay implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acceptance is derived from actual replay failures, not a quiet watcher or a cached boolean independent of current observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absent-predicate and complete-replay semantics, using separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay receives the same filesystem operations and identity context as the observation owner; the adapter adds no native spelling assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms It returns whether graphInputObservationFailures found nothing, which replays only the recorded predicates.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+function matchesGraphInputObservation(file, observation, filesystem, identities) {
+    return (graphInputObservationFailures.graphInputObservationFailures(file, observation, filesystem, identities)
+        .length === 0);
+}
+
+exports.matchesGraphInputObservation = matchesGraphInputObservation;
+//# sourceMappingURL=matchesGraphInputObservation.js.map

package/lib/core/transform/inputs/matchesGraphInputObservation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchesGraphInputObservation.js","sources":["../../../../src/core/transform/inputs/matchesGraphInputObservation.ts"],"sourcesContent":[null],"names":["graphInputObservationFailures"],"mappings":";;;;AAMA;;;;;;;;;;;;;AAaG;AACG,SAAU,4BAA4B,CAC1C,IAAY,EACZ,WAA0D,EAC1D,UAA6C,EAC7C,UAAyC,EAAA;IAEzC,QACEA,2DAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU;SACpE,MAAM,KAAK,CAAC;AAEnB;;;;"}

package/lib/core/transform/inputs/matchesGraphInputObservation.mjs

@@ -0,0 +1,23 @@
+import { graphInputObservationFailures } from './graphInputObservationFailures.mjs';
+
+/**
+ * Report whether replay found no changed recorded compiler predicates.
+ * Unrecorded predicates impose no condition. The failure collector performs the
+ * complete observation even though this adapter returns only a boolean.
+ *
+ * @evidence contracts/common.md#principled-implementation An empty failure list means each explicitly recorded predicate matched its replay; absent predicates do not create extra obligations.
+ * @evidence contracts/common.md#clear-and-simple-design The boolean adapter uses the same failure collector as diagnostic callers instead of a competing predicate replay implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Acceptance is derived from actual replay failures, not a quiet watcher or a cached boolean independent of current observations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absent-predicate and complete-replay semantics, using separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral replay receives the same filesystem operations and identity context as the observation owner; the adapter adds no native spelling assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms It returns whether graphInputObservationFailures found nothing, which replays only the recorded predicates.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A replay answers for the filesystem now; callers decide whether an earlier replay may be shared.
+ */
+function matchesGraphInputObservation(file, observation, filesystem, identities) {
+    return (graphInputObservationFailures(file, observation, filesystem, identities)
+        .length === 0);
+}
+
+export { matchesGraphInputObservation };
+//# sourceMappingURL=matchesGraphInputObservation.mjs.map

package/lib/core/transform/inputs/matchesGraphInputObservation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchesGraphInputObservation.mjs","sources":["../../../../src/core/transform/inputs/matchesGraphInputObservation.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAMA;;;;;;;;;;;;;AAaG;AACG,SAAU,4BAA4B,CAC1C,IAAY,EACZ,WAA0D,EAC1D,UAA6C,EAC7C,UAAyC,EAAA;IAEzC,QACE,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU;SACpE,MAAM,KAAK,CAAC;AAEnB;;;;"}

package/lib/core/transform/inputs/missingPathProbe.d.cts

@@ -0,0 +1,33 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.cjs";
+/**
+ * Choose an ancestor candidate for a path already observed as missing. The
+ * nearest existing directory supplies a child name to check. An existing
+ * nondirectory ancestor is returned as a blocker; metadata must also prove that
+ * blocker unchanged. The caller must obtain native existence evidence for the
+ * returned child; a directory listing alone cannot exclude every native alias.
+ *
+ * Root exhaustion returns a candidate even when root stat failed, so this
+ * selection alone never proves absence. Path parsing follows an explicit
+ * filesystem.platform override, or the running Node host when none is
+ * supplied.
+ *
+ * @evidence contracts/common.md#principled-implementation Ancestor traversal stops at a directory, a nondirectory blocker or root; the returned candidate and optional blocker let consumers obtain the separate observations required for an absence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One upward walk selects the observation boundary without acquiring watchers or asserting that selection itself certifies a missing path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed ancestor stats continue to parents; root termination is a traversal boundary rather than invented successful accessibility or an unconditional absence result.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain blocker evidence, caller native-proof responsibility, root failure and explicit versus default path dialect; member comments and tags remain visibly separated following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral traversal selects Node's Windows or POSIX path implementation from the observing filesystem's override, falling back to the host platform, and applies that same dialect to resolution, parent traversal and child-name extraction without inferring case policy.
+ * @evidence contracts/performance.md#efficient-algorithms At most D ancestor stats are performed for D path components; parent string operations can cost O(D times path length), and no subtree walk or content read is performed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selects one current probe boundary; observers own reuse of candidate observations and blocker metadata across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The walk retains only its current path and returned candidate; native watchers and saved absence proofs belong to consumers.
+ */
+export declare function missingPathProbe(file: string, filesystem?: TtscTransformFilesystemOperations): {
+    /** Existing nondirectory ancestor whose metadata must remain unchanged. */
+    blocker?: string;
+    /**
+     * Directory containing the candidate; exhaustion does not prove
+     * accessibility.
+     */
+    directory: string;
+    /** Original child spelling whose native absence the caller must establish. */
+    name: string;
+};

package/lib/core/transform/inputs/missingPathProbe.d.mts

@@ -0,0 +1,33 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations.mjs";
+/**
+ * Choose an ancestor candidate for a path already observed as missing. The
+ * nearest existing directory supplies a child name to check. An existing
+ * nondirectory ancestor is returned as a blocker; metadata must also prove that
+ * blocker unchanged. The caller must obtain native existence evidence for the
+ * returned child; a directory listing alone cannot exclude every native alias.
+ *
+ * Root exhaustion returns a candidate even when root stat failed, so this
+ * selection alone never proves absence. Path parsing follows an explicit
+ * filesystem.platform override, or the running Node host when none is
+ * supplied.
+ *
+ * @evidence contracts/common.md#principled-implementation Ancestor traversal stops at a directory, a nondirectory blocker or root; the returned candidate and optional blocker let consumers obtain the separate observations required for an absence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One upward walk selects the observation boundary without acquiring watchers or asserting that selection itself certifies a missing path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed ancestor stats continue to parents; root termination is a traversal boundary rather than invented successful accessibility or an unconditional absence result.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain blocker evidence, caller native-proof responsibility, root failure and explicit versus default path dialect; member comments and tags remain visibly separated following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral traversal selects Node's Windows or POSIX path implementation from the observing filesystem's override, falling back to the host platform, and applies that same dialect to resolution, parent traversal and child-name extraction without inferring case policy.
+ * @evidence contracts/performance.md#efficient-algorithms At most D ancestor stats are performed for D path components; parent string operations can cost O(D times path length), and no subtree walk or content read is performed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selects one current probe boundary; observers own reuse of candidate observations and blocker metadata across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The walk retains only its current path and returned candidate; native watchers and saved absence proofs belong to consumers.
+ */
+export declare function missingPathProbe(file: string, filesystem?: TtscTransformFilesystemOperations): {
+    /** Existing nondirectory ancestor whose metadata must remain unchanged. */
+    blocker?: string;
+    /**
+     * Directory containing the candidate; exhaustion does not prove
+     * accessibility.
+     */
+    directory: string;
+    /** Original child spelling whose native absence the caller must establish. */
+    name: string;
+};

package/lib/core/transform/inputs/missingPathProbe.d.ts

@@ -0,0 +1,33 @@
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+/**
+ * Choose an ancestor candidate for a path already observed as missing. The
+ * nearest existing directory supplies a child name to check. An existing
+ * nondirectory ancestor is returned as a blocker; metadata must also prove that
+ * blocker unchanged. The caller must obtain native existence evidence for the
+ * returned child; a directory listing alone cannot exclude every native alias.
+ *
+ * Root exhaustion returns a candidate even when root stat failed, so this
+ * selection alone never proves absence. Path parsing follows an explicit
+ * filesystem.platform override, or the running Node host when none is
+ * supplied.
+ *
+ * @evidence contracts/common.md#principled-implementation Ancestor traversal stops at a directory, a nondirectory blocker or root; the returned candidate and optional blocker let consumers obtain the separate observations required for an absence proof.
+ * @evidence contracts/common.md#clear-and-simple-design One upward walk selects the observation boundary without acquiring watchers or asserting that selection itself certifies a missing path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed ancestor stats continue to parents; root termination is a traversal boundary rather than invented successful accessibility or an unconditional absence result.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain blocker evidence, caller native-proof responsibility, root failure and explicit versus default path dialect; member comments and tags remain visibly separated following documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation OS-neutral traversal selects Node's Windows or POSIX path implementation from the observing filesystem's override, falling back to the host platform, and applies that same dialect to resolution, parent traversal and child-name extraction without inferring case policy.
+ * @evidence contracts/performance.md#efficient-algorithms At most D ancestor stats are performed for D path components; parent string operations can cost O(D times path length), and no subtree walk or content read is performed.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selects one current probe boundary; observers own reuse of candidate observations and blocker metadata across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The walk retains only its current path and returned candidate; native watchers and saved absence proofs belong to consumers.
+ */
+export declare function missingPathProbe(file: string, filesystem?: TtscTransformFilesystemOperations): {
+    /** Existing nondirectory ancestor whose metadata must remain unchanged. */
+    blocker?: string;
+    /**
+     * Directory containing the candidate; exhaustion does not prove
+     * accessibility.
+     */
+    directory: string;
+    /** Original child spelling whose native absence the caller must establish. */
+    name: string;
+};