@ttsc/graph 0.30.4 → 0.31.1

package/lib/internal/GraphProcessTrace.js

@@ -0,0 +1,235 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphProcessTrace = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_events_1 = require("node:events");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Private process observers; package entrypoints do not export this namespace.
+ * The aliases retain Node's overloads while their adapters pass arguments
+ * intact. Native executable, argv and option types stay with Node. This
+ * grouping adds no product flag, protocol field, cache, process holder or
+ * algorithm; those responsibilities remain with the adapters and their existing
+ * callers.
+ *
+ * @internal
+ */
+var GraphProcessTrace;
+(function (GraphProcessTrace) {
+    GraphProcessTrace.spawn = observeSpawn;
+    GraphProcessTrace.spawnSync = observeSpawnSync;
+})(GraphProcessTrace || (exports.GraphProcessTrace = GraphProcessTrace = {}));
+/**
+ * Correlate one actual call in the coordinator's absolute scratch directory.
+ * Failed writes leave bounded integrity evidence where possible; an unwritable
+ * sink remains missing measurement data. Neither failure changes product IO.
+ *
+ * A process-local nonce and increasing ordinal distinguish calls from child PID
+ * reuse. The optional closure owns correlation and the append sink only;
+ * callers own process behavior. Node's absolute-path and append operations use
+ * the coordinator's native path spelling and process.pid identifies the writer.
+ * No fixture oracle, foreign mutation or test-helper dependency is involved.
+ * Each event carries the writer's actual process.version; that runtime string
+ * alone does not authenticate executable bytes or the loaded native image.
+ *
+ * Each event serializes its observed fields once, so temporary text follows
+ * event size. Synchronous IO is measurement overhead, not a claimed speedup.
+ * Effectful calls and writes are never deduplicated. Scalar counters and one
+ * nonce persist per module instance; each append closes its handle. Events are
+ * capped at64MiB and writer output at256MiB, plus one overwritten bounded
+ * integrity marker. The coordinator retains these files until writers join.
+ */
+function begin() {
+    const root = process.env.TTSC_E2E_TRACE;
+    if (!root || !node_path_1.default.isAbsolute(root))
+        return undefined;
+    try {
+        instance ??= (0, node_crypto_1.randomUUID)();
+    }
+    catch {
+        return undefined;
+    }
+    const writerInstance = instance;
+    const invocation = `${writerInstance}:${++ordinal}`;
+    const file = node_path_1.default.join(root, `${process.pid}-${writerInstance}.jsonl`);
+    return (event, fields) => {
+        try {
+            const line = JSON.stringify({
+                ...fields,
+                schema: 1,
+                event,
+                writerPid: process.pid,
+                instance: writerInstance,
+                sequence: ++sequence,
+                at: new Date().toISOString(),
+                invocation,
+                data: {
+                    ...fields.data,
+                    writerRuntime: process.version,
+                },
+            }) + "\n";
+            const bytes = Buffer.byteLength(line);
+            if (bytes > EVENT_LIMIT || written + bytes > WRITER_LIMIT)
+                throw new Error("trace writer byte budget exceeded");
+            node_fs_1.default.appendFileSync(file, line, { encoding: "utf8", mode: 0o600 });
+            written += bytes;
+        }
+        catch {
+            try {
+                node_fs_1.default.writeFileSync(`${file}.integrity`, "trace serialization, append or byte budget failed", { mode: 0o600 });
+            }
+            catch {
+                /* Missing trace remains an integrity failure. */
+            }
+        }
+    };
+}
+/**
+ * Observe the supported spawn, exit and close events on the original child.
+ * errorMonitor observes errors without becoming a normal error handler. Call
+ * bounds are not exact OS creation times; close does not join descendants.
+ *
+ * Native spawn executes once with unchanged executable, argv and options and
+ * returns the original child or throws the same synchronous error. Events
+ * provide actual PID and lifecycle observations under one invocation; cwd
+ * records explicit or inherited intent without guessing native resolution.
+ * Streams, parsing, shutdown, references and normal errors stay caller-owned.
+ *
+ * Disabled observation delegates directly; enabled calls serialize argv and a
+ * fixed event population. Effectful starts are not reusable results. Once
+ * listeners retain correlation until their event or child collection; no timer,
+ * reference change, kill or independent wait is added. Existing owners release
+ * the child, and no foreign process export is patched.
+ */
+function observeSpawn(...args) {
+    const trace = begin();
+    if (!trace)
+        return Reflect.apply(node_child_process_1.spawn, undefined, args);
+    const options = (Array.isArray(args[1]) ? args[2] : args[1]);
+    const selected = {
+        argv: [args[0], ...(Array.isArray(args[1]) ? args[1] : [])],
+        cwd: options?.cwd === undefined ? null : String(options.cwd),
+        data: { primitive: "spawn", cwdInherited: options?.cwd === undefined },
+    };
+    const startLowerBound = new Date().toISOString();
+    trace("process-attempt", { ...selected, pid: null, startLowerBound });
+    let child;
+    try {
+        child = Reflect.apply(node_child_process_1.spawn, undefined, args);
+    }
+    catch (error) {
+        trace("process-result", {
+            pid: null,
+            started: false,
+            exitObserved: false,
+            startLowerBound,
+            startUpperBound: new Date().toISOString(),
+            data: { outcome: "synchronous-spawn-error", error },
+        });
+        throw error;
+    }
+    const startUpperBound = new Date().toISOString();
+    let started = false;
+    let exitObserved = false;
+    child.once("spawn", () => {
+        started = true;
+        trace("process-start", {
+            pid: child.pid ?? null,
+            started,
+            startLowerBound,
+            startUpperBound,
+        });
+    });
+    child.once(node_events_1.errorMonitor, (error) => trace("process-error", {
+        pid: child.pid ?? null,
+        started,
+        exitObserved,
+        error: error.message,
+        data: { code: error.code },
+    }));
+    child.once("exit", (status, signal) => {
+        exitObserved = true;
+        trace("process-exit", {
+            pid: child.pid ?? null,
+            started,
+            exitObserved,
+            status,
+            signal,
+        });
+    });
+    child.once("close", (status, signal) => trace("process-close", {
+        pid: child.pid ?? null,
+        started,
+        exitObserved,
+        status,
+        signal,
+    }));
+    return child;
+}
+/**
+ * Observe the original synchronous result without replacing file descriptors,
+ * encoding, buffers, shell options or errors. A positive returned PID records a
+ * started child; call bounds do not invent its exact creation timestamp.
+ *
+ * Actual returned PID/status/signal/error distinguish a child from a failed
+ * pre-start attempt. Executable, argv, native options and the identical result
+ * or thrown error pass through unchanged. Explicit cwd and inherited intent are
+ * distinct observations, not resolved executable identity. Downstream capture,
+ * status mapping, protocol bytes and disposal remain in their existing owners.
+ *
+ * Observation adds argv serialization and two bounded event writes per actual
+ * effectful call; captured output is not copied or reused as expected counts.
+ * One correlation remains until native return, append handles close per write
+ * and original callers still release their captures.
+ */
+function observeSpawnSync(...args) {
+    const trace = begin();
+    if (!trace)
+        return Reflect.apply(node_child_process_1.spawnSync, undefined, args);
+    const options = (Array.isArray(args[1]) ? args[2] : args[1]);
+    const selected = {
+        argv: [args[0], ...(Array.isArray(args[1]) ? args[1] : [])],
+        cwd: options?.cwd === undefined ? null : String(options.cwd),
+        data: { primitive: "spawnSync", cwdInherited: options?.cwd === undefined },
+    };
+    const startLowerBound = new Date().toISOString();
+    trace("process-attempt", { ...selected, pid: null, startLowerBound });
+    let result;
+    try {
+        result = Reflect.apply(node_child_process_1.spawnSync, undefined, args);
+    }
+    catch (error) {
+        trace("process-result", {
+            pid: null,
+            started: false,
+            exitObserved: false,
+            startLowerBound,
+            startUpperBound: new Date().toISOString(),
+            data: { outcome: "synchronous-spawn-error", error },
+        });
+        throw error;
+    }
+    trace("process-result", {
+        pid: result.pid || null,
+        started: result.pid > 0,
+        exitObserved: result.status !== null || result.signal !== null,
+        status: result.status,
+        signal: result.signal,
+        error: result.error?.message,
+        startLowerBound,
+        startUpperBound: new Date().toISOString(),
+    });
+    return result;
+}
+let instance;
+let ordinal = 0;
+let sequence = 0;
+let written = 0;
+const EVENT_LIMIT = 64 * 1024 * 1024;
+const WRITER_LIMIT = 256 * 1024 * 1024;
+//# sourceMappingURL=GraphProcessTrace.js.map

