ttsc 0.30.4 → 0.31.0

package/lib/plugin/CapabilityPluginResolver.js

@@ -0,0 +1,400 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapabilityPluginResolver = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_v8_1 = require("node:v8");
+const node_worker_threads_1 = require("node:worker_threads");
+const E2ETrace_1 = require("../internal/E2ETrace");
+const OwnedNativeProcess_1 = require("../internal/OwnedNativeProcess");
+const serializeCompilerError_1 = require("../internal/serializeCompilerError");
+const receiveCapabilityFailure_1 = require("./internal/receiveCapabilityFailure");
+/**
+ * Own asynchronous capability discovery and its opaque freshness proofs. The
+ * same worker executes the existing synchronous resolver and keeps each
+ * original proof closure. Its native commands are relayed to a joined process
+ * supervisor, so cancellation unwinds build cleanup rather than killing the
+ * resolver thread while it holds a lease.
+ *
+ * @evidence contracts/common.md#principled-implementation Serial worker requests preserve the original resolver and proof objects; command containment completes before cancellation resumes their synchronous stacks.
+ * @evidence contracts/common.md#clear-and-simple-design This owner controls admission, worker RPC, opaque proof handles and shutdown; the worker owns synchronous discovery and the native owner controls process trees.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No consumer inventory replaces resolver authority and no warmup, altered timeout or uncontained fallback hides a cold producer.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains proof lifetime, cancellation cleanup and the independent native process owner.
+ * @evidence contracts/portability.md#os-neutral-implementation The compiled worker uses the SDK's CommonJS file layout, cloned environments and platform helper resolution rather than consumer-specific paths.
+ * @evidence contracts/performance.md#efficient-algorithms One worker serves serialized requests and retains original proof closures; command output serialization scales with returned bytes and request admission grows with submitted demand.
+ * @evidence contracts/performance.md#reuse-equivalent-work Worker reuse retains validated SDK caches but every resolve and currentness request still calls its original authority; proof handles never transfer freshness between generations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Explicit release drops proof handles. Close aborts admitted work, joins command supervisors and waits for worker exit; private command exchange storage is removed after its request settles.
+ */
+class CapabilityPluginResolver {
+    worker;
+    queue = Promise.resolve();
+    nextId = 0;
+    generation = 0;
+    closed = false;
+    closing;
+    controllers = new Set();
+    native = new Set();
+    failures = [];
+    exits = new Map();
+    /**
+     * Resolve through the SDK owner, retaining this exact answer's opaque proof.
+     *
+     * @evidence contracts/common.md#principled-implementation The original resolver creates the answer and closure; worker-generation-qualified handles prevent a restarted worker from reinterpreting an earlier proof number.
+     * @evidence contracts/common.md#clear-and-simple-design Returned currentness and release callbacks retain one answer while the owner serializes all worker operations.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Discovery and currentness execute the existing authority instead of substituting an inventory or inferring freshness from a cache path.
+     * @evidence contracts/common.md#meaningful-documentation The method describes retained opaque ownership; member types distinguish asynchronous proof queries and release.
+     * @evidence contracts/portability.md#os-neutral-implementation Cloned options and environment reach the packaged Node worker; native commands use the separate platform supervisor.
+     * @evidence contracts/performance.md#efficient-algorithms Resolution cost remains with the original resolver; the RPC copies returned plugin metadata and retains one closure per unreleased answer.
+     * @evidence contracts/performance.md#reuse-equivalent-work Every currentness query calls the original closure in its original worker generation; release or worker loss makes that proof unusable.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Explicit release removes the worker proof, while close clears all remaining proofs after cancelling and joining admitted work.
+     */
+    async resolve(options, request = {}) {
+        const value = (await this.request({ kind: "resolve", options }, request.signal));
+        let released = false;
+        return {
+            status: value.status,
+            plugins: value.plugins,
+            isCurrent: async ({ signal } = {}) => released || this.closed
+                ? false
+                : (await this.request({
+                    kind: "current",
+                    handle: value.handle,
+                    generation: value.generation,
+                }, signal)),
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                if (!this.closed)
+                    await this.request({
+                        kind: "release",
+                        handle: value.handle,
+                        generation: value.generation,
+                    });
+            },
+        };
+    }
+    /**
+     * Execute an admitted publisher verb with the same native lifetime owner.
+     *
+     * @evidence contracts/common.md#principled-implementation Admission checks terminal ownership before registering a linked controller; the native owner supplies actual joined command outcomes.
+     * @evidence contracts/common.md#clear-and-simple-design This method links caller cancellation and owner shutdown to one native operation and removes both links on settlement.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No synchronous fallback bypasses native containment when a publisher cannot use its resident daemon.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies publisher execution and the shared lifetime owner; option support is enforced by that native owner.
+     * @evidence contracts/portability.md#os-neutral-implementation Exact argv and options reach the platform supervisor through OwnedNativeProcess rather than shell reconstruction in this method.
+     * @evidence contracts/performance.md#efficient-algorithms Admission and retirement use sets with one operation entry; output costs belong to the native operation.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Publisher verbs can have effects and must execute per admitted request.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Close can abort every registered operation, waits for its real completion, and retains non-cancellation failures instead of silently certifying clean shutdown.
+     */
+    runCommand(command, args, options, request = {}) {
+        if (this.closed)
+            return Promise.reject(new Error("ttsc: capability resolver is closed"));
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        const abort = () => controller.abort(request.signal?.reason);
+        request.signal?.addEventListener("abort", abort, { once: true });
+        if (request.signal?.aborted)
+            abort();
+        const operation = OwnedNativeProcess_1.OwnedNativeProcess.run(command, args, options, controller.signal, (state) => {
+            if (state === "unknown")
+                this.closed = true;
+        });
+        this.native.add(operation);
+        void operation.catch((error) => {
+            if (!controller.signal.aborted || error !== controller.signal.reason)
+                this.rememberFailure(error);
+        });
+        return operation.finally(() => {
+            this.native.delete(operation);
+            this.controllers.delete(controller);
+            request.signal?.removeEventListener("abort", abort);
+        });
+    }
+    /**
+     * Withdraw all admission and join native owners before releasing the worker.
+     *
+     * @evidence contracts/common.md#principled-implementation Terminal admission is set synchronously, then cancellation unwinds request cleanup before idle worker shutdown; every worker exit is joined even after an error event.
+     * @evidence contracts/common.md#clear-and-simple-design One memoized shutdown promise orders queue drain, native joining and worker exit.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts An error event is not treated as thread exit and a failed native receipt cannot become successful close.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states admission withdrawal and join order; retained failures become an aggregate terminal error.
+     * @evidence contracts/portability.md#os-neutral-implementation AbortController and Worker exit events provide the Node lifetime boundary while platform process cleanup remains native-owned.
+     * @evidence contracts/performance.md#efficient-algorithms Shutdown visits admitted controllers, outstanding native operations and created worker exits once; their actual cleanup durations remain delegated.
+     * @evidence contracts/performance.md#reuse-equivalent-work Repeated close calls share the same terminal promise without reopening admission.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Queue completion and real native retirement precede worker close, and all created worker exit promises settle before the owner reports terminal success or retained failure.
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.closed = true;
+        for (const controller of this.controllers)
+            controller.abort(new DOMException("ttsc: capability resolver closed", "AbortError"));
+        this.closing = (async () => {
+            await this.queue;
+            await Promise.allSettled(this.native);
+            const worker = this.worker;
+            if (worker !== undefined) {
+                worker.ref();
+                try {
+                    worker.postMessage({ kind: "close" });
+                }
+                catch (error) {
+                    this.rememberFailure(error);
+                    // No task remains after queue/native joining, so a failed shutdown
+                    // message may terminate this idle thread without abandoning leases.
+                    await worker.terminate();
+                }
+            }
+            await Promise.all(this.exits.values());
+            this.worker = undefined;
+            if (this.failures.length !== 0)
+                throw new AggregateError(this.failures, "ttsc: capability owner failed to retire cleanly");
+        })();
+        return this.closing;
+    }
+    request(body, signal) {
+        if (this.closed)
+            return Promise.reject(new Error("ttsc: capability resolver is closed"));
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        const operation = this.queue
+            .catch(() => undefined)
+            .then(() => this.call(body, controller.signal));
+        this.queue = operation.then(() => undefined, () => undefined);
+        return operation.finally(() => {
+            this.controllers.delete(controller);
+            signal?.removeEventListener("abort", abort);
+        });
+    }
+    async call(body, signal) {
+        signal.throwIfAborted();
+        if (this.closed)
+            throw new Error("ttsc: capability resolver is closed");
+        if (body.generation !== undefined &&
+            (this.worker === undefined || body.generation !== this.generation))
+            return body.kind === "current" ? false : undefined;
+        const worker = this.worker ?? this.createWorker();
+        const generation = this.generation;
+        const id = ++this.nextId;
+        const cancel = new SharedArrayBuffer(4);
+        const directory = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "ttsc-capability-rpc-"));
+        const commands = new Set();
+        const nativeController = new AbortController();
+        const stop = () => {
+            nativeController.abort(signal.reason);
+            Atomics.store(new Int32Array(cancel), 0, 1);
+            Atomics.notify(new Int32Array(cancel), 0);
+        };
+        signal.addEventListener("abort", stop, { once: true });
+        if (signal.aborted)
+            stop();
+        worker.ref();
+        let originalFailure;
+        let failed = false;
+        try {
+            return await new Promise((resolve, reject) => {
+                const clear = () => {
+                    worker.off("message", message);
+                    worker.off("error", failed);
+                    worker.off("exit", exited);
+                };
+                const failed = (error) => {
+                    nativeController.abort(error);
+                    clear();
+                    if (this.worker === worker)
+                        this.worker = undefined;
+                    reject(error);
+                };
+                const exited = (code) => failed(new Error(`ttsc: capability worker exited ${code} before replying`));
+                const message = (reply) => {
+                    if (reply.id !== id)
+                        return;
+                    if (reply.kind === "command") {
+                        if (this.closed) {
+                            const explicitClose = this.closing !== undefined;
+                            E2ETrace_1.E2ETrace.capabilityResolution("command-admission-withdrawn", {
+                                request: id,
+                                responseFile: reply.responseFile,
+                                explicitClose,
+                                retirement: "not-started",
+                            });
+                            const rejection = Promise.resolve().then(() => writeCommandReply(reply, {
+                                retirement: "not-started",
+                                thrown: (0, serializeCompilerError_1.serializeCompilerError)(explicitClose
+                                    ? Object.assign(new Error("ttsc: capability resolver closed before command admission"), { name: "AbortError" })
+                                    : new Error("ttsc: capability resolver is closed")),
+                            }));
+                            commands.add(rejection);
+                            void rejection.catch((error) => this.rememberFailure(error));
+                            return;
+                        }
+                        let retirement = "not-started";
+                        const operation = OwnedNativeProcess_1.OwnedNativeProcess.run(reply.command, reply.args, reply.options, nativeController.signal, (state, _reason, observation) => {
+                            retirement = state;
+                            if (state === "unknown")
+                                this.closed = true;
+                            if (process.env.TTSC_E2E_TRACE) {
+                                // The worker's existing command-relay-queued event binds
+                                // this response file to its original boundary token.
+                                E2ETrace_1.E2ETrace.capabilityResolution("native-command-retired", {
+                                    taskToken: `${directory}:${id}`,
+                                    responseFile: reply.responseFile,
+                                    retirement: state,
+                                    ...observation,
+                                });
+                            }
+                        }).then((result) => writeCommandReply(reply, {
+                            retirement,
+                            result: {
+                                ...result,
+                                ...(result.error === undefined
+                                    ? {}
+                                    : { error: (0, serializeCompilerError_1.serializeCompilerError)(result.error) }),
+                            },
+                        }), (error) => {
+                            const cancelled = nativeController.signal.aborted &&
+                                error === nativeController.signal.reason;
+                            if (!cancelled)
+                                this.rememberFailure(error);
+                            // The worker needs a cancellation classification, while the
+                            // caller's arbitrary reason stays on its original main thread.
+                            writeCommandReply(reply, {
+                                retirement,
+                                thrown: (0, serializeCompilerError_1.serializeCompilerError)(cancelled
+                                    ? Object.assign(new Error("ttsc: operation cancelled"), {
+                                        name: "AbortError",
+                                    })
+                                    : error),
+                            });
+                        });
+                        commands.add(operation);
+                        this.native.add(operation);
+                        // Keep every command in this request until its final join, including
+                        // failed exchange writes after native retirement.
+                        void operation
+                            .finally(() => this.native.delete(operation))
+                            .catch(() => undefined);
+                        return;
+                    }
+                    clear();
+                    if (reply.thrown !== undefined) {
+                        const error = (0, receiveCapabilityFailure_1.receiveCapabilityFailure)(reply, (failure) => this.failures.push(failure));
+                        if (signal.aborted && error.name === "AbortError")
+                            reject(signal.reason);
+                        else if (signal.aborted)
+                            reject(new AggregateError([signal.reason, error], "ttsc: cancellation cleanup failed"));
+                        else
+                            reject(error);
+                    }
+                    else if (signal.aborted) {
+                        if (body.kind === "resolve") {
+                            const handle = reply.value.handle;
+                            try {
+                                worker.postMessage({ kind: "discard", handle });
+                            }
+                            catch (error) {
+                                this.rememberFailure(error);
+                                reject(new AggregateError([signal.reason, error], "ttsc: cancelled proof retirement failed"));
+                                return;
+                            }
+                        }
+                        reject(signal.reason);
+                    }
+                    else
+                        resolve(body.kind === "resolve"
+                            ? { ...reply.value, generation }
+                            : reply.value);
+                };
+                worker.on("message", message);
+                worker.once("error", failed);
+                worker.once("exit", exited);
+                try {
+                    worker.postMessage({
+                        ...body,
+                        id,
+                        cancel,
+                        directory,
+                        env: { ...process.env },
+                    });
+                }
+                catch (error) {
+                    failed(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        }
+        catch (error) {
+            failed = true;
+            originalFailure = error;
+            throw error;
+        }
+        finally {
+            signal.removeEventListener("abort", stop);
+            await Promise.allSettled(commands);
+            if (this.worker !== worker)
+                await this.exits.get(worker);
+            worker.unref();
+            try {
+                node_fs_1.default.rmSync(directory, { force: true, recursive: true });
+            }
+            catch (error) {
+                this.rememberFailure(error);
+                throw failed
+                    ? new AggregateError([originalFailure, error], "ttsc: resolver request cleanup failed")
+                    : error;
+            }
+        }
+    }
+    /** Keep idle worker failures observed and prevent reuse of a retired thread. */
+    createWorker() {
+        const worker = new node_worker_threads_1.Worker(node_path_1.default.join(__dirname, "internal", "capabilityPluginWorker.js"));
+        const retire = () => {
+            if (this.worker === worker)
+                this.worker = undefined;
+        };
+        worker.on("error", (error) => {
+            this.failWorker(error instanceof Error ? error : new Error(String(error)));
+            retire();
+        });
+        const exited = new Promise((resolve) => worker.once("exit", (code) => {
+            if (code !== 0 || this.closing === undefined)
+                this.failWorker(new Error(`ttsc: capability worker exited ${code}${this.closing === undefined ? " unexpectedly" : ""}`));
+            retire();
+            resolve();
+        }));
+        this.exits.set(worker, exited);
+        worker.unref();
+        ++this.generation;
+        this.worker = worker;
+        return worker;
+    }
+    /** Retain failed ownership outcomes while treating requested abort as normal. */
+    rememberFailure(error) {
+        if (!(error instanceof Error) || error.name !== "AbortError")
+            this.failures.push(error);
+    }
+    /** Refuse new work after a thread fails with potentially unknown lease state. */
+    failWorker(error) {
+        this.rememberFailure(error);
+        this.closed = true;
+        for (const controller of this.controllers)
+            controller.abort(error);
+    }
+}
+exports.CapabilityPluginResolver = CapabilityPluginResolver;
+function writeCommandReply(reply, value) {
+    try {
+        node_fs_1.default.writeFileSync(reply.responseFile, (0, node_v8_1.serialize)(value));
+    }
+    finally {
+        Atomics.store(new Int32Array(reply.done), 0, 1);
+        Atomics.notify(new Int32Array(reply.done), 0);
+    }
+}
+//# sourceMappingURL=CapabilityPluginResolver.js.map

