@forgezero/runtime 0.1.0

package/dist/openssh.js

@@ -0,0 +1,106 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/openssh.ts
+import { sha256 } from "@noble/hashes/sha2.js";
+import { toBase64Url, fromBase64Url } from "@forgezero/access/security";
+var ALGORITHM = "ssh-ed25519";
+var ENCODER = new TextEncoder;
+function sshString(value) {
+  const bytes = typeof value === "string" ? ENCODER.encode(value) : value;
+  const out = new Uint8Array(4 + bytes.length);
+  new DataView(out.buffer).setUint32(0, bytes.length, false);
+  out.set(bytes, 4);
+  return out;
+}
+var concat = (...parts) => {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+};
+function base64(bytes) {
+  const url = toBase64Url(bytes);
+  const standard = url.replaceAll("-", "+").replaceAll("_", "/");
+  const padding = (4 - standard.length % 4) % 4;
+  return standard + "=".repeat(padding);
+}
+var unbase64 = (value) => fromBase64Url(value.replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, ""));
+
+class OpenSshError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "OpenSshError";
+  }
+}
+function publicKeyBlob(publicKey) {
+  if (publicKey.length !== 32) {
+    throw new OpenSshError("BAD_KEY", "An ed25519 public key is 32 bytes.");
+  }
+  return concat(sshString(ALGORITHM), sshString(publicKey));
+}
+function authorizedKey(publicKey, comment = "") {
+  if (/[\r\n]/.test(comment)) {
+    throw new OpenSshError("BAD_COMMENT", "A comment cannot contain a newline — in authorized_keys that ends the line and starts another entry.");
+  }
+  const line = `${ALGORITHM} ${base64(publicKeyBlob(publicKey))}`;
+  return comment.trim() ? `${line} ${comment.trim()}` : line;
+}
+function fingerprint(publicKey) {
+  return `SHA256:${base64(sha256(publicKeyBlob(publicKey))).replace(/=+$/, "")}`;
+}
+function signatureBlob(signature) {
+  if (signature.length !== 64) {
+    throw new OpenSshError("BAD_KEY", "An ed25519 signature is 64 bytes.");
+  }
+  return concat(sshString(ALGORITHM), sshString(signature));
+}
+function parseAuthorizedKey(line) {
+  const parts = line.trim().split(/\s+/);
+  if (parts.length < 2)
+    throw new OpenSshError("BAD_BLOB", "That is not an authorized_keys line.");
+  const [prefix, encoded, ...rest] = parts;
+  if (prefix !== ALGORITHM) {
+    throw new OpenSshError("BAD_BLOB", `Only ${ALGORITHM} is supported here, not ${prefix}.`);
+  }
+  let blob;
+  try {
+    blob = unbase64(encoded);
+  } catch {
+    throw new OpenSshError("BAD_BLOB", "The key body is not valid base64.");
+  }
+  if (blob.length !== 51)
+    throw new OpenSshError("BAD_BLOB", "That is not an ed25519 key blob.");
+  const view = new DataView(blob.buffer, blob.byteOffset, blob.byteLength);
+  const nameLength = view.getUint32(0, false);
+  const name = new TextDecoder().decode(blob.slice(4, 4 + nameLength));
+  if (name !== ALGORITHM) {
+    throw new OpenSshError("BAD_BLOB", `The blob says "${name}" while the line says "${prefix}". sshd reads the blob, so this key would be refused at login.`);
+  }
+  const keyLength = view.getUint32(4 + nameLength, false);
+  if (keyLength !== 32)
+    throw new OpenSshError("BAD_BLOB", "The embedded key is not 32 bytes.");
+  return {
+    publicKey: blob.slice(4 + nameLength + 4),
+    comment: rest.join(" ")
+  };
+}
+export {
+  signatureBlob,
+  publicKeyBlob,
+  parseAuthorizedKey,
+  fingerprint,
+  authorizedKey,
+  OpenSshError
+};

