@hyperfixation/db 0.1.0

package/dist/schema/machinery.js

@@ -0,0 +1,146 @@
+import { sql } from "drizzle-orm";
+import { bigint, doublePrecision, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, } from "drizzle-orm/pg-core";
+// None of these tables carries a foreign key to an app table (E004 applies the other way
+// round, but the core cannot know an app's tables either), and every `record_id` is `text`
+// — a record id is carried, not joined on, matching hf_approval and hf_action_log.
+// Lock order: all of them sit in the last tier, with the app's own tables.
+export const sourceRunStatuses = ["running", "ok", "error"];
+export const sourceRecordStatuses = ["new", "linked", "review", "error"];
+// `created` is the link for a record the resolver made for this source row; the column is
+// plain `text`, so widening the union is a TypeScript change with no migration behind it.
+export const recordLinkMethods = ["exact", "fuzzy", "created", "manual", "human_confirmed"];
+export const taskOrigins = ["flow", "manual", "sweep"];
+export const labelTargets = ["score", "draft", "record"];
+export const labelValues = ["up", "down", "correction"];
+const at = (name) => timestamp(name, { withTimezone: true, mode: "date" });
+const id = () => bigint("id", { mode: "number" }).generatedAlwaysAsIdentity().primaryKey();
+export const hfSourceRun = pgTable("hf_source_run", {
+    id: id(),
+    source: text("source").notNull(),
+    startedAt: at("started_at").notNull().defaultNow(),
+    finishedAt: at("finished_at"),
+    status: text("status", { enum: sourceRunStatuses }).notNull(),
+    rowsIn: integer("rows_in").notNull().default(0),
+    rowsNew: integer("rows_new").notNull().default(0),
+    rowsChanged: integer("rows_changed").notNull().default(0),
+    error: text("error"),
+});
+export const hfSourceRecord = pgTable("hf_source_record", {
+    id: id(),
+    source: text("source").notNull(),
+    externalId: text("external_id").notNull(),
+    payload: jsonb("payload").notNull(),
+    payloadHash: text("payload_hash").notNull(),
+    status: text("status", { enum: sourceRecordStatuses }).notNull().default("new"),
+    attempts: integer("attempts").notNull().default(0),
+    error: text("error"),
+    runId: bigint("run_id", { mode: "number" }),
+    firstSeen: at("first_seen").notNull().defaultNow(),
+    lastSeen: at("last_seen").notNull().defaultNow(),
+}, (t) => [
+    uniqueIndex("hf_source_record_source_external_uq").on(t.source, t.externalId),
+    // The resolver's batch scan: what is still `new` or waiting in `review`.
+    index("hf_source_record_status_idx").on(t.status),
+]);
+export const hfRecordLink = pgTable("hf_record_link", {
+    id: id(),
+    sourceRecordId: bigint("source_record_id", { mode: "number" }).notNull(),
+    recordType: text("record_type").notNull(),
+    recordId: text("record_id").notNull(),
+    confidence: doublePrecision("confidence"),
+    method: text("method", { enum: recordLinkMethods }).notNull(),
+    decidedBy: text("decided_by"),
+    decidedAt: at("decided_at"),
+}, (t) => [
+    uniqueIndex("hf_record_link_source_record_uq").on(t.sourceRecordId),
+    index("hf_record_link_record_idx").on(t.recordType, t.recordId),
+]);
+export const hfScore = pgTable("hf_score", {
+    id: id(),
+    recordType: text("record_type").notNull(),
+    recordId: text("record_id").notNull(),
+    // Which spec decided this, alongside the version it decided under: two specs score one
+    // record, and without the name their rows are indistinguishable. Nullable for the rows
+    // written before it existed — every write path fills it.
+    specName: text("spec_name"),
+    specVersion: integer("spec_version").notNull(),
+    score: doublePrecision("score").notNull(),
+    explanation: text("explanation"),
+    // The ledger row of the call that produced an LLM-assigned score; a rule-based score has none.
+    llmCallId: bigint("llm_call_id", { mode: "number" }),
+    // What makes a step-side score write replay-safe: attempt 2 runs the step again under a new
+    // workflow id, and `(run_id, key, spec_name)` is what it conflicts on. Null for a web-side
+    // write. The spec name is in the key because one step may score a record under two specs,
+    // which share the step's key and must not collapse into one row.
+    runId: text("run_id"),
+    key: text("key"),
+    createdAt: at("created_at").notNull().defaultNow(),
+}, (t) => [
+    index("hf_score_record_idx").on(t.recordType, t.recordId),
+    uniqueIndex("hf_score_run_key_spec_uq")
+        .on(t.runId, t.key, t.specName)
+        .where(sql `${t.key} IS NOT NULL`),
+]);
+export const hfActivity = pgTable("hf_activity", {
+    id: id(),
+    // Nullable, like `hf_approval`'s and `hf_action_log`'s: a row about no record writes NULL,
+    // which E002 ignores. A stand-in such as `'hf_approval'` would fail it at the next boot.
+    recordType: text("record_type"),
+    recordId: text("record_id"),
+    kind: text("kind").notNull(),
+    actorId: text("actor_id"),
+    body: text("body"),
+    meta: jsonb("meta"),
+    // The run that wrote it, for the timeline; null for a web-side write (a label, an
+    // outcome, a manual task), which the timeline groups under "manual".
+    runId: text("run_id"),
+    // The idempotency key of the step that wrote it; null for a web-side write, which happens
+    // once per request and has no replay to survive.
+    key: text("key"),
+    at: at("at").notNull().defaultNow(),
+}, (t) => [
+    index("hf_activity_record_idx").on(t.recordType, t.recordId),
+    uniqueIndex("hf_activity_run_key_uq")
+        .on(t.runId, t.key)
+        .where(sql `${t.key} IS NOT NULL`),
+]);
+export const hfTask = pgTable("hf_task", {
+    id: id(),
+    // Nullable for the same reason as `hf_activity`'s above.
+    recordType: text("record_type"),
+    recordId: text("record_id"),
+    title: text("title").notNull(),
+    dueAt: at("due_at"),
+    ownerId: text("owner_id"),
+    doneAt: at("done_at"),
+    cancelledAt: at("cancelled_at"),
+    origin: text("origin", { enum: taskOrigins }).notNull(),
+    // Makes "one task per uncertain action row, once" an `ON CONFLICT` target for
+    // `reconcile()` and `actions.perform`; set to the action-log row's id.
+    originRef: text("origin_ref"),
+    createdAt: at("created_at").notNull().defaultNow(),
+}, (t) => [
+    index("hf_task_record_idx").on(t.recordType, t.recordId),
+    uniqueIndex("hf_task_origin_ref_uq")
+        .on(t.origin, t.originRef)
+        .where(sql `${t.originRef} IS NOT NULL`),
+]);
+export const hfLabel = pgTable("hf_label", {
+    id: id(),
+    recordType: text("record_type").notNull(),
+    recordId: text("record_id").notNull(),
+    target: text("target", { enum: labelTargets }).notNull(),
+    targetId: text("target_id"),
+    value: text("value", { enum: labelValues }).notNull(),
+    correction: jsonb("correction"),
+    userId: text("user_id"),
+    createdAt: at("created_at").notNull().defaultNow(),
+}, (t) => [index("hf_label_record_idx").on(t.recordType, t.recordId)]);
+export const hfOutcome = pgTable("hf_outcome", {
+    id: id(),
+    recordType: text("record_type").notNull(),
+    recordId: text("record_id").notNull(),
+    outcome: text("outcome").notNull(),
+    at: at("at").notNull().defaultNow(),
+    notes: text("notes"),
+}, (t) => [index("hf_outcome_record_idx").on(t.recordType, t.recordId)]);

