@hyperfixation/core 0.1.0

package/dist/index.js

@@ -0,0 +1,19 @@
+export { defineApp, AppNotAttached, NoApplicationVersion, } from "./define-app.js";
+export { createRegistry, DuplicateRegistration, InvalidDefinition, UnknownRegistration, } from "./registry.js";
+export { defineSource } from "./sources.js";
+export { defineResolver } from "./resolvers.js";
+export { bigramDice, fuzzyCandidateStatement, resolveBatch, DEFAULT_RESOLVE_LIMIT, DEFAULT_RESOLVE_MAX_ATTEMPTS, FUZZY_CANDIDATE_LIMIT, } from "./resolution.js";
+export { defineSpec } from "./specs.js";
+export { defineScorer } from "./scorers.js";
+export { defineSchedule, fireSchedule, schedulesDue, } from "./schedules.js";
+export { latestScores, writeScore, writeStepScore, EXISTING_SCORE_STATEMENT, LATEST_SCORES_STATEMENT, WRITE_SCORE_STATEMENT, } from "./scores.js";
+export { assertActivityKind, insertActivity, listActivity, recordActivity, InvalidActivityKind, ACTIVITY_KIND_PATTERN, ACTIVITY_LIST_OPERATION, EXISTING_ACTIVITY_STATEMENT, INSERT_ACTIVITY_STATEMENT, } from "./activity.js";
+export { cancelOpenTasksForRecord, cancelTask, completeTask, createManualTask, createTask, flowOriginRef, listTasks, TASK_CANCEL_OPERATION, TASK_COMPLETE_OPERATION, TASK_CREATE_MANUAL_OPERATION, TASK_LIST_OPERATION, } from "./tasks.js";
+export { addLabel, listLabels, LABEL_ADD_OPERATION, LABEL_LIST_OPERATION, } from "./labels.js";
+export { listOutcomes, recordOutcome, OUTCOME_LIST_OPERATION, OUTCOME_RECORD_OPERATION, } from "./outcomes.js";
+export { pauseApp, resumeApp, PAUSED_MARKER, PAUSE_OPERATION, RESUMED_MARKER, RESUME_OPERATION, } from "./pause.js";
+export { archiveRecord, archiveDecisionKey, assertRecordStages, displayColumnOf, ARCHIVED_MARKER, ARCHIVE_OPERATION, DEFAULT_DISPLAY_COLUMN, } from "./records.js";
+export { appStatus, CORE_VERSION, } from "./status.js";
+export { createStatusHandler, statusRouteOf, STATUS_TOKEN_ACTOR, } from "./status-route.js";
+export { bearerToken, hashStatusToken, statusTokenMatches, STATUS_TOKEN_DIGEST, } from "./status-token.js";
+export { workspaceBoard, workspaceHome, workspaceInbox, workspaceRecord, DEFAULT_BOARD_LIMIT, WORKSPACE_BOARD_OPERATION, WORKSPACE_HOME_OPERATION, WORKSPACE_INBOX_OPERATION, WORKSPACE_RECORD_OPERATION, } from "./workspace-views.js";

package/dist/labels.d.ts

@@ -0,0 +1,41 @@
+import { type LabelTarget, type LabelValue, type RecordTable } from "@hyperfixation/db";
+import type { Pool } from "pg";
+import type { Registry } from "./registry.js";
+export declare const LABEL_ADD_OPERATION = "labels.add";
+export declare const LABEL_LIST_OPERATION = "labels.list";
+export interface LabelAddOptions {
+    recordType: string;
+    recordId: string | number;
+    target: LabelTarget;
+    /** Which score or draft the label is about; null for a label on the record itself. */
+    targetId?: string | number;
+    value: LabelValue;
+    correction?: unknown;
+    userId?: string;
+}
+export interface LabelListOptions {
+    recordType: string;
+    recordId: string | number;
+}
+export interface LabelRow {
+    id: number;
+    recordType: string;
+    recordId: string;
+    target: LabelTarget;
+    targetId: string | null;
+    value: LabelValue;
+    correction: unknown;
+    userId: string | null;
+    createdAt: Date;
+}
+/**
+ * A human's feedback on a score, a draft or the record, always from the web: `hf_label` is what
+ * the scorer's next spec version is argued from, and nothing in a run produces one.
+ *
+ * The record type is required and registered — the row's `record_type` is NOT NULL, and an
+ * unregistered value is what E002 refuses at the next boot.
+ */
+export declare function addLabel(pool: Pool, records: Registry<RecordTable>, options: LabelAddOptions): Promise<{
+    id: number;
+}>;
+export declare function listLabels(pool: Pool, options: LabelListOptions): Promise<LabelRow[]>;

