@inflexa-ai/harness 0.31.1 → 0.33.0

package/dist/report-render/views/references-view.d.ts

@@ -16,10 +16,26 @@ import { type DerivationChains, type ReferenceLedger } from "../references.js";
  *
  * A bracket reads as a reference inside prose, and it stays a span beside the words. One notation serves
  * every kind, thus one list answers every marker.
+ *
+ * Every grounded kind renders its marker here. Thus the lineage control has one emission point, and a
+ * marker that names no place carries no control. The page shows the control only where a stamp gives the
+ * script a key to walk.
  */
-export declare function Marker({ n }: {
+export declare function Marker({ n, lineage }: {
     n: number;
+    lineage?: number;
 }): import("hono/jsx/jsx-dev-runtime").JSX.Element;
+/**
+ * The count of hash characters that a chain line shows.
+ *
+ * A content hash is 64 hex characters, and a line that carries three whole ones reads as noise. The head
+ * identifies the bytes, and it matches the count that a staged file name carries. Thus a reader compares the
+ * two by sight.
+ *
+ * The appendix line and the hop of the lineage popover both cut a hash to this count. Thus one hash reads
+ * the same in the two places.
+ */
+export declare const CHAIN_HASH_CHARS = 12;
 /**
  * The one appendix list: one entry for each distinct reference of the page, in the order of the ladder.
  *

package/dist/report-render/views/references-view.js

@@ -1,14 +1,19 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "hono/jsx/jsx-runtime";
 import { citationRecordOf } from "../../report-model/reference-resolver.js";
 import { citationKeyOf } from "../references.js";
+import { LineageControl } from "./lineage.js";
 /**
  * One evidence marker as a bracket number that links to its appendix entry.
  *
  * A bracket reads as a reference inside prose, and it stays a span beside the words. One notation serves
  * every kind, thus one list answers every marker.
+ *
+ * Every grounded kind renders its marker here. Thus the lineage control has one emission point, and a
+ * marker that names no place carries no control. The page shows the control only where a stamp gives the
+ * script a key to walk.
  */
-export function Marker({ n }) {
-    return (_jsx("span", { class: "report-marker", children: _jsx("a", { href: `#ref-${n}`, children: `[${n}]` }) }));
+export function Marker({ n, lineage }) {
+    return (_jsxs("span", { class: "report-marker", children: [_jsx("a", { href: `#ref-${n}`, children: `[${n}]` }), lineage !== undefined ? _jsx(LineageControl, { place: lineage }) : null] }));
 }
 /** The kind label of one reference entry. */
 function RefKind({ children }) {
@@ -32,8 +37,11 @@ function HashCode({ children }) {
  * A content hash is 64 hex characters, and a line that carries three whole ones reads as noise. The head
  * identifies the bytes, and it matches the count that a staged file name carries. Thus a reader compares the
  * two by sight.
+ *
+ * The appendix line and the hop of the lineage popover both cut a hash to this count. Thus one hash reads
+ * the same in the two places.
  */
-const CHAIN_HASH_CHARS = 12;
+export const CHAIN_HASH_CHARS = 12;
 /** The head of one content hash: the hex after the algorithm name, cut to the shown length. */
 function hashHead(hash) {
     return hash.slice(hash.lastIndexOf(":") + 1).slice(0, CHAIN_HASH_CHARS);

package/dist/report-render/views/values.d.ts

@@ -26,6 +26,7 @@
 import type { CitationBlock, FigureBlock, MetricBlock, TableBlock } from "../../contracts/report-blocks.js";
 import { type ArtifactTableReference } from "../../contracts/report-reference.js";
 import type { CitationRecord } from "../../report-model/reference-resolver.js";
+import { type ViewOptions } from "./lineage.js";
 import { type ReferenceLedger } from "../references.js";
 import type { ColumnDisplay } from "../table-data.js";
 import type { RenderValue } from "../types.js";
@@ -76,8 +77,11 @@ type FigureValue = Extract<RenderValue, {
  * The value binding joins the reference ladder, thus the label line carries the marker and the appendix
  * names the cell. The marker sits on the label and never on the value, because the value line is the one
  * figure that a reader takes from the card.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export declare function renderMetric(block: MetricBlock, ledger: ReferenceLedger, value: ScalarValue): string;
+export declare function renderMetric(block: MetricBlock, ledger: ReferenceLedger, value: ScalarValue, view?: ViewOptions): string;
 /**
  * Wrap a run of stat cards in one responsive grid. The caller renders each card first, and it passes the
  * markup as one already-escaped string, thus `raw()` inserts it byte for byte. The grid carries its own
@@ -141,8 +145,11 @@ export declare function tableStatusText(shown: number, total: number): string;
  * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
  * appendix names the artifact. Every evidentiary block ledgers this way, and a card with no title still
  * shows its marker on the same line.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export declare function renderTable(block: TableBlock, ledger: ReferenceLedger, rowCount: number, total?: number): string;
+export declare function renderTable(block: TableBlock, ledger: ReferenceLedger, rowCount: number, total?: number, view?: ViewOptions): string;
 /**
  * Render a figure block as a corner-accent card. The source rides the `src` attribute, and the caption
  * renders below the image. The caption also fills the `alt` attribute, thus the escape keeps a hostile
@@ -151,8 +158,11 @@ export declare function renderTable(block: TableBlock, ledger: ReferenceLedger,
  * The whole-file binding joins the reference ladder, thus the caption line carries the marker and the
  * appendix names the image. A figure with no caption still shows its marker on that line. The marker stays
  * out of the `alt` text, because a screen reader reads the alt as the picture and not as a footnote.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export declare function renderFigure(block: FigureBlock, ledger: ReferenceLedger, value: FigureValue): string;
+export declare function renderFigure(block: FigureBlock, ledger: ReferenceLedger, value: FigureValue, view?: ViewOptions): string;
 /**
  * Render a citation block as a bibliography card. The binding joins the one reference ladder like a claim
  * binding, thus one shared source keeps one bracket number. The card shows the marker, the short citation
@@ -161,6 +171,9 @@ export declare function renderFigure(block: FigureBlock, ledger: ReferenceLedger
  * The short citation of a `pmid:` record carries the PubMed link of its identifier. A key of another
  * identifier space shows the citation as text. A key with no pinned record shows the key and the note
  * alone, because absence is a normal condition and no text stands in for the paper.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps the identity of
+ * the external record in place of a pin, because a paper is no artifact and no data chain reaches it.
  */
-export declare function renderCitation(block: CitationBlock, ledger: ReferenceLedger, record?: CitationRecord): string;
+export declare function renderCitation(block: CitationBlock, ledger: ReferenceLedger, record?: CitationRecord, view?: ViewOptions): string;
 export {};

package/dist/report-render/views/values.js

@@ -27,6 +27,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "hono/jsx/jsx-
 import { raw } from "hono/html";
 import { declaredForColumn } from "../../contracts/report-reference.js";
 import { stagedSource, tableSidecarName } from "../assets.js";
+import { DEFAULT_VIEW_OPTIONS, lineagePlace, lineageStamp } from "./lineage.js";
 import { Marker } from "./references-view.js";
 import { formatNumberCell, formatTableCell, holdsANumber, selectColumnKind, selectNumberKind, smallestPositiveValue } from "../number-format.js";
 import { citationKeyOf } from "../references.js";
@@ -67,11 +68,14 @@ const DOWNLOAD_LABEL = "Download";
  * The value binding joins the reference ladder, thus the label line carries the marker and the appendix
  * names the cell. The marker sits on the label and never on the value, because the value line is the one
  * figure that a reader takes from the card.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export function renderMetric(block, ledger, value) {
+export function renderMetric(block, ledger, value, view = DEFAULT_VIEW_OPTIONS) {
     const n = ledger.mark(block.value);
     const shown = formatNumberCell(value.value, selectNumberKind(block.label, value.value));
-    return String(_jsxs("div", { class: "stat-card corner-accents", children: [_jsx("div", { class: "stat-card-value", title: shown.full, children: shown.text }), _jsxs("div", { class: "stat-card-label", children: [block.label, _jsx(Marker, { n: n })] })] }));
+    return String(_jsxs("div", { class: "stat-card corner-accents", ...lineageStamp(view.lineage, block.id, [block.value]), children: [_jsx("div", { class: "stat-card-value", title: shown.full, children: shown.text }), _jsxs("div", { class: "stat-card-label", children: [block.label, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.value) })] })] }));
 }
 /**
  * Wrap a run of stat cards in one responsive grid. The caller renders each card first, and it passes the
@@ -199,13 +203,16 @@ export function tableStatusText(shown, total) {
  * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
  * appendix names the artifact. Every evidentiary block ledgers this way, and a card with no title still
  * shows its marker on the same line.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export function renderTable(block, ledger, rowCount, total) {
+export function renderTable(block, ledger, rowCount, total, view = DEFAULT_VIEW_OPTIONS) {
     const binding = block.binding;
     const n = ledger.mark(binding);
     const download = tableSidecarName(binding.hash, binding.path);
     const bound = boundText(binding);
-    return String(_jsxs("div", { class: "report-table", children: [_jsxs("div", { class: "report-table-title", children: [block.title, _jsx(Marker, { n: n })] }), _jsxs("div", { class: "corner-accents", children: [_jsx("div", { class: "report-grid", [GRID_MOUNT_ATTRIBUTE]: block.id }), _jsxs("div", { class: "report-table-footer", children: [_jsxs("div", { class: "report-table-footer-row", children: [_jsxs("span", { class: "report-table-status", children: [_jsx("span", { class: GRID_COUNT_CLASS, children: tableStatusText(rowCount, total ?? rowCount) }), bound !== undefined ? _jsx("span", { class: "report-table-bound", children: bound }) : null] }), _jsx("a", { class: "report-table-download", href: stagedSource(download), download: download, children: downloadLabel(binding.path) })] }), _jsx("div", { class: GRID_NOTE_CLASS })] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
+    return String(_jsxs("div", { class: "report-table", ...lineageStamp(view.lineage, block.id, [binding]), children: [_jsxs("div", { class: "report-table-title", children: [block.title, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, binding) })] }), _jsxs("div", { class: "corner-accents", children: [_jsx("div", { class: "report-grid", [GRID_MOUNT_ATTRIBUTE]: block.id }), _jsxs("div", { class: "report-table-footer", children: [_jsxs("div", { class: "report-table-footer-row", children: [_jsxs("span", { class: "report-table-status", children: [_jsx("span", { class: GRID_COUNT_CLASS, children: tableStatusText(rowCount, total ?? rowCount) }), bound !== undefined ? _jsx("span", { class: "report-table-bound", children: bound }) : null] }), _jsx("a", { class: "report-table-download", href: stagedSource(download), download: download, children: downloadLabel(binding.path) })] }), _jsx("div", { class: GRID_NOTE_CLASS })] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
 }
 /**
  * Render a figure block as a corner-accent card. The source rides the `src` attribute, and the caption
@@ -215,11 +222,14 @@ export function renderTable(block, ledger, rowCount, total) {
  * The whole-file binding joins the reference ladder, thus the caption line carries the marker and the
  * appendix names the image. A figure with no caption still shows its marker on that line. The marker stays
  * out of the `alt` text, because a screen reader reads the alt as the picture and not as a footnote.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps its keys, and the
+ * marker carries the control that opens the chain.
  */
-export function renderFigure(block, ledger, value) {
+export function renderFigure(block, ledger, value, view = DEFAULT_VIEW_OPTIONS) {
     const n = ledger.mark(block.binding);
     const caption = block.caption;
-    return String(_jsxs("figure", { class: "report-figure corner-accents", children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "report-figure-image" }), _jsxs("figcaption", { class: "report-caption", children: [caption, _jsx(Marker, { n: n })] })] }));
+    return String(_jsxs("figure", { class: "report-figure corner-accents", ...lineageStamp(view.lineage, block.id, [block.binding]), children: [_jsx("img", { src: value.src, alt: caption !== undefined ? caption : "", class: "report-figure-image" }), _jsxs("figcaption", { class: "report-caption", children: [caption, _jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, block.binding) })] })] }));
 }
 /**
  * The PubMed address of one identifier. The address is deterministic, and an anchor loads nothing, thus a
@@ -234,10 +244,13 @@ const PUBMED_BASE = "https://pubmed.ncbi.nlm.nih.gov/";
  * The short citation of a `pmid:` record carries the PubMed link of its identifier. A key of another
  * identifier space shows the citation as text. A key with no pinned record shows the key and the note
  * alone, because absence is a normal condition and no text stands in for the paper.
+ *
+ * `view.lineage` states that the page carries a provenance document. The card then stamps the identity of
+ * the external record in place of a pin, because a paper is no artifact and no data chain reaches it.
  */
