@volter/twin-inngest 0.1.0

package/src/inngest-connector.ts

@@ -0,0 +1,133 @@
+// inngest CONNECTOR — the live-vendor pull path that gives the inngest twin the "git for SaaS"
+// lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL (real -> twin) is HANDLE-DRIVEN, like fal-connector.ts and pinecone's vector pull — the
+// real Inngest v2 REST API (grounded, api-docs.inngest.com/api-specs/v2.json, fetched read-only
+// during this build) has NO bulk "list every event" or "list every run" endpoint: only
+// `GET /runs/{runId}` (by known id) and `GET /events/{eventId}/runs` (runs for a KNOWN event id).
+// So a caller of this connector must already know which event/run ids it cares about (e.g. from
+// its own application's persisted correlation ids) — the connector pulls the CURRENT real state
+// of each named handle and folds it into the twin via `syncPull` (shadow-diff dedup, so a re-pull
+// of identical state is a no-op).
+//
+// The vendor I/O is an INJECTED client interface (`InngestLikeClient`): a fake in tests, a thin
+// real-fetch wrapper in prod. The pack imports NO SDK and holds NO key.
+import { syncPull } from '@volter/world-core';
+import type { SyncResource } from '@volter/world-core';
+//
+// ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
+// Inngest's REST reference documents NO rate limit, no 429 and no Retry-After for the endpoints this
+// connector calls; the one endpoint it does annotate as rate limited ("fetch function run jobs",
+// cached for 5 seconds) gives no number and is not in this surface.
+// Every entrypoint below GUARDS the injected client before touching it (`guardInngestClient`, which is
+// idempotent — a caller who already wrapped is not double-charged, a caller who forgot is protected
+// anyway); there is deliberately no option that turns the budget off. See inngest-budget.ts.
+import { inngestBudgetOf, guardInngestClient, type InngestBudgetedOptions } from './inngest-budget.ts';
+
+const SERVICE = 'inngest';
+
+export type { InngestBudgetedOptions };
+
+export type InngestEventHandle = { eventId: string };
+export type InngestRunHandle = { runId: string };
+
+export type InngestRealEvent = { name: string; data?: unknown; user?: unknown; idempotencyId?: string | null; ts?: number };
+export type InngestRealRun = { id: string; functionId: string; eventId: string; status: string; output?: unknown; error?: unknown; cursor?: number };
+
+// The injected client exposes the minimal subset the connector calls; a real client wrapping the
+// v2 REST API's `GET /runs/{runId}` / `GET /events/{eventId}/runs` is structurally assignable.
+export interface InngestLikeClient {
+  events?: { get: (eventId: string) => Promise<InngestRealEvent> };
+  runs?: { get: (runId: string) => Promise<InngestRealRun> };
+}
+
+function kid(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+
+/** Pure mapper (real event -> SyncResource) — never touches a client, so the mutation-test
+ *  connector-seam sweep (which sabotages every export matching the sync-or-push-or-pull-or-
+ *  fullSync naming convention) leaves this real, per the pack convention (fal-connector.ts's
+ *  `mapQueueRequest`). Field names avoid the kernel's reserved `type`/`id`/`updatedAt` meta keys
+ *  (see inngest-runtime.ts header) — `idempotency_id`, never a bare `id`, inside `fields`. */
+export function mapEvent(handle: InngestEventHandle, real: InngestRealEvent): SyncResource {
+  return {
+    type: 'event',
+    id: kid('event', handle.eventId),
+    fields: {
+      name: real.name,
+      data: real.data ?? {},
+      user: real.user ?? null,
+      idempotency_id: real.idempotencyId ?? null,
+      ts: real.ts ?? null,
+      received_at: null,
+      v: null,
+    },
+  };
+}
+
+/** Pure mapper (real run -> SyncResource). */
+export function mapRun(handle: InngestRunHandle, real: InngestRealRun): SyncResource {
+  return {
+    type: 'run',
+    id: kid('run', handle.runId),
+    fields: {
+      function_id: real.functionId,
+      event_id: real.eventId,
+      status: real.status,
+      cursor: real.cursor ?? 0,
+      output: real.output ?? null,
+      error: real.error ?? null,
+      created_at: null,
+      started_at: null,
+      ended_at: null,
+    },
+  };
+}
+
+/** Pull the CURRENT real state of every named event handle. No `client.events` (or an empty
+ *  handle list) observes nothing — there is nothing to enumerate without a handle. */
+export async function pullInngestEvents(rawClient: InngestLikeClient, handles: InngestEventHandle[], opts: InngestBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardInngestClient(rawClient, opts);
+  if (!client.events || handles.length === 0) return [];
+  const out: SyncResource[] = [];
+  for (const handle of handles) {
+    const real = await client.events.get(handle.eventId);
+    out.push(mapEvent(handle, real));
+  }
+  return out;
+}
+
+/** Pull the CURRENT real state of every named run handle. */
+export async function pullInngestRuns(rawClient: InngestLikeClient, handles: InngestRunHandle[], opts: InngestBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardInngestClient(rawClient, opts);
+  if (!client.runs || handles.length === 0) return [];
+  const out: SyncResource[] = [];
+  for (const handle of handles) {
+    const real = await client.runs.get(handle.runId);
+    out.push(mapRun({ runId: handle.runId }, real));
+  }
+  return out;
+}
+
+/**
+ * D7 entry point: pull the current real state of every explicitly-named event/run handle and
+ * fold it into the twin via ONE `syncPull` (shadow-diff dedup). Returns
+ * `{observed, deltasAppended}` — a re-pull of identical state appends ZERO deltas.
+ */
+export async function syncInngestFromReal(
+  rawClient: InngestLikeClient,
+  opts: { root?: string; occurredAt?: string; events?: InngestEventHandle[]; runs?: InngestRunHandle[] } & InngestBudgetedOptions = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  // Guard ONCE here and hand the guarded client down: the per-handle loops below are unbounded in
+  // handle count, so this is the entrypoint that must be unable to run unbudgeted.
+  const client = guardInngestClient(rawClient, inngestBudgetOf(opts));
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const [events, runs] = await Promise.all([
+    pullInngestEvents(client, opts.events ?? []),
+    pullInngestRuns(client, opts.runs ?? []),
+  ]);
+  const resources = [...events, ...runs];
+  const result = syncPull({ service: SERVICE, resources, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}

package/src/inngest-runtime.ts

@@ -0,0 +1,391 @@
+// inngest DURABLE-EXECUTION STATE MACHINE — written FRESH for this pack (build spec §1
+// divergence 1). This is the novel core: Inngest's defining product idea is that a function
+// runs as a sequence of independently-checkpointed STEPS — each step's output is durably
+// persisted, and re-invoking a run REPLAYS every already-completed step by reading its
+// persisted output back out (never recomputing it) before advancing to the next uncompleted
+// step. That is the exact semantic this file models, kernel-backed (no in-memory side-store):
+// every step's result lives in a `step:<runId>::<stepId>` kernel row, and `advanceRun` below
+// is the ONLY function that ever creates or completes one — it always re-reads state from
+// `projectResources` first, so a "replay" is genuinely a kernel read, not a JS-local cache hit.
+//
+// HONESTY (build spec §13 ⚠3, README ## Coverage): this twin does NOT execute real user code —
+// there is no sandboxed JS runtime here. A function's steps are DECLARED up front (at
+// `functions.register` time, or directly by a test) as a `step_plan: [{id, op, ...}]` array —
+// a twin-only extension of the real wire register body (the real Inngest register payload has
+// no such field; a real SDK infers steps by re-running the handler function up to its next
+// `step.run()` call). Given a declared plan, this twin faithfully reproduces the DURABLE-
+// EXECUTION SEMANTICS real Inngest promises — memoization, replay-from-storage, sleep/wait
+// gating, exact retry counting — without ever running arbitrary code. `exec.sdk_executor_
+// roundtrip` (a real running app + real step functions) is the filed `todo`; see the pack
+// README.
+//
+// Step opcodes GROUNDED against the installed `inngest@4.12.0` package's own compiled
+// `StepOpCode` enum (types.js — read-only `npm pack` fetch during this build, not just docs):
+// 'StepRun' | 'Sleep' | 'WaitForEvent' | 'InvokeFunction' — see spec-sources.json.
+//
+// Poll-fold pattern ported from fal-twin.ts's `progressOnce` (fal-twin.ts:245-255): each call to
+// `advanceRun` performs AT MOST ONE meaningful state transition (no wall clock, no timers), so a
+// test suite re-running this file is bit-for-bit reproducible regardless of real elapsed time.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { createHash } from 'node:crypto';
+
+const SERVICE = 'inngest';
+
+// Kernel META reserves the field names `type`/`id`/`updatedAt` on every projected resource
+// (packages/world-core/src/actions.ts's `META` set) — a `fields` write using any of
+// those three keys is SILENTLY DROPPED by `projectResources`. The real Inngest step-op wire
+// shape names its opcode field `type`; this twin instead stores it as `op` (never `type`) for
+// exactly that reason. Likewise a real Inngest event payload's user-supplied idempotency field
+// is named `id`; this twin stores it as `idempotency_id`. Neither collision reaches the kernel.
+export type InngestStepOp = 'StepRun' | 'Sleep' | 'WaitForEvent' | 'InvokeFunction';
+
+export type DeclaredStep = {
+  id: string;
+  op: InngestStepOp;
+  /** WaitForEvent only: the event name this step gates on. */
+  eventName?: string;
+  /** WaitForEvent only: resolve with a deterministic timeout (output=null) after this many
+   *  non-matching advance calls — a poll-COUNT timeout, never a wall-clock one (§13 ⚠5). */
+  timeoutAfterPolls?: number;
+  /** StepRun only: fail this many times (attempts 1..failTimes) before succeeding on the next
+   *  advance — the deterministic retry-count fixture. */
+  failTimes?: number;
+  /** StepRun only: an explicit, test-declared output (skips the deterministic-stub hash). */
+  output?: unknown;
+};
+
+export type CancelOnRule = { event: string; if?: string };
+
+export type DeclaredFunction = {
+  id: string;
+  triggers: Array<{ event?: string; cron?: string }>;
+  steps: DeclaredStep[];
+  config?: Record<string, unknown>;
+  cancelOn?: CancelOnRule[];
+  url?: string;
+};
+
+const DEFAULT_MAX_ATTEMPTS = 4; // modeled default (§13 ⚠4 — doc-UNVERIFIED exact vendor default; config.retries overrides it, see inngest-twin.ts)
+
+function kid(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+export function nowIso(occurredAt?: string): string {
+  return occurredAt ?? new Date().toISOString();
+}
+
+// ── canonical JSON + deterministic stub hashing (ported convention: fal-twin.ts:186-195) ──────
+export function canonicalJson(v: unknown): string {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(v as Record<string, unknown>).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson((v as Record<string, unknown>)[k])}`).join(',')}}`;
+}
+
+/** step.run output = declared output or hash(runId::stepId::canonical-JSON(input)) (build spec
+ *  §1 divergence 1). `input` includes every PRIOR completed step's persisted output, so step-2's
+ *  value is a genuine function of step-1's REPLAYED (kernel-read) result — the load-bearing fact
+ *  `steps.replay_deterministic` proves. */
+export function stubStepOutput(runId: string, stepId: string, input: unknown): string {
+  const hash = createHash('sha256').update(`${runId}::${stepId}::${canonicalJson(input)}`).digest('hex').slice(0, 8);
+  return `[twin-stub:inngest:${hash}]`;
+}
+
+// A ULID-SHAPED (Crockford base32, 26 chars, time-prefixed) id — real Inngest event ids are
+// ULIDs, and this models the shape faithfully AND DETERMINISTICALLY (R9). Both halves used to
+// carry entropy — `Date.now()` for the time prefix and `randomUUID()` for the tail — so two
+// identical worlds sending the same event served different ids as soon as anything read the
+// event state back (`GET /twin/store/events`, `GET /api/v2/events/{id}/runs`). The time prefix
+// is now the WORLD instant (which is what a ULID's prefix MEANS, so this is also the more
+// faithful shape) and the tail is a stable digest of the seed the caller passes.
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export function newUlid(atMs: number, seed: string): string {
+  let timePart = '';
+  let t = Math.max(0, Math.floor(atMs));
+  for (let i = 0; i < 10; i++) { timePart = CROCKFORD[t % 32] + timePart; t = Math.floor(t / 32); }
+  let randPart = '';
+  const digest = createHash('sha256').update(seed).digest('hex');
+  for (let i = 0; i < 16; i++) { randPart += CROCKFORD[parseInt(digest[i]!, 16) % 32]; }
+  return timePart + randPart;
+}
+
+/** A UUID-shaped digest of `seed` — a run id keeps the vendor's shape without the entropy. */
+function uuidFrom(seed: string): string {
+  const h = createHash('sha256').update(seed).digest('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+// ── projection helpers (mirrors fal-twin.ts:154-168) ──────────────────────────────────────────
+export function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  const prefix = `${type}:`;
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === type && r.id.startsWith(prefix) && (r as Record<string, unknown>)._deleted !== true)
+    .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
+}
+export function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+function view(r: Record<string, unknown>): Record<string, unknown> {
+  const { type: _t, updatedAt: _u, ...rest } = r;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rest)) if (!k.startsWith('_')) out[k] = v;
+  return out;
+}
+export async function write(
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+  op: string,
+  root: string | undefined,
+  occurredAt: string | undefined,
+): Promise<Record<string, unknown>> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    { operation: op, subjectType: type, subjectId: kid(type, id), fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } },
+    root,
+  );
+  return view({ ...resource, id });
+}
+
+// ── functions: register / lookup ───────────────────────────────────────────────────────────────
+export async function registerFunction(fn: DeclaredFunction, root: string | undefined, occurredAt: string | undefined): Promise<{ row: Record<string, unknown>; modified: boolean; skipped: boolean }> {
+  const existing = getRow('function', fn.id, root);
+  const nextFields = {
+    fn_id: fn.id,
+    triggers: fn.triggers,
+    step_plan: fn.steps,
+    config: fn.config ?? {},
+    cancel_on: fn.cancelOn ?? [],
+    url: fn.url ?? null,
+    registered_at: nowIso(occurredAt),
+  };
+  // Compare only the caller-meaningful shape — never `fn_id`/`registered_at` (registration
+  // metadata, not config) and never `existing`'s extra `id`/`type` projection keys (present on a
+  // `getRow` read, absent from a fresh `write()`-shaped object) — an asymmetric key set would
+  // make canonicalJson ALWAYS mismatch, permanently defeating the skip-if-unchanged check.
+  const comparable = (f: { triggers: unknown; step_plan: unknown; config: unknown; cancel_on: unknown; url: unknown }) => ({
+    triggers: f.triggers, step_plan: f.step_plan, config: f.config, cancel_on: f.cancel_on, url: f.url,
+  });
+  if (existing) {
+    const prev = comparable(existing as { triggers: unknown; step_plan: unknown; config: unknown; cancel_on: unknown; url: unknown });
+    const next = comparable(nextFields);
+    if (canonicalJson(prev) === canonicalJson(next)) {
+      return { row: existing, modified: false, skipped: true };
+    }
+  }
+  const row = await write('function', fn.id, nextFields, existing ? 'function.reregister' : 'function.register', root, occurredAt);
+  return { row, modified: true, skipped: false };
+}
+export function listFunctions(root?: string): Array<Record<string, unknown>> {
+  return rows('function', root);
+}
+export function functionsMatchingEvent(eventName: string, root?: string): Array<Record<string, unknown>> {
+  return listFunctions(root).filter((f) => (f.triggers as Array<{ event?: string }>).some((t) => t.event === eventName));
+}
+export function functionsCancelledByEvent(eventName: string, root?: string): Array<Record<string, unknown>> {
+  return listFunctions(root).filter((f) => ((f.cancel_on as CancelOnRule[] | undefined) ?? []).some((c) => c.event === eventName));
+}
+
+// ── events ──────────────────────────────────────────────────────────────────────────────────
+export type SendEventInput = { name: string; data?: unknown; user?: unknown; id?: string; ts?: number; v?: string };
+
+/** Find an already-received event with the same (name, idempotency_id) — a minimal single-run
+ *  dedupe window (build spec §13 ⚠7: modeled minimal, not the real vendor's full TTL window). */
+export function findIdempotentEvent(name: string, idempotencyId: string, root?: string): Record<string, unknown> | undefined {
+  return rows('event', root).find((e) => e.name === name && e.idempotency_id === idempotencyId);
+}
+
+export async function recordEvent(input: SendEventInput, root: string | undefined, occurredAt: string | undefined): Promise<{ id: string; deduped: boolean }> {
+  if (input.id) {
+    const dup = findIdempotentEvent(input.name, input.id, root);
+    if (dup) return { id: dup.id as string, deduped: true };
+  }
+  // Seeded from the state this write lands on: the world instant plus the ordinal the event
+  // takes among the events already in the root, so two sends in one millisecond still differ.
+  const at = nowIso(occurredAt);
+  const id = newUlid(Date.parse(at), `event:${input.name}:${at}:${rows('event', root).length}`);
+  await write('event', id, {
+    name: input.name,
+    data: input.data ?? {},
+    user: input.user ?? null,
+    idempotency_id: input.id ?? null,
+    ts: input.ts ?? Date.parse(nowIso(occurredAt)),
+    received_at: nowIso(occurredAt),
+    v: input.v ?? null,
+  }, 'event.send', root, occurredAt);
+  return { id, deduped: false };
+}
+
+export async function createRun(functionId: string, eventId: string, root: string | undefined, occurredAt: string | undefined): Promise<Record<string, unknown>> {
+  const id = uuidFrom(`run:${functionId}:${eventId}:${nowIso(occurredAt)}:${rows('run', root).length}`);
+  return write('run', id, {
+    function_id: functionId,
+    event_id: eventId,
+    status: 'QUEUED',
+    cursor: 0,
+    output: null,
+    error: null,
+    created_at: nowIso(occurredAt),
+    started_at: null,
+    ended_at: null,
+  }, 'run.create', root, occurredAt);
+}
+
+export function runsForEvent(eventId: string, root?: string): Array<Record<string, unknown>> {
+  return rows('run', root).filter((r) => r.event_id === eventId);
+}
+export function runsForFunction(functionId: string, root?: string): Array<Record<string, unknown>> {
+  return rows('run', root).filter((r) => r.function_id === functionId);
+}
+
+const TERMINAL_STATUSES = new Set(['COMPLETED', 'FAILED', 'CANCELLED']);
+
+/** Cancel every non-terminal run of `functionId` — the REAL Inngest cancellation mechanism
+ *  (grounded live, 2026-07-09, inngest.com/docs/features/inngest-functions/cancellation): a
+ *  function declares `cancelOn: [{event, if}]`; when a matching event is sent, in-flight runs of
+ *  that function transition to CANCELLED. `if` is a CEL-style expression against
+ *  `event.data`/`async.data` — this twin matches on EVENT NAME ONLY (config-acceptance done, per
+ *  build spec §0's "config knobs = echo back" tier); full `if`-expression evaluation is todo
+ *  (`inngest.scheduling.cancel_if_expression`). NOT a REST DELETE call — the real v2 REST API
+ *  (api-docs.inngest.com/api-specs/v2.json, fetched read-only during this build) has no
+ *  cancel-run endpoint at all; this is the one and only real mechanism. */
+export async function cancelRunsForFunction(functionId: string, root: string | undefined, occurredAt: string | undefined): Promise<Record<string, unknown>[]> {
+  const cancelled: Record<string, unknown>[] = [];
+  for (const run of runsForFunction(functionId, root)) {
+    if (TERMINAL_STATUSES.has(run.status as string)) continue;
+    const updated = await write('run', run.id as string, { status: 'CANCELLED', ended_at: nowIso(occurredAt) }, 'run.cancel_via_event', root, occurredAt);
+    cancelled.push(updated);
+  }
+  return cancelled;
+}
+
+// ── the step machine ───────────────────────────────────────────────────────────────────────────
+function stepRowId(runId: string, stepId: string): string {
+  return `${runId}::${stepId}`;
+}
+export function getStep(runId: string, stepId: string, root?: string): Record<string, unknown> | undefined {
+  return getRow('step', stepRowId(runId, stepId), root);
+}
+export function stepsForRun(runId: string, root?: string): Array<Record<string, unknown>> {
+  return rows('step', root).filter((s) => s.run_id === runId);
+}
+
+/** Every COMPLETED step's persisted output, in declared-plan order — read FRESH from the kernel
+ *  on every call (never a JS-local cache), so a re-invocation genuinely REPLAYS them rather than
+ *  recomputing. This is what makes `steps.replay_deterministic` die under the `httpEmpty`
+ *  saboteur: an empty kernel means this returns `{}`, and any downstream step's stub hash — which
+ *  folds this object into its input — comes out WRONG. */
+export function priorOutputs(runId: string, plan: DeclaredStep[], uptoIndex: number, root?: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (let i = 0; i < uptoIndex; i++) {
+    const s = plan[i]!;
+    const row = getStep(runId, s.id, root);
+    if (row && row.state === 'completed') out[s.id] = row.output ?? null;
+  }
+  return out;
+}
+
+export type AdvanceResult = { run: Record<string, unknown>; step?: Record<string, unknown> };
+
+/**
+ * ONE poll-fold advance of a run (fal-twin.ts progressOnce pattern, build spec §6):
+ *   QUEUED         -> RUNNING (echo, no step touched — mirrors fal's poll-1 IN_QUEUE echo)
+ *   cursor < plan.length -> process plan[cursor] by its declared op (memoize on first touch,
+ *                            REPLAY — read, never recompute — on every subsequent touch)
+ *   cursor >= plan.length -> COMPLETED, output = last completed step's output
+ * A run already in a terminal state (COMPLETED/FAILED/CANCELLED) is a no-op (idempotent).
+ */
+export async function advanceRun(runId: string, root: string | undefined, occurredAt: string | undefined): Promise<AdvanceResult | undefined> {
+  const run = getRow('run', runId, root);
+  if (!run) return undefined;
+  const status = run.status as string;
+  if (TERMINAL_STATUSES.has(status)) return { run };
+
+  if (status === 'QUEUED') {
+    const updated = await write('run', runId, { status: 'RUNNING', started_at: nowIso(occurredAt) }, 'run.start', root, occurredAt);
+    return { run: updated };
+  }
+
+  const fn = getRow('function', run.function_id as string, root);
+  // No function row for this run's `function_id` — e.g. a connector-pulled run whose owning
+  // function was never (re-)registered locally. There is no declared step_plan to advance
+  // against, so this is a defensive no-op (never fabricate a plan-less COMPLETED transition) —
+  // the run's REAL vendor-observed `status` (folded in by the connector) is authoritative.
+  if (!fn) return { run };
+  const plan = (fn.step_plan as DeclaredStep[] | undefined) ?? [];
+  const cursor = run.cursor as number;
+
+  if (cursor >= plan.length) {
+    if (status !== 'COMPLETED') {
+      const lastStep = plan.length > 0 ? getStep(runId, plan[plan.length - 1]!.id, root) : undefined;
+      const updated = await write('run', runId, { status: 'COMPLETED', output: lastStep?.output ?? null, ended_at: nowIso(occurredAt) }, 'run.complete', root, occurredAt);
+      return { run: updated };
+    }
+    return { run };
+  }
+
+  const stepDef = plan[cursor]!;
+  const existing = getStep(runId, stepDef.id, root);
+
+  if (stepDef.op === 'Sleep') {
+    if (existing?.state === 'completed') {
+      const updatedRun = await write('run', runId, { cursor: cursor + 1 }, 'run.advance', root, occurredAt);
+      return { run: updatedRun, step: existing };
+    }
+    const step = await write('step', stepRowId(runId, stepDef.id), { run_id: runId, step_id: stepDef.id, op: 'Sleep', output: null, attempts: 1, state: 'completed' }, 'step.sleep', root, occurredAt);
+    const updatedRun = await write('run', runId, { cursor: cursor + 1 }, 'run.advance', root, occurredAt);
+    return { run: updatedRun, step };
+  }
+
+  if (stepDef.op === 'WaitForEvent') {
+    const eventName = stepDef.eventName ?? '';
+    if (!existing) {
+      const step = await write('step', stepRowId(runId, stepDef.id), { run_id: runId, step_id: stepDef.id, op: 'WaitForEvent', wait_event_name: eventName, waiting_since: nowIso(occurredAt), output: null, attempts: 1, state: 'waiting' }, 'step.wait_created', root, occurredAt);
+      return { run, step };
+    }
+    if (existing.state === 'waiting') {
+      const waitingSince = existing.waiting_since as string;
+      const match = rows('event', root).find((e) => e.name === eventName && (e.received_at as string) >= waitingSince);
+      if (match) {
+        const step = await write('step', stepRowId(runId, stepDef.id), { state: 'completed', output: { name: match.name, data: match.data } }, 'step.wait_resolved', root, occurredAt);
+        const updatedRun = await write('run', runId, { cursor: cursor + 1 }, 'run.advance', root, occurredAt);
+        return { run: updatedRun, step };
+      }
+      const attempts = (existing.attempts as number) + 1;
+      if (stepDef.timeoutAfterPolls !== undefined && attempts >= stepDef.timeoutAfterPolls) {
+        const step = await write('step', stepRowId(runId, stepDef.id), { state: 'completed', output: null, attempts }, 'step.wait_timeout', root, occurredAt);
+        const updatedRun = await write('run', runId, { cursor: cursor + 1 }, 'run.advance', root, occurredAt);
+        return { run: updatedRun, step };
+      }
+      const step = await write('step', stepRowId(runId, stepDef.id), { attempts }, 'step.wait_poll', root, occurredAt);
+      return { run, step };
+    }
+    // already completed -> replay (cursor should already be past it; defensive no-op)
+    return { run, step: existing };
+  }
+
+  // StepRun / InvokeFunction (both modeled identically: memoize + replay + optional retry fixture)
+  if (existing?.state === 'completed') {
+    const updatedRun = await write('run', runId, { cursor: cursor + 1 }, 'run.advance', root, occurredAt);
+    return { run: updatedRun, step: existing };
+  }
+
+  const failTimes = stepDef.failTimes ?? 0;
+  const maxAttempts = ((fn?.config as Record<string, unknown> | undefined)?.retries as number | undefined) ?? DEFAULT_MAX_ATTEMPTS;
+  const currentAttempts = ((existing?.attempts as number | undefined) ?? 0) + 1;
+
+  if (currentAttempts > maxAttempts) {
+    const step = await write('step', stepRowId(runId, stepDef.id), { run_id: runId, step_id: stepDef.id, op: stepDef.op, state: 'failed', attempts: currentAttempts, error: 'max attempts exceeded', output: null }, 'step.retry_exhausted', root, occurredAt);
+    const updatedRun = await write('run', runId, { status: 'FAILED', error: { step: stepDef.id, message: 'max attempts exceeded' }, ended_at: nowIso(occurredAt) }, 'run.fail', root, occurredAt);
+    return { run: updatedRun, step };
+  }
+  if (currentAttempts <= failTimes) {
+    const step = await write('step', stepRowId(runId, stepDef.id), { run_id: runId, step_id: stepDef.id, op: stepDef.op, state: 'failed', attempts: currentAttempts, error: `stub failure ${currentAttempts}`, output: null }, 'step.retry', root, occurredAt);
+    return { run, step };
+  }
+  const input = { priorOutputs: priorOutputs(runId, plan, cursor, root), stepId: stepDef.id };
+  const output = stepDef.output !== undefined ? stepDef.output : stubStepOutput(runId, stepDef.id, input);
+  const step = await write('step', stepRowId(runId, stepDef.id), { run_id: runId, step_id: stepDef.id, op: stepDef.op, state: 'completed', attempts: currentAttempts, error: null, output }, 'step.run', root, occurredAt);
+  const updatedRun = await write('run', runId, { cursor: cursor + 1 }, 'run.advance', root, occurredAt);
+  return { run: updatedRun, step };
+}

