ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,30 @@
+/**
+ * Internal controls for Go object-cache maintenance.
+ *
+ * Sizes are bytes and ages are milliseconds. Omitted controls use the owned
+ * Go-cache retention policy; the clock can be supplied by the invoking owner.
+ * Recent age selects a target-sized cohort with the collector's mtime
+ * allowance, rather than protecting every recent file. This type imposes no
+ * finite-number, range or ordering validation.
+ *
+ * @evidence contracts/common.md#principled-implementation Trigger and target sizes are separate from recent-file protection and the current clock, preserving the collector's independent decisions.
+ * @evidence contracts/common.md#clear-and-simple-design One option record supplies overrides to the existing selected-root collector; omitted fields retain its defaults rather than selecting a different maintenance implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied limits and time are ordinary inputs; production does not detect tests or fabricate object sizes to meet an expected result.
+ * @evidence contracts/common.md#meaningful-documentation Owning prose states byte/millisecond units, defaults, cohort scope and numeric-validation limits; members distinguish interval bypass from build-lease safety and recent-age eligibility from a retention guarantee.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export interface IGoBuildCachePruneOptions {
+    /** Ignore the interval marker; build-lease exclusion still applies. */
+    force?: boolean;
+    /** Size that triggers LRU pruning. */
+    maxBytes?: number;
+    /** Size to prune toward once the ceiling is crossed. */
+    targetBytes?: number;
+    /** Current wall-clock time in milliseconds since the Unix epoch. */
+    now?: number;
+    /** Recent-age threshold for cohort selection, with the mtime allowance added. */
+    protectedAgeMs?: number;
+}

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

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

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

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

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

@@ -0,0 +1,33 @@
+/**
+ * Internal controls for plugin-binary cache maintenance; the single-file
+ * collector uses the same numeric controls without `protectedEntries`.
+ *
+ * Sizes are bytes and ages are milliseconds. Omitted controls use the shared
+ * retention policy. Explicit protected entries are caller-selected cache
+ * directories; the cold-build caller supplies its just-returned entry, but the
+ * collector validates location rather than proving how an entry was produced.
+ * This type imposes no finite-number, range or ordering validation.
+ *
+ * @evidence contracts/common.md#principled-implementation Independent trigger, target, clock and protection fields represent the eviction decisions without confusing byte limits with millisecond age thresholds.
+ * @evidence contracts/common.md#clear-and-simple-design One internal option object configures the existing collector instead of a separate deterministic maintenance implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Overrides are explicit maintenance inputs shared with production; no branch changes behavior by recognizing a test or expected eviction result.
+ * @evidence contracts/common.md#meaningful-documentation Owning prose supplies units, omission behavior and numeric-validation limits; members distinguish forced passes, recent-cohort selection and caller-selected protected entries.
+ * @evidence contracts/portability.md#os-neutral-implementation Protected entries are native cache directories validated against the canonical root; numeric byte and millisecond controls do not encode an OS's case or path rules.
+ * @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 interface IPluginCachePruneOptions {
+    /** Ignore the once-daily marker. */
+    force?: boolean;
+    /** Size that triggers LRU pruning. */
+    maxBytes?: number;
+    /** Current wall-clock time in milliseconds since the Unix epoch. */
+    now?: number;
+    /** Recent-use age for the binary cohort or single-file size protection. */
+    protectedAgeMs?: number;
+    /** Cache directories explicitly protected by this invocation's caller. */
+    protectedEntries?: readonly string[];
+    /** Size to prune toward once the ceiling is crossed. */
+    targetBytes?: number;
+}

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

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

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * One `replace` directive of a plugin module's `go.mod` whose target is a local
+ * directory outside the module (`pluginModuleReplaceDirectories`).
+ *
+ * `go build` in the original module compiles that directory in place, so ttsc
+ * keys and snapshots it, reports its state, and resolves a relative spelling
+ * from the module's own directory.
+ *
+ * @evidence contracts/common.md#principled-implementation Logical module/version identity, original spelling and resolved directory preserve the distinction needed to hash sources and rewrite the correct Go replacement directive.
+ * @evidence contracts/common.md#clear-and-simple-design One replacement record travels from Go's directive reader to keying and scratch anchoring without reparsing its text.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Module replacements are actual go.mod directives read by Go's editor, not guessed dependencies or consumer-specific overrides.
+ * @evidence contracts/common.md#meaningful-documentation Members distinguish resolved target, original spelling, left-side module identity and optional version, with separated comments.
+ * @evidence contracts/portability.md#os-neutral-implementation Directory carries an absolute native target with best-effort physical spelling, which can retain unresolved suffixes/fallback; spelled preserves modfile syntax and modulePath is a Go identifier, not a path. The record does not pin future native identity.
+ * @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 interface IPluginModuleReplaceDirectory {
+    /** The target's absolute native path with best-effort physical spelling. */
+    directory: string;
+    /** The replaced module path, the directive's left side. */
+    modulePath: string;
+    /** The target as `go.mod` spells it. */
+    spelled: string;
+    /** The replaced version, when the directive names one. */
+    version?: string;
+}

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

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

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * One contributor's resolved Go source plus its target sub-package name.
+ *
+ * @evidence contracts/common.md#principled-implementation The name fixes the contributor's import suffix and the absolute source identifies the directory hashed and copied into the host module.
+ * @evidence contracts/common.md#clear-and-simple-design Two fields carry the already-resolved contribution, leaving descriptor validation and scratch materialization to their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The name is caller-declared contribution identity, not a fixture-specific package insertion.
+ * @evidence contracts/common.md#meaningful-documentation Members state the contrib target layout and absolute source-path requirement with separate native comments.
+ * @evidence contracts/portability.md#os-neutral-implementation Source carries the caller's resolved absolute native directory. Name is used both as a native contrib-directory component and a Go import suffix; this type does not validate materialization eligibility or pin physical identity, which remain with admission/copy owners.
+ * @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 interface ITtscBuildContributor {
+    /** Sub-package suffix: scratch lands at `<host>/contrib/<name>/`. */
+    name: string;
+    /** Absolute path to the contributor's source directory. */
+    source: string;
+}

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

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

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

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

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