-export function renderCitation(block, ledger, record) {
+export function renderCitation(block, ledger, record, view = DEFAULT_VIEW_OPTIONS) {
     const n = ledger.mark(block.binding);
     const binding = block.binding;
     const key = citationKeyOf(binding);
-    return String(_jsxs("div", { class: "report-citation corner-accents", children: [_jsx(Marker, { n: n }), record !== undefined ? (_jsxs(_Fragment, { children: [" ", binding.idKind === "pmid" ? (_jsx("a", { class: "report-citation-source", href: `${PUBMED_BASE}${encodeURIComponent(binding.id)}/`, children: record.citation })) : (_jsx("span", { class: "report-citation-source", children: record.citation }))] })) : null, block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "report-citation-note", children: block.note })] })) : null, " ", _jsx("span", { class: "report-citation-key", children: key })] }));
+    return String(_jsxs("div", { class: "report-citation corner-accents", ...lineageStamp(view.lineage, block.id, [binding]), children: [_jsx(Marker, { n: n, lineage: lineagePlace(view.lineage, binding) }), record !== undefined ? (_jsxs(_Fragment, { children: [" ", binding.idKind === "pmid" ? (_jsx("a", { class: "report-citation-source", href: `${PUBMED_BASE}${encodeURIComponent(binding.id)}/`, children: record.citation })) : (_jsx("span", { class: "report-citation-source", children: record.citation }))] })) : null, block.note !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx("span", { class: "report-citation-note", children: block.note })] })) : null, " ", _jsx("span", { class: "report-citation-key", children: key })] }));
 }

