ttsc 0.30.3 → 0.31.0

package/lib/plugin/internal/source/PluginBuildEnvironmentWitness.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginBuildEnvironmentWitness = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const E2ETrace_1 = require("../../../internal/E2ETrace");
+/**
+ * Native path metadata and ambient lookup variables actually observed while
+ * reading a plugin build environment.
+ *
+ * The environment digest reads the Go tool, the file `go env -w` writes, the
+ * executables the C toolchain commands name, and GOROOT
+ * (`hashPluginBuildEnvironment`). Their metadata, taken before their content is
+ * read, is what a later observer compares: a process keeping its reading
+ * (`processPluginBuildEnvironment`), and a build proving the toolchain it ran
+ * is the one its key read. Change time can reveal a write even when size and
+ * modification time are restored.
+ *
+ * This witnesses native metadata and link target names, not a second byte
+ * comparison. Its change detection assumes the filesystem distinguishes
+ * contributing edits in the captured identity and timestamps; an edit that
+ * reproduces the entire metadata signature is outside the proof this record
+ * supplies. Native executable lookup variables are recorded at the lookup,
+ * because a shared worker can observe a transient parent value between the
+ * request and final snapshots.
+ *
+ * @evidence contracts/common.md#principled-implementation Pre-read identity and write metadata witness external dependencies not carried by variables under the documented metadata-distinguishability premise; a refused dependency makes the complete reading unusable.
+ * @evidence contracts/common.md#clear-and-simple-design Record construction, refusal and validation share one metadata representation; the caller owns the reading and its lifetime.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Validation inspects real paths instead of replacing filesystem behavior or accepting a stable pathname as proof of unchanged contents.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain provenance, replacement detection and both consuming boundaries; member documentation states refusal and validation meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Node bigint stat follows the content reader's targets, while lstat and readlink separately witness link identity and target spelling; no platform name supplies case or identity policy.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace defines the record and operations; add and holds own observation/validation processing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Consumers own environment reuse; the namespace itself retains no reading.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Witness maps are created and released by callers, not retained by this namespace.
+ */
+var PluginBuildEnvironmentWitness;
+(function (PluginBuildEnvironmentWitness) {
+    /**
+     * Record `file`'s metadata before reading it, unless already recorded.
+     * `observed` reuses a stat the caller just took before the same read.
+     *
+     * @evidence contracts/common.md#principled-implementation First-write retention keeps the earliest metadata even when a path contributes more than once; caller-provided metadata is from the same pre-read observation.
+     * @evidence contracts/common.md#clear-and-simple-design Optional output makes one reader usable with or without a witness and leaves signature encoding in one helper.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Observation uses native stat state; absent witnessing does not alter the content read or fake validity.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states first-observation semantics and the provenance required for the optional stat, with a blank line before tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Metadata comes from Node bigint stat for the actual path; callers can reuse precisely that native observation.
+     * @evidence contracts/performance.md#efficient-algorithms Map membership/set processes path keys; an unseen dependency without supplied metadata performs native stat/path lookup, then formats bigint fields. Native/key/numeric-text costs remain despite expected constant-time map indexing; supplied stat provenance is a caller premise.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated dependencies reuse the first signature and a caller's pre-read stat avoids repeating the equivalent syscall.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the witness map and its release; this operation adds one dependency without retaining another handle.
+     */
+    function add(witness, file, observed) {
+        if (witness === undefined || witness.has(file))
+            return;
+        witness.set(file, signature(file, observed));
+    }
+    PluginBuildEnvironmentWitness.add = add;
+    /**
+     * Witness a link itself before following it, including a missing target.
+     * Target metadata remains a separate observation through add.
+     *
+     * @evidence contracts/common.md#principled-implementation First-observation retention records native link metadata and target spelling separately from followed-target state. A successfully observed changed spelling changes this witness; unavailable lstat/readlink yields the helper's missing marker, which does not distinguish every failure cause.
+     * @evidence contracts/common.md#clear-and-simple-design Qualified keys keep link and target observations in the same caller-owned record, and holds dispatches to their respective native observations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A link's existence does not certify its target; native lstat and readlink preserve missing-target and retargeting distinctions without replacing filesystem operations.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes the link observation from add's target observation and states pre-follow timing.
+     * @evidence contracts/portability.md#os-neutral-implementation Node lstat and readlink inspect the native link or junction and its target spelling without an OS-based case or existence assumption.
+     * @evidence contracts/performance.md#efficient-algorithms Qualified-key construction/map indexing process path text; an unseen link uses native lstat/readlink and serializes bigint/target spelling. Native component/link lookup and all numeric/path/target bytes contribute work; no file content is read.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated link observations retain their first signature in this record rather than replacing evidence of a race.
+     *
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns the record; the operation retains no native handle.
+     */
+    function addLink(witness, file) {
+        const key = LINK_PREFIX + file;
+        if (witness === undefined || witness.has(key))
+            return;
+        witness.set(key, linkSignature(file));
+    }
+    PluginBuildEnvironmentWitness.addLink = addLink;
+    /**
+     * Retain an ambient native lookup variable at the exact lookup that used it.
+     * A different repeated observation refuses the reading. A captured transient
+     * value can reveal an ABA interval hidden by initial/final snapshots; a value
+     * never observed here is not detected by this record.
+     *
+     * @evidence contracts/common.md#principled-implementation First observed native lookup inputs remain paired with the digest and are compared with current host inputs before publication and reuse.
+     * @evidence contracts/common.md#clear-and-simple-design Disjoint environment keys share the existing caller-owned witness and validation boundary.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual observed variables qualify native selection without writing the parent's shared environment or inventing a tool identity.
+     * @evidence contracts/common.md#meaningful-documentation The prose distinguishes lookup-time authority from request and final snapshots.
+     * @evidence contracts/portability.md#os-neutral-implementation Native executable selection supplies the variable value it observed; holds uses lowercase-name matching on Windows and direct name lookup elsewhere, without writing host variables.
+     * @evidence contracts/performance.md#efficient-algorithms Name qualification/map indexing and JSON serialization process supplied name/value bytes on every observation, including repeats. Equal observations keep the first value; a different value sets the refusal sentinel, with no native subprocess or file-content read here.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated equal observations reuse the first signature; a different observation refuses the complete reading.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns and releases the record; this operation retains no process or environment handle.
+     */
+    function addEnvironment(witness, name, value) {
+        if (witness === undefined)
+            return;
+        const key = ENVIRONMENT_PREFIX + name;
+        const recorded = JSON.stringify([value ?? null]);
+        if (witness.has(key) && witness.get(key) !== recorded)
+            witness.set(key, UNWITNESSABLE);
+        else if (!witness.has(key))
+            witness.set(key, recorded);
+    }
+    PluginBuildEnvironmentWitness.addEnvironment = addEnvironment;
+    /**
+     * Record `file` as a path whose state could not be witnessed, so the record
+     * never holds and nothing kept under it is reused.
+     *
+     * @evidence contracts/common.md#principled-implementation The refusal sentinel cannot equal a metadata signature, so an incomplete environment never passes holds.
+     * @evidence contracts/common.md#clear-and-simple-design One sentinel uses the existing record format rather than adding a parallel error collection.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An unreadable dependency refuses reuse rather than substituting an assumed valid reading.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the effect on every consumer of the record, not merely the stored value.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This operation stores a sentinel and performs no native path lookup.
+     * @evidence contracts/performance.md#efficient-algorithms An optional supplied-map write processes the key and replaces its value with a fixed sentinel; it performs no native observation, content scan or separate dependency traversal.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work It invalidates a witness rather than sharing a computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Record lifetime belongs to the caller.
+     */
+    function refuse(witness, file) {
+        witness?.set(file, UNWITNESSABLE);
+    }
+    PluginBuildEnvironmentWitness.refuse = refuse;
+    /**
+     * Whether every native path and ambient variable still matches its
+     * observation. The existing private opt-in trace retains the first actual
+     * mismatch without repeating its lookup or changing the refusal. An optional
+     * observation label separates preparation and build epochs in that trace; it
+     * does not change validation or authorize publication.
+     *
+     * @evidence contracts/common.md#principled-implementation Universal comparison requires every dependency to match its pre-read signature and immediately rejects a refused or changed path.
+     * @evidence contracts/common.md#clear-and-simple-design Validation uses the same signature helper as capture, keeping identity and timestamp policy in one place.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts All dependencies are inspected; a quiet parent or unchanged VERSION cannot stand in for nested SDK inputs.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the universal unchanged-metadata condition and tags remain separated from it.
+     * @evidence contracts/portability.md#os-neutral-implementation Validation reads actual Node metadata using the same link-following semantics as capture.
+     * @evidence contracts/performance.md#efficient-algorithms Validation iterates dependencies until mismatch and performs native stat/link queries or ambient-variable serialization. Windows environment matching enumerates names and lowercases text per witnessed variable, so P alone does not bound that work. Native path/link/name/value/numeric bytes contribute cost; file content is not read and unavailable native observations share the helper's missing marker. An enabled private trace serializes the first mismatch's already-computed text through its existing bounded sink.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call must establish current validity; caching that answer would conceal external changes.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Validation retains no handles or additional historical state.
+     */
+    function holds(witness, observation) {
+        for (const [file, recorded] of witness) {
+            const current = file.startsWith(ENVIRONMENT_PREFIX)
+                ? environmentSignature(file.slice(ENVIRONMENT_PREFIX.length))
+                : file.startsWith(LINK_PREFIX)
+                    ? linkSignature(file.slice(LINK_PREFIX.length))
+                    : signature(file);
+            if (current !== recorded) {
+                E2ETrace_1.E2ETrace.capabilityResolution("plugin-build-environment-witness-mismatch", {
+                    key: file,
+                    recorded,
+                    current,
+                    refused: recorded === UNWITNESSABLE,
+                    observation,
+                });
+                return false;
+            }
+        }
+        return true;
+    }
+    PluginBuildEnvironmentWitness.holds = holds;
+    /** A recorded state no signature equals. */
+    const UNWITNESSABLE = "unwitnessable";
+    /** NUL cannot occur in a native pathname, so this qualification is disjoint. */
+    const LINK_PREFIX = "\0link:";
+    const ENVIRONMENT_PREFIX = "\0environment:";
+    function environmentSignature(name) {
+        const actualName = process.platform === "win32"
+            ? Object.keys(process.env).find((key) => key.toLowerCase() === name.toLowerCase())
+            : name;
+        return JSON.stringify([
+            actualName === undefined ? null : (process.env[actualName] ?? null),
+        ]);
+    }
+    /** Observe the link before its target, under the same metadata premise. */
+    function linkSignature(file) {
+        try {
+            const stat = node_fs_1.default.lstatSync(file, { bigint: true });
+            return JSON.stringify([
+                stat.dev.toString(),
+                stat.ino.toString(),
+                stat.size.toString(),
+                stat.mtimeNs.toString(),
+                stat.ctimeNs.toString(),
+                node_fs_1.default.readlinkSync(file),
+            ]);
+        }
+        catch {
+            return "missing";
+        }
+    }
+    /**
+     * The metadata a replacement moves: identity, size, and modification and
+     * change times, following links; `missing` when the native stat is
+     * unavailable.
+     */
+    function signature(file, observed) {
+        try {
+            const stat = observed ?? node_fs_1.default.statSync(file, { bigint: true });
+            return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+        }
+        catch {
+            return "missing";
+        }
+    }
+})(PluginBuildEnvironmentWitness || (exports.PluginBuildEnvironmentWitness = PluginBuildEnvironmentWitness = {}));
+//# sourceMappingURL=PluginBuildEnvironmentWitness.js.map