package/dist/otpauth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The `otpauth://` URI, which is what a QR code actually contains.
+ *
+ * Every site that offers "scan this" encodes the same thing: a secret, who it
+ * belongs to, and the parameters needed to reproduce a code. Nothing about it
+ * is standardised beyond a Google wiki page, so implementations disagree at the
+ * edges — and each disagreement is a code that comes out wrong for one issuer
+ * and right for every other, which is the hardest kind of bug to be told about.
+ *
+ * So this parses strictly and refuses what it cannot reproduce, rather than
+ * guessing a default and generating six digits that will never be accepted.
+ *
+ * ## The label is not the issuer, except when it is
+ *
+ *     otpauth://totp/GitHub:alice@example.com?issuer=GitHub&secret=...
+ *
+ * The prefix before the colon and the `issuer` parameter are the same claim
+ * made twice, and they DISAGREE in the wild. The parameter wins — it is
+ * unambiguous, while the label prefix cannot be told apart from an account name
+ * that happens to contain a colon.
+ */
+export interface OtpAuth {
+    /** `totp`. `hotp` is counter-based and deliberately unsupported. */
+    type: 'totp';
+    /** Who issued it — "GitHub", "AWS". */
+    issuer: string;
+    /** The account at that issuer. May be empty; not every issuer sets one. */
+    account: string;
+    /** Base32, no padding, upper case. */
+    secret: string;
+    digits: number;
+    stepSeconds: number;
+    algorithm: 'SHA-1' | 'SHA-256' | 'SHA-512';
+}
+/**
+ * Parse, or throw.
+ *
+ * There is no partial success. A URI missing its secret, or carrying digits we
+ * cannot produce, yields nothing usable — and storing it would mean an entry
+ * that looks enrolled and can never sign anybody in.
+ */
+export declare function parseOtpAuth(raw: string): OtpAuth;
+/**
+ * Back to a URI, for handing to another authenticator.
+ *
+ * A vault somebody cannot leave is a vault they should not have joined, and for
+ * TOTP that means being able to export what was imported.
+ *
+ * The issuer appears TWICE — as the label prefix and as the parameter — because
+ * older authenticators read only one of the two, and which one is not knowable
+ * from here.
+ */
+export declare function formatOtpAuth(entry: OtpAuth): string;
+/** A secret somebody typed by hand, rather than scanned. */
+export declare function fromManualSecret(secret: string, issuer?: string, account?: string): OtpAuth;
+/** Round-trip a secret we generated ourselves, for enrolling a NEW account. */
+export declare const newOtpAuth: (secretBytes: Uint8Array, issuer: string, account: string) => OtpAuth;

package/dist/otpauth.js

