@inflexa-ai/harness 0.39.1 → 0.40.0

package/dist/providers/reasoning.js

@@ -1,34 +1,23 @@
 /**
- * The reasoning depth of a run.
+ * The reasoning depth of a call.
  *
- * The harness states the depth one time, on `ChatRequest.reasoning`, with the
- * neutral names of the AI SDK. It names no vendor key. Each provider package
- * holds the table of what its own models accept, and it maps the neutral name
- * onto the wire. The Anthropic package also selects adaptive thinking there.
+ * The effort resolves in order: `ChatRequest.reasoning` (set only through
+ * `RunAgentOptions.reasoning`), the provider configuration's `reasoning`, then
+ * {@link DEFAULT_REASONING}. Anthropic discards its message cache when the
+ * top-level effort changes between calls.
  *
- * ## Why the harness names no vendor key
- *
- * The harness wrote `providerOptions.anthropic.effort` before. A value on that
- * key turns the per-model table of the Anthropic package off, thus the raw name
- * reached the wire. A model that accepts `high` but not `xhigh` answered 400.
- * The neutral field has no such hazard, because the package resolves the name
- * for the model that it is bound to.
- *
- * ## Where the policy belongs
- *
- * The policy rides on the run, not on the provider, for the same reason that the
- * cache policy does. A one-shot LLM call elsewhere in the harness has its own
- * depth needs, and it must not inherit the depth of an agent loop.
+ * Do not set `providerOptions.anthropic.effort` directly. It bypasses the
+ * per-model table, and a model that rejects the raw name answers 400.
  */
 /**
- * The default policy: the deepest name of the neutral ladder.
+ * The last source of the effort: the deepest rung of the neutral ladder.
  *
  * Each agent of the harness drives tools over many iterations. A shallow turn
  * there wastes more calls than a deeper turn costs in tokens. The Anthropic
  * package sends `xhigh` to a model that accepts it, and `max` to a model that
  * does not. The OpenAI-compatible package sends the name as it is.
  *
- * A host that wants a cheaper loop passes a lower name. A host on a model with
- * no reasoning support passes `"provider-default"`.
+ * A host that wants a cheaper role sets a lower name on that role's provider
+ * configuration. With no reasoning support, a host sets `"provider-default"`.
  */
 export const DEFAULT_REASONING = "xhigh";

package/dist/providers/types.d.ts

@@ -5,7 +5,7 @@
  * vendor-neutral interfaces. Every call carries an `AgentSession`; billing
  * attribution is resolved lazily at the provider wire boundary.
  */
-import type { FinishReason, LanguageModel, ModelMessage, ToolSet } from "ai";
+import type { FinishReason, LanguageModel, ModelMessage, SystemModelMessage, ToolSet } from "ai";
 import type { LanguageModelV4CallOptions } from "@ai-sdk/provider";
 import type { ProviderOptions } from "@ai-sdk/provider-utils";
 import type { ResultAsync } from "neverthrow";
@@ -32,19 +32,30 @@ export interface ProviderCapabilities {
      */
     readonly imageUserMessages?: boolean;
 }
+/**
+ * The request carries no free-form provider options. That would let a caller
+ * set a vendor key that bypasses the provider's per-model table.
+ */
 export interface ChatRequest {
-    readonly system: string;
+    /**
+     * The system prompt: a plain string, or a system message that carries the
+     * cache marker at its end (`withSystemPromptBreakpoint`).
+     */
+    readonly system: string | SystemModelMessage;
     readonly messages: readonly ModelMessage[];
     readonly tools: ToolSet;
     /**
      * A forced choice (`required`, or one named tool) is absent on purpose: some
      * Claude models reject it with a 400, and the model is chosen at run time.
+     *
+     * CAUTION: `@ai-sdk/anthropic` strips the tools when this is `"none"`, and
+     * Anthropic drops its cache on any `tool_choice` change — taking a signed
+     * thinking block with it. Use a tool mask instead of sending `"none"`.
      */
     readonly toolChoice?: "auto" | "none";
-    readonly providerOptions?: ProviderOptions;
     /**
-     * How deep the model reasons on this call. Absent sends no directive, thus
-     * the model applies its own default. Refer to `ReasoningPolicy`.
+     * How deep the model reasons. Absent, the effort falls back to the provider
+     * configuration's `reasoning`, then `DEFAULT_REASONING`.
      */
     readonly reasoning?: ReasoningPolicy;
 }