package/dist/runtime/assemble.d.ts

@@ -34,6 +34,7 @@ import { type CitationResolverConfig } from "../citations/resolve.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { AuthContext } from "../auth/types.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { MakeSessionPagePublisher, ResolvePageAsset, ResolvePageUrl } from "../tools/report-session/index.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
@@ -160,6 +161,27 @@ export interface CoreRuntimeDeps {
      * the eyes tool of a report session then reports that condition.
      */
     readonly eyes?: AcquireEyes;
+    /**
+     * The provenance seam. Each act of a session — the creation of the session, the block operations, the
+     * title, the derivation, the preview, and the record — rides the session emit as one typed event, and
+     * the embedder lands the events in the record of the analysis that it owns. The emit is
+     * fire-and-forget: it gives no result, a throw of the realization reaches the log alone, and an unbound
+     * member emits nothing. Thus a composition that binds none behaves the same as one that never had the
+     * seam.
+     *
+     * The document read gives the signed document of the analysis back, as opaque text. The preview of a
+     * report session carries a frozen copy into the page, and the page then shows the chain of a grounded
+     * block with no host and no network. The harness parses nothing. Absence is a normal result: an unbound
+     * member, and a bound member that holds no document for the analysis, both give a page with no
+     * provenance and no other change.
+     *
+     * Each member is optional alone, thus a composition binds the members that it records.
+     *
+     * The assembly reaches two consumers with the seam: the report agent, and the conversation agent, whose
+     * start tool passes it to the spawn. The creation of a conversation thread rides `prepareChatTurn`,
+     * which an embedder calls on its own. Thus that composition binds the seam there as well.
+     */
+    readonly provenance?: ProvenanceSeam;
 }
 /**
  * The refusal a thread type carries no agent yet. `report` is a valid

package/dist/runtime/assemble.js

@@ -124,6 +124,9 @@ export function assembleCoreRuntime(deps) {
         usageRecorder,
         citationResolver,
         ...(eyes ? { eyes } : {}),
+        // The start tool passes it to the spawn, which emits the creation of a
+        // report session. The same seam reaches the report agent below.
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
     });
     // The report agent is a singleton over the conversation deps, the same way the
     // session runtime is. Its preview tool writes the page into the analysis tree
@@ -173,6 +176,7 @@ export function assembleCoreRuntime(deps) {
         ...(deps.resolveReportPageAsset ? { resolvePageAsset: deps.resolveReportPageAsset } : {}),
         ...(deps.makeSessionPagePublisher ? { makeSessionPages: deps.makeSessionPagePublisher } : {}),
         ...(deps.resolveReportPageUrl ? { resolvePageUrl: deps.resolveReportPageUrl } : {}),
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
         ...(conversation.logger ? { logger: conversation.logger } : {}),
     });
     // The single registration point for every typed agent. A future thread type's

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

@@ -20,7 +20,7 @@ import { clearSandboxRef } from "../state/index.js";
 import { type AwaitExecOptions } from "./await-exec.js";
 import type { SandboxClient } from "./client.js";
 import { type SubmitExecDeps } from "./submit-exec.js";
-import { type CreateSandboxMeta, type SandboxTransport } from "./types.js";
+import { type CreateSandboxMeta, type FarmSource, type SandboxTransport, type ToolchainSource } from "./types.js";
 /**
  * Narrow config slice the sandbox factory reads off `Env` — the backend
  * default and the K8s namespace fallback. Composition roots map their
@@ -65,6 +65,21 @@ export interface CreateSandboxClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Docker: host dir bind-mounted read-only at `/mnt/libs`. */
     libStorePath?: string;