package/lib/plugin/internal/source/PluginBuildEnvironmentWitness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildEnvironmentWitness.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildEnvironmentWitness.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AAEzB,yDAAsD;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,IAAiB,6BAA6B,CAsM7C;AAtMD,WAAiB,6BAA6B;IAkB5C;;;;;;;;;;;;;OAaG;IACH,SAAgB,GAAG,CACjB,OAA2B,EAC3B,IAAY,EACZ,QAAyB;QAEzB,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QACvD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC/C,CAAC;IAPe,8BAAA,GAAG,MAOlB,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,OAAO,CAAC,OAA2B,EAAE,IAAY;QAC/D,MAAM,GAAG,GAAG,WAAW,GAAG,IAAI,CAAC;QAC/B,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QACtD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,CAAC;IAJe,8BAAA,OAAO,UAItB,CAAA;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAgB,cAAc,CAC5B,OAA2B,EAC3B,IAAY,EACZ,KAAyB;QAEzB,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO;QAClC,MAAM,GAAG,GAAG,kBAAkB,GAAG,IAAI,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC;QACjD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ;YACnD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;aAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACzD,CAAC;IAXe,8BAAA,cAAc,iBAW7B,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,MAAM,CAAC,OAA2B,EAAE,IAAY;QAC9D,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACpC,CAAC;IAFe,8BAAA,MAAM,SAErB,CAAA;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,SAAgB,KAAK,CAAC,OAAe,EAAE,WAAoB;QACzD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC;gBACjD,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;gBAC7D,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;oBAC5B,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;oBAC/C,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACtB,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACzB,mBAAQ,CAAC,oBAAoB,CAC3B,2CAA2C,EAC3C;oBACE,GAAG,EAAE,IAAI;oBACT,QAAQ;oBACR,OAAO;oBACP,OAAO,EAAE,QAAQ,KAAK,aAAa;oBACnC,WAAW;iBACZ,CACF,CAAC;gBACF,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAtBe,8BAAA,KAAK,QAsBpB,CAAA;IAED,4CAA4C;IAC5C,MAAM,aAAa,GAAG,eAAe,CAAC;IACtC,gFAAgF;IAChF,MAAM,WAAW,GAAG,SAAS,CAAC;IAC9B,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;IAE5C,SAAS,oBAAoB,CAAC,IAAY;QACxC,MAAM,UAAU,GACd,OAAO,CAAC,QAAQ,KAAK,OAAO;YAC1B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAC3B,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAClD;YACH,CAAC,CAAC,IAAI,CAAC;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;SACpE,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAC3E,SAAS,aAAa,CAAC,IAAY;QACjC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,iBAAE,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,OAAO,IAAI,CAAC,SAAS,CAAC;gBACpB,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE;gBACnB,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE;gBACnB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;gBACpB,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACvB,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACvB,iBAAE,CAAC,YAAY,CAAC,IAAI,CAAC;aACtB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS,SAAS,CAAC,IAAY,EAAE,QAAyB;QACxD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,QAAQ,IAAI,iBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CACrE,GAAG,CACJ,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC,EAtMgB,6BAA6B,aAA7B,6BAA6B,GAA7B,6BAA6B,QAsM7C"}

