@hyperfixation/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graham Lutz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/activity.d.ts

@@ -0,0 +1,73 @@
+import type { StepContext } from "@hyperfixation/workflows";
+import type { ClientBase, Pool } from "pg";
+export declare const ACTIVITY_LIST_OPERATION = "activity.list";
+/** `<noun>.<verb>`, the shape `action.uncertain` and `approval.<decision>` already write. */
+export declare const ACTIVITY_KIND_PATTERN: RegExp;
+export declare class InvalidActivityKind extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+/**
+ * `DO NOTHING` on the partial `(run_id, key)` index: a step re-run under a second attempt writes
+ * the same key and adds nothing, which is what makes every step-side write in this package
+ * replay-safe. A web-side write passes `key` null, no conflict can fire, and the row is added.
+ */
+export declare const INSERT_ACTIVITY_STATEMENT: string;
+export declare const EXISTING_ACTIVITY_STATEMENT = "SELECT id FROM hf_activity WHERE run_id = $1 AND key = $2";
+/** The whole row, as any writer in this package supplies it. */
+export interface ActivityWrite {
+    kind: string;
+    recordType?: string | null;
+    recordId?: string | number | null;
+    actorId?: string | null;
+    body?: string | null;
+    meta?: unknown;
+    runId?: string | null;
+    key?: string | null;
+}
+export interface ActivityRecorded {
+    id: number;
+    /** False when a replay found the row its own key had already written. */
+    created: boolean;
+}
+/** What a flow records: the run and the key come from the step, not from the caller. */
+export interface ActivityRecordOptions {
+    kind: string;
+    recordType?: string;
+    recordId?: string | number;
+    actorId?: string;
+    body?: string;
+    meta?: unknown;
+    /** Distinguishes two rows written by one step; defaults to the step's key and the kind. */
+    key?: string;
+}
+export interface ActivityListOptions {
+    recordType: string;
+    recordId: string | number;
+}
+export interface ActivityRow {
+    id: number;
+    recordType: string | null;
+    recordId: string | null;
+    kind: string;
+    actorId: string | null;
+    body: string | null;
+    meta: unknown;
+    /** Null for a web-side write; C6's timeline groups those under "manual". */
+    runId: string | null;
+    at: Date;
+}
+export declare function assertActivityKind(kind: string): void;
+/**
+ * The one `hf_activity` writer in this package — tasks, labels, outcomes, scores and
+ * `records.archive()` all go through it, on whatever client their own transaction already holds.
+ */
+export declare function insertActivity(queryable: Pool | ClientBase, write: ActivityWrite): Promise<ActivityRecorded>;
+/**
+ * A flow's own timeline entry, written inside `ctx.tx` so it commits with whatever else the step
+ * wrote. The default key is the step's, which makes one row per step per kind: a step that wants
+ * two rows of one kind names them itself.
+ */
+export declare function recordActivity(ctx: StepContext, options: ActivityRecordOptions): Promise<ActivityRecorded>;
+/** A control-plane read: `run_id` travels with the row so the timeline can group by it. */
+export declare function listActivity(pool: Pool, options: ActivityListOptions): Promise<ActivityRow[]>;

package/dist/activity.js

