@inflexa-ai/harness 0.34.0 → 0.35.1

package/dist/providers/prompt-cache.js

@@ -15,12 +15,53 @@
  * error — on an OpenAI-compatible model, which is exactly what we want: that
  * family does automatic server-side prefix caching and needs no directive.
  *
- * ## What the Anthropic namespace does
+ * ## What the Anthropic namespace does, and where the marker must go
  *
- * A request-level `cacheControl` makes the provider emit a single top-level
- * `cache_control` marker; the server then places the breakpoint on the last
- * cacheable block, so the whole prefix (tools → system → history) is cached
- * without the harness hand-placing per-block markers.
+ * The options go on the LAST MESSAGE of the request, never on the request
+ * itself. Both placements cache the same bytes — one breakpoint at the end of
+ * the messages covers the whole prefix (tools → system → history), because the
+ * cache keys on a prefix — but only the message placement survives an
+ * intermediary.
+ *
+ * A REQUEST-level `cacheControl` makes the provider emit a top-level
+ * `cache_control` field instead of a per-block marker, and the server then
+ * places the breakpoint itself. That is one fewer thing for the harness to get
+ * right, and it is why this module used to do it. It is also invisible: an
+ * intermediary that counts breakpoints to stay under Anthropic's cap of four
+ * counts BLOCKS, so a top-level field is a breakpoint nothing on the way
+ * upstream can see. CLIProxyAPI — what the OSS CLI routes through on the Claude
+ * OAuth path — injects up to four block markers of its own and trims to four by
+ * that blind count, so the harness's invisible fifth breakpoint made every
+ * request past a thread's first turn fail with `A maximum of 4 blocks with
+ * cache_control may be provided. Found 5.` (HTTP 400, non-retryable — the thread
+ * is wedged, because the next turn rebuilds the same shape).
+ *
+ * A marker on a message block is counted, trimmed, and reasoned about by every
+ * hop. Keep it there. {@link withPromptCacheBreakpoint} is the only writer.
+ *
+ * ## Which vendors need a marker at all
+ *
+ * Only two of them, and both take it on a message:
+ *
+ *  - **Anthropic** — `anthropic.cacheControl`. Fully opt-in: no marker, no
+ *    caching, at full price.
+ *  - **Amazon Bedrock** — `bedrock.cachePoint`. Also fully opt-in.
+ *
+ * The OpenAI family caches prefixes server-side, unprompted, and exposes no
+ * breakpoint to place (`promptCacheKey` and `promptCacheRetention` are request
+ * settings for affinity and retention, not placement — a separate concern from
+ * this policy). Gemini caches implicitly by default, and its explicit mode is a
+ * cache RESOURCE created out of band and referenced by name, which is not a
+ * marker and does not fit a ttl policy.
+ *
+ * So both markers ride together on the one chosen message. A provider reads only
+ * its own namespace, thus the pair is free to whichever vendor is not serving
+ * the call, and the placement never learns which one that is.
+ *
+ * The asymmetry worth remembering: under-marking silently costs money, while
+ * over-marking hard-fails. Anthropic answers 400 past four breakpoints, and the
+ * legacy Bedrock integration answers 400 on a top-level `cache_control`. Every
+ * failure in this area comes from asking for too much.
  *
  * ## Cache defeaters — what silently kills the hit rate
  *
@@ -43,13 +84,27 @@
  * `prompts/briefing.ts`). Keep it that way — one interpolated id or path there
  * makes every step's ~20k-char prefix unique.
  *
- * ## Where caching is a no-op regardless
+ * ## What the cache-token metrics do and do not prove
  *
- * The Claude Max OAuth path does not honour cache directives, and the OSS CLI
- * defaults to routing through a local CLIProxyAPI on exactly that path. Caching
- * only engages against a direct API key or a gateway. The cache-token metrics
- * (`loop/metrics.ts`) are what tell the two apart at runtime — a flat-zero
- * `cache_read_tokens` counter is the symptom.
+ * Caching DOES engage on the Claude OAuth path the OSS CLI routes through a
+ * local CLIProxyAPI: measured, 2050-2151 cache-read tokens on the turns after
+ * the first. An earlier note here claimed that path ignores cache directives
+ * outright. It does not.
+ *
+ * But a read there is not evidence that OUR breakpoint earned it. While cloaking
+ * — which is what that path does — the proxy places breakpoints of its own on
+ * the system block, the first user message, the system message it relocates, and
+ * the last message. Those cache the prefix whatever the harness sends: with
+ * `promptCache: "off"` and no marker of ours on the wire, a repeat request still
+ * read 1902 tokens back.
+ *
+ * So on that path `cache_read_tokens` (`loop/metrics.ts`) reports whether the
+ * deployment gets caching at all, which is what the counter is for. It does not
+ * attribute the read, and it cannot tell a working harness breakpoint from a
+ * proxy that is quietly doing the work. Against a direct API key or a gateway,
+ * where nothing injects markers, the counter does mean exactly that — and a
+ * flat-zero read counter beside a non-zero write counter is still the signature
+ * of an endpoint billing for writes and serving no reads.
  */
 /**
  * The default policy: cache with the 5-minute TTL.
@@ -67,11 +122,138 @@ export const DEFAULT_PROMPT_CACHE = { ttl: "5m" };
 /**
  * Translate a neutral cache policy into provider wire options.
  *
- * Returns `undefined` for `"off"` so the caller can leave `providerOptions`
- * entirely unset rather than sending an empty bag.
+ * Returns `undefined` for `"off"` so the caller can leave the bag entirely unset
+ * rather than sending an empty one.
+ *
+ * Both vendors that take an explicit marker get one, in their own namespace. A
+ * provider reads only its own key, so the pair costs nothing to whichever one is
+ * not serving the call, and the placement needs no idea which vendor it is
+ * talking to. The two shapes differ in more than spelling: Anthropic marks the
+ * last content block of the message, while Bedrock appends a `cachePoint` block
+ * after it. Both end up at the same position in the prefix.
+ *
+ * The `satisfies` clauses are the point of naming the vendor types at all. This
+ * bag is a `Record<string, JSONObject>`, thus nothing here is checked by
+ * default, and a renamed key would compile and silently stop caching —
+ * `cacheControl` has already been renamed once, and the provider still accepts
+ * `cache_control` as its alias.
+ *
+ * CAUTION: this is the marker's VALUE, not its placement. Attaching it to a
+ * `ChatRequest` emits the invisible top-level field the module header warns
+ * about. Place it with {@link withPromptCacheBreakpoint}.
  */
 export function promptCacheProviderOptions(policy) {
     if (policy === "off")
         return undefined;
-    return { anthropic: { cacheControl: { type: "ephemeral", ttl: policy.ttl } } };
+    const anthropic = { cacheControl: { type: "ephemeral", ttl: policy.ttl } };
+    const bedrock = { cachePoint: { type: "default", ttl: policy.ttl } };
+    return { anthropic, bedrock };
+}
+/**
+ * Every namespace that can carry a breakpoint, and the key it carries it under.
+ *
+ * The writer and the stripper both read this list, thus they cannot drift apart,
+ * and the one-breakpoint invariant covers each vendor rather than only the one
+ * that happens to be serving the call. `@ai-sdk/amazon-bedrock` reads either
+ * `bedrock` or `amazonBedrock`; its own documentation uses `bedrock`.
+ */
+const BREAKPOINT_SITES = [
+    ["anthropic", "cacheControl"],
+    ["bedrock", "cachePoint"],
+];
+/**
+ * Whether a message can HOST the breakpoint — that is, whether the marker put on
+ * it actually reaches the wire.
+ *
+ * The Anthropic provider resolves a message-level marker onto the message's last
+ * content part. A thinking block cannot carry `cache_control`, so a marker on an
+ * assistant message that ends in one is dropped by the provider: no error, no
+ * breakpoint, and a silent cache miss on every call after it. Walking back past
+ * such a message is what the server-side placement did for us before, so this
+ * keeps the behaviour rather than introducing a new failure mode.
+ *
+ * An empty content array hosts nothing either — there is no last part to mark.
+ * The content is read as `unknown` because the four message roles carry four
+ * different part unions and this predicate cares about exactly one field.
+ */
+function canHostBreakpoint(message) {
+    const content = message.content;
+    if (typeof content === "string")
+        return content.length > 0;
+    if (!Array.isArray(content))
+        return false;
+    const last = content.at(-1);
+    if (typeof last !== "object" || last === null)
+        return false;
+    return last.type !== "reasoning";
+}
+/** The index of the last message that can host the breakpoint, or `-1` when none can. */
+function lastHostIndex(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message !== undefined && canHostBreakpoint(message))
+            return i;
+    }
+    return -1;
+}
+/** Whether this message already carries a cache marker in ANY breakpoint namespace. */
+function carriesBreakpoint(message) {
+    return BREAKPOINT_SITES.some(([namespace, key]) => message.providerOptions?.[namespace]?.[key] !== undefined);
+}
+/** The same message with each namespace of `options` merged into its own bag. */
+function withBreakpoint(message, options) {
+    const merged = { ...message.providerOptions };
+    for (const [namespace] of BREAKPOINT_SITES) {
+        const marker = options[namespace];
+        if (marker === undefined)
+            continue;
+        merged[namespace] = { ...message.providerOptions?.[namespace], ...marker };
+    }
+    return { ...message, providerOptions: merged };
+}
+/** The same message with every marker removed, and each namespace dropped when it held nothing else. */
+function withoutBreakpoint(message) {
+    if (!carriesBreakpoint(message))
+        return message;
+    const remaining = { ...message.providerOptions };
+    for (const [namespace, key] of BREAKPOINT_SITES) {
+        const bag = remaining[namespace];
+        if (bag?.[key] === undefined)
+            continue;
+        const { [key]: _dropped, ...rest } = bag;
+        if (Object.keys(rest).length === 0)
+            delete remaining[namespace];
+        else
+            remaining[namespace] = rest;
+    }
+    return { ...message, providerOptions: remaining };
+}
+/**
+ * Place the request's ONE cache breakpoint, on the last message that can host it.
+ *
+ * Returns a copy — the caller's array is the transcript the loop keeps pushing
+ * onto and the host later persists, and a marker written into it would ride into
+ * the stored thread and come back on every later turn, one more breakpoint per
+ * turn until the request is refused. Only the request-shaped copy carries one.
+ *
+ * The placement is deliberately ROLLING, not pinned to the end of the stable
+ * prefix: within one run the loop appends an assistant reply and its tool results
+ * on every iteration, and a breakpoint that advances with them lets iteration N+1
+ * read back everything iteration N wrote. A pinned breakpoint would re-process
+ * the whole tool transcript uncached on every iteration, which is the opposite of
+ * what an agent loop needs.
+ *
+ * A marker already on any other message is REMOVED — the invariant is exactly one
+ * breakpoint per request, and a stored message that carries one from an older
+ * build (`memory/ai-sdk-message-storage.ts` reads `cache_control` back off a
+ * stored block) would otherwise spend a slot that the harness never budgeted.
+ * `"off"` strips and places nothing, so turning caching off really does send no
+ * directive at all.
+ */
+export function withPromptCacheBreakpoint(messages, policy) {
+    const options = promptCacheProviderOptions(policy);
+    const target = options === undefined ? -1 : lastHostIndex(messages);
+    if (target < 0 && !messages.some(carriesBreakpoint))
+        return messages;
+    return messages.map((message, index) => (index === target && options !== undefined ? withBreakpoint(message, options) : withoutBreakpoint(message)));
 }

package/dist/sandbox/client.d.ts

@@ -25,8 +25,17 @@
  * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
  * rule yet, thus a new caller must read this paragraph.
  */
-import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody } from "./types.js";
+import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody, ToolchainSource } from "./types.js";
 export interface SandboxClient {
+    /**
+     * The declared owner of the sandbox toolchain, as the client was composed
+     * with it: `"image"` when the config declared it, `"store"` when the config
+     * declared nothing. The mount plan and the orient-core prompt both key on
+     * this one value, thus the environment a sandbox gets and the text that
+     * describes it cannot disagree. Required rather than optional, because an
+     * optional field would carry two meanings, undeclared and unknown.
+     */
+    readonly toolchainSource: ToolchainSource;
     /**
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the

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

@@ -80,6 +80,18 @@ export interface CreateSandboxClientConfig {
      * this field existed.
      */
     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 neither backend makes a machine. Absent keeps
+     * the degrade: the store mounts drop, a warning is logged, and the
+     * sandbox reports the store as unavailable. 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";
     /** Docker: host dir bind-mounted read-only at `/mnt/refs`. */
     refStorePath?: string;
     /** Docker: force the container platform (e.g. `linux/amd64`) so the sandbox matches the mounted lib store's arch. */

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>;