@makaio/framework 1.0.0-dev-1785409369816 → 1.0.0-dev-1787670071418

package/dist/types-DnK6Wa_Y.d.mts

@@ -0,0 +1,260 @@
+import { z } from "zod";
+import { CodeExecutionFailedOutcomeCode, JsonValue } from "@makaio/framework/contracts";
+
+//#region runtimes/node/src/code-execution/types.d.ts
+/** Default maximum number of virtual files a submitted program may contain. */
+declare const CODE_EXECUTION_DEFAULT_MAX_PROGRAM_FILES = 256;
+/** Default maximum aggregate UTF-8 size of a submitted program's sources, in bytes (5 MiB). */
+declare const CODE_EXECUTION_DEFAULT_MAX_SOURCE_BYTES: number;
+/** Default maximum serialized JSON size of a handler result, in bytes (1 MiB). */
+declare const CODE_EXECUTION_DEFAULT_MAX_RESULT_BYTES: number;
+/**
+ * Default maximum serialized JSON size of an invocation's arguments, in bytes (1 MiB).
+ *
+ * The argument is the one part of a request no other budget measures, and it is
+ * retained for longer than any of them: a queued invocation holds it from
+ * admission until dispatch, and the pool then structured-clones it into the
+ * worker. Bounding it is what keeps a burst of large arguments from costing the
+ * host more than the configured concurrency implies.
+ *
+ * Matched to {@link CODE_EXECUTION_DEFAULT_MAX_RESULT_BYTES} deliberately: both
+ * bound one JSON value crossing the same thread boundary, in opposite
+ * directions, so a host that raises one usually means the pair.
+ */
+declare const CODE_EXECUTION_DEFAULT_MAX_ARGUMENT_BYTES: number;
+/** Default maximum number of concurrently executing worker threads. */
+declare const CODE_EXECUTION_DEFAULT_MAX_CONCURRENCY = 4;
+/**
+ * Default maximum number of invocations allowed to wait for an execution slot.
+ *
+ * Concurrency bounds what executes; this bounds what is *retained while
+ * waiting*. A queued invocation holds its whole request — up to
+ * {@link CODE_EXECUTION_DEFAULT_MAX_SOURCE_BYTES} of sources and
+ * {@link CODE_EXECUTION_DEFAULT_MAX_ARGUMENT_BYTES} of arguments — from arrival
+ * until dispatch, and its deadline is the caller's rather than the provider's,
+ * so an unbounded queue makes the host's retained memory a function of the
+ * arrival rate. Refusing past the cap keeps it a function of configuration.
+ *
+ * 16 is four times {@link CODE_EXECUTION_DEFAULT_MAX_CONCURRENCY}, so an
+ * ordinary burst still queues and is served rather than being refused, while
+ * the worst-case retained request set stays a small multiple of what the
+ * executing invocations already hold.
+ */
+declare const CODE_EXECUTION_DEFAULT_MAX_QUEUED_INVOCATIONS = 16;
+/** Default idle duration after which unused worker threads are reaped, in milliseconds. */
+declare const CODE_EXECUTION_DEFAULT_IDLE_TIMEOUT_MS = 30000;
+/**
+ * Default number of invocations a worker thread serves before it is retired.
+ *
+ * Every invocation adds a module graph to its worker's ESM module map, and Node
+ * never evicts one: the record is keyed by URL, and each invocation imports a
+ * freshly materialized program under a URL that has never been seen before. A
+ * worker that is never idle long enough to be reaped therefore grows without
+ * bound. Retiring it after a fixed number of invocations is what turns that
+ * into a bounded working set.
+ *
+ * 64 trades the two costs against each other: retirement pays one worker spawn
+ * and one TypeScript-loader bootstrap, which is worth amortizing, while the
+ * accumulated graphs of 64 bounded programs are not.
+ */
+declare const CODE_EXECUTION_DEFAULT_MAX_INVOCATIONS_PER_WORKER = 64;
+/**
+ * Composition options for the Piscina-backed CodeExecution provider.
+ *
+ * Every option is host-owned: the provider never derives capability, package
+ * availability, or environment from the submitted program.
+ */
+interface PiscinaCodeExecutionProviderOptions {
+  /**
+   * Provider identifier, bounded by the public CodeExecution identifier limit.
+   * @defaultValue `'piscina-code-execution'`
+   */
+  readonly id?: string;
+  /** Human-readable provider name. @defaultValue `'Local (Piscina)'` */
+  readonly displayName?: string;
+  /** Selection priority among matching providers; higher wins. @defaultValue 0 */
+  readonly priority?: number;
+  /** Maximum concurrent worker threads. @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_CONCURRENCY} */
+  readonly maxConcurrency?: number;
+  /**
+   * Invocations allowed to wait for an execution slot before the provider
+   * refuses further work.
+   *
+   * {@link maxConcurrency} bounds what executes; this bounds what is retained
+   * while waiting. A queued invocation holds its sources and its arguments from
+   * arrival until dispatch, under the caller's deadline rather than the
+   * provider's, so without this bound a burst of valid requests would grow the
+   * host's retained memory with the arrival rate.
+   *
+   * An invocation that arrives at a full queue is refused immediately — it is
+   * never enqueued — and reported as `provider_unavailable`. Zero disables
+   * queueing entirely: only what fits into a free slot right away is admitted.
+   * @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_QUEUED_INVOCATIONS}
+   */
+  readonly maxQueuedInvocations?: number;
+  /**
+   * Idle duration before worker threads are reaped, in milliseconds.
+   * @defaultValue {@link CODE_EXECUTION_DEFAULT_IDLE_TIMEOUT_MS}
+   */
+  readonly idleTimeoutMs?: number;
+  /**
+   * Invocations a worker thread serves before it is retired and replaced.
+   *
+   * Idle reaping alone does not bound a worker's memory: a pool that is
+   * continuously busy never goes idle, and every invocation permanently adds a
+   * module graph to its worker's ESM module map. This bound is what makes the
+   * working set a function of the configured value rather than of uptime.
+   *
+   * Enforced as a strict upper bound per thread, and reached sooner when
+   * {@link maxConcurrency} is above one — a whole generation of workers is
+   * retired together once the *generation* has served this many invocations, so
+   * no thread in it can have served more.
+   * @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_INVOCATIONS_PER_WORKER}
+   */
+  readonly maxInvocationsPerWorker?: number;
+  /**
+   * Environment variables visible to worker threads.
+   *
+   * Defaults to an empty object rather than the host process environment, so
+   * host secrets are not handed to executed code by accident. Node built-ins
+   * and filesystem access stay available regardless — this provider runs
+   * trusted code only and the environment is not a sandbox.
+   *
+   * Configured values are stripped from diagnostics before those can reach a
+   * contract failure, but only above a minimum length: a value of three
+   * characters or fewer occurs in ordinary prose, so redacting it would mangle
+   * the diagnostic it is meant to protect. Such a value is therefore **not**
+   * redacted and can appear verbatim in a bus-bound message — do not place a
+   * secret in an environment value that short. The length is measured on the
+   * whitespace-collapsed value, which is the form diagnostics are matched in.
+   *
+   * The resolved worker entry's own loader variables are applied *after* these,
+   * so a value here that happens to name one of them does not take effect: that
+   * loader is what bounds which ordinary packages a submitted program resolves,
+   * and it is provider-owned rather than host-configurable.
+   */
+  readonly environment?: Readonly<Record<string, string>>;
+  /**
+   * Ordinary bare package names the program may import, mapped to absolute
+   * package root directories.
+   *
+   * These packages are linked into the materialized program, and a resolve
+   * guard in the worker rejects every *other* ordinary import — including one
+   * an ambient `node_modules` above the temporary program root would otherwise
+   * satisfy. So the map is the whole truth about which packages a program can
+   * reach by name, on any host.
+   *
+   * It bounds bare specifiers and nothing else. Node built-ins, absolute and
+   * `file:` specifiers, and direct filesystem access all remain available to
+   * the executed code, and a configured package's own dependencies resolve
+   * within that package as usual — configuring a package vouches for what it
+   * depends on. This is a resolution boundary, not an isolation boundary.
+   */
+  readonly packageRoots?: Readonly<Record<string, string>>;
+  /** Maximum number of virtual files per program. @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_PROGRAM_FILES} */
+  readonly maxProgramFiles?: number;
+  /**
+   * Maximum aggregate UTF-8 source size per program, in bytes.
+   * @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_SOURCE_BYTES}
+   */
+  readonly maxSourceBytes?: number;
+  /**
+   * Maximum serialized JSON size of a handler result, in bytes.
+   * @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_RESULT_BYTES}
+   */
+  readonly maxResultBytes?: number;
+  /**
+   * Maximum serialized JSON size of an invocation's arguments, in bytes.
+   *
+   * Enforced before the invocation waits for an admission slot, and reported as
+   * `invalid_program`: the argument is part of what was submitted, so an
+   * over-budget one is a rejected request rather than a provider fault.
+   * @defaultValue {@link CODE_EXECUTION_DEFAULT_MAX_ARGUMENT_BYTES}
+   */
+  readonly maxArgumentBytes?: number;
+}
+/**
+ * Structured-clone-safe task handed to the worker entry for one invocation.
+ *
+ * The task carries only resolved primitives and JSON values. TypeScript
+ * transpilation and module loading happen in the worker thread, so no
+ * program source and no live host object crosses the boundary.
+ */
+interface CodeExecutionWorkerTask {
+  /**
+   * `file:` URL of the generated module that re-exports the program's entry namespace.
+   *
+   * Not the program's entry module itself. Importing that directly would let a
+   * program exporting a callable `then` hijack the import promise; see
+   * {@link CODE_EXECUTION_ENTRY_NAMESPACE_EXPORT}, which names the export this
+   * module carries the entry namespace on.
+   */
+  readonly entryNamespaceUrl: string;
+  /** `file:` URL used as the importing parent for the scoped import. */
+  readonly parentUrl: string;
+  /**
+   * `file:` URL prefixes identifying the modules the import allowlist applies to.
+   *
+   * Every spelling of the program root, each ending in a slash. Everything the
+   * worker resolves for its own module graph sits outside these prefixes and is
+   * therefore unaffected. More than one prefix is required because the module
+   * loader reports a module reached through a symlinked prefix by its real
+   * path, which is a different spelling of the same root.
+   */
+  readonly programRootUrls: readonly string[];
+  /**
+   * Ordinary bare package names the program is allowed to import.
+   *
+   * Carried per task rather than read from the worker's environment because the
+   * allowlist is a property of the host's composition, and the worker must be
+   * able to enforce it without knowing how the provider was configured. Node
+   * resolves a bare specifier by walking up from the importing module, so
+   * linking these packages into the program root is not by itself an
+   * allowlist — an ancestor `node_modules` would satisfy an unlisted import.
+   */
+  readonly allowedPackages: readonly string[];
+  /** Name of the export invoked on the entry module. */
+  readonly exportName: string;
+  /** JSON-safe value passed to the invoked export as its single argument. */
+  readonly arguments: JsonValue;
+  /** Per-invocation TypeScript loader namespace, isolating module caches between invocations. */
+  readonly namespace: string;
+  /** Maximum serialized JSON size of the handler result, in bytes. */
+  readonly maxResultBytes: number;
+  /**
+   * Values to strip from diagnostics before they leave the worker.
+   *
+   * Carries the materialized program paths for this invocation plus the
+   * host-configured values the provider knows are sensitive. Redacting in the
+   * worker as well as in the host keeps a long diagnostic from being truncated
+   * around a value the host would then no longer be able to match.
+   */
+  readonly redactedPaths: readonly string[];
+}
+/** Worker outcome for an invocation whose export returned a JSON-safe value the host revalidates after transfer. */
+interface CodeExecutionWorkerCompletedOutcome {
+  /** Discriminant for a completed invocation. */
+  readonly kind: 'completed';
+  /** JSON-safe value validated by the worker and revalidated by the host after transfer. */
+  readonly value: JsonValue;
+}
+/** Worker outcome for an invocation that failed inside the worker thread. */
+interface CodeExecutionWorkerFailedOutcome {
+  /** Discriminant for a failed invocation. */
+  readonly kind: 'failed';
+  /** Stable failure classification, already narrowed to a `failed` outcome code. */
+  readonly code: CodeExecutionFailedOutcomeCode;
+  /** Sanitized, bounded summary of what went wrong. */
+  readonly message: string;
+}
+/**
+ * Discriminated envelope the worker entry returns for every invocation.
+ *
+ * The worker resolves rather than rejects for expected failures so that only
+ * small, clone-safe values cross the thread boundary. Timeouts and
+ * cancellations are not represented here: those are observed by the host
+ * thread through the effective abort signal.
+ */
+type CodeExecutionWorkerOutcome = CodeExecutionWorkerCompletedOutcome | CodeExecutionWorkerFailedOutcome;
+//#endregion
+export { CODE_EXECUTION_DEFAULT_MAX_PROGRAM_FILES as a, CODE_EXECUTION_DEFAULT_MAX_SOURCE_BYTES as c, PiscinaCodeExecutionProviderOptions as d, CODE_EXECUTION_DEFAULT_MAX_INVOCATIONS_PER_WORKER as i, CodeExecutionWorkerOutcome as l, CODE_EXECUTION_DEFAULT_MAX_ARGUMENT_BYTES as n, CODE_EXECUTION_DEFAULT_MAX_QUEUED_INVOCATIONS as o, CODE_EXECUTION_DEFAULT_MAX_CONCURRENCY as r, CODE_EXECUTION_DEFAULT_MAX_RESULT_BYTES as s, CODE_EXECUTION_DEFAULT_IDLE_TIMEOUT_MS as t, CodeExecutionWorkerTask as u };