@hyperfixation/core 0.1.0

package/dist/resolution.d.ts

@@ -0,0 +1,57 @@
+import { type StepDatabase } from "@hyperfixation/db";
+import type { ResolverDefinition } from "./resolvers.js";
+export declare const DEFAULT_RESOLVE_LIMIT = 500;
+export declare const DEFAULT_RESOLVE_MAX_ATTEMPTS = 3;
+/** How many trigram candidates the re-ranker looks at; the GIN index orders nothing. */
+export declare const FUZZY_CANDIDATE_LIMIT = 20;
+/**
+ * The candidate query, exported so a test can `EXPLAIN` the statement resolution really issues
+ * rather than a hand-copied lookalike. `%` is what the GIN trigram index answers; the
+ * `ORDER BY` is a sort over the bitmap heap scan's output, not an index walk.
+ */
+export declare function fuzzyCandidateStatement(table: string, field: string): string;
+export interface ResolveBatchOptions {
+    resolver: ResolverDefinition;
+    /** The app table the resolver's `recordType` lives in; `exactKeys` are columns on it. */
+    table: string;
+    source: string;
+    /** Rows per call, and per transaction: the caller loops until `done`. Defaults to 500. */
+    limit?: number | undefined;
+    maxAttempts?: number | undefined;
+}
+export interface ResolveBatchResult {
+    scanned: number;
+    linkedExact: number;
+    linkedFuzzy: number;
+    created: number;
+    /** Rows that already carried a link: the record was updated and the link left alone. */
+    updated: number;
+    review: number;
+    error: number;
+    /**
+     * False while the scan filled its `limit` *and* the batch moved at least one row out of the
+     * scan, so the caller has another batch to run.
+     */
+    done: boolean;
+}
+/**
+ * Dice coefficient over bigram multisets, in [0, 1]. Postgres's `similarity()` already ordered
+ * the candidates; this re-ranks them in process, where the comparison is free and a resolver's
+ * `review()` threshold can be read against one scale that does not move with a Postgres upgrade.
+ */
+export declare function bigramDice(a: string, b: string): number;
+/**
+ * Links, creates or parks every unlinked `hf_source_record` row of `source`, inside the
+ * caller's `ctx.tx`. One call is one batch of at most `limit` rows and one transaction, so a
+ * 200k load is many calls: the alternative — one transaction for the whole load — holds
+ * `hf_run FOR SHARE` for as long as resolution takes.
+ *
+ * A row that already carries a link is never re-decided, whatever the link's method: only its
+ * record is updated. That is the whole of "a `manual` or `human_confirmed` link is never
+ * re-decided" — no method is special-cased, because none has to be.
+ *
+ * Records resolve one at a time so a later row sees an earlier row's create, and each one runs
+ * in its own savepoint: a `create`/`update` that throws marks that row `error` and the batch
+ * carries on.
+ */
+export declare function resolveBatch(tx: StepDatabase, options: ResolveBatchOptions): Promise<ResolveBatchResult>;

package/dist/resolution.js

