@volter/twin-fireworks 0.1.0

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

@@ -0,0 +1,212 @@
+/** One message in a chat request. `reasoning_content` on assistant messages is a Fireworks
+ *  extension (reasoning models return it; `reasoning_history` controls whether it is replayed). */
+export type FireworksMessageParam = {
+    role: string;
+    content?: unknown;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    reasoning_content?: string | null;
+};
+/** The `service_tier` enum is Fireworks' own; only 'priority' is honored — every other value is
+ *  treated as 'default' (documented; NOT an error). */
+export type FireworksServiceTier = 'auto' | 'default' | 'flex' | 'priority';
+/** Fireworks' documented OpenAI difference: the default is `truncate`, not `error`. */
+export type FireworksContextLengthExceededBehavior = 'error' | 'truncate';
+export type FireworksChatRequest = {
+    model: string;
+    messages: FireworksMessageParam[];
+    temperature?: number | null;
+    top_p?: number | null;
+    top_k?: number | null;
+    frequency_penalty?: number | null;
+    presence_penalty?: number | null;
+    max_tokens?: number | null;
+    max_completion_tokens?: number | null;
+    n?: number | null;
+    stop?: string | string[] | null;
+    stream?: boolean | null;
+    stream_options?: {
+        include_usage?: boolean;
+        buffer_tokens?: number;
+        buffer_ms?: number;
+        buffer_mode?: string;
+    } | null;
+    tools?: Array<Record<string, unknown>>;
+    tool_choice?: unknown;
+    parallel_tool_calls?: boolean | null;
+    response_format?: Record<string, unknown> | null;
+    reasoning_effort?: string | number | boolean | null;
+    reasoning_history?: 'disabled' | 'interleaved' | 'preserved' | null;
+    service_tier?: FireworksServiceTier | null;
+    context_length_exceeded_behavior?: FireworksContextLengthExceededBehavior | null;
+    seed?: number | null;
+    user?: string | null;
+    echo?: boolean | null;
+    logprobs?: boolean | null;
+    top_logprobs?: number | null;
+    logit_bias?: Record<string, number> | null;
+    metadata?: Record<string, unknown> | null;
+};
+export type FireworksChatMessage = {
+    role: 'assistant';
+    content: string | null;
+    reasoning_content?: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+};
+/** The response envelope: `usage` is nullable on chat (absent when `echo`/logprobs paths skip it),
+ *  unlike `Completion` below where the spec marks it required. */
+export type FireworksChatCompletion = {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: FireworksChatMessage;
+        finish_reason: string | null;
+        logprobs?: unknown | null;
+        token_ids?: number[] | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        total_tokens: number;
+        completion_tokens: number;
+    } | null;
+};
+/** Legacy `/v1/completions`: the spec marks `usage` REQUIRED here (chat's is nullable). */
+export type FireworksCompletion = {
+    id: string;
+    object: 'text_completion';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        text: string;
+        finish_reason: string | null;
+        logprobs?: unknown | null;
+    }>;
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+        completion_tokens: number;
+    };
+};
+/** The Responses API (`/v1/responses`): `id` is nullable when `store=false` (the vendor's own
+ *  contract — a non-stored response has no id to retrieve later). */
+export type FireworksResponseObject = {
+    id: string | null;
+    object: 'response';
+    created_at: number;
+    status: 'completed' | 'in_progress' | 'incomplete' | 'failed' | 'cancelled';
+    model: string;
+    output: Array<FireworksResponseOutputItem>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    } | null;
+    error?: unknown | null;
+    incomplete_details?: unknown | null;
+    instructions?: unknown | null;
+    max_output_tokens?: number | null;
+    metadata?: Record<string, unknown> | null;
+    parallel_tool_calls?: boolean | null;
+    previous_response_id?: string | null;
+    reasoning?: unknown | null;
+    store?: boolean | null;
+    temperature?: number | null;
+    text?: unknown | null;
+    tool_choice?: unknown;
+    tools?: Array<Record<string, unknown>> | null;
+    top_p?: number | null;
+    truncation?: string | null;
+    user?: string | null;
+};
+export type FireworksResponseOutputItem = {
+    type: 'message';
+    id: string;
+    role: 'assistant';
+    status: 'in_progress' | 'completed';
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+} | {
+    type: 'function_call';
+    id: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+    status?: string;
+} | {
+    type: 'function_call_output';
+    tool_call_id: string;
+    output: unknown;
+};
+/** Anthropic-compatible `/v1/messages`: the response `content` is an array of typed blocks, and
+ *  `stop_reason` is Anthropic's enum (never OpenAI's `finish_reason`). */
+export type FireworksAnthropicMessage = {
+    id: string;
+    type: 'message';
+    role: 'assistant';
+    content: Array<FireworksAnthropicContentBlock>;
+    model: string;
+    stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal' | null;
+    stop_sequence: string | null;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+};
+export type FireworksAnthropicContentBlock = {
+    type: 'text';
+    text: string;
+    citations?: unknown[] | null;
+} | {
+    type: 'thinking';
+    thinking: string;
+    signature: string;
+} | {
+    type: 'redacted_thinking';
+    data: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+};
+/** The Anthropic error envelope: `{ type: 'error', error: { type, message }, request_id? }` — a
+ *  DIFFERENT envelope from the OpenAI-compat plane's `{ error: { … } }`. */
+export type FireworksAnthropicErrorType = 'invalid_request_error' | 'authentication_error' | 'billing_error' | 'permission_error' | 'not_found_error' | 'rate_limit_error' | 'timeout_error' | 'api_error' | 'overloaded_error';
+/** google.rpc-style status, embedded on every resource as `status` and (per the vendor's own
+ *  comment) mimicking google/rpc/status.proto. */
+export type FireworksGatewayStatus = {
+    code: FireworksGatewayCode;
+    message?: string;
+} | null;
+/** The gatewayCode enum — the gRPC canonical codes, as strings. */
+export type FireworksGatewayCode = 'OK' | 'CANCELLED' | 'UNKNOWN' | 'INVALID_ARGUMENT' | 'DEADLINE_EXCEEDED' | 'NOT_FOUND' | 'ALREADY_EXISTS' | 'PERMISSION_DENIED' | 'UNAUTHENTICATED' | 'RESOURCE_EXHAUSTED' | 'FAILED_PRECONDITION' | 'ABORTED' | 'OUT_OF_RANGE' | 'UNIMPLEMENTED' | 'INTERNAL' | 'UNAVAILABLE' | 'DATA_LOSS';
+/** The list envelope every Gateway list operation answers. */
+export type FireworksListEnvelope<T> = {
+    items?: never;
+} & {
+    [K in string]: T[];
+} & {
+    nextPageToken?: string | null;
+    totalSize?: number | null;
+};

