@volter/twin-fireworks 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,184 @@
+# @volter/twin-fireworks
+
+A local, faithful **Fireworks AI** twin your real `fireworks` Python client or
+`@ai-sdk/fireworks` provider talks to **unmodified** — point the client at the twin's host and
+chat completions (OpenAI-compatible + streaming), the legacy completions endpoint, the Responses
+API, the Anthropic-compatible `/v1/messages`, embeddings, rerank, and the stateful Gateway control
+plane (deployments, datasets, batch-inference and supervised-fine-tuning jobs, users/apiKeys,
+secrets, models) all work. Built on the shared `@volter/world-core` kernel; see
+[the model](../../../docs/concepts/the-model.md) for storage and branching; no parallel side store.
+
+```ts
+import { createFireworks } from '@ai-sdk/fireworks';
+import { createFireworksTwinServer } from '@volter/twin-fireworks';
+
+const { port } = createFireworksTwinServer({});
+// The provider's default baseURL is https://api.fireworks.ai/inference/v1 and it appends
+// /chat/completions to it — the twin serves that same prefix, so "swap the host" is the
+// whole configuration.
+const fireworks = createFireworks({ apiKey: 'fw_twin', baseURL: `http://127.0.0.1:${port}/inference/v1` });
+const result = await generateText({ model: fireworks('accounts/fireworks/models/kimi-k2-instruct'), prompt: 'hello' });
+// result.text starts with "[twin-stub:…]" — a deterministic stub, clearly labeled.
+```
+
+Fireworks serves **two API planes on one host** (`api.fireworks.ai`), and the twin serves both at
+their real wire prefixes:
+
+| plane | prefix | surface |
+|---|---|---|
+| inference | **`/inference/v1/…`** | `chat/completions`, `completions`, `responses`, `embeddings`, `rerank`, and the Anthropic-compatible `messages` |
+| control | **`/v1/accounts/{account_id}/…`** | deployments, datasets, batch-inference jobs, supervised fine-tuning jobs, users, apiKeys, secrets, models |
+
+The merged spec some clients are generated from publishes the inference operations at `/v1/…`
+with `servers: https://api.fireworks.ai/inference` — same operations, different spelling. The
+twin serves the **real** wire prefix; a request to the bare `/v1/chat/completions` 404s, because
+the real vendor does not serve it either — a twin that answered there would let a mis-configured
+client "work" locally and then fail against the real vendor.
+
+## Fireworks is not OpenAI — the differences this twin models
+
+The inference plane is *OpenAI-compatible*, and treating "compatible" as "identical" is how a
+Fireworks twin gets built wrong. The load-bearing differences, grounded in Fireworks' own
+published specs (see `specSource` in `src/index.ts`) and docs, read 2026-09-16:
+
+| | Fireworks | OpenAI |
+|---|---|---|
+| base path | **`https://api.fireworks.ai/inference/v1/…`** | `https://api.openai.com/v1/…` |
+| validation errors | the **FastAPI** envelope: `422` with `{ detail: [{ loc, msg, type }] }` | `{ error: { message, type, param, code } }` with 400 |
+| streaming usage | in the **final chunk's `usage`, by default** (opt out with `stream_options.include_usage: false`) | opt-IN via `stream_options.include_usage` |
+| `service_tier` | **`priority`-only** (plus `auto`); `flex`/`performance` are not Fireworks tiers | a different set |
+| context overflow | modeled as a **request field**: `context_length_exceeded_behavior` (`truncate_left` / `middle_truncate` / `error`) | not a request field |
+| reasoning models | expose **`reasoning_content`** on the message | `reasoning` content blocks |
+| `max_tokens` / `max_completion_tokens` | **cannot both be set** — 400 naming the alias | both accepted |
+| error envelope (inference) | `{ error: { message, … } }` (OpenAI shape) / Anthropic shape on `/v1/messages` | `{ error: { message, type, param, code } }` |
+| error envelope (control) | **google.rpc style**: `{ code: <gatewayCode>, message }` | OpenAI shape |
+| control-plane writes | ids passed via **query params** (`POST …/deployments?deploymentId=x`), custom methods as **verb suffixes** (`:cancel`, `:scale`, `:undelete`, `apiKeys:delete`) | ids in the body; verbs as separate resources |
+| list envelopes | `{ items, nextPageToken, totalSize }` + `pageToken` pagination | `{ data, has_more }` |
+| deletes | answer **`{}`** (empty object), not a `deleted: true` echo | `{ id, deleted }` |
+
+## The generative-stub design (be honest)
+
+The twin **cannot run the model** — there are no weights here. So `POST /inference/v1/chat/completions`
+returns a **deterministic STUB completion** that is unmistakably a twin stub (it carries a
+`[twin-stub:<model>]` marker and echoes your prompt), `POST /inference/v1/embeddings` returns
+**deterministic pseudo-vectors** (L2-normalized, seeded from the input hash), and `rerank` returns
+**deterministic overlap-biased scores**. They **never** pretend to be real model output.
+
+What **is** faithful is the **entire protocol envelope**:
+
+- chat response shape — `{ id:'chatcmpl-…', object:'chat.completion', created, model, choices:[{index, message:{role:'assistant', content, reasoning_content?}, logprobs, finish_reason}], usage }`
+- **streaming** via SSE — real `data: {…chat.completion.chunk with choices[].delta…}` chunks ending with `data: [DONE]` (role chunk → reasoning/content deltas → the finish chunk carrying `usage` by default; driven through an injected sink — no real sockets in the handler). The legacy completions stream uses the legacy chunk shape throughout (`object: 'text_completion'`, delta in `choices[].text`, same final-chunk usage default). The Anthropic-compatible `/v1/messages` streams its OWN event sequence (`message_start` → `content_block_delta` → `message_delta` with the real token counts → `message_stop`) and **no `[DONE]` sentinel**
+- **the Responses API** — create (with `store: false` → `id: null`), retrieve, list (`{ data, has_more }`), delete
+- **the Anthropic-compatible messages** — the Anthropic envelope, `max_tokens` optional (Fireworks' difference from Anthropic), `stop_reason`, system as blocks, the Anthropic error shape on both planes' 401
+- `max_tokens` / `max_completion_tokens` (mutually exclusive), `stop` (earliest hit), `response_format` `json_object`, `reasoning_effort` → `reasoning_content`, `context_length_exceeded_behavior`, `service_tier` (`auto`/`priority` only); **deterministic usage**
+- **Embeddings** — `{ object:'list', data:[{object:'embedding', index, embedding}], model, usage }`, `dimensions` parameter, `encoding_format` `float`/`base64`
+- **Rerank** — query-responsive ordering (shared-token overlap), `top_n`, `return_documents`
+
+The genuinely **stateful + static** surface is real, not a stub:
+
+- **Deployments** — create (id via query param), get, list (paginated), delete (`{}`), undelete (`:undelete`), scale (both the `:scale` POST spelling and the spec's PATCH spelling), read-only-field PATCH tolerated, duplicate-create 409, `baseModel` required
+- **Datasets** — create (body-carried id), lifecycle
+- **Batch-inference jobs** — create (dataset reference validated — the dataset must really exist, 400 otherwise), cancel (`:cancel`), cancel-in-wrong-state refused
+- **Supervised fine-tuning jobs** — create over a dataset that must really exist (400 otherwise)
+- **Users & apiKeys** — role validation, key returned exactly once (create response only — the LIST answers it never), delete via the collection-level `apiKeys:delete` body spelling, cross-user key access refused through both the id-segment and collection-level spellings
+- **Secrets** — `value` never on read, `name`/`keyName` required
+- **Models** — create + list
+
+Vendor-shaped errors throughout: `400` / `401` / `404` / `405` (read-only guard) / `409` / `422`
+(FastAPI) / `429` (scripted) — the inference plane in its OpenAI/Anthropic envelopes, the control
+plane in google.rpc `{ code, message }` with the vendor's own `gatewayCode` enum (`NOT_FOUND`,
+`ALREADY_EXISTS`, …). Mixing the planes' envelopes is a wire lie the twin never commits.
+
+## Scenario scripting (twin-only)
+
+Chat completions can be scripted by MSW-shaped handlers in a world dir's `handlers/fireworks.json`,
+run by the ONE kernel scenario engine with this pack's adapter:
+
+```json
+{ "handlers": [
+  { "on": { "userTextIncludes": "refund" },
+    "respond": { "text": "Refund queued." }, "once": true },
+  { "on": { "modelEndsWith": "kimi-k2-instruct" }, "respond": { "error": { "type": "rate_limit_exceeded" } } }
+] }
+```
+
+Load it with `--scenario FILE` / `createFireworksTwinServer({ scenarioPath })` /
+`TWIN_FIREWORKS_SCENARIO`. The read doors `GET /twin` and `GET /twin/scenario` explain and inspect
+it. A malformed file throws **at load**, never a silent fall-back. Scenario support is twin-only
+scaffolding for eval worlds, not vendor surface, so it is deliberately **not** in the capability
+manifest.
+
+## CLI
+
+```
+world-fireworks serve       [--port N] [--root DIR] [--read-only] [--scenario FILE]
+world-fireworks conformance [--root DIR]
+```
+
+## Connector (pull / push)
+
+`pullFireworksState` folds the real control plane (deployments, datasets, both job families,
+users, apiKeys, secrets, models) into the twin — each collection paginated to exhaustion, so the
+kernel's tombstone sweep marks subjects that vanished remotely as `deleted: true` locally;
+`pushFireworksAction` /
+`pushPendingFireworksActions` push pending local writes (create / delete / scale / undelete) to
+the real API and confirm them by the **vendor's** `_external_id`; `fullSyncFireworks` and
+`syncFireworksFromRemote` are the protocol-2 refresh entry points. All vendor I/O is over an
+**injected executor** (`liveFireworksExecute(apiKey)` live; a fake in tests) — the pack holds no
+key and imports no SDK at runtime. Every live call is charged against the shared kernel
+`RateBudget` **before** it goes out, and the executor refuses any path outside
+`/inference/v1/` and `/v1/accounts/`. Fireworks publishes no scalar request limit and no
+header a cooldown could arm on, so the declaration is pinned at the kernel fallback and buys
+resolution **downward** (inference endpoints cost 6 → at most 10 per window); see
+`fireworks-budget.ts` for the full reasoning.
+
+## Coverage
+
+The capability manifest (`fireworks-capabilities.ts`) enumerates the **real Fireworks API
+surface** as the honest denominator, enumerated top-down from the five first-party OpenAPI specs
+(see `specSource`) plus `docs.fireworks.ai` (read 2026-09-16); `verify()` proves each `done`
+against the local twin, offline + deterministically. Run
+`bun scripts/twin-capabilities.ts fireworks` for the live numbers.
+
+Coverage is **partial and honest**: the served protocol envelopes are enumerated and proven, but
+whole product areas are modeled only as gaps — the serverless model catalog and its rate limits,
+account quotas, the dataset-upload extra, the fine-tuning lifecycle (create→READY with training
+progression), per-request response ids, per-request chat completions inside batch outputs (the
+batch OUTPUT surface is unmodeled entirely — jobs stay in their early state), and the image
+generation surface the `@ai-sdk/fireworks` provider reaches (`/image_generation/{model}` legacy
+and the async workflows pair) are all `todo`.
+
+### Done (proven, verifiable)
+- **Chat Completions** — create + faithful envelope, the labeled stub, FastAPI 422 validation,
+  the `max_tokens`/`max_completion_tokens` mutual exclusion, `service_tier` priority-only,
+  `context_length_exceeded_behavior`, `stop`, `max_tokens` length finish, `reasoning_content`,
+  `json_object` response format
+- **Streaming** — the chunk sequence, usage on the final chunk **by default** (the Fireworks
+  difference) with `include_usage: false` opting out, the pre-stream refusal answering a real
+  status (never a 200 event stream)
+- **Legacy completions** — create, prompt arrays, streaming in the legacy chunk shape (usage on the final chunk by default, `include_usage: false` opting out)
+- **Responses API** — create + retrieve, `store: false` → `id: null`, delete, the list envelope
+- **Anthropic-compatible messages** — the Anthropic envelope, `max_tokens` optional,
+  `stop_reason`, the Anthropic error envelope, streaming, system as blocks (priced into
+  `input_tokens`, echoed when the user content is whitespace)
+- **Embeddings** — create, L2-normalized vectors, `dimensions`, array input
+- **Rerank** — create, query-responsive ordering, `top_n` + `return_documents`
+- **Auth** — missing key, invalid key, any non-empty key accepted, the Anthropic plane gated with
+  its OWN error envelope
+- **Errors** — unknown-path 404, the scripted 429
+- **Deployments** — create (query-param id), get, list, pagination, delete (`{}`), delete-then-404,
+  read-only-field PATCH, undelete, scale (both spellings), duplicate 409, `baseModel` required
+- **Datasets / Batch jobs / SFT / Users / apiKeys / Secrets / Models** — as listed above
+- **Connector** — control-plane pull, refusal-is-not-emptiness, pull idempotency, push create with
+  query params, push delete by the vendor's `_external_id`, inference ops never pushed, request
+  shapes, full sync, the live client's unmodeled-path refusal
+- **Conformance** — one real probe per claimed endpoint plus the hand-authored router census
+
+### No UI mirror
+
+**The API is the product.** When someone does Fireworks' core job they write code against the
+inference API or the Gateway control plane; the Fireworks console is incidental tooling for API
+keys, usage dashboards and deployments — not where the work happens. Per the contributor recipe's
+"Does this vendor get a mirror?" rule (and ../../../docs/contributing/architecture.md C1b), this
+pack therefore ships **no mirror and no UI capabilities**; coverage is API + connector. This
+matches the sibling generative packs (`openai`, `anthropic`, `gemini`, `groq`).

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,28 @@
+#!/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.js";
+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.js");
+    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/dist/src/fireworks-budget.d.ts

@@ -0,0 +1,54 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const FIREWORKS_BUDGET_WINDOW_MS = 60000;
+/**
+ * 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 declare const FIREWORKS_BUDGET_CEILING = 60;
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export declare 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 declare 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. */
+    readonly inference: 6;
+    /** Everything else: Gateway control-plane CRUD (deployments, datasets, fine-tuning jobs, …). */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, the only Fireworks-specific thing in the whole budget. */
+export declare const FIREWORKS_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * 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 declare function fireworksCallWeight(method: string, path: string): number;
+/** 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 declare function fireworksBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** 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 declare class FireworksBudget extends RateBudget {
+    constructor(opts?: FireworksBudgetOptions);
+}
+/** 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;

package/dist/src/fireworks-budget.js

@@ -0,0 +1,146 @@
+// 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, } 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,
+};
+/** THE PACK'S DECLARATION — pure data, the only Fireworks-specific thing in the whole budget. */
+export const FIREWORKS_RATE_BUDGET = {
+    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, path) {
+    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) {
+    const at = path.indexOf('?');
+    const query = {};
+    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 = {}) {
+    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 });
+}
+/**
+ * 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 = {}) {
+        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';

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

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const FIREWORKS_CAPABILITIES: CapabilitySpec[];
+export declare const FIREWORKS_AREAS: readonly ["account", "apiKeys", "auth", "batch_inference", "chat", "completions", "conformance", "control", "connector", "datasets", "deployments", "embeddings", "errors", "fine_tuning", "image_generation", "messages", "models", "quota", "rerank", "responses", "secrets", "serverless", "streaming", "users"];
+export declare function fireworksCapabilities(): Promise<CapabilityReport>;