@inflexa-ai/harness 0.1.1

package/dist/state/step-executions.js

@@ -0,0 +1,175 @@
+/**
+ * `cortex_step_executions` operations — step lifecycle and retry telemetry.
+ * The `sandbox_ref` column is read/written by the sibling `active-sandboxes`
+ * module.
+ */
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+/**
+ * Seed one `pending` row per plan step at run start (`started_at` NULL — no
+ * attempt has happened yet; `attempts`/`hit_max_steps` lean on their column
+ * defaults). `ON CONFLICT DO NOTHING`, NOT the mark-running upsert: on DBOS
+ * recovery the parent body replays this seed against rows a prior execution
+ * already advanced, and an upsert would reset them — DO NOTHING makes the seed
+ * idempotent and monotone (it can only ever add missing rows). From the first
+ * seed, `queryStepsByRun` returns the run's full DAG, so consumers can render
+ * honest done/total progress including not-yet-started steps.
+ */
+export function seedStepExecutions(pool, rows) {
+    return tryMutation("stepExecutions.seedStepExecutions", async () => {
+        if (rows.length === 0)
+            return;
+        const values = [];
+        const tuples = rows.map((row) => {
+            values.push(row.runId, row.stepId, row.analysisId, row.wave, row.agentId);
+            const base = values.length - 5;
+            return `($${base + 1}, $${base + 2}, $${base + 3}, $${base + 4}, $${base + 5}, 'pending')`;
+        });
+        await pool.query({
+            text: `INSERT INTO cortex_step_executions
+          (run_id, step_id, analysis_id, wave, agent_id, status)
+          VALUES ${tuples.join(", ")}
+          ON CONFLICT (run_id, step_id) DO NOTHING`,
+            values,
+        });
+    });
+}
+export function insertStepExecution(pool, input) {
+    const now = new Date().toISOString();
+    return tryMutation("stepExecutions.insertStepExecution", async () => {
+        await pool.query({
+            text: `INSERT INTO cortex_step_executions
+          (run_id, step_id, analysis_id, wave, agent_id, status, started_at,
+           attempts, last_error_class, finish_reason, hit_max_steps,
+           child_workflow_id)
+          VALUES ($1, $2, $3, $4, $5, 'running', $6, 1, NULL, NULL, 0, $7)
+          ON CONFLICT (run_id, step_id) DO UPDATE SET
+            wave = EXCLUDED.wave,
+            agent_id = EXCLUDED.agent_id,
+            status = EXCLUDED.status,
+            started_at = EXCLUDED.started_at,
+            completed_at = NULL,
+            duration_ms = NULL,
+            error = NULL,
+            attempts = 1,
+            last_error_class = NULL,
+            finish_reason = NULL,
+            hit_max_steps = 0,
+            child_workflow_id = EXCLUDED.child_workflow_id`,
+            values: [input.runId, input.stepId, input.analysisId, input.wave, input.agentId, now, input.childWorkflowId ?? null],
+        });
+    });
+}
+/**
+ * Update a step execution row. Columns are written conditionally so callers
+ * can bump `attempts` / `lastErrorClass` on retry without clobbering timing
+ * telemetry, or set `finishReason` / `hitMaxSteps` on success.
+ *
+ * `completed_at` is only stamped for terminal statuses (completed/failed/
+ * skipped) — running updates leave it NULL for the next transition.
+ */
+export function updateStepExecution(pool, runId, stepId, update) {
+    // Build the SET clause dynamically so retries can bump telemetry columns
+    // without clobbering timing, and success paths can set finish_reason /
+    // hit_max_steps without touching error. Placeholders are numbered
+    // position-wise via the `values` array length.
+    const sets = [];
+    const values = [];
+    const push = (col, val) => {
+        values.push(val);
+        sets.push(`${col} = $${values.length}`);
+    };
+    push("status", update.status);
+    const isTerminal = update.status !== "running";
+    if (isTerminal) {
+        push("completed_at", new Date().toISOString());
+        push("duration_ms", update.durationMs ?? null);
+        push("error", update.error ?? null);
+    }
+    if (update.attempts != null) {
+        push("attempts", update.attempts);
+    }
+    // Accept explicit null to clear (e.g., on success).
+    if (update.lastErrorClass !== undefined) {
+        push("last_error_class", update.lastErrorClass ?? null);
+    }
+    if (update.finishReason !== undefined) {
+        push("finish_reason", update.finishReason ?? null);
+    }
+    if (update.hitMaxSteps !== undefined) {
+        // `hit_max_steps` is INTEGER NOT NULL. node-postgres binds JS booleans as
+        // PG `boolean` type and PG refuses the implicit boolean → integer cast,
+        // so coerce to 0/1 at the bind site.
+        push("hit_max_steps", update.hitMaxSteps === true ? 1 : 0);
+    }
+    if (update.blockedReason !== undefined) {
+        push("blocked_reason", update.blockedReason ?? null);
+    }
+    values.push(runId);
+    const runIdPos = values.length;
+    values.push(stepId);
+    const stepIdPos = values.length;
+    return tryMutation("stepExecutions.updateStepExecution", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET ${sets.join(", ")}
+          WHERE run_id = $${runIdPos} AND step_id = $${stepIdPos}`,
+            values,
+        });
+    });
+}
+/**
+ * Sweep a run's still-`pending` rows to `skipped` ("never ran, never will") at
+ * finalisation, stamping `completed_at`. Only genuinely-terminal paths may call
+ * this — the resumable budget-pause branch must NOT, because the resumed
+ * workflow still executes those steps (see the workflow-failure-lifecycle
+ * spec). `skipped`, not `canceled`: canceled means torn down mid-flight, and
+ * these steps never started.
+ */
+export function sweepPendingStepExecutions(pool, runId) {
+    const now = new Date().toISOString();
+    return tryMutation("stepExecutions.sweepPendingStepExecutions", async () => {
+        await pool.query({
+            text: `UPDATE cortex_step_executions
+          SET status = 'skipped', completed_at = $2
+          WHERE run_id = $1 AND status = 'pending'`,
+            values: [runId, now],
+        });
+    });
+}
+export function queryStepsByRun(pool, runId) {
+    return tryQuery("stepExecutions.queryStepsByRun", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id, step_id, analysis_id, wave, agent_id,
+                 status, started_at, completed_at, duration_ms, error,
+                 attempts, last_error_class, finish_reason, hit_max_steps,
+                 blocked_reason, sandbox_ref, exec_id, child_workflow_id
+          FROM cortex_step_executions
+          WHERE run_id = $1
+          ORDER BY wave, started_at NULLS LAST, step_id`,
+            values: [runId],
+        });
+        return result.rows.map(mapStepExecutionRow);
+    });
+}
+function mapStepExecutionRow(row) {
+    return {
+        runId: row.run_id,
+        stepId: row.step_id,
+        analysisId: row.analysis_id,
+        wave: Number(row.wave),
+        agentId: row.agent_id,
+        status: row.status,
+        startedAt: row.started_at ?? null,
+        completedAt: row.completed_at ?? null,
+        durationMs: row.duration_ms === null || row.duration_ms === undefined ? null : Number(row.duration_ms),
+        error: row.error ?? null,
+        attempts: row.attempts ?? 1,
+        lastErrorClass: row.last_error_class ?? null,
+        finishReason: row.finish_reason ?? null,
+        hitMaxSteps: row.hit_max_steps === 1 || row.hit_max_steps === true,
+        blockedReason: row.blocked_reason ?? null,
+        sandboxRef: row.sandbox_ref ?? null,
+        execId: row.exec_id ?? null,
+        childWorkflowId: row.child_workflow_id ?? null,
+    };
+}