@@ -0,0 +1,221 @@
+import { quoteIdent } from "@hyperfixation/db";
+import { InvalidDefinition } from "./registry.js";
+export const DEFAULT_RESOLVE_LIMIT = 500;
+export const DEFAULT_RESOLVE_MAX_ATTEMPTS = 3;
+/** How many trigram candidates the re-ranker looks at; the GIN index orders nothing. */
+export const FUZZY_CANDIDATE_LIMIT = 20;
+/** Reused per row rather than named per id: `RELEASE` always releases the innermost one. */
+const SAVEPOINT = "hf_resolve_row";
+const SCAN_STATEMENT = "SELECT id, payload FROM hf_source_record " +
+    "WHERE source = $1 AND status <> 'linked' AND attempts < $2 ORDER BY id LIMIT $3 FOR UPDATE";
+const LINKS_STATEMENT = "SELECT source_record_id, record_id FROM hf_record_link WHERE source_record_id = ANY($1::bigint[])";
+const INSERT_LINK_STATEMENT = "INSERT INTO hf_record_link (source_record_id, record_type, record_id, confidence, method) " +
+    "VALUES ($1, $2, $3, $4, $5)";
+const LINKED_STATEMENT = "UPDATE hf_source_record SET status = 'linked', error = NULL WHERE id = $1";
+const REVIEW_STATEMENT = "UPDATE hf_source_record SET status = 'review', error = NULL WHERE id = $1";
+const ERROR_STATEMENT = "UPDATE hf_source_record SET status = 'error', attempts = attempts + 1, error = $2 WHERE id = $1";
+/**
+ * The candidate query, exported so a test can `EXPLAIN` the statement resolution really issues
+ * rather than a hand-copied lookalike. `%` is what the GIN trigram index answers; the
+ * `ORDER BY` is a sort over the bitmap heap scan's output, not an index walk.
+ */
+export function fuzzyCandidateStatement(table, field) {
+    const column = quoteIdent(field);
+    return (`SELECT id, ${column} FROM ${quoteIdent(table)} ` +
+        `WHERE ${column} % $1 AND archived_at IS NULL ` +
+        `ORDER BY similarity(${column}, $1) DESC LIMIT ${FUZZY_CANDIDATE_LIMIT}`);
+}
+function bigrams(value) {
+    const grams = new Map();
+    for (let i = 0; i + 1 < value.length; i += 1) {
+        const gram = value.slice(i, i + 2);
+        grams.set(gram, (grams.get(gram) ?? 0) + 1);
+    }
+    return grams;
+}
+/**
+ * Dice coefficient over bigram multisets, in [0, 1]. Postgres's `similarity()` already ordered
+ * the candidates; this re-ranks them in process, where the comparison is free and a resolver's
+ * `review()` threshold can be read against one scale that does not move with a Postgres upgrade.
+ */
+export function bigramDice(a, b) {
+    if (a === b)
+        return 1;
+    const left = bigrams(a);
+    let total = 0;
+    let shared = 0;
+    for (const count of left.values())
+        total += count;
+    for (const [gram, count] of bigrams(b)) {
+        total += count;
+        shared += Math.min(count, left.get(gram) ?? 0);
+    }
+    return total === 0 ? 0 : (2 * shared) / total;
+}
+function thresholdLiteral(resolver, threshold) {
+    if (!(threshold > 0 && threshold <= 1)) {
+        throw new InvalidDefinition("resolver", resolver.name, `has a fuzzy.threshold of ${threshold}, which is not in (0, 1]`);
+    }
+    // `SET` takes no bind parameters, so the value is interpolated; `toFixed` never produces
+    // exponent notation, which is not a numeric literal Postgres accepts here.
+    return threshold.toFixed(10);
+}
+/** Null or missing in any exact key means the row groups with nothing and joins on nothing. */
+function exactValues(payload, keys) {
+    const values = [];
+    for (const key of keys) {
+        const value = payload[key];
+        if (value === null || value === undefined)
+            return undefined;
+        values.push(String(value));
+    }
+    return values;
+}
+/**
+ * Links, creates or parks every unlinked `hf_source_record` row of `source`, inside the
+ * caller's `ctx.tx`. One call is one batch of at most `limit` rows and one transaction, so a
+ * 200k load is many calls: the alternative — one transaction for the whole load — holds
+ * `hf_run FOR SHARE` for as long as resolution takes.
+ *
+ * A row that already carries a link is never re-decided, whatever the link's method: only its
+ * record is updated. That is the whole of "a `manual` or `human_confirmed` link is never
+ * re-decided" — no method is special-cased, because none has to be.
+ *
+ * Records resolve one at a time so a later row sees an earlier row's create, and each one runs
+ * in its own savepoint: a `create`/`update` that throws marks that row `error` and the batch
+ * carries on.
+ */
+export async function resolveBatch(tx, options) {
+    const { resolver, table, source } = options;
+    const limit = options.limit ?? DEFAULT_RESOLVE_LIMIT;
+    const maxAttempts = options.maxAttempts ?? DEFAULT_RESOLVE_MAX_ATTEMPTS;
+    const client = tx.$client;
+    const result = {
+        scanned: 0,
+        linkedExact: 0,
+        linkedFuzzy: 0,
+        created: 0,
+        updated: 0,
+        review: 0,
+        error: 0,
+        done: true,
+    };
+    const scanned = await client.query(SCAN_STATEMENT, [source, maxAttempts, limit]);
+    const rows = scanned.rows;
+    result.scanned = rows.length;
+    if (rows.length === 0)
+        return result;
+    const linked = await client.query(LINKS_STATEMENT, [rows.map((row) => row.id)]);
+    const existing = new Map(linked.rows.map((row) => [row.source_record_id, row.record_id]));
+    const { fuzzy } = resolver;
+    if (fuzzy) {
+        // Transaction-scoped, so it is set once and survives every ROLLBACK TO SAVEPOINT below.
+        await client.query(`SET LOCAL pg_trgm.similarity_threshold = ${thresholdLiteral(resolver, fuzzy.threshold)}`);
+    }
+    const candidateStatement = fuzzy ? fuzzyCandidateStatement(table, fuzzy.field) : undefined;
+    const payloadKey = fuzzy?.payloadKey ?? fuzzy?.field;
+    const exactStatement = resolver.exactKeys.length === 0
+        ? undefined
+        : `SELECT id FROM ${quoteIdent(table)} WHERE ` +
+            resolver.exactKeys.map((key, i) => `${quoteIdent(key)} = $${i + 1}`).join(" AND ") +
+            " AND archived_at IS NULL LIMIT 1";
+    const link = (id, recordId, method, confidence) => client.query(INSERT_LINK_STATEMENT, [
+        id,
+        resolver.recordType,
+        recordId,
+        confidence,
+        method,
+    ]);
+    const groups = new Map();
+    for (const row of rows) {
+        const recordId = existing.get(row.id);
+        const keys = exactValues(row.payload, resolver.exactKeys);
+        const groupKey = recordId === undefined && keys ? JSON.stringify(keys) : undefined;
+        const leaderOutcome = groupKey === undefined ? undefined : groups.get(groupKey);
+        await client.query(`SAVEPOINT ${SAVEPOINT}`);
+        try {
+            if (recordId !== undefined) {
+                await resolver.update(recordId, row.payload, tx);
+                await client.query(LINKED_STATEMENT, [row.id]);
+                result.updated += 1;
+            }
+            else if (leaderOutcome !== undefined) {
+                // A duplicate within the batch: the leader already decided this entity, so the
+                // follower takes its outcome rather than resolving — and never its own `update`.
+                if (leaderOutcome.kind === "record") {
+                    await link(row.id, leaderOutcome.recordId, "exact", 1);
+                    await client.query(LINKED_STATEMENT, [row.id]);
+                    result.linkedExact += 1;
+                }
+                else if (leaderOutcome.kind === "review") {
+                    await client.query(REVIEW_STATEMENT, [row.id]);
+                    result.review += 1;
+                }
+                else {
+                    throw new Error("the first row of this batch group failed to resolve");
+                }
+            }
+            else {
+                const outcome = await resolveRow(row, keys);
+                if (groupKey !== undefined)
+                    groups.set(groupKey, outcome);
+            }
+            await client.query(`RELEASE SAVEPOINT ${SAVEPOINT}`);
+        }
+        catch (error) {
+            await client.query(`ROLLBACK TO SAVEPOINT ${SAVEPOINT}`);
+            await client.query(`RELEASE SAVEPOINT ${SAVEPOINT}`);
+            await client.query(ERROR_STATEMENT, [row.id, String(error.message ?? error)]);
+            result.error += 1;
+            if (groupKey !== undefined)
+                groups.set(groupKey, { kind: "error" });
+        }
+    }
+    // A `review` row stays scannable, so a full batch that moved nothing would be handed back
+    // identically forever and a `while (!done)` loop would never end. An `error` row counts as
+    // movement: its `attempts` climbs towards `maxAttempts`, which does take it out of the scan.
+    const moved = result.linkedExact + result.linkedFuzzy + result.created + result.updated + result.error;
+    result.done = rows.length < limit || moved === 0;
+    return result;
+    async function resolveRow(row, keys) {
+        if (exactStatement && keys) {
+            const hit = await client.query(exactStatement, keys);
+            const match = hit.rows[0];
+            if (match) {
+                await resolver.update(match.id, row.payload, tx);
+                await link(row.id, match.id, "exact", 1);
+                await client.query(LINKED_STATEMENT, [row.id]);
+                result.linkedExact += 1;
+                return { kind: "record", recordId: match.id };
+            }
+        }
+        const needle = payloadKey === undefined ? undefined : row.payload[payloadKey];
+        if (candidateStatement && typeof needle === "string" && needle !== "") {
+            const candidates = await client.query(candidateStatement, [needle]);
+            let best;
+            for (const candidate of candidates.rows) {
+                const value = candidate[fuzzy.field];
+                const score = typeof value === "string" ? bigramDice(needle, value) : 0;
+                if (!best || score > best.score)
+                    best = { id: candidate.id, score };
+            }
+            if (best) {
+                if (resolver.review?.(best.score) === true) {
+                    await client.query(REVIEW_STATEMENT, [row.id]);
+                    result.review += 1;
+                    return { kind: "review" };
+                }
+                await resolver.update(best.id, row.payload, tx);
+                await link(row.id, best.id, "fuzzy", best.score);
+                await client.query(LINKED_STATEMENT, [row.id]);
+                result.linkedFuzzy += 1;
+                return { kind: "record", recordId: best.id };
+            }
+        }
+        const created = await resolver.create(row.payload, tx);
+        await link(row.id, created.id, "created", null);
+        await client.query(LINKED_STATEMENT, [row.id]);
+        result.created += 1;
+        return { kind: "record", recordId: created.id };
+    }
+}