package/dist/schema/records.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Spread into an app's record table. Every column is nullable or DB-defaulted and none is
+ * unique, so adding the mixin to an existing table is an allowed app migration. The trigram
+ * index on `normalized_name` is the app's to declare (E003 fails boot without it).
+ */
+export declare const hfRecordColumns: () => {
+    createdAt: import("drizzle-orm").HasDefault<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"created_at">>;
+    updatedAt: import("drizzle-orm").HasDefault<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"updated_at">>;
+    archivedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"archived_at">;
+    stage: import("drizzle-orm/pg-core").PgTextBuilderInitial<"stage", [string, ...string[]]>;
+    score: import("drizzle-orm/pg-core").PgDoublePrecisionBuilderInitial<"score">;
+    scoreExplanation: import("drizzle-orm/pg-core").PgTextBuilderInitial<"score_explanation", [string, ...string[]]>;
+    specVersion: import("drizzle-orm/pg-core").PgIntegerBuilderInitial<"spec_version">;
+    normalizedName: import("drizzle-orm/pg-core").PgTextBuilderInitial<"normalized_name", [string, ...string[]]>;
+};

package/dist/schema/records.js

@@ -0,0 +1,16 @@
+import { doublePrecision, integer, text, timestamp } from "drizzle-orm/pg-core";
+/**
+ * Spread into an app's record table. Every column is nullable or DB-defaulted and none is
+ * unique, so adding the mixin to an existing table is an allowed app migration. The trigram
+ * index on `normalized_name` is the app's to declare (E003 fails boot without it).
+ */
+export const hfRecordColumns = () => ({
+    createdAt: timestamp("created_at", { withTimezone: true, mode: "date" }).defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true, mode: "date" }).defaultNow(),
+    archivedAt: timestamp("archived_at", { withTimezone: true, mode: "date" }),
+    stage: text("stage"),
+    score: doublePrecision("score"),
+    scoreExplanation: text("score_explanation"),
+    specVersion: integer("spec_version"),
+    normalizedName: text("normalized_name"),
+});