@@ -0,0 +1,25 @@
+/**
+ * Source-plugin cache locations resolved for one ttsc invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate binary and Go object roots preserve independent cache selection; the source discriminant identifies whether ttsc or the caller controls object-cache reclamation.
+ * @evidence contracts/common.md#clear-and-simple-design One resolved-location object shares the same roots with build, pruning and clean without repeating resolution policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ownership follows explicit selection provenance rather than assuming every configured directory is disposable.
+ * @evidence contracts/common.md#meaningful-documentation Member comments identify content-addressed binaries, GOCACHE and selection provenance, with blank lines between fields.
+ * @evidence contracts/portability.md#os-neutral-implementation Members carry native directory spellings and a platform-independent provenance union; resolvers use node:path rather than assuming slash spelling or case policy.
+ * @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 interface ITtscSourceBuildCachePaths {
+    /** Selected plugin-cache layout root; an external GOCACHE may lie elsewhere. */
+    root: string;
+    /** Directory containing content-addressed compiled plugin binaries. */
+    pluginRoot: string;
+    /**
+     * Value passed to Go as `GOCACHE` for source-plugin builds. External GOCACHE
+     * preserves the caller's spelling; Go owns its admission and validation.
+     */
+    goBuildRoot: string;
+    /** Selection provenance controlling automatic pruning and explicit clean. */
+    goBuildRootSource: "ttsc-cache" | "TTSC_GO_CACHE_DIR" | "GOCACHE";
+}

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

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

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

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

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