package/dist/labels.js

@@ -0,0 +1,62 @@
+import { assertNotInWorkflow, controlPlaneTx, } from "@hyperfixation/db";
+import { insertActivity } from "./activity.js";
+export const LABEL_ADD_OPERATION = "labels.add";
+export const LABEL_LIST_OPERATION = "labels.list";
+const INSERT_LABEL_STATEMENT = "INSERT INTO hf_label (record_type, record_id, target, target_id, value, correction, user_id) " +
+    "VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7) RETURNING id";
+const LIST_LABELS_STATEMENT = "SELECT id, record_type, record_id, target, target_id, value, correction, user_id, created_at " +
+    "FROM hf_label WHERE record_type = $1 AND record_id = $2 ORDER BY created_at, id";
+/**
+ * A human's feedback on a score, a draft or the record, always from the web: `hf_label` is what
+ * the scorer's next spec version is argued from, and nothing in a run produces one.
+ *
+ * The record type is required and registered — the row's `record_type` is NOT NULL, and an
+ * unregistered value is what E002 refuses at the next boot.
+ */
+export async function addLabel(pool, records, options) {
+    records.require(options.recordType);
+    const recordId = String(options.recordId);
+    return controlPlaneTx(pool, { operation: LABEL_ADD_OPERATION }, async (work) => {
+        const { rows } = await work.query(INSERT_LABEL_STATEMENT, [
+            options.recordType,
+            recordId,
+            options.target,
+            options.targetId === undefined ? null : String(options.targetId),
+            options.value,
+            options.correction === undefined ? null : JSON.stringify(options.correction),
+            options.userId ?? null,
+        ]);
+        const id = Number(rows[0].id);
+        await insertActivity(work, {
+            recordType: options.recordType,
+            recordId,
+            kind: "label.added",
+            actorId: options.userId ?? null,
+            meta: {
+                labelId: id,
+                target: options.target,
+                targetId: options.targetId === undefined ? null : String(options.targetId),
+                value: options.value,
+            },
+        });
+        return { id };
+    });
+}
+export async function listLabels(pool, options) {
+    assertNotInWorkflow(LABEL_LIST_OPERATION);
+    const { rows } = await pool.query(LIST_LABELS_STATEMENT, [
+        options.recordType,
+        String(options.recordId),
+    ]);
+    return rows.map((row) => ({
+        id: Number(row.id),
+        recordType: row.record_type,
+        recordId: row.record_id,
+        target: row.target,
+        targetId: row.target_id,
+        value: row.value,
+        correction: row.correction,
+        userId: row.user_id,
+        createdAt: row.created_at,
+    }));
+}

package/dist/outcomes.d.ts

@@ -0,0 +1,35 @@
+import { type RecordTable } from "@hyperfixation/db";
+import type { Pool } from "pg";
+import type { Registry } from "./registry.js";
+export declare const OUTCOME_RECORD_OPERATION = "outcomes.record";
+export declare const OUTCOME_LIST_OPERATION = "outcomes.list";
+export interface OutcomeRecordOptions {
+    recordType: string;
+    recordId: string | number;
+    /** The app's own vocabulary — what happened, not how it was scored. */
+    outcome: string;
+    /** When it happened, if that is not now; an outcome is often learned after the fact. */
+    at?: Date;
+    notes?: string;
+    userId?: string;
+}
+export interface OutcomeListOptions {
+    recordType: string;
+    recordId: string | number;
+}
+export interface OutcomeRow {
+    id: number;
+    recordType: string;
+    recordId: string;
+    outcome: string;
+    at: Date;
+    notes: string | null;
+}
+/**
+ * What became of a record, from the web. Unlike a score it is never derived: a flow that thinks
+ * it knows an outcome is asserting a fact about the world, which is a human's to record.
+ */
+export declare function recordOutcome(pool: Pool, records: Registry<RecordTable>, options: OutcomeRecordOptions): Promise<{
+    id: number;
+}>;
+export declare function listOutcomes(pool: Pool, options: OutcomeListOptions): Promise<OutcomeRow[]>;