package/lib/internal/GraphProcessTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphProcessTrace.js","sourceRoot":"","sources":["../../src/internal/GraphProcessTrace.ts"],"names":[],"mappings":"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"}

package/lib/launcherArgs.d.ts

@@ -1,24 +1,83 @@
+import type { ILauncherOption } from "./ILauncherOption";
+import type { IProjectOptions } from "./IProjectOptions";
+import type { ParsedLauncherOptions } from "./ParsedLauncherOptions";
+/**
+ * Invalid launcher syntax or a value outside the option's supported domain.
+ *
+ * @evidence contracts/common.md#principled-implementation An Error subtype gives callers a distinct argument-failure category while preserving the original diagnostic message.
+ * @evidence contracts/common.md#clear-and-simple-design Only the error name differs; native Error owns stack and message behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No global Error behavior is patched to classify launcher failures.
+ * @evidence contracts/common.md#meaningful-documentation The native headline identifies the two supported causes without restating the class name.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Argument failure representation has no filesystem or process boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources an Error subclass retains only its message and stack for the catcher.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms an Error subclass that only sets its name, so it runs no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work an Error subclass holds no computation that could be shared.
+ */
 export declare class GraphArgumentError extends Error {
     constructor(message: string);
 }
-type OptionKind = "value" | "flag" | "boolean";
-export interface ILauncherOption {
-    key: string;
-    flags: readonly string[];
-    kind: OptionKind;
-}
-export type ParsedLauncherOptions = ReadonlyMap<string, string | boolean>;
-export interface IProjectOptions {
-    cwd: string;
-    tsconfig: string;
-}
 export declare const PROJECT_OPTIONS: readonly ILauncherOption[];
