@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,176 @@
+/**
+ * Data-profile status operations — the `data_profile_*` columns on
+ * `cortex_analysis_state`. Tracks the lifecycle of the per-analysis data
+ * profiling pass (pending → running → completed | failed).
+ */
+import type { ResultAsync } from "neverthrow";
+import { type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+/**
+ * One profiled input file's **drift signature**. `fileId` is a path identity the
+ * embedder derives (two files at the same path share it regardless of content),
+ * so `size` + `mtimeMs` are what let a consumer notice that the bytes behind a
+ * path changed. The harness treats all three as opaque labels: it persists them
+ * verbatim and never stats a source file or compares signatures itself.
+ */
+export interface DataProfileInputFile {
+    fileId: string;
+    size: number;
+    mtimeMs: number;
+}
+/** The profile snapshot `completeDataProfile` persists and `loadDataProfileStatus` reads back. */
+export interface DataProfileResult {
+    summary: string;
+    files: Array<{
+        path: string;
+        description: string;
+    }>;
+    /** Which files the profile covered — the audit record. */
+    inputFileIds: string[];
+    /**
+     * Whether the same bytes were covered — the drift comparand. Optional on read:
+     * a snapshot written before this field existed carries only `inputFileIds`, and
+     * a consumer treats the absence as drift (re-profiling repairs it), exactly as
+     * it already treats a wholly absent `result`.
+     */
+    inputFiles?: DataProfileInputFile[];
+    profiledAt: string;
+}
+export interface DataProfileStatus {
+    status: "pending" | "running" | "completed" | "failed";
+    error: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    result: DataProfileResult | null;
+    seedInputFileIds: string[] | null;
+}
+/**
+ * Try to claim a startable row into `running`. Startable means `'pending'` (seeded,
+ * not yet run) or NULL (no profile: never profiled, or cleared by `clearDataProfile`).
+ *
+ * NULL must be claimable or a cleared analysis whose inputs return can never be
+ * profiled again: the seed upsert's ON CONFLICT deliberately never rewrites profile
+ * status, so the row stays NULL — and NULL matches neither the rerun (`completed`)
+ * nor retry (`failed`) claims. A cleared row is therefore claimable only once a later
+ * seed upsert has repopulated `seed_input_file_ids` (see {@link SEEDED}).
+ *
+ * `ok(true)` when this call won the CAS; `ok(false)` when it lost or the row is
+ * unseeded — neither is an error, both stay in the ok channel.
+ */
+export declare function tryStartDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/** Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}. */
+export declare function tryRetryDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Claim a `completed` row back into `running` (the re-profile route). `data_profile_result`
+ * is deliberately preserved so a consumer can keep serving the prior profile while the new
+ * one runs. Carries {@link SEEDED}.
+ */
+export declare function tryRerunDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Stamp a claimed-`running` row `completed` and record its result — a terminal
+ * write CAS'd on `data_profile_status = 'running'`.
+ *
+ * The running guard is load-bearing, not decoration. This write runs as plain
+ * workflow-body code, and the row it targets can be moved out from under it in the
+ * window between the claim and this call: `clearDataProfile` nulls an emptied-inputs
+ * row (its own guard only defers on a *running* row, so it succeeds on a `failed` one),
+ * `expireStaleDataProfile` flips a slow run to `failed`, and DBOS recovery may replay
+ * this body after either has landed. Without the guard a late completion re-stamps
+ * `completed` + result over a since-cleared row, resurrecting exactly the seedless-
+ * completed state the seed CAS forbids (`completed` with a NULL `seed_input_file_ids`).
+ * Every legitimate caller reaches here from a row it claimed into `running`, so the
+ * guard only ever refuses a row another writer already moved on from.
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it
+ * (the row was cleared/expired/replayed away) — a no-op the caller logs, not an error.
+ */
+export declare function completeDataProfile(pool: Querier, analysisId: string, result?: DataProfileResult): ResultAsync<boolean, DbError>;
+/**
+ * Stamp a claimed-`running` row `failed` with a reason — the terminal-failure
+ * counterpart to {@link completeDataProfile}, CAS'd on `data_profile_status = 'running'`
+ * for the same reason: a workflow that fails after its row was cleared/expired
+ * out from under it (or a recovery replay of that body) must not resurrect a
+ * `failed` status over a cleared row. `data_profile_result` is left untouched so a
+ * prior profile survives the failure (the re-profile/retry route can keep serving it).
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it —
+ * a logged no-op, not an error.
+ */
+export declare function failDataProfile(pool: Querier, analysisId: string, error: string): ResultAsync<boolean, DbError>;
+export declare function expireStaleDataProfile(pool: Querier, analysisId: string, timeoutMs: number): ResultAsync<boolean, DbError>;
+/**
+ * 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`
+ * compensates itself (`triggerDataProfile`/`runDataProfile` fail the ledger in
+ * their catch). 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
+ * `already_running` forever.
+ *
+ * The `NOT EXISTS` guard keys off the DBOS workflow ledger directly (the same
+ * `dataprofile:{analysisId}:{nonce}` id space this module's trigger mints) so a
+ * genuinely in-flight or recovery-requeued run — whose `dbos.workflow_status`
+ * row is PENDING/ENQUEUED/DELAYED — is never disturbed: only a row with no
+ * active workflow is reset. Call it AFTER `DBOS.launch()` has run recovery, so
+ * a resumable run has already been re-queued and is visible to the guard.
+ */
+export declare function reconcileOrphanedDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Clear an analysis's data profile back to the honest "no profile" state,
+ * nulling every `data_profile_*` column plus the `seed_input_file_ids` the
+ * profile was taken against. `ok(true)` when a row was cleared, `ok(false)`
+ * when the clear was skipped (no such analysis, or a live profile) — a skip
+ * stays in the ok channel, exactly like the sibling CAS ops.
+ *
+ * An emptied input set makes any existing profile a lie: it describes files
+ * the analysis no longer has, so the UI must fall back to "not profiled". The
+ * `IS DISTINCT FROM 'running'` guard defers the clear while a profiling workflow
+ * is live, so this write does not race that workflow's own ledger updates;
+ * reconciliation waits for the caller's next parity check once it settles.
+ *
+ * Deferring here is NOT what stops a late workflow from resurrecting a cleared
+ * row — it cannot be, because a clear still succeeds once the row has left
+ * `running`. The dangerous interleave is: `expireStaleDataProfile` flips a slow
+ * run to `failed`, this clear then succeeds on that `failed` row, and the
+ * still-live workflow finally reaches its terminal write against a since-cleared
+ * row. That resurrection is closed at the OTHER end: `completeDataProfile` /
+ * `failDataProfile` CAS on `data_profile_status = 'running'`, so a terminal write
+ * finds no running row to stamp and no-ops instead of re-seeding the cleared one.
+ */
+export declare function clearDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * Load an analysis's data-profile ledger state. Returns `null` for BOTH miss
+ * conditions, deliberately indistinguishable to consumers:
+ *   - the analysis row does not exist, AND
+ *   - the row exists but `data_profile_status IS NULL` — set by
+ *     {@link clearDataProfile} when the input set empties (the cleared state is
+ *     the same wire shape as a never-profiled analysis on purpose, so the UI
+ *     falls back to "not profiled" uniformly).
+ *
+ * This collapsed null is a public contract: a non-null `analysisId` does NOT
+ * guarantee a non-null status. Consumers must treat `null` uniformly as "no
+ * profile" — never assume "row exists ⇒ status non-null" — and never read
+ * `seedInputFileIds` from a `null` return (it rides along only on the non-null
+ * branch). The pre-clearance state to check seed is not exposed here; read
+ * `seed_input_file_ids` directly when a caller needs that distinction
+ * (e.g. the seed-first guard in `triggerDataProfile`).
+ */
+export declare function loadDataProfileStatus(pool: Querier, analysisId: string): ResultAsync<DataProfileStatus | null, DbError>;
+/**
+ * Read an analysis's raw `seed_input_file_ids`, without the NULL-status collapse
+ * {@link loadDataProfileStatus} applies (which hides the seed of any cleared row).
+ * Returns the seeded set, or `null` for BOTH "no such analysis row" AND "the row
+ * exists but the column is NULL" — the two are deliberately indistinguishable here,
+ * exactly as they are to the consumer: both mean "nothing to profile, no claim would
+ * match". A stored `[]` returns as an empty array — a real value naming zero files,
+ * which a caller refuses distinctly from a missing seed.
+ *
+ * Advisory only: this read never gates a claim. The seed conjunct that actually makes
+ * a seedless `running` row impossible rides in each claim's CAS (see {@link SEEDED});
+ * this exists so a caller can name WHY no claim would match before it fires one (the
+ * seed-first guard in `triggerDataProfile`).
+ */
+export declare function loadSeedInputFileIds(pool: Querier, analysisId: string): ResultAsync<string[] | null, DbError>;

package/dist/state/data-profile.js

@@ -0,0 +1,284 @@
+/**
+ * Data-profile status operations — the `data_profile_*` columns on
+ * `cortex_analysis_state`. Tracks the lifecycle of the per-analysis data
+ * profiling pass (pending → running → completed | failed).
+ */
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+/**
+ * The conjunct every claim into `running` carries: the row names a non-empty set
+ * of seeded input files.
+ *
+ * It rides in the CAS rather than in a caller's pre-read because "a `running` row
+ * records the input set it is profiling" is an invariant of the LEDGER, not of any
+ * one orchestration — and `clearDataProfile` can null the seed of any non-`running`
+ * row at any moment, so a pre-read followed by a claim is a race, not an enforcement.
+ *
+ * An empty array is not a seed. `upsertAnalysis` writes NULL to mean "leave the
+ * stored seed alone" (its `COALESCE` conflict branch), so `[]` is a real value that
+ * names zero files — a set no profile may run against. `jsonb_array_length` raises on
+ * a non-array jsonb; the column is only ever written from `JSON.stringify(string[])`,
+ * and surfacing a hand-corrupted row as a `DbError` beats silently claiming it.
+ */
+const SEEDED = "seed_input_file_ids IS NOT NULL AND jsonb_array_length(seed_input_file_ids) > 0";
+/**
+ * Try to claim a startable row into `running`. Startable means `'pending'` (seeded,
+ * not yet run) or NULL (no profile: never profiled, or cleared by `clearDataProfile`).
+ *
+ * NULL must be claimable or a cleared analysis whose inputs return can never be
+ * profiled again: the seed upsert's ON CONFLICT deliberately never rewrites profile
+ * status, so the row stays NULL — and NULL matches neither the rerun (`completed`)
+ * nor retry (`failed`) claims. A cleared row is therefore claimable only once a later
+ * seed upsert has repopulated `seed_input_file_ids` (see {@link SEEDED}).
+ *
+ * `ok(true)` when this call won the CAS; `ok(false)` when it lost or the row is
+ * unseeded — neither is an error, both stay in the ok channel.
+ */
+export function tryStartDataProfile(pool, analysisId) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.tryStartDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'running', data_profile_started_at = $1
+            WHERE analysis_id = $2 AND (data_profile_status = 'pending' OR data_profile_status IS NULL) AND ${SEEDED}`,
+            values: [now, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/** Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}. */
+export function tryRetryDataProfile(pool, analysisId) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.tryRetryDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'running', data_profile_started_at = $1,
+                data_profile_error = NULL, data_profile_completed_at = NULL
+            WHERE analysis_id = $2 AND data_profile_status = 'failed' AND ${SEEDED}`,
+            values: [now, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/**
+ * Claim a `completed` row back into `running` (the re-profile route). `data_profile_result`
+ * is deliberately preserved so a consumer can keep serving the prior profile while the new
+ * one runs. Carries {@link SEEDED}.
+ */
+export function tryRerunDataProfile(pool, analysisId) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.tryRerunDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'running', data_profile_started_at = $1,
+                data_profile_error = NULL, data_profile_completed_at = NULL
+            WHERE analysis_id = $2 AND data_profile_status = 'completed' AND ${SEEDED}`,
+            values: [now, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/**
+ * Stamp a claimed-`running` row `completed` and record its result — a terminal
+ * write CAS'd on `data_profile_status = 'running'`.
+ *
+ * The running guard is load-bearing, not decoration. This write runs as plain
+ * workflow-body code, and the row it targets can be moved out from under it in the
+ * window between the claim and this call: `clearDataProfile` nulls an emptied-inputs
+ * row (its own guard only defers on a *running* row, so it succeeds on a `failed` one),
+ * `expireStaleDataProfile` flips a slow run to `failed`, and DBOS recovery may replay
+ * this body after either has landed. Without the guard a late completion re-stamps
+ * `completed` + result over a since-cleared row, resurrecting exactly the seedless-
+ * completed state the seed CAS forbids (`completed` with a NULL `seed_input_file_ids`).
+ * Every legitimate caller reaches here from a row it claimed into `running`, so the
+ * guard only ever refuses a row another writer already moved on from.
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it
+ * (the row was cleared/expired/replayed away) — a no-op the caller logs, not an error.
+ */
+export function completeDataProfile(pool, analysisId, result) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.completeDataProfile", async () => {
+        const res = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'completed', data_profile_completed_at = $1,
+                data_profile_result = $2::jsonb
+            WHERE analysis_id = $3 AND data_profile_status = 'running'`,
+            values: [now, result ? JSON.stringify(result) : null, analysisId],
+        });
+        return (res.rowCount ?? 0) > 0;
+    });
+}
+/**
+ * Stamp a claimed-`running` row `failed` with a reason — the terminal-failure
+ * counterpart to {@link completeDataProfile}, CAS'd on `data_profile_status = 'running'`
+ * for the same reason: a workflow that fails after its row was cleared/expired
+ * out from under it (or a recovery replay of that body) must not resurrect a
+ * `failed` status over a cleared row. `data_profile_result` is left untouched so a
+ * prior profile survives the failure (the re-profile/retry route can keep serving it).
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the guard refused it —
+ * a logged no-op, not an error.
+ */
+export function failDataProfile(pool, analysisId, error) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.failDataProfile", async () => {
+        const res = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'failed', data_profile_error = $1,
+                data_profile_completed_at = $2
+            WHERE analysis_id = $3 AND data_profile_status = 'running'`,
+            values: [error, now, analysisId],
+        });
+        return (res.rowCount ?? 0) > 0;
+    });
+}
+export function expireStaleDataProfile(pool, analysisId, timeoutMs) {
+    const now = new Date();
+    const cutoff = new Date(now.getTime() - timeoutMs).toISOString();
+    return tryMutation("dataProfile.expireStaleDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'failed',
+                data_profile_error = 'Data profiling timed out',
+                data_profile_completed_at = $1
+            WHERE analysis_id = $2 AND data_profile_status = 'running'
+              AND data_profile_started_at < $3`,
+            values: [now.toISOString(), analysisId, cutoff],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/**
+ * 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`
+ * compensates itself (`triggerDataProfile`/`runDataProfile` fail the ledger in
+ * their catch). 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
+ * `already_running` forever.
+ *
+ * The `NOT EXISTS` guard keys off the DBOS workflow ledger directly (the same
+ * `dataprofile:{analysisId}:{nonce}` id space this module's trigger mints) so a
+ * genuinely in-flight or recovery-requeued run — whose `dbos.workflow_status`
+ * row is PENDING/ENQUEUED/DELAYED — is never disturbed: only a row with no
+ * active workflow is reset. Call it AFTER `DBOS.launch()` has run recovery, so
+ * a resumable run has already been re-queued and is visible to the guard.
+ */
+export function reconcileOrphanedDataProfile(pool, analysisId) {
+    const now = new Date().toISOString();
+    return tryMutation("dataProfile.reconcileOrphanedDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = 'failed',
+                data_profile_error = 'Profiling never started (no backing workflow); reset for retry',
+                data_profile_completed_at = $1
+            WHERE analysis_id = $2 AND data_profile_status = 'running'
+              AND NOT EXISTS (
+                  SELECT 1 FROM dbos.workflow_status
+                  WHERE workflow_uuid LIKE 'dataprofile:' || $2 || ':%'
+                    AND status IN ('PENDING', 'ENQUEUED', 'DELAYED'))`,
+            values: [now, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/**
+ * Clear an analysis's data profile back to the honest "no profile" state,
+ * nulling every `data_profile_*` column plus the `seed_input_file_ids` the
+ * profile was taken against. `ok(true)` when a row was cleared, `ok(false)`
+ * when the clear was skipped (no such analysis, or a live profile) — a skip
+ * stays in the ok channel, exactly like the sibling CAS ops.
+ *
+ * An emptied input set makes any existing profile a lie: it describes files
+ * the analysis no longer has, so the UI must fall back to "not profiled". The
+ * `IS DISTINCT FROM 'running'` guard defers the clear while a profiling workflow
+ * is live, so this write does not race that workflow's own ledger updates;
+ * reconciliation waits for the caller's next parity check once it settles.
+ *
+ * Deferring here is NOT what stops a late workflow from resurrecting a cleared
+ * row — it cannot be, because a clear still succeeds once the row has left
+ * `running`. The dangerous interleave is: `expireStaleDataProfile` flips a slow
+ * run to `failed`, this clear then succeeds on that `failed` row, and the
+ * still-live workflow finally reaches its terminal write against a since-cleared
+ * row. That resurrection is closed at the OTHER end: `completeDataProfile` /
+ * `failDataProfile` CAS on `data_profile_status = 'running'`, so a terminal write
+ * finds no running row to stamp and no-ops instead of re-seeding the cleared one.
+ */
+export function clearDataProfile(pool, analysisId) {
+    return tryMutation("dataProfile.clearDataProfile", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_status = NULL, data_profile_error = NULL,
+                data_profile_started_at = NULL, data_profile_completed_at = NULL,
+                data_profile_result = NULL, seed_input_file_ids = NULL
+            WHERE analysis_id = $1 AND data_profile_status IS DISTINCT FROM 'running'`,
+            values: [analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
+/**
+ * Load an analysis's data-profile ledger state. Returns `null` for BOTH miss
+ * conditions, deliberately indistinguishable to consumers:
+ *   - the analysis row does not exist, AND
+ *   - the row exists but `data_profile_status IS NULL` — set by
+ *     {@link clearDataProfile} when the input set empties (the cleared state is
+ *     the same wire shape as a never-profiled analysis on purpose, so the UI
+ *     falls back to "not profiled" uniformly).
+ *
+ * This collapsed null is a public contract: a non-null `analysisId` does NOT
+ * guarantee a non-null status. Consumers must treat `null` uniformly as "no
+ * profile" — never assume "row exists ⇒ status non-null" — and never read
+ * `seedInputFileIds` from a `null` return (it rides along only on the non-null
+ * branch). The pre-clearance state to check seed is not exposed here; read
+ * `seed_input_file_ids` directly when a caller needs that distinction
+ * (e.g. the seed-first guard in `triggerDataProfile`).
+ */
+export function loadDataProfileStatus(pool, analysisId) {
+    return tryQuery("dataProfile.loadDataProfileStatus", async () => {
+        const result = await pool.query({
+            text: `SELECT data_profile_status, data_profile_error,
+                   data_profile_started_at, data_profile_completed_at,
+                   data_profile_result, seed_input_file_ids
+            FROM cortex_analysis_state WHERE analysis_id = $1`,
+            values: [analysisId],
+        });
+        const row = result.rows[0];
+        if (!row || row.data_profile_status === null)
+            return null;
+        return {
+            status: row.data_profile_status,
+            error: row.data_profile_error ?? null,
+            startedAt: row.data_profile_started_at ?? null,
+            completedAt: row.data_profile_completed_at ?? null,
+            result: row.data_profile_result ?? null,
+            seedInputFileIds: row.seed_input_file_ids ?? null,
+        };
+    });
+}
+/**
+ * Read an analysis's raw `seed_input_file_ids`, without the NULL-status collapse
+ * {@link loadDataProfileStatus} applies (which hides the seed of any cleared row).
+ * Returns the seeded set, or `null` for BOTH "no such analysis row" AND "the row
+ * exists but the column is NULL" — the two are deliberately indistinguishable here,
+ * exactly as they are to the consumer: both mean "nothing to profile, no claim would
+ * match". A stored `[]` returns as an empty array — a real value naming zero files,
+ * which a caller refuses distinctly from a missing seed.
+ *
+ * Advisory only: this read never gates a claim. The seed conjunct that actually makes
+ * a seedless `running` row impossible rides in each claim's CAS (see {@link SEEDED});
+ * this exists so a caller can name WHY no claim would match before it fires one (the
+ * seed-first guard in `triggerDataProfile`).
+ */
+export function loadSeedInputFileIds(pool, analysisId) {
+    return tryQuery("dataProfile.loadSeedInputFileIds", async () => {
+        const result = await pool.query({
+            text: "SELECT seed_input_file_ids AS seed FROM cortex_analysis_state WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        return result.rows[0]?.seed ?? null;
+    });
+}

package/dist/state/db.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared Postgres-querier type for `state/` modules.
+ *
+ * Every per-entity module accepts a `Querier` as its first parameter so the
+ * same operation works against the harness's connection pool or a
+ * single-transaction `PoolClient`. Lifted here to keep the type declared in
+ * one place instead of redeclared per file.
+ */
+import type { Pool, PoolClient } from "pg";
+export type Querier = Pool | PoolClient;

package/dist/state/db.js

@@ -0,0 +1,9 @@
+/**
+ * Shared Postgres-querier type for `state/` modules.
+ *
+ * Every per-entity module accepts a `Querier` as its first parameter so the
+ * same operation works against the harness's connection pool or a
+ * single-transaction `PoolClient`. Lifted here to keep the type declared in
+ * one place instead of redeclared per file.
+ */
+export {};

package/dist/state/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cortex execution state module.
+ *
+ * Cortex-owned Postgres tables for analysis state, artifact registry,
+ * and execution ledgers. Per-entity sub-modules live alongside this barrel;
+ * importers may either pull from `./state` (everything) or from the
+ * specific entity module (e.g. `./state/runs.js`) when narrow.
+ */
+export { initCortexState } from "./init.js";
+export type { Querier } from "./db.js";
+export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
+export type { RegisterArtifactInput, InputArtifactMeta } from "./artifacts.js";
+export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export type { InsertRunInput } from "./runs.js";
+export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
+export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
+export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
+export type { ActiveSandboxRow } from "./active-sandboxes.js";
+export { insertPlan, loadPlan } from "./plans.js";
+export type { InsertPlanInput } from "./plans.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
+export type { DataProfileStatus, DataProfileResult, DataProfileInputFile } from "./data-profile.js";
+export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
+export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";
+export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";
+export type { TargetAssessmentStatus, TargetAssessmentRow, TargetAssessmentError, InsertAssessmentInput, ListAssessmentsOptions, } from "./target-assessments.js";

package/dist/state/index.js

@@ -0,0 +1,20 @@
+/**
+ * Cortex execution state module.
+ *
+ * Cortex-owned Postgres tables for analysis state, artifact registry,
+ * and execution ledgers. Per-entity sub-modules live alongside this barrel;
+ * importers may either pull from `./state` (everything) or from the
+ * specific entity module (e.g. `./state/runs.js`) when narrow.
+ */
+export { initCortexState } from "./init.js";
+export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
+export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
+export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
+export { insertPlan, loadPlan } from "./plans.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
+export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
+export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cortex state table initialization.
+ *
+ * Creates `cortex_*` tables on startup using `CREATE TABLE IF NOT EXISTS` +
+ * additive `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`. The whole flow is
+ * serialized across concurrent replicas with a Postgres advisory lock so
+ * simultaneous startups don't race on DDL.
+ */
+import type { Pool } from "pg";
+/**
+ * Initialize Cortex state tables. Safe to call on every startup and across
+ * concurrent replicas (advisory lock serializes the init flow).
+ */
+export declare function initCortexState(pool: Pool): Promise<void>;