ttsc 0.30.4 → 0.31.0

package/lib/internal/SourceNativeRetirement.d.ts

@@ -0,0 +1,384 @@
+import fs from "node:fs";
+/**
+ * Preserve source-build resources until their native boundary has retired.
+ *
+ * Guards are published before command admission. Pending and uncertified
+ * boundaries protect inputs from cooperating collectors even after their Node
+ * owner disappears. Neither PID absence nor elapsed time grants reclamation.
+ * Older compiler versions do not implement these guards and cannot safely share
+ * quarantined roots. External deletion is outside this protocol.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact pre-admission guards protect inputs until the original native boundary certifies closure; PID absence and age never grant authority.
+ * @evidence contracts/common.md#clear-and-simple-design One protocol owns admission, deferred cleanup and collector checks; native containment remains with the command owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Durable pending records remain conservative when unknown diagnostics cannot be published.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states cooperative-version limits and the absence of disk-only recovery authority.
+ * @evidence contracts/portability.md#os-neutral-implementation Node realpath, lstat and argv-independent JSON paths represent actual filesystem roots; later namespace replacement remains outside the retained-handle premise.
+ * @evidence contracts/performance.md#efficient-algorithms Member operations own scans and publication costs; the namespace itself executes no algorithm.
+ * @evidence contracts/performance.md#reuse-equivalent-work Guards carry ownership, not reusable compiler results.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Unknown boundaries intentionally retain inputs without an age bound; losing the original closure capability requires operator-confirmed external closure.
+ */
+export declare namespace SourceNativeRetirement {
+    /**
+     * Original task capability retained for qualified recovery. Losing this
+     * object leaves durable guards and requires external closure confirmation;
+     * loading guard bytes does not manufacture native reclamation authority.
+     *
+     * @evidence contracts/common.md#principled-implementation Original task identity, resources, admitted boundaries and cleanup callbacks express separate ownership states.
+     * @evidence contracts/common.md#clear-and-simple-design Maps index roots and boundary tokens while the FIFO preserves normal finally order.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Disk metadata cannot construct this original task capability or certify process closure.
+     * @evidence contracts/common.md#meaningful-documentation Field prose explains original authority and the consequence of losing it.
+     * @evidence contracts/portability.md#os-neutral-implementation Resources contain observed physical native roots; command retirement authority is an in-memory capability.
+     * @evidence contracts/performance.md#efficient-algorithms This type declares state without executing an algorithm.
+     * @evidence contracts/performance.md#reuse-equivalent-work Task identity permits no equivalent-result sharing.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The type acquires no resources itself; begin, settle and recover own their lifetimes.
+     */
+    interface Scope {
+        /** Identity supplied by the original worker request owner. */
+        taskToken: string;
+        /** Currently registered physical roots and their retained input paths. */
+        resources: Map<string, Resource>;
+        /** Original native admission capabilities, never reconstructed from disk. */
+        boundaries: Map<string, Boundary>;
+        /** Original cleanup callbacks, in normal finally-unwinding order. */
+        deferred: Array<() => void>;
+        /**
+         * Optional task-local publication primitives for an explicit filesystem
+         * boundary oracle. Omitted tasks use Node's original synchronous APIs.
+         * Implementations must preserve exclusive-open and real descriptor
+         * meaning.
+         */
+        guardFileOperations?: Pick<typeof fs, "openSync" | "writeFileSync" | "closeSync" | "renameSync" | "rmSync">;
+    }
+    /**
+     * Allocate an empty task capability without acquiring a filesystem guard.
+     *
+     * @evidence contracts/common.md#principled-implementation A nonempty task token distinguishes the original admission owner and starts with no native commands.
+     * @evidence contracts/common.md#clear-and-simple-design Two maps and one FIFO separate registration, boundary state and deferred cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Allocation grants no native closure certificate from PID or elapsed time.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies allocation without filesystem acquisition.
+     * @evidence contracts/portability.md#os-neutral-implementation Allocation handles opaque identity and collections without native operations.
+     * @evidence contracts/performance.md#efficient-algorithms One object and three empty collections take constant initial space.
+     * @evidence contracts/performance.md#reuse-equivalent-work Each task receives distinct mutable ownership state rather than a shared result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns the returned capability; no filesystem or process handle is acquired.
+     */
+    function createScope(taskToken: string): Scope;
+    /**
+     * Install one synchronous task; promises do not extend its lexical lifetime.
+     *
+     * @evidence contracts/common.md#principled-implementation Finally restores the predecessor even when task work throws.
+     * @evidence contracts/common.md#clear-and-simple-design One lexical saved reference supports nested synchronous scopes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An asynchronously returned value cannot extend this synchronous authority implicitly.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the synchronous lifetime and promise limitation.
+     * @evidence contracts/portability.md#os-neutral-implementation Scope sequencing has no native path or process representation.
+     * @evidence contracts/performance.md#efficient-algorithms One reference save and restore surround delegated callback cost.
+     * @evidence contracts/performance.md#reuse-equivalent-work Every effectful callback runs independently; this operation caches no answer.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Restoration releases the global reference while the original caller retains its task capability.
+     */
+    function run<T>(scope: Scope, task: () => T): T;
+    /**
+     * Register inputs before their first native command. Additional paths merge
+     * with the same held generation; conflicting generation authority is refused.
+     * Ordinary synchronous callers acquire no new protocol state.
+     *
+     * @evidence contracts/common.md#principled-implementation Physical root identity and generation/nonce consistency bind additional paths to the same held resource.
+     * @evidence contracts/common.md#clear-and-simple-design A root-indexed map merges paths while retaining one generation capability.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Registration is opt-in and cannot silently substitute a conflicting generation.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains registration timing, merging and ordinary-call behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Native realpath resolves existing root aliases; retained path spellings use Node path resolution.
+     * @evidence contracts/performance.md#efficient-algorithms Merging scans existing and incoming path strings once through a Set; map lookup uses the physical root key.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated registration shares the same root entry only when supplied generation authority agrees.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Task resource entries persist until safe forget or scope reclamation; native guards snapshot registrations at admission.
+     */
+    function register(resource: {
+        /** Existing physical root where cooperating cleanup observes guards. */
+        fenceRoot: string;
+        /** Exact inputs retained and disclosed in terminal diagnostics. */
+        retainedPaths: readonly string[];
+        /** Held source-key or shared-cache lease generation, when applicable. */
+        generation?: string;
+        /** Original source-key task completion capability, when applicable. */
+        completionNonce?: string;
+    }): void;
+    /**
+     * Register an explicitly selected shared Go cache only in an owned task.
+     * Ordinary synchronous consumers retain their existing directory behavior.
+     * This adds lifetime protection, without claiming eviction ownership or
+     * restricting independent builders that share the cache.
+     *
+     * @evidence contracts/common.md#principled-implementation Scoped native work creates or resolves the selected Go root before registration so its eventual guard protects the same physical input directory.
+     * @evidence contracts/common.md#clear-and-simple-design One helper confines scoped-only directory materialization and registration; ordinary unmanaged callbacks keep their prior path.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Lifetime guard metadata does not convert a user cache into an evictable compiler-owned cache or serialize independent builds.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes lifetime protection, eviction ownership and unchanged ordinary synchronous behavior.
+     * @evidence contracts/portability.md#os-neutral-implementation Node recursive mkdir and delegated native realpath preserve existing physical aliases without choosing case policy from an OS name.
+     * @evidence contracts/performance.md#efficient-algorithms One directory creation observation and delegated root registration scale with path depth and retained path text.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Shared cache ownership permits concurrent builds but authorizes no compiler-result reuse in this helper.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources No process or persistent handle is acquired; the scope owns the root entry and each admitted boundary owns its guard until certified retirement.
+     */
+    function registerSharedRoot(root: string): void;
+    /**
+     * Forget a safely released registration, never another generation's inputs.
+     *
+     * @evidence contracts/common.md#principled-implementation Safe tasks remove only the matching registered generation.
+     * @evidence contracts/common.md#clear-and-simple-design The current scope and one physical root lookup keep ownership local.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unresolved native ownership prevents forgetting instead of treating cleanup as complete.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states safe release and exact-generation exclusion.
+     * @evidence contracts/portability.md#os-neutral-implementation Native realpath supplies the same physical root spelling used at registration.
+     * @evidence contracts/performance.md#efficient-algorithms One physical resolution and map lookup perform the removal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Removing ownership state does not reuse a computed build result.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Safe forgetting drops the scope entry; admitted boundaries retain their original resource snapshots.
+     */
+    function forget(fenceRoot: string, generation?: string): void;
+    /**
+     * Publish every input guard before the native owner may admit a command.
+     * Partial publication failure admits no native work and rolls back only this
+     * boundary's guards. A failed rollback remains a visible protected record. An
+     * unresolved earlier command closes further admission in the same task.
+     * Exclusive open registers ownership before any write or close can fail.
+     * Failed close/rollback preserves original errors and exact paths for the
+     * task owner even if a legacy resolver converts the result to unavailable.
+     *
+     * @evidence contracts/common.md#principled-implementation All registered guards are written before command admission; publication failure rolls back only files whose exclusive open actually succeeded, including partial writes; close/rollback errors remain original aggregate members.
+     * @evidence contracts/common.md#clear-and-simple-design One boundary snapshots registered resources and tracks its exact guard paths.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Publication refusal admits no command; rollback failure stays visible rather than claiming clean release.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains publication ordering and partial-failure effects.
+     * @evidence contracts/portability.md#os-neutral-implementation Native directory validation rejects guard links; an actual exclusive descriptor establishes creation ownership before writing, while EEXIST cannot grant deletion authority.
+     * @evidence contracts/performance.md#efficient-algorithms For R registered roots, publication writes R records whose bytes scale with retained path text.
+     * @evidence contracts/performance.md#reuse-equivalent-work Fresh boundary tokens prohibit accidental reuse of an effectful admission.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Each boundary owns one guard per root from exclusive open until certified settlement or successful pre-admission rollback; failed close/rollback is reported across legacy catches, and unknown descriptor closure is never claimed or blindly retried.
+     */
+    function begin(boundaryToken: string): void;
+    /**
+     * Accept the original boundary owner's classified outcome. A certified
+     * terminal outcome is immutable, so a surrounding catch cannot turn a joined
+     * command back into unknown. Unknown remains protected if diagnostic writes
+     * fail; the pre-admission pending guard already protects its inputs.
+     * Candidate close/removal failures retain their original errors and reach the
+     * owned task even when later resolver code catches the thrown outcome.
+     * Successful removal relinquishes that pathname immediately; only failed
+     * removals retain retry authority, and all roots are attempted before
+     * failure.
+     *
+     * @evidence contracts/common.md#principled-implementation Only the original boundary accepts a classified result; safe certificates cannot become unknown through a surrounding catch.
+     * @evidence contracts/common.md#clear-and-simple-design The state transition and exact guard-file list centralize completion and unknown publication.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An unknown diagnostic write failure retains the pre-admission guard instead of inferring native closure.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states immutable safe outcomes and failure-safe unknown protection.
+     * @evidence contracts/portability.md#os-neutral-implementation Node exclusive temporary writes and rename publish metadata; native I/O refusal is propagated.
+     * @evidence contracts/performance.md#efficient-algorithms Unknown publication visits registered guard files and serialized path bytes; certified cleanup scans each still-owned guard and failed candidate once before aggregating refusals.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated identical safe outcomes retry cleanup, while conflicting certificates are rejected.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Joined or never-started outcomes relinquish each successfully removed guard or candidate pathname and retain only failed removals for retry; original cleanup failures reach the owned task across legacy catches. Unknown retains guards and failed owned candidates until qualified recovery.
+     */
+    function settle(boundaryToken: string, retirement: "joined" | "not-started" | "unknown", reason?: string): void;
+    /**
+     * Run safe cleanup now or retain its original capability after unknown
+     * retirement. Deferred callbacks are not treated as completed cleanup. A
+     * cleanup refusal is recorded for the task owner before it is rethrown, so a
+     * surrounding discovery catch cannot turn resource loss into success.
+     *
+     * @evidence contracts/common.md#principled-implementation Cleanup executes only when all admitted boundaries certify safety; otherwise its original callback is retained. An immediate refusal remains the same thrown error and is recorded in the asynchronous task owner's failure ledger.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate chooses immediate execution or FIFO deferral.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Deferral is never reported as completed cleanup.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes retained authority from successful release.
+     * @evidence contracts/portability.md#os-neutral-implementation The callback owns native details; this operation sequences opaque cleanup capabilities.
+     * @evidence contracts/performance.md#efficient-algorithms One safety scan over task boundaries precedes constant-time append or delegated cleanup.
+     * @evidence contracts/performance.md#reuse-equivalent-work Effectful cleanup callbacks are not deduplicated by matching return values.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Deferred callbacks remain with the original scope until qualified recovery succeeds; unknown has no age-based eviction.
+     */
+    function release(cleanup: () => void): void;
+    /**
+     * Release one destructible resource using its observed registration identity.
+     *
+     * Capture the original scope, physical key and registration while the root
+     * still exists. Cleanup can then remove that root without another realpath.
+     * Only successful cleanup drops the exact captured registration; a failed
+     * cleanup or a replacement registration remains owned. Unknown boundaries
+     * defer the same callback and identity through the original release protocol.
+     *
+     * The optional task failure distinguishes an earlier thrown undefined from
+     * no earlier failure. It is combined with a cleanup refusal, never rethrown
+     * after successful cleanup or deferred recovery. Ordinary unscoped callers
+     * perform cleanup without observing or inventing a registration.
+     *
+     * Enabled private tracing observes the original callback's execution, not
+     * its deferral. Scalar own error properties are read without invoking
+     * getters; reflection or sink failures leave the original outcome intact.
+     * Synchronous trace writes can change scheduling and prove only that run.
+     *
+     * @evidence contracts/common.md#principled-implementation Physical identity and the exact resource object are captured before destruction; only successful cleanup removes that identical registration from the original scope, while failure and replacement retain ownership.
+     * @evidence contracts/common.md#clear-and-simple-design One operation combines destructive cleanup with registration release, using the existing release/recover protocol instead of making each caller order physical lookup around removal.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing scoped root fails its real observation without guessing an identity or weakening forget; ordinary unscoped calls acquire no protocol state, and original task/cleanup errors remain separate aggregate members when both fail.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain capture timing, replacement and failure retention, unknown deferral, thrown undefined, successful recovery and passive trace limits; they do not claim an atomic namespace or retained directory handle.
+     * @evidence contracts/portability.md#os-neutral-implementation Native realpath observes aliases before destruction and the captured map key avoids resolving a removed path; later namespace replacement remains outside the caller's ownership premise.
+     * @evidence contracts/performance.md#efficient-algorithms Scoped capture performs one native physical lookup and map observation before the existing boundary safety scan; cleanup costs are delegated and the final identity comparison/map removal does not enumerate resources. Enabled tracing alone allocates an observer, projects five error properties and visits the scope's B boundaries, with synchronous encoding and IO proportional to their recorded text.
+     * @evidence contracts/performance.md#reuse-equivalent-work The captured object proves only this release's original registration, never reusable compiler results; a reentrant replacement is retained rather than treated as equivalent ownership.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Failed cleanup retains its registration; unknown boundaries retain the original callback through FIFO recovery, whose failed callback remains queued. Immediate cleanup failure follows release's reporting contract without creating a new automatic retry, and successful cleanup drops only its original entry. An enabled observer shares that callback's lifetime; bounded trace storage has no resource-release authority.
+     */
+    function releaseResource(fenceRoot: string, cleanup: () => void, taskFailure?: {
+        error: unknown;
+    }): void;
+    /**
+     * Observe the installed task's native closure authority without throwing.
+     *
+     * @evidence contracts/common.md#principled-implementation Every boundary must be joined or never started before cleanup is safe.
+     * @evidence contracts/common.md#clear-and-simple-design One task-local predicate serves every release consumer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No PID, clock or unavailable plugin result supplies closure proof.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies a nonthrowing authority observation.
+     * @evidence contracts/portability.md#os-neutral-implementation The predicate inspects discriminants without native operations.
+     * @evidence contracts/performance.md#efficient-algorithms The scan stops at the first unresolved boundary and takes at most the task boundary count.
+     * @evidence contracts/performance.md#reuse-equivalent-work Mutable boundary state is inspected anew, not cached.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Observation allocates transient iteration state and acquires no resource.
+     */
+    function canRelease(): boolean;
+    /**
+     * Retry deferred cleanup only with the original task and boundary capability.
+     * The caller must supply actual qualified native closure, not a timer or PID
+     * observation. No disk-only recovery capability is created by this API.
+     *
+     * @evidence contracts/common.md#principled-implementation Only the original scope and exact boundary token can apply qualified closure and retry original cleanup. Failed callbacks remain at the FIFO head, preserve their original thrown error and report it to the current asynchronous task owner before propagation.
+     * @evidence contracts/common.md#clear-and-simple-design Certified settlement precedes FIFO cleanup, and a throwing callback remains at the head for retry.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Timers and PID observations cannot manufacture recovery authority; losing it leaves terminal quarantine.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states caller proof requirements and excludes disk-only recovery.
+     * @evidence contracts/portability.md#os-neutral-implementation Settlement and callbacks own native filesystem effects; this coordinator preserves their actual failures.
+     * @evidence contracts/performance.md#efficient-algorithms Settlement scans every still-owned guard and candidate before reporting cleanup failures; deferred callbacks run in FIFO order until the first callback failure.
+     * @evidence contracts/performance.md#reuse-equivalent-work A previously certified identical outcome can retry failed cleanup without rerunning successful callbacks.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Successful callbacks are removed once; failures retain the original capability for another qualified retry.
+     */
+    function recover(scope: Scope, boundaryToken: string, retirement: "joined" | "not-started"): void;
+    /**
+     * Pending, malformed and unknown guards all prohibit collector reclamation.
+     * An exact generation query ignores valid guards for different generations.
+     *
+     * @evidence contracts/common.md#principled-implementation Any pending, unknown or malformed guard prevents reclamation.
+     * @evidence contracts/common.md#clear-and-simple-design One shared reader defines conservative protection for all collectors.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid metadata is protected rather than interpreted as absence.
+     * @evidence contracts/common.md#meaningful-documentation Native prose names the protected states and collector purpose.
+     * @evidence contracts/portability.md#os-neutral-implementation Guard reading validates native directory identity and rejects links.
+     * @evidence contracts/performance.md#efficient-algorithms Reading costs the guard-entry count and total metadata bytes; no PID queries are needed.
+     * @evidence contracts/performance.md#reuse-equivalent-work Mutable guard directories are observed for each reclamation decision.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The observation holds no persistent handle and acquires no ownership.
+     */
+    function isProtected(fenceRoot: string, generation?: string): boolean;
+    /**
+     * Snapshot protected generations for one cooperative collector pass.
+     * Undefined protects every generation because metadata is malformed or an
+     * unleased shared input has no narrower generation. An empty set protects
+     * none. Eviction must still recheck root protection before deleting objects.
+     *
+     * @evidence contracts/common.md#principled-implementation Valid guards select their exact generations; malformed or unleased records conservatively protect all generations rather than authorizing deletion.
+     * @evidence contracts/common.md#clear-and-simple-design A set-or-universal result separates one metadata scan from the collector's per-record membership checks.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The snapshot supplies no native closure proof and cannot replace the final root guard check before object deletion.
+     * @evidence contracts/common.md#meaningful-documentation Native prose specifies universal, empty and exact-generation meanings and the snapshot's deletion limitation.
+     * @evidence contracts/portability.md#os-neutral-implementation The shared native guard reader validates directory identity and JSON records before generations enter the set.
+     * @evidence contracts/performance.md#efficient-algorithms One scan costs guard count and metadata bytes; subsequent record membership avoids rescanning G guards for every one of L lease records.
+     * @evidence contracts/performance.md#reuse-equivalent-work One collector pass shares this observed guard snapshot; later passes and final object-eviction admission make fresh native observations.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The returned set retains at most one token per observed guarded generation and holds no native handle; the collector owns this transient snapshot.
+     */
+    function protectedGenerations(fenceRoot: string): ReadonlySet<string> | undefined;
+    /**
+     * Refuse unknown or malformed exclusive-key ownership. Pending guards remain
+     * non-admitting wait states; callers must separately avoid acquisition and
+     * binary adoption while isProtected remains true.
+     *
+     * @evidence contracts/common.md#principled-implementation Unknown or malformed exclusive-key ownership refuses admission; pending guards permit only the existing bounded waiter, whose acquisition and binary adoption remain blocked separately.
+     * @evidence contracts/common.md#clear-and-simple-design Admission policy is separate from shared-cache collector protection.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared Go cache builds do not invoke this exclusive-key check; their separate leases remain concurrent.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies exclusive admission and its quarantine diagnostic.
+     * @evidence contracts/portability.md#os-neutral-implementation Guard paths and retained native paths are reported using Node filesystem spellings.
+     * @evidence contracts/performance.md#efficient-algorithms A guard-directory scan and metadata reads precede the first refusal.
+     * @evidence contracts/performance.md#reuse-equivalent-work Fresh admission rechecks mutable metadata rather than reusing a prior availability observation.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The check acquires no ownership and leaves retained guards untouched.
+     */
+    function assertAvailable(fenceRoot: string): void;
+    /**
+     * Explain retained input ownership in a bounded wait's failure diagnostic.
+     * This reports observed guard bytes and grants no process-closure authority.
+     *
+     * @evidence contracts/common.md#principled-implementation The first observed guard supplies its state, original reason and exact retained paths without inferring lifetime from PID or elapsed time.
+     * @evidence contracts/common.md#clear-and-simple-design One optional diagnostic lets bounded waiters preserve the same metadata interpretation as collector and admission checks.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Pending diagnostic publication does not manufacture a safe outcome or make a timeout reclaim inputs.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the reporting purpose and explicitly excludes closure authority.
+     * @evidence contracts/portability.md#os-neutral-implementation The shared native reader validates guard directories; JSON retains actual path spellings in the diagnostic.
+     * @evidence contracts/performance.md#efficient-algorithms One guard scan and path-byte formatting occur on diagnostic demand, outside successful waiter polls.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable guard diagnostics are observed anew at the failure boundary rather than cached across transitions.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The returned string holds no process or directory capability; guard and input retention remain unchanged.
+     */
+    function describeProtection(fenceRoot: string): string | undefined;
+    /**
+     * Refuse ownership completion or stealing while any native guard remains.
+     *
+     * @evidence contracts/common.md#principled-implementation Any relevant guard prohibits completion or stealing; exact differing generations do not block their independent lease release.
+     * @evidence contracts/common.md#clear-and-simple-design One generation filter serves key retirement and shared Go record cleanup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed metadata cannot authorize generation-based bypass.
+     * @evidence contracts/common.md#meaningful-documentation Native prose describes completion and stealing refusal.
+     * @evidence contracts/portability.md#os-neutral-implementation The shared reader validates native guard directories and preserves I/O failures.
+     * @evidence contracts/performance.md#efficient-algorithms The check scans guard entries and metadata until a relevant protection is found.
+     * @evidence contracts/performance.md#reuse-equivalent-work Reclamation authority is observed anew rather than cached across filesystem mutations.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Refusal leaves the original resources and guards owned; the check holds no persistent handle.
+     */
+    function assertReleasable(fenceRoot: string, generation?: string): void;
+    /**
+     * Refuse recursive clean when a selected physical tree or its ancestors
+     * contain a guard. Terminal links are not followed. Scans acquire no held
+     * directory identity; callers retain the existing deletion-race premise.
+     *
+     * @evidence contracts/common.md#principled-implementation A whole-tree and ancestor check prevents recursive deletion of guarded inputs while terminal links remain unlinkable.
+     * @evidence contracts/common.md#clear-and-simple-design An iterative directory stack and ancestor walk separate descendant guards from enclosing ownership.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Links are not traversed and unknown guards cannot be treated as safe deletion targets.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states terminal-link behavior and the existing deletion-race limitation.
+     * @evidence contracts/portability.md#os-neutral-implementation Node lstat distinguishes actual terminal links; callers supply physically pinned ancestor paths.
+     * @evidence contracts/performance.md#efficient-algorithms The scan costs visited directories and guard metadata bytes; full traversal is necessary because guards may exist in any selected descendant.
+     * @evidence contracts/performance.md#reuse-equivalent-work Each clean transaction observes mutable guards; no cross-clean index supplies stale authority.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Only path strings and a directory stack are retained during the call; no held directory identity prevents later replacement.
+     */
+    function assertCleanable(target: string): void;
+}
+/**
+ * A registered physical input root and its optional exact source/lease
+ * generation.
+ *
+ * Optional generation and nonce preserve existing owner authority while path
+ * lists explain retained inputs. One resource combines its root, diagnostic
+ * input paths and exact generation identity. A root entry never equates PID
+ * identity with native closure. Field comments identify ownership and
+ * diagnostic purpose. Native paths are strings whose physical root was resolved
+ * at registration. This type executes no algorithm. The type grants no
+ * equivalent-result reuse. Runtime scope and boundary owners govern the
+ * represented resource lifetime.
+ */
+interface Resource {
+    /** Observed physical directory holding the guard. */
+    fenceRoot: string;
+    /** Exact input spellings disclosed by the original owner. */
+    retainedPaths: string[];
+    /** Held key or Go lease generation, absent for unleased shared roots. */
+    generation?: string;
+    /** Original key completion capability, absent for Go roots. */
+    completionNonce?: string;
+}
+/**
+ * One original command admission and its exact input-guard publication set.
+ *
+ * State separates unresolved admission from qualified joined or never-started
+ * closure. One boundary stores its token, immutable snapshot and owned guard
+ * paths. Unknown is represented explicitly instead of converted to successful
+ * cleanup. Native prose identifies per-command ownership and publication scope.
+ * File strings address native guard entries; classification comes from the
+ * native owner. This type declares state without scanning or publishing. A
+ * boundary identity cannot be reused for another admission. The task owner
+ * retains this record and its input snapshot until qualified completion or
+ * terminal quarantine.
+ */
+interface Boundary {
+    /** Original command admission token. */
+    token: string;
+    /** Explicit closure classification; unresolved states prohibit cleanup. */
+    state: "pending" | "joined" | "not-started" | "unknown";
+    /** Native owner diagnosis when closure is unknown. */
+    reason?: string;
+    /** Resource snapshot taken before native command admission. */
+    resources: Resource[];
+    /** Exclusively created guard entries still owned, including partial writes. */
+    files: string[];
+    /** Exclusively created update candidates whose removal has not succeeded. */
+    candidates: Set<string>;
+}
+export {};