-/** Parse one complete launcher argument vector and reject every unknown token. */
+/**
+ * Parse one complete launcher argument vector and reject every unknown token.
+ *
+ * Repeated aliases replace the prior canonical value. Missing values, values on
+ * bare flags and unsupported boolean spellings throw GraphArgumentError.
+ *
+ * @evidence contracts/common.md#principled-implementation An alias map and ordered argument scan implement explicit option grammar; typed validators reject unsupported values without coercion.
+ * @evidence contracts/common.md#clear-and-simple-design Definitions own grammar while private helpers own equals syntax, nonempty text and boolean spellings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every token must match a configured option; unknown input is not silently accepted for a known fixture.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains repeated options and argument failures, with tags separated by a blank comment line.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Token parsing interprets no path and invokes no native process; projectOptions handles path-bearing options later.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources builds a local Map that it returns and keeps no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one pass over argv with a Map of flag aliases, linear in the argument count.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work parses one argv per launch and caches nothing.
+ */
 export declare function parseLauncherOptions(argv: readonly string[], definitions: readonly ILauncherOption[]): ParsedLauncherOptions;
-/** Resolve the two project-selection values shared by every launcher lane. */
+/**
+ * Resolve the two project-selection values shared by every launcher lane.
+ *
+ * Defaults are the process directory and tsconfig.json; relative cwd values are
+ * resolved before package lookup or native process invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation Native path.resolve makes cwd absolute while the config retains the producer's cwd-relative convention.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter owns both shared defaults for all launcher lanes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Defaults are public launcher conventions rather than named-repository exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents defaults and resolution timing instead of only listing returned keys.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path.resolve applies the host's native path rules without manually concatenating separators.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms resolves two values in constant time.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work two lookups per call, nothing worth sharing.
+ */
 export declare function projectOptions(values: ParsedLauncherOptions): IProjectOptions;
-/** Read a bounded non-negative integer option without JavaScript coercion. */
+/**
+ * Read a bounded non-negative integer option without JavaScript coercion.
+ *
+ * The value must be present, decimal digits and a safe integer no greater than
+ * maximum. Missing parser state is an internal error; invalid text is an
+ * argument error.
+ *
+ * @evidence contracts/common.md#principled-implementation Decimal syntax plus safe-integer and maximum checks exclude coercible nonintegers and precision loss before returning a number.
+ * @evidence contracts/common.md#clear-and-simple-design One validator owns nonnegative parsing and is reused by the positive validator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Bounds are supplied by the option contract rather than expected fixture values.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains numeric domain and the distinction between missing state and invalid input.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Numeric option validation has no native filesystem or process operation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a number and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one digit-pattern test and one Number conversion of a single option value.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work validates one option value per call.
+ */
 export declare function nonNegativeIntegerOption(values: ParsedLauncherOptions, key: string, maximum: number): number;
-/** Read a bounded positive integer option without JavaScript coercion. */
+/**
+ * Read a bounded positive integer option without JavaScript coercion.
+ *
+ * Uses the nonnegative validator and additionally rejects zero.
+ *
+ * @evidence contracts/common.md#principled-implementation Reusing safe nonnegative validation then excluding zero yields exactly the bounded positive-integer domain.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter adds one domain restriction rather than duplicating numeric parsing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Zero rejection follows the option domain, not a special expected command case.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the additional restriction and identifies the shared validator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The positivity restriction is a platform-independent numeric predicate.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a number and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms delegates to nonNegativeIntegerOption and compares the result with zero.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work validates one option value per call.
+ */
 export declare function positiveIntegerOption(values: ParsedLauncherOptions, key: string, maximum: number): number;