package/dist/resolvers.d.ts

@@ -0,0 +1,23 @@
+import type { StepDatabase } from "@hyperfixation/db";
+export interface ResolverFuzzy {
+    /** The record column the candidate query matches on, `normalized_name` in every app so far. */
+    readonly field: string;
+    /** The payload key compared against `field`, already normalized. Defaults to `field`. */
+    readonly payloadKey?: string;
+    /** What `pg_trgm.similarity_threshold` is set to for the candidate query; in (0, 1]. */
+    readonly threshold: number;
+}
+export interface ResolverDefinition<P = unknown> {
+    readonly name: string;
+    readonly recordType: string;
+    /** Payload keys joined on before any fuzzy pass; a match on all of them is a link. */
+    readonly exactKeys: readonly string[];
+    readonly fuzzy?: ResolverFuzzy;
+    /** True sends the row to `review` rather than linking it at that similarity. */
+    review?(similarity: number): boolean;
+    create(payload: P, db: StepDatabase): Promise<{
+        id: string;
+    }>;
+    update(id: string, payload: P, db: StepDatabase): Promise<void>;
+}
+export declare function defineResolver<P>(definition: ResolverDefinition<P>): ResolverDefinition<P>;

package/dist/resolvers.js

@@ -0,0 +1,9 @@
+import { InvalidDefinition } from "./registry.js";
+export function defineResolver(definition) {
+    const threshold = definition.fuzzy?.threshold;
+    // 0 matches everything and anything above 1 matches nothing; neither is a resolver anyone meant.
+    if (threshold !== undefined && !(threshold > 0 && threshold <= 1)) {
+        throw new InvalidDefinition("resolver", definition.name, `has a fuzzy.threshold of ${threshold}, which is not in (0, 1]`);
+    }
+    return definition;
+}