package/lib/plugin/CapabilityPluginResolver.js.map

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

package/lib/plugin/ITtscCapabilityPlugin.d.ts

@@ -0,0 +1,87 @@
+/**
+ * One plugin that declared the requested capability.
+ *
+ * `manifest` is the `--plugins-json` payload its sidecar needs to find its own
+ * configured entry. Consumers must forward the selected manifest rather than
+ * infer configuration from an empty capability answer; handling an absent
+ * manifest remains with the particular sidecar implementation.
+ *
+ * @evidence contracts/common.md#principled-implementation A selected sidecar carries its executable plus full plugin manifest and optional requested project identity, so it can locate its own configuration without rediscovering the project.
+ * @evidence contracts/common.md#clear-and-simple-design The result contains only invocation identity and payloads; discovery, building and sidecar lifetime remain with their owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Capability opt-in selects the sidecar, without package-name routing or a narrowed manifest that fabricates an empty configuration.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc explains why full manifest/context are necessary and absent projectContext meaning; paragraphs, member and tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Binary is a resolved native executable path; manifest and project-context are JSON argv payloads, not shell command text or POSIX path fragments.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This invocation-data type performs no discovery, build or publication algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This representation states invocation identity but owns no reusable work cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Paths and payloads are plain data; a caller that starts the sidecar owns its process lifetime.
+ */
+export interface ITtscCapabilityPlugin {
+    /** Absolute path of the plugin's native sidecar executable. */
+    binary: string;
+    /** The `--plugins-json` payload to pass to the sidecar. */
+    manifest: string;
+    /**
+     * The `--project-context-json` payload, or `undefined` when the plugin's
+     * descriptor does not declare it wants one.
+     *
+     * A context-capable sidecar receives the selected project identity to resolve
+     * its own inputs, such as claim documents or a schema. When this payload is
+     * absent, the sidecar owns its fallback or refusal policy; this result type
+     * does not certify an empty answer or independently resolve that context.
+     */
+    projectContext?: string;
+}
+/**
+ * A capability lookup and an opaque proof of its continued validity.
+ *
+ * A resolved empty list means no admitted sidecar matches the requested
+ * capability. An unavailable lookup also has no entries, but must be retried
+ * rather than retained as proof of absence. Even a resolved lookup can lack
+ * reusable proof, for example when a descriptor does not declare its external
+ * reads or config inheritance uses module resolution with unobserved selection
+ * authority.
+ *
+ * @evidence contracts/common.md#principled-implementation Status distinguishes completed lookup from degraded failure; the selected array contains only admitted nonempty-binary sidecars with the requested capability declared true. The owning freshness predicate separately decides reuse under its recorded premises, rather than an independently reconstructed consumer inventory.
+ * @evidence contracts/common.md#clear-and-simple-design Plugins, outcome and one opaque validity query expose the consumer's decisions without leaking persistent-cache format or requiring a second package resolver.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An unavailable or unproved lookup is not reusable empty success; only the owner can validate discovery and evaluation authorities.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc distinguishes empty resolved results, degraded failures and non-reusable resolved results; documented members and tag separation follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Platform/path proof remains with the ttsc owner; consumers receive resolved native sidecar data and a query rather than reproducing separator or case policy.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This result type executes no lookup algorithm; its producing function owns computation cost.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work The owning predicate is the sole discovery freshness authority; consumer-specific publication inputs remain a separate reuse premise.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The consumer owns this snapshot and its closure lifetime; no global result registry or sidecar handle is retained by the representation.
+ */
+export interface ITtscCapabilityPluginResolution {
+    /** Selected sidecars in configured order, empty for no match or unavailable. */
+    readonly plugins: readonly ITtscCapabilityPlugin[];
+    /** Whether lookup completed, distinct from an unavailable degraded answer. */
+    readonly status: "resolved" | "unavailable";
+    /**
+     * Whether this exact lookup still has a complete current owning proof.
+     *
+     * False requires lookup again before reusing dependent output. Cache removal,
+     * missing proof and observation failure are conservative false results.
+     */
+    readonly isCurrent: TtscCapabilityFreshnessQuery;
+}
+/**
+ * Query whether one capability lookup retains its complete owning proof.
+ *
+ * False requires lookup again before dependent output is reused. A consumer
+ * must also validate its own publication inputs; this query owns discovery and
+ * descriptor validity alone.
+ *
+ * @evidence contracts/common.md#principled-implementation The query validates the original lookup's owning premises and refuses unknown state without deciding a consumer's separate publication inputs.
+ * @evidence contracts/common.md#clear-and-simple-design A boolean query hides discovery and cache details while making required relookup explicit.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or failed proof cannot authorize reuse or be replaced with a guessed config-file inventory.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain false-result consequences and the consumer boundary before separated acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Owning native-path and process-authority checks define validity; the callback type embeds no OS-specific interpretation.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This callback type specifies a result and carries no implementation of observation traversal or hashing.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work True permits reuse only under the original complete discovery/evaluation identity; unavailable lookups always return false.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The query owns no sidecar. Its producer closure retains proof/context data while the result or a separately retained callback remains reachable; dropping the result alone does not release another reference to that callback.
+ */
+export type TtscCapabilityFreshnessQuery = () => boolean;

