@forgezero/runtime 0.1.0 → 0.1.2

package/dist/outbox.d.ts

@@ -47,6 +47,8 @@ export declare class OutboxError extends Error {
 export declare const EVENT_STATES: readonly ["pending", "delivering", "delivered", "dead"];
 export type EventState = (typeof EVENT_STATES)[number];
 export interface OutboxEvent {
+    /** Set when a drainer claims it; proves ownership at settle time. */
+    claimToken?: string;
     id: string;
     type: string;
     /** The aggregate this concerns. Events sharing one are delivered in order. */
@@ -134,7 +136,14 @@ export interface OutboxStore {
         nowMs: number;
         claimTtlMs: number;
     }): Promise<OutboxEvent[]>;
-    settle(id: string, patch: Partial<OutboxEvent>): Promise<void>;
+    /**
+     * `claimToken` proves the caller still owns this event.
+     *
+     * Without it a drainer whose lease had expired could overwrite the result of
+     * the drainer that took over, landing an old outcome on top of a newer one.
+     * Optional so an in-memory store that cannot lose ownership need not carry it.
+     */
+    settle(id: string, patch: Partial<OutboxEvent>, claimToken?: string): Promise<void>;
     byState(state: EventState, limit?: number): Promise<OutboxEvent[]>;
     get(id: string): Promise<OutboxEvent | null>;
 }

package/dist/outbox.js

@@ -27,13 +27,18 @@ function backoffMs(attempts, policy = DEFAULT_POLICY, random = Math.random) {
   const exponential = Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempts - 1), policy.maxDelayMs);
   return Math.round(exponential * (1 + policy.jitter * random()));
 }
+function randomSuffix() {
+  const bytes = new Uint8Array(4);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 function createOutbox(options) {
   const policy = { ...DEFAULT_POLICY, ...options.policy };
   const now = options.now ?? Date.now;
   const random = options.random ?? Math.random;
   const drainerId = options.drainerId ?? `drainer-${Math.floor(Math.random() * 1e9).toString(36)}`;
   let sequence = 0;
-  const nextId = () => `evt_${now().toString(36)}_${(sequence += 1).toString(36)}`;
+  const nextId = () => `evt_${now().toString(36)}_${(sequence += 1).toString(36)}_${randomSuffix()}`;
   async function settleOne(event) {
     let result;
     try {
@@ -47,7 +52,7 @@ function createOutbox(options) {
         deliveredAtMs: now(),
         claimedBy: undefined,
         claimedUntilMs: undefined
-      });
+      }, event.claimToken);
       return "delivered";
     }
     const attempts = event.attempts + 1;
@@ -67,7 +72,7 @@ function createOutbox(options) {
         lastError: result.error,
         claimedBy: undefined,
         claimedUntilMs: undefined
-      });
+      }, event.claimToken);
       options.onDeadLetter?.(dead);
       return "dead";
     }

package/dist/pipeline.d.ts

@@ -1,11 +1,12 @@
 /**
- * Deciding whether a push should cause a deploy, and what that deploy is.
+ * Deciding whether a push should cause a deploy.
  *
  * A webhook receiver is a public endpoint that runs commands on your machines
  * when something posts to it. Everything worth getting right is in the gap
- * between those two facts, so this module holds the decisions and none of the
- * doing: no network, no shell, no clone. What it produces is a PLAN, and
- * something else carries it out.
+ * between those two facts, so this module holds trigger verification and none
+ * of the doing: no network, no shell, no clone, and no executable plan. The
+ * agent later reads the only deployment definition from the exact checked-out
+ * commit.
  *
  * That split is not tidiness. It means the interesting cases — a forged
  * signature, a push to a branch nobody deploys, two pushes racing, a repository
@@ -21,8 +22,8 @@
  * matters when reading logs during an incident.
  */
 export declare class PipelineError extends Error {
-    readonly code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'WRONG_REPOSITORY' | 'NO_SECRET';
-    constructor(code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'WRONG_REPOSITORY' | 'NO_SECRET', message: string);
+    readonly code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'NO_SECRET';
+    constructor(code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'NO_SECRET', message: string);
 }
 export declare const GIT_PROVIDERS: readonly ["github", "gitlab", "generic"];
 export type GitProvider = (typeof GIT_PROVIDERS)[number];