package/dist/schedules.d.ts

@@ -0,0 +1,40 @@
+import type { Flow, StartedRun } from "@hyperfixation/workflows";
+import type { Pool } from "pg";
+export interface ScheduleDefinition<I = unknown> {
+    readonly name: string;
+    readonly flow: Flow<I, unknown>;
+    /** An interval in milliseconds, not a cron expression. */
+    readonly every: number;
+    /** The flow's input, built per firing; a flow taking `undefined` needs none. */
+    input?(): I;
+}
+/**
+ * A schedule of any shape, as `AnyFlow` is a flow of any shape: the registry holds these, so
+ * what it holds says nothing about any one flow's input type.
+ */
+export interface AnySchedule {
+    readonly name: string;
+    readonly flow: Flow<never, unknown>;
+    readonly every: number;
+    input?(): unknown;
+}
+export type ScheduleFired = {
+    started: false;
+    reason: "paused";
+} | {
+    started: true;
+    run: StartedRun;
+};
+export declare function defineSchedule<I>(definition: ScheduleDefinition<I>): ScheduleDefinition<I>;
+/**
+ * One firing: a schedule starts a run and never sleeps durably, which is why this is a plain
+ * call a timer outside DBOS makes — `runs.start` is a control-plane operation that
+ * `assertNotInWorkflow()` refuses from inside a run, the same reason `startReconciler` is a
+ * `setInterval`.
+ *
+ * A paused app starts nothing. The flag is read before the run row is written rather than left
+ * to the step gate, so a pause does not accumulate runs that suspend at their first step.
+ */
+export declare function fireSchedule(pool: Pool, schedule: AnySchedule, start: (flow: Flow<unknown, unknown>, input: unknown) => Promise<StartedRun>): Promise<ScheduleFired>;
+/** The names due at `now`: never fired, or last fired at least `every` ms ago. */
+export declare function schedulesDue(schedules: readonly AnySchedule[], now: Date, lastFired: ReadonlyMap<string, Date>): string[];