@@ -0,0 +1,223 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/totp.ts
+import { timingSafeEqual } from "@forgezero/access/security";
+
+class TotpError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "TotpError";
+  }
+}
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function toBase32(bytes) {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      output += ALPHABET[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0)
+    output += ALPHABET[value << 5 - bits & 31];
+  return output;
+}
+function fromBase32(text) {
+  const cleaned = text.toUpperCase().replace(/[\s=-]/g, "");
+  if (cleaned.length === 0)
+    throw new TotpError("BAD_SECRET", "The secret is empty.");
+  let bits = 0;
+  let value = 0;
+  const bytes = [];
+  for (const character of cleaned) {
+    const index = ALPHABET.indexOf(character);
+    if (index === -1) {
+      throw new TotpError("BAD_SECRET", `"${character}" is not a base32 character.`);
+    }
+    value = value << 5 | index;
+    bits += 5;
+    if (bits >= 8) {
+      bytes.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(bytes);
+}
+function generateSecret(bytes = 20) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toBase32(buffer);
+}
+var DEFAULT_STEP_SECONDS = 30;
+var DEFAULT_DIGITS = 6;
+var counterAt = (atMs, stepSeconds = DEFAULT_STEP_SECONDS) => Math.floor(atMs / 1000 / stepSeconds);
+async function hmac(secret, counter, algorithm) {
+  const message = new Uint8Array(8);
+  let remaining = counter;
+  for (let index = 7;index >= 0; index -= 1) {
+    message[index] = remaining & 255;
+    remaining = Math.floor(remaining / 256);
+  }
+  const key = await crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: algorithm }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, message));
+}
+async function codeFor(secret, counter, options = {}) {
+  const digits = options.digits ?? DEFAULT_DIGITS;
+  if (digits < 6 || digits > 8) {
+    throw new TotpError("BAD_DIGITS", "A TOTP code is between six and eight digits.");
+  }
+  const mac = await hmac(fromBase32(secret), counter, options.algorithm ?? "SHA-1");
+  const offset = mac[mac.length - 1] & 15;
+  const binary = (mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255;
+  return String(binary % 10 ** digits).padStart(digits, "0");
+}
+var codeAt = (secret, atMs, options = {}) => codeFor(secret, counterAt(atMs, options.stepSeconds ?? DEFAULT_STEP_SECONDS), options);
+async function verifyCode(secret, code, options = {}) {
+  const digits = options.digits ?? DEFAULT_DIGITS;
+  const cleaned = code.replace(/\s/g, "");
+  if (!new RegExp(`^\\d{${digits}}$`).test(cleaned)) {
+    return { ok: false, reason: "BAD_CODE" };
+  }
+  const step = options.stepSeconds ?? DEFAULT_STEP_SECONDS;
+  const window = options.window ?? 1;
+  const current = counterAt(options.atMs ?? Date.now(), step);
+  let matched;
+  for (let drift = -window;drift <= window; drift += 1) {
+    const counter = current + drift;
+    const expected = await codeFor(secret, counter, options);
+    if (timingSafeEqual(expected, cleaned))
+      matched = counter;
+  }
+  if (matched === undefined)
+    return { ok: false, reason: "BAD_CODE" };
+  if (options.lastCounter !== undefined && matched <= options.lastCounter) {
+    return { ok: false, counter: matched, reason: "REPLAYED" };
+  }
+  return { ok: true, counter: matched };
+}
+async function assertCode(secret, code, options = {}) {
+  const result = await verifyCode(secret, code, options);
+  if (!result.ok) {
+    throw new TotpError(result.reason ?? "BAD_CODE", result.reason === "REPLAYED" ? "That code has already been used. Wait for the next one." : "That code is not right. Check your authenticator and try again.");
+  }
+  return result.counter;
+}
+function enrolmentUri(args) {
+  const label = `${encodeURIComponent(args.issuer)}:${encodeURIComponent(args.account)}`;
+  const parameters = new URLSearchParams({
+    secret: args.secret,
+    issuer: args.issuer,
+    algorithm: (args.options?.algorithm ?? "SHA-1").replace("-", ""),
+    digits: String(args.options?.digits ?? DEFAULT_DIGITS),
+    period: String(args.options?.stepSeconds ?? DEFAULT_STEP_SECONDS)
+  });
+  return `otpauth://totp/${label}?${parameters.toString()}`;
+}
+var secondsRemaining = (atMs = Date.now(), stepSeconds = DEFAULT_STEP_SECONDS) => stepSeconds - Math.floor(atMs / 1000) % stepSeconds;
+
+// src/otpauth.ts
+var ALGORITHMS = {
+  SHA1: "SHA-1",
+  SHA256: "SHA-256",
+  SHA512: "SHA-512"
+};
+function parseOtpAuth(raw) {
+  let url;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new TotpError("OTPAUTH_MALFORMED", "That is not an otpauth:// URI.");
+  }
+  if (url.protocol !== "otpauth:") {
+    throw new TotpError("OTPAUTH_MALFORMED", "That is not an otpauth:// URI.");
+  }
+  const afterScheme = raw.trim().slice("otpauth://".length);
+  const [typeAndLabel = "", ...rest] = afterScheme.split("?");
+  const query = new URLSearchParams(rest.join("?"));
+  const slash = typeAndLabel.indexOf("/");
+  const type = (slash === -1 ? typeAndLabel : typeAndLabel.slice(0, slash)).toLowerCase();
+  const label = decodeURIComponent(slash === -1 ? "" : typeAndLabel.slice(slash + 1));
+  if (type === "hotp") {
+    throw new TotpError("OTPAUTH_UNSUPPORTED", "Counter-based (hotp) codes are not supported.");
+  }
+  if (type !== "totp") {
+    throw new TotpError("OTPAUTH_UNSUPPORTED", `"${type}" is not a kind of code we generate.`);
+  }
+  const secret = (query.get("secret") ?? "").replace(/\s|=/g, "").toUpperCase();
+  if (!secret)
+    throw new TotpError("OTPAUTH_NO_SECRET", "The URI carries no secret.");
+  fromBase32(secret);
+  const colon = label.indexOf(":");
+  const labelIssuer = colon === -1 ? "" : label.slice(0, colon).trim();
+  const issuer = (query.get("issuer") ?? labelIssuer).trim();
+  const account = (colon === -1 ? label : label.slice(colon + 1)).trim();
+  const digits = Number(query.get("digits") ?? DEFAULT_DIGITS);
+  if (![6, 7, 8].includes(digits)) {
+    throw new TotpError("OTPAUTH_UNSUPPORTED", `${digits}-digit codes are not supported.`);
+  }
+  const stepSeconds = Number(query.get("period") ?? DEFAULT_STEP_SECONDS);
+  if (!Number.isInteger(stepSeconds) || stepSeconds < 15 || stepSeconds > 300) {
+    throw new TotpError("OTPAUTH_UNSUPPORTED", `A ${stepSeconds}s period is out of range.`);
+  }
+  const rawAlgorithm = (query.get("algorithm") ?? "SHA1").toUpperCase().replace("-", "");
+  const algorithm = ALGORITHMS[rawAlgorithm];
+  if (!algorithm) {
+    throw new TotpError("OTPAUTH_UNSUPPORTED", `${rawAlgorithm} is not an algorithm we support.`);
+  }
+  return { type: "totp", issuer, account, secret, digits, stepSeconds, algorithm };
+}
+function formatOtpAuth(entry) {
+  const label = entry.issuer ? `${encodeURIComponent(entry.issuer)}:${encodeURIComponent(entry.account)}` : encodeURIComponent(entry.account);
+  const query = new URLSearchParams({ secret: entry.secret });
+  if (entry.issuer)
+    query.set("issuer", entry.issuer);
+  if (entry.digits !== DEFAULT_DIGITS)
+    query.set("digits", String(entry.digits));
+  if (entry.stepSeconds !== DEFAULT_STEP_SECONDS)
+    query.set("period", String(entry.stepSeconds));
+  if (entry.algorithm !== "SHA-1")
+    query.set("algorithm", entry.algorithm.replace("-", ""));
+  return `otpauth://totp/${label}?${query.toString()}`;
+}
+function fromManualSecret(secret, issuer = "", account = "") {
+  const cleaned = secret.replace(/\s|=/g, "").toUpperCase();
+  if (!cleaned)
+    throw new TotpError("OTPAUTH_NO_SECRET", "Enter the secret the site showed you.");
+  fromBase32(cleaned);
+  return {
+    type: "totp",
+    issuer: issuer.trim(),
+    account: account.trim(),
+    secret: cleaned,
+    digits: DEFAULT_DIGITS,
+    stepSeconds: DEFAULT_STEP_SECONDS,
+    algorithm: "SHA-1"
+  };
+}
+var newOtpAuth = (secretBytes, issuer, account) => ({
+  type: "totp",
+  issuer,
+  account,
+  secret: toBase32(secretBytes),
+  digits: DEFAULT_DIGITS,
+  stepSeconds: DEFAULT_STEP_SECONDS,
+  algorithm: "SHA-1"
+});
+export {
+  parseOtpAuth,
+  newOtpAuth,
+  fromManualSecret,
+  formatOtpAuth
+};

