@volter/twin-fireworks 0.1.0

package/dist/src/fireworks-conformance.d.ts

@@ -0,0 +1,14 @@
+export type ConformanceViolation = {
+    check: string;
+    detail: string;
+};
+export type FireworksConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    probes: number;
+    violations: ConformanceViolation[];
+};
+/** Run the offline conformance checks against a fresh temp root. */
+export declare function checkFireworksConformance(opts?: {
+    root?: string;
+}): Promise<FireworksConformanceReport>;

package/dist/src/fireworks-conformance.js

@@ -0,0 +1,514 @@
+// Fireworks twin conformance — an offline check with REAL TEETH: delete a handler branch and it
+// goes RED. The harness does not compare two constants (the false-green ADDING_A_TWIN.md §6
+// documents). Instead it runs THREE passes:
+//
+//   1. PROBES — one real request per CLAIMED endpoint, graded on the OUTCOME a live handler
+//      produces: an expected status set PLUS a predicate over the body. A handler that returned
+//      `{}`, or whose branch was deleted (so the router falls through to its not-found), fails.
+//   2. BIJECTION — the probe table and the claimed-endpoint snapshot must match two ways, so a
+//      claim with no probe and a probe with no claim are both RED.
+//   3. ROUTER_SURFACE — a HAND-AUTHORED census of every method/path pair `routeFireworks`
+//      branches on, INCLUDING the generic single-resource branch (the `rest.length === 2`
+//      GET/PATCH/DELETE arms serve ALL seven collections, so the census names each one). Every
+//      entry must be claimed; and the paths Fireworks serves but this twin does NOT model must
+//      answer the vendor-shaped not-found envelope. This closes the served-but-unclaimed
+//      direction that probe⇄claim alone is blind to.
+//
+// Fully offline + deterministic (drives the local handler against a temp root) so it runs in CI
+// without an API key. Honest scope: it checks the protocol envelope, NOT model output (a
+// deterministic labeled stub by design).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleFireworksTwinRequest } from "./fireworks-twin.js";
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const MODEL = 'accounts/fireworks/models/kimi-k2-instruct';
+const CHAT = { model: MODEL, messages: [{ role: 'user', content: 'hi' }] };
+const ACCOUNT = '/v1/accounts/my-account';
+const PROBES = [
+    {
+        key: 'POST /inference/v1/chat/completions',
+        method: 'POST', path: '/inference/v1/chat/completions', body: CHAT, statuses: [200],
+        ok: (b) => isObj(b) && b.object === 'chat.completion' && Array.isArray(b.choices)
+            && b.choices[0]?.message?.role === 'assistant'
+            && typeof b.choices[0]?.message?.content === 'string'
+            && isObj(b.usage) && typeof b.usage.prompt_tokens === 'number',
+    },
+    {
+        key: 'POST /inference/v1/completions',
+        method: 'POST', path: '/inference/v1/completions', body: { model: MODEL, prompt: 'hi' }, statuses: [200],
+        ok: (b) => isObj(b) && b.object === 'text_completion' && Array.isArray(b.choices) && isObj(b.usage) && typeof b.usage.total_tokens === 'number',
+    },
+    {
+        key: 'POST /inference/v1/responses',
+        method: 'POST', path: '/inference/v1/responses', body: { model: MODEL, input: 'hi' }, statuses: [200],
+        ok: (b) => isObj(b) && b.object === 'response' && b.status === 'completed' && Array.isArray(b.output) && typeof b.id === 'string',
+    },
+    {
+        key: 'GET /inference/v1/responses',
+        method: 'GET', path: '/inference/v1/responses', statuses: [200],
+        ok: (b) => isObj(b) && b.object === 'list' && Array.isArray(b.data) && typeof b.has_more === 'boolean',
+    },
+    {
+        key: 'GET /inference/v1/responses/{response_id}',
+        method: 'GET', path: '/inference/v1/responses/resp_twin_jw3ibm', statuses: [404],
+        ok: (b) => isObj(b) && isObj(b.error) && typeof b.error.message === 'string',
+    },
+    {
+        key: 'DELETE /inference/v1/responses/{response_id}',
+        method: 'DELETE', path: '/inference/v1/responses/resp_twin_jw3ibm', statuses: [200],
+        seed: async (h) => { await h('POST', '/inference/v1/responses', { model: MODEL, input: 'hi' }); },
+        ok: (b) => isObj(b) && b.deleted === true && b.id === 'resp_twin_jw3ibm',
+    },
+    {
+        key: 'POST /inference/v1/messages',
+        method: 'POST', path: '/inference/v1/messages', body: CHAT, statuses: [200],
+        ok: (b) => isObj(b) && b.type === 'message' && b.role === 'assistant' && Array.isArray(b.content)
+            && b.content[0]?.type === 'text' && typeof b.stop_reason === 'string' && isObj(b.usage),
+    },
+    {
+        key: 'POST /inference/v1/embeddings',
+        method: 'POST', path: '/inference/v1/embeddings', body: { model: 'nomic-ai/nomic-embed-text-v1.5', input: 'hi' }, statuses: [200],
+        ok: (b) => isObj(b) && b.object === 'list' && Array.isArray(b.data) && b.data[0]?.object === 'embedding' && Array.isArray(b.data[0]?.embedding) && isObj(b.usage),
+    },
+    {
+        key: 'POST /inference/v1/rerank',
+        method: 'POST', path: '/inference/v1/rerank', body: { query: 'q', documents: ['a', 'b'] }, statuses: [200],
+        ok: (b) => isObj(b) && b.object === 'list' && Array.isArray(b.data) && b.data.every((d) => typeof d.relevance_score === 'number') && isObj(b.usage),
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/deployments',
+        method: 'POST', path: `${ACCOUNT}/deployments?deploymentId=conf-dep`, body: { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }, statuses: [200],
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/deployments/conf-dep' && b.state === 'CREATING' && isObj(b.status) && b.status.code === 'OK',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/deployments',
+        method: 'GET', path: `${ACCOUNT}/deployments?pageSize=100`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/deployments?deploymentId=conf-dep`, { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }); },
+        ok: (b) => isObj(b) && Array.isArray(b.deployments) && b.deployments.some((d) => d.name === 'accounts/my-account/deployments/conf-dep') && typeof b.nextPageToken !== 'undefined' && b.totalSize >= 1,
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/deployments/{deployment_id}',
+        method: 'GET', path: `${ACCOUNT}/deployments/conf-dep`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/deployments?deploymentId=conf-dep`, { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/deployments/conf-dep' && typeof b.baseModel === 'string',
+    },
+    {
+        // The account segment is part of the address: the same id under ANOTHER account's path must
+        // answer the vendor's own NOT_FOUND (tenancy), never the other account's row.
+        key: 'GET /v1/accounts/{account_id}/deployments/{deployment_id} (cross-account 404)',
+        method: 'GET', path: '/v1/accounts/other-account/deployments/conf-dep', statuses: [404],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/deployments?deploymentId=conf-dep`, { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }); },
+        ok: (b) => isObj(b) && b.code === 'NOT_FOUND' && typeof b.message === 'string',
+    },
+    {
+        key: 'DELETE /v1/accounts/{account_id}/deployments/{deployment_id}',
+        method: 'DELETE', path: `${ACCOUNT}/deployments/conf-dep`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/deployments?deploymentId=conf-dep`, { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }); },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0, // the vendor's empty-object delete
+    },
+    {
+        key: 'PATCH /v1/accounts/{account_id}/deployments/{deployment_id}',
+        method: 'PATCH', path: `${ACCOUNT}/deployments/conf-dep`, body: { displayName: 'patched' }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/deployments?deploymentId=conf-dep`, { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }); },
+        ok: (b) => isObj(b) && b.displayName === 'patched' && b.name === 'accounts/my-account/deployments/conf-dep',
+    },
+    {
+        // the spec's own spelling: PATCH …/{deployment_id}:scale with {replicaCount}, answering `{}`
+        key: 'PATCH /v1/accounts/{account_id}/deployments/{deployment_id}:scale',
+        method: 'PATCH', path: `${ACCOUNT}/deployments/conf-dep:scale`, body: { replicaCount: 2 }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/deployments?deploymentId=conf-dep`, { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' }); },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/datasets',
+        method: 'POST', path: `${ACCOUNT}/datasets`, body: { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }, statuses: [200],
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/datasets/conf-ds' && b.state === 'UPLOADING',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/datasets',
+        method: 'GET', path: `${ACCOUNT}/datasets?pageSize=100`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }); },
+        ok: (b) => isObj(b) && Array.isArray(b.datasets) && b.datasets.some((d) => d.name === 'accounts/my-account/datasets/conf-ds') && typeof b.nextPageToken !== 'undefined',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/datasets/{dataset_id}',
+        method: 'GET', path: `${ACCOUNT}/datasets/conf-ds`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/datasets/conf-ds' && b.state === 'UPLOADING',
+    },
+    {
+        // Gateway_UpdateDataset: a mutable field lands; the response carries the patched value.
+        key: 'PATCH /v1/accounts/{account_id}/datasets/{dataset_id}',
+        method: 'PATCH', path: `${ACCOUNT}/datasets/conf-ds`, body: { displayName: 'patched-ds' }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }); },
+        ok: (b) => isObj(b) && b.displayName === 'patched-ds' && b.name === 'accounts/my-account/datasets/conf-ds',
+    },
+    {
+        key: 'DELETE /v1/accounts/{account_id}/datasets/{dataset_id}',
+        method: 'DELETE', path: `${ACCOUNT}/datasets/conf-ds`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }); },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/batchInferenceJobs',
+        method: 'POST', path: `${ACCOUNT}/batchInferenceJobs?batchInferenceJobId=conf-job`, body: { model: MODEL, inputDatasetId: 'conf-ds' }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/batchInferenceJobs/conf-job' && b.state === 'JOB_STATE_CREATING',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/batchInferenceJobs',
+        method: 'GET', path: `${ACCOUNT}/batchInferenceJobs?pageSize=100`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/batchInferenceJobs?batchInferenceJobId=conf-job`, { model: MODEL, inputDatasetId: 'conf-ds' });
+        },
+        ok: (b) => isObj(b) && Array.isArray(b.batchInferenceJobs) && b.batchInferenceJobs.some((j) => j.name === 'accounts/my-account/batchInferenceJobs/conf-job') && typeof b.nextPageToken !== 'undefined',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/batchInferenceJobs/{job_id}',
+        method: 'GET', path: `${ACCOUNT}/batchInferenceJobs/conf-job`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/batchInferenceJobs?batchInferenceJobId=conf-job`, { model: MODEL, inputDatasetId: 'conf-ds' });
+        },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/batchInferenceJobs/conf-job' && b.state === 'JOB_STATE_CREATING',
+    },
+    {
+        key: 'DELETE /v1/accounts/{account_id}/batchInferenceJobs/{job_id}',
+        method: 'DELETE', path: `${ACCOUNT}/batchInferenceJobs/conf-job`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/batchInferenceJobs?batchInferenceJobId=conf-job`, { model: MODEL, inputDatasetId: 'conf-ds' });
+        },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/batchInferenceJobs/{job_id}:cancel',
+        method: 'POST', path: `${ACCOUNT}/batchInferenceJobs/conf-job:cancel`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/batchInferenceJobs?batchInferenceJobId=conf-job`, { model: MODEL, inputDatasetId: 'conf-ds' });
+        },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/supervisedFineTuningJobs',
+        method: 'POST', path: `${ACCOUNT}/supervisedFineTuningJobs?supervisedFineTuningJobId=conf-sft`, body: { dataset: 'accounts/my-account/datasets/conf-ds', baseModel: MODEL }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/supervisedFineTuningJobs/conf-sft' && b.state === 'JOB_STATE_CREATING',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/supervisedFineTuningJobs',
+        method: 'GET', path: `${ACCOUNT}/supervisedFineTuningJobs?pageSize=100`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/supervisedFineTuningJobs?supervisedFineTuningJobId=conf-sft`, { dataset: 'accounts/my-account/datasets/conf-ds', baseModel: MODEL });
+        },
+        ok: (b) => isObj(b) && Array.isArray(b.supervisedFineTuningJobs) && b.supervisedFineTuningJobs.some((j) => j.name === 'accounts/my-account/supervisedFineTuningJobs/conf-sft') && typeof b.nextPageToken !== 'undefined',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/supervisedFineTuningJobs/{job_id}',
+        method: 'GET', path: `${ACCOUNT}/supervisedFineTuningJobs/conf-sft`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/supervisedFineTuningJobs?supervisedFineTuningJobId=conf-sft`, { dataset: 'accounts/my-account/datasets/conf-ds', baseModel: MODEL });
+        },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/supervisedFineTuningJobs/conf-sft' && b.state === 'JOB_STATE_CREATING',
+    },
+    {
+        key: 'DELETE /v1/accounts/{account_id}/supervisedFineTuningJobs/{job_id}',
+        method: 'DELETE', path: `${ACCOUNT}/supervisedFineTuningJobs/conf-sft`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/datasets`, { dataset: { displayName: 'conf ds' }, datasetId: 'conf-ds' });
+            await h('POST', `${ACCOUNT}/supervisedFineTuningJobs?supervisedFineTuningJobId=conf-sft`, { dataset: 'accounts/my-account/datasets/conf-ds', baseModel: MODEL });
+        },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/users',
+        method: 'POST', path: `${ACCOUNT}/users?userId=conf-user`, body: { role: 'admin' }, statuses: [200],
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/users/conf-user' && b.role === 'admin',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/users',
+        method: 'GET', path: `${ACCOUNT}/users?pageSize=100`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'admin' }); },
+        ok: (b) => isObj(b) && Array.isArray(b.users) && b.users.some((u) => u.name === 'accounts/my-account/users/conf-user') && typeof b.nextPageToken !== 'undefined',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/users/{user_id}',
+        method: 'GET', path: `${ACCOUNT}/users/conf-user`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'admin' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/users/conf-user' && b.role === 'admin',
+    },
+    {
+        key: 'PATCH /v1/accounts/{account_id}/users/{user_id}',
+        method: 'PATCH', path: `${ACCOUNT}/users/conf-user`, body: { displayName: 'patched' }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'admin' }); },
+        ok: (b) => isObj(b) && b.displayName === 'patched' && b.name === 'accounts/my-account/users/conf-user',
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/users/{user_id}/apiKeys',
+        method: 'POST', path: `${ACCOUNT}/users/conf-user/apiKeys`, body: { apiKey: { displayName: 'conf key' } }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'user' }); },
+        ok: (b) => isObj(b) && typeof b.key === 'string' && String(b.key).startsWith('fw_') && typeof b.keyId === 'string',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/users/{user_id}/apiKeys',
+        method: 'GET', path: `${ACCOUNT}/users/conf-user/apiKeys`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'user' });
+            await h('POST', `${ACCOUNT}/users/conf-user/apiKeys`, { apiKey: { displayName: 'conf key' } });
+        },
+        // The list NEVER carries the full key — the custody rule holds on every read path.
+        ok: (b) => isObj(b) && Array.isArray(b.apiKeys) && b.apiKeys.length === 1 && b.apiKeys[0]?.key === undefined && typeof b.apiKeys[0]?.prefix === 'string',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/users/{user_id}/apiKeys/{key_id}',
+        method: 'GET', path: `${ACCOUNT}/users/conf-user/apiKeys/key_twin_1`, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'user' });
+            await h('POST', `${ACCOUNT}/users/conf-user/apiKeys`, { apiKey: { displayName: 'conf key' } });
+        },
+        ok: (b) => isObj(b) && b.key === undefined && typeof b.prefix === 'string',
+    },
+    {
+        key: 'PATCH /v1/accounts/{account_id}/users/{user_id}/apiKeys/{key_id}',
+        method: 'PATCH', path: `${ACCOUNT}/users/conf-user/apiKeys/key_twin_1`, body: { displayName: 'renamed' }, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'user' });
+            await h('POST', `${ACCOUNT}/users/conf-user/apiKeys`, { apiKey: { displayName: 'conf key' } });
+        },
+        ok: (b) => isObj(b) && b.displayName === 'renamed' && b.key === undefined,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/users/{user_id}/apiKeys/{key_id}:delete',
+        method: 'POST', path: `${ACCOUNT}/users/conf-user/apiKeys/key_twin_1:delete`, body: { keyId: 'key_twin_1' }, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'user' });
+            await h('POST', `${ACCOUNT}/users/conf-user/apiKeys`, { apiKey: { displayName: 'conf key' } });
+        },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        // the spec's own collection-level spelling: POST …/apiKeys:delete with {keyId} (Gateway_DeleteApiKey)
+        key: 'POST /v1/accounts/{account_id}/users/{user_id}/apiKeys:delete',
+        method: 'POST', path: `${ACCOUNT}/users/conf-user/apiKeys:delete`, body: { keyId: 'key_twin_1' }, statuses: [200],
+        seed: async (h) => {
+            await h('POST', `${ACCOUNT}/users?userId=conf-user`, { role: 'user' });
+            await h('POST', `${ACCOUNT}/users/conf-user/apiKeys`, { apiKey: { displayName: 'conf key 2' } });
+        },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/secrets',
+        method: 'POST', path: `${ACCOUNT}/secrets`, body: { name: 'conf-secret', keyName: 'KEY', value: 'v' }, statuses: [200],
+        ok: (b) => isObj(b) && b.keyName === 'KEY' && b.value === undefined, // the value is never echoed on the read surface
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/secrets',
+        method: 'GET', path: `${ACCOUNT}/secrets?pageSize=100`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/secrets`, { name: 'conf-secret', keyName: 'KEY', value: 'v' }); },
+        ok: (b) => isObj(b) && Array.isArray(b.secrets) && b.secrets.some((s) => s.name === 'accounts/my-account/secrets/conf-secret') && typeof b.nextPageToken !== 'undefined',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/secrets/{secret_id}',
+        method: 'GET', path: `${ACCOUNT}/secrets/conf-secret`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/secrets`, { name: 'conf-secret', keyName: 'KEY', value: 'v' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/secrets/conf-secret' && b.value === undefined,
+    },
+    {
+        // Gateway_UpdateSecret: keyName is the mutable field (value is INPUT_ONLY and never echoes).
+        key: 'PATCH /v1/accounts/{account_id}/secrets/{secret_id}',
+        method: 'PATCH', path: `${ACCOUNT}/secrets/conf-secret`, body: { keyName: 'KEY2' }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/secrets`, { name: 'conf-secret', keyName: 'KEY', value: 'v' }); },
+        ok: (b) => isObj(b) && b.keyName === 'KEY2' && b.value === undefined,
+    },
+    {
+        key: 'DELETE /v1/accounts/{account_id}/secrets/{secret_id}',
+        method: 'DELETE', path: `${ACCOUNT}/secrets/conf-secret`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/secrets`, { name: 'conf-secret', keyName: 'KEY', value: 'v' }); },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+    {
+        key: 'POST /v1/accounts/{account_id}/models',
+        method: 'POST', path: `${ACCOUNT}/models?modelId=conf-model`, body: { displayName: 'conf model' }, statuses: [200],
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/models/conf-model' && b.public === false,
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/models',
+        method: 'GET', path: `${ACCOUNT}/models?pageSize=100`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/models?modelId=conf-model`, { displayName: 'conf model' }); },
+        ok: (b) => isObj(b) && Array.isArray(b.models) && b.models.some((m) => m.name === 'accounts/my-account/models/conf-model') && typeof b.nextPageToken !== 'undefined',
+    },
+    {
+        key: 'GET /v1/accounts/{account_id}/models/{model_id}',
+        method: 'GET', path: `${ACCOUNT}/models/conf-model`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/models?modelId=conf-model`, { displayName: 'conf model' }); },
+        ok: (b) => isObj(b) && b.name === 'accounts/my-account/models/conf-model' && b.public === false,
+    },
+    {
+        key: 'PATCH /v1/accounts/{account_id}/models/{model_id}',
+        method: 'PATCH', path: `${ACCOUNT}/models/conf-model`, body: { displayName: 'patched' }, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/models?modelId=conf-model`, { displayName: 'conf model' }); },
+        ok: (b) => isObj(b) && b.displayName === 'patched' && b.name === 'accounts/my-account/models/conf-model',
+    },
+    {
+        key: 'DELETE /v1/accounts/{account_id}/models/{model_id}',
+        method: 'DELETE', path: `${ACCOUNT}/models/conf-model`, statuses: [200],
+        seed: async (h) => { await h('POST', `${ACCOUNT}/models?modelId=conf-model`, { displayName: 'conf model' }); },
+        ok: (b) => isObj(b) && Object.keys(b).length === 0,
+    },
+];
+/** The literal the router falls through to when NO branch matched. A census entry answering this
+ *  means its branch is gone. Kept as a LITERAL — importing the handler's string would be a
+ *  tautology that could not catch the message drifting. */
+const ROUTER_MISS = 'Unknown request URL';
+const ROUTER_SURFACE = [
+    { key: 'POST /inference/v1/chat/completions', method: 'POST', path: '/inference/v1/chat/completions', body: CHAT },
+    { key: 'POST /inference/v1/completions', method: 'POST', path: '/inference/v1/completions', body: { model: MODEL, prompt: 'hi' } },
+    { key: 'POST /inference/v1/responses', method: 'POST', path: '/inference/v1/responses', body: { model: MODEL, input: 'hi' } },
+    { key: 'GET /inference/v1/responses', method: 'GET', path: '/inference/v1/responses' },
+    { key: 'GET /inference/v1/responses/{response_id}', method: 'GET', path: '/inference/v1/responses/resp_twin_jw3ibm' },
+    { key: 'DELETE /inference/v1/responses/{response_id}', method: 'DELETE', path: '/inference/v1/responses/resp_twin_jw3ibm' },
+    { key: 'POST /inference/v1/messages', method: 'POST', path: '/inference/v1/messages', body: CHAT },
+    { key: 'POST /inference/v1/embeddings', method: 'POST', path: '/inference/v1/embeddings', body: { model: 'nomic-ai/nomic-embed-text-v1.5', input: 'hi' } },
+    { key: 'POST /inference/v1/rerank', method: 'POST', path: '/inference/v1/rerank', body: { query: 'q', documents: ['a', 'b'] } },
+    { key: 'POST /v1/accounts/{account_id}/deployments', method: 'POST', path: `${ACCOUNT}/deployments?deploymentId=conf-dep`, body: { baseModel: 'accounts/fireworks/models/llama-v3p1-8b-instruct' } },
+    { key: 'GET /v1/accounts/{account_id}/deployments', method: 'GET', path: `${ACCOUNT}/deployments` },
+    { key: 'GET /v1/accounts/{account_id}/deployments/{deployment_id}', method: 'GET', path: `${ACCOUNT}/deployments/conf-dep` },
+    { key: 'GET /v1/accounts/{account_id}/deployments/{deployment_id} (cross-account 404)', method: 'GET', path: '/v1/accounts/other-account/deployments/conf-dep' },
+    { key: 'PATCH /v1/accounts/{account_id}/deployments/{deployment_id}', method: 'PATCH', path: `${ACCOUNT}/deployments/conf-dep`, body: { displayName: 'x' } },
+    { key: 'DELETE /v1/accounts/{account_id}/deployments/{deployment_id}', method: 'DELETE', path: `${ACCOUNT}/deployments/conf-dep` },
+    { key: 'POST /v1/accounts/{account_id}/datasets', method: 'POST', path: `${ACCOUNT}/datasets`, body: { dataset: { displayName: 'x' }, datasetId: 'conf-ds' } },
+    { key: 'GET /v1/accounts/{account_id}/datasets', method: 'GET', path: `${ACCOUNT}/datasets` },
+    { key: 'GET /v1/accounts/{account_id}/datasets/{dataset_id}', method: 'GET', path: `${ACCOUNT}/datasets/conf-ds` },
+    { key: 'PATCH /v1/accounts/{account_id}/datasets/{dataset_id}', method: 'PATCH', path: `${ACCOUNT}/datasets/conf-ds`, body: { displayName: 'x' } },
+    { key: 'DELETE /v1/accounts/{account_id}/datasets/{dataset_id}', method: 'DELETE', path: `${ACCOUNT}/datasets/conf-ds` },
+    { key: 'POST /v1/accounts/{account_id}/batchInferenceJobs', method: 'POST', path: `${ACCOUNT}/batchInferenceJobs?batchInferenceJobId=conf-job`, body: { model: MODEL, inputDatasetId: 'conf-ds' } },
+    { key: 'GET /v1/accounts/{account_id}/batchInferenceJobs', method: 'GET', path: `${ACCOUNT}/batchInferenceJobs` },
+    { key: 'GET /v1/accounts/{account_id}/batchInferenceJobs/{job_id}', method: 'GET', path: `${ACCOUNT}/batchInferenceJobs/conf-job` },
+    { key: 'DELETE /v1/accounts/{account_id}/batchInferenceJobs/{job_id}', method: 'DELETE', path: `${ACCOUNT}/batchInferenceJobs/conf-job` },
+    { key: 'POST /v1/accounts/{account_id}/batchInferenceJobs/{job_id}:cancel', method: 'POST', path: `${ACCOUNT}/batchInferenceJobs/conf-job:cancel` },
+    { key: 'POST /v1/accounts/{account_id}/supervisedFineTuningJobs', method: 'POST', path: `${ACCOUNT}/supervisedFineTuningJobs?supervisedFineTuningJobId=conf-sft`, body: { dataset: 'accounts/my-account/datasets/conf-ds', baseModel: MODEL } },
+    { key: 'GET /v1/accounts/{account_id}/supervisedFineTuningJobs', method: 'GET', path: `${ACCOUNT}/supervisedFineTuningJobs` },
+    { key: 'GET /v1/accounts/{account_id}/supervisedFineTuningJobs/{job_id}', method: 'GET', path: `${ACCOUNT}/supervisedFineTuningJobs/conf-sft` },
+    { key: 'DELETE /v1/accounts/{account_id}/supervisedFineTuningJobs/{job_id}', method: 'DELETE', path: `${ACCOUNT}/supervisedFineTuningJobs/conf-sft` },
+    { key: 'POST /v1/accounts/{account_id}/users', method: 'POST', path: `${ACCOUNT}/users?userId=conf-user`, body: { role: 'admin' } },
+    { key: 'GET /v1/accounts/{account_id}/users', method: 'GET', path: `${ACCOUNT}/users` },
+    { key: 'GET /v1/accounts/{account_id}/users/{user_id}', method: 'GET', path: `${ACCOUNT}/users/conf-user` },
+    { key: 'PATCH /v1/accounts/{account_id}/users/{user_id}', method: 'PATCH', path: `${ACCOUNT}/users/conf-user`, body: { displayName: 'x' } },
+    { key: 'POST /v1/accounts/{account_id}/users/{user_id}/apiKeys', method: 'POST', path: `${ACCOUNT}/users/conf-user/apiKeys`, body: { apiKey: { displayName: 'k' } } },
+    { key: 'GET /v1/accounts/{account_id}/users/{user_id}/apiKeys', method: 'GET', path: `${ACCOUNT}/users/conf-user/apiKeys` },
+    { key: 'GET /v1/accounts/{account_id}/users/{user_id}/apiKeys/{key_id}', method: 'GET', path: `${ACCOUNT}/users/conf-user/apiKeys/key_twin_1` },
+    { key: 'PATCH /v1/accounts/{account_id}/users/{user_id}/apiKeys/{key_id}', method: 'PATCH', path: `${ACCOUNT}/users/conf-user/apiKeys/key_twin_1`, body: { displayName: 'x' } },
+    { key: 'POST /v1/accounts/{account_id}/users/{user_id}/apiKeys/{key_id}:delete', method: 'POST', path: `${ACCOUNT}/users/conf-user/apiKeys/key_twin_1:delete`, body: { keyId: 'key_twin_1' } },
+    { key: 'POST /v1/accounts/{account_id}/users/{user_id}/apiKeys:delete', method: 'POST', path: `${ACCOUNT}/users/conf-user/apiKeys:delete`, body: { keyId: 'key_twin_2' } },
+    { key: 'PATCH /v1/accounts/{account_id}/deployments/{deployment_id}:scale', method: 'PATCH', path: `${ACCOUNT}/deployments/conf-dep:scale`, body: { replicaCount: 2 } },
+    { key: 'POST /v1/accounts/{account_id}/secrets', method: 'POST', path: `${ACCOUNT}/secrets`, body: { name: 's', keyName: 'K', value: 'v' } },
+    { key: 'GET /v1/accounts/{account_id}/secrets', method: 'GET', path: `${ACCOUNT}/secrets` },
+    { key: 'GET /v1/accounts/{account_id}/secrets/{secret_id}', method: 'GET', path: `${ACCOUNT}/secrets/s` },
+    { key: 'PATCH /v1/accounts/{account_id}/secrets/{secret_id}', method: 'PATCH', path: `${ACCOUNT}/secrets/s`, body: { keyName: 'K2' } },
+    { key: 'DELETE /v1/accounts/{account_id}/secrets/{secret_id}', method: 'DELETE', path: `${ACCOUNT}/secrets/s` },
+    { key: 'POST /v1/accounts/{account_id}/models', method: 'POST', path: `${ACCOUNT}/models?modelId=conf-model`, body: { displayName: 'm' } },
+    { key: 'GET /v1/accounts/{account_id}/models', method: 'GET', path: `${ACCOUNT}/models` },
+    { key: 'GET /v1/accounts/{account_id}/models/{model_id}', method: 'GET', path: `${ACCOUNT}/models/conf-model` },
+    { key: 'PATCH /v1/accounts/{account_id}/models/{model_id}', method: 'PATCH', path: `${ACCOUNT}/models/conf-model`, body: { displayName: 'x' } },
+    { key: 'DELETE /v1/accounts/{account_id}/models/{model_id}', method: 'DELETE', path: `${ACCOUNT}/models/conf-model` },
+];
+const ROUTER_SURFACE_KEYS = ROUTER_SURFACE.map((e) => e.key);
+/**
+ * Surface the twin must NOT serve: real Fireworks endpoints this twin does not model yet
+ * (unmodeled ops fail like the vendor, never a fake success), plus paths neither plane declares.
+ */
+const MUST_NOT_SERVE = [
+    { method: 'POST', path: '/v1/chat/completions', why: 'the bare OpenAI /v1 prefix is NOT the vendor path — Fireworks serves /inference/v1; a twin answering here would be a lie about the vendor' },
+    { method: 'GET', path: '/v1/accounts/my-account/serverlessModels', why: 'the vendor-curated serverless catalog is real surface this twin does not model yet (the spec scopes it under the account: /v1/accounts/{account_id}/serverlessModels)' },
+    { method: 'GET', path: '/v1/accounts/my-account/quotas', why: 'quotas are vendor-assigned surface this twin does not model yet' },
+    { method: 'POST', path: '/v1/accounts/my-account/datasets/conf-ds:upload', why: 'the dataset-upload extra is real surface this twin does not model yet' },
+];
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkFireworksConformance(opts = {}) {
+    const violations = [];
+    let checksRun = 0;
+    const fail = (check, detail) => violations.push({ check, detail });
+    // ── 1. PROBES: each in its OWN throwaway root, so a probe's seed can't leak into another. ──
+    for (const probe of PROBES) {
+        checksRun++;
+        // A FRESH root per probe, always. `opts.root` is the PARENT directory, never a shared root:
+        // sharing it let `nextId` ratchet across probes, so a probe read the id an earlier probe had
+        // minted and `world-fireworks conformance --root DIR` reported false violations.
+        const root = mkdtempSync(join(opts.root ?? tmpdir(), 'fireworks-conf-'));
+        const h = (method, path, body) => handleFireworksTwinRequest({ method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }), root });
+        try {
+            if (probe.seed)
+                await probe.seed(h);
+            const res = await h(probe.method, probe.path, probe.body);
+            if (!probe.statuses.includes(res.status)) {
+                fail(`probe:${probe.key}`, `status ${res.status} (expected one of ${probe.statuses.join('/')}) body=${JSON.stringify(res.body).slice(0, 200)}`);
+            }
+            else if (!probe.ok(res.body, res.status)) {
+                fail(`probe:${probe.key}`, `body did not satisfy the live-handler predicate: ${JSON.stringify(res.body).slice(0, 300)}`);
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }
+    // ── 2. BIJECTION: probe table ⇄ router census, both directions. ──
+    checksRun++;
+    const probeKeys = new Set(PROBES.map((p) => p.key));
+    for (const key of ROUTER_SURFACE_KEYS)
+        if (!probeKeys.has(key))
+            fail('bijection', `router branch "${key}" has no probe`);
+    for (const key of probeKeys)
+        if (!ROUTER_SURFACE_KEYS.includes(key))
+            fail('bijection', `probe "${key}" is not in the hand-authored router census`);
+    if (PROBES.length !== new Set(PROBES.map((p) => p.key)).size)
+        fail('bijection', 'duplicate probe key');
+    if (ROUTER_SURFACE.length !== ROUTER_SURFACE_KEYS.length)
+        fail('bijection', 'the router census and its key list disagree');
+    // ── 2b. THE CENSUS HAS TEETH: every declared branch must actually be REACHED. A branch whose
+    //       handler was deleted falls through to the router's own not-found, which is what this
+    //       catches — independently of that endpoint's own probe.
+    for (const entry of ROUTER_SURFACE) {
+        checksRun++;
+        const root = mkdtempSync(join(opts.root ?? tmpdir(), 'fireworks-conf-'));
+        try {
+            const res = await handleFireworksTwinRequest({ method: entry.method, path: entry.path, ...(entry.body === undefined ? {} : { body: JSON.stringify(entry.body) }), root });
+            const message = String(res.body?.error?.message ?? '');
+            // The control plane's google.rpc error carries `message` at the top level.
+            const gatewayMessage = String(res.body?.message ?? '');
+            if (message.includes(ROUTER_MISS) || gatewayMessage.includes(ROUTER_MISS)) {
+                fail('router_surface', `${entry.key} fell through to the router's not-found — the branch is gone (answered ${res.status}: ${message || gatewayMessage})`);
+            }
+            if (!ROUTER_SURFACE_KEYS.includes(entry.key))
+                fail('router_surface', `${entry.key} is exercised but not declared`);
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }
+    // ── 3. The twin must not serve surface it does not model (or the vendor does not have). ──
+    {
+        const root = opts.root ?? mkdtempSync(join(tmpdir(), 'fireworks-conf-'));
+        try {
+            for (const entry of MUST_NOT_SERVE) {
+                checksRun++;
+                const res = await handleFireworksTwinRequest({ method: entry.method, path: entry.path, root });
+                if (res.status !== 404)
+                    fail('must_not_serve', `${entry.method} ${entry.path} answered ${res.status}, not 404 — ${entry.why}`);
+                // The vendor 404s carry EITHER plane's envelope: the inference plane's {error:{…}} or the
+                // control plane's google.rpc {code, message}.
+                else if (!isObj(res.body) || (!isObj(res.body.error) && res.body.code === undefined))
+                    fail('must_not_serve', `${entry.method} ${entry.path} 404 body is not the vendor error envelope`);
+            }
+        }
+        finally {
+            if (root !== opts.root)
+                rmSync(root, { recursive: true, force: true });
+        }
+    }
+    return { ok: violations.length === 0, checksRun, probes: PROBES.length, violations };
+}