package/dist/outcomes.js

@@ -0,0 +1,50 @@
+import { assertNotInWorkflow, controlPlaneTx } from "@hyperfixation/db";
+import { insertActivity } from "./activity.js";
+export const OUTCOME_RECORD_OPERATION = "outcomes.record";
+export const OUTCOME_LIST_OPERATION = "outcomes.list";
+const INSERT_OUTCOME_STATEMENT = "INSERT INTO hf_outcome (record_type, record_id, outcome, at, notes) " +
+    "VALUES ($1, $2, $3, COALESCE($4, now()), $5) RETURNING id";
+const LIST_OUTCOMES_STATEMENT = "SELECT id, record_type, record_id, outcome, at, notes FROM hf_outcome " +
+    "WHERE record_type = $1 AND record_id = $2 ORDER BY at, id";
+/**
+ * What became of a record, from the web. Unlike a score it is never derived: a flow that thinks
+ * it knows an outcome is asserting a fact about the world, which is a human's to record.
+ */
+export async function recordOutcome(pool, records, options) {
+    records.require(options.recordType);
+    const recordId = String(options.recordId);
+    return controlPlaneTx(pool, { operation: OUTCOME_RECORD_OPERATION }, async (work) => {
+        const { rows } = await work.query(INSERT_OUTCOME_STATEMENT, [
+            options.recordType,
+            recordId,
+            options.outcome,
+            options.at ?? null,
+            options.notes ?? null,
+        ]);
+        const id = Number(rows[0].id);
+        await insertActivity(work, {
+            recordType: options.recordType,
+            recordId,
+            kind: "outcome.recorded",
+            actorId: options.userId ?? null,
+            body: options.notes ?? null,
+            meta: { outcomeId: id, outcome: options.outcome },
+        });
+        return { id };
+    });
+}
+export async function listOutcomes(pool, options) {
+    assertNotInWorkflow(OUTCOME_LIST_OPERATION);
+    const { rows } = await pool.query(LIST_OUTCOMES_STATEMENT, [
+        options.recordType,
+        String(options.recordId),
+    ]);
+    return rows.map((row) => ({
+        id: Number(row.id),
+        recordType: row.record_type,
+        recordId: row.record_id,
+        outcome: row.outcome,
+        at: row.at,
+        notes: row.notes,
+    }));
+}

package/dist/pages.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A workspace page, keyed by `path`. It says a page exists and what to call it, and nothing
+ * about how to draw it: the workspace ships descriptors and the template renders them, so a
+ * page carries no component here.
+ */
+export interface PageDefinition {
+    readonly path: string;
+    readonly title: string;
+    /** In the workspace nav; a page reached only from another page leaves it out. */
+    readonly nav?: boolean;
+}

package/dist/pages.js

@@ -0,0 +1 @@
+export {};

package/dist/pause.d.ts

@@ -0,0 +1,41 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type QueueConcurrency, type ReconcileReport } from "@hyperfixation/workflows";
+import type { Pool } from "pg";
+export declare const PAUSE_OPERATION = "app.pause";
+export declare const RESUME_OPERATION = "app.resume";
+/** One line per transition, carrying who asked for it. */
+export declare const PAUSED_MARKER = "hf-app: paused";
+export declare const RESUMED_MARKER = "hf-app: resumed";
+export interface PauseOptions {
+    /** Recorded in `hf_app_state.paused_by` and on the audit row. */
+    userId?: string | null;
+    reason?: string;
+}
+export interface PauseResult {
+    paused: true;
+    queues: QueueConcurrency[];
+}
+export interface ResumeOptions extends PauseOptions {
+    /** What `reconcile()` treats as the live version; `defineApp` supplies the app's. */
+    applicationVersion: string;
+}
+export interface ResumeResult {
+    paused: false;
+    queues: QueueConcurrency[];
+    /** The pass that started the next attempt of every run the pause parked. */
+    reconciled: ReconcileReport;
+}
+/**
+ * A control-plane operation. The flag goes first and the queues second, in that order for a
+ * reason: `hf_app_state.paused` is what the step gate reads, so it is the whole of the
+ * correctness, and zero concurrency only stops work being dispatched that the gate would
+ * suspend at its first step anyway. A pause whose queue half failed is still a pause.
+ */
+export declare function pauseApp(pool: Pool, client: DBOSClient, options?: PauseOptions): Promise<PauseResult>;
+/**
+ * The mirror, in the mirrored order: the queues are restored only once the flag is clear, so
+ * there is no window in which a step is dispatched into an app that still reads as paused and
+ * suspends it again. `reconcile()` last, because step (3) is what starts the next attempt of
+ * every run the pause parked, and it only moves a `paused` run while the app is not paused.
+ */
+export declare function resumeApp(pool: Pool, client: DBOSClient, options: ResumeOptions): Promise<ResumeResult>;

