@hyperfixation/workflows 0.1.0

package/dist/index.js

@@ -0,0 +1,16 @@
+export { startWorker, MissingBuildSha, NotAWorkerProcess, DRAIN_TIMEOUT_MS, LAUNCHED_MARKER, LAUNCHING_MARKER, MIN_BUILD_SHA_LENGTH, QUEUES, RECONCILER_POOL_SIZE, SHUTDOWN_FAILED_MARKER, SHUTDOWN_IGNORED_MARKER, SHUTDOWN_MARKER, SHUTDOWN_WATCHDOG_MS, SYSTEM_DATABASE_POOL_SIZE, SYSTEM_DATABASE_SCHEMA, WORKER_PROCESS, } from "./start-worker.js";
+export { registerLangfuse, LANGFUSE_ENV } from "./langfuse.js";
+export { getClient, resetClient, CLIENT_POOL_SIZE } from "./client.js";
+export { setPausedQueueConcurrency, PAUSED_CONCURRENCY, PAUSED_QUEUES, } from "./queue-concurrency.js";
+export { WorkerLockUnavailable, LOCK_ACQUIRED_MARKER } from "./worker-lock.js";
+export { defineFlow, definedFlows, DuplicateFlow, UnknownQueue, SUPERSEDED_MARKER, } from "./define-flow.js";
+export { step, STEP_GATE_STATEMENT } from "./step.js";
+export { actions, perform, idempotencyKey, stubChannel, ActionUncertain, } from "./actions.js";
+export { approvals, decide, waitForApproval, ApprovalBatchRefused, ApprovalRunMoved, ApprovalWriteLost, APPROVAL_DECISIONS, DECIDE_OPERATION, } from "./approvals.js";
+export { createApprovalNotifier, NO_RECIPIENTS_MARKER, } from "./approval-notifier.js";
+export { handleTelegramCallback, encodeCallbackData, decodeCallbackData, decisionKeyFor, maxNonceLength, CallbackDataTooLong, CALLBACK_DATA_MAX_BYTES, CALLBACK_DATA_VERSION, } from "./telegram.js";
+export { UnknownFlow } from "./bump.js";
+export { Suspend, SUSPEND_STATUSES } from "./suspend.js";
+export { currentRun, OutsideRun } from "./run-context.js";
+export { runsStart, START_RUN_STATEMENT } from "./runs.js";
+export { reconcile, startReconciler, sweepDecisionKey, ABANDON_LLM_CALLS_STATEMENT, DRIFT_STATEMENT, EXPIRED_APPROVALS_STATEMENT, PAUSED_RUNS_STATEMENT, RECONCILE_ACTION_MARKER, RECONCILE_ANOMALY_MARKER, RECONCILE_FAILED_MARKER, RECONCILE_INTERVAL_MS, RECONCILE_PASS_MARKER, RECONCILE_QUEUE_MARKER, RUNNING_RUNS_STATEMENT, UNCERTAIN_ACTIONS_STATEMENT, } from "./reconcile.js";

package/dist/langfuse.d.ts