package/src/inngest-server.ts

@@ -0,0 +1,50 @@
+// inngest twin HTTP server — serve the full Inngest API twin handler over HTTP so the real
+// `inngest` SDK's `.send()` (via its `baseUrl` constructor option / `INNGEST_BASE_URL` env
+// override — SDK-source grounded, see inngest-sdk.integration.test.ts) works unmodified against
+// it. Every route is plain JSON. The incoming HTTP `Host` header is forwarded as-is (unlike
+// fal-server.ts, this twin's surface routing is PATH-primary — see inngest-twin.ts's
+// `routeInngestSurface` header note — so no proxy-header recovery dance is needed here).
+// Writable by default; pass `readOnly` to reject writes with 405 (D3). State is the kernel
+// projection (no side-store) — see inngest-twin.ts / inngest-runtime.ts.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`) with the host threading as its
+// per-request `extras`; the server is one line of Bun.serve around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handleInngestTwinRequest } from './inngest-twin.ts';
+import { rows } from './inngest-runtime.ts';
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+
+/** Options every Inngest-twin HTTP surface needs, independent of who owns the socket. */
+export interface InngestTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+export function createInngestTwinFetch(options: InngestTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  return createTwinFetchFromHandler(handleInngestTwinRequest, {
+    ...options,
+    manifest: statefulTwinManifest({ vendor: 'inngest', twinOf: 'the Inngest durable-execution surface', stores: 'events, registered functions and their kernel-persisted run state' }),
+    // THE STORE DOOR (R5c). The vendor's own read surface is addressed BY ID
+    // (`GET /api/v2/runs/{id}`, `GET /api/v2/events/{id}/runs`) and has no listing endpoint at
+    // all, so the ingested event feed and the runs it fanned out to were write-only state that
+    // nothing could read back without already knowing an id — which is exactly how the entropy
+    // in their ids went unseen (R9). These are the same deterministic projections the handler
+    // serves per-id, listed oldest-first.
+    stores: {
+      events: () => rows('event', options.root),
+      runs: () => rows('run', options.root),
+    },
+    extras: (_request, url) => ({ host: url.host }),
+  });
+}
+
+export async function createInngestTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createInngestTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}