package/dist/pause.js

@@ -0,0 +1,52 @@
+import { AppStateMissing, controlPlaneTx, SET_APP_PAUSED_STATEMENT } from "@hyperfixation/db";
+import { reconcile, setPausedQueueConcurrency, } from "@hyperfixation/workflows";
+export const PAUSE_OPERATION = "app.pause";
+export const RESUME_OPERATION = "app.resume";
+/** One line per transition, carrying who asked for it. */
+export const PAUSED_MARKER = "hf-app: paused";
+export const RESUMED_MARKER = "hf-app: resumed";
+const AUDIT_STATEMENT = "INSERT INTO hf_audit (actor_id, action, target_type, target_id, meta) " +
+    "VALUES ($1, $2, 'hf_app_state', '1', $3::jsonb)";
+/**
+ * A control-plane operation. The flag goes first and the queues second, in that order for a
+ * reason: `hf_app_state.paused` is what the step gate reads, so it is the whole of the
+ * correctness, and zero concurrency only stops work being dispatched that the gate would
+ * suspend at its first step anyway. A pause whose queue half failed is still a pause.
+ */
+export async function pauseApp(pool, client, options = {}) {
+    await setPaused(pool, PAUSE_OPERATION, true, options);
+    const queues = await setPausedQueueConcurrency(client, true);
+    console.info(PAUSED_MARKER, JSON.stringify({ by: options.userId ?? null, queues }));
+    return { paused: true, queues };
+}
+/**
+ * The mirror, in the mirrored order: the queues are restored only once the flag is clear, so
+ * there is no window in which a step is dispatched into an app that still reads as paused and
+ * suspends it again. `reconcile()` last, because step (3) is what starts the next attempt of
+ * every run the pause parked, and it only moves a `paused` run while the app is not paused.
+ */
+export async function resumeApp(pool, client, options) {
+    await setPaused(pool, RESUME_OPERATION, false, options);
+    const queues = await setPausedQueueConcurrency(client, false);
+    console.info(RESUMED_MARKER, JSON.stringify({ by: options.userId ?? null, queues }));
+    const reconciled = await reconcile(pool, client, {
+        applicationVersion: options.applicationVersion,
+    });
+    return { paused: false, queues, reconciled };
+}
+/** The flag and its audit row in one tag-asserted transaction; the audit insert is fatal. */
+async function setPaused(pool, operation, paused, options) {
+    await controlPlaneTx(pool, { operation }, async (client) => {
+        const written = await client.query(SET_APP_PAUSED_STATEMENT, [
+            paused,
+            paused ? (options.userId ?? null) : null,
+        ]);
+        if (written.rowCount !== 1)
+            throw new AppStateMissing(operation);
+        await client.query(AUDIT_STATEMENT, [
+            options.userId ?? null,
+            paused ? "app.paused" : "app.resumed",
+            JSON.stringify({ reason: options.reason ?? null }),
+        ]);
+    });
+}

package/dist/records.d.ts