@@ -0,0 +1,16 @@
+/** The three variables `LangfuseSpanProcessor` reads for itself; all three or nothing. */
+export declare const LANGFUSE_ENV: readonly ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_BASE_URL"];
+export interface LangfuseRegistration {
+    /** Flushes the batch. Called from the SIGTERM handler before the process exits. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Registers the process-wide tracer provider Langfuse exports through, or nothing when the keys
+ * are absent — in which case `trace.getTracer()` stays the no-op proxy and every span the AI
+ * SDK and DBOS would create costs nothing.
+ *
+ * `register()` also installs the async-hooks context manager, which is what lets a `gen_ai` span
+ * inherit the DBOS step span's trace id; DBOS's own installer then sees a working context and
+ * leaves ours alone. Exported so the web's `instrumentation.ts` registers the same way.
+ */
+export declare function registerLangfuse(env?: NodeJS.ProcessEnv): LangfuseRegistration | undefined;

package/dist/langfuse.js

@@ -0,0 +1,24 @@
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+/** The three variables `LangfuseSpanProcessor` reads for itself; all three or nothing. */
+export const LANGFUSE_ENV = [
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+    "LANGFUSE_BASE_URL",
+];
+/**
+ * Registers the process-wide tracer provider Langfuse exports through, or nothing when the keys
+ * are absent — in which case `trace.getTracer()` stays the no-op proxy and every span the AI
+ * SDK and DBOS would create costs nothing.
+ *
+ * `register()` also installs the async-hooks context manager, which is what lets a `gen_ai` span
+ * inherit the DBOS step span's trace id; DBOS's own installer then sees a working context and
+ * leaves ours alone. Exported so the web's `instrumentation.ts` registers the same way.
+ */
+export function registerLangfuse(env = process.env) {
+    if (LANGFUSE_ENV.some((name) => (env[name] ?? "") === ""))
+        return undefined;
+    const provider = new NodeTracerProvider({ spanProcessors: [new LangfuseSpanProcessor()] });
+    provider.register();
+    return { shutdown: () => provider.shutdown() };
+}

package/dist/queue-concurrency.d.ts

@@ -0,0 +1,32 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type QueueName } from "./start-worker.js";
+/**
+ * The queues `pause` stops. `resolve` is deliberately not one of them: the plan names `llm` and
+ * `actions`, the two that spend money and reach the outside world, and a resolution batch is
+ * stopped by the step gate at its next step like everything else.
+ */
+export declare const PAUSED_QUEUES: readonly ["llm", "actions"];
+export interface QueueConcurrency {
+    name: QueueName;
+    globalConcurrency: number;
+    /**
+     * False when no `dbos.queues` row exists yet — no worker has launched — so the concurrency
+     * could not be written. The pause itself still stands: `hf_app_state.paused` is what a step
+     * reads, and `startWorker()` re-applies the zero on the way up.
+     */
+    applied: boolean;
+}
+/** What `pause` sets the two queues to. Zero means the dequeue claims nothing at all. */
+export declare const PAUSED_CONCURRENCY = 0;
+/** What a resume — and `reconcile()`'s step (6) — puts a queue back to. */
+export declare function registeredConcurrency(name: QueueName): number;
+/**
+ * Sets `llm` and `actions` to zero, or back to their registered concurrency. The queues are
+ * database-backed (`DBOS.registerQueue` persists them), so a worker in another process picks
+ * the change up on its next reconcile of the queues table — this is callable from the web.
+ *
+ * It is the *second* half of a pause and the *first* half of a resume in both cases: the
+ * correctness mechanism is the pause flag the step gate reads, and this only stops work from
+ * being dispatched that the gate would immediately suspend.
+ */
+export declare function setPausedQueueConcurrency(client: DBOSClient, paused: boolean): Promise<QueueConcurrency[]>;

package/dist/queue-concurrency.js