package/lib/plugin/internal/source/PluginBuildLockFence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Opaque identity of one observed lock generation.
+ *
+ * Returned by {@link inspectPluginBuildLock} and consumed by
+ * {@link reclaimPluginBuildLock}, carrying the generation and protocol the
+ * waiter observed. A v3 observer is recorded inside that generation so its
+ * tombstone remains while the observing process can still use the fence,
+ * preventing a stale fence from retiring a successor. Legacy fences cannot
+ * provide that guarantee against old executables that delete their lock path.
+ *
+ * @evidence contracts/common.md#principled-implementation Protocol and generation distinguish a captured legacy fence from an observer-protected v3 retirement identity.
+ * @evidence contracts/common.md#clear-and-simple-design The token contains no mutable pathname observation; inspection owns registration and reclamation owns retirement.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fence retains the observed generation rather than substituting a successor's current identity after a delay.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify producer, consumer and observer lifetime; member comments explain protocol and generation separately from tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Tokens use protocol discriminants and hexadecimal identity; callers derive native paths through the protocol adapter rather than embedding filesystem syntax in the token.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type PluginBuildLockFence = {
+    /** Which lock protocol held the observed generation. */
+    protocol: "legacy" | "v3";
+    /** The 128-bit hex id of the observed generation. */
+    generation: string;
+};