package/dist/schema/runs.d.ts

@@ -0,0 +1,213 @@
+export declare const runStatuses: readonly ["running", "waiting", "paused", "done", "failed"];
+export type RunStatus = (typeof runStatuses)[number];
+export declare const hfRun: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "hf_run";
+    schema: undefined;
+    columns: {
+        runId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "run_id";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        flow: import("drizzle-orm/pg-core").PgColumn<{
+            name: "flow";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        input: import("drizzle-orm/pg-core").PgColumn<{
+            name: "input";
+            tableName: "hf_run";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: "paused" | "failed" | "running" | "waiting" | "done";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["running", "waiting", "paused", "done", "failed"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "attempt";
+            tableName: "hf_run";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        currentWorkflowId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "current_workflow_id";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        version: import("drizzle-orm/pg-core").PgColumn<{
+            name: "version";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        recordType: import("drizzle-orm/pg-core").PgColumn<{
+            name: "record_type";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        recordId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "record_id";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        error: import("drizzle-orm/pg-core").PgColumn<{
+            name: "error";
+            tableName: "hf_run";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        startedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "started_at";
+            tableName: "hf_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        finishedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "finished_at";
+            tableName: "hf_run";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/schema/runs.js

@@ -0,0 +1,26 @@
+import { sql } from "drizzle-orm";
+import { check, index, integer, jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+export const runStatuses = ["running", "waiting", "paused", "done", "failed"];
+export const hfRun = pgTable("hf_run", {
+    runId: text("run_id").primaryKey(),
+    flow: text("flow").notNull(),
+    input: jsonb("input"),
+    status: text("status", { enum: runStatuses }).notNull(),
+    attempt: integer("attempt").notNull().default(1),
+    // The fencing token: attempt 1 is `run_id`, attempt N is `run_id:N`. Written
+    // only by the one bump path under FOR UPDATE; every step write takes FOR SHARE
+    // on this row and matches it.
+    currentWorkflowId: text("current_workflow_id").notNull().unique(),
+    version: text("version"),
+    recordType: text("record_type"),
+    recordId: text("record_id"),
+    error: text("error"),
+    startedAt: timestamp("started_at", { withTimezone: true, mode: "date" })
+        .notNull()
+        .defaultNow(),
+    finishedAt: timestamp("finished_at", { withTimezone: true, mode: "date" }),
+}, (t) => [
+    index("hf_run_status_idx").on(t.status),
+    index("hf_run_record_idx").on(t.recordType, t.recordId),
+    check("hf_run_attempt_positive", sql `${t.attempt} >= 1`),
+]);

package/dist/step-pool.d.ts

@@ -0,0 +1,26 @@
+import { type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { Pool, type PoolConfig } from "pg";
+import * as schema from "./schema/index.js";
+export declare const STEP_POOL_SIZE = 8;
+/** `ctx.tx`'s first statement, and the only place the fencing token is read. */
+export declare const FENCE_STATEMENT = "SELECT 1 FROM hf_run WHERE run_id = $1 AND current_workflow_id = $2 FOR SHARE";
+export declare class StaleAttempt extends Error {
+    readonly runId: string;
+    readonly workflowId: string;
+    constructor(runId: string, workflowId: string);
+}
+export type StepDatabase = NodePgDatabase<typeof schema>;
+export type StepPoolOptions = PoolConfig;
+export interface StepPool {
+    /** The fenced `pg.Pool`: reads pass, writes are refused outside `ctx.tx`. */
+    readonly pool: Pool;
+    /** What an app's `@/db` resolves to in the worker. */
+    readonly db: StepDatabase;
+    tx<T>(runId: string, workflowId: string, work: (tx: StepDatabase) => Promise<T>): Promise<T>;
+    end(): Promise<void>;
+}
+/**
+ * The only database handle step and app code are meant to reach. `runId`/`workflowId` are
+ * explicit here; chunk 9 supplies them from the DBOS context.
+ */
+export declare function createStepPool(options: StepPoolOptions): StepPool;

package/dist/step-pool.js

@@ -0,0 +1,57 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { fencePool, tagForTransaction } from "./fenced-client.js";
+import * as schema from "./schema/index.js";
+export const STEP_POOL_SIZE = 8;
+/** `ctx.tx`'s first statement, and the only place the fencing token is read. */
+export const FENCE_STATEMENT = "SELECT 1 FROM hf_run WHERE run_id = $1 AND current_workflow_id = $2 FOR SHARE";
+export class StaleAttempt extends Error {
+    runId;
+    workflowId;
+    constructor(runId, workflowId) {
+        super(`StaleAttempt: hf_run ${runId} is no longer on attempt ${workflowId}`);
+        this.name = "StaleAttempt";
+        this.runId = runId;
+        this.workflowId = workflowId;
+    }
+}
+/**
+ * The only database handle step and app code are meant to reach. `runId`/`workflowId` are
+ * explicit here; chunk 9 supplies them from the DBOS context.
+ */
+export function createStepPool(options) {
+    const pool = fencePool(new Pool({ max: STEP_POOL_SIZE, ...options }));
+    return {
+        pool,
+        db: drizzle(pool, { schema }),
+        async tx(runId, workflowId, work) {
+            const client = await pool.connect();
+            tagForTransaction(client);
+            let broken;
+            try {
+                await client.query("BEGIN");
+                const fence = await client.query(FENCE_STATEMENT, [runId, workflowId]);
+                if (fence.rowCount === 0)
+                    throw new StaleAttempt(runId, workflowId);
+                const result = await work(drizzle(client, { schema }));
+                await client.query("COMMIT");
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query("ROLLBACK");
+                }
+                catch (rollbackError) {
+                    // The connection is in an unknown transaction state; hand it back with the error
+                    // so the pool destroys it instead of leasing it to the next transaction.
+                    broken = rollbackError;
+                }
+                throw error;
+            }
+            finally {
+                client.release(broken);
+            }
+        },
+        end: () => pool.end(),
+    };
+}