package/dist/src/fireworks-types.js

@@ -0,0 +1,4 @@
+// Fireworks wire shapes, typed narrowly — the subsets of the vendor's real response shapes this
+// pack reads and writes, grounded in the first-party OpenAPI specs (see specSource in index.ts).
+// Where Fireworks differs from OpenAI the difference is NAMED here, not papered over.
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export { handleFireworksTwinRequest, FIREWORKS_INFERENCE_PREFIX, FIREWORKS_ACCOUNTS_PREFIX } from './fireworks-twin.js';
+export type { FireworksRequest, FireworksResponseEnvelope } from './fireworks-twin.js';
+export { createFireworksTwinFetch, createFireworksTwinServer, type FireworksTwinFetchOptions } from './fireworks-server.js';
+export { fullSyncFireworks, fireworksRequestForAction, liveFireworksExecute, pullFireworksState, pushFireworksAction, pushPendingFireworksActions, syncFireworksFromReal, unpushableReason, } from './fireworks-connector.js';
+export type { FireworksExecute, LiveFireworksOptions } from './fireworks-connector.js';
+export { FIREWORKS_BUDGET_CEILING, FIREWORKS_BUDGET_MAX_RETRY_AFTER_S, FIREWORKS_BUDGET_WINDOW_MS, FIREWORKS_CALL_WEIGHTS, FIREWORKS_RATE_BUDGET, FireworksBudget, FireworksBudgetError, fireworksBudgetPath, fireworksCallWeight, } from './fireworks-budget.js';
+export type { FireworksBudgetErrorKind, FireworksBudgetOptions, FireworksBudgetReservation, FireworksBudgetSnapshot } from './fireworks-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,105 @@
+// @volter/twin-fireworks — the Fireworks twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. Fireworks serves TWO API planes on ONE host (api.fireworks.ai):
+//
+//   • the INFERENCE plane — `https://api.fireworks.ai/inference/v1/…`, OpenAI-compatible
+//     (chat/completions, completions, responses, embeddings, rerank) plus an Anthropic-compatible
+//     POST /v1/messages. Generative output is a labeled deterministic stub; the wire protocol and
+//     Fireworks' documented OpenAI differences are the fidelity surface.
+//   • the CONTROL plane — the Gateway REST API (`https://api.fireworks.ai/v1/accounts/{account_id}/…`):
+//     deployments, datasets, fine-tuning jobs, users/apiKeys, secrets, models, quotas — a stateful
+//     google.rpc-style surface (list envelopes {items, nextPageToken, totalSize}, verb-suffixed
+//     custom methods like `:cancel`, ids passed via query params on writes).
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so inference returns a
+// DETERMINISTIC STUB completion (clearly labeled `[twin-stub:<model>]`), never pretending to be
+// real inference. Everything around it — the wire protocol, the rejections, the state — is faithful.
+// (Conformance + capability tooling live in @volter/world-tooling, a dev dependency — NOT
+// re-exported here, per E2.)
+export { handleFireworksTwinRequest, FIREWORKS_INFERENCE_PREFIX, FIREWORKS_ACCOUNTS_PREFIX } from "./fireworks-twin.js";
+export { createFireworksTwinFetch, createFireworksTwinServer } from "./fireworks-server.js";
+export { fullSyncFireworks, fireworksRequestForAction, liveFireworksExecute, pullFireworksState, pushFireworksAction, pushPendingFireworksActions, syncFireworksFromReal, unpushableReason, } from "./fireworks-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveFireworksExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Fireworks' DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `FireworksBudgetError` by type; there is deliberately no export that disables the guard.
+export { FIREWORKS_BUDGET_CEILING, FIREWORKS_BUDGET_MAX_RETRY_AFTER_S, FIREWORKS_BUDGET_WINDOW_MS, FIREWORKS_CALL_WEIGHTS, FIREWORKS_RATE_BUDGET, FireworksBudget, FireworksBudgetError, fireworksBudgetPath, fireworksCallWeight, } from "./fireworks-budget.js";
+import { FIREWORKS_RATE_BUDGET as RATE_BUDGET } from "./fireworks-budget.js";
+import { performFireworksAction, syncFireworksFromRemote } from "./fireworks-connector.js";
+export const pack = {
+    vendor: 'fireworks',
+    // The SAME object fireworks-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    // PROTOCOL 2 (pack contract Part 3): the pack is a plugin — its wire, its tree, and its half of
+    // the real state system. The control plane is the stateful surface (deployments, datasets,
+    // fine-tuning jobs, users/apiKeys, secrets); inference is generative and stores nothing.
+    protocol: '2',
+    refresh: { every: '15m', onDemand: { atMost: '60s' } },
+    stateSystem: { perform: performFireworksAction, refresh: syncFireworksFromRemote },
+    // The round trip: a chat completion — the one call every Fireworks integration makes first, and
+    // the one whose answer proves the wire is live end to end — then a DEPLOYMENT, because inference
+    // is generative and stores nothing; the control plane is what has state. The deployment carries no
+    // `deploymentId`, so the vendor mints one (the spec makes it optional) and the create repeats
+    // cleanly on a branch that inherited the first.
+    roundTrip: [
+        { method: 'POST', path: '/inference/v1/chat/completions', body: { model: 'accounts/fireworks/models/kimi-k2-instruct', messages: [{ role: 'user', content: 'round trip' }] }, headers: { authorization: 'Bearer round-trip' } },
+        { method: 'POST', path: '/v1/accounts/round-trip/deployments', body: { baseModel: 'accounts/fireworks/models/kimi-k2-instruct', displayName: 'round trip' }, headers: { authorization: 'Bearer round-trip' } },
+    ],
+    parityOrigin: 'http://twin',
+    archetype: 'generative',
+    bin: 'world-fireworks',
+    // The subject types the twin SERVES from its own state — the R2 resource-level claim. Inference
+    // (chat/completions, completions, responses, messages, embeddings, rerank) is generative and
+    // stores nothing; the control plane is what has state.
+    resources: ['deployment', 'dataset', 'batchInferenceJob', 'supervisedFineTuningJob', 'user', 'apiKey', 'secret', 'model'],
+    // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+    resourcesUnreachable: {
+        account: 'the vendor’s own account row (one per credential, not creatable through the API)',
+        quota: 'vendor-assigned limits (read-only in the API; the twin derives them from the account)',
+        serverlessModel: 'the vendor catalog (serverless models are curated by Fireworks, not created by callers)',
+    },
+    specSource: 'Fireworks first-party OpenAPI spec (https://docs.fireworks.ai/merged.openapi.yaml, downloaded 2026-09-16): ' +
+        'the merged Gateway REST API 5.10.0 document covering the control plane (api.fireworks.ai/v1/accounts/{account_id}/…) ' +
+        'AND the inference plane namespaces (chat/completions, completions, Responses, Anthropic-compatible messages). ' +
+        'The embeddings and rerank operations are documented on the vendor api-reference pages only ' +
+        '(docs.fireworks.ai/api-reference — post /embeddings, post /rerank), not in the merged spec. ' +
+        'The earlier cited URLs (api.fireworks.ai and app.fireworks.ai api/docs/openapi.json, the per-plane ' +
+        'api-reference *-openapi.* files) are dead (404, checked 2026-09-16). Envelope-faithful; ' +
+        'model output, embedding values and rerank scores are labeled deterministic stubs.',
+    description: 'Fireworks AI twin — the OpenAI-compatible inference plane (chat/completions + streaming, completions, ' +
+        'Responses API CRUD, Anthropic-compatible /v1/messages, embeddings, rerank) with Fireworks’ documented ' +
+        'OpenAI differences (usage in the final stream chunk by default, context_length_exceeded_behavior, ' +
+        "service_tier 'priority'-only), plus the stateful Gateway control plane (deployments, datasets, " +
+        'batch-inference and supervised-fine-tuning jobs, users/apiKeys, secrets, models) with google.rpc-style ' +
+        'statuses; generative output is a labeled deterministic stub.',
+    // Fireworks serves BOTH planes on ONE host: the inference plane under /inference/v1/ and the
+    // control plane under /v1/accounts/{account_id}/. `apiPathPrefix` is a single startsWith prefix,
+    // so '/v' is the narrowest value that routes BOTH surfaces to the twin.
+    browserRouting: { apiPathPrefix: '/v', loaderHost: 'https://api.fireworks.ai' },
+    // ADOPTION — how an app repo betrays that it talks to Fireworks, so `volter-world covers`/
+    // `init` can attribute the signal here. Declared ON THE DESCRIPTOR, never in the central
+    // SDK_TWINS / SDK_SCOPE_VENDORS / ENV_STEM_VENDORS / VENDOR_WORLD_IDS maps: declaring a fact in
+    // both homes THROWS (world-runtime/src/pack-facts.ts, `overlay*`). `fireworks-ai` is Fireworks'
+    // official Python client; `@ai-sdk/fireworks` is the Vercel AI SDK provider. `FIREWORKS` covers
+    // FIREWORKS_API_KEY / FIREWORKS_BASE_URL, the names both clients read.
+    adoption: {
+        pypi: ['fireworks-ai'],
+        sdks: ['@ai-sdk/fireworks'],
+        envStems: ['FIREWORKS'],
+    },
+    // INTERCEPTION: the one host both planes are addressed on (the `fireworks` Python client and
+    // @ai-sdk/fireworks both default to api.fireworks.ai; the inference base URL is
+    // https://api.fireworks.ai/inference).
+    hosts: [{ host: 'api.fireworks.ai' }],
+    // No app-read endpoint env, deliberately. The `fireworks` Python client reads FIREWORKS_BASE_URL
+    // — but the app-read table is the FALLBACK for packs the injector cannot intercept, and this pack
+    // declares `hosts`, so FIREWORKS_TWIN_URL + zero-edit interception is the better answer. Emitting
+    // both would quietly forgo interception (`init.test.ts`, "the app-read endpoint table cannot go
+    // stale behind the injector").
+    endpointEnvNone: 'The injector intercepts api.fireworks.ai (see `hosts`), so a world wires this pack through FIREWORKS_TWIN_URL rather than an app-read base-URL var. The `fireworks` Python client would honour FIREWORKS_BASE_URL, but @ai-sdk/fireworks — the dominant client in this repo’s demand census — takes its baseURL as a constructor option and reads no such env, so an app-read var would cover only half the traffic while disabling the interception that covers all of it.',
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+import { registerPack } from '@volter/world-core';
+registerPack(pack);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@volter/twin-fireworks",
+  "version": "0.1.0",
+  "description": "Local Fireworks AI twin — OpenAI-compatible inference + Anthropic-compatible messages + the stateful Gateway control plane, envelope-faithful with labeled deterministic stubs. Built on @volter/twin.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/fireworks"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/fireworks#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-fireworks": "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": {
+    "@ai-sdk/fireworks": "^3.0.52",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-fireworks CLI: serve the Fireworks AI twin or run conformance. Fireworks is an
+// API-first vendor — its console is a deployments/usage dashboard, not where the work happens
+// — so this pack ships no mirror.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createFireworksTwinServer } from './fireworks-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted responses (JSON file)
+
+if (cmd === 'serve') {
+  const s = await createFireworksTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+  process.stdout.write(`fireworks twin (Gateway control plane at /v1/accounts/{account_id}; inference at /inference/v1)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling
+  const { checkFireworksConformance } = await import('./fireworks-conformance.ts');
+  const report = await checkFireworksConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-fireworks serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/src/fireworks-budget.ts

@@ -0,0 +1,172 @@
+// Fireworks' CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveFireworksExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that
+// module's header for the full rationale AND for the honest list of what the guard does not
+// guarantee.
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN (live-read, 2026-09-16) ───────────────────────────────────────
+// https://docs.fireworks.ai/serverless/rate-limits (read 2026-09-16) publishes NO scalar per-key
+// request limit a client could be bound by. Fireworks meters THREE token-per-minute metrics —
+// Total Prompt TPM, Uncached Prompt TPM and Generated TPM — each "per account and per model", and
+// the ceilings are ADAPTIVE: an account's allowance scales within its size tier based on recent
+// usage, so the only place the real numbers live is the account's own dashboard. The docs also
+// state rate-limit headers are not currently returned, so there is no response-derived backstop
+// signal to bind.
+//
+// So this declaration does not model Fireworks' limit, and nothing here is more permissive than
+// the kernel's undeclared fallback: window 60s, ceiling 60, defaultWeight 2 — i.e. 30 calls/minute,
+// EXACTLY `DEFAULT_RATE_BUDGET`, with no endpoint priced cheaper than the fallback would price it.
+// What the declaration buys is RESOLUTION, and it deliberately buys it DOWNWARD: the inference
+// endpoints (the token-metered ones — every TPM metric above is about inference traffic) cost 6,
+// so at most TEN of them land in a window. Being stricter than the fallback needs no vendor
+// justification; being looser would, and there is none to have.
+//
+// It bounds the 60s AVERAGE; it does not pace (the kernel refuses, it never sleeps). The backstop
+// for a sub-second burst is the `Retry-After`/429 cooldown, and it is the ONLY backstop. Fireworks
+// DOES document rate-limit response headers — `X-Ratelimit-Limit-Tokens-Prompt`,
+// `X-Ratelimit-Limit-Tokens-Cache-Adjusted-Prompt`, `X-Ratelimit-Limit-Tokens-Generated` — but they
+// carry TOKEN CEILING values, not a remaining-count or a retry-after, so none of them is a signal
+// the kernel's cooldown can arm on. Unlike the groq declaration there is no header-derived
+// cooldown trigger: only a real 429 (or an explicit `Retry-After`) can arm it.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ───────────────────────────────
+//   • The inference endpoints cost 6: all THREE published TPM metrics are about inference traffic,
+//     so one chat/completions/embeddings/rerank request consumes far more of the account's real
+//     allowance than a deployments list poll. 60/6 = 10 per window is a deliberate tightening,
+//     not a matched published figure — Fireworks publishes no RPM at all.
+//   • Everything else (control-plane CRUD on the Gateway REST surface) costs 2 — the fallback's
+//     own default.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'fireworks';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const FIREWORKS_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback, because Fireworks publishes no scalar that would
+ * justify more. See the header.
+ */
+export const FIREWORKS_BUDGET_CEILING = 60;
+
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const FIREWORKS_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const FIREWORKS_CALL_WEIGHTS = {
+  /** The token-metered inference surface: `/inference/v1/chat/completions`,
+   *  `/inference/v1/completions`, `/inference/v1/responses`, `/inference/v1/embeddings`,
+   *  `/inference/v1/rerank` and `/inference/v1/messages`. Every published TPM metric (Total
+   *  Prompt, Uncached Prompt, Generated) is about exactly this traffic. At 60/6 = 10 per window —
+   *  a deliberate tightening below the fallback's 30, since Fireworks publishes no request-rate
+   *  figure at all. */
+  inference: 6,
+  /** Everything else: Gateway control-plane CRUD (deployments, datasets, fine-tuning jobs, …). */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Fireworks-specific thing in the whole budget. */
+export const FIREWORKS_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: FIREWORKS_BUDGET_WINDOW_MS,
+  ceiling: FIREWORKS_BUDGET_CEILING,
+  defaultWeight: FIREWORKS_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: FIREWORKS_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /inference/v1/(chat/completions|completions|responses|embeddings|rerank|messages)$', weight: FIREWORKS_CALL_WEIGHTS.inference },
+  ],
+  reason:
+    'Fireworks publishes NO scalar per-key request limit (docs.fireworks.ai/serverless/rate-limits, ' +
+    'read 2026-09-16): it meters THREE token-per-minute metrics — Total Prompt TPM, Uncached Prompt ' +
+    'TPM and Generated TPM — each per account AND per model, with ADAPTIVE ceilings that scale within ' +
+    "a size tier based on recent usage, so the real numbers live only on the account's dashboard. " +
+    'Its documented rate-limit response headers (X-Ratelimit-Limit-Tokens-Prompt / ' +
+    '-Cache-Adjusted-Prompt / -Generated) carry TOKEN CEILING values, not a remaining count or a ' +
+    'retry-after, so no header is a signal the cooldown can arm on. Because no published figure ' +
+    'justifies going higher, the ceiling is pinned at the kernel fallback in EVERY dimension — ' +
+    '60 units / 60s at defaultWeight 2 = 30 calls/min — and the declaration buys resolution ' +
+    'DOWNWARD, never headroom: the inference endpoints cost 6, so at most 10 land in a window. ' +
+    'The window bounds the 60s AVERAGE and does not pace; the `retry-after`/429 cooldown is the ' +
+    'only sub-second-burst backstop.',
+};
+
+// Declared at module load, so merely importing this module (which `fireworks-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, FIREWORKS_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Fireworks. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function fireworksCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+  // `execute('post', …)` really does issue a POST and must be priced as one.
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/**
+ * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the
+ * query. NORMALIZED, because the anchored rules are otherwise trivially evaded: `fetch` upper-cases
+ * a known method before sending, so `execute('post', …)` issues a real WRITE that a `^POST ` rule
+ * would price as a read; and a trailing slash makes a path miss a `$` anchor while most routers
+ * treat it as the same endpoint.
+ */
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  // Collapse REPEATED slashes as well as a trailing one: `/inference/v1//chat/completions` reaches
+  // the same endpoint on most routers but misses a `^POST /inference/v1/(chat/completions|…)$` rule,
+  // which would price an inference call as a 2-unit read.
+  const raw = (at === -1 ? path : path.slice(0, at)).replace(/\/{2,}/g, '/');
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where Fireworks' ledger lives. Token-keyed and cwd-independent by default (Fireworks' limits
+ *  are per ACCOUNT, i.e. per key, so a cwd-scoped ledger would hand the same key a fresh allowance
+ *  in every checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export function fireworksBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for Fireworks' budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type FireworksBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Fireworks' budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof FireworksBudget` in `liveFireworksExecute` means "a budget
+ * that accounts against FIREWORKS' ledger under FIREWORKS' ceiling".
+ */
+export class FireworksBudget extends RateBudget {
+  constructor(opts: FireworksBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as FireworksBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as FireworksBudgetErrorKind } from '@volter/world-core';
+export type FireworksBudgetReservation = RateBudgetReservation;
+export type FireworksBudgetSnapshot = RateBudgetSnapshot;