@volter/twin-inngest 0.1.0

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

@@ -0,0 +1,32 @@
+export declare class InngestSignatureError extends Error {
+    constructor(message: string);
+}
+/** The kernel resource type the key is stored as — declared in `pack.resources` and mirrored by
+ *  inngest-twin.ts's `INNGEST_RESOURCE_TYPES`. */
+export declare const INNGEST_SIGNING_KEY_TYPE = "signing_key";
+/** The root's established signing key, or undefined on a world that has never touched one.
+ *  Pure read — never writes, so a read-only serve can ask. */
+export declare function storedInngestSigningKey(root?: string): string | undefined;
+/** A freshly minted key in the real `signkey-prod-<64 hex chars>` shape — the SHAPE the old
+ *  per-root derivation served (so a `removeSigningKeyPrefix`-style strip still round-trips it
+ *  exactly as a real signing key would), now drawn from real entropy. */
+export declare function mintInngestSigningKey(): string;
+/**
+ * The root's signing key, established on first use and stable forever after — across calls AND
+ * across processes. Minted from real entropy (Inngest's protocol offers nothing to seed from — see
+ * the header) and persisted as the declared `signing_key` resource through the kernel action log.
+ */
+export declare function inngestSigningKey(root?: string): Promise<string>;
+/** Sign a request body: HMAC-SHA256(stripPrefix(signingKey), canonicalJson(body) + timestamp),
+ *  hex digest — real crypto, not a stub. */
+export declare function signInngestRequest(body: unknown, timestamp: number, signingKey: string): string;
+/** Build the real `x-inngest-signature` header value: `t=<unix_seconds>&s=<hex_hmac>` (SDK-source
+ *  grounded format, `RequestSignature`/`URLSearchParams`-compatible). */
+export declare function buildInngestSignatureHeader(body: unknown, timestamp: number, signingKey: string): string;
+/** Verify a request's `x-inngest-signature` header against a signing key. Throws
+ *  `InngestSignatureError` on a missing/malformed header, an expired timestamp (>300s from
+ *  `now`), or a signature mismatch (constant-time compare). Pure — never touches the handler. */
+export declare function verifyInngestSignature(body: unknown, header: string, signingKey: string, opts?: {
+    now?: number;
+    toleranceSec?: number;
+}): void;

package/dist/src/inngest-signing.js