@@ -0,0 +1,36 @@
+import { QUEUES } from "./start-worker.js";
+/**
+ * The queues `pause` stops. `resolve` is deliberately not one of them: the plan names `llm` and
+ * `actions`, the two that spend money and reach the outside world, and a resolution batch is
+ * stopped by the step gate at its next step like everything else.
+ */
+export const PAUSED_QUEUES = ["llm", "actions"];
+/** What `pause` sets the two queues to. Zero means the dequeue claims nothing at all. */
+export const PAUSED_CONCURRENCY = 0;
+/** What a resume — and `reconcile()`'s step (6) — puts a queue back to. */
+export function registeredConcurrency(name) {
+    return QUEUES.find((queue) => queue.name === name).globalConcurrency;
+}
+/**
+ * Sets `llm` and `actions` to zero, or back to their registered concurrency. The queues are
+ * database-backed (`DBOS.registerQueue` persists them), so a worker in another process picks
+ * the change up on its next reconcile of the queues table — this is callable from the web.
+ *
+ * It is the *second* half of a pause and the *first* half of a resume in both cases: the
+ * correctness mechanism is the pause flag the step gate reads, and this only stops work from
+ * being dispatched that the gate would immediately suspend.
+ */
+export async function setPausedQueueConcurrency(client, paused) {
+    const applied = [];
+    for (const name of PAUSED_QUEUES) {
+        const globalConcurrency = paused ? PAUSED_CONCURRENCY : registeredConcurrency(name);
+        const queue = await client.retrieveQueue(name);
+        if (queue === null) {
+            applied.push({ name, globalConcurrency, applied: false });
+            continue;
+        }
+        await queue.setGlobalConcurrency(globalConcurrency);
+        applied.push({ name, globalConcurrency, applied: true });
+    }
+    return applied;
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,157 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import type { Pool } from "pg";
+import type { QueueName } from "./start-worker.js";
+/** How often the worker runs a pass after the one it runs at boot. */
+export declare const RECONCILE_INTERVAL_MS = 60000;
+/**
+ * A `running` run whose `current_workflow_id` has no `dbos.workflow_status` row at all. Every
+ * path that writes the column enqueues in the same transaction, so this cannot happen — it is
+ * logged at error and counted rather than swallowed, and the attempt is enqueued anyway.
+ */
+export declare const RECONCILE_ANOMALY_MARKER = "hf-reconcile: a running run has no workflow row";
+/** One line per run a pass could not finish; the pass carries on with the others. */
+export declare const RECONCILE_FAILED_MARKER = "hf-reconcile: run refused";
+/**
+ * One line per run a pass moved, carrying the `run_id`. The pass summary alone would make a
+ * redeploy that moved a whole backlog a single number, with no way back to which run went where.
+ */
+export declare const RECONCILE_ACTION_MARKER = "hf-reconcile: run moved";
+/**
+ * One line per queue a pass re-derived from `hf_app_state.paused`, carrying both concurrencies.
+ * Its own marker rather than the action one: nothing about it is a run, and a stall this fixed
+ * is diagnosed by reading which direction it went.
+ */
+export declare const RECONCILE_QUEUE_MARKER = "hf-reconcile: queue concurrency corrected";
+/** One line per pass, carrying the report. */
+export declare const RECONCILE_PASS_MARKER = "hf-reconcile: pass";
+/**
+ * The drift scan. `reconcile()` reports it and never corrects it: correcting a counter is how
+ * round-2 finding 3 happened, and per-period drift is exact because a call is billed to the
+ * period stamped on its own row.
+ */
+export declare const DRIFT_STATEMENT: string;
+/**
+ * Step (1)'s scan. A plain `SELECT`, joined against `dbos.workflow_status` rather than asking
+ * the SDK per run: one statement for the whole scan, and the application role reads that table
+ * under the grants E006 checks.
+ */
+export declare const RUNNING_RUNS_STATEMENT: string;
+/** Step (3)'s scan: runs parked by a pause the app has since come out of. */
+export declare const PAUSED_RUNS_STATEMENT: string;
+/**
+ * Step (4), ledger half. Round 3 widened the predicate twice over round 2: to `running` runs'
+ * non-current rows, and to every row on a `waiting`/`paused` run, whose current workflow has
+ * ended so nothing can still be in flight. Idempotent because the predicate is the status.
+ *
+ * Hygiene and audit, not budget correctness — none of these rows reserves anything by the time
+ * this runs, because the reservation only ever counts rows whose `workflow_id` is still their
+ * run's `current_workflow_id` on a `running` run.
+ */
+export declare const ABANDON_LLM_CALLS_STATEMENT: string;
+/**
+ * Step (4), actions half: the same predicate, into the status that already means this. The
+ * `RETURNING` is what makes "one task per uncertain row, once" fall out of the status predicate —
+ * a row this pass moved is never returned by the next one.
+ */
+export declare const UNCERTAIN_ACTIONS_STATEMENT: string;
+/**
+ * Step (5)'s scan. A plain `SELECT`: `decide()` locks what it decides, and an approval this
+ * scan read a moment before someone decided it is simply not pending any more by then.
+ */
+export declare const EXPIRED_APPROVALS_STATEMENT: string;
+export interface ReconcileOptions {
+    /** The version this worker runs; an attempt under any other one is dead. */
+    applicationVersion: string;
+    /** A Postgres interval literal handed to every transaction of the pass. */
+    lockTimeout?: string;
+}
+export interface Reattempted {
+    runId: string;
+    attempt: number;
+    workflowId: string;
+    /** What the previous attempt was doing when the pass found it. */
+    reason: "dead-version" | "cancelled" | "resumed";
+}
+export interface Concluded {
+    runId: string;
+    status: "done" | "failed";
+    dbosStatus: string;
+}
+export interface ReconcileAnomaly {
+    runId: string;
+    workflowId: string;
+    /** False when the enqueue itself was refused; the anomaly is counted either way. */
+    enqueued: boolean;
+}
+export interface ReconcileFailure {
+    /** Null on a failure no run owns; step (6)'s subject is the app's queues, not a run. */
+    runId: string | null;
+    step: "reattempt" | "conclude" | "resume" | "anomaly" | "expire" | "queues";
+    error: string;
+}
+export interface ExpiredApproval {
+    approvalId: number;
+    runId: string;
+    /** The attempt `decide()` enqueued to tell the run its approval expired. */
+    workflowId: string;
+}
+export interface QueueConcurrencyCorrection {
+    name: QueueName;
+    /** `hf_app_state.paused` as this pass read it, which is what the correction was against. */
+    paused: boolean;
+    /** What the queue's row said before the pass wrote it; `null` is a registered no-limit. */
+    was: number | null;
+    now: number;
+}
+export interface PeriodDrift {
+    period: string;
+    spentUsd: string;
+    ledgerUsd: string;
+    driftUsd: string;
+}
+export interface ReconcileReport {
+    reattempted: Reattempted[];
+    concluded: Concluded[];
+    anomalies: ReconcileAnomaly[];
+    abandonedLlmCalls: number;
+    uncertainActions: number;
+    expired: ExpiredApproval[];
+    queueConcurrency: QueueConcurrencyCorrection[];
+    drift: PeriodDrift[];
+    failures: ReconcileFailure[];
+}
+/**
+ * The app-level half of a redeploy: DBOS's own recovery is version- and executor-scoped, so an
+ * old version's workflows are never touched by a new worker. This is what moves those runs on.
+ *
+ * A control-plane operation — control pool, `assertNotInWorkflow()`, every transaction through
+ * the tag-asserting helper — and it **never locks `hf_budget_period`**: its drift read is a
+ * plain `SELECT`, which is what keeps the lock order `hf_run → hf_budget_period → ledger` free
+ * of a cycle (round-3 finding 8).
+ *
+ * One run's refusal never ends the pass: the runs are independent, and a pass that stopped at
+ * the first one would leave the rest of a backlog stranded until the defect was fixed.
+ *
+ * Steps (1), (3), (4), (5) and (6) and the drift read; step (2) is deleted, not re-predicated —
+ * the enqueue is in the bump's own transaction, so there is no commit-to-enqueue window to
+ * backstop.
+ */
+export declare function reconcile(pool: Pool, dbosClient: DBOSClient, options: ReconcileOptions): Promise<ReconcileReport>;
+/** Stable across passes, so a re-decided row is a replay rather than a second decision. */
+export declare function sweepDecisionKey(approvalId: number): string;
+export interface Reconciler {
+    /** Stops the interval; the pass already in flight is left to finish. */
+    stop(): void;
+}
+/**
+ * The every-minute schedule. A plain timer rather than a DBOS scheduled workflow: DBOS's
+ * scheduler runs its functions *as workflows*, and `reconcile()` is a control-plane operation
+ * that `assertNotInWorkflow()` refuses from inside one (round-3 finding 2).
+ *
+ * Passes never overlap — a pass that outruns the interval would have two reconcilers bumping
+ * the same backlog — and a failed pass is logged, never thrown: there is no caller left to
+ * throw to, and the next pass reconciles whatever this one did not.
+ */
+export declare function startReconciler(pool: Pool, dbosClient: DBOSClient, options: ReconcileOptions & {
+    intervalMs?: number;
+}): Reconciler;