@@ -0,0 +1,67 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type RecordTable } from "@hyperfixation/db";
+import type { Pool } from "pg";
+import { type Registry } from "./registry.js";
+export declare const ARCHIVE_OPERATION = "records.archive";
+/** The `displayColumn` a record type gets when it names none: the mixin's own name column. */
+export declare const DEFAULT_DISPLAY_COLUMN = "normalized_name";
+/** One board column. `name` is the value the mixin's `stage` carries; `title` is the heading. */
+export interface StageDefinition {
+    readonly name: string;
+    readonly title: string;
+}
+/**
+ * What the workspace needs to know about a record type, on top of the two strings the delete
+ * guard and every machinery row already need. All of it is optional: a bare `RecordTable` is
+ * still a valid registration, and the workspace falls back to `recordType` and
+ * `DEFAULT_DISPLAY_COLUMN`.
+ */
+export interface RecordDefinition extends RecordTable {
+    /** What the nav and the board call this type; `recordType` when absent. */
+    readonly title?: string;
+    /** The column the workspace shows as a record's name. */
+    readonly displayColumn?: string;
+    /** The board's columns, in board order. A `stage` outside the list gets an "Other" column. */
+    readonly stages?: readonly StageDefinition[];
+}
+export declare function displayColumnOf(definition: RecordDefinition): string;
+/**
+ * Refused at registration rather than at render: a duplicate stage name would give the board two
+ * columns competing for the same rows, and which one won would depend on iteration order.
+ */
+export declare function assertRecordStages(definition: RecordDefinition): void;
+/** One line per record archived, carrying what it took down with it. */
+export declare const ARCHIVED_MARKER = "hf-records: archived";
+export interface ArchiveOptions {
+    recordType: string;
+    recordId: string | number;
+    userId?: string | null;
+    reason?: string;
+}
+export interface ArchiveResult {
+    recordType: string;
+    recordId: string;
+    /** False when the record was already archived; archiving twice writes nothing the second time. */
+    archived: boolean;
+    /** The approvals this archive cancelled, each through `decide()` and its own bump. */
+    cancelledApprovals: number[];
+    /** The record's open tasks, cancelled in the same transaction as the record itself. */
+    cancelledTasks: number[];
+}
+/** Stable per approval, so an archive retried after a crash replays instead of deciding twice. */
+export declare function archiveDecisionKey(recordType: string, recordId: string, approvalId: number): string;
+/**
+ * A **control-plane operation**, and the reason `assertNotInWorkflow()` exists at all
+ * (round-3 finding 2): called from inside a step's open `ctx.tx` on the same run, the
+ * `FOR UPDATE` this takes on `hf_run` through `decide()` would wait on the step's own
+ * `FOR SHARE` while the step waits on this call — a cycle whose second half is a JS `await`,
+ * which Postgres's deadlock detector cannot see. So it is refused from inside any run, before
+ * a single statement is issued. A flow that wants a record archived creates a task.
+ *
+ * The approvals go first and the record second: cancelling an approval bumps its run, so the
+ * flow waiting on it resumes and sees the cancellation rather than the record vanishing
+ * underneath it. Each approval is its own `decide()` call — a batch would let one bad row
+ * strand the rest — and each carries a `decisionKey` derived from the record, so an archive
+ * retried after a crash replays the decisions it already made.
+ */
+export declare function archiveRecord(pool: Pool, client: DBOSClient, records: Registry<RecordTable>, options: ArchiveOptions): Promise<ArchiveResult>;

package/dist/records.js

