@inflexa-ai/harness 0.39.1 → 0.39.2

package/dist/execution/artifact-registration.d.ts

@@ -12,6 +12,7 @@
 import { type Result } from "neverthrow";
 import type { Pool, PoolClient } from "pg";
 import type { AgentSession } from "../auth/types.js";
+import type { DbError } from "../lib/db-result.js";
 import { type GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { ArtifactRegistry, ArtifactRegistrationInput } from "./artifact-registry.js";
@@ -29,6 +30,14 @@ export interface ArtifactRegistrationResult {
         error: string;
     }>;
 }
+/** Why a registration stopped: the `register` gate refused it, or a write of the local ledger failed. */
+export type ArtifactRegistrationFailure = {
+    readonly kind: "refused";
+    readonly refusal: GateRefusal;
+} | {
+    readonly kind: "ledger_failed";
+    readonly error: DbError;
+};
 /**
  * Register step-level artifacts (paths under `runs/{runId}/{stepId}/`).
  *
@@ -37,6 +46,7 @@ export interface ArtifactRegistrationResult {
  * and applies any returned external ids back onto the local rows.
  *
  * A refusal of `register` writes no external id: the upserted rows keep
- * `artifact_id = NULL`.
+ * `artifact_id = NULL`. A failed ledger write stops the registration at that
+ * write.
  */
-export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession, logger?: Logger): Promise<Result<ArtifactRegistrationResult, GateRefusal>>;
+export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession, logger?: Logger): Promise<Result<ArtifactRegistrationResult, ArtifactRegistrationFailure>>;

package/dist/execution/artifact-registration.js

@@ -22,7 +22,8 @@ import { upsertArtifacts, updateArtifactId } from "../state/index.js";
  * and applies any returned external ids back onto the local rows.
  *
  * A refusal of `register` writes no external id: the upserted rows keep
- * `artifact_id = NULL`.
+ * `artifact_id = NULL`. A failed ledger write stops the registration at that
+ * write.
  */
 export async function registerStepArtifacts(db, registry, input, session, 
 // A parameter rather than a field on `ArtifactRegistrationInput`: that type is
@@ -51,11 +52,13 @@ logger = createNoopLogger()) {
             fileType: a.type,
         };
     });
-    await upsertArtifacts(db, localEntries);
+    const upserted = await upsertArtifacts(db, localEntries);
+    if (upserted.isErr())
+        return err({ kind: "ledger_failed", error: upserted.error });
     const localPaths = new Set(localEntries.map((e) => e.path));
     const registered = await passGate("ArtifactRegistry.register", registry.register(input, session));
     if (registered.isErr())
-        return err(registered.error);
+        return err({ kind: "refused", refusal: registered.error });
     const result = registered.value;
     // The registry excluded these from `failed` by its own severity judgement, so
     // this is their only record. Logged here rather than left to the registry:
@@ -72,7 +75,9 @@ logger = createNoopLogger()) {
         // (e.g., data inputs that were already born-synced).
         if (!localPaths.has(reg.path))
             continue;
-        await updateArtifactId(db, resourceId, reg.path, reg.externalId);
+        const updated = await updateArtifactId(db, resourceId, reg.path, reg.externalId);
+        if (updated.isErr())
+            return err({ kind: "ledger_failed", error: updated.error });
         externalRegistered++;
     }
     return ok({

package/dist/execution/post-step-pipeline.d.ts

@@ -17,10 +17,10 @@ import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
-import type { GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ArtifactRegistry } from "./artifact-registry.js";
+import { type ArtifactRegistrationFailure } from "./artifact-registration.js";
 import { type FileMetadataEntry } from "./artifact-metadata.js";
 import type { PostStepArtifacts, PostStepContext, StepOutputs } from "../workflows/sandbox-step.js";
 /**
@@ -55,10 +55,7 @@ export declare function generateStepFileMetadata(deps: PostStepPipelineDeps, pos
  * still returned for vector indexing.
  */
 export declare function generateStepSummaryAndWrite(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<StepSummary | undefined>;
-export type StepRegistrationFailure = {
-    readonly kind: "refused";
-    readonly refusal: GateRefusal;
-} | {
+export type StepRegistrationFailure = ArtifactRegistrationFailure | {
     readonly kind: "rejected";
     readonly message: string;
 };
@@ -71,7 +68,7 @@ export declare function describeStepRegistrationFailure(failure: StepRegistratio
  * plus anything rejected as a consequence of one — so a non-zero count means
  * real outputs went unregistered, and the `err` carries the per-file detail (the
  * OSS filesystem registry returns `externalFailed: 0`, so it never trips). A
- * refusal of the `register` gate is the other `err`.
+ * refusal of the `register` gate and a failed ledger write are the other `err`s.
  * Returns the reconciled manifest.
  */
 export declare function reconcileAndRegisterStepArtifacts(deps: PostStepPipelineDeps, postCtx: PostStepContext, manifest: readonly ArtifactManifestEntry[]): Promise<Result<readonly ArtifactManifestEntry[], StepRegistrationFailure>>;

package/dist/execution/post-step-pipeline.js

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import { err, ok } from "neverthrow";
 import { unwrapOrThrow } from "../lib/result.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { describeDbError } from "../lib/db-result.js";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
 import { registerStepArtifacts } from "./artifact-registration.js";
 import { reconcileManifestWithDisk } from "./reconcile-manifest.js";
@@ -94,7 +95,14 @@ export async function generateStepSummaryAndWrite(deps, postCtx, manifest) {
     return summary;
 }
 export function describeStepRegistrationFailure(failure) {
-    return failure.kind === "refused" ? `the artifact registry refused the registration: ${failure.refusal.reason}` : failure.message;
+    switch (failure.kind) {
+        case "refused":
+            return `the artifact registry refused the registration: ${failure.refusal.reason}`;
+        case "ledger_failed":
+            return `the artifact ledger write failed: ${describeDbError(failure.error)}`;
+        case "rejected":
+            return failure.message;
+    }
 }
 /**
  * Reconcile the manifest against disk (drop phantoms, rehash) and register the
@@ -104,7 +112,7 @@ export function describeStepRegistrationFailure(failure) {
  * plus anything rejected as a consequence of one — so a non-zero count means
  * real outputs went unregistered, and the `err` carries the per-file detail (the
  * OSS filesystem registry returns `externalFailed: 0`, so it never trips). A
- * refusal of the `register` gate is the other `err`.
+ * refusal of the `register` gate and a failed ledger write are the other `err`s.
  * Returns the reconciled manifest.
  */
 export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest) {
@@ -129,7 +137,7 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
         collector: lineageCollector,
     }, session, deps.logger);
     if (registered.isErr())
-        return err({ kind: "refused", refusal: registered.error });
+        return err(registered.error);
     const reg = registered.value;
     if (reg.externalFailed > 0) {
         // The registry commits per leaf and per activity, so accepted and rejected

package/dist/index.d.ts

@@ -110,8 +110,8 @@ export type { WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 export { createPool } from "./lib/storage.js";
 export type { PoolConfig } from "./lib/storage.js";
 export type { Pool } from "pg";
-export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile } from "./tasks/data-profile.js";
-export type { DataProfileDeps, DataProfileWorkflowInput, DataProfileTriggerDeps, DataProfileTriggerParams, DataProfileTriggerResult, } from "./tasks/data-profile.js";
+export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile, describeDataProfileStartError } from "./tasks/data-profile.js";
+export type { DataProfileDeps, DataProfileWorkflowInput, DataProfileTriggerDeps, DataProfileTriggerParams, DataProfileTriggerResult, DataProfileStartError, } from "./tasks/data-profile.js";
 /**
  * The synthetic run id the data-profile workflow stamps onto its own frame — the profile has no run
  * row, so this literal is the only thing that identifies its work as the profile's.

package/dist/index.js

@@ -210,7 +210,7 @@ export { createPool } from "./lib/storage.js";
 // when the analysis names a non-empty seeded input set; a failed profile is re-claimed
 // via `tryRetryDataProfile` and then started with `runDataProfile` (the managed retry
 // route's shape — embedders mirror it).
-export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile } from "./tasks/data-profile.js";
+export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile, describeDataProfileStartError } from "./tasks/data-profile.js";
 /**
  * The synthetic run id the data-profile workflow stamps onto its own frame — the profile has no run
  * row, so this literal is the only thing that identifies its work as the profile's.

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

package/dist/state/data-profile.js

@@ -225,9 +225,9 @@ export function expireStaleDataProfile(pool, analysisId, timeoutMs) {
  * 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

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

@@ -17,7 +17,7 @@
  * triggers dedup via the ledger CAS (only one `tryStart/tryRerun/tryRetry`
  * UPDATE wins); each winning attempt starts a workflow under a per-attempt id.
  */
-import { type ResultAsync } from "neverthrow";
+import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
@@ -26,6 +26,7 @@ import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorize
 import type { StagedInput } from "../execution/staged-input.js";
 import type { SandboxAgentDeps } from "../agents/sandbox/shared.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { DbError } from "../lib/db-result.js";
 import { type GateRefusal } from "../lib/hooks.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
@@ -149,9 +150,25 @@ export declare function runDataProfileBody(input: DataProfileWorkflowInput, deps
  * - `"already_running"`: a workflow already owns the row, and nothing new ran.
  * - `"completed"`: the analysis has no input files, so the row is `completed` at once
  *   with no result. No workflow ran (see {@link completeEmptyDataProfile}).
- * - `"failed"`: the trigger refused the call or faulted, and the row is unchanged.
+ * - `"failed"`: the trigger refused the call, and the row is unchanged.
  */
 export type DataProfileTriggerResult = "started" | "restarted" | "already_running" | "completed" | "failed";
+/**
+ * Why the dispatch of a claimed profile started no workflow. The dispatch writes `failed` to the claimed
+ * row before a caller reads the `err`:
+ * - `refused`: `RunAuthorizer.authorize` gave an `err`. `reason` and `suspend` are the values of the host.
+ * - `start_failed`: DBOS did not start the workflow. `cause` is the throw of DBOS.
+ */
+export type DataProfileStartError = {
+    readonly type: "refused";
+    readonly reason: string;
+    readonly suspend: boolean;
+} | {
+    readonly type: "start_failed";
+    readonly cause: unknown;
+};
+/** A one-line, user-facing description of a `DataProfileStartError`. */
+export declare function describeDataProfileStartError(e: DataProfileStartError): string;
 /**
  * Route-side deps for triggering the data-profile workflow: the ledger pool,
  * the run authorizer, and the registered workflow callable. The body's
@@ -213,16 +230,17 @@ export declare function dataProfileWorkflowId(analysisId: string, nonce: string)
  * `"completed"`. An empty manifest against a seed that names files is a divergence
  * between the caller and the ledger, and the trigger refuses it.
  *
- * Returns what happened, so the caller can surface it (e.g. in the seed response).
+ * Returns what happened, so the caller can surface it (e.g. in the seed response). A
+ * failed ledger read or claim is the `err`. The dispatch settles its own row, thus a
+ * refusal or a failed start after a claim shows on the ledger only.
  */
-export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<DataProfileTriggerResult>;
+export declare function triggerDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): ResultAsync<DataProfileTriggerResult, DbError>;
 /**
  * Start the data-profile workflow for an already-claimed analysis (the retry
  * route claims via `tryRetryDataProfile`, then calls this). The caller does not
- * await the workflow's completion, but a start that rejects compensates the
- * ledger (see {@link compensateStartFailure}) before re-throwing, so a caller's
- * own `.catch` still observes the error and the row never wedges at `running`.
- * A refused authorization fails the row with the reason of the host, and the
- * promise resolves: the row is where a caller reads the outcome.
+ * wait for the completion of the workflow. A refused authorization and a failed
+ * start each settle the row as `failed` before the `err` (see
+ * {@link dispatchClaimedProfile}), thus a caller that minted an authorization
+ * can revoke it.
  */
-export declare function runDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): Promise<void>;
+export declare function runDataProfile(deps: DataProfileTriggerDeps, params: DataProfileTriggerParams): ResultAsync<void, DataProfileStartError>;

package/dist/tasks/data-profile.js

@@ -19,7 +19,7 @@
  */
 import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { randomUUID } from "node:crypto";
-import { err, ok } from "neverthrow";
+import { ResultAsync, err, ok } from "neverthrow";
 import { forStep, forSubAgent } from "../auth/types.js";
 import { createDataProfilerAgent } from "../agents/sandbox/data-profiler.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
@@ -345,14 +345,14 @@ export async function runDataProfileBody(input, deps) {
             return;
         }
         // 2. Register staged files in cortex_artifacts
-        await upsertArtifacts(deps.pool, stagedInputs.map((f) => ({
+        unwrapOrThrow(await upsertArtifacts(deps.pool, stagedInputs.map((f) => ({
             resourceId: analysisId,
             path: inputArtifactPath(f),
             hash: f.hash,
             size: f.size,
             role: "input",
             fileId: f.fileId,
-        })));
+        }))));
         const executionId = generateExecutionId(DATA_PROFILE_AGENT_ID);
         const workflowId = DBOS.workflowID ?? `${DATA_PROFILE_RUN_LITERAL}:${executionId}`;
         const childSession = forSubAgent(runSession, DATA_PROFILE_AGENT_ID);
@@ -636,6 +636,15 @@ function settleTerminalWrite(logger, analysisId, write, status) {
     }
     recordRunCompleted({ workflow: "data_profile", status, durationMs: elapsedSinceIso(write.startedAt) });
 }
+/** A one-line, user-facing description of a `DataProfileStartError`. */
+export function describeDataProfileStartError(e) {
+    switch (e.type) {
+        case "refused":
+            return `the profile run was not authorized: ${e.reason}`;
+        case "start_failed":
+            return `the profile workflow did not start: ${profileFailureReason(e.cause)}`;
+    }
+}
 /**
  * Resolve the `RunSession` the workflow runs under. Whether the authorization
  * is freshly minted (Cortex-owned) or reused (caller-owned) is decided by the
@@ -667,18 +676,14 @@ export function dataProfileWorkflowId(analysisId, nonce) {
     return `dataprofile:${analysisId}:${nonce}`;
 }
 /**
- * Authorize the run via the `RunAuthorizer` and start the data-profile workflow
- * under a per-attempt id `dataprofile:{analysisId}:{nonce}` — concurrent
- * triggers are already serialized by the ledger CAS. The caller has already
- * staged the inputs and supplied the manifest in `params.stagedInputs`; this
- * forwards it into the workflow input. Fire-and-forget: the handle result is
- * not awaited.
+ * Start the data-profile workflow under the authorization and a per-attempt id
+ * `dataprofile:{analysisId}:{nonce}` — concurrent triggers are already
+ * serialized by the ledger CAS. The caller has already staged the inputs and
+ * supplied the manifest in `params.stagedInputs`; this forwards it into the
+ * workflow input. The handle result is not awaited.
  */
-async function startDataProfileWorkflow(deps, params) {
-    const authorized = await authorizeDataProfile(deps, params);
-    if (authorized.isErr())
-        return err(authorized.error);
-    const { runSession, ownsMandate } = authorized.value; // oss-core-managed-ok
+async function startDataProfileWorkflow(deps, params, authorization) {
+    const { runSession, ownsMandate } = authorization; // oss-core-managed-ok
     const attemptNonce = randomUUID();
     await DBOS.startWorkflow(deps.workflow, {
         workflowID: dataProfileWorkflowId(params.analysisId, attemptNonce),
@@ -688,20 +693,29 @@ async function startDataProfileWorkflow(deps, params) {
         ownsMandate, // oss-core-managed-ok
         stagedInputs: params.stagedInputs,
     });
-    return ok(undefined);
 }
 /**
- * Dispatch a claimed profile, fire-and-forget. The claim already flipped the
- * row to `running`, thus a refused authorization and a rejected start each
- * settle the row as `failed`, and it never wedges at `running`.
+ * Authorize and start a claimed profile. The claim already flipped the row to
+ * `running`, thus a refused authorization and a failed start each settle the
+ * row as `failed` before the `err`, and the row never wedges at `running`. A
+ * rejected `authorize` promise is a defect of the host: the row is settled the
+ * same way, and the rejection passes through.
  */
 async function dispatchClaimedProfile(deps, params, phase) {
-    const started = await startDataProfileWorkflow(deps, params).catch(async (cause) => {
-        await compensateStartFailure(deps, params.analysisId, phase, cause);
-        return undefined;
+    const authorized = await Promise.resolve(authorizeDataProfile(deps, params)).catch(async (defect) => {
+        await compensateStartFailure(deps, params.analysisId, phase, defect);
+        throw defect;
     });
-    if (started?.isErr())
-        await refuseClaimedProfile(deps, params.analysisId, phase, started.error);
+    if (authorized.isErr()) {
+        await refuseClaimedProfile(deps, params.analysisId, phase, authorized.error);
+        return err({ type: "refused", reason: authorized.error.reason, suspend: authorized.error.kind === "suspended" });
+    }
+    const started = await ResultAsync.fromPromise(startDataProfileWorkflow(deps, params, authorized.value), (cause) => cause);
+    if (started.isErr()) {
+        await compensateStartFailure(deps, params.analysisId, phase, started.error);
+        return err({ type: "start_failed", cause: started.error });
+    }
+    return ok(undefined);
 }
 /**
  * Attempt to claim and run data profiling for an analysis, then start the workflow
@@ -720,70 +734,85 @@ async function dispatchClaimedProfile(deps, params, phase) {
  * `"completed"`. An empty manifest against a seed that names files is a divergence
  * between the caller and the ledger, and the trigger refuses it.
  *
- * Returns what happened, so the caller can surface it (e.g. in the seed response).
+ * Returns what happened, so the caller can surface it (e.g. in the seed response). A
+ * failed ledger read or claim is the `err`. The dispatch settles its own row, thus a
+ * refusal or a failed start after a claim shows on the ledger only.
  */
-export async function triggerDataProfile(deps, params) {
+export function triggerDataProfile(deps, params) {
+    return new ResultAsync(claimAndDispatchProfile(deps, params));
+}
+async function claimAndDispatchProfile(deps, params) {
     const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId: params.analysisId });
     const { analysisId } = params;
-    try {
-        // ADVISORY pre-check, not the enforcement — the claim CAS carries the same seed
-        // conjunct (see `SEEDED` in state/data-profile.ts) and is what actually makes a
-        // seedless `running` row impossible. This read exists only to name the cause: on
-        // the ordinary non-racing path it turns an opaque "no claim matched" into a
-        // precise reason. An empty array is not a seed — it names zero files. Reads via
-        // `loadSeedInputFileIds`, which returns null for BOTH a missing analysis row and
-        // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
-        const seeded = unwrapOrThrow(await loadSeedInputFileIds(deps.pool, analysisId));
-        if (params.stagedInputs.length === 0) {
-            // The trigger validates the manifest it is about to dispatch against the ledger
-            // seed. A seeded row profiled against an EMPTY manifest would claim `running` and
-            // then hit the body's empty-manifest path, and complete with a NULL result while
-            // the seed still names files. Refuse the divergence before any claim.
-            if (seeded !== null && seeded.length > 0) {
-                logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
-                return "failed";
-            }
-            // The analysis has no input files, so there is nothing to profile. The row is
-            // `completed` at once, with no workflow. The CAS carries the same seed
-            // predicate as this pre-read, so a seed upsert that lands in between cannot be
-            // hidden behind a finished profile: the stamp refuses, and the status read
-            // below names the cause.
-            if (unwrapOrThrow(await completeEmptyDataProfile(deps.pool, analysisId)))
-                return "completed";
-            const current = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
-            if (current?.status === "running")
-                return "already_running";
-            logger.error("trigger rejected: empty-set completion refused (no analysis row, or the seed now names files)");
-            return "failed";
-        }
-        // A non-empty manifest against a seed that names no file: the caller skipped the
-        // seed, or the analysis row is missing. Name the cause before any claim.
-        if (seeded === null || seeded.length === 0) {
-            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
-            return "failed";
-        }
-        const started = unwrapOrThrow(await tryStartDataProfile(deps.pool, analysisId));
-        if (started) {
-            void dispatchClaimedProfile(deps, params, "Run");
-            return "started";
+    // ADVISORY pre-check, not the enforcement — the claim CAS carries the same seed
+    // conjunct (see `SEEDED` in state/data-profile.ts) and is what actually makes a
+    // seedless `running` row impossible. This read exists only to name the cause: on
+    // the ordinary non-racing path it turns an opaque "no claim matched" into a
+    // precise reason. An empty array is not a seed — it names zero files. Reads via
+    // `loadSeedInputFileIds`, which returns null for BOTH a missing analysis row and
+    // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
+    const seedRead = await loadSeedInputFileIds(deps.pool, analysisId);
+    if (seedRead.isErr())
+        return err(seedRead.error);
+    const seeded = seedRead.value;
+    if (params.stagedInputs.length === 0) {
+        // The trigger validates the manifest it is about to dispatch against the ledger
+        // seed. A seeded row profiled against an EMPTY manifest would claim `running` and
+        // then hit the body's empty-manifest path, and complete with a NULL result while
+        // the seed still names files. Refuse the divergence before any claim.
+        if (seeded !== null && seeded.length > 0) {
+            logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
+            return ok("failed");
         }
-        const restarted = unwrapOrThrow(await tryRerunDataProfile(deps.pool, analysisId));
-        if (restarted) {
-            void dispatchClaimedProfile(deps, params, "Re-run");
-            return "restarted";
-        }
-        const status = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
-        if (status?.status === "running")
-            return "already_running";
-        return "failed";
+        // The analysis has no input files, so there is nothing to profile. The row is
+        // `completed` at once, with no workflow. The CAS carries the same seed
+        // predicate as this pre-read, so a seed upsert that lands in between cannot be
+        // hidden behind a finished profile: the stamp refuses, and the status read
+        // below names the cause.
+        const completed = await completeEmptyDataProfile(deps.pool, analysisId);
+        if (completed.isErr())
+            return err(completed.error);
+        if (completed.value)
+            return ok("completed");
+        const current = await loadDataProfileStatus(deps.pool, analysisId);
+        if (current.isErr())
+            return err(current.error);
+        if (current.value?.status === "running")
+            return ok("already_running");
+        logger.error("trigger rejected: empty-set completion refused (no analysis row, or the seed now names files)");
+        return ok("failed");
     }
-    catch (err) {
-        logger.error("trigger error", logger.errorFields(err));
-        return "failed";
+    // A non-empty manifest against a seed that names no file: the caller skipped the
+    // seed, or the analysis row is missing. Name the cause before any claim.
+    if (seeded === null || seeded.length === 0) {
+        logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
+        return ok("failed");
+    }
+    const started = await tryStartDataProfile(deps.pool, analysisId);
+    if (started.isErr())
+        return err(started.error);
+    if (started.value) {
+        dispatchInBackground(deps, params, "Run");
+        return ok("started");
+    }
+    const restarted = await tryRerunDataProfile(deps.pool, analysisId);
+    if (restarted.isErr())
+        return err(restarted.error);
+    if (restarted.value) {
+        dispatchInBackground(deps, params, "Re-run");
+        return ok("restarted");
     }
+    const status = await loadDataProfileStatus(deps.pool, analysisId);
+    if (status.isErr())
+        return err(status.error);
+    return ok(status.value?.status === "running" ? "already_running" : "failed");
+}
+/** The dispatch settles the row on each arm and logs a defect, thus the trigger keeps no outcome of it. */
+function dispatchInBackground(deps, params, phase) {
+    void dispatchClaimedProfile(deps, params, phase).catch(() => undefined);
 }
 /**
- * Compensate a fire-and-forget start that rejected. The ledger CAS in
+ * Compensate a start that failed after the claim. The ledger CAS in
  * `tryStart`/`tryRerun`/`tryRetry` already flipped the row to `running`; if the
  * dispatch never landed a workflow, DBOS has nothing to recover, so without
  * this the row would sit at `running` forever and every later trigger would
@@ -827,23 +856,13 @@ async function failClaimedProfile(deps, analysisId, phase, reason) {
 /**
  * Start the data-profile workflow for an already-claimed analysis (the retry
  * route claims via `tryRetryDataProfile`, then calls this). The caller does not
- * await the workflow's completion, but a start that rejects compensates the
- * ledger (see {@link compensateStartFailure}) before re-throwing, so a caller's
- * own `.catch` still observes the error and the row never wedges at `running`.
- * A refused authorization fails the row with the reason of the host, and the
- * promise resolves: the row is where a caller reads the outcome.
+ * wait for the completion of the workflow. A refused authorization and a failed
+ * start each settle the row as `failed` before the `err` (see
+ * {@link dispatchClaimedProfile}), thus a caller that minted an authorization
+ * can revoke it.
  */
-export async function runDataProfile(deps, params) {
-    let started;
-    try {
-        started = await startDataProfileWorkflow(deps, params);
-    }
-    catch (cause) {
-        await compensateStartFailure(deps, params.analysisId, "Retry", cause);
-        throw cause;
-    }
-    if (started.isErr())
-        await refuseClaimedProfile(deps, params.analysisId, "Retry", started.error);
+export function runDataProfile(deps, params) {
+    return new ResultAsync(dispatchClaimedProfile(deps, params, "Retry"));
 }
 /**
  * Concise, UI-safe failure reason. `data_profile_error` is surfaced verbatim

package/dist/workflows/execute-analysis.js

@@ -69,7 +69,7 @@
  *       via `inspectRun`)
  */
 import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
-import { ResultAsync, err, ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { forStep } from "../auth/types.js";
@@ -286,7 +286,7 @@ async function collectUpstreamHandoffs(args) {
     const handoffs = [];
     for (const summary of summaries) {
         const outputDir = stepSubdir(runStepDir(runId, summary.stepId), "output");
-        const artifacts = await queryStepArtifactPaths(pool, analysisId, runId, summary.stepId, MAX_UPSTREAM_ARTIFACTS);
+        const artifacts = unwrapOrThrow(await queryStepArtifactPaths(pool, analysisId, runId, summary.stepId, MAX_UPSTREAM_ARTIFACTS));
         handoffs.push({
             stepId: summary.stepId,
             agentId: summary.agentId,
@@ -1124,7 +1124,9 @@ async function collectAndComplete(args) {
     // beat the CLI's poll-and-shutdown). These branches only fan out the UI stream part, whose
     // completed/failed shapes genuinely differ — the provenance record does not.
     if (status === "completed" || status === "partial") {
-        const artifactCount = await DBOS.runStep(async () => await ResultAsync.fromPromise(countArtifactsForRun(deps.pool, input.analysisId, runId), () => "the artifact count failed").unwrapOr(0), { name: "count-run-artifacts" });
+        const artifactCount = await DBOS.runStep(async () => await countArtifactsForRun(deps.pool, input.analysisId, runId).unwrapOr(0), {
+            name: "count-run-artifacts",
+        });
         await emitStreamPart({
             type: "data-run-completed",
             runId,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.39.1",
+    "version": "0.39.2",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",