@@ -0,0 +1,84 @@
+import { assertNotInWorkflow } from "@hyperfixation/db";
+import { stepClient } from "./step-client.js";
+export const ACTIVITY_LIST_OPERATION = "activity.list";
+/** `<noun>.<verb>`, the shape `action.uncertain` and `approval.<decision>` already write. */
+export const ACTIVITY_KIND_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+export class InvalidActivityKind extends Error {
+    kind;
+    constructor(kind) {
+        super(`InvalidActivityKind: ${JSON.stringify(kind)} is not a <noun>.<verb> activity kind, ` +
+            "as 'task.created' and 'action.uncertain' are");
+        this.name = "InvalidActivityKind";
+        this.kind = kind;
+    }
+}
+/**
+ * `DO NOTHING` on the partial `(run_id, key)` index: a step re-run under a second attempt writes
+ * the same key and adds nothing, which is what makes every step-side write in this package
+ * replay-safe. A web-side write passes `key` null, no conflict can fire, and the row is added.
+ */
+export const INSERT_ACTIVITY_STATEMENT = "INSERT INTO hf_activity (record_type, record_id, kind, actor_id, body, meta, run_id, key) " +
+    "VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8) " +
+    "ON CONFLICT (run_id, key) WHERE key IS NOT NULL DO NOTHING RETURNING id";
+export const EXISTING_ACTIVITY_STATEMENT = "SELECT id FROM hf_activity WHERE run_id = $1 AND key = $2";
+const LIST_ACTIVITY_STATEMENT = "SELECT id, record_type, record_id, kind, actor_id, body, meta, run_id, at FROM hf_activity " +
+    "WHERE record_type = $1 AND record_id = $2 ORDER BY at, id";
+export function assertActivityKind(kind) {
+    if (!ACTIVITY_KIND_PATTERN.test(kind))
+        throw new InvalidActivityKind(kind);
+}
+/**
+ * The one `hf_activity` writer in this package — tasks, labels, outcomes, scores and
+ * `records.archive()` all go through it, on whatever client their own transaction already holds.
+ */
+export async function insertActivity(queryable, write) {
+    assertActivityKind(write.kind);
+    const runId = write.runId ?? null;
+    const key = write.key ?? null;
+    const inserted = await queryable.query(INSERT_ACTIVITY_STATEMENT, [
+        write.recordType ?? null,
+        write.recordId === undefined || write.recordId === null ? null : String(write.recordId),
+        write.kind,
+        write.actorId ?? null,
+        write.body ?? null,
+        write.meta === undefined ? null : JSON.stringify(write.meta),
+        runId,
+        key,
+    ]);
+    if (inserted.rows[0] !== undefined)
+        return { id: Number(inserted.rows[0].id), created: true };
+    const found = await queryable.query(EXISTING_ACTIVITY_STATEMENT, [runId, key]);
+    return { id: Number(found.rows[0].id), created: false };
+}
+/**
+ * A flow's own timeline entry, written inside `ctx.tx` so it commits with whatever else the step
+ * wrote. The default key is the step's, which makes one row per step per kind: a step that wants
+ * two rows of one kind names them itself.
+ */
+export async function recordActivity(ctx, options) {
+    assertActivityKind(options.kind);
+    return ctx.tx((db) => insertActivity(stepClient(db), {
+        ...options,
+        runId: ctx.runId,
+        key: options.key ?? `${ctx.key}:${options.kind}`,
+    }));
+}
+/** A control-plane read: `run_id` travels with the row so the timeline can group by it. */
+export async function listActivity(pool, options) {
+    assertNotInWorkflow(ACTIVITY_LIST_OPERATION);
+    const { rows } = await pool.query(LIST_ACTIVITY_STATEMENT, [
+        options.recordType,
+        String(options.recordId),
+    ]);
+    return rows.map((row) => ({
+        id: Number(row.id),
+        recordType: row.record_type,
+        recordId: row.record_id,
+        kind: row.kind,
+        actorId: row.actor_id,
+        body: row.body,
+        meta: row.meta,
+        runId: row.run_id,
+        at: row.at,
+    }));
+}

package/dist/define-app.d.ts

