@volter/twin-inngest 0.1.0

package/dist/src/inngest-connector.d.ts

@@ -0,0 +1,60 @@
+import type { SyncResource } from '@volter/world-core';
+import { type InngestBudgetedOptions } from './inngest-budget.js';
+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;
+};
+export interface InngestLikeClient {
+    events?: {
+        get: (eventId: string) => Promise<InngestRealEvent>;
+    };
+    runs?: {
+        get: (runId: string) => Promise<InngestRealRun>;
+    };
+}
+/** 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 declare function mapEvent(handle: InngestEventHandle, real: InngestRealEvent): SyncResource;
+/** Pure mapper (real run -> SyncResource). */
+export declare function mapRun(handle: InngestRunHandle, real: InngestRealRun): SyncResource;
+/** 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 declare function pullInngestEvents(rawClient: InngestLikeClient, handles: InngestEventHandle[], opts?: InngestBudgetedOptions): Promise<SyncResource[]>;
+/** Pull the CURRENT real state of every named run handle. */
+export declare function pullInngestRuns(rawClient: InngestLikeClient, handles: InngestRunHandle[], opts?: InngestBudgetedOptions): Promise<SyncResource[]>;
+/**
+ * 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 declare function syncInngestFromReal(rawClient: InngestLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+    events?: InngestEventHandle[];
+    runs?: InngestRunHandle[];
+} & InngestBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;

package/dist/src/inngest-connector.js

@@ -0,0 +1,109 @@
+// 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';
+//
+// ── 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 } from "./inngest-budget.js";
+const SERVICE = 'inngest';
+function kid(type, id) {
+    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, real) {
+    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, real) {
+    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, handles, opts = {}) {
+    const client = guardInngestClient(rawClient, opts);
+    if (!client.events || handles.length === 0)
+        return [];
+    const out = [];
+    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, handles, opts = {}) {
+    const client = guardInngestClient(rawClient, opts);
+    if (!client.runs || handles.length === 0)
+        return [];
+    const out = [];
+    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, opts = {}) {
+    // 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/dist/src/inngest-runtime.d.ts

@@ -0,0 +1,98 @@
+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;
+};
+export declare function nowIso(occurredAt?: string): string;
+export declare function canonicalJson(v: unknown): string;
+/** 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 declare function stubStepOutput(runId: string, stepId: string, input: unknown): string;
+export declare function newUlid(atMs: number, seed: string): string;
+export declare function rows(type: string, root?: string): Array<Record<string, unknown>>;
+export declare function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined;
+export declare function write(type: string, id: string, fields: Record<string, unknown>, op: string, root: string | undefined, occurredAt: string | undefined): Promise<Record<string, unknown>>;
+export declare function registerFunction(fn: DeclaredFunction, root: string | undefined, occurredAt: string | undefined): Promise<{
+    row: Record<string, unknown>;
+    modified: boolean;
+    skipped: boolean;
+}>;
+export declare function listFunctions(root?: string): Array<Record<string, unknown>>;
+export declare function functionsMatchingEvent(eventName: string, root?: string): Array<Record<string, unknown>>;
+export declare function functionsCancelledByEvent(eventName: string, root?: string): Array<Record<string, unknown>>;
+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 declare function findIdempotentEvent(name: string, idempotencyId: string, root?: string): Record<string, unknown> | undefined;
+export declare function recordEvent(input: SendEventInput, root: string | undefined, occurredAt: string | undefined): Promise<{
+    id: string;
+    deduped: boolean;
+}>;
+export declare function createRun(functionId: string, eventId: string, root: string | undefined, occurredAt: string | undefined): Promise<Record<string, unknown>>;
+export declare function runsForEvent(eventId: string, root?: string): Array<Record<string, unknown>>;
+export declare function runsForFunction(functionId: string, root?: string): Array<Record<string, unknown>>;
+/** 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 declare function cancelRunsForFunction(functionId: string, root: string | undefined, occurredAt: string | undefined): Promise<Record<string, unknown>[]>;
+export declare function getStep(runId: string, stepId: string, root?: string): Record<string, unknown> | undefined;
+export declare function stepsForRun(runId: string, root?: string): Array<Record<string, unknown>>;
+/** 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 declare function priorOutputs(runId: string, plan: DeclaredStep[], uptoIndex: number, root?: string): Record<string, unknown>;
+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 declare function advanceRun(runId: string, root: string | undefined, occurredAt: string | undefined): Promise<AdvanceResult | undefined>;

package/dist/src/inngest-runtime.js

@@ -0,0 +1,329 @@
+// 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';
+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, id) {
+    return `${type}:${id}`;
+}
+export function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+// ── canonical JSON + deterministic stub hashing (ported convention: fal-twin.ts:186-195) ──────
+export function canonicalJson(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    const keys = Object.keys(v).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(v[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, stepId, input) {
+    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, seed) {
+    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) {
+    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, root) {
+    const prefix = `${type}:`;
+    return projectResources(SERVICE, root)
+        .filter((r) => r.type === type && r.id.startsWith(prefix) && r._deleted !== true)
+        .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
+}
+export function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+function view(r) {
+    const { type: _t, updatedAt: _u, ...rest } = r;
+    const out = {};
+    for (const [k, v] of Object.entries(rest))
+        if (!k.startsWith('_'))
+            out[k] = v;
+    return out;
+}
+export async function write(type, id, fields, op, root, occurredAt) {
+    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, root, occurredAt) {
+    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: f.triggers, step_plan: f.step_plan, config: f.config, cancel_on: f.cancel_on, url: f.url,
+    });
+    if (existing) {
+        const prev = comparable(existing);
+        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) {
+    return rows('function', root);
+}
+export function functionsMatchingEvent(eventName, root) {
+    return listFunctions(root).filter((f) => f.triggers.some((t) => t.event === eventName));
+}
+export function functionsCancelledByEvent(eventName, root) {
+    return listFunctions(root).filter((f) => (f.cancel_on ?? []).some((c) => c.event === eventName));
+}
+/** 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, idempotencyId, root) {
+    return rows('event', root).find((e) => e.name === name && e.idempotency_id === idempotencyId);
+}
+export async function recordEvent(input, root, occurredAt) {
+    if (input.id) {
+        const dup = findIdempotentEvent(input.name, input.id, root);
+        if (dup)
+            return { id: dup.id, 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, eventId, root, occurredAt) {
+    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, root) {
+    return rows('run', root).filter((r) => r.event_id === eventId);
+}
+export function runsForFunction(functionId, root) {
+    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, root, occurredAt) {
+    const cancelled = [];
+    for (const run of runsForFunction(functionId, root)) {
+        if (TERMINAL_STATUSES.has(run.status))
+            continue;
+        const updated = await write('run', run.id, { status: 'CANCELLED', ended_at: nowIso(occurredAt) }, 'run.cancel_via_event', root, occurredAt);
+        cancelled.push(updated);
+    }
+    return cancelled;
+}
+// ── the step machine ───────────────────────────────────────────────────────────────────────────
+function stepRowId(runId, stepId) {
+    return `${runId}::${stepId}`;
+}
+export function getStep(runId, stepId, root) {
+    return getRow('step', stepRowId(runId, stepId), root);
+}
+export function stepsForRun(runId, root) {
+    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, plan, uptoIndex, root) {
+    const out = {};
+    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;
+}
+/**
+ * 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, root, occurredAt) {
+    const run = getRow('run', runId, root);
+    if (!run)
+        return undefined;
+    const status = run.status;
+    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, 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 ?? [];
+    const cursor = run.cursor;
+    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;
+            const match = rows('event', root).find((e) => e.name === eventName && e.received_at >= 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 + 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?.retries ?? DEFAULT_MAX_ATTEMPTS;
+    const currentAttempts = (existing?.attempts ?? 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/dist/src/inngest-server.d.ts

@@ -0,0 +1,14 @@
+/** Options every Inngest-twin HTTP surface needs, independent of who owns the socket. */
+export interface InngestTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createInngestTwinFetch(options?: InngestTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createInngestTwinServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/inngest-server.js

@@ -0,0 +1,42 @@
+// 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.js";
+import { rows } from "./inngest-runtime.js";
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+export function createInngestTwinFetch(options = {}) {
+    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 = {}) {
+    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) };
+}