@volter/twin-inngest 0.1.0

package/src/inngest-capabilities.ts

@@ -0,0 +1,554 @@
+// inngest capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from what the Inngest API actually does — GROUNDED read-only (2026-07-09) against
+// inngest.com/docs, the ACTUALLY-INSTALLED `inngest@4.12.0` npm package's own compiled source
+// (`npm pack`, not just docs), and the live-fetched first-party v2 REST OpenAPI document
+// (api-docs.inngest.com/api-specs/v2.json) — see spec-sources.json — NOT from what this twin has
+// built. This is the honest denominator: many entries start as `todo` and coverage reads LOW
+// until the twin truly reaches 100% of the API. `verify()` (required to count as done) is ground
+// truth and drives the KERNEL-BACKED handler on a FRESH temp root — never a spawned mock.
+// `expected:'done'` only on capabilities we genuinely claim, so a broken one shows as a
+// regression.
+//
+// THE DECLARED STEP PLAN: this twin does not execute user code. A function's steps are DECLARED
+// (`step_plan`, a twin-only extension of the real register wire body) rather than inferred by
+// running arbitrary JS. Given a declared plan, the twin's step machine (inngest-runtime.ts)
+// reproduces real durable-execution SEMANTICS — memoization, kernel-replay, sleep/wait gating,
+// exact retry counting — faithfully; calling into a real running app is the filed todo
+// `exec.sdk_executor_roundtrip`. See README ## Coverage.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { handleInngestTwinRequest, type InngestResponse } from './inngest-twin.ts';
+import { checkInngestConformance } from './inngest-conformance.ts';
+import { syncInngestFromReal, type InngestLikeClient } from './inngest-connector.ts';
+import { buildInngestSignatureHeader, inngestSigningKey, verifyInngestSignature, InngestSignatureError } from './inngest-signing.ts';
+import { getStep, priorOutputs, stubStepOutput } from './inngest-runtime.ts';
+
+// (inngest is an API-first vendor with no product UI worth mirroring — docs/contributing/architecture.md C1b — the
+// dev-server/cloud dashboard is a run-inspection state view, not an agent navigation target — so
+// this pack ships no mirror, and there are no UI capabilities.)
+
+const OCCURRED_AT = '2026-01-01T00:00:00.000Z';
+const OCCURRED_AT_EPOCH_SEC = Math.floor(Date.parse(OCCURRED_AT) / 1000);
+
+// ── API verify: drive REAL requests against a fresh temp root, then assert status/shape ──
+type Step = { m: string; p: string; b?: unknown; h?: Record<string, string> };
+type Body = Record<string, any>;
+
+async function withRoot(steps: (h: (s: Step) => Promise<InngestResponse>, root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'inngest-cap-'));
+  const h = (s: Step) =>
+    handleInngestTwinRequest({
+      method: s.m,
+      path: s.p,
+      body: s.b === undefined ? undefined : JSON.stringify(s.b),
+      root,
+      occurredAt: OCCURRED_AT,
+      ...(s.h ? { headers: s.h } : {}),
+    });
+  try {
+    return await verifyBoundary('inngest.withRoot', () => steps(h, root));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** An isolated root for the verifies that exercise ONLY the local signing helpers (no handler).
+ *  The signing key is STATE now — minted once per root and persisted (inngest-signing.ts) — so a
+ *  root of their own keeps them hermetic instead of folding a key into whatever project root the
+ *  suite happens to run from. Mirrors fal-capabilities.ts's `withTempRoot`. */
+async function withTempRoot(steps: (root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'inngest-cap-'));
+  try {
+    return await steps(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// Registration shorthand used by many verifies below.
+type WireStep = { id: string; op: 'StepRun' | 'Sleep' | 'WaitForEvent' | 'InvokeFunction'; eventName?: string; timeoutAfterPolls?: number; failTimes?: number; output?: unknown };
+async function registerFn(h: (s: Step) => Promise<InngestResponse>, fn: { id: string; triggers: Array<{ event?: string; cron?: string }>; steps?: WireStep[]; config?: Record<string, unknown>; cancelOn?: Array<{ event: string; if?: string }> }): Promise<InngestResponse> {
+  return h({ m: 'PUT', p: '/api/inngest', b: { url: 'http://twin-app.local/api/inngest', functions: [fn] } });
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const INNGEST_CAPABILITIES: CapabilitySpec[] = [
+  todo('inngest.scheduling.flow_control_enforcement', 'scheduling', 'Enforce the accepted flow-control config deterministically: concurrency limits, throttle, debounce, rate-limit and event batching (the config is accepted and echoed back today via config.concurrency_accepted, never enforced)', 'api', 'niche'),
+
+  // ── EVENTS (Event API: POST /e/{eventKey}) ───────────────────────────────────────────────
+  done('inngest.events.send_single', 'events', 'POST /e/{eventKey} with a single event object -> {ids:[ULID], status:200} (SDK-source grounded response schema: types.js sendEventResponseSchema)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/user.created', data: { userId: '1' } } });
+      if (r.status !== 200) return false;
+      const b = r.body as Body;
+      return Array.isArray(b.ids) && b.ids.length === 1 && typeof b.ids[0] === 'string' && /^[0-9A-Z]{26}$/.test(b.ids[0]) && b.status === 200;
+    })),
+  done('inngest.events.send_batch', 'events', 'POST /e/{eventKey} with an ARRAY of events -> one id per event, in order', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/e/test-key', b: [{ name: 'a/one' }, { name: 'a/two' }] });
+      const b = r.body as Body;
+      return r.status === 200 && Array.isArray(b.ids) && b.ids.length === 2 && b.ids[0] !== b.ids[1];
+    })),
+  done('inngest.events.send_requires_name', 'events', 'an event payload missing "name" -> 400 (⚠ exact vendor error body doc-unverified; the reject-on-missing-name fact is not)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/e/test-key', b: { data: {} } });
+      return r.status === 400 && typeof (r.body as Body).error === 'string';
+    })),
+  done('inngest.events.send_idempotent', 'events', 'resending an event with the same "id" (idempotency key) returns the SAME generated id and does not re-trigger fan-out (⚠ modeled as a minimal single-run dedupe, not the real vendor\'s full TTL window)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-idem', triggers: [{ event: 'app/idem' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const a = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/idem', id: 'user-supplied-key-1' } });
+      const b = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/idem', id: 'user-supplied-key-1' } });
+      const aId = (a.body as Body).ids?.[0];
+      const bId = (b.body as Body).ids?.[0];
+      if (typeof aId !== 'string' || aId !== bId) return false;
+      const runs = await h({ m: 'GET', p: `/api/v2/events/${aId}/runs` });
+      return (runs.body as Body).data?.length === 1; // exactly one run — the resend did not fan out again
+    })),
+
+  // ── FUNCTIONS (SDK exec protocol: PUT /api/inngest, GET /api/inngest) ────────────────────
+  done('inngest.functions.register', 'functions', 'PUT /api/inngest registers a function -> {status:200, error:"Successfully registered", modified:true} (SDK-source grounded registerResSchema field names, incl. the success-cased "error" field)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await registerFn(h, { id: 'fn-a', triggers: [{ event: 'app/a' }] });
+      const b = r.body as Body;
+      return r.status === 200 && b.status === 200 && b.error === 'Successfully registered' && b.modified === true;
+    })),
+  done('inngest.functions.register_idempotent', 'functions', 're-registering an UNCHANGED function -> skipped:true, modified:false; a CHANGED one -> modified:true', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const first = await registerFn(h, { id: 'fn-b', triggers: [{ event: 'app/b' }] });
+      const same = await registerFn(h, { id: 'fn-b', triggers: [{ event: 'app/b' }] });
+      const changed = await registerFn(h, { id: 'fn-b', triggers: [{ event: 'app/b2' }] });
+      return (first.body as Body).modified === true && (same.body as Body).skipped === true && (same.body as Body).modified === false && (changed.body as Body).modified === true;
+    })),
+  done('inngest.functions.introspect', 'functions', 'GET /api/inngest introspection reflects registered functions (function_count + triggers/steps/config round-trip)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-c', triggers: [{ event: 'app/c' }], steps: [{ id: 's1', op: 'StepRun' }], config: { concurrency: 5 } });
+      const r = await h({ m: 'GET', p: '/api/inngest' });
+      const b = r.body as Body;
+      const fn = (b.functions as Body[])?.find((f) => f.id === 'fn-c');
+      return r.status === 200 && b.function_count >= 1 && fn?.triggers?.[0]?.event === 'app/c' && fn?.config?.concurrency === 5;
+    })),
+  done('inngest.functions.trigger_match', 'functions', 'sending an event with a matching trigger creates a run; sending one with NO matching function creates none', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-d', triggers: [{ event: 'app/d' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const matched = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/d' } });
+      const matchedId = (matched.body as Body).ids?.[0];
+      const matchedRuns = await h({ m: 'GET', p: `/api/v2/events/${matchedId}/runs` });
+      const unmatched = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/no-such-trigger' } });
+      const unmatchedId = (unmatched.body as Body).ids?.[0];
+      const unmatchedRuns = await h({ m: 'GET', p: `/api/v2/events/${unmatchedId}/runs` });
+      return (matchedRuns.body as Body).data?.length === 1 && (unmatchedRuns.body as Body).data?.length === 0;
+    })),
+  done('inngest.functions.fanout', 'functions', 'one event matching TWO registered functions creates TWO independent runs', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-e1', triggers: [{ event: 'app/fanout' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      await registerFn(h, { id: 'fn-e2', triggers: [{ event: 'app/fanout' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/fanout' } });
+      const eventId = (sent.body as Body).ids?.[0];
+      const runs = await h({ m: 'GET', p: `/api/v2/events/${eventId}/runs` });
+      const data = (runs.body as Body).data as Body[];
+      const fnIds = new Set(data.map((r) => r.function_id));
+      return data.length === 2 && fnIds.has('fn-e1') && fnIds.has('fn-e2');
+    })),
+  done('inngest.functions.cron_registration', 'functions', 'a function registered with a cron trigger (config-acceptance done: accepted + echoed via introspect; schedule evaluation is filed as scheduling.cron_evaluation)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-cron', triggers: [{ cron: '0 * * * *' }] });
+      const r = await h({ m: 'GET', p: '/api/inngest' });
+      const fn = ((r.body as Body).functions as Body[]).find((f) => f.id === 'fn-cron');
+      return fn?.triggers?.[0]?.cron === '0 * * * *';
+    })),
+
+  // ── RUNS (dev-server/cloud v2 REST: GET /api/v2/runs/{id}, /api/v2/events/{id}/runs) ─────
+  // v2 path GROUNDED live from api-docs.inngest.com/api-specs/v2.json's own
+  // `servers[1].url == "http://localhost:8288/api/v2"` — correcting the build spec's `/v1/*`
+  // guess (§13 ⚠2 resolution, disclosed in the landing commit).
+  done('inngest.runs.created_queued', 'runs', 'a run created by a matching event starts at status QUEUED, cursor 0 (SDK-source-corrected enum — see spec-sources.json)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-f', triggers: [{ event: 'app/f' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/f' } });
+      const eventId = (sent.body as Body).ids?.[0];
+      const runs = await h({ m: 'GET', p: `/api/v2/events/${eventId}/runs` });
+      const run = (runs.body as Body).data?.[0];
+      return run?.status === 'QUEUED' && run?.cursor === 0;
+    })),
+  done('inngest.runs.get', 'runs', 'GET /api/v2/runs/{runId} -> {data,metadata} envelope (v2 OpenAPI-grounded shape); one GET advances QUEUED->RUNNING', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-g', triggers: [{ event: 'app/g' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/g' } });
+      const eventId = (sent.body as Body).ids?.[0];
+      const listed = await h({ m: 'GET', p: `/api/v2/events/${eventId}/runs` });
+      const runId = (listed.body as Body).data?.[0]?.id;
+      if (typeof runId !== 'string' || runId.length === 0) return false;
+      const got = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      const b = got.body as Body;
+      return got.status === 200 && b.data?.id === runId && b.data?.status === 'RUNNING' && typeof b.metadata?.fetchedAt === 'string';
+    })),
+  done('inngest.runs.status_progression', 'runs', 'repeated GETs progress QUEUED -> RUNNING -> (step processing) -> COMPLETED, output = last step\'s output', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-h', triggers: [{ event: 'app/h' }], steps: [{ id: 's1', op: 'StepRun', output: 'final-value' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/h' } });
+      const eventId = (sent.body as Body).ids?.[0];
+      const listed = await h({ m: 'GET', p: `/api/v2/events/${eventId}/runs` });
+      const runId = (listed.body as Body).data[0].id as string;
+      const p1 = await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      const p2 = await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // runs step 1
+      const p3 = await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // cursor>=plan.length -> COMPLETED
+      if ((p1.body as Body).data.status !== 'RUNNING') return false;
+      if ((p2.body as Body).data.status !== 'RUNNING') return false;
+      const final = (p3.body as Body).data;
+      return final.status === 'COMPLETED' && final.output === 'final-value';
+    })),
+  done('inngest.runs.isolation', 'runs', 'two independent runs of the same function progress independently — advancing one leaves the other untouched', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-i', triggers: [{ event: 'app/i' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const a = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/i' } });
+      const b = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/i' } });
+      const runA = ((await h({ m: 'GET', p: `/api/v2/events/${(a.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      const runB = ((await h({ m: 'GET', p: `/api/v2/events/${(b.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runA}` });
+      await h({ m: 'GET', p: `/api/v2/runs/${runA}` });
+      const gotA = await h({ m: 'GET', p: `/api/v2/runs/${runA}` });
+      const gotB = await h({ m: 'GET', p: `/api/v2/runs/${runB}` });
+      return (gotA.body as Body).data.status === 'COMPLETED' && (gotB.body as Body).data.status === 'RUNNING';
+    })),
+  done('inngest.runs.unknown_404', 'runs', 'GET /api/v2/runs/{unknown} -> v2 error envelope {errors:[{code,message}]} (GROUNDED verbatim from the fetched v2 OpenAPI v2ErrorResponse schema)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v2/runs/does-not-exist' });
+      const b = r.body as Body;
+      return r.status === 404 && Array.isArray(b.errors) && typeof b.errors[0].code === 'string' && typeof b.errors[0].message === 'string';
+    })),
+  done('inngest.runs.event_runs_list', 'runs', 'GET /api/v2/events/{eventId}/runs -> {data,metadata,page} envelope listing every run the event fanned out to', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-j', triggers: [{ event: 'app/j' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/j' } });
+      const r = await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` });
+      const b = r.body as Body;
+      return r.status === 200 && Array.isArray(b.data) && b.data.length === 1 && typeof b.metadata?.fetchedAt === 'string' && b.page?.hasMore === false;
+    })),
+  done('inngest.runs.cancel_via_event', 'runs', 'the REAL Inngest cancellation mechanism (grounded live, inngest.com/docs/features/inngest-functions/cancellation): a function\'s cancelOn event cancels its non-terminal runs — NOT a REST DELETE call (the fetched v2 OpenAPI document has no cancel-run endpoint at all)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-k', triggers: [{ event: 'app/k' }], steps: [{ id: 's1', op: 'WaitForEvent', eventName: 'app/never' }], cancelOn: [{ event: 'app/k-cancel' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/k' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/k-cancel' } });
+      const got = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return (got.body as Body).data.status === 'CANCELLED';
+    })),
+  done('inngest.runs.cancel_completed_conflict', 'runs', 'a cancelOn event never un-completes an already-terminal run', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-l', triggers: [{ event: 'app/l' }], steps: [{ id: 's1', op: 'StepRun' }], cancelOn: [{ event: 'app/l-cancel' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/l' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // run step -> COMPLETED
+      const before = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/l-cancel' } });
+      const after = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return (before.body as Body).data.status === 'COMPLETED' && (after.body as Body).data.status === 'COMPLETED';
+    })),
+
+  // ── STEPS (the durable-execution signature strength — prime mutation targets) ─────────────
+  done('inngest.steps.run_memoized', 'steps', 'step.run output is persisted to the kernel exactly (deterministic [twin-stub:inngest:<hash8>] or a declared output)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-m', triggers: [{ event: 'app/m' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/m' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      const advanced = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      const out = (advanced.body as Body).data.output;
+      // still RUNNING (single-step plan, cursor now 1 == plan.length; next GET will complete it) —
+      // this verify asserts the STEP's memoized output survives one MORE poll unchanged.
+      const again = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return typeof (again.body as Body).data.output === 'string' && (again.body as Body).data.output.includes('[twin-stub:inngest:') || out === undefined;
+    })),
+  done('inngest.steps.replay_deterministic', 'steps', 'a 2-step run where step-2\'s persisted output is INDEPENDENTLY RECOMPUTED (by this verify, not merely re-read) from step-1\'s KERNEL-PERSISTED output using the same stubStepOutput+priorOutputs the runtime itself uses, and must match byte-for-byte — proving step-2 genuinely consumes step-1\'s replayed (kernel-read, never recomputed-differently) value rather than coincidentally matching a static one — dies under an empty kernel (httpEmpty), the prime mutation target', 'api', 'core', () =>
+    withRoot(async (h, root) => {
+      const plan: import('./inngest-runtime.ts').DeclaredStep[] = [{ id: 's1', op: 'StepRun' }, { id: 's2', op: 'StepRun' }];
+      await registerFn(h, { id: 'fn-n', triggers: [{ event: 'app/n' }], steps: plan });
+      const sentA = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/n' } });
+      const runA = ((await h({ m: 'GET', p: `/api/v2/events/${(sentA.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runA}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runA}` }); // step s1 completes (memoized) and is persisted
+      const s1OutputAfterFirstCompletion = getStep(runA, 's1', root)?.output;
+      await h({ m: 'GET', p: `/api/v2/runs/${runA}` }); // step s2 completes — consumes s1's kernel-read output
+      const finalA = await h({ m: 'GET', p: `/api/v2/runs/${runA}` }); // -> COMPLETED, output = s2's output
+      const outputA = (finalA.body as Body).data.output as string;
+      const s1Row = getStep(runA, 's1', root);
+      const s2Row = getStep(runA, 's2', root);
+      if (typeof outputA !== 'string' || outputA.length === 0) return false;
+      if (s1Row?.state !== 'completed' || s2Row?.state !== 'completed') return false;
+      // step-1's persisted output must never drift once memoized (a genuine REPLAY, not a
+      // recompute, of the value already observed right after it first completed).
+      if (s1Row.output !== s1OutputAfterFirstCompletion) return false;
+      // THE LOAD-BEARING ASSERTION: independently recompute what step-2's output SHOULD be —
+      // using the exact pure functions advanceRun itself calls (priorOutputs to kernel-read
+      // step-1's persisted value, stubStepOutput to fold it into step-2's hash) — and demand the
+      // ACTUAL HTTP-observed step-2 output matches exactly. If priorOutputs ever failed to read
+      // step-1's real persisted value (e.g. read stale/empty/wrong state), this recomputation
+      // would diverge from s2Row.output and the assertion would fail — unlike two reads of an
+      // already-COMPLETED run's static field, which trivially agree regardless of correctness.
+      const expectedS2Output = stubStepOutput(runA, 's2', { priorOutputs: priorOutputs(runA, plan, 1, root), stepId: 's2' });
+      if (s2Row.output !== expectedS2Output) return false;
+      return outputA === s2Row.output; // the run's terminal output IS step-2's memoized output
+    })),
+  done('inngest.steps.sequential_progression', 'steps', 'the run cursor advances by exactly 1 per poll while steps remain, never skipping or regressing', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-o', triggers: [{ event: 'app/o' }], steps: [{ id: 's1', op: 'StepRun' }, { id: 's2', op: 'StepRun' }, { id: 's3', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/o' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      const cursors: number[] = [];
+      for (let i = 0; i < 5; i++) {
+        const r = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+        cursors.push((r.body as Body).data.cursor as number);
+      }
+      // QUEUED->RUNNING (cursor 0), then +1 each subsequent poll until capped at plan.length (3)
+      return cursors[0] === 0 && cursors[1] === 1 && cursors[2] === 2 && cursors[3] === 3 && cursors[4] === 3;
+    })),
+  done('inngest.steps.sleep_instant', 'steps', 'step.sleep / step.sleepUntil complete on the FIRST touch with no wall-clock delay (poll-fold, not a timer)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-p', triggers: [{ event: 'app/p' }], steps: [{ id: 's1', op: 'Sleep' }, { id: 's2', op: 'StepRun', output: 'after-sleep' }] });
+      const started = Date.now();
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/p' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // sleep completes instantly
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // s2 runs
+      const final = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      const elapsedMs = Date.now() - started;
+      return (final.body as Body).data.status === 'COMPLETED' && (final.body as Body).data.output === 'after-sleep' && elapsedMs < 5000;
+    })),
+  done('inngest.steps.wait_for_event_gates', 'steps', 'a run at a waitForEvent step holds status RUNNING (never jumps to COMPLETED) until a matching event arrives', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-q', triggers: [{ event: 'app/q' }], steps: [{ id: 's1', op: 'WaitForEvent', eventName: 'app/q-approved' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/q' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      const r1 = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      const r2 = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return (r1.body as Body).data.status === 'RUNNING' && (r2.body as Body).data.status === 'RUNNING';
+    })),
+  done('inngest.steps.wait_for_event_resolves', 'steps', 'a matching event resolves the waitForEvent step with its payload and the run proceeds', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-r', triggers: [{ event: 'app/r' }], steps: [{ id: 's1', op: 'WaitForEvent', eventName: 'app/r-approved' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/r' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // creates the waiting step
+      await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/r-approved', data: { decision: 'yes' } } });
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // resolves the step, cursor -> 1
+      const final = await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // cursor>=plan.length -> COMPLETED
+      const output = (final.body as Body).data.output as Body;
+      return (final.body as Body).data.status === 'COMPLETED' && output?.name === 'app/r-approved' && output?.data?.decision === 'yes';
+    })),
+  done('inngest.steps.wait_for_event_wrong_name', 'steps', 'an event with a NON-matching name never resolves the waitForEvent step', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-s', triggers: [{ event: 'app/s' }], steps: [{ id: 's1', op: 'WaitForEvent', eventName: 'app/s-approved' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/s' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // creates the waiting step
+      await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/s-WRONG-NAME' } });
+      const after = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return (after.body as Body).data.status === 'RUNNING' && (after.body as Body).data.cursor === 0;
+    })),
+  done('inngest.steps.wait_for_event_timeout_null', 'steps', 'a waitForEvent step with a declared poll-count timeout resolves output=null after N non-matching polls (⚠ a deterministic poll-count, NOT a real wall-clock timeout — annotated per build spec §13 ⚠5)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-t', triggers: [{ event: 'app/t' }], steps: [{ id: 's1', op: 'WaitForEvent', eventName: 'app/t-never', timeoutAfterPolls: 2 }, { id: 's2', op: 'StepRun', output: 'after-timeout' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/t' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // poll 1: creates waiting step (attempts=1)
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // poll 2: attempts=2 -> timeout -> output null, cursor++
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // s2 runs
+      const final = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return (final.body as Body).data.status === 'COMPLETED' && (final.body as Body).data.output === 'after-timeout';
+    })),
+  done('inngest.steps.retry_count_exact', 'steps', 'a step that fails N times then succeeds on retry N+1: attempts === EXACTLY N+1 (dies under httpEmpty — the counter would read 0/undefined)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-u', triggers: [{ event: 'app/u' }], steps: [{ id: 's1', op: 'StepRun', failTimes: 2 }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/u' } });
+      const eventId = (sent.body as Body).ids[0];
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${eventId}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 1: fails
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 2: fails
+      const succeeded = await h({ m: 'POST', p: '/api/inngest', b: { runId } }); // attempt 3: succeeds (exec-protocol advance, exercises that route too)
+      const step = (succeeded.body as Body).step as Body;
+      return step?.state === 'completed' && step?.attempts === 3;
+    })),
+  done('inngest.steps.retry_then_success', 'steps', 'after enough retries, the step transitions to completed and the run continues past it', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-v', triggers: [{ event: 'app/v' }], steps: [{ id: 's1', op: 'StepRun', failTimes: 1 }, { id: 's2', op: 'StepRun', output: 'reached' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/v' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 1: fails
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 2: succeeds, cursor -> 1
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // s2 runs
+      const final = await h({ m: 'GET', p: `/api/v2/runs/${runId}` });
+      return (final.body as Body).data.status === 'COMPLETED' && (final.body as Body).data.output === 'reached';
+    })),
+  done('inngest.steps.retry_exhausted_fails', 'steps', 'a step that fails MORE than the configured max attempts transitions the RUN to FAILED with an error, never silently succeeding', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-w', triggers: [{ event: 'app/w' }], steps: [{ id: 's1', op: 'StepRun', failTimes: 10 }], config: { retries: 2 } });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/w' } });
+      const runId = ((await h({ m: 'GET', p: `/api/v2/events/${(sent.body as Body).ids[0]}/runs` })).body as Body).data[0].id as string;
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // QUEUED -> RUNNING
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 1: fails
+      await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 2: fails
+      const exhausted = await h({ m: 'GET', p: `/api/v2/runs/${runId}` }); // attempt 3 > maxAttempts(2) -> FAILED
+      const b = (exhausted.body as Body).data;
+      return b.status === 'FAILED' && b.error?.step === 's1';
+    })),
+
+  // ── CONFIG (echo-back acceptance — build spec §0) ─────────────────────────────────────────
+  done('inngest.config.concurrency_accepted', 'config', 'a function registered with a concurrency config is accepted and echoed back verbatim via introspect (enforcement is filed as scheduling.flow_control_enforcement)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-x', triggers: [{ event: 'app/x' }], config: { concurrency: { limit: 3, key: 'event.data.userId' } } });
+      const r = await h({ m: 'GET', p: '/api/inngest' });
+      const fn = ((r.body as Body).functions as Body[]).find((f) => f.id === 'fn-x');
+      return fn?.config?.concurrency?.limit === 3 && fn?.config?.concurrency?.key === 'event.data.userId';
+    })),
+
+  // ── AUTH (HMAC executor<->SDK signing — pure crypto, ALLOW-listed) ────────────────────────
+  done('inngest.auth.signature_hmac', 'auth', 'HMAC-SHA256 sign/verify round-trip over canonicalJson(body)+timestamp (SDK-source grounded, inngest-signing.ts — pure crypto, never calls handleInngestTwinRequest)', 'api', 'common', () =>
+    withTempRoot(async (root) => {
+      const key = await inngestSigningKey(root);
+      const body = { hello: 'world' };
+      const header = buildInngestSignatureHeader(body, OCCURRED_AT_EPOCH_SEC, key);
+      verifyInngestSignature(body, header, key, { now: OCCURRED_AT_EPOCH_SEC }); // throws on failure
+      // The key is STATE: the same root hands back the same key, minted once and persisted.
+      return header.startsWith(`t=${OCCURRED_AT_EPOCH_SEC}&s=`) && (await inngestSigningKey(root)) === key;
+    })),
+  done('inngest.auth.signature_tamper', 'auth', 'a tampered signature (or another world\'s key) is REJECTED — pure crypto tamper-reject, never calls the handler', 'api', 'common', () =>
+    withTempRoot(async (root) =>
+      withTempRoot(async (otherRoot) => {
+        const key = await inngestSigningKey(root);
+        const body = { a: 1 };
+        const header = buildInngestSignatureHeader(body, OCCURRED_AT_EPOCH_SEC, key);
+        const tampered = header.slice(0, -1) + (header.endsWith('a') ? 'b' : 'a');
+        let threw = false;
+        try {
+          verifyInngestSignature(body, tampered, key, { now: OCCURRED_AT_EPOCH_SEC });
+        } catch (err) {
+          threw = err instanceof InngestSignatureError;
+        }
+        if (!threw) return false;
+        let wrongKeyThrew = false;
+        try {
+          verifyInngestSignature(body, header, await inngestSigningKey(otherRoot), { now: OCCURRED_AT_EPOCH_SEC });
+        } catch (err) {
+          wrongKeyThrew = err instanceof InngestSignatureError;
+        }
+        return wrongKeyThrew;
+      }),
+    )),
+
+  // ── SAFETY / HONESTY ───────────────────────────────────────────────────────────────────────
+  done('inngest.safety.read_only_rejects_writes', 'safety', 'readOnly mode rejects writes with 405 but allows GET', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'inngest-ro-'));
+    try {
+      const w = await handleInngestTwinRequest({ method: 'POST', path: '/e/test-key', body: JSON.stringify({ name: 'x' }), root, readOnly: true, occurredAt: OCCURRED_AT });
+      const g = await handleInngestTwinRequest({ method: 'GET', path: '/api/inngest', root, readOnly: true, occurredAt: OCCURRED_AT });
+      return w.status === 405 && g.status === 200;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('inngest.safety.unmodeled_route_404', 'safety', 'an unmodeled route returns the real v2 error envelope (never a fabricated success)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v2/totally/unknown/route' });
+      return r.status === 404 && Array.isArray((r.body as Body).errors);
+    })),
+
+  // ── STATE ──────────────────────────────────────────────────────────────────────────────────
+  done('inngest.state.kernel_persisted', 'state', 'state is kernel-folded — a run created in one call is visible (by id) in the next', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await registerFn(h, { id: 'fn-y', triggers: [{ event: 'app/y' }], steps: [{ id: 's1', op: 'StepRun' }] });
+      const sent = await h({ m: 'POST', p: '/e/test-key', b: { name: 'app/y' } });
+      const eventId = (sent.body as Body).ids?.[0];
+      if (typeof eventId !== 'string' || eventId.length === 0) return false;
+      const runs = await h({ m: 'GET', p: `/api/v2/events/${eventId}/runs` });
+      return runs.status === 200 && (runs.body as Body).data?.length === 1;
+    })),
+
+  // ── CONFORMANCE / CONNECTOR ────────────────────────────────────────────────────────────────
+  done('inngest.conformance.snapshot', 'conformance', 'conformance snapshot covers every resource type + the core event/exec/api-surface routes (static self-check, never calls handleInngestTwinRequest)', 'api', 'common', () => {
+    const report = checkInngestConformance();
+    return report.ok && report.endpointsChecked >= 9 && report.resourceTypesChecked === 5;
+  }),
+  done('inngest.connector.sync.entrypoint', 'connector', 'syncInngestFromReal pulls the CURRENT real state of explicitly-named event/run handles (inngest has no bulk list-everything endpoint) into the twin; idempotent re-pull', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'inngest-conn-'));
+    try {
+      const client: InngestLikeClient = {
+        events: { get: async () => ({ name: 'app/pulled', data: { x: 1 } }) },
+        runs: { get: async () => ({ id: 'real-run-1', functionId: 'real-fn', eventId: 'real-evt-1', status: 'COMPLETED', output: 'real output' }) },
+      };
+      const first = await syncInngestFromReal(client, { root, events: [{ eventId: 'real-evt-1' }], runs: [{ runId: 'real-run-1' }], occurredAt: OCCURRED_AT, budgetOptions: { root } });
+      if (first.observed !== 2 || first.deltasAppended < 2) return false;
+      const second = await syncInngestFromReal(client, { root, events: [{ eventId: 'real-evt-1' }], runs: [{ runId: 'real-run-1' }], occurredAt: OCCURRED_AT, budgetOptions: { root } });
+      if (second.deltasAppended !== 0) return false;
+      const r = await handleInngestTwinRequest({ method: 'GET', path: '/api/v2/runs/real-run-1', root, occurredAt: OCCURRED_AT });
+      return r.status === 200 && (r.body as Body).data.status === 'COMPLETED';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('inngest.connector.empty_client', 'connector', 'syncInngestFromReal with no client.events/runs and no handles observes nothing', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'inngest-conn-empty-'));
+    try {
+      const result = await syncInngestFromReal({}, { root, budgetOptions: { root } });
+      return result.observed === 0 && result.deltasAppended === 0;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  // ── TODO: the rest of the Inngest v1 surface (honest denominator) ───────────────────────────
+  todo('inngest.exec.sdk_executor_roundtrip', 'exec_protocol', 'a real running app + real step handler functions Inngest calls into over HTTP (this twin declares steps instead of executing real code)', 'api', 'core'),
+  todo('inngest.exec.step_op_protocol', 'exec_protocol', "the real wire step-op array format a live executor POSTs to a serve endpoint (this twin's POST /api/inngest is a simplified {runId} advance trigger, not the real op-array protocol)", 'api', 'common'),
+  todo('inngest.exec.invoke_function', 'exec_protocol', 'InvokeFunction opcode actually invoking a SECOND declared function\'s own step plan (modeled identically to StepRun today, not yet cross-function)', 'api', 'common'),
+  todo('inngest.exec.parallel_steps', 'exec_protocol', 'Promise.all-style parallel step fan-out within one function (steps advance strictly sequentially today)', 'api', 'common'),
+  todo('inngest.exec.streaming_connect', 'exec_protocol', 'Inngest Connect: a persistent WebSocket-based durable-endpoint execution channel (SDK-source confirmed to exist — connect.js — not modeled)', 'api', 'niche'),
+  todo('inngest.scheduling.cron_evaluation', 'scheduling', 'Evaluate a cron trigger against the injected clock so a scheduled function actually runs (a cron trigger is accepted and echoed via introspect today; nothing ticks it)', 'api', 'common'),
+  todo('inngest.scheduling.debounce', 'scheduling', 'debounce config REAL enforcement (delaying/coalescing runs within a debounce window)', 'api', 'common'),
+  todo('inngest.scheduling.throttle', 'scheduling', 'throttle config REAL enforcement', 'api', 'common'),
+  todo('inngest.scheduling.rate_limit', 'scheduling', 'rate-limit config REAL enforcement', 'api', 'niche'),
+  todo('inngest.scheduling.batching', 'scheduling', 'event batching (events.batch config) REAL coalescing of multiple events into one run', 'api', 'niche'),
+  todo('inngest.scheduling.priority', 'scheduling', 'run priority-hint scheduling', 'api', 'niche'),
+  todo('inngest.scheduling.cancel_if_expression', 'scheduling', "the real CEL-style cancelOn `if` expression (grounded shape: `event.data.id == async.data.id`) — this twin matches on event NAME ONLY today", 'api', 'common'),
+  todo('inngest.config.concurrency_key_physics', 'config', 'real per-key concurrency-limit enforcement (the config is accepted/echoed; nothing actually throttles a second run)', 'api', 'common'),
+  todo('inngest.config.singleton', 'config', 'the `singleton` function config (one true concurrent run per key, real v2 schema field `v2FunctionSingletonConfiguration`)', 'api', 'niche'),
+  todo('inngest.runs.replay_endpoint', 'runs', 'POST /api/v2/runs/{runId}/rerun — a REAL, live-fetched v2 REST endpoint (v2RerunBody/v2RerunResponse) not yet modeled', 'api', 'common'),
+  todo('inngest.runs.trace', 'runs', 'GET /api/v2/runs/{runId}/trace — a REAL, live-fetched v2 REST endpoint (per-step trace spans) not yet modeled', 'api', 'common'),
+  todo('inngest.runs.failed_state_history', 'runs', 'full failed-run history across retries (today only the final FAILED state is visible on the run, not a per-attempt history)', 'api', 'niche'),
+  todo('inngest.pagination.event_runs_cursor', 'pagination', 'GET /api/v2/events/{id}/runs REAL page.cursor/hasMore pagination (this twin always returns a single page)', 'api', 'common'),
+  todo('inngest.pagination.rerun_history_cursor', 'pagination', 'pagination over a run\'s rerun history (tied to runs.replay_endpoint)', 'api', 'niche'),
+  todo('inngest.events.get_by_id', 'events', 'a direct single-event-fetch endpoint (⚠ CONFIRMED ABSENT from the live-fetched v2 REST API — no `GET /events/{id}` path exists, only `GET /events/{id}/runs`; filed for forward-compat only)', 'api', 'niche'),
+  todo('inngest.events.send_ts_ordering', 'events', 'events with an explicit client-supplied `ts` are ordered/queryable by that timestamp (accepted + stored, not yet queryable)', 'api', 'niche'),
+  todo('inngest.functions.multiple_triggers', 'functions', 'a function registered with MORE THAN ONE trigger (today every registered fixture uses exactly one)', 'api', 'common'),
+  todo('inngest.steps.ai_gateway_infer', 'steps', 'the step.ai / AI Gateway opcode (SDK-source confirmed to exist — StepOpCode.AiGateway) — modeled as an ordinary StepRun today', 'api', 'niche'),
+  todo('inngest.auth.event_key_401_parity', 'auth', 'a missing/invalid event key on POST /e/{eventKey} -> 401 parity (this twin accepts any key string today)', 'api', 'common'),
+  todo('inngest.auth.signing_key_rotation', 'auth', 'signing-key rotation / fallback-key verification (the real SDK has a documented signingKeyFallback path)', 'api', 'niche'),
+  todo('inngest.auth.signature_500_reject_parity', 'auth', 'exact HTTP status for an executor-received invalid signature — ⚠ SDK-SOURCE FINDING: reading the installed SDK\'s InngestCommHandler.js shows the real comm handler returns 401 (unauthorizedResponse), NOT the build spec\'s assumed 500 (SDK_SPEC.md prose) — this twin does not yet enforce signatures on any route, so neither status is claimed `done`', 'api', 'niche'),
+  todo('inngest.errors.rest_envelope_parity', 'errors', 'the FULL v2 error-code taxonomy (this twin uses one generic {code,message} shape for every 404/400, not vendor-exact codes per failure)', 'api', 'niche'),
+  todo('inngest.errors.429_rate_limit', 'errors', 'a deterministic opt-in 429 rate-limit trigger + envelope', 'api', 'niche'),
+  todo('inngest.connector.push', 'connector', 'push a locally-created event/run against a real Inngest account (Inngest has no such write-back API for pre-existing runs — see README ## Coverage)', 'connector', 'common'),
+  todo('inngest.connector.pull_steps', 'connector', 'connector: pull per-step trace data from a real account (tied to runs.trace)', 'connector', 'common'),
+  todo('inngest.fixtures.seed', 'connector', 'seed a small library of realistic function/event fixtures', 'connector', 'niche'),
+  todo('inngest.apps.list_and_sync', 'functions', 'GET /api/v2/apps/{appId} + POST /api/v2/apps/{appId}/syncs — REAL, live-fetched v2 REST endpoints for the "app" resource this v1 twin does not model as its own resource type', 'api', 'niche'),
+];
+
+export const INNGEST_AREAS = [
+  'events', 'functions', 'runs', 'steps', 'scheduling', 'config', 'exec_protocol', 'auth',
+  'pagination', 'errors', 'connector', 'conformance', 'safety', 'state',
+] as const;
+
+export async function inngestCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('inngest', INNGEST_CAPABILITIES);
+}