@@ -0,0 +1,171 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import type { StepDatabase } from "@hyperfixation/db";
+import { type ActionChannel, type ApprovalDraftSchema, type DecideOptions, type DecideResult, type Flow, type ReconcileOptions, type ReconcileReport, type RunsStartOptions, type StartedRun, type StepContext } from "@hyperfixation/workflows";
+import type { Pool } from "pg";
+import { type ActivityListOptions, type ActivityRecordOptions, type ActivityRecorded, type ActivityRow } from "./activity.js";
+import { type LabelAddOptions, type LabelListOptions, type LabelRow } from "./labels.js";
+import { type OutcomeListOptions, type OutcomeRecordOptions, type OutcomeRow } from "./outcomes.js";
+import type { PageDefinition } from "./pages.js";
+import { type PauseOptions, type PauseResult, type ResumeResult } from "./pause.js";
+import { type ArchiveOptions, type ArchiveResult, type RecordDefinition } from "./records.js";
+import { type Registry } from "./registry.js";
+import { type ResolveBatchResult } from "./resolution.js";
+import type { ResolverDefinition } from "./resolvers.js";
+import { type AnySchedule, type ScheduleFired } from "./schedules.js";
+import type { ScorerDefinition } from "./scorers.js";
+import { type ScoreWritten, type StepWriteScoreOptions } from "./scores.js";
+import type { SourceDefinition } from "./sources.js";
+import type { SpecDefinition } from "./specs.js";
+import { type StatusReport } from "./status.js";
+import { type TaskCloseOptions, type TaskClosed, type TaskCreateManualOptions, type TaskCreateOptions, type TaskCreated, type TaskListOptions, type TaskRow } from "./tasks.js";
+import { type AppWorkspace } from "./workspace.js";
+/**
+ * A flow of any shape. `Flow<never, unknown>` is the bottom of the family: its input is
+ * contravariant, so every `Flow<I, O>` is one of these.
+ */
+export type AnyFlow = Flow<never, unknown>;
+export interface ApprovalTypeDefinition {
+    readonly name: string;
+    /** The Zod schema an edited draft is parsed against; a type without one refuses every edit. */
+    readonly schema?: ApprovalDraftSchema;
+}
+/**
+ * The pool and client every control-plane operation runs on. In the worker this is the control
+ * pool `startWorker()` built and the worker's own `DBOSClient`; in the web it is the web's
+ * ordinary pool and `getClient()`. Neither is fenced, and neither has to be: a control-plane
+ * operation's fence is a predicate, and `assertNotInWorkflow()` is what keeps it out of a run.
+ */
+export interface ControlPlane {
+    pool: Pool;
+    client: DBOSClient;
+}
+export declare class AppNotAttached extends Error {
+    readonly operation: string;
+    constructor(operation: string);
+}
+export declare class NoApplicationVersion extends Error {
+    constructor(operation: string);
+}
+export interface DefineAppOptions {
+    name: string;
+    /** Defaults to `HF_BUILD_SHA`, the one source of a version in every process. */
+    applicationVersion?: string;
+    flows?: readonly AnyFlow[];
+    sources?: readonly SourceDefinition[];
+    resolvers?: readonly ResolverDefinition[];
+    scorers?: readonly ScorerDefinition[];
+    specs?: readonly SpecDefinition[];
+    approvalTypes?: readonly ApprovalTypeDefinition[];
+    channels?: readonly ActionChannel[];
+    /** A bare `RecordTable` is still one of these: everything the workspace adds is optional. */
+    records?: readonly RecordDefinition[];
+    pages?: readonly PageDefinition[];
+    schedules?: readonly AnySchedule[];
+}
+export interface AppRecords {
+    /** Registered record types, keyed by the `record_type` machinery rows carry. */
+    readonly types: Registry<RecordDefinition>;
+    archive(options: ArchiveOptions): Promise<ArchiveResult>;
+}
+/**
+ * The write helpers split by where they run, not by what they write: `record` takes the step's
+ * context and writes inside `ctx.tx`, `list` is a control-plane read. There is no one entry point
+ * that sniffs the handle — a flow and the web reach different functions on purpose.
+ */
+export interface AppActivity {
+    record(ctx: StepContext, options: ActivityRecordOptions): Promise<ActivityRecorded>;
+    list(options: ActivityListOptions): Promise<ActivityRow[]>;
+}
+export interface AppTasks {
+    /** A flow's follow-up, keyed by the step so a replay finds its own task. */
+    create(ctx: StepContext, options: TaskCreateOptions): Promise<TaskCreated>;
+    createManual(options: TaskCreateManualOptions): Promise<TaskCreated>;
+    complete(options: TaskCloseOptions): Promise<TaskClosed>;
+    cancel(options: TaskCloseOptions): Promise<TaskClosed>;
+    list(options?: TaskListOptions): Promise<TaskRow[]>;
+}
+export interface AppLabels {
+    add(options: LabelAddOptions): Promise<{
+        id: number;
+    }>;
+    list(options: LabelListOptions): Promise<LabelRow[]>;
+}
+export interface AppOutcomes {
+    record(options: OutcomeRecordOptions): Promise<{
+        id: number;
+    }>;
+    list(options: OutcomeListOptions): Promise<OutcomeRow[]>;
+}
+export interface AppScores {
+    /** The `hf_score` row, the record's mixin columns and the timeline entry, in one transaction. */
+    write(ctx: StepContext, options: StepWriteScoreOptions): Promise<ScoreWritten>;
+}
+export interface AppResolutionBatchOptions {
+    resolver: string;
+    source: string;
+    limit?: number | undefined;
+    maxAttempts?: number | undefined;
+}
+export interface AppResolution {
+    /**
+     * Step-side, so it takes the open `ctx.tx` and not the control plane: resolution is a write
+     * inside a run's transaction, and the table comes from the resolver's registered record type.
+     */
+    batch(tx: StepDatabase, options: AppResolutionBatchOptions): Promise<ResolveBatchResult>;
+}
+export interface AppSchedules extends Registry<AnySchedule> {
+    /** Starts the schedule's flow now, unless the app is paused. */
+    fire(name: string): Promise<ScheduleFired>;
+    due(now: Date, lastFired: ReadonlyMap<string, Date>): string[];
+}
+export interface App {
+    readonly name: string;
+    readonly applicationVersion: string | undefined;
+    readonly flows: Registry<AnyFlow>;
+    readonly sources: Registry<SourceDefinition>;
+    readonly resolvers: Registry<ResolverDefinition>;
+    readonly scorers: Registry<ScorerDefinition>;
+    readonly specs: Registry<SpecDefinition>;
+    readonly approvalTypes: Registry<ApprovalTypeDefinition>;
+    readonly channels: Registry<ActionChannel>;
+    readonly records: AppRecords;
+    readonly activity: AppActivity;
+    readonly tasks: AppTasks;
+    readonly labels: AppLabels;
+    readonly outcomes: AppOutcomes;
+    readonly scores: AppScores;
+    readonly resolution: AppResolution;
+    /** Keyed by `path`, not by a name: the path is what a workspace link points at. */
+    readonly pages: Registry<PageDefinition>;
+    readonly schedules: AppSchedules;
+    /** Paths and nav items for the workspace the template renders. */
+    readonly workspace: AppWorkspace;
+    /** Hands the app the handles every control-plane operation below runs on. */
+    attach(controlPlane: ControlPlane): void;
+    /** For a process that is tearing its pool down; the next call refuses rather than using it. */
+    detach(): void;
+    controlPlane(operation?: string): ControlPlane;
+    runs: {
+        start<I>(flow: Flow<I, unknown>, input: I, options?: RunsStartOptions): Promise<StartedRun>;
+    };
+    approvals: {
+        decide(options: DecideOptions): Promise<DecideResult>;
+    };
+    reconcile(options?: Partial<ReconcileOptions>): Promise<ReconcileReport>;
+    pause(options?: PauseOptions): Promise<PauseResult>;
+    resume(options?: PauseOptions): Promise<ResumeResult>;
+    status(): Promise<StatusReport>;
+    /** A `fetch` handler: the template's `app/api/status/[[...route]]/route.ts` is one line. */
+    statusHandler(request: Request): Promise<Response>;
+}
+/**
+ * The app object, and the thing that finally owns the pool and the `DBOSClient` that
+ * `reconcile()`, the bump path and `decide()` have taken as bare parameters until now. Every
+ * control-plane operation on it is the same function those chunks shipped, with the handles
+ * closed over — there is no second implementation of any of them here.
+ *
+ * Registration is module-level and the handles are not: `src/hyperfixation.ts` is imported by
+ * the web and by `worker.ts` alike, and only one of those has a control pool at import time.
+ * So `attach()` is a separate call, made once the process knows which shape it is.
+ */
+export declare function defineApp(options: DefineAppOptions): App;

