@volter/twin-fireworks 0.1.0

package/dist/src/fireworks-connector.js

@@ -0,0 +1,641 @@
+// Fireworks CONNECTOR — the live-vendor pull/push path that gives the Fireworks twin the full
+// "git for SaaS" lifecycle, over an INJECTED executor (the auth boundary; the kernel + this pack
+// hold NO key and import NO SDK at runtime).
+//
+// PULL  (real → twin): enumerate the CONTROL plane (the stateful surface — deployments, datasets,
+//                       batch-inference and supervised-fine-tuning jobs, users, models, secrets)
+//                       through the Gateway REST list endpoints and fold into the event log via
+//                       the kernel's `observeResources` (protocol 2 — one batch, one instant,
+//                       shadow-diff dedup, so a re-pull of identical state appends ZERO deltas).
+//                       The INFERENCE plane stores nothing (chat/completions, embeddings, rerank
+//                       are generative), so there is nothing there to pull.
+// PUSH  (twin → real): replay each pending local write against the real Gateway REST surface and
+//                       confirm it. Inference operations are NOT pushes — replaying a completion
+//                       would spend real money and store nothing — so they are refused by name.
+//
+// The vendor I/O is an INJECTED executor (`FireworksExecute`): a fake in tests, `liveFireworksExecute`
+// in prod. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, confirmAction, deployableEntries, observeResources, projectResources } from '@volter/world-core';
+import { FireworksBudget, FireworksBudgetError, fireworksBudgetPath, fireworksCallWeight } from "./fireworks-budget.js";
+const SERVICE = 'fireworks';
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+/** The account every Gateway REST path is addressed under when no caller (or subject namespace)
+ *  supplies one. The vendor keys every control-plane path by account id; the twin models one
+ *  default account, and the perform path derives the account from the SUBJECT's own namespace
+ *  first, falling back to this constant only for a bare id. */
+export const FIREWORKS_ACCOUNT_ID = 'my-account';
+/**
+ * A live executor against the real Fireworks API (the user's own API key). Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own serve path — only constructed
+ * by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.fireworks.ai` request, and therefore the one
+ * place the rate budget is enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `FireworksBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `retry-after` / 429 becomes a persisted cooldown that makes every later call fail fast WITHOUT
+ * touching Fireworks. There is deliberately no OPTION to disable the guard, and no value a caller
+ * can pass for `budget` that yields an unguarded client. What that does NOT claim is immunity from
+ * a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an injected clock,
+ * restores the allowance, because the same seam tests need cannot be denied to a determined caller
+ * in the same process. See `fireworks-budget.ts` and the kernel header for the limits of the
+ * guarantee.
+ */
+export function liveFireworksExecute(apiKey, base = 'https://api.fireworks.ai', opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    // ONE expression decides which budget is used, so there is no second, weaker test that could
+    // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+    // must be an UNMODIFIED FireworksBudget — a duck-typed stand-in, a SUBCLASS overriding
+    // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that would
+    // otherwise hand back a client with no ceiling. The default ledger is keyed by a hash of THIS
+    // key: Fireworks meters per ACCOUNT, so a cwd-scoped ledger would hand the same key a fresh
+    // allowance per checkout/worktree/CI leg.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, FireworksBudget, 'liveFireworksExecute')
+        : new FireworksBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, body) => {
+        // A path this pack never modelled is refused BEFORE the budget is even charged: an executor
+        // that will happily issue any URL is how a careless script reaches an unpriced endpoint.
+        if (!path.startsWith('/inference/v1/') && !path.startsWith('/v1/accounts/')) {
+            throw new Error('fireworks: refusing to call an unmodeled path — Fireworks serves the inference plane under /inference/v1/ and the control plane under /v1/accounts/');
+        }
+        const headers = { authorization: `Bearer ${apiKey}`, accept: 'application/json' };
+        const init = { method, headers };
+        if (method === 'POST' || method === 'PATCH') {
+            headers['content-type'] = 'application/json';
+            init.body = JSON.stringify(body ?? {});
+        }
+        const weight = fireworksCallWeight(method, path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${base}${path}`, init);
+        const resHeaders = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        let data = {};
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = {};
+        }
+        // Settles the reservation and, on a back-off signal, arms the cooldown.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer Fireworks ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof FireworksBudgetError) || !res.ok)
+                throw error;
+        }
+        return { status: res.status, data };
+    };
+}
+// ── PULL: real → twin (protocol 2 — the refresh adapter's fold) ─────────────────────────────
+/** The gateway list envelope: `{ <plural>: [...], nextPageToken, totalSize }`. */
+function envelopeList(data, plural) {
+    if (data === null || typeof data !== 'object')
+        return [];
+    const items = data[plural];
+    return Array.isArray(items) ? items : [];
+}
+/** The kernel subject id for a pulled row: `{account}/{id}` from the vendor's own resource
+ *  `name` (`accounts/{account}/{collection}/{id}`). The twin's create path writes the same
+ *  namespace, so created and pulled rows share ONE id space per (type, account). */
+function namespacedId(name) {
+    const seg = name.split('/');
+    return seg.length >= 4 ? `${seg[1]}/${seg[seg.length - 1]}` : (seg[seg.length - 1] ?? name);
+}
+/** Map one gateway deployment row → a twin sync resource. Vendor `name` is
+ *  `accounts/{account}/deployments/{id}`; the twin keys the resource by the id segment. */
+export function mapDeployment(d) {
+    const name = typeof d.name === 'string' ? d.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'deployment',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            displayName: d.displayName ?? null,
+            baseModel: d.baseModel ?? null,
+            state: d.state ?? 'STATE_UNSPECIFIED',
+            region: d.region ?? null,
+            replicaCount: d.replicaCount ?? null,
+            minReplicaCount: d.minReplicaCount ?? null,
+            maxReplicaCount: d.maxReplicaCount ?? null,
+            precision: d.precision ?? null,
+            createTime: d.createTime ?? null,
+            updateTime: d.updateTime ?? null,
+            status: d.status ?? null,
+        },
+    };
+}
+export function mapDataset(ds) {
+    const name = typeof ds.name === 'string' ? ds.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'dataset',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            displayName: ds.displayName ?? null,
+            state: ds.state ?? 'STATE_UNSPECIFIED',
+            format: ds.format ?? null,
+            exampleCount: ds.exampleCount ?? null,
+            userUploaded: ds.userUploaded ?? null,
+            createTime: ds.createTime ?? null,
+            updateTime: ds.updateTime ?? null,
+            status: ds.status ?? null,
+        },
+    };
+}
+export function mapBatchInferenceJob(j) {
+    const name = typeof j.name === 'string' ? j.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'batchInferenceJob',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            displayName: j.displayName ?? null,
+            model: j.model ?? null,
+            inputDatasetId: j.inputDatasetId ?? null,
+            outputDatasetId: j.outputDatasetId ?? null,
+            state: j.state ?? 'JOB_STATE_UNSPECIFIED',
+            createTime: j.createTime ?? null,
+            updateTime: j.updateTime ?? null,
+            status: j.status ?? null,
+        },
+    };
+}
+export function mapSupervisedFineTuningJob(j) {
+    const name = typeof j.name === 'string' ? j.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'supervisedFineTuningJob',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            displayName: j.displayName ?? null,
+            baseModel: j.baseModel ?? null,
+            dataset: j.dataset ?? null,
+            state: j.state ?? 'JOB_STATE_UNSPECIFIED',
+            createTime: j.createTime ?? null,
+            updateTime: j.updateTime ?? null,
+            status: j.status ?? null,
+        },
+    };
+}
+export function mapUser(u) {
+    const name = typeof u.name === 'string' ? u.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'user',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            displayName: u.displayName ?? null,
+            email: u.email ?? null,
+            role: u.role ?? null,
+            state: u.state ?? 'STATE_UNSPECIFIED',
+            createTime: u.createTime ?? null,
+            updateTime: u.updateTime ?? null,
+            status: u.status ?? null,
+        },
+    };
+}
+export function mapModel(m) {
+    const name = typeof m.name === 'string' ? m.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'model',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            displayName: m.displayName ?? null,
+            state: m.state ?? 'STATE_UNSPECIFIED',
+            public: m.public ?? null,
+            contextLength: m.contextLength ?? null,
+            createTime: m.createTime ?? null,
+            updateTime: m.updateTime ?? null,
+            status: m.status ?? null,
+        },
+    };
+}
+/** Secrets never carry their value on a list read (the vendor redacts it), so the map stores the
+ *  metadata only — mirroring the vendor's own read surface. */
+export function mapSecret(s) {
+    const name = typeof s.name === 'string' ? s.name : '';
+    // The kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}`) — the same space the
+    // twin's own create path writes — so a pulled row and a created row of one vendor resource are
+    // ONE subject, never two.
+    const id = namespacedId(name);
+    return {
+        type: 'secret',
+        id,
+        fields: {
+            // The vendor's own identity field — the SAME shape the twin's own creates store, so one
+            // collection never has two shapes (round-four review: a pulled row served `vendor_name`
+            // and every official client reading `.name` got undefined).
+            name,
+            // The account the row belongs to (the vendor name's own second segment) — the twin's
+            // reads are account-scoped, so a pulled row must carry the tenancy it was pulled under.
+            _account: name.split('/')[1] ?? null,
+            keyName: s.keyName ?? null,
+            state: s.state ?? 'STATE_UNSPECIFIED',
+            createTime: s.createTime ?? null,
+            updateTime: s.updateTime ?? null,
+            status: s.status ?? null,
+        },
+    };
+}
+/** Which collections a pull enumerates, with their mappers. Paginated with the vendor's own
+ *  `pageToken` cursor so a large account is not truncated at page one. */
+const PULL_COLLECTIONS = [
+    { plural: 'deployments', type: 'deployment', map: mapDeployment },
+    { plural: 'datasets', type: 'dataset', map: mapDataset },
+    { plural: 'batchInferenceJobs', type: 'batchInferenceJob', map: mapBatchInferenceJob },
+    { plural: 'supervisedFineTuningJobs', type: 'supervisedFineTuningJob', map: mapSupervisedFineTuningJob },
+    { plural: 'users', type: 'user', map: mapUser },
+    { plural: 'models', type: 'model', map: mapModel },
+    { plural: 'secrets', type: 'secret', map: mapSecret },
+];
+/** Fetch the account's control-plane state through the injected client and map to SyncResource[]
+ *  (no fold). `accountId` scopes every list; a missing/failed list throws — a REFUSED pull is NOT
+ *  an empty account, and folding an empty list over real observed state would tombstone it. */
+export async function pullFireworksState(execute, accountId) {
+    const resources = [];
+    for (const col of PULL_COLLECTIONS) {
+        let pageToken = null;
+        // An independent page ceiling: pagination terminates on `nextPageToken` becoming null, but a
+        // vendor (or a scenario handler) echoing a token forever must end in a thrown error, not an
+        // endless loop — no single response field can make this loop unbounded.
+        for (let page = 0; page < MAX_PULL_PAGES; page++) {
+            const q = pageToken ? `?pageToken=${encodeURIComponent(pageToken)}&pageSize=200` : '?pageSize=200';
+            const res = await execute('GET', `/v1/accounts/${encodeURIComponent(accountId)}/${col.plural}${q}`);
+            if (res.status < 200 || res.status >= 300) {
+                throw new Error(`fireworks pull ${col.plural} failed: HTTP ${res.status} ${JSON.stringify(res.data).slice(0, 200)}`);
+            }
+            for (const row of envelopeList(res.data, col.plural))
+                resources.push(col.map(row));
+            pageToken = typeof res.data?.nextPageToken === 'string' ? res.data.nextPageToken : null;
+            if (!pageToken)
+                break;
+        }
+        if (pageToken !== null)
+            throw new Error(`fireworks pull ${col.plural} did not terminate after ${MAX_PULL_PAGES} pages — refusing to loop forever on a vendor that keeps returning nextPageToken`);
+    }
+    return resources;
+}
+/** The pagination ceiling above: 10 000 rows at pageSize 200 per collection — far above any real
+ *  account, far below forever. */
+const MAX_PULL_PAGES = 50;
+/** One fold onto the head: protocol 2's observe, one batch, one instant.
+ *
+ * COMPLETENESS IS PER ACCOUNT: the pull observes ONE account, so the tombstone sweep it arms
+ * must reach only that account's rows. The kernel's `complete` is type-level — it tombstones
+ * every subject of the type the batch does not hold — so folding account B's listing with
+ * `complete: ['deployment', …]` erased account A's rows (the sweep never saw them in the
+ * batch). The pack therefore expresses completeness itself, the way the kernel's explicit
+ * tombstones allow: every row the projection holds for THIS account's collections that the
+ * listing did not name is observed as `{deleted: true}` in the same batch, and NO type-level
+ * `complete` is armed. A foreign account's rows are invisible to the sweep by construction,
+ * and a vanished resource still gets its tombstone. */
+function fold(resources, opts) {
+    const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+    const observed = resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields }));
+    const seen = new Set(observed.map((r) => `${r.type}:${r.id}`));
+    for (const row of projectResources(SERVICE, opts.root)) {
+        if (!PULL_TYPES.has(row.type))
+            continue;
+        if (row._account !== opts.accountId)
+            continue; // another account's row — never this sweep's
+        if (seen.has(`${row.type}:${row.id}`))
+            continue;
+        if (row.deleted === true)
+            continue; // already tombstoned
+        observed.push({ type: row.type, id: row.id, fields: { deleted: true } });
+    }
+    return observeResources(SERVICE, observed, {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:fireworks:${at}`,
+    });
+}
+/** The collection types a pull enumerates — the ones completeness is expressed over. */
+const PULL_TYPES = new Set(PULL_COLLECTIONS.map((c) => c.type));
+/**
+ * D7 consumer-facing pull entry point: gather all Fireworks control-plane read domains and fold
+ * them into the twin through a SINGLE observed batch, returning the standard result shape.
+ * Idempotent: a re-pull of identical state appends no new deltas.
+ */
+export async function syncFireworksFromReal(execute, opts = { accountId: '' }) {
+    const resources = await pullFireworksState(execute, opts.accountId);
+    const result = fold(resources, opts);
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+// ── PUSH: twin → real ───────────────────────────────────────────────────────────────────────
+/**
+ * The gateway create ids are QUERY params (deployments: deploymentId, users: userId) or body
+ * fields (datasets), per the vendor's own spec — not path segments. A body field is carried
+ * through the body; a query param is appended here.
+ */
+function createQueryString(type, id) {
+    if (type === 'deployment' || type === 'user' || type === 'batchInferenceJob' || type === 'supervisedFineTuningJob') {
+        return `?${type}Id=${encodeURIComponent(id)}`;
+    }
+    return '';
+}
+/** Map a subject type → its Gateway REST collection segment. */
+const COLLECTION_SEGMENT = {
+    deployment: 'deployments',
+    dataset: 'datasets',
+    batchInferenceJob: 'batchInferenceJobs',
+    supervisedFineTuningJob: 'supervisedFineTuningJobs',
+    user: 'users',
+    model: 'models',
+    secret: 'secrets',
+};
+/** The twin's LOCALLY-MINTED id namespace (see `nextId` in fireworks-twin.ts). A subject still
+ *  bearing one has no counterpart in the real account. The `_twin_` infix is anchored so a PULLED
+ *  vendor id can never match. */
+const LOCAL_ID = /_twin_\d+$/;
+/** The BARE id a vendor path segment carries: kernel subjects are account-namespaced
+ *  (`{account}/{id}` — see `namespacedId`), and the Gateway REST path addresses the resource by
+ *  the id segment alone. A bare id (a connector-verify action written directly) passes through. */
+function bareId(subjectId) {
+    return subjectId.includes('/') ? subjectId.slice(subjectId.indexOf('/') + 1) : subjectId;
+}
+/** Why this operation cannot be pushed to the real vendor, or null if it can. Pure — no vendor
+ *  call on its path. Inference operations are the big class: replaying a completion at the vendor
+ *  spends real money and stores nothing, so a push of one is a category error, not a gap. */
+export function unpushableReason(op) {
+    if (op.startsWith('response.') || op === 'chat.completion' || op === 'completion') {
+        return 'inference is generative and stores nothing — replaying it at the vendor would spend real money for no stored state; the twin records it locally only';
+    }
+    if (op.endsWith('.cancel') || op.endsWith('.resume') || op.endsWith('.undelete') || op.endsWith('.scale')) {
+        return `the custom verb '${op.slice(op.indexOf('.') + 1)}' has no push mapping in this pack — the twin models it for wire fidelity, the connector replays only create/delete`;
+    }
+    return null;
+}
+/**
+ * The REST (method, path, body) that CONFIRMS one local action against the real Gateway REST
+ * surface. Create ids go where the vendor's spec puts them (query params for deployments/users,
+ * the body for the rest). A locally-minted id on anything but a create is REFUSED — the twin's
+ * own mint is not an address the vendor knows.
+ */
+export function fireworksRequestForAction(action, accountId, opts = {}) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    const segment = COLLECTION_SEGMENT[action.subject.type];
+    if (!segment)
+        throw new Error(`fireworks push: no REST collection for subject type '${action.subject.type}'`);
+    const fields = (action.fields ?? {});
+    if (verb === 'create') {
+        const id = bareId(action.subject.id);
+        const path = `/v1/accounts/${encodeURIComponent(accountId)}/${segment}${createQueryString(action.subject.type, id)}`;
+        // The body IS the resource for deployments, jobs, users and secrets (the vendor's spec takes
+        // the resource directly); datasets and models wrap ({dataset, datasetId} / {model, modelId}).
+        if (action.subject.type === 'dataset')
+            return { method: 'POST', path, body: { dataset: fields, datasetId: id } };
+        if (action.subject.type === 'model')
+            return { method: 'POST', path, body: { model: fields, modelId: id } };
+        return { method: 'POST', path, body: fields };
+    }
+    if (verb === 'delete') {
+        const localId = bareId(action.subject.id);
+        const vendorId = !LOCAL_ID.test(localId) ? localId
+            : opts.externalId ?? null;
+        if (vendorId === null) {
+            throw new Error(`fireworks push: refusing to address the real account by the twin's own id '${localId}' — no vendor id was ever recorded for this subject`);
+        }
+        return { method: 'DELETE', path: `/v1/accounts/${encodeURIComponent(accountId)}/${segment}/${encodeURIComponent(vendorId)}` };
+    }
+    throw new Error(`fireworks push: unsupported operation '${op}' — refusing to silently drop a local write`);
+}
+/**
+ * Push ONE pending action to REAL Fireworks via the injected executor. Returns the real external
+ * id (the vendor's own id from the create response's `name`, or the addressed id on delete).
+ * WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushFireworksAction(execute, action, accountId, opts = {}) {
+    const req = fireworksRequestForAction(action, accountId, opts);
+    const res = await execute(req.method, req.path, req.body);
+    if (res.status < 200 || res.status >= 300) {
+        throw new Error(`fireworks push ${action.operation} refused: HTTP ${res.status} ${JSON.stringify(res.data).slice(0, 200)}`);
+    }
+    const data = res.data;
+    // The vendor's create response carries the resource with its `name`
+    // (accounts/{account}/<plural>/<id>); the id segment is the external id. A create response
+    // without one is REFUSED, never guessed: falling back to the twin's own mint would record a
+    // vendor address the vendor never issued. (A delete answers `{}` — its external id is the
+    // address it just acted on.)
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    const name = typeof data?.name === 'string' ? data.name : '';
+    const externalId = name.split('/').pop() || opts.externalId;
+    if (verb === 'create' && !externalId) {
+        throw new Error(`fireworks push ${op}: the vendor response named no resource — refusing to record the twin's own id '${action.subject.id}' as the external id`);
+    }
+    return { externalId: externalId || action.subject.id };
+}
+/**
+ * Push the twin's PENDING local actions to real Fireworks and CONFIRM each. Idempotent: a
+ * confirmed action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * An action this connector cannot faithfully push is SKIPPED AND REPORTED, never confirmed and
+ * never silently dropped: it stays pending and is named in `refused`. A create's real id is
+ * recorded on the resource as `_external_id` at confirm time, so a later delete addresses the
+ * VENDOR by it — never the twin's own mint.
+ */
+export async function pushPendingFireworksActions(execute, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    const refused = [];
+    const at = opts.occurredAt ?? new Date().toISOString();
+    for (const action of deployableEntries(SERVICE, opts.root)) {
+        const op = action.operation ?? `${action.subject.type}.update`;
+        const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+        if (verb !== 'create' && verb !== 'delete') {
+            refused.push({ actionId: action.id, operation: op, reason: unpushableReason(op) ?? `unsupported operation '${op}'` });
+            continue;
+        }
+        const why = unpushableReason(op);
+        if (why) {
+            refused.push({ actionId: action.id, operation: op, reason: why });
+            continue;
+        }
+        // Anything but a create must address the vendor by the id the vendor issued. A locally-minted
+        // subject with none recorded is REFUSED, never guessed.
+        let external;
+        if (verb !== 'create' && LOCAL_ID.test(bareId(action.subject.id))) {
+            const row = projectResources(SERVICE, opts.root).find((r) => r.type === action.subject.type && r.id === action.subject.id);
+            const ext = row?._external_id;
+            if (typeof ext !== 'string' || !ext) {
+                refused.push({ actionId: action.id, operation: op, reason: `no vendor id recorded for ${action.subject.type} '${action.subject.id}' — it was never pushed to the real account, so there is nothing there to ${verb}` });
+                continue;
+            }
+            external = ext;
+        }
+        let externalId;
+        try {
+            ({ externalId } = await pushFireworksAction(execute, action, opts.accountId, ...(external !== undefined ? [{ externalId: external }] : [])));
+        }
+        catch (err) {
+            // A push that cannot be confirmed faithfully (a vendor response that names no resource, a
+            // locally-minted delete address) is REPORTED and left pending — the sweep continues.
+            refused.push({ actionId: action.id, operation: op, reason: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        // Record the id the vendor issued ON the resource, so a later delete can address it.
+        confirmAction({
+            service: SERVICE, actionId: action.id, subject: action.subject,
+            fields: { ...(action.fields ?? {}), ...(verb === 'create' ? { _external_id: externalId } : {}) },
+            occurredAt: at, ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        confirmed.push(action.id);
+        externalIds[action.id] = externalId;
+    }
+    return { pushed: confirmed.length, confirmed, externalIds, refused };
+}
+// ── FULL bi-directional sync ────────────────────────────────────────────────────────────────
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to real
+ * Fireworks and confirm it, then (2) PULL the control-plane collections back and fold them into
+ * the event log. Pushing first means the pull observes the twin's own writes as confirmed external
+ * state (no double-count). Re-running with no pending writes and identical real state is a no-op.
+ */
+export async function fullSyncFireworks(execute, opts) {
+    const push = await pushPendingFireworksActions(execute, opts);
+    const resources = await pullFireworksState(execute, opts.accountId);
+    const pull = fold(resources, opts);
+    return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.appended, collections: PULL_COLLECTIONS.length, refused: push.refused };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The one HTTP call every adapter below makes, over the kernel's executor. At a REAL boundary the
+ *  kernel sets the sealed credential over these headers (executor.ts); at the twin's own wire any
+ *  credential is one. */
+function fireworksSend(execute) {
+    return async (method, path, body) => {
+        const res = await execute({
+            method, path,
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer fireworks_twin_bootstrap_token' },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        let parsed = {};
+        try {
+            parsed = JSON.parse(res.body || '{}');
+        }
+        catch {
+            parsed = {};
+        }
+        return { status: res.status, data: parsed };
+    };
+}
+/** A `FireworksExecute` over the kernel's executor — the adapter seam protocol 2 fixes. */
+export function fireworksExecuteOver(execute) {
+    return fireworksSend(execute);
+}
+/** The refresh adapter: pull the account's control-plane collections. `origin` is unused —
+ *  Fireworks' surface is single-host, so the executor's own base URL is the address. */
+export async function syncFireworksFromRemote(execute, opts = {}) {
+    return syncFireworksFromReal(fireworksExecuteOver(execute), {
+        accountId: opts.accountId ?? FIREWORKS_ACCOUNT_ID,
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}),
+    });
+}
+/**
+ * The perform adapter — the head's executor for a local write at a REAL boundary. Create/delete
+ * replay against the Gateway REST surface through `ctx.resolve` (a locally minted subject is
+ * addressed by the vendor id the projection recorded, never by the mint). Inference operations and
+ * custom verbs are NOT performed: they are the twin's own record, and the outcome says so.
+ */
+export async function performFireworksAction(execute, action, ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (verb !== 'create' && verb !== 'delete') {
+        return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — ${unpushableReason(op) ?? 'the connector does not replay it'}` } };
+    }
+    // The account rides ON THE SUBJECT: kernel subject ids are account-namespaced
+    // (`{account}/{id}` — the same grammar the create/pull paths write), so the perform path
+    // derives the Gateway account from the subject's own namespace. Hardcoding the pack constant
+    // here made a perform of any OTHER account's subject address /v1/accounts/my-account/… — the
+    // wrong tenant's REST surface. A bare subject id (a connector-verify action written directly)
+    // falls back to the pack's default account.
+    const accountId = action.subject.id.includes('/') ? action.subject.id.slice(0, action.subject.id.indexOf('/')) : FIREWORKS_ACCOUNT_ID;
+    const row = projectResources(SERVICE, ctx.root).find((r) => r.type === action.subject.type && r.id === action.subject.id);
+    const recordedExternal = typeof row?._external_id === 'string' ? row._external_id : undefined;
+    const bare = bareId(action.subject.id);
+    const vendorId = verb === 'create'
+        ? bare
+        : (!LOCAL_ID.test(bare) ? bare : recordedExternal ?? null);
+    if (vendorId === null) {
+        throw new Error(`fireworks perform ${op} refused: the subject '${action.subject.id}' was never pushed, so the vendor holds no row to ${verb}`);
+    }
+    const req = fireworksRequestForAction(action, accountId, ...(vendorId !== action.subject.id ? [{ externalId: vendorId }] : []));
+    const res = await fireworksExecuteOver(execute)(req.method, req.path, req.body);
+    if (res.status < 200 || res.status >= 300) {
+        throw new Error(`fireworks perform ${op} refused: HTTP ${res.status} ${JSON.stringify(res.data).slice(0, 200)}`);
+    }
+    const data = res.data;
+    const name = typeof data?.name === 'string' ? data.name : '';
+    const externalId = name.split('/').pop() || vendorId;
+    return { externalId, data: (data ?? {}) };
+}
+// The ledger path is re-exported so an operator can find the spend file without importing the
+// budget module separately.
+export { fireworksBudgetPath };

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

@@ -0,0 +1,11 @@
+/** One catalog row: the id the inference plane accepts. */
+export type FireworksCatalogModel = {
+    id: string;
+    /** Which inference endpoint families accept it. */
+    kind: 'chat' | 'embeddings' | 'rerank';
+};
+export declare const FIREWORKS_MODELS: FireworksCatalogModel[];
+/** The static ids, for the refusal check. */
+export declare const FIREWORKS_MODEL_IDS: Set<string>;
+/** Which endpoint family a static model id belongs to (undefined = not a chat id). */
+export declare function catalogKind(id: string): FireworksCatalogModel['kind'] | undefined;