package/dist/schedules.js

@@ -0,0 +1,32 @@
+import { appPaused } from "@hyperfixation/db";
+import { InvalidDefinition } from "./registry.js";
+export function defineSchedule(definition) {
+    if (!(definition.every > 0)) {
+        throw new InvalidDefinition("schedule", definition.name, `fires every ${definition.every}ms, which is not a positive interval`);
+    }
+    return definition;
+}
+/**
+ * One firing: a schedule starts a run and never sleeps durably, which is why this is a plain
+ * call a timer outside DBOS makes — `runs.start` is a control-plane operation that
+ * `assertNotInWorkflow()` refuses from inside a run, the same reason `startReconciler` is a
+ * `setInterval`.
+ *
+ * A paused app starts nothing. The flag is read before the run row is written rather than left
+ * to the step gate, so a pause does not accumulate runs that suspend at their first step.
+ */
+export async function fireSchedule(pool, schedule, start) {
+    if (await appPaused(pool))
+        return { started: false, reason: "paused" };
+    const run = await start(schedule.flow, schedule.input?.());
+    return { started: true, run };
+}
+/** The names due at `now`: never fired, or last fired at least `every` ms ago. */
+export function schedulesDue(schedules, now, lastFired) {
+    return schedules
+        .filter((schedule) => {
+        const last = lastFired.get(schedule.name);
+        return last === undefined || now.getTime() - last.getTime() >= schedule.every;
+    })
+        .map((schedule) => schedule.name);
+}

package/dist/scorers.d.ts

@@ -0,0 +1,17 @@
+import type { StepContext } from "@hyperfixation/workflows";
+import type { SpecDefinition } from "./specs.js";
+/** What a scorer returns; `writeScore` takes the same fields. */
+export interface Scored {
+    readonly score: number;
+    readonly explanation?: string;
+    /** The `hf_llm_call` row behind an LLM-assigned score; a rule-based score has none. */
+    readonly llmCallId?: number;
+}
+export interface ScorerDefinition<R = unknown, C = unknown> {
+    readonly name: string;
+    readonly recordType: string;
+    readonly spec: SpecDefinition<C>;
+    /** `ctx` is what an LLM-assigned score needs: `llm.run` ledgers against it. */
+    score(record: R, criteria: C, ctx: StepContext): Promise<Scored>;
+}
+export declare function defineScorer<R, C>(definition: ScorerDefinition<R, C>): ScorerDefinition<R, C>;

package/dist/scorers.js

@@ -0,0 +1,3 @@
+export function defineScorer(definition) {
+    return definition;
+}

package/dist/scores.d.ts