package/dist/state/target-assessments.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Harness-side typed query helpers for `cortex_target_assessments`.
+ *
+ * Owns the helpers the DBOS workflow body and harness HTTP routes call:
+ *  - `insertAssessment` accepts an optional `workflowId` and persists it on
+ *    insert (defaults to the assessment id; for DBOS-shaped rows the
+ *    assessmentId IS the DBOS workflowID).
+ *  - `markAssessmentSuspended` flips the row to the new
+ *    `suspended_insufficient_funds` status, idempotent on replay.
+ *  - `markAssessmentRunning` is used by the resume entry point after
+ *    `DBOS.resumeWorkflow` completes.
+ *  - All row mappers surface `workflowId` alongside `workflowRunId`.
+ *
+ * Soft-deleted rows (`status = 'deleted'`) are never resurrected — every
+ * mutating helper carries an `AND status != 'deleted'` guard, so a user
+ * deleting a row mid-run causes terminal workflow writes to no-op.
+ */
+import type { ResultAsync } from "neverthrow";
+import { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema, type TargetAssessmentStatus, type TargetAssessmentError, type TargetAssessmentListRow, type TargetAssessmentRow } from "@inflexa-ai/harness/contracts/target-assessment-row.js";
+import { type DbError } from "../lib/db-result.js";
+import type { Querier } from "./db.js";
+export { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema };
+export type { TargetAssessmentStatus, TargetAssessmentError, TargetAssessmentListRow, TargetAssessmentRow };
+export interface InsertAssessmentInput {
+    id?: string;
+    /**
+     * DBOS workflow id for the executeTargetAssessment workflow. Defaults to
+     * the assessment id when omitted — the trigger route always passes the
+     * id explicitly so a future split between the two ids stays trivial.
+     */
+    workflowId?: string;
+    organizationId: string;
+    targetId: string;
+    targetLabel: string;
+    goal?: string | null;
+    billingContextId: string;
+    requestedBy: string;
+}
+export declare function insertAssessment(pool: Querier, input: InsertAssessmentInput): ResultAsync<string, DbError>;
+export declare function updateProgress(pool: Querier, id: string, progress: string, status?: TargetAssessmentStatus): ResultAsync<void, DbError>;
+export declare function setDossier(pool: Querier, id: string, dossier: Record<string, unknown>): ResultAsync<void, DbError>;
+export declare function markFailed(pool: Querier, id: string, error: TargetAssessmentError): ResultAsync<void, DbError>;
+/**
+ * Flip the row to the new `suspended_insufficient_funds` status used when
+ * an LLM step self-cancels the workflow on a 402 (budget exhausted).
+ * Idempotent on DBOS replay — a second call from the terminal handler on
+ * the recovery path is a no-op against an already-suspended row. Soft-
+ * deleted rows are NOT resurrected.
+ */
+export declare function markAssessmentSuspended(pool: Querier, id: string): ResultAsync<void, DbError>;
+/**
+ * Flip a suspended row back to `running` on `DBOS.resumeWorkflow`. Called
+ * from the resume entry point AFTER the resume call returns success.
+ * No-op on a soft-deleted row.
+ */
+export declare function markAssessmentRunning(pool: Querier, id: string): ResultAsync<void, DbError>;
+export declare function getAssessment(pool: Querier, id: string, organizationId: string): ResultAsync<TargetAssessmentRow | null, DbError>;
+export interface ListAssessmentsOptions {
+    limit?: number;
+    offset?: number;
+    includeDeleted?: boolean;
+}
+export declare function listAssessmentsByOrg(pool: Querier, organizationId: string, options?: ListAssessmentsOptions): ResultAsync<TargetAssessmentListRow[], DbError>;
+/**
+ * Soft-delete a row. A missing/already-deleted row returns `ok(0)` — absence
+ * rides the ok channel; `rowCount === 0` is not a failure.
+ */
+export declare function softDeleteAssessment(pool: Querier, id: string, organizationId: string): ResultAsync<number, DbError>;