@@ -0,0 +1,111 @@
+import { assertNotInWorkflow, controlPlaneTx, quoteIdent, } from "@hyperfixation/db";
+import { decide } from "@hyperfixation/workflows";
+import { insertActivity } from "./activity.js";
+import { InvalidDefinition } from "./registry.js";
+import { cancelOpenTasksForRecord } from "./tasks.js";
+export const ARCHIVE_OPERATION = "records.archive";
+/** The `displayColumn` a record type gets when it names none: the mixin's own name column. */
+export const DEFAULT_DISPLAY_COLUMN = "normalized_name";
+export function displayColumnOf(definition) {
+    return definition.displayColumn ?? DEFAULT_DISPLAY_COLUMN;
+}
+/**
+ * Refused at registration rather than at render: a duplicate stage name would give the board two
+ * columns competing for the same rows, and which one won would depend on iteration order.
+ */
+export function assertRecordStages(definition) {
+    const seen = new Set();
+    for (const stage of definition.stages ?? []) {
+        if (seen.has(stage.name)) {
+            throw new InvalidDefinition("record type", definition.recordType, `lists the stage ${JSON.stringify(stage.name)} twice`);
+        }
+        seen.add(stage.name);
+    }
+}
+/** One line per record archived, carrying what it took down with it. */
+export const ARCHIVED_MARKER = "hf-records: archived";
+/**
+ * Pending approvals on the record being archived. Read unlocked — `decide()` locks what it
+ * decides, and an approval someone decided between this read and that lock is simply not
+ * pending by then and refuses the batch, which is the right answer.
+ */
+const PENDING_FOR_RECORD_STATEMENT = "SELECT id FROM hf_approval WHERE record_type = $1 AND record_id = $2 AND status = 'pending' " +
+    "ORDER BY id";
+const AUDIT_STATEMENT = "INSERT INTO hf_audit (actor_id, action, target_type, target_id, meta) VALUES ($1, 'record.archived', $2, $3, $4::jsonb)";
+/** Stable per approval, so an archive retried after a crash replays instead of deciding twice. */
+export function archiveDecisionKey(recordType, recordId, approvalId) {
+    return `archive:${recordType}:${recordId}:${approvalId}`;
+}
+/**
+ * A **control-plane operation**, and the reason `assertNotInWorkflow()` exists at all
+ * (round-3 finding 2): called from inside a step's open `ctx.tx` on the same run, the
+ * `FOR UPDATE` this takes on `hf_run` through `decide()` would wait on the step's own
+ * `FOR SHARE` while the step waits on this call — a cycle whose second half is a JS `await`,
+ * which Postgres's deadlock detector cannot see. So it is refused from inside any run, before
+ * a single statement is issued. A flow that wants a record archived creates a task.
+ *
+ * The approvals go first and the record second: cancelling an approval bumps its run, so the
+ * flow waiting on it resumes and sees the cancellation rather than the record vanishing
+ * underneath it. Each approval is its own `decide()` call — a batch would let one bad row
+ * strand the rest — and each carries a `decisionKey` derived from the record, so an archive
+ * retried after a crash replays the decisions it already made.
+ */
+export async function archiveRecord(pool, client, records, options) {
+    assertNotInWorkflow(ARCHIVE_OPERATION);
+    const recordId = String(options.recordId);
+    const { table } = records.require(options.recordType);
+    const pending = await pool.query(PENDING_FOR_RECORD_STATEMENT, [
+        options.recordType,
+        recordId,
+    ]);
+    const cancelledApprovals = [];
+    for (const row of pending.rows) {
+        const approvalId = Number(row.id);
+        const result = await decide(pool, client, {
+            ids: [approvalId],
+            decision: "cancelled",
+            via: "archive",
+            decisionKey: archiveDecisionKey(options.recordType, recordId, approvalId),
+            userId: options.userId ?? null,
+        });
+        cancelledApprovals.push(...result.decided.map((decided) => decided.approvalId));
+    }
+    // The tasks go with the record and nothing else does: `hf_activity`, `hf_label` and
+    // `hf_outcome` are the record's history, and archiving is not a deletion.
+    const { archived, cancelledTasks } = await controlPlaneTx(pool, { operation: ARCHIVE_OPERATION }, async (work) => {
+        // `archived_at` is the record mixin's column; a table registered as a record type without
+        // it fails here by name rather than by being quietly skipped.
+        const updated = await work.query(`UPDATE ${quoteIdent(table)} SET archived_at = now() WHERE id = $1 AND archived_at IS NULL`, [recordId]);
+        const cancelled = await cancelOpenTasksForRecord(work, options.recordType, recordId);
+        const meta = {
+            table,
+            reason: options.reason ?? null,
+            cancelledApprovals,
+            cancelledTasks: cancelled,
+            alreadyArchived: updated.rowCount === 0,
+        };
+        await insertActivity(work, {
+            recordType: options.recordType,
+            recordId,
+            kind: "record.archived",
+            actorId: options.userId ?? null,
+            meta,
+        });
+        await work.query(AUDIT_STATEMENT, [
+            options.userId ?? null,
+            options.recordType,
+            recordId,
+            JSON.stringify(meta),
+        ]);
+        return { archived: updated.rowCount === 1, cancelledTasks: cancelled };
+    });
+    const result = {
+        recordType: options.recordType,
+        recordId,
+        archived,
+        cancelledApprovals,
+        cancelledTasks,
+    };
+    console.info(ARCHIVED_MARKER, JSON.stringify(result));
+    return result;
+}