package/lib/plugin/ITtscCapabilityPlugin.js

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

package/lib/plugin/ITtscCapabilityPlugin.js.map

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

package/lib/plugin/internal/CapabilityPluginResult.d.ts

@@ -0,0 +1,66 @@
+import type { ITtscCapabilityPlugin, ITtscCapabilityPluginResolution } from "../ITtscCapabilityPlugin";
+/**
+ * Project capability selection and the resolver's caught unavailable outcome.
+ * These operations consume supplied discovery values; they neither acquire
+ * runtime authority nor establish the validity of a descriptor's observations.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact true declarations select nonempty binaries in input order; caught task failures remain unavailable rather than reusable empty success.
+ * @evidence contracts/common.md#clear-and-simple-design One internal concern owns selection and degraded result construction, without moving authority acquisition into its catch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied values are not native proof and no runtime, evaluator or compiler is substituted.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates supplied selection policy from discovery, authority and later freshness.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace groups data-selection and outcome functions; its initialization performs no native path, filesystem or process operation.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace itself defines members without computing a selection or executing a task; each operation owns its processing choices.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace owns no computed answer or reusable cache; resolver authority and persistence remain outside it.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no retained result collection, native handle or task lifecycle.
+ */
+export declare namespace CapabilityPluginResult {
+    /**
+     * Select declarations while forwarding the complete manifest and opted-in
+     * project context. Returned objects are fresh; their string values are kept.
+     *
+     * @evidence contracts/common.md#principled-implementation Only exact true declarations and nonempty binaries qualify; context requires its own true declaration and nonnull input.
+     * @evidence contracts/common.md#clear-and-simple-design One ordered filter and projection preserve the existing result shape.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection never narrows the complete supplied manifest or invents acquired context.
+     * @evidence contracts/common.md#meaningful-documentation Native prose identifies fresh result objects and the separate context gate.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Binary, manifest and context strings are forwarded unchanged as supplied data; selection neither interprets native paths nor acquires a process or filesystem observation.
+     * @evidence contracts/performance.md#efficient-algorithms For P supplied entries and Q admitted entries, one filter scans P and one map projects Q, with an intermediate Q-reference array and Q fresh result objects. Declaration lookups are ordinary property access; manifest/context strings are referenced rather than parsed or copied.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This projection decides no discovery freshness or expensive-computation reuse; the resolver owns those premises and this operation constructs fresh results each time.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Returned storage grows with Q admitted entries and retains supplied string values until its caller releases it. The operation stores no history, cache, callback or native handle beyond the returned caller-owned objects.
+     */
+    function select(resolution: {
+        manifest: string;
+        projectContext: string | null;
+        plugins: readonly {
+            binary: string;
+            capabilities: Record<string, boolean>;
+        }[];
+    }, capability: string): ITtscCapabilityPlugin[];
+    /**
+     * Construct fresh degraded absence with no reusable freshness claim.
+     *
+     * @evidence contracts/common.md#principled-implementation Unavailability always returns false freshness and an empty selection.
+     * @evidence contracts/common.md#clear-and-simple-design A single constructor owns this existing outcome shape.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Degraded absence is not evidence of missing publishers.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes unavailable from resolved empty success.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This constructor creates status data and a false predicate without native paths, I/O or platform decisions.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Fixed empty-result construction performs no input traversal or processing-strategy choice.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A fresh degraded result supplies no reusable computation or validity decision; its predicate is always false.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The caller owns plain returned data and a predicate capturing no external state; the constructor retains no collection, task or native handle.
+     */
+    function unavailable(): ITtscCapabilityPluginResolution;
+    /**
+     * Preserve the resolver's plugin-load/publication catch boundary. Callers
+     * acquire authority, inspect caches and resolve tools before supplying this
+     * task, so exceptions from those earlier operations remain outside it.
+     *
+     * @evidence contracts/common.md#principled-implementation Successful tasks retain the exact returned resolution; any exception inside the supplied task becomes unavailable.
+     * @evidence contracts/common.md#clear-and-simple-design One synchronous task boundary preserves the existing try/catch without wrapping prior acquisition.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The callback is the actual load/publication operation, not a replacement runtime or native producer.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states which exceptions are caught and which caller operations precede it.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Catching the supplied task's exception prescribes no native path or process representation; actual runtime and filesystem effects remain in the resolver task.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This wrapper chooses an outcome for one synchronous task, not that task's discovery, hashing, serialization or build algorithm. Its cost includes the full task, and no constant-time or bounded-native-work claim is made.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The wrapper neither retries nor caches the task and decides no equivalence or freshness; those policies remain with the supplied resolver operation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The wrapper retains neither the task nor its result after returning and acquires no handle or lease; any native resource lifetime and returned freshness closure remain with the task and caller.
+     */
+    function fromTask(task: () => ITtscCapabilityPluginResolution): ITtscCapabilityPluginResolution;
+}