@@ -139,6 +150,11 @@ export interface ChatResponse {
      * diagnostics, never as an invariant.
      */
     readonly servedModelId?: string;
+    /**
+     * The AI SDK's `LanguageModel.provider` id, for example `anthropic.messages`.
+     * Absent for a bare model-id string, which names no provider.
+     */
+    readonly provider?: string;
 }
 export type ChatStreamEvent = {
     readonly type: "text-delta";

package/dist/report-model/authoring-grammar.d.ts

@@ -398,15 +398,15 @@ declare const AUTHORING_ATOM_SCHEMAS: readonly [z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    linear: "linear";
                     log: "log";
+                    linear: "linear";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    linear: "linear";
                     log: "log";
+                    linear: "linear";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;

package/dist/report-model/pin-snapshot.js

@@ -210,19 +210,13 @@ async function collectCitations(pool, resolveWorkspaceRoot, analysisId) {
  * tier, which runs one time for each report version.
  */
 export async function pinReportSnapshot(pool, analysisId, options = {}) {
-    let ledgerRows;
-    try {
-        ledgerRows = await queryAnalysisArtifacts(pool, analysisId);
-    }
-    catch (cause) {
-        // The query speaks the throw protocol of the `pg` driver. This is the thin wrapper that turns
-        // that throw into a value, thus each caller above reads a failure as data.
-        return err({ kind: "ledger-read-failed", cause });
-    }
+    const ledgerRows = await queryAnalysisArtifacts(pool, analysisId);
+    if (ledgerRows.isErr())
+        return err({ kind: "ledger-read-failed", cause: ledgerRows.error.cause });
     // The ledger accepts any path. A null-prototype map keeps a key such as `__proto__` an ordinary
     // entry, thus no path collides with a prototype slot.
     const artifacts = Object.create(null);
-    for (const row of ledgerRows) {
+    for (const row of ledgerRows.value) {
         artifacts[row.path] = { hash: row.hash, fileType: row.fileType };
     }
     // A citation reference resolves against this list: the resolver refuses a key that the list does not

package/dist/runtime/assemble.d.ts

@@ -49,12 +49,13 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * here would let an embedder wire a recorder the workflows use and the
  * conversation agent does not — a half-wired ledger that reads as a complete
  * one. The protection has to hold on both sides of the assembly, not just the
- * conversation side.
+ * conversation side. Each bag omits `toolOutputStore` for the same reason: each
+ * loop must keep its texts in the one store that each read tool reads.
  */
 export interface CoreWorkflowDeps {
-    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver">;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver">;
-    readonly dataProfile: Omit<DataProfileDeps, "usageRecorder">;
+    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver" | "toolOutputStore">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver" | "toolOutputStore">;
+    readonly dataProfile: Omit<DataProfileDeps, "usageRecorder" | "toolOutputStore">;
 }
 /** The registered, callable workflow handles. */
 export interface RegisteredWorkflows {
@@ -66,21 +67,22 @@ export interface RegisteredWorkflows {
 }
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, the
- * usage recorder, the report-session anchor, and the eyes.
+ * usage recorder, the report-session anchor, the eyes, and the tool output store.
  * `assembleCoreRuntime` supplies each of those itself. Thus a caller cannot wire
- * one of these five values:
+ * one of these six values:
  *
  * - a stale callable
  * - a policy that diverges from the one the workflows see
  * - a recorder that only half the agent tree reports to
  * - an anchor over a different session runtime
  * - a seam that only half the agent tree looks through
+ * - a store that only half the agent tree keeps its texts in
  *
  * The assembly resolves the eyes one time, from `CoreRuntimeDeps.eyes` and the
  * chrome config. A caller that bound the eyes here would give the conversation
  * agent a seam that the report agent never sees.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes" | "toolOutputStore">;
 /**
  * What binds one reference resolver: the analysis whose pinned artifacts it reads, and the auth of the tool
  * call that reads them. A resolver serves one analysis, thus the report tools build one for each call.

package/dist/runtime/assemble.js

@@ -30,6 +30,7 @@ import { createCitationResolver } from "../citations/resolve.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createArtifactReadStore, createProductionResolver } from "../report-model/production-resolver.js";
 import { createReportVersionStore } from "../state/report-versions.js";
+import { createToolOutputStore } from "../state/tool-outputs.js";
 const _assertDomainError = true;
 /**
  * Wrap a type→agent registry as the resolution surface. Held apart from
@@ -83,9 +84,10 @@ export function assembleCoreRuntime(deps) {
             ? {}
             : { semanticScholarApiKey: conversation.bioKeys.semanticScholar }),
     });
-    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder });
-    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder });
-    const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
+    const toolOutputStore = createToolOutputStore(conversation.pool);
+    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder, toolOutputStore });
+    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder, toolOutputStore });
+    const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder, toolOutputStore });
     // The extraction workflow shares the profile's sandbox and authorization rails, thus it draws the same
     // three seams from the profile deps. The report resolver factory binds the extraction arm over this
     // callable, thus a fall-through report reference reads its file out of process on the profile rails.
@@ -120,6 +122,7 @@ export function assembleCoreRuntime(deps) {
         anchorReportSession: reportSession.ensureSessionState,
         resourcePolicy,
         usageRecorder,
+        toolOutputStore,
         citationResolver,
         ...(eyes ? { eyes } : {}),
         // The start tool passes it to the spawn, which emits the creation of a
@@ -176,6 +179,7 @@ export function assembleCoreRuntime(deps) {
         ...(deps.resolveReportPageUrl ? { resolvePageUrl: deps.resolveReportPageUrl } : {}),
         ...(deps.provenance ? { provenance: deps.provenance } : {}),
         ...(conversation.logger ? { logger: conversation.logger } : {}),
+        toolOutputStore,
     });
     // The single registration point for every typed agent. A future thread type's
     // agent plugs in here at assembly with no embedder change. `conversation` is

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

@@ -49,8 +49,8 @@ export interface CreateSandboxClientConfig {
     /**
      * Per-stream retention budget sent with every exec, so the sandbox drops
      * output past it instead of shipping it. Defaults to `EXEC_STREAM_BYTE_CAP`,
-     * the same value the host truncates to on receipt — sending more than the
-     * host will keep buys nothing.
+     * the maximum of a kept tool output and the same value the host truncates to
+     * on receipt — sending more than the host will keep buys nothing.
      */
     execStreamByteCap?: number;
     /** Cluster resource ceilings; every sandbox request is clamped to these. */

package/dist/sandbox/submit-exec.d.ts

@@ -26,7 +26,7 @@ export interface SubmitExecDeps {
     }) => Promise<T>;
     /**
      * Per-stream retention budget to send when the body does not carry one.
-     * Defaults to `EXEC_STREAM_BYTE_CAP`.
+     * Defaults to `EXEC_STREAM_BYTE_CAP`, the maximum of a kept tool output.
      */
     execStreamByteCap?: number;
 }

package/dist/schemas/artifact-manifest.d.ts

@@ -8,9 +8,9 @@ import { z } from "zod";
 /** Artifact type inferred from the step subdirectory. */
 export declare const ArtifactTypeSchema: z.ZodEnum<{
     output: "output";
-    log: "log";
-    figure: "figure";
     script: "script";
+    figure: "figure";
+    log: "log";
     notebook: "notebook";
 }>;
 export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
@@ -22,9 +22,9 @@ export declare const ArtifactManifestEntrySchema: z.ZodObject<{
     size: z.ZodNumber;
     type: z.ZodEnum<{
         output: "output";
-        log: "log";
-        figure: "figure";
         script: "script";
+        figure: "figure";
+        log: "log";
         notebook: "notebook";
     }>;
     hash: z.ZodOptional<z.ZodString>;

package/dist/state/artifacts.d.ts

@@ -2,6 +2,8 @@
  * `cortex_artifacts` operations — artifact upsert, lookup, and file-id
  * reconciliation.
  */
+import type { ResultAsync } from "neverthrow";
+import { type DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
 import type { ArtifactRow } from "./schema.js";
 export interface RegisterArtifactInput {
@@ -20,7 +22,7 @@ export interface RegisterArtifactInput {
      */
     fileId?: string | null;
 }
-export declare function upsertArtifact(pool: Querier, entry: RegisterArtifactInput): Promise<void>;
+export declare function upsertArtifact(pool: Querier, entry: RegisterArtifactInput): ResultAsync<void, DbError>;
 /**
  * Batched upsert — writes entries in multi-row `INSERT ... VALUES` statements
  * of at most {@link ROWS_PER_STATEMENT} rows. Callers range from per-step
@@ -30,7 +32,7 @@ export declare function upsertArtifact(pool: Querier, entry: RegisterArtifactInp
  * idempotent per row (`ON CONFLICT ... DO UPDATE`), so a failure between
  * chunks is healed by the caller's retry re-upserting the same manifest.
  */
-export declare function upsertArtifacts(pool: Querier, entries: RegisterArtifactInput[]): Promise<void>;
+export declare function upsertArtifacts(pool: Querier, entries: RegisterArtifactInput[]): ResultAsync<void, DbError>;
 /** Result type for input artifact metadata lookups. */
 export interface InputArtifactMeta {
     path: string;
@@ -42,8 +44,8 @@ export interface InputArtifactMeta {
  * Query cortex_artifacts for input-role rows matching the given paths.
  * Used at the registration boundary to resolve metadata for data-source inputs.
  */
-export declare function queryInputArtifacts(pool: Querier, analysisId: string, paths: string[]): Promise<InputArtifactMeta[]>;
-export declare function queryUnsyncedStepArtifacts(pool: Querier, resourceId: string, runId: string, stepId: string): Promise<ArtifactRow[]>;
+export declare function queryInputArtifacts(pool: Querier, analysisId: string, paths: string[]): ResultAsync<InputArtifactMeta[], DbError>;
+export declare function queryUnsyncedStepArtifacts(pool: Querier, resourceId: string, runId: string, stepId: string): ResultAsync<ArtifactRow[], DbError>;
 /** One registered step output, as a downstream consumer needs to name it. */
 export interface StepArtifactRef {
     /** Workspace-root-relative path (`runs/{runId}/{stepId}/output/de.csv`). */
@@ -56,7 +58,7 @@ export interface StepArtifactRef {
  * path, so a `limit` truncates the tail of the list rather than an arbitrary
  * slice of it — and so the same call replays to the same rows.
  */
-export declare function queryStepArtifactPaths(pool: Querier, resourceId: string, runId: string, stepId: string, limit: number): Promise<StepArtifactRef[]>;
+export declare function queryStepArtifactPaths(pool: Querier, resourceId: string, runId: string, stepId: string, limit: number): ResultAsync<StepArtifactRef[], DbError>;
 /** One registered artifact of an analysis, as a reader of the full artifact set names it. */
 export interface AnalysisArtifactRef {
     /** Workspace-root-relative path (`runs/{runId}/{stepId}/output/de.csv`). */
@@ -72,11 +74,11 @@ export interface AnalysisArtifactRef {
  * query drops such a row, a later refusal says that the artifact never existed, and that reason is
  * false.
  */
-export declare function queryAnalysisArtifacts(pool: Querier, analysisId: string): Promise<AnalysisArtifactRef[]>;
+export declare function queryAnalysisArtifacts(pool: Querier, analysisId: string): ResultAsync<AnalysisArtifactRef[], DbError>;
 /** Count step-output artifacts produced by a run — for the run-completed card. */
-export declare function countArtifactsForRun(pool: Querier, analysisId: string, runId: string): Promise<number>;
-export declare function updateArtifactId(pool: Querier, resourceId: string, path: string, artifactId: string, fileType?: string | null): Promise<void>;
+export declare function countArtifactsForRun(pool: Querier, analysisId: string, runId: string): ResultAsync<number, DbError>;
+export declare function updateArtifactId(pool: Querier, resourceId: string, path: string, artifactId: string, fileType?: string | null): ResultAsync<void, DbError>;
 export declare function updateFileIds(pool: Querier, pairs: Array<{
     artifactId: string;
     fileId: string;
-}>): Promise<void>;
+}>): ResultAsync<void, DbError>;

package/dist/state/artifacts.js

@@ -2,10 +2,12 @@
  * `cortex_artifacts` operations — artifact upsert, lookup, and file-id
  * reconciliation.
  */
-export async function upsertArtifact(pool, entry) {
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+export function upsertArtifact(pool, entry) {
     const now = new Date().toISOString();
-    await pool.query({
-        text: `INSERT INTO cortex_artifacts
+    return tryMutation("artifacts.upsertArtifact", async () => {
+        await pool.query({
+            text: `INSERT INTO cortex_artifacts
           (analysis_id, path, hash, size, role, source_step, source_run, file_type, file_id, created_at)
           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
           ON CONFLICT (analysis_id, path) DO UPDATE SET
@@ -16,18 +18,19 @@ export async function upsertArtifact(pool, entry) {
             source_run = EXCLUDED.source_run,
             file_type = COALESCE(EXCLUDED.file_type, cortex_artifacts.file_type),
             file_id = COALESCE(EXCLUDED.file_id, cortex_artifacts.file_id)`,
-        values: [
-            entry.resourceId,
-            entry.path,
-            entry.hash,
-            entry.size,
-            entry.role,
-            entry.sourceStep ?? null,
-            entry.sourceRun ?? null,
-            entry.fileType ?? null,
-            entry.fileId ?? null,
-            now,
-        ],
+            values: [
+                entry.resourceId,
+                entry.path,
+                entry.hash,
+                entry.size,
+                entry.role,
+                entry.sourceStep ?? null,
+                entry.sourceRun ?? null,
+                entry.fileType ?? null,
+                entry.fileId ?? null,
+                now,
+            ],
+        });
     });
 }
 const COLS_PER_ROW = 10;
@@ -49,31 +52,32 @@ const ROWS_PER_STATEMENT = 1_000;
  * idempotent per row (`ON CONFLICT ... DO UPDATE`), so a failure between
  * chunks is healed by the caller's retry re-upserting the same manifest.
  */
-export async function upsertArtifacts(pool, entries) {
+export function upsertArtifacts(pool, entries) {
     const now = new Date().toISOString();
-    for (let start = 0; start < entries.length; start += ROWS_PER_STATEMENT) {
-        const chunk = entries.slice(start, start + ROWS_PER_STATEMENT);
-        const placeholders = chunk
-            .map((_, i) => {
-            const base = i * COLS_PER_ROW;
-            return (`($${base + 1}, $${base + 2}, $${base + 3}, $${base + 4}, ` +
-                `$${base + 5}, $${base + 6}, $${base + 7}, $${base + 8}, $${base + 9}, $${base + 10})`);
-        })
-            .join(", ");
-        const values = chunk.flatMap((e) => [
-            e.resourceId,
-            e.path,
-            e.hash,
-            e.size,
-            e.role,
-            e.sourceStep ?? null,
-            e.sourceRun ?? null,
-            e.fileType ?? null,
-            e.fileId ?? null,
-            now,
-        ]);
-        await pool.query({
-            text: `INSERT INTO cortex_artifacts
+    return tryMutation("artifacts.upsertArtifacts", async () => {
+        for (let start = 0; start < entries.length; start += ROWS_PER_STATEMENT) {
+            const chunk = entries.slice(start, start + ROWS_PER_STATEMENT);
+            const placeholders = chunk
+                .map((_, i) => {
+                const base = i * COLS_PER_ROW;
+                return (`($${base + 1}, $${base + 2}, $${base + 3}, $${base + 4}, ` +
+                    `$${base + 5}, $${base + 6}, $${base + 7}, $${base + 8}, $${base + 9}, $${base + 10})`);
+            })
+                .join(", ");
+            const values = chunk.flatMap((e) => [
+                e.resourceId,
+                e.path,
+                e.hash,
+                e.size,
+                e.role,
+                e.sourceStep ?? null,
+                e.sourceRun ?? null,
+                e.fileType ?? null,
+                e.fileId ?? null,
+                now,
+            ]);
+            await pool.query({
+                text: `INSERT INTO cortex_artifacts
           (analysis_id, path, hash, size, role, source_step, source_run, file_type, file_id, created_at)
           VALUES ${placeholders}
           ON CONFLICT (analysis_id, path) DO UPDATE SET
@@ -84,42 +88,47 @@ export async function upsertArtifacts(pool, entries) {
             source_run = EXCLUDED.source_run,
             file_type = COALESCE(EXCLUDED.file_type, cortex_artifacts.file_type),
             file_id = COALESCE(EXCLUDED.file_id, cortex_artifacts.file_id)`,
-            values,
-        });
-    }
+                values,
+            });
+        }
+    });
 }
 /**
  * Query cortex_artifacts for input-role rows matching the given paths.
  * Used at the registration boundary to resolve metadata for data-source inputs.
  */
-export async function queryInputArtifacts(pool, analysisId, paths) {
-    if (paths.length === 0)
-        return [];
-    const result = await pool.query({
-        text: `SELECT path, hash, size, file_id
+export function queryInputArtifacts(pool, analysisId, paths) {
+    return tryQuery("artifacts.queryInputArtifacts", async () => {
+        if (paths.length === 0)
+            return [];
+        const result = await pool.query({
+            text: `SELECT path, hash, size, file_id
           FROM cortex_artifacts
           WHERE analysis_id = $1 AND role = 'input' AND path = ANY($2::text[])`,
-        values: [analysisId, paths],
+            values: [analysisId, paths],
+        });
+        return result.rows.map((r) => ({
+            path: r.path,
+            hash: r.hash,
+            size: Number(r.size),
+            fileId: r.file_id ?? null,
+        }));
     });
-    return result.rows.map((r) => ({
-        path: r.path,
-        hash: r.hash,
-        size: Number(r.size),
-        fileId: r.file_id ?? null,
-    }));
 }
-export async function queryUnsyncedStepArtifacts(pool, resourceId, runId, stepId) {
-    const result = await pool.query({
-        text: `SELECT analysis_id, path, artifact_id, file_id, hash, size, role,
+export function queryUnsyncedStepArtifacts(pool, resourceId, runId, stepId) {
+    return tryQuery("artifacts.queryUnsyncedStepArtifacts", async () => {
+        const result = await pool.query({
+            text: `SELECT analysis_id, path, artifact_id, file_id, hash, size, role,
                  source_step, source_run, created_at, file_type
           FROM cortex_artifacts
           WHERE analysis_id = $1 AND source_run = $2 AND source_step = $3
             AND artifact_id IS NOT NULL AND file_id IS NULL
             AND role = 'step_output'
           ORDER BY created_at`,
-        values: [resourceId, runId, stepId],
+            values: [resourceId, runId, stepId],
+        });
+        return result.rows.map(mapArtifactRow);
     });
-    return result.rows.map(mapArtifactRow);
 }
 /**
  * The artifacts a completed step registered, most consequential first. Ordered
@@ -127,11 +136,12 @@ export async function queryUnsyncedStepArtifacts(pool, resourceId, runId, stepId
  * path, so a `limit` truncates the tail of the list rather than an arbitrary
  * slice of it — and so the same call replays to the same rows.
  */
-export async function queryStepArtifactPaths(pool, resourceId, runId, stepId, limit) {
-    if (limit <= 0)
-        return [];
-    const result = await pool.query({
-        text: `SELECT path, file_type
+export function queryStepArtifactPaths(pool, resourceId, runId, stepId, limit) {
+    return tryQuery("artifacts.queryStepArtifactPaths", async () => {
+        if (limit <= 0)
+            return [];
+        const result = await pool.query({
+            text: `SELECT path, file_type
           FROM cortex_artifacts
           WHERE analysis_id = $1 AND source_run = $2 AND source_step = $3
             AND role = 'step_output'
@@ -144,9 +154,10 @@ export async function queryStepArtifactPaths(pool, resourceId, runId, stepId, li
                    END,
                    path
           LIMIT $4`,
-        values: [resourceId, runId, stepId, limit],
+            values: [resourceId, runId, stepId, limit],
+        });
+        return result.rows.map((r) => ({ path: r.path, fileType: r.file_type ?? null }));
     });
-    return result.rows.map((r) => ({ path: r.path, fileType: r.file_type ?? null }));
 }
 /**
  * Every artifact of one analysis, ordered by path so the same call gives the same rows.
@@ -156,50 +167,58 @@ export async function queryStepArtifactPaths(pool, resourceId, runId, stepId, li
  * query drops such a row, a later refusal says that the artifact never existed, and that reason is
  * false.
  */
-export async function queryAnalysisArtifacts(pool, analysisId) {
-    const result = await pool.query({
-        text: `SELECT path, hash, file_type
+export function queryAnalysisArtifacts(pool, analysisId) {
+    return tryQuery("artifacts.queryAnalysisArtifacts", async () => {
+        const result = await pool.query({
+            text: `SELECT path, hash, file_type
           FROM cortex_artifacts
           WHERE analysis_id = $1
           ORDER BY path`,
-        values: [analysisId],
+            values: [analysisId],
+        });
+        return result.rows.map((r) => ({ path: r.path, hash: r.hash, fileType: r.file_type ?? null }));
     });
-    return result.rows.map((r) => ({ path: r.path, hash: r.hash, fileType: r.file_type ?? null }));
 }
 /** Count step-output artifacts produced by a run — for the run-completed card. */
-export async function countArtifactsForRun(pool, analysisId, runId) {
-    const result = await pool.query({
-        text: `SELECT COUNT(*)::text AS n
+export function countArtifactsForRun(pool, analysisId, runId) {
+    return tryQuery("artifacts.countArtifactsForRun", async () => {
+        const result = await pool.query({
+            text: `SELECT COUNT(*)::text AS n
           FROM cortex_artifacts
           WHERE analysis_id = $1 AND source_run = $2 AND role = 'step_output'`,
-        values: [analysisId, runId],
+            values: [analysisId, runId],
+        });
+        return Number(result.rows[0]?.n ?? 0);
     });
-    return Number(result.rows[0]?.n ?? 0);
 }
-export async function updateArtifactId(pool, resourceId, path, artifactId, fileType) {
-    await pool.query({
-        text: `UPDATE cortex_artifacts SET artifact_id = $1,
+export function updateArtifactId(pool, resourceId, path, artifactId, fileType) {
+    return tryMutation("artifacts.updateArtifactId", async () => {
+        await pool.query({
+            text: `UPDATE cortex_artifacts SET artifact_id = $1,
              file_type = COALESCE($4, file_type)
            WHERE analysis_id = $2 AND path = $3`,
-        values: [artifactId, resourceId, path, fileType ?? null],
+            values: [artifactId, resourceId, path, fileType ?? null],
+        });
     });
 }
-export async function updateFileIds(pool, pairs) {
-    if (pairs.length === 0)
-        return;
-    const values = [];
-    const tuples = [];
-    for (let i = 0; i < pairs.length; i++) {
-        const base = i * 2;
-        tuples.push(`($${base + 1}::text, $${base + 2}::text)`);
-        values.push(pairs[i].artifactId, pairs[i].fileId);
-    }
-    await pool.query({
-        text: `UPDATE cortex_artifacts AS a
+export function updateFileIds(pool, pairs) {
+    return tryMutation("artifacts.updateFileIds", async () => {
+        if (pairs.length === 0)
+            return;
+        const values = [];
+        const tuples = [];
+        for (let i = 0; i < pairs.length; i++) {
+            const base = i * 2;
+            tuples.push(`($${base + 1}::text, $${base + 2}::text)`);
+            values.push(pairs[i].artifactId, pairs[i].fileId);
+        }
+        await pool.query({
+            text: `UPDATE cortex_artifacts AS a
            SET file_id = c.file_id
            FROM (VALUES ${tuples.join(", ")}) AS c(artifact_id, file_id)
            WHERE a.artifact_id = c.artifact_id`,
-        values,
+            values,
+        });
     });
 }
 function mapArtifactRow(row) {

package/dist/state/data-profile.d.ts

@@ -146,9 +146,9 @@ export declare function expireStaleDataProfile(pool: Querier, analysisId: string
  * Reset a ledger row wedged at `running` with no workflow behind it back to
  * `failed`, so the normal retry path can re-profile it.
  *
- * A start that rejects after the CAS already flipped the row to `running`
+ * A start that fails after the CAS already flipped the row to `running`
  * compensates itself (`triggerDataProfile`/`runDataProfile` fail the ledger in
- * their catch). This covers the residual case that compensation cannot: a host
+ * their dispatch). This covers the residual case that compensation cannot: a host
  * that dies in the window between the CAS and the `DBOS.startWorkflow` insert
  * leaves a `running` row with no workflow for recovery to resume — nothing
  * would ever move it off `running`, and every later trigger reports