@@ -0,0 +1,155 @@
+import { SourcePluginWorkspace } from "./SourcePluginWorkspace";
+/**
+ * Observe Go-selected packages under the native builder's workspace policy.
+ *
+ * Metadata does not compile dependencies or certify a later build. A cold
+ * build repeats ownership admission in its proven, materialized workspace.
+ *
+ * @evidence contracts/common.md#principled-implementation The selected Go tool, effective environment, shared workspace writer and actual copied package inputs determine package names and errors; Go remains the build-constraint and package-validity authority.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace separates contextual observation, metadata framing and ownership admission; source-only contributions are observed inside their selected host module.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No filename exception or partial tag parser classifies packages. Go Error and empty production-file selections are rejected rather than trusting Name from an erroneous package.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes metadata selection from compilation and later materialized admission.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path/fs operations and the shared Go tool selector preserve environment-name and path identity without blanket case folding; Go itself applies target platform and cgo selection.
+ * @evidence contracts/performance.md#efficient-algorithms One list command observes all distinct package entries in each prepared context. Context materialization traverses and copies admitted host/contributor files; workspace setup delegates manifest commands and list skips dependency loading. Framing and JSON parsing process complete output bytes, and retained results scale with selected packages/files.
+ * @evidence contracts/performance.md#reuse-equivalent-work Entries are deduplicated within a contextual observation; callers group equivalent module contexts for one load. No metadata result is cached across source, environment or toolchain changes. Cold admission uses the already prepared real build workspace.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Each metadata scratch has finally-based retirement-aware cleanup, and capture resources belong to spawnGoTool. Unknown native retirement retains scratch under the existing scope; results and complete output remain caller-owned with no independent byte ceiling.
+ */
+export declare namespace NativeSourcePackages {
+    /**
+     * Go-selected package identity, production files and diagnostic.
+     *
+     * @evidence contracts/common.md#principled-implementation Go supplies these observations; Name alone is not valid ownership when Error exists or production files are absent.
+     * @evidence contracts/common.md#clear-and-simple-design One record preserves the fields needed by admission without interpreting constraints.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A record is not proof of compilation or later input stability.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+     * @evidence contracts/portability.md#os-neutral-implementation Dir preserves native spelling; other fields are Go-owned text.
+     * @evidence contracts/performance.md#efficient-algorithms A type executes no algorithm.
+     * @evidence contracts/performance.md#reuse-equivalent-work The type establishes no result cache.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The type acquires no handles; its caller owns record lifetime.
+     */
+    interface Package {
+        /** Physical package directory reported by Go. */
+        Dir?: string;
+        /** Selected package name; an error does not make it authoritative. */
+        Name?: string;
+        /** Selected ordinary Go source basenames. */
+        GoFiles?: string[];
+        /** Selected cgo source basenames. */
+        CgoFiles?: string[];
+        /** Go-owned package diagnostic. */
+        Error?: {
+            Err: string;
+        };
+    }
+    /**
+     * Observe entries together in a private module layout for their context.
+     *
+     * @evidence contracts/common.md#principled-implementation The original source module pins the selected native Go tool before copying. Actual observations retain their owning manifests; prospective nested observations replace only scratch root manifests with the maintained generic host manifests. Source-only final admissions enter their selected host module.
+     * @evidence contracts/common.md#clear-and-simple-design Copying, workspace construction and batched reading have separate owners.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Go interprets tags, suffixes, cgo and manifests; selected errors are returned for admission, not overwritten by guessed kinds.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+     * @evidence contracts/portability.md#os-neutral-implementation Native copy/path and selected tool/environment owners preserve platform identity; contribution target containment is checked.
+     * @evidence contracts/performance.md#efficient-algorithms Copies admitted host/contributor bytes and enumerates entries; workspace setup reads manifests and one list command skips dependencies.
+     * @evidence contracts/performance.md#reuse-equivalent-work All entries share one prepared context; optional readers are scoped to one load and the same selected tool/effective environment.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Finally releases owned scratch through retirement authority; unknown native closure defers removal and capture cleanup remains delegated.
+     */
+    function inspect(opts: {
+        source: string;
+        pluginName: string;
+        env?: NodeJS.ProcessEnv;
+        packages: readonly {
+            entry: string;
+            source?: string;
+            name?: string;
+        }[];
+        readers?: Map<string, SourcePluginWorkspace.GoModReader>;
+        proposal?: boolean;
+    }): Package[];
+    /**
+     * Group one load's standalone candidates by their actual owning module.
+     *
+     * @evidence contracts/common.md#principled-implementation Bounded module resolution groups package entries under the module that a standalone build uses; selected errors remain terminal at ownership admission.
+     * @evidence contracts/common.md#clear-and-simple-design A map groups input indices, one contextual observation serves each module, and ordered output preserves caller identity.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No selected tool or workspace error is converted to a fallback observation. Cancellation remains terminal through checkpoints.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+     * @evidence contracts/portability.md#os-neutral-implementation Native module roots retain their selected spelling, without blanket case folding.
+     * @evidence contracts/performance.md#efficient-algorithms One grouping pass plus contextual copies and metadata work for each distinct module; output storage scales with input population.
+     * @evidence contracts/performance.md#reuse-equivalent-work Equivalent entries in a module share one list; overlay module observations share the load's selected-tool readers, without global metadata caching.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Grouping/maps/results live for this call/load; scratch and native captures remain with inspect/read.
+     */
+    function ownPackages(inputs: readonly {
+        source: string;
+        label: string;
+    }[], env: NodeJS.ProcessEnv, readers?: Map<string, SourcePluginWorkspace.GoModReader>): Package[];
+    /**
+     * Propose ownership with the candidate-selected tool before final admission.
+     *
+     * Nested transform sources retain their admitted source-module layout but
+     * use unchanged generic host root manifests in scratch. Their outer module
+     * graph and toolchain are not source-only build authority. Module-root and
+     * check sources retain their actual owning module. Executable proposals must
+     * agree in the actual own module; linked proposals in each chosen actual host.
+     *
+     * @evidence contracts/common.md#principled-implementation Candidate tool selection occurs at the original owning module and effective environment; only prospective nested source-only manifests change in owned scratch before Go interprets the normal generated workspace.
+     * @evidence contracts/common.md#clear-and-simple-design One grouping pass shares each module/proposal context and returns whether actual own-module observation already occurred.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Errors propagate; no fixed-point retry, manual constraint parser or ignored outer toolchain command determines kind.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states deterministic proposal authority and mandatory final ownership confirmation.
+     * @evidence contracts/portability.md#os-neutral-implementation Native module/tool/environment owners preserve candidate-relative tool and source layout identity.
+     * @evidence contracts/performance.md#efficient-algorithms Groups inputs by module and actual/prospective mode, copies each admitted module once per context, and batches entries through Go metadata; retained work scales with source bytes and distinct contexts.
+     * @evidence contracts/performance.md#reuse-equivalent-work Equivalent entries share one observation and per-load manifest readers; no result crosses a load or changed context.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Group records live for this call; scratch/process cleanup remains with inspect and no independent output byte cap is imposed.
+     */
+    function propose(inputs: readonly {
+        source: string;
+        label: string;
+        ownModule?: boolean;
+    }[], env: NodeJS.ProcessEnv, readers?: Map<string, SourcePluginWorkspace.GoModReader>): Array<{
+        observation: Package;
+        ownModule: boolean;
+    }>;
+    /**
+     * Read metadata in an already prepared workspace, including cold builds.
+     *
+     * @evidence contracts/common.md#principled-implementation Actual Go list uses the supplied pinned tool, effective build environment and builder flags; results are matched to requested physical directories.
+     * @evidence contracts/common.md#clear-and-simple-design One command handles distinct entries, framing delegates to parse, and physical lookup restores requested order.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Nonzero status, launch failure and missing package records propagate; no dependency compilation or fabricated success replaces Go output.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+     * @evidence contracts/portability.md#os-neutral-implementation The existing Go spawn owner supports native tools/wrappers, while native realpath matches package identities.
+     * @evidence contracts/performance.md#efficient-algorithms Deduplication and result indexing scan entry/record populations; full output capture/framing and native physical-path lookups add byte/lookup costs.
+     * @evidence contracts/performance.md#reuse-equivalent-work Duplicate entry requests share one command result within this prepared context; no result survives a subsequent read.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Capture cleanup belongs to spawnGoTool; returned records and decoded output are invocation-local, with no independent byte ceiling.
+     */
+    function read(opts: {
+        cwd: string;
+        entries: readonly string[];
+        env: NodeJS.ProcessEnv;
+        goBinary: string;
+        pluginName: string;
+    }): Package[];
+    /**
+     * Require a valid production package and agreement with requested ownership.
+     *
+     * @evidence contracts/common.md#principled-implementation Go Error is terminal and Name is admitted only with ordinary or cgo production files; main means executable, and a requested kind must agree without reclassification.
+     * @evidence contracts/common.md#clear-and-simple-design One admission function is shared by preliminary resolution, selected-host linking and cold build checks.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Test-only names and erroneous mixed-package names cannot claim ownership.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+     * @evidence contracts/portability.md#os-neutral-implementation This decision consumes Go text and counts without native path assumptions.
+     * @evidence contracts/performance.md#efficient-algorithms A fixed number of field/count checks precedes one exact name comparison.
+     * @evidence contracts/performance.md#reuse-equivalent-work Every current observation is checked directly; no kind cache is retained.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The function acquires no native resources and returns one kind string.
+     */
+    function kind(input: Package, label: string, expected?: "executable" | "linked"): "executable" | "linked";
+    /**
+     * Frame Go's JSON object stream and validate the selected fields.
+     *
+     * @evidence contracts/common.md#principled-implementation A string/escape-aware brace state machine frames complete objects before standard JSON parsing; invalid framing and field shapes throw.
+     * @evidence contracts/common.md#clear-and-simple-design Framing, JSON decoding and selected-field validation are explicit sequential steps.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Braces inside diagnostic strings cannot split records; no textual replacement fabricates a JSON array.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states this operation's authority and delegated boundaries; fields retain separate native comments.
+     * @evidence contracts/portability.md#os-neutral-implementation JSON is a platform-neutral wire format and Dir bytes are preserved unchanged.
+     * @evidence contracts/performance.md#efficient-algorithms One character pass frames output, followed by JSON parsing and selected filename-array validation; complete object slices/records scale with output bytes.
+     * @evidence contracts/performance.md#reuse-equivalent-work Each output stream is decoded once and retained only by the caller; no prior stream is reused.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources No handles are acquired; complete input/slices/decoded records can coexist without a separate byte cap.
+     */
+    function parse(output: string): Package[];
+}