@inflexa-ai/harness 0.1.1

package/dist/state/active-sandboxes.js

@@ -0,0 +1,100 @@
+/**
+ * Active-sandbox registry (CONTEXT.md) — the projection over
+ * `cortex_step_executions` rows with a non-null `sandbox_ref` and a running
+ * status. Owns the `sandbox_ref` + `exec_id` columns: written by
+ * `sandbox/create-sandbox.ts` on mint, cleared on teardown, enumerated by
+ * `sandbox/watchdog.ts` for liveness sweeps.
+ */
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+/**
+ * Record the live sandbox handle on a step row. Called inside the
+ * `createSandbox` DBOS step after the backend has confirmed the sandbox
+ * is up. The `callbackSecret` is deliberately not part of the persisted
+ * shape (see the harness-sandbox-exec spec) — it lives only in the cached step output.
+ */
+export function setSandboxRef(pool, runId, stepId, sandboxRef, execId) {
+    return tryMutation("activeSandboxes.setSandboxRef", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET sandbox_ref = $1::jsonb, exec_id = $2
+          WHERE run_id = $3 AND step_id = $4`,
+            values: [JSON.stringify(sandboxRef), execId, runId, stepId],
+        });
+    });
+}
+/**
+ * Tag the active-sandbox row with the exec currently in flight. Called from
+ * `run-exec.ts` right before `awaitExec` so the liveness watchdog can target
+ * the hung exec when the sandbox dies mid-command. Targets the same
+ * `(run_id, step_id)` row `setSandboxRef` writes and `queryActiveSandboxes`
+ * enumerates. Overwritten by the next exec; cleared on teardown.
+ */
+export function setActiveExecId(pool, runId, stepId, execId) {
+    return tryMutation("activeSandboxes.setActiveExecId", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET exec_id = $1
+          WHERE run_id = $2 AND step_id = $3`,
+            values: [execId, runId, stepId],
+        });
+    });
+}
+/**
+ * Clear the sandbox handle. Called inside the `teardown` DBOS step. Safe
+ * to call when no sandbox was ever recorded — the UPDATE simply targets
+ * zero rows.
+ */
+export function clearSandboxRef(pool, runId, stepId) {
+    return tryMutation("activeSandboxes.clearSandboxRef", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET sandbox_ref = NULL, exec_id = NULL
+          WHERE run_id = $1 AND step_id = $2`,
+            values: [runId, stepId],
+        });
+    });
+}
+/**
+ * Reconcile a step row after the reaper deletes its sandbox machine (ADR
+ * 0016). Always clears `sandbox_ref`/`exec_id` (drops the row from the
+ * active-sandbox registry, ending the watchdog churn); a row still stuck at
+ * `status='running'` — a cancellation that never ran its `mark-*` step — is
+ * also flipped to the owning workflow's terminal status so a terminal workflow
+ * never leaves a perpetually-"running" step behind. Returns true if a row
+ * matched. Safe when no row exists (Class A pure orphan): matches zero rows.
+ */
+export function reconcileReapedSandbox(pool, sandboxId, terminalStatus) {
+    // `completed_at` is a TEXT column holding ISO-8601 strings (see
+    // `step-executions.ts`), so bind one — `now()` is `timestamptz` and the CASE
+    // cannot unify a timestamptz branch with the text column ("CASE types text
+    // and timestamp with time zone cannot be matched"), which aborted every sweep.
+    const completedAt = new Date().toISOString();
+    return tryMutation("activeSandboxes.reconcileReapedSandbox", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET sandbox_ref = NULL,
+              exec_id = NULL,
+              status = CASE WHEN status = 'running' THEN $2 ELSE status END,
+              completed_at = CASE WHEN status = 'running' THEN $3 ELSE completed_at END
+          WHERE sandbox_ref->>'sandboxId' = $1`,
+            values: [sandboxId, terminalStatus, completedAt],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+export function queryActiveSandboxes(pool) {
+    return tryQuery("activeSandboxes.queryActiveSandboxes", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id, step_id, analysis_id, sandbox_ref, exec_id
+          FROM cortex_step_executions
+          WHERE status = 'running' AND sandbox_ref IS NOT NULL`,
+        });
+        return result.rows.map((r) => ({
+            runId: r.run_id,
+            stepId: r.step_id,
+            analysisId: r.analysis_id,
+            sandboxRef: r.sandbox_ref,
+            execId: r.exec_id ?? null,
+        }));
+    });
+}

package/dist/state/analyses-metrics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cross-entity aggregate reads used by `routes/analyses-metrics.ts` to build
+ * the per-analysis metrics view. Each query touches one table; the view is
+ * the batch shape callers want.
+ */
+import { type ResultAsync } from "neverthrow";
+import { type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+export declare function queryRunCountsByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<Array<{
+    analysisId: string;
+    status: string;
+    count: number;
+}>, DbError>;
+export declare function queryThreadCountsByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<Array<{
+    analysisId: string;
+    count: number;
+}>, DbError>;
+export declare function queryDataProfileStatusByAnalyses(pool: Querier, analysisIds: string[]): ResultAsync<Array<{
+    analysisId: string;
+    status: string | null;
+}>, DbError>;

package/dist/state/analyses-metrics.js

@@ -0,0 +1,59 @@
+/**
+ * Cross-entity aggregate reads used by `routes/analyses-metrics.ts` to build
+ * the per-analysis metrics view. Each query touches one table; the view is
+ * the batch shape callers want.
+ */
+import { okAsync } from "neverthrow";
+import { tryQuery } from "../lib/db-result.js";
+export function queryRunCountsByAnalyses(pool, analysisIds) {
+    if (analysisIds.length === 0)
+        return okAsync([]);
+    return tryQuery("analysesMetrics.queryRunCountsByAnalyses", async () => {
+        const result = await pool.query({
+            text: `SELECT analysis_id, status, COUNT(*)::int AS count
+             FROM cortex_runs
+             WHERE analysis_id = ANY($1::text[])
+             GROUP BY analysis_id, status`,
+            values: [analysisIds],
+        });
+        return result.rows.map((r) => ({
+            analysisId: r.analysis_id,
+            status: r.status,
+            count: r.count,
+        }));
+    });
+}
+export function queryThreadCountsByAnalyses(pool, analysisIds) {
+    if (analysisIds.length === 0)
+        return okAsync([]);
+    return tryQuery("analysesMetrics.queryThreadCountsByAnalyses", async () => {
+        const result = await pool.query({
+            text: `SELECT analysis_id, COUNT(*)::int AS count
+             FROM cortex_analysis_threads
+             WHERE analysis_id = ANY($1::text[])
+               AND deleted_at IS NULL
+             GROUP BY analysis_id`,
+            values: [analysisIds],
+        });
+        return result.rows.map((r) => ({
+            analysisId: r.analysis_id,
+            count: r.count,
+        }));
+    });
+}
+export function queryDataProfileStatusByAnalyses(pool, analysisIds) {
+    if (analysisIds.length === 0)
+        return okAsync([]);
+    return tryQuery("analysesMetrics.queryDataProfileStatusByAnalyses", async () => {
+        const result = await pool.query({
+            text: `SELECT analysis_id, data_profile_status
+             FROM cortex_analysis_state
+             WHERE analysis_id = ANY($1::text[])`,
+            values: [analysisIds],
+        });
+        return result.rows.map((r) => ({
+            analysisId: r.analysis_id,
+            status: r.data_profile_status ?? null,
+        }));
+    });
+}

package/dist/state/analyses.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `cortex_analysis_state` operations — analysis lifecycle and billing context.
+ */
+import type { ResultAsync } from "neverthrow";
+import { type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+/**
+ * Upsert a cortex_analysis_state row.
+ *
+ * The seed endpoint is called repeatedly; this function handles both the
+ * initial INSERT and subsequent UPDATEs by writing ALL mutable fields on
+ * every call. Re-upserts replace `context` and `billing_context` wholesale.
+ *
+ * User identity is derived from the ambient credential's JWT `sub` claim
+ * at request time — not persisted in this table.
+ *
+ * INTENTIONAL: split-attribution across a single run.
+ * If the seed re-upserts mid-workflow (e.g., the billing context's VK rotates),
+ * in-flight steps that have already issued LLM calls keep the old attribution
+ * on those calls, while subsequent steps in the same run pick up the new
+ * identity on their next `billedAgent` resolution. This is by design —
+ * usage rows contain full per-call attribution, so spend is
+ * always assignable even when it crosses a rotation boundary.
+ */
+export declare function upsertAnalysis(pool: Querier, resourceId: string, context: string | null, billingContext: Record<string, string> | null, inputFileIds?: string[]): ResultAsync<void, DbError>;
+export declare function loadAnalysisStatus(pool: Querier, resourceId: string): ResultAsync<{
+    status: string;
+    context: string | null;
+} | null, DbError>;
+/**
+ * Suspend an analysis due to a 402 `budget_exceeded` error.
+ * Idempotent — no-op if already suspended.
+ *
+ * The only cause of suspension today is budget exhaustion; no reason is
+ * persisted. If a second cause arises, add a column rather than a param so
+ * history is queryable.
+ */
+export declare function suspendAnalysis(pool: Querier, analysisId: string): ResultAsync<void, DbError>;
+/**
+ * Resume a suspended analysis after the user tops up.
+ * Only transitions from `suspended_insufficient_funds` → `active`.
+ */
+export declare function resumeAnalysis(pool: Querier, analysisId: string): ResultAsync<void, DbError>;
+/**
+ * Resolve the persisted billing context for an analysis.
+ *
+ * Single DB-read chokepoint used by `requireAnalysisBilling` middleware and
+ * by any downstream code that needs to re-read billing identity. The driver
+ * read is wrapped as a `DbError`; the missing-row / null-billing /
+ * unparseable-JSON cases are control-flow throws (a misconfiguration, not a
+ * driver failure) that short-circuit the chain and surface verbatim.
+ *
+ * User identity (`HEADERS.User`) is derived from the ambient credential's
+ * JWT `sub` claim by `credential-middleware`, not from the DB.
+ */
+export declare function resolveAnalysisBilling(pool: Querier, analysisId: string): ResultAsync<{
+    billingContext: Record<string, string>;
+}, DbError>;

package/dist/state/analyses.js

@@ -0,0 +1,132 @@
+/**
+ * `cortex_analysis_state` operations — analysis lifecycle and billing context.
+ */
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+/**
+ * Upsert a cortex_analysis_state row.
+ *
+ * The seed endpoint is called repeatedly; this function handles both the
+ * initial INSERT and subsequent UPDATEs by writing ALL mutable fields on
+ * every call. Re-upserts replace `context` and `billing_context` wholesale.
+ *
+ * User identity is derived from the ambient credential's JWT `sub` claim
+ * at request time — not persisted in this table.
+ *
+ * INTENTIONAL: split-attribution across a single run.
+ * If the seed re-upserts mid-workflow (e.g., the billing context's VK rotates),
+ * in-flight steps that have already issued LLM calls keep the old attribution
+ * on those calls, while subsequent steps in the same run pick up the new
+ * identity on their next `billedAgent` resolution. This is by design —
+ * usage rows contain full per-call attribution, so spend is
+ * always assignable even when it crosses a rotation boundary.
+ */
+export function upsertAnalysis(pool, resourceId, context, billingContext, inputFileIds) {
+    const now = new Date().toISOString();
+    return tryMutation("analyses.upsertAnalysis", async () => {
+        await pool.query({
+            text: `INSERT INTO cortex_analysis_state
+            (analysis_id, status, context, billing_context, data_profile_status,
+             seed_input_file_ids, created_at, updated_at)
+            VALUES ($1, 'active', $2, $3::jsonb, 'pending', $4::jsonb, $5, $6)
+            ON CONFLICT (analysis_id) DO UPDATE SET
+              context = EXCLUDED.context,
+              billing_context = EXCLUDED.billing_context,
+              seed_input_file_ids = COALESCE(EXCLUDED.seed_input_file_ids, cortex_analysis_state.seed_input_file_ids),
+              updated_at = EXCLUDED.updated_at`,
+            values: [
+                resourceId,
+                context ?? null,
+                billingContext === null ? null : JSON.stringify(billingContext),
+                inputFileIds ? JSON.stringify(inputFileIds) : null,
+                now,
+                now,
+            ],
+        });
+    });
+}
+export function loadAnalysisStatus(pool, resourceId) {
+    return tryQuery("analyses.loadAnalysisStatus", async () => {
+        const result = await pool.query({
+            text: "SELECT status, context FROM cortex_analysis_state WHERE analysis_id = $1",
+            values: [resourceId],
+        });
+        const row = result.rows[0];
+        if (!row)
+            return null;
+        return { status: row.status, context: row.context ?? null };
+    });
+}
+/**
+ * Suspend an analysis due to a 402 `budget_exceeded` error.
+ * Idempotent — no-op if already suspended.
+ *
+ * The only cause of suspension today is budget exhaustion; no reason is
+ * persisted. If a second cause arises, add a column rather than a param so
+ * history is queryable.
+ */
+export function suspendAnalysis(pool, analysisId) {
+    return tryMutation("analyses.suspendAnalysis", async () => {
+        await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET status = 'suspended_insufficient_funds', updated_at = $1
+            WHERE analysis_id = $2 AND status != 'suspended_insufficient_funds'`,
+            values: [new Date().toISOString(), analysisId],
+        });
+    });
+}
+/**
+ * Resume a suspended analysis after the user tops up.
+ * Only transitions from `suspended_insufficient_funds` → `active`.
+ */
+export function resumeAnalysis(pool, analysisId) {
+    return tryMutation("analyses.resumeAnalysis", async () => {
+        await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET status = 'active', updated_at = $1
+            WHERE analysis_id = $2 AND status = 'suspended_insufficient_funds'`,
+            values: [new Date().toISOString(), analysisId],
+        });
+    });
+}
+/**
+ * Resolve the persisted billing context for an analysis.
+ *
+ * Single DB-read chokepoint used by `requireAnalysisBilling` middleware and
+ * by any downstream code that needs to re-read billing identity. The driver
+ * read is wrapped as a `DbError`; the missing-row / null-billing /
+ * unparseable-JSON cases are control-flow throws (a misconfiguration, not a
+ * driver failure) that short-circuit the chain and surface verbatim.
+ *
+ * User identity (`HEADERS.User`) is derived from the ambient credential's
+ * JWT `sub` claim by `credential-middleware`, not from the DB.
+ */
+export function resolveAnalysisBilling(pool, analysisId) {
+    return tryQuery("analyses.resolveAnalysisBilling", () => pool.query({
+        text: "SELECT billing_context FROM cortex_analysis_state WHERE analysis_id = $1",
+        values: [analysisId],
+    })).map((result) => {
+        const row = result.rows[0];
+        if (!row) {
+            throw new Error(`resolveAnalysisBilling: no cortex_analysis_state row for analysisId=${analysisId}`);
+        }
+        const rawBilling = row.billing_context;
+        if (rawBilling === null || rawBilling === undefined) {
+            throw new Error(`resolveAnalysisBilling: billing_context missing for analysisId=${analysisId}`);
+        }
+        // JSONB is parsed by `pg` into native objects. Legacy TEXT rows (if any
+        // slipped through) arrive as strings — parse them.
+        let billingContext;
+        if (typeof rawBilling === "string") {
+            try {
+                billingContext = JSON.parse(rawBilling);
+            }
+            catch (err) {
+                throw new Error(`resolveAnalysisBilling: billing_context is not valid JSON for analysisId=${analysisId}: ${err instanceof Error ? err.message : err}`, { cause: err });
+            }
+        }
+        else {
+            billingContext = rawBilling;
+        }
+        return { billingContext };
+    });
+}

package/dist/state/artifacts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `cortex_artifacts` operations — artifact upsert, lookup, and file-id
+ * reconciliation.
+ */
+import type { Querier } from "./db.js";
+import type { ArtifactRow } from "./schema.js";
+export interface RegisterArtifactInput {
+    resourceId: string;
+    path: string;
+    hash: string;
+    size: number;
+    role: "input" | "step_output";
+    sourceStep?: string | null;
+    sourceRun?: string | null;
+    fileType?: string | null;
+    /**
+     * Upstream file identity. Set for `input` rows at materialization so
+     * provenance lineage can attribute data inputs by `fileId`; left null for
+     * `step_output` rows (their `file_id` is assigned after upload-sync).
+     */
+    fileId?: string | null;
+}
+export declare function upsertArtifact(pool: Querier, entry: RegisterArtifactInput): Promise<void>;
+/**
+ * Batched upsert — writes entries in multi-row `INSERT ... VALUES` statements
+ * of at most {@link ROWS_PER_STATEMENT} rows. Callers range from per-step
+ * manifests (tens of files) to a data-profile's full staged-input manifest
+ * (unbounded — directory inputs can reach tens of thousands of files).
+ * Chunks run sequentially without a wrapping transaction: the upsert is
+ * 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>;
+/** Result type for input artifact metadata lookups. */
+export interface InputArtifactMeta {
+    path: string;
+    hash: string;
+    size: number;
+    fileId: string | null;
+}
+/**
+ * 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[]>;
+/** 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 updateFileIds(pool: Querier, pairs: Array<{
+    artifactId: string;
+    fileId: string;
+}>): Promise<void>;

package/dist/state/artifacts.js

@@ -0,0 +1,175 @@
+/**
+ * `cortex_artifacts` operations — artifact upsert, lookup, and file-id
+ * reconciliation.
+ */
+export async function upsertArtifact(pool, entry) {
+    const now = new Date().toISOString();
+    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
+            hash = EXCLUDED.hash,
+            size = EXCLUDED.size,
+            role = EXCLUDED.role,
+            source_step = EXCLUDED.source_step,
+            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,
+        ],
+    });
+}
+const COLS_PER_ROW = 10;
+/**
+ * Rows per INSERT statement. The Postgres extended protocol carries the Bind
+ * message's parameter count as an Int16, so a statement is capped at 65,535
+ * bind parameters — beyond that the count silently wraps and the server
+ * rejects with 08P01 ("bind message has N parameter formats but 0
+ * parameters"). 1,000 rows × 10 columns stays an order of magnitude under the
+ * cap while keeping round-trips negligible even for huge input manifests.
+ */
+const ROWS_PER_STATEMENT = 1_000;
+/**
+ * Batched upsert — writes entries in multi-row `INSERT ... VALUES` statements
+ * of at most {@link ROWS_PER_STATEMENT} rows. Callers range from per-step
+ * manifests (tens of files) to a data-profile's full staged-input manifest
+ * (unbounded — directory inputs can reach tens of thousands of files).
+ * Chunks run sequentially without a wrapping transaction: the upsert is
+ * 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) {
+    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
+          (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
+            hash = EXCLUDED.hash,
+            size = EXCLUDED.size,
+            role = EXCLUDED.role,
+            source_step = EXCLUDED.source_step,
+            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,
+        });
+    }
+}
+/**
+ * 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
+          FROM cortex_artifacts
+          WHERE analysis_id = $1 AND role = 'input' AND path = ANY($2::text[])`,
+        values: [analysisId, paths],
+    });
+    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,
+                 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],
+    });
+    return result.rows.map(mapArtifactRow);
+}
+/** 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
+          FROM cortex_artifacts
+          WHERE analysis_id = $1 AND source_run = $2 AND role = 'step_output'`,
+        values: [analysisId, runId],
+    });
+    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,
+             file_type = COALESCE($4, file_type)
+           WHERE analysis_id = $2 AND path = $3`,
+        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
+           SET file_id = c.file_id
+           FROM (VALUES ${tuples.join(", ")}) AS c(artifact_id, file_id)
+           WHERE a.artifact_id = c.artifact_id`,
+        values,
+    });
+}
+function mapArtifactRow(row) {
+    return {
+        resourceId: row.analysis_id,
+        path: row.path,
+        artifactId: row.artifact_id ?? null,
+        fileId: row.file_id ?? null,
+        hash: row.hash,
+        size: Number(row.size),
+        role: row.role,
+        sourceStep: row.source_step ?? null,
+        sourceRun: row.source_run ?? null,
+        createdAt: row.created_at,
+        unrecoverableAt: row.unrecoverable_at ?? null,
+        fileType: row.file_type ?? null,
+    };
+}