package/lib/plugin/internal/source/PluginBuildLockFence.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginBuildLockFence.js.map

package/lib/plugin/internal/source/PluginBuildLockFence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockFence.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockFence.ts"],"names":[],"mappings":""}

package/lib/plugin/internal/source/PluginBuildLockLease.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ownership token returned only to the process that acquired the v3 lock.
+ *
+ * Produced by {@link acquirePluginBuildLock} and consumed by
+ * {@link releasePluginBuildLock}. Release retires this generation and no other,
+ * so a holder whose lock was reclaimed cannot release its successor. The token
+ * remains valid only in its original coordination namespace.
+ *
+ * Its completion nonce authorizes the acquiring process to record actual task
+ * completion after its payload callback has ended, including an already retired
+ * generation. Expiring a wait budget does not end that callback.
+ *
+ * @evidence contracts/common.md#principled-implementation The protocol and random generation identify the holder's retirement destination; a separate nonce qualifies its actual task-completion witness, without representing legacy or old v2 acquisition.
+ * @evidence contracts/common.md#clear-and-simple-design The token carries ownership identity while acquisition, finally release and tombstone collection own the lifecycle decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Release uses the recorded generation rather than deleting whichever holder currently occupies a shared pathname.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names producer, consumer, protocol and namespace lifetime; properties have separate useful comments without checklist tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The generation is protocol spelling independent of native separators; the v3 discriminant isolates the filesystem namespace from old v2 reclaimers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type PluginBuildLockLease = {
+    /** Always "v3": acquisition never grants an older protocol's ownership. */
+    protocol: "v3";
+    /** The 128-bit hex id of the held generation. */
+    generation: string;
+    /** The acquiring task's 128-bit completion publication capability. */
+    completionNonce: string;
+};