@@ -0,0 +1,173 @@
+// inngest EXECUTOR<->SDK REQUEST SIGNING — written FRESH for this pack (build spec §1
+// divergence 3), pure crypto, NEVER imports the twin handler (`inngest-twin.ts`) — this is what
+// makes the two mutation-test ALLOW entries (`inngest.auth.signature_hmac`,
+// `inngest.auth.signature_tamper`) legitimate: a saboteured `handleInngestTwinRequest` cannot
+// possibly affect a verify that never calls it.
+//
+// GROUNDED (2026-07-09, read-only `npm pack inngest@4.12.0` — the actually-installed devDep —
+// NOT just docs prose) against the compiled SDK source:
+//   - helpers/net.ts (`signDataWithKey`/`signWithHashJs`/`signWithNative`): the signed message is
+//     `canonicalize(body) + timestamp` (string concat, NOT newline-joined) — `canonicalize` is
+//     the JCS (RFC 8785) canonical-JSON `canonicalize` npm package the SDK itself depends on;
+//     this twin uses the same canonical-JSON convention every other pack in this repo already
+//     uses (`canonicalJson` in inngest-runtime.ts / fal-twin.ts's own copy) — both produce
+//     sorted-key, delimiter-stable JSON, which is what JCS guarantees for the plain-object
+//     payload shapes this twin signs (no need for the real npm `canonicalize` dependency itself).
+//   - HMAC-SHA256(key, message) -> hex digest.
+//   - `removeSigningKeyPrefix` (helpers/strings.ts): `signingKey.replace(/^signkey-[\w]+-/, '')`
+//     — strips a `signkey-<env>-` prefix before using the key bytes (matches build spec §1's
+//     "key = signing key with signkey-*- prefix removed, hex").
+//   - `RequestSignature` (components/InngestCommHandler.js): the `x-inngest-signature` header
+//     value is `t=<unix_seconds>&s=<hex_hmac>` (URLSearchParams-encoded, not a bare hex string) —
+//     genuinely different from — and MORE grounded than — the build spec's own prose guess of a
+//     bare hex signature; this pack follows the SDK-source-confirmed `t=&s=` format (deviation
+//     disclosed in the landing commit).
+//   - 5-minute (300s) freshness tolerance: `Math.abs(Date.now() - ts*1000) > 5*60*1000` rejects.
+//   - REJECT STATUS: the build spec's §3/§13⚠8 cited SDK_SPEC.md's prose as "500"; reading the
+//     ACTUAL installed SDK's `InngestCommHandler.js` shows the real client-side comm handler
+//     returns `unauthorizedResponse` (status **401**) for a signature-validation failure — a
+//     genuine, source-confirmed correction over the doc-prose guess. This twin does not yet
+//     claim a `done` status-code-parity capability either way (`auth.signature_500_reject_parity`
+//     stays `todo`, its title annotated with this 401 finding) — only the PURE crypto sign/
+//     verify/tamper-reject round-trip below is claimed `done`.
+//
+// THE SIGNING KEY IS STATE, NOT THE ROOT'S PATH. It used to be
+// `sha256('inngest-twin-signing-key:' + root)` wrapped in `signkey-prod-`: the world's DIRECTORY
+// was the key. A world COPIED to another directory then rotated its key out from under every
+// consumer that had already verified against it (R4 says snapshot/fork IS a copy of the root); an
+// addressed namespace (R7b) has no local directory to derive from at all; and anyone who knew
+// where a world sat on disk could compute the key this pack's whole executor<->SDK signing scheme
+// rests on. That is environment masquerading as state.
+//
+// A root's key is now MINTED ONCE from real entropy and persisted as the pack's declared
+// `signing_key` resource, folded through the kernel action log — so it rides snapshots/hydrate/
+// flush like every other fact this twin holds, no `node:fs` touches the serve path, and two serves
+// on one root agree across a process restart. The decide-and-append runs inside the kernel's own
+// action lock (`applyTwinWriteAtomic`), so two processes racing a first use agree on ONE key
+// rather than each signing with a key the other's state does not hold. `GET /api/v2/keys/signing`
+// is the route that establishes it on first touch (fold-on-first-touch, the idiom twilio's
+// IncomingPhoneNumbers list takes) and still answers exactly the masked constant it always did.
+//
+// There is NO trust-on-first-use seeding here, and that is a PROTOCOL FACT rather than an
+// omission: Inngest's SDK never puts its signing key on the wire — it presents
+// `Authorization: Bearer <sha256(key)>`, a one-way hash — so a virgin world has nothing to adopt.
+// (twilio seeds from the Basic pair and figma from `X-Figma-Token` because those protocols DO hand
+// the credential over; this one does not.) The key is minted instead.
+//
+// This is the runtime contract's ONE NAMED EXCEPTION to R9 (keying material generated once per
+// root and persisted, exactly like fal's ed25519 seed and twilio's AuthToken): same-root
+// byte-identical, cross-root divergent BY CONSTRUCTION — from entropy now, never from a path.
+// Nothing this pack SERVES carries the key material — the introspection route masks it, and
+// signatures ride requests the handler never emits — so the exception costs the replay nothing.
+//
+// `node:crypto` is required LAZILY (server-only), same convention as fal-webhooks.ts, so this
+// module stays browser-bundle safe.
+import { applyTwinWriteAtomic, projectResources, nodeBuiltin } from '@volter/world-core';
+function nodeCrypto() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return nodeBuiltin('node:crypto');
+}
+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(',')}}`;
+}
+export class InngestSignatureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InngestSignatureError';
+    }
+}
+const SERVICE = 'inngest';
+/** The kernel resource type the key is stored as — declared in `pack.resources` and mirrored by
+ *  inngest-twin.ts's `INNGEST_RESOURCE_TYPES`. */
+export const INNGEST_SIGNING_KEY_TYPE = 'signing_key';
+const SIGNING_KEY_SUBJECT = 'signing_key:executor';
+function readStored(resources) {
+    const row = resources.find((r) => r.type === INNGEST_SIGNING_KEY_TYPE && r.id === SIGNING_KEY_SUBJECT);
+    const key = row?.['_key'];
+    return typeof key === 'string' && key.length > 0 ? key : undefined;
+}
+/** The root's established signing key, or undefined on a world that has never touched one.
+ *  Pure read — never writes, so a read-only serve can ask. */
+export function storedInngestSigningKey(root) {
+    return readStored(projectResources(SERVICE, root));
+}
+/** A freshly minted key in the real `signkey-prod-<64 hex chars>` shape — the SHAPE the old
+ *  per-root derivation served (so a `removeSigningKeyPrefix`-style strip still round-trips it
+ *  exactly as a real signing key would), now drawn from real entropy. */
+export function mintInngestSigningKey() {
+    return `signkey-prod-${nodeCrypto().randomBytes(32).toString('hex')}`;
+}
+/**
+ * The root's signing key, established on first use and stable forever after — across calls AND
+ * across processes. Minted from real entropy (Inngest's protocol offers nothing to seed from — see
+ * the header) and persisted as the declared `signing_key` resource through the kernel action log.
+ */
+export async function inngestSigningKey(root) {
+    const fast = storedInngestSigningKey(root);
+    if (fast)
+        return fast;
+    const { value } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const existing = readStored(resources);
+        if (existing)
+            return { kind: 'skip', value: existing };
+        const minted = mintInngestSigningKey();
+        return {
+            kind: 'write',
+            value: minted,
+            write: {
+                operation: 'signing_key.create',
+                subjectType: INNGEST_SIGNING_KEY_TYPE,
+                subjectId: SIGNING_KEY_SUBJECT,
+                // `_`-prefixed fields are twin-internal: no view serves them and no store door projects
+                // this type, so the key material can never leave through the wire.
+                fields: { _key: minted },
+                actor: { kind: 'system' },
+            },
+        };
+    }, root);
+    return value;
+}
+function stripPrefix(signingKey) {
+    return signingKey.replace(/^signkey-[\w]+-/, '');
+}
+/** Sign a request body: HMAC-SHA256(stripPrefix(signingKey), canonicalJson(body) + timestamp),
+ *  hex digest — real crypto, not a stub. */
+export function signInngestRequest(body, timestamp, signingKey) {
+    const message = `${canonicalJson(body)}${timestamp}`;
+    return nodeCrypto().createHmac('sha256', stripPrefix(signingKey)).update(message).digest('hex');
+}
+/** Build the real `x-inngest-signature` header value: `t=<unix_seconds>&s=<hex_hmac>` (SDK-source
+ *  grounded format, `RequestSignature`/`URLSearchParams`-compatible). */
+export function buildInngestSignatureHeader(body, timestamp, signingKey) {
+    const sig = signInngestRequest(body, timestamp, signingKey);
+    return `t=${timestamp}&s=${sig}`;
+}
+function parseHeader(header) {
+    const params = new URLSearchParams(header);
+    const t = Number(params.get('t'));
+    const s = params.get('s') ?? '';
+    if (!Number.isFinite(t) || !s)
+        throw new InngestSignatureError(`Invalid x-inngest-signature header: "${header}"`);
+    return { t, s };
+}
+/** Verify a request's `x-inngest-signature` header against a signing key. Throws
+ *  `InngestSignatureError` on a missing/malformed header, an expired timestamp (>300s from
+ *  `now`), or a signature mismatch (constant-time compare). Pure — never touches the handler. */
+export function verifyInngestSignature(body, header, signingKey, opts = {}) {
+    const { t, s } = parseHeader(header);
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const tolerance = opts.toleranceSec ?? 300;
+    if (Math.abs(now - t) > tolerance)
+        throw new InngestSignatureError(`Signature timestamp outside the ${tolerance}s tolerance.`);
+    const expected = signInngestRequest(body, t, signingKey);
+    const a = Buffer.from(expected, 'hex');
+    const b = Buffer.from(s, 'hex');
+    const ok = a.length === b.length && a.length > 0 && nodeCrypto().timingSafeEqual(a, b);
+    if (!ok)
+        throw new InngestSignatureError('Signature verification failed.');
+}

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

@@ -0,0 +1,30 @@
+export type InngestRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    host?: string;
+    headers?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+};
+export type InngestResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare const INNGEST_RESOURCE_TYPES: readonly ["event", "function", "run", "step", "signing_key"];
+export type InngestResourceType = typeof INNGEST_RESOURCE_TYPES[number];
+export type InngestSurface = 'event' | 'exec' | 'api';
+export declare function routeInngestSurface(req: {
+    host?: string;
+    headers?: Record<string, string>;
+    path: string;
+    method?: string;
+}): InngestSurface;
+export declare function handleInngestTwinRequest(req: InngestRequest): Promise<InngestResponse>;
+export type InngestTwinSnapshot = {
+    resourceTypes: readonly InngestResourceType[];
+    implementedEndpoints: readonly string[];
+};
+export declare function inngestTwinSnapshot(): InngestTwinSnapshot;

package/dist/src/inngest-twin.js

@@ -0,0 +1,332 @@
+// Inngest API twin REQUEST HANDLER — a v1 slice of Inngest's durable workflow-orchestration
+// surface, backed by the event/action-log kernel (@volter/world-core). Contract:
+//   handleInngestTwinRequest({ method, path, body, host?, headers, root, readOnly }) -> { status, body, headers }
+//
+// SOURCE OF TRUTH: grounded read-only (2026-07-09) against three independent sources —
+// inngest.com/docs (event/serving/cancellation pages), the ACTUALLY-INSTALLED `inngest@4.12.0`
+// npm package's own compiled source (`npm pack`, read-only — not just its docs), and the
+// first-party v2 REST OpenAPI document fetched LIVE from `api-docs.inngest.com/api-specs/v2.json`
+// (unauthenticated GET). See spec-sources.json for the full citation + every correction this
+// build made over the build spec's own doc-prose assumptions (§13 ⚠1/⚠2/⚠6/⚠8 below).
+//
+// THREE API SURFACES + host/path split (build spec §1 divergence 2), routed by
+// `routeInngestSurface`:
+//   'event' — POST /e/{eventKey}      the real Event API (SDK-source grounded: `Inngest.send()`
+//                                      builds `new URL('e/'+eventKey, eventBaseUrl)`).
+//   'exec'  — /api/inngest, /fn/register   the SDK execution protocol: GET introspects, PUT
+//                                      registers, POST (twin-only simplification, see below)
+//                                      advances a run's step machine.
+//   'api'   — /api/v2/*                the dev-server/cloud REST management API — GROUNDED at
+//                                      this exact path from the live-fetched v2 OpenAPI document
+//                                      (`servers[1].url == "http://localhost:8288/api/v2"`),
+//                                      correcting the build spec's speculative `/v1/*` guess
+//                                      (⚠2 resolution, disclosed in the landing commit).
+//
+// THE STEP MACHINE (honesty, mirrors fal's generative-stub pattern): this twin does NOT execute
+// user code. `POST /api/inngest` — which in the real protocol is INNGEST
+// calling INTO a running app to execute one step — has no real app to call here, so this twin
+// repurposes it as the run-advance trigger: given a `{runId}`, it performs one poll-fold step of
+// `advanceRun` (inngest-runtime.ts) against that run's DECLARED step plan. `GET /api/v2/runs/
+// {runId}` ALSO drives one advance per call (the fal-twin.ts `progressOnce`-on-poll pattern),
+// since polling run status is the natural, vendor-faithful place a caller observes progress.
+// `exec.sdk_executor_roundtrip` (a real running app + real step functions Inngest calls into
+// over HTTP) is the filed `todo` — see README ## Coverage.
+//
+// State lives ENTIRELY in the kernel action log (inngest-runtime.ts's `write`/`rows`/`getRow`
+// wrap `applyTwinWrite`/`projectResources`) — there is NO Map/array side-store. No real Inngest
+// is ever contacted.
+//
+// Honesty (D2): an unmodeled route returns Inngest's real v2 error envelope
+// (`{errors:[{code,message}]}`, GROUNDED from the fetched v2 OpenAPI `v2ErrorResponse` schema),
+// never a fabricated success. `readOnly` rejects writes with 405.
+import { advanceRun, cancelRunsForFunction, createRun, functionsCancelledByEvent, functionsMatchingEvent, getRow, listFunctions, recordEvent, registerFunction, runsForEvent, } from "./inngest-runtime.js";
+const SERVICE = 'inngest';
+// The subject types this twin stores and serves — the mirror of the pack descriptor's
+// `resources` (index.ts). `signing_key` IS one: the world's executor<->SDK signing key is minted
+// once from real entropy and persisted (inngest-signing.ts), and `GET /api/v2/keys/signing` is the
+// route that establishes it on first touch — so a row of that type really does exist per root.
+// What the route SERVES is still the masked constant real Inngest serves; the key material never
+// leaves.
+export const INNGEST_RESOURCE_TYPES = ['event', 'function', 'run', 'step', 'signing_key'];
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+export function routeInngestSurface(req) {
+    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    if (path.startsWith('/e/'))
+        return 'event';
+    if (path === '/api/inngest' || path === '/fn/register')
+        return 'exec';
+    if (path.startsWith('/api/v2/'))
+        return 'api';
+    return 'exec'; // default: the exec surface's own root path (introspection) is the most common bare entry point
+}
+// ── error envelopes ────────────────────────────────────────────────────────────────────────
+// v2 REST envelope GROUNDED verbatim from the live-fetched v2 OpenAPI document's own
+// `v2ErrorResponse`/`v2Error` component schemas (api-docs.inngest.com/api-specs/v2.json).
+function apiError(status, code, message) {
+    return { status, body: { errors: [{ code, message }] } };
+}
+// The Event API / exec-protocol surfaces don't share the v2 management API's envelope (they
+// predate it); modeled on the SDK's own `sendEventResponseSchema`-adjacent plain-object shape.
+function plainError(status, error) {
+    return { status, body: { error } };
+}
+// ── body helpers ───────────────────────────────────────────────────────────────────────────
+function parseJson(body) {
+    if (body === undefined || body === '')
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { __parseError: true };
+    }
+}
+function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+// ── views ──────────────────────────────────────────────────────────────────────────────────
+const RUN_STATUS_MAP = { QUEUED: 'QUEUED', RUNNING: 'RUNNING', COMPLETED: 'COMPLETED', FAILED: 'FAILED', CANCELLED: 'CANCELLED' };
+function runView(row) {
+    return {
+        id: row.id,
+        function_id: row.function_id,
+        event_id: row.event_id,
+        status: RUN_STATUS_MAP[row.status] ?? row.status,
+        cursor: row.cursor,
+        output: row.output ?? null,
+        error: row.error ?? null,
+        created_at: row.created_at,
+        started_at: row.started_at ?? null,
+        ended_at: row.ended_at ?? null,
+    };
+}
+function stepView(row) {
+    return {
+        run_id: row.run_id,
+        step_id: row.step_id,
+        op: row.op,
+        state: row.state,
+        attempts: row.attempts,
+        output: row.output ?? null,
+        error: row.error ?? null,
+    };
+}
+function functionView(row) {
+    return {
+        id: row.fn_id,
+        triggers: row.triggers,
+        steps: row.step_plan,
+        config: row.config,
+        cancel_on: row.cancel_on,
+        url: row.url ?? null,
+    };
+}
+// ── event send (Event API) ────────────────────────────────────────────────────────────────
+function normalizeSendBody(raw) {
+    if (raw === undefined)
+        return { ok: true, events: [] };
+    if (Array.isArray(raw)) {
+        if (raw.some((e) => typeof e !== 'object' || e === null))
+            return { ok: false };
+        return { ok: true, events: raw };
+    }
+    if (typeof raw === 'object' && raw !== null)
+        return { ok: true, events: [raw] };
+    return { ok: false };
+}
+async function handleSendEvents(rawBody, req) {
+    const parsed = parseJson(rawBody);
+    const normalized = normalizeSendBody(parsed);
+    if (!normalized.ok)
+        return plainError(400, 'Event payload must be an object or an array of objects.');
+    if (normalized.events.length === 0)
+        return { status: 200, body: { ids: [], status: 200 } };
+    const ids = [];
+    for (const raw of normalized.events) {
+        const name = raw.name;
+        if (typeof name !== 'string' || name.length === 0)
+            return plainError(400, 'Event payload must include a "name" (string).');
+        const { id, deduped } = await recordEvent({ name, data: raw.data, user: raw.user, id: typeof raw.id === 'string' ? raw.id : undefined, ts: typeof raw.ts === 'number' ? raw.ts : undefined, v: typeof raw.v === 'string' ? raw.v : undefined }, req.root, req.occurredAt);
+        ids.push(id);
+        if (deduped)
+            continue; // an idempotent replay never re-triggers fan-out or cancellation
+        for (const fn of functionsMatchingEvent(name, req.root)) {
+            await createRun(fn.fn_id, id, req.root, req.occurredAt);
+        }
+        for (const fn of functionsCancelledByEvent(name, req.root)) {
+            await cancelRunsForFunction(fn.fn_id, req.root, req.occurredAt);
+        }
+    }
+    // sendEventResponseSchema GROUNDED (types.js): {ids: string[], status: number, error?: string}
+    // — the real client's `.send()` throws unless `status === 200`, so this exact field is
+    // load-bearing for the SDK integration path (inngest-sdk.integration.test.ts).
+    return { status: 200, body: { ids, status: 200 } };
+}
+// ── exec surface (SDK protocol) ───────────────────────────────────────────────────────────
+function stepFromWire(raw) {
+    const id = raw.id;
+    const op = raw.op;
+    if (typeof id !== 'string' || (op !== 'StepRun' && op !== 'Sleep' && op !== 'WaitForEvent' && op !== 'InvokeFunction'))
+        return undefined;
+    const out = { id, op };
+    if (typeof raw.eventName === 'string')
+        out.eventName = raw.eventName;
+    if (typeof raw.timeoutAfterPolls === 'number')
+        out.timeoutAfterPolls = raw.timeoutAfterPolls;
+    if (typeof raw.failTimes === 'number')
+        out.failTimes = raw.failTimes;
+    if ('output' in raw)
+        out.output = raw.output;
+    return out;
+}
+async function handleRegister(rawBody, req) {
+    const parsed = parseJson(rawBody);
+    const list = parsed?.functions;
+    if (!Array.isArray(list) || list.length === 0)
+        return plainError(400, 'Register body must include a non-empty "functions" array.');
+    let anyModified = false;
+    let allSkipped = true;
+    for (const raw of list) {
+        if (typeof raw.id !== 'string')
+            return plainError(400, 'Every function must have a string "id".');
+        const triggers = Array.isArray(raw.triggers) ? raw.triggers : [];
+        const steps = Array.isArray(raw.steps) ? raw.steps.map(stepFromWire).filter((s) => s !== undefined) : [];
+        const fn = {
+            id: raw.id,
+            triggers,
+            steps,
+            config: raw.config ?? {},
+            cancelOn: Array.isArray(raw.cancelOn) ? raw.cancelOn : [],
+            url: typeof parsed?.url === 'string' ? parsed.url : undefined,
+        };
+        const { modified, skipped } = await registerFunction(fn, req.root, req.occurredAt);
+        if (modified)
+            anyModified = true;
+        if (!skipped)
+            allSkipped = false;
+    }
+    // registerResSchema GROUNDED (types.js): {status, error (default "Successfully registered"),
+    // skipped?, modified?} — the "error" field's SUCCESS default is a real, if oddly-named, wire
+    // quirk confirmed from the SDK's own compiled zod schema, not guessed.
+    return { status: 200, body: { status: 200, error: 'Successfully registered', skipped: allSkipped, modified: anyModified } };
+}
+function introspectView(req) {
+    const fns = listFunctions(req.root);
+    return {
+        status: 200,
+        body: {
+            function_count: fns.length,
+            functions: fns.map(functionView),
+            mode: 'dev',
+            sdk_language: 'js',
+            sdk_version: '4.12.0',
+            authentication_succeeded: false,
+        },
+    };
+}
+async function handleExecInvoke(rawBody, req) {
+    const parsed = parseJson(rawBody);
+    const runId = parsed?.runId;
+    if (typeof runId !== 'string')
+        return plainError(400, 'Invoke body must include "runId" (twin-only exec-protocol simplification — see inngest-twin.ts header).');
+    const result = await advanceRun(runId, req.root, req.occurredAt);
+    if (!result)
+        return apiError(404, 'run_not_found', `No run with id "${runId}".`);
+    return { status: 200, body: { run: runView(result.run), ...(result.step ? { step: stepView(result.step) } : {}) } };
+}
+// ── api surface (dev-server/cloud v2 REST management API) ────────────────────────────────
+async function handleGetRun(runId, req) {
+    const existing = getRow('run', runId, req.root);
+    if (!existing)
+        return apiError(404, 'run_not_found', `No run with id "${runId}".`);
+    const result = await advanceRun(runId, req.root, req.occurredAt); // poll-fold advance on read (fal-twin.ts progressOnce pattern)
+    const row = result?.run ?? existing;
+    return { status: 200, body: { data: runView(row), metadata: { fetchedAt: nowIso(req.occurredAt) } } };
+}
+function handleEventRuns(eventId, req) {
+    const event = getRow('event', eventId, req.root);
+    if (!event)
+        return apiError(404, 'event_not_found', `No event with id "${eventId}".`);
+    const runs = runsForEvent(eventId, req.root).map(runView);
+    return { status: 200, body: { data: runs, metadata: { fetchedAt: nowIso(req.occurredAt) }, page: { cursor: '', hasMore: false, limit: runs.length } } };
+}
+async function handleSigningKeys(req) {
+    // `GET /keys/signing` is a REAL v2 REST path (grounded from the fetched OpenAPI document). The
+    // key VALUE is deliberately masked here (real Inngest never returns raw key material over this
+    // introspection route either) — the usable key is `inngest-signing.ts`'s `inngestSigningKey`,
+    // which this route ESTABLISHES on first touch: the key is state (minted once from real entropy,
+    // persisted as the `signing_key` resource), so the introspection route for it is where a virgin
+    // world materializes it, exactly as twilio's IncomingPhoneNumbers list folds its seeded rows on
+    // first read. The import is LAZY so the signing module stays out of this file's static graph and
+    // the mutation-test ALLOW entries keep their meaning in both directions.
+    //
+    // A read-only serve does not establish it: readOnly worlds serve, they never fold. The masked
+    // body never depended on the key, so it answers identically either way.
+    if (!req.readOnly) {
+        const { inngestSigningKey } = await import("./inngest-signing.js");
+        await inngestSigningKey(req.root);
+    }
+    return { status: 200, body: { data: [{ id: 'signing-key', key: 'signkey-prod-***' }], metadata: { fetchedAt: nowIso(req.occurredAt) } } };
+}
+// ── route handler ────────────────────────────────────────────────────────────────────
+export async function handleInngestTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const [rawPath] = req.path.split('?');
+    const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+    const surface = routeInngestSurface({ host: req.host, headers: req.headers, path, method });
+    if (req.readOnly && method !== 'GET' && method !== 'HEAD') {
+        return { status: 405, body: { error: 'read_only', hint: 'this twin was started read-only; omit readOnly to accept writes' } };
+    }
+    if (path === '/' || path === '') {
+        return { status: 200, body: { service: 'inngest', object: 'twin' } };
+    }
+    if (surface === 'event') {
+        if (method === 'POST')
+            return handleSendEvents(req.body, req);
+        return plainError(404, 'not found');
+    }
+    if (surface === 'exec') {
+        if ((method === 'PUT' && path === '/api/inngest') || (method === 'POST' && path === '/fn/register')) {
+            return handleRegister(req.body, req);
+        }
+        if (method === 'GET' && path === '/api/inngest')
+            return introspectView(req);
+        if (method === 'POST' && path === '/api/inngest')
+            return handleExecInvoke(req.body, req);
+        return plainError(404, 'not found');
+    }
+    // surface === 'api'  (/api/v2/*)
+    const seg = path.replace(/^\/+/, '').split('/').filter(Boolean); // ['api','v2', ...]
+    const rest = seg.slice(2);
+    if (method === 'GET' && rest[0] === 'runs' && rest.length === 2)
+        return handleGetRun(decodeURIComponent(rest[1]), req);
+    if (method === 'GET' && rest[0] === 'events' && rest.length === 3 && rest[2] === 'runs')
+        return handleEventRuns(decodeURIComponent(rest[1]), req);
+    if (method === 'GET' && rest[0] === 'keys' && rest[1] === 'signing')
+        return handleSigningKeys(req);
+    return apiError(404, 'not_found', `No route for ${method} ${path}`);
+}
+// Endpoint inventory used by the conformance snapshot (self-referential — see
+// inngest-conformance.ts header note and docs/contributing/conformance.md's "2 spec" discussion of this pattern,
+// shared with replicate/elevenlabs/polar/fal/pinecone/algolia).
+export function inngestTwinSnapshot() {
+    return {
+        resourceTypes: INNGEST_RESOURCE_TYPES,
+        implementedEndpoints: [
+            'POST /e/{eventKey} (event send, single or batch)',
+            'PUT /api/inngest (function register)',
+            'POST /fn/register (function register, real SDK outbound target)',
+            'GET /api/inngest (introspection)',
+            'POST /api/inngest (twin exec-protocol simplification: run advance)',
+            'GET /api/v2/runs/{runId} (run get, poll-fold advance)',
+            'GET /api/v2/runs/{runId} (404 unknown run)',
+            'GET /api/v2/events/{eventId}/runs (runs for an event)',
+            'GET /api/v2/keys/signing',
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/twin-inngest",
+  "version": "0.1.0",
+  "description": "Local Inngest twin for the durable-execution workflow-orchestration surface: event send/batch (Event API), function register/introspect (SDK exec protocol), and a REAL kernel-persisted step-machine (step.run memoize/replay, sleep/sleepUntil instant-advance, waitForEvent gating, exact retry-attempt counters), run status/get/list/cancel-via-event, HMAC-SHA256 executor<->SDK request signing, built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/inngest"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/inngest#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-inngest": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "inngest": "4.12.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-inngest CLI: serve the KERNEL-BACKED Inngest API twin, or run conformance. State
+// lives in the @volter/world-core action log (no in-memory side-store). Conformance is dev-only +
+// lazy-imported so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createInngestTwinServer } from './inngest-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createInngestTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`inngest twin (durable-execution workflow orchestration: events/functions/runs/steps, host/path split)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkInngestConformance } = await import('./inngest-conformance.ts');
+  const report = checkInngestConformance();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-inngest serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}