+    /**
+     * Where the farm of an analysis comes from. Required of every embedder —
+     * the harness never invents a farm location, and it reads no store-root
+     * `current` pointer. On Docker, `FarmLocation.farmPath` is a host
+     * directory. On K8s, it is a `subPath` into `libStorePvc`. Consulted only
+     * when a store is configured.
+     */
+    farmSource: FarmSource;
+    /**
+     * The declared toolchain owner. `"image"` keys the resolver env and the
+     * orient-core prompt text onto the image-owned toolchain. Absent means
+     * `"store"`: the legacy environment, byte-identical to the one before
+     * this field existed.
+     */
+    toolchainSource?: ToolchainSource;
     /** 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. */
@@ -109,9 +124,10 @@ export interface CreateSandboxClientConfig {
     /** Override the backend selection — defaults to `env.SANDBOX_BACKEND`. */
     backend?: "docker" | "k8s";
     /**
-     * Optional logger forwarded to the Docker backend so a lib-store degradation
-     * (a configured store whose `current` vanished/went incomplete mid-session) is
-     * observable rather than a silent mount drop. No-op when unset.
+     * Optional logger forwarded to the Docker backend so a store degradation
+     * (a resolved farm whose `inflexa.lock` vanished or went invalid
+     * mid-session) is observable rather than a silent mount drop. No-op when
+     * unset.
      */
     logger?: Logger;
     /** Dependency seams (fetch, durable step/sleep, clock, recv, warn sink) forwarded to submit/await. */

package/dist/sandbox/create-sandbox.js

@@ -86,6 +86,8 @@ export function createSandboxClient(config) {
             sessionPvcRoot: config.sessionPvcRoot,
             resolveWorkspaceRoot: config.resolveWorkspaceRoot,
             libStorePvc: config.libStorePvc,
+            farmSource: config.farmSource,
+            toolchainSource: config.toolchainSource,
             refStorePvc: config.refStorePvc,
             nodeSelector: config.nodeSelector,
             tolerations: config.tolerations,
@@ -98,6 +100,8 @@ export function createSandboxClient(config) {
             transport,
             resolveWorkspaceRoot: config.resolveWorkspaceRoot,
             libStorePath: config.libStorePath,
+            farmSource: config.farmSource,
+            toolchainSource: config.toolchainSource,
             refStorePath: config.refStorePath,
             platform: config.platform,
             engineSocketPath: config.engineSocketPath,

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

@@ -3,9 +3,10 @@
  *
  * Thin wrapper around `dockerode`. Storage is wired via `HostConfig.Binds`:
  * a flat read-only mount of the analysis tree at `/{resourceId}`, a nested
- * read-write mount of the step's artifact dir, and the lib/ref stores at
- * `/mnt/libs` / `/mnt/refs` when their host paths are configured. Container
- * paths and lib-store env come from the shared mount plan (`mount-plan.ts`).
+ * read-write mount of the step's artifact dir, the package store at
+ * `/mnt/libs` with the resolved farm nested inside it, and the ref store at
+ * `/mnt/refs` when its host path is configured. Container paths and
+ * lib-store env come from the shared mount plan (`mount-plan.ts`).
  *
  * ## The cpu files
  *
@@ -42,7 +43,7 @@ import { ResultAsync } from "neverthrow";
 import type { Logger } from "../lib/logger.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type SandboxError } from "./sandbox-error.js";
-import type { CreateSandboxMeta, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport } from "./types.js";
+import type { CreateSandboxMeta, FarmSource, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport, ToolchainSource } from "./types.js";
 export interface DockerClientConfig {
     image: string;
     /** Cortex base URL injected into the sandbox env in callback mode so callbacks land here. Unused in poll mode. */
@@ -53,6 +54,15 @@ export interface DockerClientConfig {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Host lib store; bind-mounted read-only at `/mnt/libs` when set. */
     libStorePath?: string;
+    /**
+     * Where the farm of an analysis comes from. Required — the harness never
+     * invents a farm location. `FarmLocation.farmPath` is a host directory
+     * here, bind-mounted read-only at the farm container path. Consulted only
+     * when `libStorePath` is set.
+     */
+    farmSource: FarmSource;
+    /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
+    toolchainSource?: ToolchainSource;
     /**
      * Host ref store; bind-mounted read-only at `/mnt/refs`. Embedders pass the
      * configured store location unconditionally — existence is (re-)checked at each
@@ -85,8 +95,8 @@ export interface DockerClientConfig {
      */
     readHostCpuinfo?: () => Promise<string | undefined>;
     /**
-     * Optional logger so a lib-store degradation (a configured store whose `current`
-     * vanished or went incomplete by sandbox-create time) is observable instead of a
+     * Optional logger so a store degradation (a resolved farm whose `inflexa.lock`
+     * is absent or invalid by sandbox-create time) is observable instead of a
      * silent libs-mount drop. Matches the `reaper`/`watchdog` logger seam.
      */
     logger?: Logger;

package/dist/sandbox/docker-client.js

@@ -3,9 +3,10 @@
  *
  * Thin wrapper around `dockerode`. Storage is wired via `HostConfig.Binds`:
  * a flat read-only mount of the analysis tree at `/{resourceId}`, a nested
- * read-write mount of the step's artifact dir, and the lib/ref stores at
- * `/mnt/libs` / `/mnt/refs` when their host paths are configured. Container
- * paths and lib-store env come from the shared mount plan (`mount-plan.ts`).
+ * read-write mount of the step's artifact dir, the package store at
+ * `/mnt/libs` with the resolved farm nested inside it, and the ref store at
+ * `/mnt/refs` when its host path is configured. Container paths and
+ * lib-store env come from the shared mount plan (`mount-plan.ts`).
  *
  * ## The cpu files
  *
@@ -37,7 +38,7 @@
  * Either way the workload ends as uid 1000 with `no-new-privileges` and no
  * effective capabilities.
  */
-import { existsSync, lstatSync, statSync } from "node:fs";
+import { lstatSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import Docker from "dockerode";
@@ -45,6 +46,7 @@ import { ResultAsync, err, ok } from "neverthrow";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { tailWritePrefix } from "../workspace/paths.js";
 import { trySandbox } from "./sandbox-error.js";
+import { readFarmLock, resolveFarmSource } from "./farm.js";
 import { buildMountPlan, sandboxWriteTail } from "./mount-plan.js";
 import { CPU_ONLINE_PATH, CPUINFO_PATH, cpuFiles, readHostCpuinfoOnce } from "./cpu-files.js";
 import { threadLimitEnv } from "./thread-env.js";
@@ -74,26 +76,6 @@ const RUN_ID_LABEL = "cortex/run-id";
 const STEP_ID_LABEL = "cortex/step-id";
 /** The directory next to the workspace root that holds the cpu files of each sandbox. */
 const CPU_FILES_DIR = ".cpu";
-/**
- * Whether the lib store's `current` resolves to a COMPLETE, usable version, not merely a
- * present symlink. By sandbox-create time `current` may be gone (concurrent prune/`rm`), a
- * dangling symlink (its target pruned), or an incomplete tree. Binding a missing source
- * makes Docker auto-create a root-owned dir (bricking a later store refresh); binding a broken
- * one mounts broken content. Require a resolved directory carrying both completeness
- * markers `activate` writes before it flips the pointer.
- */
-function libStoreUsable(libStorePath) {
-    const current = join(libStorePath, "current");
-    try {
-        // statSync FOLLOWS the symlink, so a dangling `current` throws here and is rejected.
-        if (!statSync(current).isDirectory())
-            return false;
-    }
-    catch {
-        return false;
-    }
-    return existsSync(join(current, "packages.txt")) && existsSync(join(current, "meta.json"));
-}
 /**
  * Whether `refStorePath` is, right now, a real directory fit to be a bind authority.
  * Deliberately shallow — it checks existence-as-a-directory only, never the store's
@@ -253,13 +235,41 @@ export function createDockerSandboxOps(config) {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
                 const { sandboxId, callbackSecret } = identity;
-                // Re-check AT sandbox-creation time: `config.libStorePath` was fixed at CLI
-                // boot and the store may have gone away since (see libStoreUsable). Not
-                // usable → skip the mount (sandbox degrades to available:false) and log it,
-                // since an otherwise-silent libs-mount drop is invisible to operators.
-                const libsMounted = !!config.libStorePath && libStoreUsable(config.libStorePath);
-                if (config.libStorePath && !libsMounted) {
-                    logger.warn("lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)", { libStorePath: config.libStorePath, sandboxId });
+                // Farm resolution comes before any container work: a resolver
+                // refusal and a resolver throw refuse the whole call, and no
+                // container is made. The reason of the embedder rides in the error.
+                let farm;
+                if (config.libStorePath) {
+                    const resolved = await resolveFarmSource(config.farmSource, meta.analysisId, "docker.createSandbox");
+                    if (resolved.isErr())
+                        return err(resolved.error);
+                    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.
+                let libsMounted = false;
+                if (config.libStorePath && farm) {
+                    const lock = readFarmLock(farm.farmPath);
+                    libsMounted = lock.isOk();
+                    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 });
+                    }
+                }
+                // The cache path is the one farm value with no gate of its
+                // own: the lock gate proves `farmPath`, and this bind string
+                // would carry a malformed cache path verbatim. An unusable
+                // value degrades to no cache mount — the rule of a missing
+                // one — because the entrypoint fallback covers the caches.
+                const cacheBindable = farm?.cachePath !== undefined && farm.cachePath.startsWith("/") && !farm.cachePath.includes(":");
+                if (farm?.cachePath !== undefined && !cacheBindable) {
+                    logger.warn("the farm cache path cannot ride a docker bind — mounting no cache", {
+                        cachePath: farm.cachePath,
+                        sandboxId,
+                    });
                 }
                 // Re-checked here too, so a ref store installed after boot is mounted into
                 // the next sandbox. Unlike libs, a missing ref store is NOT warned: a missing
@@ -271,6 +281,8 @@ export function createDockerSandboxOps(config) {
                 const plan = buildMountPlan(meta, {
                     libs: libsMounted,
                     refs: refsMounted,
+                    toolchainSource: config.toolchainSource,
+                    cache: cacheBindable,
                 });
                 const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
                 // `tailWritePrefix` (not a raw `join`) so the RW bind source runs through
@@ -290,12 +302,16 @@ export function createDockerSandboxOps(config) {
                 const cpuBinds = await writeCpuFiles(cpuDir, cpuFiles(threads, cpuinfo), logger, sandboxId);
                 if (cpuBinds.length > 0)
                     cpuDirs.set(sandboxId, cpuDir);
+                // The farm bind comes after the store bind, thus the nesting is
+                // stable; the cache bind comes after the two store binds.
                 const binds = [
                     `${hostTreePath}:${plan.readonlyTreePath}:ro`,
                     ...(write && plan.writableStepPath
                         ? [`${tailWritePrefix({ workspaceRoot: hostTreePath, tail: write.tail })}:${plan.writableStepPath}:rw`]
                         : []),
                     ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
+                    ...(libsMounted && farm && plan.farmPath ? [`${farm.farmPath}:${plan.farmPath}:ro`] : []),
+                    ...(libsMounted && cacheBindable && farm?.cachePath && plan.cachePath ? [`${farm.cachePath}:${plan.cachePath}:rw`] : []),
                     ...(refsMounted && config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
                     ...cpuBinds,
                 ];

package/dist/sandbox/farm.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Farm-source resolution and the `inflexa.lock` farm contract.
+ *
+ * A farm carries exactly one metadata file, `inflexa.lock`, beside its link
+ * trees and its caches (the lib-store spec). The mount gate and the package
+ * inventory read this one file — `packages.txt`, `meta.json`, and
+ * `lock.json` are not part of the farm contract.
+ *
+ * The resolution and the gate refuse differently, on purpose:
+ * - 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.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import type { SandboxError } from "./sandbox-error.js";
+import type { FarmLocation, FarmSource } from "./types.js";
+/** The one metadata file of a farm. */
+export declare const FARM_LOCK_FILE = "inflexa.lock";
+/** One linked distribution. `requested` obeys the PEP 376 meaning: true for a direct ask, false for a transitive dependency. */
+export declare const FarmLockPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    track: z.ZodString;
+    store_dir: z.ZodString;
+    hash: z.ZodString;
+    requested: z.ZodBoolean;
+}, z.core.$loose>;
+/**
+ * `inflexa.lock` at schema version 1. Additive fields pass through — a
+ * breaking change to the shape must move the schema number instead.
+ */
+export declare const FarmLockSchema: z.ZodObject<{
+    schema: z.ZodLiteral<1>;
+    arch: z.ZodEnum<{
+        amd64: "amd64";
+        arm64: "arm64";
+    }>;
+    packages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        track: z.ZodString;
+        store_dir: z.ZodString;
+        hash: z.ZodString;
+        requested: z.ZodBoolean;
+    }, z.core.$loose>>;
+    languages: z.ZodObject<{
+        python: z.ZodOptional<z.ZodObject<{
+            version: z.ZodString;
+            index: z.ZodString;
+        }, z.core.$loose>>;
+        r: z.ZodOptional<z.ZodObject<{
+            version: z.ZodString;
+            bioc_releases: z.ZodArray<z.ZodString>;
+            pak_lock: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    warm: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        script_sha256: z.ZodString;
+        cache_entries: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>>;
+    merge_conflicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        entry: z.ZodString;
+        action: z.ZodEnum<{
+            skipped: "skipped";
+            "kept-first": "kept-first";
+        }>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type FarmLock = z.infer<typeof FarmLockSchema>;
+export type FarmLockError = {
+    readonly type: "lock_unreadable";
+    readonly lockPath: string;
+    readonly cause: unknown;
+} | {
+    readonly type: "lock_invalid";
+    readonly lockPath: string;
+    readonly cause: unknown;
+};
+/**
+ * Read and validate the `inflexa.lock` of a farm directory. The mount gate
+ * accepts a farm only when this returns ok — a farm whose lock is absent,
+ * unparseable, or at an unknown schema version is not usable.
+ */
+export declare function readFarmLock(farmPath: string): Result<FarmLock, FarmLockError>;
+/** Read and validate one `inflexa.lock` by its file path. The package inventory reads through this too. */
+export declare function readFarmLockFile(lockPath: string): Result<FarmLock, FarmLockError>;
+/**
+ * Resolve the farm source of one analysis. Runs before any container work.
+ * `fixed` answers at once. `per-analysis` calls the resolver of the
+ * embedder — an `unavailable` result and a throw both refuse the call with
+ * `farm_unavailable`, and the reason of the embedder rides in the error.
+ */
+export declare function resolveFarmSource(source: FarmSource, analysisId: string, op: string): Promise<Result<FarmLocation, SandboxError>>;