package/lib/plugin/internal/source/PluginBuildLockLease.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginBuildLockLease.js.map

package/lib/plugin/internal/source/PluginBuildLockLease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockLease.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockLease.ts"],"names":[],"mappings":""}

package/lib/plugin/internal/source/PluginBuildLockObservation.d.ts

@@ -0,0 +1,42 @@
+import type { PluginBuildLockFence } from "./PluginBuildLockFence";
+/**
+ * One observation of a plugin build lock directory's state.
+ *
+ * - `active`: the lock exists and its owner is alive (or cannot be disproven:
+ *   another host or unconfirmed owner metadata). Keep waiting within the
+ *   caller's admission budget.
+ * - `abandoned`: the lock has a qualified, provably absent same-host owner. The
+ *   returned fence permits an attempt to retire that observed generation.
+ * - `released`: observation found a released or unavailable handoff and carries
+ *   no fence. V3 coordination roots persist independently of `current`; these
+ *   sequential observations do not guarantee that no successor exists by
+ *   return. This is never an infinitely old abandoned lock.
+ *
+ * A v3 active or abandoned result records the observer before returning its
+ * fence. Reclamation is still a separate action that may lose a retirement
+ * race.
+ *
+ * @evidence contracts/common.md#principled-implementation The discriminated union requires a fence for occupied generations and omits it for absence, separating liveness labels from retirement authority.
+ * @evidence contracts/common.md#clear-and-simple-design Each state carries only its relevant diagnostic description and token; observation does not itself retire ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Released is represented explicitly rather than an infinite age that could manufacture abandonment after a normal handoff.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains all three states, persistent-root absence and the observation/reclamation distinction before its tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The states represent filesystem observations independently of OS errno wording; occupied states carry the protocol distinction needed for native retirement.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export type PluginBuildLockObservation = {
+    state: "active";
+    /** The diagnostic label of the observed holder. */
+    owner: string;
+    /** The captured identity; a timeout alone cannot authorize retirement. */
+    fence: PluginBuildLockFence;
+} | {
+    state: "abandoned";
+    /** The qualified process-absence grounds for reclamation. */
+    reason: string;
+    /** The generation whose retirement may be attempted. */
+    fence: PluginBuildLockFence;
+} | {
+    state: "released";
+};

package/lib/plugin/internal/source/PluginBuildLockObservation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PluginBuildLockObservation.js.map

