@inflexa-ai/harness 0.33.1 → 0.35.0

package/dist/sandbox/create-sandbox.js

@@ -23,6 +23,7 @@ import { awaitExec } from "./await-exec.js";
 import { createDockerSandboxOps } from "./docker-client.js";
 import { createK8sSandboxOps } from "./k8s-client.js";
 import { sandboxWriteTail } from "./mount-plan.js";
+import { SandboxFailure } from "./sandbox-error.js";
 import { submitExec } from "./submit-exec.js";
 import { toPersistedRef } from "./types.js";
 /**
@@ -73,6 +74,39 @@ export async function precreateStepTree(deps, meta) {
 export function createSandboxClient(config) {
     const backend = config.backend ?? config.env.backend;
     const transport = config.transport ?? "poll";
+    // Normalized once, here, and handed to the backends and to the client
+    // alike: the mount plan and the orient-core prompt then key on one value,
+    // and an absent declaration means "store" on both sides.
+    const toolchainSource = config.toolchainSource ?? "store";
+    // The declared fact needs a gate that can prove it. Each combination below
+    // leaves the backend with no gate at all, thus the fact could never be
+    // proved and every create would pass an unproved store. The refusal is at
+    // composition, where the embedder states the fact — the same rule as the
+    // tail-beside-readOnly throw in `mount-plan.ts` — because a contradiction
+    // found at the first sandbox costs a whole run. A K8s `per-analysis` farm
+    // source with no `libStorePvcRoot` is NOT a contradiction: there the
+    // resolver owes the proof, and its refusal already stops the create.
+    if (config.packageStore === "required") {
+        if (backend === "docker" && !config.libStorePath) {
+            throw new Error("createSandboxClient: packageStore is required but no libStorePath is configured — the docker lock gate has no store to prove");
+        }
+        if (backend === "k8s" && !config.libStorePvc) {
+            throw new Error("createSandboxClient: packageStore is required but no libStorePvc is configured — the k8s lock gate has no store to prove");
+        }
+        if (backend === "k8s" && config.farmSource.kind === "fixed" && !config.libStorePvcRoot) {
+            throw new Error("createSandboxClient: packageStore is required but a fixed farm source has no libStorePvcRoot — no resolver and no host-side gate can prove the store");
+        }
+    }
+    /**
+     * What the seam throws for a backend failure: the description of the
+     * variant as the message, and the variant itself on `cause`. The `mapErr`
+     * happens before the bridge because `toThrowable` passes an `Error`
+     * through untouched — thus `unwrapOrThrow` stays the single sanctioned
+     * Result→throw bridge, no second bridge is introduced, and the
+     * `must-use-result` lint patch keeps recognizing every site. The registry
+     * unwraps below stay on the plain bridge: they carry a `DbError`.
+     */
+    const failing = (e) => new SandboxFailure(e);
     const registerSandbox = async (meta, ref) => {
         unwrapOrThrow(await setSandboxRef(config.pool, meta.runId, meta.stepId, toPersistedRef(ref), meta.execId ?? null));
     };