@@ -0,0 +1,80 @@
+import { type RecordTable } from "@hyperfixation/db";
+import type { StepContext } from "@hyperfixation/workflows";
+import type { ClientBase, Pool } from "pg";
+import type { Registry } from "./registry.js";
+import type { SpecDefinition } from "./specs.js";
+/**
+ * `DO NOTHING` fires only for a row that carries a `run_id`/`key` pair, which is the partial
+ * unique index's predicate: a web-side or untracked write passes null and always inserts.
+ */
+export declare const WRITE_SCORE_STATEMENT: string;
+export declare const EXISTING_SCORE_STATEMENT = "SELECT id FROM hf_score WHERE run_id = $1 AND key = $2 AND spec_name = $3";
+/**
+ * The newest row per spec, not per record: two specs scoring one record each keep their own
+ * answer, and a later run of one never supersedes the other.
+ */
+export declare const LATEST_SCORES_STATEMENT: string;
+export interface WriteScoreOptions {
+    recordType: string;
+    recordId: string | number;
+    spec: SpecDefinition;
+    score: number;
+    explanation?: string;
+    llmCallId?: number;
+    /** Set together: `(run_id, key, spec_name)` is what makes a step-side write survive a replay. */
+    runId?: string;
+    key?: string;
+}
+export interface ScoreWritten {
+    id: number;
+    /** False when a replay found the row its own key had already written. */
+    created: boolean;
+}
+/** What a step hands `scores.write`; the run and the key come from the step. */
+export interface StepWriteScoreOptions {
+    recordType: string;
+    recordId: string | number;
+    spec: SpecDefinition;
+    score: number;
+    explanation?: string;
+    llmCallId?: number;
+    /** Distinguishes two scores one step writes; defaults to the step's key. */
+    key?: string;
+}
+/**
+ * Always an INSERT, never an UPDATE: `hf_score` is the history of what each spec version
+ * thought, so scoring a record again — under this version or the next — adds a row and leaves
+ * every earlier one standing.
+ *
+ * Takes a bare queryable so the step-side `scores.write` can hand it the open `ctx.tx` client;
+ * this function neither opens a transaction nor touches the record's mixin columns.
+ */
+export declare function writeScore(queryable: Pool | ClientBase, options: WriteScoreOptions): Promise<ScoreWritten>;
+/** One row per spec, newest first by spec name; a spec that never scored the record has none. */
+export interface LatestScoreRow {
+    id: number;
+    /** Null for a row written before `spec_name` existed. */
+    specName: string | null;
+    specVersion: number;
+    score: number;
+    explanation: string | null;
+    llmCallId: number | null;
+    createdAt: Date;
+}
+export interface LatestScoresOptions {
+    recordType: string;
+    recordId: string | number;
+}
+/**
+ * What each spec currently says about one record, out of `hf_score`'s history.
+ *
+ * The record's own mixin columns hold whichever spec scored last, so they cannot answer this
+ * for a record two specs score; the table can, and this is the read that does it.
+ */
+export declare function latestScores(queryable: Pool | ClientBase, options: LatestScoresOptions): Promise<LatestScoreRow[]>;
+/**
+ * A scorer's write, inside `ctx.tx`: the `hf_score` row, the record's mixin columns and the
+ * timeline entry commit together. The mixin UPDATE is idempotent by construction — it writes the
+ * same three values a replay would — so only the insert needs the key.
+ */
+export declare function writeStepScore(ctx: StepContext, records: Registry<RecordTable>, options: StepWriteScoreOptions): Promise<ScoreWritten>;

package/dist/scores.js