@@ -73,50 +74,23 @@ export interface PushEvent {
  * failure every time somebody opened an issue.
  */
 export declare function parsePush(provider: GitProvider, body: unknown): PushEvent | null;
-export interface PipelineConfig {
+export interface DeployTrigger {
     provider: GitProvider;
     /** `owner/name`. Compared against the delivery. */
     repository: string;
     /** Only this branch deploys. One branch per pipeline, deliberately. */
     branch: string;
-    /** Where the checkout lives on the compute. */
-    workdir: string;
-    /** Shell steps, in order. Empty means clone only. */
-    steps: readonly string[];
-    cloneUrl: string;
 }
-export declare const PLAN_ACTIONS: readonly ["clone", "fetch", "checkout", "run"];
-export type PlanAction = (typeof PLAN_ACTIONS)[number];
-export interface PlanStep {
-    action: PlanAction;
-    command: string;
-    /** Shown to an operator. Never contains a credential. */
-    label: string;
-}
-/**
- * The commands that would deploy this push, in order.
- *
- * `clone` and `fetch` are both emitted, guarded on the directory existing,
- * because a runner cannot know in advance whether the first deploy has
- * happened — and branching on that in the caller means two code paths where one
- * of them is exercised once per compute, ever.
- *
- * The commit is checked out by SHA rather than by branch. A branch moves: a
- * deploy that fetched and then checked out `main` could deploy a commit that
- * arrived after the one that triggered it, so the thing tested is not the thing
- * shipped. The SHA is what the webhook said, so what deploys is what fired.
- */
-export declare function planDeploy(config: PipelineConfig, event: PushEvent): PlanStep[];
 /**
  * Should this delivery deploy at all?
  *
- * Separate from `planDeploy` so "we received it and deliberately did nothing"
- * is a first-class outcome with a reason attached. A receiver that silently
+ * "We received it and deliberately did nothing" is a first-class outcome with
+ * a reason attached. A receiver that silently
  * ignored non-matching branches would be indistinguishable from one that is
  * broken, and the first question during an incident is always whether the hook
  * arrived.
  */
-export declare function shouldDeploy(config: PipelineConfig, event: PushEvent | null): {
+export declare function shouldDeploy(config: Pick<DeployTrigger, 'repository' | 'branch'>, event: PushEvent | null): {
     deploy: boolean;
     reason: string;
 };

package/dist/pipeline.js

@@ -72,31 +72,6 @@ function parsePush(provider, body) {
     message: typeof payload.head_commit?.message === "string" ? String(payload.head_commit.message) : undefined
   };
 }
-var PLAN_ACTIONS = ["clone", "fetch", "checkout", "run"];
-function planDeploy(config, event) {
-  if (event.repository !== config.repository) {
-    throw new PipelineError("WRONG_REPOSITORY", `That delivery is for ${event.repository}, and this pipeline deploys ${config.repository}.`);
-  }
-  const dir = config.workdir;
-  return [
-    {
-      action: "clone",
-      command: `[ -d ${dir}/.git ] || git clone ${config.cloneUrl} ${dir}`,
-      label: "clone if this is the first deploy"
-    },
-    { action: "fetch", command: `git -C ${dir} fetch --prune origin`, label: "fetch" },
-    {
-      action: "checkout",
-      command: `git -C ${dir} checkout --detach ${event.commit}`,
-      label: `check out ${event.commit.slice(0, 8)}`
-    },
-    ...config.steps.map((step) => ({
-      action: "run",
-      command: `cd ${dir} && ${step}`,
-      label: step
-    }))
-  ];
-}
 function shouldDeploy(config, event) {
   if (!event)
     return { deploy: false, reason: "Not a branch push — nothing to deploy." };
@@ -113,9 +88,7 @@ export {
   webhookPath,
   verifyWebhook,
   shouldDeploy,
-  planDeploy,
   parsePush,
   PipelineError,
-  PLAN_ACTIONS,
   GIT_PROVIDERS
 };

package/dist/queue.d.ts

@@ -1,243 +1,116 @@
 /**
- * A keyed work queue — parallel across keys, strictly sequential within one.
- *
- * The problem this solves is narrow and very common: most work can run in any
- * order, but some of it must not. Two credits to the same wallet, two writes to
- * the same vault entry, two deploys of the same application — each pair has to
- * happen one after the other, while everything touching a DIFFERENT wallet,
- * entry or application should run at full width.
- *
- * A global lock gives you the ordering and throws away the throughput. A plain
- * worker pool gives you the throughput and loses the ordering. The answer is to
- * partition by key: the queue is really thousands of tiny FIFOs, and a worker
- * claims a KEY rather than a message.
- *
- * ## Why claim the key, not the message
- *
- * Claiming a message and processing it is the obvious design and it does not
- * order anything: two workers can claim message 1 and message 2 of the same key
- * at the same instant and finish in either order. Claiming the KEY makes
- * ordering structural — while a worker holds `wallet:42`, nobody else can take
- * ANY message for it, so its messages can only be processed in the order they
- * were written.
- *
- * ## What this guarantees, and what it does not
- *
- * GUARANTEED   per-key FIFO order; at-least-once delivery; at most one worker
- *              per key at a time, across the whole cluster; a message that
- *              exhausts its attempts moves to a dead letter INSTEAD of blocking
- *              its key forever.
- *
- * NOT GUARANTEED   exactly-once execution. Nothing can guarantee that: a worker
- *              can complete the side effect and die before recording that it
- *              did. `dedupeKey` collapses duplicate ENQUEUES, and the lease
- *              stops concurrent delivery, but a crash between "money moved" and
- *              "message acknowledged" will redeliver.
- *
- * ## So for money, read this
- *
- * The queue is not what makes a financial operation safe — the HANDLER is. Make
- * the effect idempotent at the point of effect: a ledger posting keyed on the
- * message id and refused by a unique index, or a transfer keyed on an
- * idempotency key the payment provider also honours. Then redelivery is free
- * and the queue only has to provide ordering and durability, which it does.
- *
- * Anything that relies on "the queue delivered it once" is relying on something
- * no queue provides, including this one, including the expensive ones.
+ * Ordered work: sequential within a key, parallel across keys.
+ *
+ * That sentence is the whole contract, and the previous version buried it under
+ * a persistence framework — `QueueStore`, leases, standalone/cluster modes and
+ * an unfinished cluster adapter — that nothing in production ever used. The
+ * framework was also wrong on its own terms: a message left `leased` after its
+ * lease expired became invisible to both the claim and ready reads, so a stale
+ * lease made work unrunnable rather than runnable again.
+ *
+ * Worse for the property that matters, retry backoff did not hold the key. A
+ * task waiting to retry was skipped and a LATER task for the same key ran
+ * first, which is precisely the ordering this module exists to guarantee.
+ *
+ * So persistence is gone. The layer that knows what a pending business request
+ * means is the runtime that issued it — ForgeZero's own durability record is an
+ * Arango row written in the same transaction as the change it describes, and
+ * the outbox drains through here rather than reimplementing ordering.
+ *
+ * ## What it does guarantee
+ *
+ * - Tasks for one key run one at a time, in submission order, INCLUDING across
+ *   a retry: a task that is waiting to try again blocks its key.
+ * - Different keys run concurrently, up to `width`.
+ * - `run()` returns the handler's own value, typed, so a caller can await work
+ *   instead of polling for it.
+ * - `stop()` awaits what is running and what is queued, with a deadline, and
+ *   reports what it managed to finish.
  */
-export interface Clock {
-    now(): number;
+export interface QueueTask<T> {
+    /** Resolves with the handler's value, or rejects with its final error. */
+    readonly result: Promise<T>;
+    /** Stable id, so a caller can cancel or look up this task. */
+    readonly id: string;
+    readonly key: string;
 }
-export declare const systemClock: Clock;
-/** `30s` → 30000. Throws rather than guessing — a wrong window is silent. */
-export declare function durationMs(value: string | number): number;
-export type MessageStatus = 'ready' | 'leased' | 'done' | 'dead';
-export interface Message<Body = unknown> {
-    id: string;
-    /** The partition. Everything sharing it runs in order, one at a time. */
-    key: string;
-    body: Body;
-    /** Monotonic per queue. Decides order within a key. */
-    sequence: number;
-    status: MessageStatus;
+export interface RetryPolicy {
+    /** How many ATTEMPTS in total, including the first. */
     attempts: number;
-    /** Earliest time this may be delivered. Set by a retry backoff. */
-    availableAtMs: number;
-    /** Collapses repeat enqueues within a window. See `enqueue`. */
-    dedupeKey?: string;
-    lastError?: string;
-    enqueuedAtMs: number;
-    completedAtMs?: number;
+    /** Milliseconds before attempt n+1. Called with the 1-based attempt made. */
+    backoffMs: (attempt: number) => number;
 }
-export interface KeyLease {
-    key: string;
-    /** Rises every time the key is granted. A stale holder cannot write. */
-    fence: number;
-    untilMs: number;
-    owner: string;
+export interface QueueOptions {
+    /** How many keys may run at once. Ordering within a key is unaffected. */
+    width?: number;
+    retry?: Partial<RetryPolicy>;
+    /** Retry delay injection. Shutdown deadlines use a cancellable native timer. */
+    sleep?: (ms: number) => Promise<void>;
 }
-/**
- * Where the queue lives. Memory for tests, a database for a cluster.
- *
- * `claimKey` MUST be atomic. A read-then-write implementation hands the same key
- * to two workers under exactly the load that makes ordering matter, and the bug
- * looks like "the queue occasionally processes out of order" — which is the
- * hardest possible thing to reproduce.
- */
-export interface QueueStore<Body = unknown> {
-    /** Which deployment shape this store can serve. See `MODES`. */
-    readonly mode: QueueMode;
-    append(queue: string, message: Message<Body>): Promise<void>;
-    /** Existing message with this dedupe key, if the window has not passed. */
-    findByDedupe(queue: string, dedupeKey: string, sinceMs: number): Promise<Message<Body> | null>;
-    /**
-     * Take the next key that has ready work and is not leased. Atomic.
-     * `exclude` skips keys this worker already holds.
-     */
-    claimKey(queue: string, owner: string, ttlMs: number, nowMs: number): Promise<KeyLease | null>;
-    renewKey(queue: string, lease: KeyLease, ttlMs: number, nowMs: number): Promise<boolean>;
-    releaseKey(queue: string, lease: KeyLease): Promise<void>;
-    /** Ready messages for one key, in sequence order. */
-    readKey(queue: string, key: string, nowMs: number, limit: number): Promise<Message<Body>[]>;
-    update(queue: string, id: string, patch: Partial<Message<Body>>): Promise<void>;
-    stats(queue: string): Promise<QueueStats>;
-    /** Dead-lettered messages, newest first. */
-    dead(queue: string, limit: number): Promise<Message<Body>[]>;
+export interface DrainReport {
+    completed: number;
+    failed: number;
+    /** Still queued or running when the deadline passed. */
+    abandoned: number;
+    timedOut: boolean;
 }
-export interface QueueStats {
-    ready: number;
-    leased: number;
-    dead: number;
-    keys: number;
+export declare class QueueStoppedError extends Error {
+    constructor();
 }
-/**
- * Standalone and cluster are the same queue with a different store.
- *
- *   standalone  one process, state in memory. No coordination, nothing to
- *               install, and the ordering guarantee still holds — because a
- *               single process claiming its own keys cannot race itself.
- *               Everything is lost on restart, which is correct for a
- *               development machine and wrong for anything holding money.
- *
- *   cluster     several processes over shared storage. The guarantee is the
- *               same and the requirement is stricter: `claimKey` must be
- *               ATOMIC. A read-then-write implementation hands one key to two
- *               workers under exactly the load that makes ordering matter, and
- *               the bug presents as "the queue occasionally processes out of
- *               order" — the hardest possible thing to reproduce.
- *
- * The distinction is declared on the store rather than inferred, so a
- * deployment can refuse to start when a durable queue was expected and a memory
- * one was wired in. That mistake is otherwise invisible until a restart.
- */
-export declare const MODES: readonly ["standalone", "cluster"];
-export type QueueMode = (typeof MODES)[number];
-/**
- * Single process. Correct for tests and for one instance, and honest about
- * being no more — nothing here coordinates across processes.
- */
-export declare function memoryStore<Body = unknown>(clock?: Clock): QueueStore<Body>;
-export interface Handler<Body> {
-    (message: Message<Body>, context: HandlerContext): Promise<void>;
+export declare class QueueKeyStoppedError extends Error {
+    readonly key: string;
+    constructor(key: string);
 }
-export interface HandlerContext {
-    /** Still ours? False means the lease expired and nothing further may be written. */
-    holdsKey(): Promise<boolean>;
-    log(message: string): void;
-    attempt: number;
+export declare class TaskCancelledError extends Error {
+    constructor();
 }
-export interface QueueOptions<Body> {
-    name: string;
-    store: QueueStore<Body>;
-    handler: Handler<Body>;
-    /** How many KEYS one worker processes at once. Not messages — see the note. */
-    concurrency?: number;
-    /** How long a key lease lasts. Renewed between messages. */
-    leaseMs?: number;
-    /** Attempts before a message is dead-lettered. */
-    maxAttempts?: number;
-    /** Backoff between attempts. Doubles, capped. */
-    backoffMs?: number;
-    maxBackoffMs?: number;
-    /** Repeat enqueues with the same `dedupeKey` inside this window collapse. */
-    dedupeWindowMs?: number;
-    /** Messages taken per key per turn, so one hot key cannot hold a slot forever. */
-    batch?: number;
-    clock?: Clock;
-    owner?: string;
-    onError?: (message: Message<Body>, error: unknown) => void;
+export declare function createQueue(options?: QueueOptions): {
     /**
-     * Refuse to start unless the store is durable.
+     * Submit work and await its value.
      *
-     * Set it wherever losing queued work on a restart would be a real loss.
-     * Without it, wiring the memory store into a cluster is a mistake nothing
-     * reports until the first restart, by which point the work is gone.
+     * The handler's return type flows through, so a caller gets a result
+     * rather than an id to poll — the previous `enqueue` returned only
+     * `{ id, duplicate }` and had nowhere to put an answer.
      */
-    require?: QueueMode;
-}
-export interface EnqueueResult {
-    id: string;
-    /** True when an identical `dedupeKey` was already queued and this was dropped. */
-    duplicate: boolean;
-}
-export declare function createQueue<Body = unknown>(options: QueueOptions<Body>): {
-    enqueue: (args: {
-        key: string;
-        body: Body;
-        dedupeKey?: string;
-        delayMs?: number;
-    }) => Promise<EnqueueResult>;
-    tick: () => Promise<number>;
-    /** Drain until nothing is ready. For tests and for a one-shot worker. */
-    drain(maxPasses?: number): Promise<void>;
-    /** Poll forever. `stop()` lets in-flight keys finish. */
-    start(intervalMs?: number): void;
-    stop(): void;
-    mode: "standalone" | "cluster";
-    stats: () => Promise<QueueStats>;
-    dead: (limit?: number) => Promise<Message<Body>[]>;
-    /** Put a dead message back at the front of its key. An operator decision. */
-    revive(id: string): Promise<void>;
-};
-export type Queue<Body = unknown> = ReturnType<typeof createQueue<Body>>;
-export declare const VERSION = "0.1.0";
-/**
- * The four operations a shared database has to provide, and the one that is
- * hard.
- *
- * Everything except `claimKey` is an ordinary read or write. `claimKey` has to
- * find a key with ready work, check that nobody holds it, and take it — as ONE
- * atomic step. Split into a read and a write, two workers pass the check
- * together and both proceed, and the queue silently stops ordering anything.
- *
- * Written as a small adapter rather than a driver so the same queue runs over
- * ArangoDB, Postgres or Redis, and so this package keeps no dependency.
- */
-export interface ClusterAdapter<Body = unknown> {
-    insert(queue: string, message: Message<Body>): Promise<void>;
-    findDuplicate(queue: string, dedupeKey: string, sinceMs: number): Promise<Message<Body> | null>;
+    run<Args extends unknown[], T>(key: string, handler: (...args: Args) => Promise<T> | T, ...args: Args): QueueTask<T>;
+    /** Remove a task that has not started. Running work is left alone. */
+    cancel(id: string): boolean;
+    /** Hold one key. Work already running for it finishes. */
+    pauseKey(key: string): void;
+    resumeKey(key: string): void;
     /**
-     * ATOMIC. Must return a key that has ready work and no live lease, marking it
-     * leased in the same operation. Returning null means there is nothing to do.
+     * Close one key and reject everything for it that has not started.
+     *
+     * JavaScript cannot safely kill an arbitrary running function. The current
+     * handler is therefore allowed to finish; every pending handler is removed,
+     * and future submissions are refused until `startKey()` is explicit.
      */
-    takeKey(args: {
-        queue: string;
-        owner: string;
-        untilMs: number;
-        nowMs: number;
-    }): Promise<KeyLease | null>;
-    extendKey(queue: string, key: string, fence: number, untilMs: number): Promise<boolean>;
-    dropKey(queue: string, key: string, fence: number): Promise<void>;
-    readReady(queue: string, key: string, nowMs: number, limit: number): Promise<Message<Body>[]>;
-    patch(queue: string, id: string, patch: Partial<Message<Body>>): Promise<void>;
-    counts(queue: string): Promise<QueueStats>;
-    deadLetter(queue: string, limit: number): Promise<Message<Body>[]>;
-}
-/**
- * A durable store over any shared database.
- *
- * Declares `mode: 'cluster'`, which is what lets a deployment refuse to start if
- * somebody wires the memory store into production by mistake — a mistake that
- * is otherwise invisible until the first restart takes the queue with it.
- */
-export declare function clusterStore<Body = unknown>(adapter: ClusterAdapter<Body>): QueueStore<Body>;
+    stopKey(key: string): number;
+    /** Re-open a key deliberately; pausing and stopping are not aliases. */
+    startKey(key: string): boolean;
+    /** Hold everything. New submissions are accepted and wait. */
+    pause(): void;
+    resume(): void;
+    /** How much is outstanding, for a health endpoint or a drain decision. */
+    snapshot(): {
+        running: number;
+        queued: number;
+        keys: number;
+        paused: boolean;
+        pausedKeys: string[];
+        stoppedKeys: string[];
+        completed: number;
+        failed: number;
+    };
+    /** Resolve when nothing is running and nothing is queued. */
+    whenIdle(): Promise<void>;
+    /**
+     * Stop accepting work and await what is left, with a deadline.
+     *
+     * `stop()` used to flip a boolean and return `void`, which is not a
+     * shutdown — a process could exit with work in flight and report success.
+     * This reports what it actually managed.
+     */
+    stop(deadlineMs?: number): Promise<DrainReport>;
+};
+export type Queue = ReturnType<typeof createQueue>;