package/dist/outbox.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Write the event with the record; deliver it afterwards.
+ *
+ * `emit` in `@forgezero/access/effects` is only as reliable as the thing it
+ * publishes into. Sending straight from the handler loses the event whenever the
+ * process dies between the commit and the send — and that window is not
+ * theoretical: it is exactly where a deploy, an OOM kill or a failover lands,
+ * which is to say the moments somebody is watching.
+ *
+ * The inversion is the whole idea. Instead of
+ *
+ *     commit the record  →  send the event      (event lost if we die here)
+ *
+ * do
+ *
+ *     commit the record AND the event together  →  send later, retrying
+ *
+ * The event is a row written by the same transaction that wrote the record, so
+ * either both exist or neither does. Delivery becomes a separate, restartable
+ * problem rather than a thing that had one chance to work.
+ *
+ * ## What this guarantees, exactly
+ *
+ * **At least once.** Not exactly once. A delivery can succeed and the write that
+ * marks it delivered can fail immediately afterwards, and the event is then sent
+ * again. There is no arrangement of two systems that avoids this — the
+ * acknowledgement is itself a message that can be lost.
+ *
+ * So consumers must be idempotent, and every event carries an `id` stable across
+ * redeliveries to make that possible. A package claiming exactly-once here would
+ * be claiming to have solved the two-generals problem, and the practical result
+ * of believing it is a double credit.
+ *
+ * ## Order is per key, not global
+ *
+ * A global order means one delivery at a time and throughput collapses. No order
+ * at all means `entry.updated` can overtake `entry.created`, and a consumer sees
+ * a change to something it has never heard of. Events therefore carry an
+ * optional `key` — an aggregate id — and delivery is strictly sequential within
+ * one key and fully parallel across keys. Same shape as `@forgezero/runtime/queue`, for
+ * the same reason.
+ */
+export declare class OutboxError extends Error {
+    readonly code: 'NO_TRANSPORT' | 'NOT_CLAIMED' | 'UNKNOWN_EVENT';
+    constructor(code: 'NO_TRANSPORT' | 'NOT_CLAIMED' | 'UNKNOWN_EVENT', message: string);
+}
+export declare const EVENT_STATES: readonly ["pending", "delivering", "delivered", "dead"];
+export type EventState = (typeof EVENT_STATES)[number];
+export interface OutboxEvent {
+    id: string;
+    type: string;
+    /** The aggregate this concerns. Events sharing one are delivered in order. */
+    key?: string;
+    route?: string;
+    realm?: string;
+    payload: Record<string, unknown>;
+    state: EventState;
+    attempts: number;
+    /** Not eligible for delivery before this. Set by backoff after a failure. */
+    nextAttemptAtMs: number;
+    /** Set while a drainer holds it. A stale claim is reclaimable — see `claim`. */
+    claimedBy?: string;
+    claimedUntilMs?: number;
+    lastError?: string;
+    createdAtMs: number;
+    deliveredAtMs?: number;
+}
+/** What a caller publishes. Everything else is filled in. */
+export interface PublishInput {
+    type: string;
+    key?: string;
+    route?: string;
+    realm?: string;
+    payload: Record<string, unknown>;
+    /**
+     * Supply this to make publishing idempotent.
+     *
+     * A handler that retries its own transaction would otherwise insert the event
+     * twice. With a stable id the second insert collides and is ignored, which is
+     * the behaviour every caller assumes they already have.
+     */
+    id?: string;
+    /** Hold the event back until a time — a reminder, a scheduled notice. */
+    notBeforeMs?: number;
+}
+export interface DeliveryPolicy {
+    /** Attempts before the event is dead-lettered. */
+    maxAttempts: number;
+    /** First retry delay. Doubles each attempt, capped. */
+    baseDelayMs: number;
+    maxDelayMs: number;
+    /**
+     * Random fraction added to each delay, 0–1.
+     *
+     * Without it, a relay that was down for a minute gets every event that failed
+     * during the outage retried in the same millisecond, and goes down again. The
+     * failure mode is self-inflicted and completely avoidable.
+     */
+    jitter: number;
+    /** How long a claim is honoured before another drainer may take the event. */
+    claimTtlMs: number;
+}
+export declare const DEFAULT_POLICY: DeliveryPolicy;
+/**
+ * Exponential backoff with jitter.
+ *
+ * `random` is injectable so a test can assert the shape of the curve rather than
+ * a range — a bounds-only assertion passes for an implementation that returns
+ * the cap every time.
+ */
+export declare function backoffMs(attempts: number, policy?: DeliveryPolicy, random?: () => number): number;
+/**
+ * Persistence.
+ *
+ * `insert` is the load-bearing method: it must run inside the SAME transaction
+ * as the business write. That is why the store is injected rather than opened
+ * here — only the caller knows what transaction is open, and an outbox that
+ * opens its own connection has thrown away the one property it exists for.
+ */
+export interface OutboxStore {
+    /** Returns false if an event with this id already exists. Never throws on collision. */
+    insert(event: OutboxEvent): Promise<boolean>;
+    /**
+     * Take up to `limit` deliverable events and mark them claimed.
+     *
+     * Must not return two events sharing a `key` in one batch, and must not
+     * return an event whose key has an older undelivered event — that is what
+     * makes per-key order hold. Must reclaim events whose `claimedUntilMs` has
+     * passed, or a drainer that crashes mid-batch strands them forever.
+     */
+    claim(args: {
+        drainerId: string;
+        limit: number;
+        nowMs: number;
+        claimTtlMs: number;
+    }): Promise<OutboxEvent[]>;
+    settle(id: string, patch: Partial<OutboxEvent>): Promise<void>;
+    byState(state: EventState, limit?: number): Promise<OutboxEvent[]>;
+    get(id: string): Promise<OutboxEvent | null>;
+}
+export interface DeliveryResult {
+    ok: boolean;
+    /** A failure that will never succeed — a malformed payload, a 400. */
+    terminal?: boolean;
+    error?: string;
+}
+export interface Transport {
+    deliver(event: OutboxEvent): Promise<DeliveryResult>;
+}
+export interface OutboxOptions {
+    store: OutboxStore;
+    transport: Transport;
+    policy?: Partial<DeliveryPolicy>;
+    /** Identifies this drainer in a claim. Must differ per process. */
+    drainerId?: string;
+    now?: () => number;
+    random?: () => number;
+    /** Called when an event exhausts its attempts. The one hook worth wiring. */
+    onDeadLetter?: (event: OutboxEvent) => void;
+}
+export interface DrainReport {
+    claimed: number;
+    delivered: number;
+    failed: number;
+    dead: number;
+}
+export declare function createOutbox(options: OutboxOptions): {
+    /**
+     * Record an event. Call this INSIDE the transaction that writes the record.
+     *
+     * Nothing is sent here. That is the point — the send is what can fail, and
+     * moving it out of the request means the request cannot fail because of it.
+     */
+    publish(input: PublishInput): Promise<OutboxEvent>;
+    /**
+     * Deliver a batch.
+     *
+     * Events are delivered concurrently because the store guarantees no two in
+     * one batch share a key — so parallelism here cannot reorder anything. That
+     * guarantee is the store's, and `memoryStore` below implements it exactly
+     * so a test cannot pass against a weaker one.
+     */
+    drain(limit?: number): Promise<DrainReport>;
+    /** Everything that gave up. The queue somebody has to actually look at. */
+    deadLetter: (limit?: number) => Promise<OutboxEvent[]>;
+    /**
+     * Put a dead event back in the queue.
+     *
+     * Attempts reset, because the reason it died has usually been fixed by hand
+     * and starting at attempt eight would dead-letter it again on the first
+     * hiccup.
+     */
+    retry(id: string): Promise<void>;
+    pending: (limit?: number) => Promise<OutboxEvent[]>;
+    drainerId: string;
+};
+export type Outbox = ReturnType<typeof createOutbox>;
+/**
+ * The outbox as a job, for `@forgezero/runtime/jobs`.
+ *
+ * Returned as a plain spec rather than importing `defineJob`, so this package
+ * does not take a dependency on `jobs` for one object literal — and so a caller
+ * running its own loop is not forced to adopt a scheduler.
+ */
+export declare function outboxJob(outbox: Outbox, options?: {
+    key?: string;
+    everyMs?: number;
+    batch?: number;
+}): {
+    key: string;
+    everyMs: number;
+    run: () => Promise<{
+        ok: boolean;
+        detail: {
+            claimed: number;
+            delivered: number;
+            failed: number;
+            dead: number;
+        };
+    }>;
+};
+/**
+ * An in-memory store that enforces every constraint a real one must.
+ *
+ * Specifically the per-key ordering rule: a test that passes against a store
+ * which happily returns two events for one key would pass here and reorder in
+ * production. Encoding the constraint in the reference implementation is the
+ * only way the interface documentation is load-bearing.
+ */
+export declare function memoryStore(): OutboxStore & {
+    all(): OutboxEvent[];
+    clear(): void;
+};
+export declare const VERSION = "0.1.0";