package/lib/plugin/internal/source/PluginBuildLockObservation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginBuildLockObservation.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/PluginBuildLockObservation.ts"],"names":[],"mappings":""}

package/lib/plugin/internal/source/PluginBuildLockOwner.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The holder a plugin build lock generation records, and what can be proven
+ * about it: a generation's `owner.json` names the process and host that took
+ * it. Inspecting a held generation and collecting a retired one's tombstone
+ * both decide from this one record.
+ *
+ * New holders also record generation and completion identity. Their qualified
+ * marker proves that a payload task ended, even if its process remains alive;
+ * it does not prove that outstanding leases or observer fences are unusable.
+ *
+ * @evidence contracts/common.md#principled-implementation Host and process identity are read from the generation's own record; only a local absence probe can establish that the recorded process is gone.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace owns holder representation, parsing, local liveness, qualified task completion and diagnostic labels shared by observation and cache collection.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native APIs supply process and host identity; an ambiguous probe failure is not replaced with an assumption that the owner died.
+ * @evidence contracts/common.md#meaningful-documentation Native comments describe record absence, local versus remote identity, reused PIDs and conservative failure handling, with separated member documentation and tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Hostname and PID describe the recorded native process boundary; Node's host and signal-zero abstractions provide the local probe without shell or platform-specific commands.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups owner operations; its parsing, probing and formatting functions own their computation strategies.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace retains no result or in-flight producer across consumers.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace declaration acquires no handle, task or ownership record; callers own record publication and collection.
+ */
+export declare namespace PluginBuildLockOwner {
+    /**
+     * A generation's recorded holder. PID identity is meaningful only on its
+     * named host; startedAt is descriptive metadata, not a PID-reuse proof.
+     *
+     * Build holders may include generation and completion identity. Older owners
+     * and observer records omit them, so those records cannot prove task
+     * completion.
+     *
+     * @evidence contracts/common.md#principled-implementation Hostname and a positive PID express local process identity; optional time, generation and completion nonce preserve newer holder metadata without requiring it in older or observer records.
+     * @evidence contracts/common.md#clear-and-simple-design The record carries process facts without embedding liveness or generation-retirement policy in the data container.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No timestamp or numeric PID is treated as an authoritative cross-host process incarnation token.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains host-local PID meaning and timestamp limitations; member comments remain separate from checklist tags.
+     * @evidence contracts/portability.md#os-neutral-implementation The hostname scopes the native PID, and the optional ISO timestamp is independent of platform process-table formatting.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms The record represents values and chooses no computation strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The record itself coordinates no shared work or cached liveness result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record container does not acquire or release its consumers' filesystem tokens.
+     */
+    interface IRecord {
+        /** The holder's host name. */
+        hostname: string;
+        /** The holder's process id on that host. */
+        pid: number;
+        /** When the holder took the generation, when recorded. */
+        startedAt?: string;
+        /** The build generation, absent from observer and older owner records. */
+        generation?: string;
+        /** Nonce qualifying actual task completion, absent from older records. */
+        completionNonce?: string;
+    }
+    /**
+     * The holder recorded in a generation directory, or `null` when the record is
+     * absent or malformed. Read failures also return null; absence of a usable
+     * record does not prove the recorded process dead.
+     *
+     * Optional generation and completion nonce fields require valid protocol
+     * spelling. Missing or invalid fields remain absent without invalidating an
+     * otherwise usable process identity.
+     *
+     * @evidence contracts/common.md#principled-implementation JSON fields are checked before construction; optional generation and completion nonce require the protocol's 128-bit spelling, while absent older metadata remains unconfirmed.
+     * @evidence contracts/common.md#clear-and-simple-design Parsing returns one nullable record and leaves age-based observation and process liveness to their respective owners.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed or unreadable metadata is not repaired into a fabricated owner or used as proof of process death.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes unusable records from dead processes and documents the nullable read result before its tags.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join and Node filesystem reads use native paths; read errors remain an inconclusive record observation on every platform.
+     * @evidence contracts/performance.md#efficient-algorithms One owner file is read and parsed, with time and temporary space proportional to its JSON bytes rather than a directory or process-table scan.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Owner metadata can change as the current pathname changes generation, so a fresh filesystem observation cannot reuse an earlier parse without a validated identity.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The synchronous read returns a value and retains no descriptor, background task or cache population.
+     */
+    function read(generationDir: string): IRecord | null;
+    /**
+     * Whether this exact generation records the end of its holder's payload task.
+     * A live process can finish a task; timeout retirement cannot prove that end.
+     * Missing, malformed or unreadable metadata leaves completion unconfirmed.
+     * This proof permits payload eviction, never removal of a live fence holder's
+     * tombstone reservation.
+     *
+     * @evidence contracts/common.md#principled-implementation The generation file and owner generation must match the requested identity and its completion nonce must match the atomically published marker; a timeout or another generation cannot supply that proof.
+     * @evidence contracts/common.md#clear-and-simple-design One conservative reader distinguishes payload-task completion from process absence, leaving eviction and tombstone lifetimes to their respective owners.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Elapsed time, retired ownership and a live-looking PID are not substituted for a release-owned completion witness.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs define exact-generation qualification, inconclusive failures and the separate payload versus fence lifetime before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node path and UTF-8 file reads inspect protocol bytes through native filesystem abstractions without shell or platform-specific process state.
+     * @evidence contracts/performance.md#efficient-algorithms Owner, generation and completion records are read directly; costs grow with their bytes, without enumerating unrelated generations.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A mutable coordination pathname requires a fresh qualified observation rather than a cached completion boolean.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The reader retains no handle or task; release publishes the witness and the collector owns its directory lifetime.
+     */
+    function taskComplete(generationDir: string, generation: string): boolean;
+    /**
+     * Whether the holder provably can no longer act: it ran on this host and no
+     * process with its id exists. A holder on another host, or one whose id is
+     * alive (possibly reused), is not proven gone.
+     *
+     * Only ESRCH proves absence. Permission errors, invalid probe arguments and
+     * other failures remain inconclusive and must not authorize reclamation.
+     *
+     * @evidence contracts/common.md#principled-implementation Signal zero checks existence without terminating the process; same-host ESRCH establishes absence, while success or any other error does not.
+     * @evidence contracts/common.md#clear-and-simple-design Host comparison and one native probe express the proof boundary directly, without a second process-discovery mechanism.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unexpected probe failures are not converted to a dead-owner special case or hidden behind retries.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish PID reuse, remote owners and each inconclusive failure class before the tags.
+     * @evidence contracts/portability.md#os-neutral-implementation os.hostname and Node's platform-independent signal-zero probe preserve native host scope; only the explicit no-such-process code authorizes absence.
+     * @evidence contracts/performance.md#efficient-algorithms A hostname comparison and one process-existence syscall avoid enumerating native processes; string comparison costs grow only with hostname length.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Liveness is a time-sensitive observation; a previously absent or present PID cannot be cached as proof for a later reclamation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The query owns no retained handle or running task and returns only its immediate proof decision.
+     */
+    function gone(owner: IRecord): boolean;
+    /**
+     * A human description of the holder, for lock diagnostics. The timestamp is
+     * omitted when unavailable; this label does not establish liveness.
+     *
+     * @evidence contracts/common.md#principled-implementation Formatting the stored PID, hostname and optional timestamp gives users the identity metadata available without deriving unrecorded process facts.
+     * @evidence contracts/common.md#clear-and-simple-design One label formatter keeps presentation independent of owner parsing and process probing.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The label reports recorded values without fabricating a process state or platform-specific command output.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states diagnostic purpose, optional timestamp omission and the absence of a liveness claim before its tags.
+     *
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Formatting stored values is pure presentation and performs no native process or filesystem operation.
+     *
+     * @evidence contracts/performance.md#efficient-algorithms One optional suffix and one label concatenation cost time and space proportional to the supplied hostname and timestamp text.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The formatter does not coordinate completed or in-flight work across requests.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returning a string acquires no handle, task or retained cache population.
+     */
+    function describe(owner: IRecord): string;
+}