package/dist/registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Every kind of thing an app registers — sources, resolvers, scorers, flows, approval types,
+ * channels, record types — is a registry, not a single fixed implementation, and every one of
+ * them refuses a second registration under a name it already holds.
+ *
+ * A duplicate is always a bug and never a harmless overwrite: the name is what a stored row
+ * points at, so silently replacing a registration would change what every `hf_run.flow`,
+ * `hf_approval.type` and `hf_action_log.channel` row already written means.
+ */
+export declare class DuplicateRegistration extends Error {
+    readonly kind: string;
+    /** Not `name`: that one is `Error`'s, and carries the class name on every error here. */
+    readonly registeredName: string;
+    constructor(kind: string, registeredName: string);
+}
+export declare class UnknownRegistration extends Error {
+    readonly kind: string;
+    readonly known: readonly string[];
+    constructor(kind: string, name: string, known: readonly string[]);
+}
+/**
+ * A definition that is malformed on its face — refused by its `defineX` before any registry
+ * sees it, so a typo in a threshold or a version costs a boot and not a run.
+ */
+export declare class InvalidDefinition extends Error {
+    readonly kind: string;
+    readonly definitionName: string;
+    constructor(kind: string, definitionName: string, problem: string);
+}
+export interface Registry<T> {
+    /** The registered thing, back, so a registration can be an expression. */
+    register(entry: T): T;
+    get(name: string): T | undefined;
+    /** `get` for callers with nothing sensible to do about an absence. */
+    require(name: string): T;
+    has(name: string): boolean;
+    names(): string[];
+    all(): T[];
+    readonly kind: string;
+    readonly size: number;
+}
+/**
+ * `keyOf` exists because not every registration calls its name `name`: a record type is keyed
+ * by `recordType`, which is the string machinery rows actually carry.
+ */
+export declare function createRegistry<T>(kind: string, keyOf?: (entry: T) => string): Registry<T>;

package/dist/registry.js

@@ -0,0 +1,75 @@
+/**
+ * Every kind of thing an app registers — sources, resolvers, scorers, flows, approval types,
+ * channels, record types — is a registry, not a single fixed implementation, and every one of
+ * them refuses a second registration under a name it already holds.
+ *
+ * A duplicate is always a bug and never a harmless overwrite: the name is what a stored row
+ * points at, so silently replacing a registration would change what every `hf_run.flow`,
+ * `hf_approval.type` and `hf_action_log.channel` row already written means.
+ */
+export class DuplicateRegistration extends Error {
+    kind;
+    /** Not `name`: that one is `Error`'s, and carries the class name on every error here. */
+    registeredName;
+    constructor(kind, registeredName) {
+        super(`DuplicateRegistration: a ${kind} named ${JSON.stringify(registeredName)} is already registered`);
+        this.name = "DuplicateRegistration";
+        this.kind = kind;
+        this.registeredName = registeredName;
+    }
+}
+export class UnknownRegistration extends Error {
+    kind;
+    known;
+    constructor(kind, name, known) {
+        super(`UnknownRegistration: no ${kind} named ${JSON.stringify(name)} is registered; ` +
+            `this app registers ${known.length === 0 ? "none" : known.join(", ")}`);
+        this.name = "UnknownRegistration";
+        this.kind = kind;
+        this.known = known;
+    }
+}
+/**
+ * A definition that is malformed on its face — refused by its `defineX` before any registry
+ * sees it, so a typo in a threshold or a version costs a boot and not a run.
+ */
+export class InvalidDefinition extends Error {
+    kind;
+    definitionName;
+    constructor(kind, definitionName, problem) {
+        super(`InvalidDefinition: the ${kind} named ${JSON.stringify(definitionName)} ${problem}`);
+        this.name = "InvalidDefinition";
+        this.kind = kind;
+        this.definitionName = definitionName;
+    }
+}
+/**
+ * `keyOf` exists because not every registration calls its name `name`: a record type is keyed
+ * by `recordType`, which is the string machinery rows actually carry.
+ */
+export function createRegistry(kind, keyOf = (entry) => entry.name) {
+    const entries = new Map();
+    return {
+        kind,
+        get size() {
+            return entries.size;
+        },
+        register(entry) {
+            const key = keyOf(entry);
+            if (entries.has(key))
+                throw new DuplicateRegistration(kind, key);
+            entries.set(key, entry);
+            return entry;
+        },
+        get: (name) => entries.get(name),
+        require(name) {
+            const entry = entries.get(name);
+            if (entry === undefined)
+                throw new UnknownRegistration(kind, name, [...entries.keys()]);
+            return entry;
+        },
+        has: (name) => entries.has(name),
+        names: () => [...entries.keys()],
+        all: () => [...entries.values()],
+    };
+}