@@ -0,0 +1,113 @@
+import { quoteIdent } from "@hyperfixation/db";
+import { insertActivity } from "./activity.js";
+import { stepClient } from "./step-client.js";
+/**
+ * `DO NOTHING` fires only for a row that carries a `run_id`/`key` pair, which is the partial
+ * unique index's predicate: a web-side or untracked write passes null and always inserts.
+ */
+export const WRITE_SCORE_STATEMENT = "INSERT INTO hf_score (record_type, record_id, spec_name, spec_version, score, explanation, " +
+    "llm_call_id, run_id, key) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) " +
+    "ON CONFLICT (run_id, key, spec_name) WHERE key IS NOT NULL DO NOTHING RETURNING id";
+export const EXISTING_SCORE_STATEMENT = "SELECT id FROM hf_score WHERE run_id = $1 AND key = $2 AND spec_name = $3";
+/**
+ * The newest row per spec, not per record: two specs scoring one record each keep their own
+ * answer, and a later run of one never supersedes the other.
+ */
+export const LATEST_SCORES_STATEMENT = "SELECT DISTINCT ON (spec_name) id, spec_name, spec_version, score, explanation, llm_call_id, " +
+    "created_at FROM hf_score WHERE record_type = $1 AND record_id = $2 " +
+    "ORDER BY spec_name, id DESC";
+/**
+ * The mixin's three score columns — the record's current answer, over `hf_score`'s history.
+ * They hold whichever spec scored last; `latestScores` is what answers per spec.
+ */
+const scoreMixinStatement = (table) => `UPDATE ${quoteIdent(table)} SET score = $1, score_explanation = $2, spec_version = $3 ` +
+    "WHERE id = $4";
+/**
+ * Always an INSERT, never an UPDATE: `hf_score` is the history of what each spec version
+ * thought, so scoring a record again — under this version or the next — adds a row and leaves
+ * every earlier one standing.
+ *
+ * Takes a bare queryable so the step-side `scores.write` can hand it the open `ctx.tx` client;
+ * this function neither opens a transaction nor touches the record's mixin columns.
+ */
+export async function writeScore(queryable, options) {
+    const runId = options.runId ?? null;
+    const key = options.key ?? null;
+    const inserted = await queryable.query(WRITE_SCORE_STATEMENT, [
+        options.recordType,
+        String(options.recordId),
+        options.spec.name,
+        options.spec.version,
+        options.score,
+        options.explanation ?? null,
+        options.llmCallId ?? null,
+        runId,
+        key,
+    ]);
+    if (inserted.rows[0] !== undefined)
+        return { id: Number(inserted.rows[0].id), created: true };
+    const found = await queryable.query(EXISTING_SCORE_STATEMENT, [
+        runId,
+        key,
+        options.spec.name,
+    ]);
+    return { id: Number(found.rows[0].id), created: false };
+}
+/**
+ * What each spec currently says about one record, out of `hf_score`'s history.
+ *
+ * The record's own mixin columns hold whichever spec scored last, so they cannot answer this
+ * for a record two specs score; the table can, and this is the read that does it.
+ */
+export async function latestScores(queryable, options) {
+    const { rows } = await queryable.query(LATEST_SCORES_STATEMENT, [
+        options.recordType,
+        String(options.recordId),
+    ]);
+    return rows.map((row) => ({
+        id: Number(row.id),
+        specName: row.spec_name,
+        specVersion: row.spec_version,
+        score: row.score,
+        explanation: row.explanation,
+        llmCallId: row.llm_call_id === null ? null : Number(row.llm_call_id),
+        createdAt: row.created_at,
+    }));
+}
+/**
+ * A scorer's write, inside `ctx.tx`: the `hf_score` row, the record's mixin columns and the
+ * timeline entry commit together. The mixin UPDATE is idempotent by construction — it writes the
+ * same three values a replay would — so only the insert needs the key.
+ */
+export async function writeStepScore(ctx, records, options) {
+    const { table } = records.require(options.recordType);
+    const key = options.key ?? ctx.key;
+    const recordId = String(options.recordId);
+    return ctx.tx(async (db) => {
+        const client = stepClient(db);
+        const written = await writeScore(client, { ...options, runId: ctx.runId, key });
+        await client.query(scoreMixinStatement(table), [
+            options.score,
+            options.explanation ?? null,
+            options.spec.version,
+            recordId,
+        ]);
+        await insertActivity(client, {
+            recordType: options.recordType,
+            recordId,
+            kind: "score.written",
+            runId: ctx.runId,
+            // `hf_activity` has no spec column, so the spec's name is in the key: two specs one step
+            // scores share its key, and the second's timeline entry would otherwise be dropped as a
+            // replay of the first's.
+            key: `${key}:score.written:${options.spec.name}`,
+            meta: {
+                scoreId: written.id,
+                spec: options.spec.name,
+                specVersion: options.spec.version,
+                score: options.score,
+            },
+        });
+        return written;
+    });
+}

package/dist/sources.d.ts

@@ -0,0 +1,13 @@
+/** One row as a source yields it, shaped for `hf_source_record (source, external_id, payload)`. */
+export interface SourceRow<P> {
+    readonly externalId: string;
+    readonly payload: P;
+}
+export interface SourceDefinition<P = unknown> {
+    readonly name: string;
+    /** What `defineRecord` calls the records this source produces. */
+    readonly recordType: string;
+    /** Streamed rather than returned: the loader COPYs it, and a full source need not fit in memory. */
+    fetch(): AsyncIterable<SourceRow<P>>;
+}
+export declare function defineSource<P>(definition: SourceDefinition<P>): SourceDefinition<P>;

package/dist/sources.js

@@ -0,0 +1,3 @@
+export function defineSource(definition) {
+    return definition;
+}

package/dist/specs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What a scorer scores against, versioned. One live version per name: `hf_score.spec_version`
+ * and the record mixin's `spec_version` carry the number of the spec a stored score was written
+ * under, so a new version adds rows and never rewrites what the old one decided.
+ */
+export interface SpecDefinition<C = unknown> {
+    readonly name: string;
+    /** An integer of at least 1, bumped whenever `criteria` changes meaning. */
+    readonly version: number;
+    readonly criteria: C;
+}
+export declare function defineSpec<C>(definition: SpecDefinition<C>): SpecDefinition<C>;

package/dist/specs.js

@@ -0,0 +1,7 @@
+import { InvalidDefinition } from "./registry.js";
+export function defineSpec(definition) {
+    if (!Number.isInteger(definition.version) || definition.version < 1) {
+        throw new InvalidDefinition("spec", definition.name, `has a version of ${definition.version}, which is not an integer of at least 1`);
+    }
+    return definition;
+}