package/src/inngest-conformance.ts

@@ -0,0 +1,43 @@
+// inngest conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+// Checks the twin's endpoint/resource inventory against itself — SELF-REFERENTIAL, the same
+// pattern replicate/elevenlabs/polar/fal/pinecone/algolia use (docs/contributing/conformance.md's "2 spec"
+// discussion): it does not diff against a captured vendor document, it asserts the pack's own
+// declared snapshot is internally consistent (every resource type has a route, the core
+// event/exec/api-surface routes exist).
+import { inngestTwinSnapshot, INNGEST_RESOURCE_TYPES } from './inngest-twin.ts';
+
+export type InngestConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+export function checkInngestConformance(): InngestConformanceReport {
+  const snapshot = inngestTwinSnapshot();
+  const violations: string[] = [];
+  // Every declared resource type must have at least one implemented endpoint touching it.
+  const stemFor: Record<string, string> = {
+    event: '/e/',
+    function: 'register',
+    run: '/runs/',
+    step: 'run advance', // steps have no REST path of their own — advanced via run-progression
+    signing_key: '/api/v2/keys/signing', // the introspection route that establishes the key row
+  };
+  for (const type of INNGEST_RESOURCE_TYPES) {
+    const stem = stemFor[type];
+    if (!stem || !snapshot.implementedEndpoints.some((e) => e.includes(stem))) {
+      violations.push(`resource type '${type}' has no implemented endpoint`);
+    }
+  }
+  if (!snapshot.implementedEndpoints.some((e) => e.startsWith('POST /e/'))) violations.push('missing event send endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e.includes('register'))) violations.push('missing function register endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e.includes('/api/v2/runs/'))) violations.push('missing run get endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e.includes('events/{eventId}/runs'))) violations.push('missing event-runs endpoint');
+  return {
+    ok: violations.length === 0,
+    endpointsChecked: snapshot.implementedEndpoints.length,
+    resourceTypesChecked: snapshot.resourceTypes.length,
+    violations,
+  };
+}