@inflexa-ai/harness 0.39.0 → 0.39.2

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