-export {};

package/lib/launcherArgs.js

@@ -9,6 +9,18 @@ exports.projectOptions = projectOptions;
 exports.nonNegativeIntegerOption = nonNegativeIntegerOption;
 exports.positiveIntegerOption = positiveIntegerOption;
 const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Invalid launcher syntax or a value outside the option's supported domain.
+ *
+ * @evidence contracts/common.md#principled-implementation An Error subtype gives callers a distinct argument-failure category while preserving the original diagnostic message.
+ * @evidence contracts/common.md#clear-and-simple-design Only the error name differs; native Error owns stack and message behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No global Error behavior is patched to classify launcher failures.
+ * @evidence contracts/common.md#meaningful-documentation The native headline identifies the two supported causes without restating the class name.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Argument failure representation has no filesystem or process boundary.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources an Error subclass retains only its message and stack for the catcher.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms an Error subclass that only sets its name, so it runs no algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work an Error subclass holds no computation that could be shared.
+ */
 class GraphArgumentError extends Error {
     constructor(message) {
         super(message);
@@ -20,7 +32,21 @@ exports.PROJECT_OPTIONS = [
     { key: "cwd", flags: ["--cwd"], kind: "value" },
     { key: "tsconfig", flags: ["--tsconfig"], kind: "value" },
 ];
-/** Parse one complete launcher argument vector and reject every unknown token. */
+/**
+ * Parse one complete launcher argument vector and reject every unknown token.
+ *
+ * Repeated aliases replace the prior canonical value. Missing values, values on
+ * bare flags and unsupported boolean spellings throw GraphArgumentError.
+ *
+ * @evidence contracts/common.md#principled-implementation An alias map and ordered argument scan implement explicit option grammar; typed validators reject unsupported values without coercion.
+ * @evidence contracts/common.md#clear-and-simple-design Definitions own grammar while private helpers own equals syntax, nonempty text and boolean spellings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every token must match a configured option; unknown input is not silently accepted for a known fixture.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains repeated options and argument failures, with tags separated by a blank comment line.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Token parsing interprets no path and invokes no native process; projectOptions handles path-bearing options later.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources builds a local Map that it returns and keeps no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one pass over argv with a Map of flag aliases, linear in the argument count.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work parses one argv per launch and caches nothing.
+ */
 function parseLauncherOptions(argv, definitions) {
     const flags = new Map();
     for (const definition of definitions) {
@@ -32,12 +58,13 @@ function parseLauncherOptions(argv, definitions) {
         const arg = argv[i];
         const exact = flags.get(arg);
         if (exact !== undefined) {
-            if (exact.kind === "value") {
+            if (exact.kind === "value" || exact.kind === "string") {
                 const value = argv[++i];
-                if (value === undefined || value.startsWith("-")) {
+                if (value === undefined ||
+                    (exact.kind === "value" && value.startsWith("-"))) {
                     throw new GraphArgumentError(`${arg} requires a non-empty value`);
                 }
-                parsed.set(exact.key, requireValue(arg, value));
+                parsed.set(exact.key, exact.kind === "string" ? value : requireValue(arg, value));
             }
             else {
                 parsed.set(exact.key, true);
@@ -56,19 +83,48 @@ function parseLauncherOptions(argv, definitions) {
             parsed.set(definition.key, parseBoolean(flag, value));
         }
         else {
-            parsed.set(definition.key, requireValue(flag, value));
+            parsed.set(definition.key, definition.kind === "string" ? value : requireValue(flag, value));
         }
     }
     return parsed;
 }
-/** Resolve the two project-selection values shared by every launcher lane. */
+/**
+ * Resolve the two project-selection values shared by every launcher lane.
+ *
+ * Defaults are the process directory and tsconfig.json; relative cwd values are
+ * resolved before package lookup or native process invocation.
+ *
+ * @evidence contracts/common.md#principled-implementation Native path.resolve makes cwd absolute while the config retains the producer's cwd-relative convention.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter owns both shared defaults for all launcher lanes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Defaults are public launcher conventions rather than named-repository exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents defaults and resolution timing instead of only listing returned keys.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path.resolve applies the host's native path rules without manually concatenating separators.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms resolves two values in constant time.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work two lookups per call, nothing worth sharing.
+ */
 function projectOptions(values) {
     return {
         cwd: node_path_1.default.resolve(stringValue(values, "cwd") ?? process.cwd()),
         tsconfig: stringValue(values, "tsconfig") ?? "tsconfig.json",
     };
 }
-/** Read a bounded non-negative integer option without JavaScript coercion. */
+/**
+ * Read a bounded non-negative integer option without JavaScript coercion.
+ *
+ * The value must be present, decimal digits and a safe integer no greater than
+ * maximum. Missing parser state is an internal error; invalid text is an
+ * argument error.
+ *
+ * @evidence contracts/common.md#principled-implementation Decimal syntax plus safe-integer and maximum checks exclude coercible nonintegers and precision loss before returning a number.
+ * @evidence contracts/common.md#clear-and-simple-design One validator owns nonnegative parsing and is reused by the positive validator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Bounds are supplied by the option contract rather than expected fixture values.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains numeric domain and the distinction between missing state and invalid input.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Numeric option validation has no native filesystem or process operation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a number and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one digit-pattern test and one Number conversion of a single option value.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work validates one option value per call.
+ */
 function nonNegativeIntegerOption(values, key, maximum) {
     const value = stringValue(values, key);
     if (value === undefined) {
@@ -83,7 +139,20 @@ function nonNegativeIntegerOption(values, key, maximum) {
     }
     return number;
 }
-/** Read a bounded positive integer option without JavaScript coercion. */
+/**
+ * Read a bounded positive integer option without JavaScript coercion.
+ *
+ * Uses the nonnegative validator and additionally rejects zero.
+ *
+ * @evidence contracts/common.md#principled-implementation Reusing safe nonnegative validation then excluding zero yields exactly the bounded positive-integer domain.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter adds one domain restriction rather than duplicating numeric parsing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Zero rejection follows the option domain, not a special expected command case.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the additional restriction and identifies the shared validator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The positivity restriction is a platform-independent numeric predicate.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a number and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms delegates to nonNegativeIntegerOption and compares the result with zero.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work validates one option value per call.
+ */
 function positiveIntegerOption(values, key, maximum) {
     const value = nonNegativeIntegerOption(values, key, maximum);
     if (value === 0) {

package/lib/launcherArgs.js.map

@@ -1 +1 @@
-{"version":3,"file":"launcherArgs.js","sourceRoot":"","sources":["../src/launcherArgs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"launcherArgs.js","sourceRoot":"","sources":["../src/launcherArgs.ts"],"names":[],"mappings":"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"}

package/lib/model/IArtifactDirectory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A directory watched on behalf of the pattern that named it.
+ *
+ * @evidence contracts/common.md#principled-implementation The absolute root and descent flag identify the conservative tree population needed to notice a declared pattern changing.
+ * @evidence contracts/common.md#clear-and-simple-design A directory watch contains only its native root and traversal choice; resolved files remain in the separate file list.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The depth decision follows wildcard path structure rather than an arbitrary maximum documentation depth.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains the recursive distinction and why a bare filename wildcard does not require a repository-wide scan.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface IArtifactDirectory {
+    /** Absolute path of the directory to walk. */
+    path: string;
+    /**
+     * Whether the walk descends.
+     *
+     * Taken from wildcard path structure rather than assumed, because assuming it
+     * is expensive in exactly the case that looks harmless: a rule declaring
+     * `*.md` has the project root for its fixed prefix, and treating that as
+     * recursive would state every file in the repository before every graph
+     * request.
+     */
+    recursive: boolean;
+}

package/lib/model/IArtifactDirectory.js

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

package/lib/model/IArtifactDirectory.js.map

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

package/lib/model/IArtifactInputs.d.ts

@@ -0,0 +1,19 @@
+import { IArtifactDirectory } from "./IArtifactDirectory";
+/**
+ * Paths an answer was derived from, split by how they are watched.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit files and watched directories represent edits and membership changes as distinct input populations.
+ * @evidence contracts/common.md#clear-and-simple-design Two lists carry sidecar-declared provenance without a second glob interpreter or compiler dependency model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An input inventory does not assert complete discovery provenance for a missing publisher.
+ * @evidence contracts/common.md#meaningful-documentation Native property prose identifies individual files and directories that notice additions and deletions.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface IArtifactInputs {
+    /** Files stated one by one. */
+    files: string[];
+    /** Directories walked, which is what notices an added or deleted file. */
+    directories: IArtifactDirectory[];
+}

package/lib/model/IArtifactInputs.js

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

package/lib/model/IArtifactInputs.js.map

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