package/dist/state/target-assessments.js

@@ -0,0 +1,222 @@
+/**
+ * Harness-side typed query helpers for `cortex_target_assessments`.
+ *
+ * Owns the helpers the DBOS workflow body and harness HTTP routes call:
+ *  - `insertAssessment` accepts an optional `workflowId` and persists it on
+ *    insert (defaults to the assessment id; for DBOS-shaped rows the
+ *    assessmentId IS the DBOS workflowID).
+ *  - `markAssessmentSuspended` flips the row to the new
+ *    `suspended_insufficient_funds` status, idempotent on replay.
+ *  - `markAssessmentRunning` is used by the resume entry point after
+ *    `DBOS.resumeWorkflow` completes.
+ *  - All row mappers surface `workflowId` alongside `workflowRunId`.
+ *
+ * Soft-deleted rows (`status = 'deleted'`) are never resurrected — every
+ * mutating helper carries an `AND status != 'deleted'` guard, so a user
+ * deleting a row mid-run causes terminal workflow writes to no-op.
+ */
+import { randomUUID } from "node:crypto";
+import { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema, } from "@inflexa-ai/harness/contracts/target-assessment-row.js";
+import { tryQuery, tryMutation } from "../lib/db-result.js";
+export { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema };
+function toIso(value) {
+    if (value === null)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    return value;
+}
+function parseJsonb(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === "string") {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    return raw;
+}
+function mapListRow(row) {
+    const created = toIso(row.created_at);
+    const updated = toIso(row.updated_at);
+    if (!created || !updated) {
+        throw new Error(`cortex_target_assessments(${row.id}): missing created_at or updated_at`);
+    }
+    return {
+        id: row.id,
+        organizationId: row.organization_id,
+        targetId: row.target_id,
+        targetLabel: row.target_label,
+        goal: row.goal,
+        status: row.status,
+        progress: row.progress,
+        billingContextId: row.billing_context_id,
+        error: parseJsonb(row.error),
+        requestedBy: row.requested_by,
+        workflowRunId: row.workflow_run_id,
+        workflowId: row.workflow_id,
+        createdAt: created,
+        updatedAt: updated,
+        completedAt: toIso(row.completed_at),
+    };
+}
+function mapRow(row) {
+    return {
+        ...mapListRow(row),
+        dossier: parseJsonb(row.dossier),
+    };
+}
+const SELECT_LIST_COLUMNS = `id, organization_id, target_id, target_label, goal,
+  status, progress, billing_context_id, error, requested_by,
+  workflow_run_id, workflow_id, created_at, updated_at, completed_at`;
+const SELECT_COLUMNS = `${SELECT_LIST_COLUMNS}, dossier`;
+export function insertAssessment(pool, input) {
+    const id = input.id ?? randomUUID();
+    const workflowId = input.workflowId ?? id;
+    return tryMutation("targetAssessments.insertAssessment", async () => {
+        await pool.query({
+            text: `INSERT INTO cortex_target_assessments
+        (id, organization_id, target_id, target_label, goal, status,
+         billing_context_id, requested_by, workflow_id)
+        VALUES ($1, $2, $3, $4, $5, 'queued', $6, $7, $8)`,
+            values: [id, input.organizationId, input.targetId, input.targetLabel, input.goal ?? null, input.billingContextId, input.requestedBy, workflowId],
+        });
+        return id;
+    });
+}
+export function updateProgress(pool, id, progress, status) {
+    return tryMutation("targetAssessments.updateProgress", async () => {
+        if (status) {
+            await pool.query({
+                text: `UPDATE cortex_target_assessments
+          SET progress = $1, status = $2, updated_at = NOW()
+          WHERE id = $3 AND status != 'deleted'`,
+                values: [progress, status, id],
+            });
+        }
+        else {
+            await pool.query({
+                text: `UPDATE cortex_target_assessments
+          SET progress = $1, updated_at = NOW()
+          WHERE id = $2 AND status != 'deleted'`,
+                values: [progress, id],
+            });
+        }
+    });
+}
+export function setDossier(pool, id, dossier) {
+    return tryMutation("targetAssessments.setDossier", async () => {
+        await pool.query({
+            text: `UPDATE cortex_target_assessments
+        SET dossier = $1::jsonb,
+            status = 'completed',
+            progress = 'Completed',
+            error = NULL,
+            completed_at = NOW(),
+            updated_at = NOW()
+        WHERE id = $2 AND status != 'deleted'`,
+            values: [JSON.stringify(dossier), id],
+        });
+    });
+}
+export function markFailed(pool, id, error) {
+    return tryMutation("targetAssessments.markFailed", async () => {
+        await pool.query({
+            text: `UPDATE cortex_target_assessments
+        SET status = 'failed',
+            error = $1::jsonb,
+            completed_at = NOW(),
+            updated_at = NOW()
+        WHERE id = $2 AND status != 'deleted'`,
+            values: [JSON.stringify(error), id],
+        });
+    });
+}
+/**
+ * Flip the row to the new `suspended_insufficient_funds` status used when
+ * an LLM step self-cancels the workflow on a 402 (budget exhausted).
+ * Idempotent on DBOS replay — a second call from the terminal handler on
+ * the recovery path is a no-op against an already-suspended row. Soft-
+ * deleted rows are NOT resurrected.
+ */
+export function markAssessmentSuspended(pool, id) {
+    return tryMutation("targetAssessments.markAssessmentSuspended", async () => {
+        await pool.query({
+            text: `UPDATE cortex_target_assessments
+        SET status = 'suspended_insufficient_funds',
+            progress = 'Suspended — insufficient funds',
+            updated_at = NOW()
+        WHERE id = $1 AND status != 'deleted'`,
+            values: [id],
+        });
+    });
+}
+/**
+ * Flip a suspended row back to `running` on `DBOS.resumeWorkflow`. Called
+ * from the resume entry point AFTER the resume call returns success.
+ * No-op on a soft-deleted row.
+ */
+export function markAssessmentRunning(pool, id) {
+    return tryMutation("targetAssessments.markAssessmentRunning", async () => {
+        await pool.query({
+            text: `UPDATE cortex_target_assessments
+        SET status = 'running',
+            progress = 'Resuming',
+            error = NULL,
+            updated_at = NOW()
+        WHERE id = $1 AND status != 'deleted'`,
+            values: [id],
+        });
+    });
+}
+export function getAssessment(pool, id, organizationId) {
+    // The raw read is wrapped; `mapRow`/`mapListRow` runs via `.map()` outside
+    // the catch so its corrupt-row throw (missing created_at) propagates as a
+    // control-flow throw rather than being captured as a `DbError`.
+    return tryQuery("targetAssessments.getAssessment", async () => {
+        const result = await pool.query({
+            text: `SELECT ${SELECT_COLUMNS}
+        FROM cortex_target_assessments
+        WHERE id = $1 AND organization_id = $2`,
+            values: [id, organizationId],
+        });
+        return result.rows[0] ?? null;
+    }).map((row) => (row ? mapRow(row) : null));
+}
+export function listAssessmentsByOrg(pool, organizationId, options = {}) {
+    const limit = options.limit ?? 50;
+    const offset = options.offset ?? 0;
+    const includeDeleted = options.includeDeleted ?? false;
+    const filterDeleted = includeDeleted ? "" : `AND status != 'deleted'`;
+    // `mapListRow` runs via `.map()` outside the catch so its corrupt-row throw
+    // propagates as a control-flow throw, not a captured `DbError`.
+    return tryQuery("targetAssessments.listAssessmentsByOrg", async () => {
+        const result = await pool.query({
+            text: `SELECT ${SELECT_LIST_COLUMNS}
+        FROM cortex_target_assessments
+        WHERE organization_id = $1 ${filterDeleted}
+        ORDER BY created_at DESC
+        LIMIT $2 OFFSET $3`,
+            values: [organizationId, limit, offset],
+        });
+        return result.rows;
+    }).map((rows) => rows.map(mapListRow));
+}
+/**
+ * Soft-delete a row. A missing/already-deleted row returns `ok(0)` — absence
+ * rides the ok channel; `rowCount === 0` is not a failure.
+ */
+export function softDeleteAssessment(pool, id, organizationId) {
+    return tryMutation("targetAssessments.softDeleteAssessment", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_target_assessments
+        SET status = 'deleted', updated_at = NOW()
+        WHERE id = $1 AND organization_id = $2`,
+            values: [id, organizationId],
+        });
+        return result.rowCount ?? 0;
+    });
+}

package/dist/state/vector-store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal pgvector store — just the surface the harness write-side needs.
+ *
+ * Schema:
+ *   - `id SERIAL PRIMARY KEY`
+ *   - `vector_id TEXT UNIQUE NOT NULL`
+ *   - `embedding vector(${dimension})`
+ *   - `metadata JSONB DEFAULT '{}'::jsonb`
+ * Existing per-analysis `search_{...}` tables continue to work; the read-side
+ * (`tools/workspace/workspace-search.ts`) already speaks `vector_id`.
+ *
+ * Identifier guard: `indexName` is interpolated into SQL — only allow the
+ * `search_{snake}` shape we ever produce.
+ */
+import { ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type DbError } from "../lib/db-result.js";
+export interface CreateIndexInput {
+    readonly indexName: string;
+    readonly dimension: number;
+    readonly metric?: "cosine" | "l2" | "ip";
+}
+export interface BuildIndexInput {
+    readonly indexName: string;
+    readonly metric?: "cosine" | "l2" | "ip";
+    readonly indexConfig: {
+        readonly type: "hnsw";
+    };
+}
+export interface UpsertInput {
+    readonly indexName: string;
+    readonly vectors: readonly number[][];
+    readonly metadata?: readonly Record<string, unknown>[];
+    readonly ids?: readonly string[];
+}
+export interface QueryInput {
+    readonly indexName: string;
+    readonly queryVector: readonly number[];
+    readonly topK: number;
+    readonly filter?: Record<string, unknown>;
+}
+export interface QueryResult {
+    readonly id: string;
+    readonly score: number;
+    readonly metadata: Record<string, unknown>;
+}
+export interface VectorStore {
+    createIndex(input: CreateIndexInput): ResultAsync<void, DbError>;
+    buildIndex(input: BuildIndexInput): ResultAsync<void, DbError>;
+    upsert(input: UpsertInput): ResultAsync<void, DbError>;
+    query(input: QueryInput): ResultAsync<QueryResult[], DbError>;
+}
+export declare function createVectorStore(pool: Pool): VectorStore;

package/dist/state/vector-store.js

@@ -0,0 +1,89 @@
+/**
+ * Minimal pgvector store — just the surface the harness write-side needs.
+ *
+ * Schema:
+ *   - `id SERIAL PRIMARY KEY`
+ *   - `vector_id TEXT UNIQUE NOT NULL`
+ *   - `embedding vector(${dimension})`
+ *   - `metadata JSONB DEFAULT '{}'::jsonb`
+ * Existing per-analysis `search_{...}` tables continue to work; the read-side
+ * (`tools/workspace/workspace-search.ts`) already speaks `vector_id`.
+ *
+ * Identifier guard: `indexName` is interpolated into SQL — only allow the
+ * `search_{snake}` shape we ever produce.
+ */
+import { okAsync } from "neverthrow";
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+const IDENT = /^[a-z_][a-z0-9_]*$/;
+function assertIdent(name) {
+    if (!IDENT.test(name)) {
+        throw new Error(`vector-store: unsafe index name "${name}"`);
+    }
+}
+function toVectorLiteral(v) {
+    return `[${v.join(",")}]`;
+}
+export function createVectorStore(pool) {
+    return {
+        createIndex({ indexName, dimension }) {
+            assertIdent(indexName);
+            return tryMutation("vectorStore.createIndex", async () => {
+                await pool.query(`CREATE TABLE IF NOT EXISTS "${indexName}" (
+             id SERIAL PRIMARY KEY,
+             vector_id TEXT UNIQUE NOT NULL,
+             embedding vector(${dimension}),
+             metadata JSONB DEFAULT '{}'::jsonb
+           )`);
+            });
+        },
+        buildIndex({ indexName, indexConfig }) {
+            assertIdent(indexName);
+            if (indexConfig.type !== "hnsw") {
+                throw new Error(`vector-store: unsupported index type "${indexConfig.type}"`);
+            }
+            // m/ef_construction default to 8/32.
+            return tryMutation("vectorStore.buildIndex", async () => {
+                await pool.query(`CREATE INDEX IF NOT EXISTS "${indexName}_vector_idx"
+           ON "${indexName}"
+           USING hnsw (embedding vector_cosine_ops)
+           WITH (m = 8, ef_construction = 32)`);
+            });
+        },
+        upsert({ indexName, vectors, metadata, ids }) {
+            assertIdent(indexName);
+            if (vectors.length === 0)
+                return okAsync(undefined);
+            const finalIds = ids ?? vectors.map(() => crypto.randomUUID());
+            return tryMutation("vectorStore.upsert", async () => {
+                for (let i = 0; i < vectors.length; i++) {
+                    const vec = toVectorLiteral(vectors[i]);
+                    const meta = JSON.stringify(metadata?.[i] ?? {});
+                    await pool.query(`INSERT INTO "${indexName}" (vector_id, embedding, metadata)
+             VALUES ($1, $2::vector, $3::jsonb)
+             ON CONFLICT (vector_id)
+             DO UPDATE SET embedding = $2::vector, metadata = $3::jsonb`, [finalIds[i], vec, meta]);
+                }
+            });
+        },
+        query({ indexName, queryVector, topK, filter }) {
+            assertIdent(indexName);
+            const literal = toVectorLiteral(queryVector);
+            const values = [literal, topK];
+            let where = "";
+            if (filter && Object.keys(filter).length > 0) {
+                values.push(JSON.stringify(filter));
+                where = `WHERE metadata @> $3::jsonb`;
+            }
+            return tryQuery("vectorStore.query", async () => {
+                const result = await pool.query(`SELECT vector_id AS id,
+                  1 - (embedding <=> $1::vector) AS score,
+                  metadata
+           FROM "${indexName}"
+           ${where}
+           ORDER BY embedding <=> $1::vector
+           LIMIT $2`, values);
+                return result.rows;
+            });
+        },
+    };
+}