package/dist/define-app.js

@@ -0,0 +1,283 @@
+import { reconcile, runsStart, decide as decideApprovals, } from "@hyperfixation/workflows";
+import { listActivity, recordActivity, } from "./activity.js";
+import { addLabel, listLabels, } from "./labels.js";
+import { listOutcomes, recordOutcome, } from "./outcomes.js";
+import { pauseApp, resumeApp } from "./pause.js";
+import { archiveRecord, assertRecordStages, } from "./records.js";
+import { createRegistry, UnknownRegistration } from "./registry.js";
+import { resolveBatch } from "./resolution.js";
+import { fireSchedule, schedulesDue, } from "./schedules.js";
+import { writeStepScore } from "./scores.js";
+import { createStatusHandler, STATUS_TOKEN_ACTOR } from "./status-route.js";
+import { appStatus } from "./status.js";
+import { cancelTask, completeTask, createManualTask, createTask, listTasks, } from "./tasks.js";
+import { workspaceNav, workspaceRoute, } from "./workspace.js";
+import { workspaceBoard, workspaceHome, workspaceInbox, workspaceRecord, } from "./workspace-views.js";
+export class AppNotAttached extends Error {
+    operation;
+    constructor(operation) {
+        super(`AppNotAttached: ${operation} needs the app's control plane; call app.attach({ pool, client }) ` +
+            "with startWorker()'s control pool in the worker, or the web's pool and getClient() in the web");
+        this.name = "AppNotAttached";
+        this.operation = operation;
+    }
+}
+export class NoApplicationVersion extends Error {
+    constructor(operation) {
+        super(`NoApplicationVersion: ${operation} needs the version this deploy runs; defineApp() reads ` +
+            "HF_BUILD_SHA, which is unset here");
+        this.name = "NoApplicationVersion";
+    }
+}
+/**
+ * The app object, and the thing that finally owns the pool and the `DBOSClient` that
+ * `reconcile()`, the bump path and `decide()` have taken as bare parameters until now. Every
+ * control-plane operation on it is the same function those chunks shipped, with the handles
+ * closed over — there is no second implementation of any of them here.
+ *
+ * Registration is module-level and the handles are not: `src/hyperfixation.ts` is imported by
+ * the web and by `worker.ts` alike, and only one of those has a control pool at import time.
+ * So `attach()` is a separate call, made once the process knows which shape it is.
+ */
+export function defineApp(options) {
+    const applicationVersion = options.applicationVersion ?? process.env.HF_BUILD_SHA;
+    const flows = createRegistry("flow");
+    const sources = createRegistry("source");
+    const resolvers = createRegistry("resolver");
+    const scorers = createRegistry("scorer");
+    const specs = createRegistry("spec");
+    const approvalTypes = createRegistry("approval type");
+    const channels = createRegistry("channel");
+    const recordTypes = createRegistry("record type", (entry) => entry.recordType);
+    const pages = createRegistry("page", (entry) => entry.path);
+    // `Object.assign` rather than a spread: the registry's `size` is a getter, and a spread would
+    // copy today's count instead of it.
+    const schedules = Object.assign(createRegistry("schedule"), {
+        async fire(name) {
+            const { pool } = controlPlane("schedules.fire");
+            return fireSchedule(pool, schedules.require(name), (flow, input) => app.runs.start(flow, input));
+        },
+        due(now, lastFired) {
+            return schedulesDue(schedules.all(), now, lastFired);
+        },
+    });
+    for (const flow of options.flows ?? [])
+        flows.register(flow);
+    for (const source of options.sources ?? [])
+        sources.register(source);
+    for (const resolver of options.resolvers ?? [])
+        resolvers.register(resolver);
+    for (const spec of options.specs ?? [])
+        specs.register(spec);
+    for (const scorer of options.scorers ?? [])
+        scorers.register(scorer);
+    for (const type of options.approvalTypes ?? [])
+        approvalTypes.register(type);
+    for (const channel of options.channels ?? [])
+        channels.register(channel);
+    for (const record of options.records ?? []) {
+        assertRecordStages(record);
+        recordTypes.register(record);
+    }
+    for (const page of options.pages ?? [])
+        pages.register(page);
+    for (const schedule of options.schedules ?? [])
+        schedules.register(schedule);
+    // Cross-registry, so after every registration: a scorer whose spec is unregistered would
+    // write `spec_version` rows nothing can explain, and a schedule whose flow is unregistered
+    // would refuse at its first firing rather than at boot.
+    for (const scorer of scorers.all()) {
+        if (!specs.has(scorer.spec.name)) {
+            throw new UnknownRegistration("spec", scorer.spec.name, specs.names());
+        }
+    }
+    for (const schedule of schedules.all()) {
+        if (!flows.has(schedule.flow.name)) {
+            throw new UnknownRegistration("flow", schedule.flow.name, flows.names());
+        }
+    }
+    let attached;
+    const controlPlane = (operation = "this operation") => {
+        if (attached === undefined)
+            throw new AppNotAttached(operation);
+        return attached;
+    };
+    const versionFor = (operation) => {
+        if (applicationVersion === undefined)
+            throw new NoApplicationVersion(operation);
+        return applicationVersion;
+    };
+    const workspaceRegistries = { records: recordTypes, pages };
+    const viewDeps = (operation) => ({
+        pool: controlPlane(operation).pool,
+        records: recordTypes,
+        hasSchema: (type) => approvalTypes.get(type)?.schema !== undefined,
+    });
+    const app = {
+        name: options.name,
+        applicationVersion,
+        flows,
+        sources,
+        resolvers,
+        scorers,
+        specs,
+        approvalTypes,
+        channels,
+        pages,
+        schedules,
+        workspace: {
+            route: (path) => workspaceRoute(workspaceRegistries, path),
+            nav: () => workspaceNav(workspaceRegistries),
+            async inbox(inboxOptions) {
+                return workspaceInbox(viewDeps("workspace.inbox"), inboxOptions);
+            },
+            async home(homeOptions) {
+                return workspaceHome(viewDeps("workspace.home"), homeOptions);
+            },
+            async board(recordType, boardOptions) {
+                return workspaceBoard(viewDeps("workspace.board"), recordType, boardOptions);
+            },
+            async record(recordType, id) {
+                return workspaceRecord(viewDeps("workspace.record"), recordType, id);
+            },
+            // The one workspace write, and no second implementation of it: the web's decision is
+            // `decide()`'s, with the `via` the session already fixes.
+            decide: (decideOptions) => app.approvals.decide({ ...decideOptions, via: "web" }),
+        },
+        records: {
+            types: recordTypes,
+            async archive(archiveOptions) {
+                const { pool, client } = controlPlane("records.archive");
+                return archiveRecord(pool, client, recordTypes, archiveOptions);
+            },
+        },
+        activity: {
+            // No `controlPlane()`: a step-side write runs on the step pool `ctx.tx` already holds.
+            record: (ctx, recordOptions) => recordActivity(ctx, recordOptions),
+            async list(listOptions) {
+                const { pool } = controlPlane("activity.list");
+                return listActivity(pool, listOptions);
+            },
+        },
+        tasks: {
+            create: (ctx, createOptions) => createTask(ctx, recordTypes, createOptions),
+            async createManual(createOptions) {
+                const { pool } = controlPlane("tasks.createManual");
+                return createManualTask(pool, recordTypes, createOptions);
+            },
+            async complete(closeOptions) {
+                const { pool } = controlPlane("tasks.complete");
+                return completeTask(pool, closeOptions);
+            },
+            async cancel(closeOptions) {
+                const { pool } = controlPlane("tasks.cancel");
+                return cancelTask(pool, closeOptions);
+            },
+            async list(listOptions = {}) {
+                const { pool } = controlPlane("tasks.list");
+                return listTasks(pool, listOptions);
+            },
+        },
+        labels: {
+            async add(addOptions) {
+                const { pool } = controlPlane("labels.add");
+                return addLabel(pool, recordTypes, addOptions);
+            },
+            async list(listOptions) {
+                const { pool } = controlPlane("labels.list");
+                return listLabels(pool, listOptions);
+            },
+        },
+        outcomes: {
+            async record(outcomeOptions) {
+                const { pool } = controlPlane("outcomes.record");
+                return recordOutcome(pool, recordTypes, outcomeOptions);
+            },
+            async list(listOptions) {
+                const { pool } = controlPlane("outcomes.list");
+                return listOutcomes(pool, listOptions);
+            },
+        },
+        scores: {
+            write: (ctx, writeOptions) => writeStepScore(ctx, recordTypes, writeOptions),
+        },
+        resolution: {
+            batch(tx, batchOptions) {
+                const resolver = resolvers.require(batchOptions.resolver);
+                return resolveBatch(tx, {
+                    resolver,
+                    table: recordTypes.require(resolver.recordType).table,
+                    source: batchOptions.source,
+                    limit: batchOptions.limit,
+                    maxAttempts: batchOptions.maxAttempts,
+                });
+            },
+        },
+        attach(next) {
+            attached = next;
+        },
+        detach() {
+            attached = undefined;
+        },
+        controlPlane,
+        runs: {
+            async start(flow, input, startOptions) {
+                const { pool, client } = controlPlane("runs.start");
+                // A flow the app never registered has no queue on this worker and would strand its run
+                // at the first bump, where the registry is the only source of a queue name.
+                if (!flows.has(flow.name)) {
+                    throw new UnknownRegistration("flow", flow.name, flows.names());
+                }
+                return runsStart(pool, client, flow, input, startOptions);
+            },
+        },
+        approvals: {
+            async decide(decideOptions) {
+                const { pool, client } = controlPlane("approvals.decide");
+                return decideApprovals(pool, client, {
+                    schemaFor: (type) => approvalTypes.get(type)?.schema,
+                    ...decideOptions,
+                });
+            },
+        },
+        async reconcile(reconcileOptions = {}) {
+            const { pool, client } = controlPlane("reconcile");
+            return reconcile(pool, client, {
+                applicationVersion: reconcileOptions.applicationVersion ?? versionFor("reconcile"),
+                ...(reconcileOptions.lockTimeout === undefined
+                    ? {}
+                    : { lockTimeout: reconcileOptions.lockTimeout }),
+            });
+        },
+        async pause(pauseOptions = {}) {
+            const { pool, client } = controlPlane("app.pause");
+            return pauseApp(pool, client, pauseOptions);
+        },
+        async resume(resumeOptions = {}) {
+            const { pool, client } = controlPlane("app.resume");
+            return resumeApp(pool, client, {
+                ...resumeOptions,
+                applicationVersion: versionFor("app.resume"),
+            });
+        },
+        async status() {
+            const { pool } = controlPlane("app.status");
+            return appStatus(pool, { app: options.name, applicationVersion: applicationVersion ?? null });
+        },
+        async statusHandler(request) {
+            const { pool } = controlPlane("app.statusHandler");
+            return createStatusHandler({
+                pool,
+                app: options.name,
+                applicationVersion: applicationVersion ?? null,
+                handlers: {
+                    status: () => app.status(),
+                    // The actor is the write token, not a session: nothing else authenticated the call.
+                    pause: () => app.pause({ userId: STATUS_TOKEN_ACTOR }),
+                    resume: () => app.resume({ userId: STATUS_TOKEN_ACTOR }),
+                },
+            })(request);
+        },
+    };
+    return app;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { defineApp, AppNotAttached, NoApplicationVersion, type AnyFlow, type App, type AppActivity, type AppLabels, type AppOutcomes, type AppRecords, type AppResolution, type AppResolutionBatchOptions, type AppSchedules, type AppScores, type AppTasks, type ApprovalTypeDefinition, type ControlPlane, type DefineAppOptions, } from "./define-app.js";
+export { createRegistry, DuplicateRegistration, InvalidDefinition, UnknownRegistration, type Registry, } from "./registry.js";
+export { defineSource, type SourceDefinition, type SourceRow } from "./sources.js";
+export { defineResolver, type ResolverDefinition, type ResolverFuzzy } from "./resolvers.js";
+export { bigramDice, fuzzyCandidateStatement, resolveBatch, DEFAULT_RESOLVE_LIMIT, DEFAULT_RESOLVE_MAX_ATTEMPTS, FUZZY_CANDIDATE_LIMIT, type ResolveBatchOptions, type ResolveBatchResult, } from "./resolution.js";
+export { defineSpec, type SpecDefinition } from "./specs.js";
+export { defineScorer, type Scored, type ScorerDefinition } from "./scorers.js";
+export type { PageDefinition } from "./pages.js";
+export { defineSchedule, fireSchedule, schedulesDue, type AnySchedule, type ScheduleDefinition, type ScheduleFired, } from "./schedules.js";
+export { latestScores, writeScore, writeStepScore, EXISTING_SCORE_STATEMENT, LATEST_SCORES_STATEMENT, WRITE_SCORE_STATEMENT, type LatestScoreRow, type LatestScoresOptions, type ScoreWritten, type StepWriteScoreOptions, type WriteScoreOptions, } from "./scores.js";
+export { assertActivityKind, insertActivity, listActivity, recordActivity, InvalidActivityKind, ACTIVITY_KIND_PATTERN, ACTIVITY_LIST_OPERATION, EXISTING_ACTIVITY_STATEMENT, INSERT_ACTIVITY_STATEMENT, type ActivityListOptions, type ActivityRecordOptions, type ActivityRecorded, type ActivityRow, type ActivityWrite, } from "./activity.js";
+export { cancelOpenTasksForRecord, cancelTask, completeTask, createManualTask, createTask, flowOriginRef, listTasks, TASK_CANCEL_OPERATION, TASK_COMPLETE_OPERATION, TASK_CREATE_MANUAL_OPERATION, TASK_LIST_OPERATION, type TaskCloseOptions, type TaskClosed, type TaskCreateManualOptions, type TaskCreateOptions, type TaskCreated, type TaskListOptions, type TaskRow, type TaskTarget, } from "./tasks.js";
+export { addLabel, listLabels, LABEL_ADD_OPERATION, LABEL_LIST_OPERATION, type LabelAddOptions, type LabelListOptions, type LabelRow, } from "./labels.js";
+export { listOutcomes, recordOutcome, OUTCOME_LIST_OPERATION, OUTCOME_RECORD_OPERATION, type OutcomeListOptions, type OutcomeRecordOptions, type OutcomeRow, } from "./outcomes.js";
+export { pauseApp, resumeApp, PAUSED_MARKER, PAUSE_OPERATION, RESUMED_MARKER, RESUME_OPERATION, type PauseOptions, type PauseResult, type ResumeOptions, type ResumeResult, } from "./pause.js";
+export { archiveRecord, archiveDecisionKey, assertRecordStages, displayColumnOf, ARCHIVED_MARKER, ARCHIVE_OPERATION, DEFAULT_DISPLAY_COLUMN, type ArchiveOptions, type ArchiveResult, type RecordDefinition, type StageDefinition, } from "./records.js";
+export { appStatus, CORE_VERSION, type PeriodStatus, type QueueStatus, type StatusOptions, type StatusReport, } from "./status.js";
+export { createStatusHandler, statusRouteOf, STATUS_TOKEN_ACTOR, type StatusHandlerOptions, type StatusRoute, type StatusRouteHandlers, } from "./status-route.js";
+export { bearerToken, hashStatusToken, statusTokenMatches, STATUS_TOKEN_DIGEST, } from "./status-token.js";
+/**
+ * The workspace's types only — its functions are `@hyperfixation/core/workspace`. They are here
+ * because `App.workspace` names them.
+ */
+export type { AppWorkspace, DraftField, WorkspaceNavItem, WorkspaceRegistries, WorkspaceRoute, } from "./workspace.js";
+export { workspaceBoard, workspaceHome, workspaceInbox, workspaceRecord, DEFAULT_BOARD_LIMIT, WORKSPACE_BOARD_OPERATION, WORKSPACE_HOME_OPERATION, WORKSPACE_INBOX_OPERATION, WORKSPACE_RECORD_OPERATION, type BoardCard, type BoardColumn, type BoardOptions, type BoardView, type HomeOptions, type HomeView, type InboxItem, type InboxOptions, type InboxView, type RecordView, type ReviewQueueCount, type TimelineGroup, type WorkspaceDecideOptions, type WorkspaceViewDeps, type WorkspaceViews, } from "./workspace-views.js";