@@ -88,7 +122,8 @@ export function createSandboxClient(config) {
             libStorePvc: config.libStorePvc,
             libStorePvcRoot: config.libStorePvcRoot,
             farmSource: config.farmSource,
-            toolchainSource: config.toolchainSource,
+            toolchainSource,
+            packageStore: config.packageStore,
             refStorePvc: config.refStorePvc,
             nodeSelector: config.nodeSelector,
             tolerations: config.tolerations,
@@ -103,7 +138,8 @@ export function createSandboxClient(config) {
             resolveWorkspaceRoot: config.resolveWorkspaceRoot,
             libStorePath: config.libStorePath,
             farmSource: config.farmSource,
-            toolchainSource: config.toolchainSource,
+            toolchainSource,
+            packageStore: config.packageStore,
             refStorePath: config.refStorePath,
             platform: config.platform,
             engineSocketPath: config.engineSocketPath,
@@ -115,7 +151,7 @@ export function createSandboxClient(config) {
     // ref + step coordinates and the wrapper does the clear after the
     // backend-level removal.
     const teardown = async (ref) => {
-        unwrapOrThrow(await ops.teardown(ref));
+        unwrapOrThrow((await ops.teardown(ref)).mapErr(failing));
         // Sandboxes are 1-per-step (see `sandbox-step.ts` body — each child
         // workflow calls `createSandbox` once then `teardown` once), so the
         // broad WHERE clause matches exactly one row. If that invariant ever
@@ -132,8 +168,9 @@ export function createSandboxClient(config) {
     };
     // One arbiter for both surfaces: the client's `isAlive` method and the
     // poll loop's escalation probe are the same backend inspect.
-    const isAlive = async (ref) => unwrapOrThrow(await ops.isAlive(ref));
+    const isAlive = async (ref) => unwrapOrThrow((await ops.isAlive(ref)).mapErr(failing));
     return {
+        toolchainSource,
         createSandbox: async (meta, identity) => {
             // The config states an engine fact (binds preserve host ownership);
             // which remediation that fact demands — today, a world-writable step
@@ -150,7 +187,7 @@ export function createSandboxClient(config) {
             }
             // Clamp to cluster ceilings so the pod is always quota-admissible.
             const resources = clampResources(meta.resources, config.resourceLimits);
-            return unwrapOrThrow(await ops.createSandbox({ ...meta, resources }, identity));
+            return unwrapOrThrow((await ops.createSandbox({ ...meta, resources }, identity)).mapErr(failing));
         },
         submitExec: async (ref, body) => submitExec(ref, body, {
             ...config.submitDeps,
@@ -163,10 +200,10 @@ export function createSandboxClient(config) {
         // retention budget and still returns whole streams.
         awaitExec: async (ref, execId, emit, deadline) => capExecStreams(await awaitExec(ref, execId, emit, deadline, composeAwaitOptions(config.awaitOptions, transport, isAlive)), config.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP),
         isAlive,
-        isAliveById: async (sandboxId) => unwrapOrThrow(await ops.isAliveById(sandboxId)),
+        isAliveById: async (sandboxId) => unwrapOrThrow((await ops.isAliveById(sandboxId)).mapErr(failing)),
         teardown,
-        teardownById: async (sandboxId) => unwrapOrThrow(await ops.teardownById(sandboxId)),
-        listManagedSandboxes: async () => unwrapOrThrow(await ops.listManagedSandboxes()),
+        teardownById: async (sandboxId) => unwrapOrThrow((await ops.teardownById(sandboxId)).mapErr(failing)),
+        listManagedSandboxes: async () => unwrapOrThrow((await ops.listManagedSandboxes()).mapErr(failing)),
     };
 }
 /** Re-exports so consumers import once from this module. */

package/dist/sandbox/docker-client.d.ts

@@ -63,6 +63,17 @@ export interface DockerClientConfig {
     farmSource: FarmSource;
     /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable` and no container is made. Absent keeps the
+     * degrade: the store mounts drop, a warning is logged, and the container
+     * is still made. The field names the deployment fact rather than the
+     * remediation, so how the harness answers it can evolve without changing
+     * the embedder surface; a single-valued union (not a boolean) so future
+     * store classes extend it without a breaking change.
+     */
+    packageStore?: "required";
     /**
      * Host ref store; bind-mounted read-only at `/mnt/refs`. Embedders pass the
      * configured store location unconditionally — existence is (re-)checked at each

package/dist/sandbox/docker-client.js

@@ -246,15 +246,29 @@ export function createDockerSandboxOps(config) {
                     farm = resolved.value;
                 }
                 // The `inflexa.lock` gate runs at each create: the store may have
-                // gone away, or the farm may be half-written. A gate failure
-                // degrades — both store mounts drop, the container is still made,
-                // and the sandbox reports the store as unavailable. The warning is
-                // logged because an otherwise-silent mount drop is invisible to
-                // operators.
+                // gone away, or the farm may be half-written. The failure has two
+                // outcomes. Under the declared fact the call refuses with
+                // `farm_unusable` before any container work, and it logs nothing:
+                // the returned value carries the reason, and the consumer logs the
+                // throw, thus a warning here would record the one fault twice.
+                // Without the fact it degrades — both store mounts drop, the
+                // container is still made, and the sandbox reports the store as
+                // unavailable. That drop is otherwise silent, thus it is warned.
                 let libsMounted = false;
                 if (config.libStorePath && farm) {
                     const lock = readFarmLock(farm.farmPath);
                     libsMounted = lock.isOk();
+                    if (lock.isErr() && config.packageStore === "required") {
+                        return err({
+                            type: "farm_unusable",
+                            op: "docker.createSandbox",
+                            analysisId: meta.analysisId,
+                            farmPath: farm.farmPath,
+                            lockPath: lock.error.lockPath,
+                            lockError: lock.error.type,
+                            cause: lock.error.cause,
+                        });
+                    }
                     if (lock.isErr()) {
                         logger.warn("the farm of the analysis has no usable inflexa.lock at sandbox creation — mounting no package store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, farmPath: farm.farmPath, lockError: lock.error.type, sandboxId });
                     }

package/dist/sandbox/farm.d.ts

@@ -10,7 +10,9 @@
  * - A resolver refusal (`unavailable`, or a throw) is a `farm_unavailable`
  *   `SandboxError` — the call refuses and no container is made.
  * - A lock-gate failure degrades — the backend drops both store mounts,
- *   logs a warning, and still makes the container.
+ *   logs a warning, and still makes the container. Under a config that
+ *   declares `packageStore: "required"`, the same failure refuses with
+ *   `farm_unusable`, and no container is made.
  */
 import { type Result } from "neverthrow";
 import { z } from "zod";

package/dist/sandbox/farm.js

@@ -10,7 +10,9 @@
  * - A resolver refusal (`unavailable`, or a throw) is a `farm_unavailable`
  *   `SandboxError` — the call refuses and no container is made.
  * - A lock-gate failure degrades — the backend drops both store mounts,
- *   logs a warning, and still makes the container.
+ *   logs a warning, and still makes the container. Under a config that
+ *   declares `packageStore: "required"`, the same failure refuses with
+ *   `farm_unusable`, and no container is made.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/sandbox/image-packages.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `image-packages.json` — the self-description of the sandbox image.
+ *
+ * The image bakes two package tracks that the content-addressed store cannot
+ * hold: the conda tools at `/opt/conda` and the Node packages at `/opt/node`.
+ * The image writes one record of them at `/opt/inflexa/image-packages.json`,
+ * and the catalog build copies that record verbatim into the root of the
+ * package store it packed beside it. Thus every reader of a store learns the
+ * image inventory from the store alone — with no container engine, no
+ * registry client, and no path outside the store.
+ *
+ * The record is JSON with a `schema` number, the same convention as
+ * {@link FarmLockSchema}: an additive field passes through untouched, and a
+ * breaking change to the shape moves the number instead. A structured record
+ * is what lets a row carry its version, and what lets a later change compare
+ * the recorded image against the configured one.
+ *
+ * This schema is the ONE definition of the shape. The image writes the bytes
+ * and the harness validates them, thus a producer that drifts is refused here
+ * rather than half-read downstream.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+/**
+ * The file name of the record, at the root of the package store. Exported,
+ * as `FARM_LOCK_FILE` is, thus an embedder that joins the path onto its own
+ * store root never spells the name by hand.
+ */
+export declare const IMAGE_PACKAGES_FILE = "image-packages.json";
+/** The image the record describes. The pair of tags shares one version string. */
+export declare const ImageIdentitySchema: z.ZodObject<{
+    repository: z.ZodString;
+    version: z.ZodString;
+    arch: z.ZodEnum<{
+        amd64: "amd64";
+        arm64: "arm64";
+    }>;
+}, z.core.$loose>;
+/** The interpreter versions of the image, so a reader can compare them against the lock. */
+export declare const ImageRuntimesSchema: z.ZodObject<{
+    python: z.ZodString;
+    r: z.ZodString;
+    node: z.ZodString;
+}, z.core.$loose>;
+/**
+ * One conda tool of the image. `executable` carries the binary name when it
+ * differs from the package name (the manifest `binaries:` map holds those
+ * exceptions), because an agent invokes the binary and not the package.
+ */
+export declare const ImageSystemToolSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    executable: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** One Node package of the image. */
+export declare const ImageNodePackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+}, z.core.$loose>;
+/**
+ * `image-packages.json` at schema version 1. The keys `system_tools` and
+ * `node` are the keys of the image manifest, thus one name means one track
+ * across the build and the reader.
+ */
+export declare const ImagePackagesSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    image: z.ZodObject<{
+        repository: z.ZodString;
+        version: z.ZodString;
+        arch: z.ZodEnum<{
+            amd64: "amd64";
+            arm64: "arm64";
+        }>;
+    }, z.core.$loose>;
+    runtimes: z.ZodObject<{
+        python: z.ZodString;
+        r: z.ZodString;
+        node: z.ZodString;
+    }, z.core.$loose>;
+    system_tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        executable: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    node: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ImagePackages = z.infer<typeof ImagePackagesSchema>;
+export type ImagePackagesError = {
+    readonly type: "record_unreadable";
+    readonly recordPath: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "record_invalid";
+    readonly recordPath: string;
+    readonly cause: unknown;
+};
+/**
+ * Read and validate one `image-packages.json` by its file path. The read is
+ * synchronous, the same as {@link readFarmLockFile}, because the caller reads
+ * the record on each call and a store download can land while the process
+ * runs. Both errors are normal states of a host that reads a store from
+ * before this record existed.
+ */
+export declare function readImagePackagesFile(recordPath: string): Result<ImagePackages, ImagePackagesError>;

package/dist/sandbox/image-packages.js

@@ -0,0 +1,107 @@
+/**
+ * `image-packages.json` — the self-description of the sandbox image.
+ *
+ * The image bakes two package tracks that the content-addressed store cannot
+ * hold: the conda tools at `/opt/conda` and the Node packages at `/opt/node`.
+ * The image writes one record of them at `/opt/inflexa/image-packages.json`,
+ * and the catalog build copies that record verbatim into the root of the
+ * package store it packed beside it. Thus every reader of a store learns the
+ * image inventory from the store alone — with no container engine, no
+ * registry client, and no path outside the store.
+ *
+ * The record is JSON with a `schema` number, the same convention as
+ * {@link FarmLockSchema}: an additive field passes through untouched, and a
+ * breaking change to the shape moves the number instead. A structured record
+ * is what lets a row carry its version, and what lets a later change compare
+ * the recorded image against the configured one.
+ *
+ * This schema is the ONE definition of the shape. The image writes the bytes
+ * and the harness validates them, thus a producer that drifts is refused here
+ * rather than half-read downstream.
+ */
+import { readFileSync } from "node:fs";
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/**
+ * The file name of the record, at the root of the package store. Exported,
+ * as `FARM_LOCK_FILE` is, thus an embedder that joins the path onto its own
+ * store root never spells the name by hand.
+ */
+export const IMAGE_PACKAGES_FILE = "image-packages.json";
+/** The image the record describes. The pair of tags shares one version string. */
+export const ImageIdentitySchema = z
+    .object({
+    repository: z.string(),
+    version: z.string(),
+    arch: z.enum(["amd64", "arm64"]),
+})
+    .passthrough();
+/** The interpreter versions of the image, so a reader can compare them against the lock. */
+export const ImageRuntimesSchema = z
+    .object({
+    python: z.string(),
+    r: z.string(),
+    node: z.string(),
+})
+    .passthrough();
+/**
+ * One conda tool of the image. `executable` carries the binary name when it
+ * differs from the package name (the manifest `binaries:` map holds those
+ * exceptions), because an agent invokes the binary and not the package.
+ */
+export const ImageSystemToolSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+    executable: z.string().optional(),
+})
+    .passthrough();
+/** One Node package of the image. */
+export const ImageNodePackageSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+})
+    .passthrough();
+/**
+ * `image-packages.json` at schema version 1. The keys `system_tools` and
+ * `node` are the keys of the image manifest, thus one name means one track
+ * across the build and the reader.
+ */
+export const ImagePackagesSchema = z
+    .object({
+    schema: z.literal(1),
+    image: ImageIdentitySchema,
+    runtimes: ImageRuntimesSchema,
+    system_tools: z.array(ImageSystemToolSchema),
+    node: z.array(ImageNodePackageSchema),
+})
+    .passthrough();
+/**
+ * Read and validate one `image-packages.json` by its file path. The read is
+ * synchronous, the same as {@link readFarmLockFile}, because the caller reads
+ * the record on each call and a store download can land while the process
+ * runs. Both errors are normal states of a host that reads a store from
+ * before this record existed.
+ */
+export function readImagePackagesFile(recordPath) {
+    let raw;
+    try {
+        raw = readFileSync(recordPath, "utf8");
+    }
+    catch (cause) {
+        return err({ type: "record_unreadable", recordPath, cause });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return err({ type: "record_invalid", recordPath, cause });
+    }
+    const record = ImagePackagesSchema.safeParse(parsed);
+    if (!record.success) {
+        return err({ type: "record_invalid", recordPath, cause: record.error });
+    }
+    return ok(record.data);
+}

package/dist/sandbox/k8s-client.d.ts

@@ -71,6 +71,17 @@ export interface K8sClientConfig {
     farmSource: FarmSource;
     /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable` and no Job is made. Absent keeps the degrade: the
+     * store mounts drop, a warning is logged, and the Job is still made. The
+     * field names the deployment fact rather than the remediation, so how the
+     * harness answers it can evolve without changing the embedder surface; a
+     * single-valued union (not a boolean) so future store classes extend it
+     * without a breaking change.
+     */
+    packageStore?: "required";
     /** PVC claim mounted read-only at `/mnt/refs` when set. */
     refStorePvc?: string;
     /** Node selector pinning sandbox pods to the dedicated agent pool. Omit for default scheduling. */

package/dist/sandbox/k8s-client.js

@@ -465,14 +465,30 @@ export function createK8sSandboxOps(config) {
                 // The `inflexa.lock` gate, for a host that mounts the libs
                 // volume itself. The resolver owes the proof either way,
                 // but a farm half-written between the resolution and this
-                // create still mounts without a second look. A gate failure
-                // degrades exactly as the Docker backend does: no store
-                // mount, the Job is still made, and the sandbox reports the
-                // store as unavailable.
+                // create still mounts without a second look. The failure
+                // has the two outcomes of the Docker backend. Under the
+                // declared fact the call refuses with `farm_unusable`
+                // before any cluster work, and it logs nothing: the
+                // returned value carries the reason, and the consumer logs
+                // the throw, thus a warning here would record the one fault
+                // twice. Without the fact it degrades — no store mount, the
+                // Job is still made, and the sandbox reports the store as
+                // unavailable.
                 let libsMounted = !!config.libStorePvc;
                 if (config.libStorePvc && config.libStorePvcRoot && farm) {
                     const lock = readFarmLock(join(config.libStorePvcRoot, farm.farmPath));
                     libsMounted = lock.isOk();
+                    if (lock.isErr() && config.packageStore === "required") {
+                        return err({
+                            type: "farm_unusable",
+                            op: "k8s.createSandbox",
+                            analysisId: meta.analysisId,
+                            farmPath: farm.farmPath,
+                            lockPath: lock.error.lockPath,
+                            lockError: lock.error.type,
+                            cause: lock.error.cause,
+                        });
+                    }
                     if (lock.isErr()) {
                         (config.logger ?? createNoopLogger())
                             .named("k8s-client")

package/dist/sandbox/sandbox-error.d.ts

@@ -26,10 +26,12 @@
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, then
- * `unwrapOrThrow`s each op's `ResultAsync` so the seam re-throws a genuine
- * `SandboxError`. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
+ * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
+ * seam throws the described failure with the variant on `.cause` and on
+ * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
+ * exception — it is already its own DBOS step and throws directly, so the seam
+ * forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
  * non-workflow consumers (`reaper`, `watchdog`,
@@ -37,6 +39,7 @@
  * untouched by this wave.
  */
 import { ResultAsync } from "neverthrow";
+import type { FarmLockError } from "./farm.js";
 /**
  * A sandbox backend failure. Absence / idempotent "already gone" is NOT
  * modelled — those ride the OK channel (`ok(false)` for a dead/missing machine,
@@ -91,6 +94,22 @@ export type SandboxError = {
     readonly analysisId: string;
     readonly reason: string;
     readonly cause?: unknown;
+} | {
+    /**
+     * The gate proved the `inflexa.lock` at the resolved farm and the
+     * farm is not usable. Raised only when the config declares
+     * `packageStore: "required"`; without the fact the same gate
+     * failure degrades to no store mount. The sibling
+     * `farm_unavailable` is the resolver refusing to name a farm at
+     * all — here a farm was named, and its lock does not hold up.
+     */
+    readonly type: "farm_unusable";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly farmPath: string;
+    readonly lockPath: string;
+    readonly lockError: FarmLockError["type"];
+    readonly cause: unknown;
 };
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -100,8 +119,24 @@ export type SandboxError = {
  * `typeof === "number"` to avoid returning it as a status.
  */
 export declare function sandboxStatusOf(cause: unknown): number | undefined;
-/** A one-line, user-facing description of a `SandboxError` for logs/error bodies. */
+/**
+ * A one-line, user-facing description of a `SandboxError` for logs/error
+ * bodies. The variant gives the head. Where the cause names a reason, that
+ * bounded line closes the description, thus the engine or the parser says why
+ * on the operator surfaces.
+ */
 export declare function describeSandboxError(e: SandboxError): string;
+/**
+ * The throw of the `SandboxClient` seam. The message is
+ * `describeSandboxError`, thus a surface that renders a message alone still
+ * names the fault and its reason. The variant rides two ways: on `cause`, so
+ * a cause-chain reader keeps working, and on `error`, so a consumer that
+ * matches the class reads the typed fields without a walk.
+ */
+export declare class SandboxFailure extends Error {
+    readonly error: SandboxError;
+    constructor(error: SandboxError);
+}
 /**
  * Wrap a single sandbox backend call (Docker SDK op, K8s API op, or the
  * `/exec` POST). A throw becomes `err(toError(status, cause))`; the caller

package/dist/sandbox/sandbox-error.js

@@ -26,10 +26,12 @@
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, then
- * `unwrapOrThrow`s each op's `ResultAsync` so the seam re-throws a genuine
- * `SandboxError`. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
+ * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
+ * seam throws the described failure with the variant on `.cause` and on
+ * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
+ * exception — it is already its own DBOS step and throws directly, so the seam
+ * forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
  * non-workflow consumers (`reaper`, `watchdog`,
@@ -37,6 +39,7 @@
  * untouched by this wave.
  */
 import { ResultAsync, err, ok } from "neverthrow";
+import { ZodError } from "zod";
 const _assertDomainError = true;
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -51,8 +54,62 @@ export function sandboxStatusOf(cause) {
         return e.code;
     return e.statusCode ?? e.response?.statusCode;
 }
-/** A one-line, user-facing description of a `SandboxError` for logs/error bodies. */
+/**
+ * The bound on the appended cause line — the same 200 characters the profile
+ * ledger keeps (`tasks/data-profile.ts`), because a description reaches that
+ * ledger and the run row. A stack trace and an engine response body must stay
+ * out of a row, so the line is cut and marked rather than carried whole.
+ */
+const CAUSE_LINE_MAX = 200;
+/**
+ * The one bounded line that names the reason of a cause, or `undefined` when
+ * the cause carries no reason to name.
+ *
+ * A `ZodError` is special-cased: its `message` is multi-line JSON whose first
+ * line is `[`, which names nothing. Thus a zod cause renders as its first
+ * issue — the path and the message — and the reader sees which field broke.
+ * Any other cause gives the first line of its message.
+ */
+function causeLine(cause) {
+    let text;
+    if (cause instanceof ZodError) {
+        const issue = cause.issues[0];
+        if (!issue)
+            return undefined;
+        const path = issue.path.join(".");
+        text = path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    }
+    else if (cause instanceof Error) {
+        text = cause.message;
+    }
+    else if (typeof cause === "string") {
+        text = cause;
+    }
+    else {
+        return undefined;
+    }
+    const first = text.split("\n", 1)[0].trim();
+    if (first.length === 0)
+        return undefined;
+    return first.length > CAUSE_LINE_MAX ? `${first.slice(0, CAUSE_LINE_MAX - 1)}…` : first;
+}
+/**
+ * A one-line, user-facing description of a `SandboxError` for logs/error
+ * bodies. The variant gives the head. Where the cause names a reason, that
+ * bounded line closes the description, thus the engine or the parser says why
+ * on the operator surfaces.
+ */
 export function describeSandboxError(e) {
+    // `farm_unavailable` is the one variant whose head already carries its
+    // reason, the text of the resolver. A cause line after it would put two
+    // dashes on one row, and the throw of a resolver is in the log with its
+    // stack. Every other variant names its reason only through the cause.
+    const line = e.type === "farm_unavailable" ? undefined : causeLine(e.cause);
+    const head = describeVariant(e);
+    return line === undefined ? head : `${head} — ${line}`;
+}
+/** The head of a description: what failed, at which op, on which subject. */
+function describeVariant(e) {
     switch (e.type) {
         case "container_create_failed":
             return `sandbox create failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
@@ -68,6 +125,23 @@ export function describeSandboxError(e) {
             return `sandbox liveness probe failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
         case "farm_unavailable":
             return `farm unavailable (${e.op}: ${e.analysisId}) — ${e.reason}`;
+        case "farm_unusable":
+            return `farm unusable (${e.op}: ${e.analysisId}, ${e.lockError} at ${e.lockPath})`;
+    }
+}
+/**
+ * The throw of the `SandboxClient` seam. The message is
+ * `describeSandboxError`, thus a surface that renders a message alone still
+ * names the fault and its reason. The variant rides two ways: on `cause`, so
+ * a cause-chain reader keeps working, and on `error`, so a consumer that
+ * matches the class reads the typed fields without a walk.
+ */
+export class SandboxFailure extends Error {
+    error;
+    constructor(error) {
+        super(describeSandboxError(error), { cause: error });
+        this.error = error;
+        this.name = "SandboxFailure";
     }
 }
 /**