@volter/twin-fireworks 0.1.0

package/src/fireworks-connector.ts

@@ -0,0 +1,700 @@
+// 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 type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { FireworksBudget, FireworksBudgetError, fireworksBudgetPath, fireworksCallWeight, type FireworksBudgetOptions } from './fireworks-budget.ts';
+
+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';
+
+/**
+ * The injected real-Fireworks boundary. `request` issues ONE Fireworks REST call against either
+ * plane:
+ *   method — 'GET' | 'POST' | 'PATCH' | 'DELETE'
+ *   path   — e.g. '/inference/v1/chat/completions' or
+ *            '/v1/accounts/{account_id}/deployments?deploymentId=my-deployment'
+ *   body   — JSON body for POST/PATCH (omitted otherwise)
+ * Returns the parsed JSON envelope (an OpenAI-compat completion, a gateway list envelope, or an
+ * error shape).
+ */
+export type FireworksExecute = (
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<{ status: number; data: unknown }>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveFireworksOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: FireworksBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: FireworksBudgetOptions;
+};
+
+/**
+ * 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: string,
+  base = 'https://api.fireworks.ai',
+  opts: LiveFireworksOptions = {},
+): FireworksExecute {
+  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: Record<string, string> = { authorization: `Bearer ${apiKey}`, accept: 'application/json' };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { 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: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    let data: unknown = {};
+    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: unknown, plural: string): Array<Record<string, unknown>> {
+  if (data === null || typeof data !== 'object') return [];
+  const items = (data as Record<string, unknown>)[plural];
+  return Array.isArray(items) ? (items as Array<Record<string, unknown>>) : [];
+}
+
+/** 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: string): string {
+  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: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? null,
+    },
+  };
+}
+
+export function mapDataset(ds: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? null,
+    },
+  };
+}
+
+export function mapBatchInferenceJob(j: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? null,
+    },
+  };
+}
+
+export function mapSupervisedFineTuningJob(j: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? null,
+    },
+  };
+}
+
+export function mapUser(u: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? null,
+    },
+  };
+}
+
+export function mapModel(m: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? 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: Record<string, unknown>): SyncResource {
+  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 as { code?: string; message?: string } | null | undefined) ?? 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: Array<{ plural: string; type: string; map: (r: Record<string, unknown>) => SyncResource }> = [
+  { 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: FireworksExecute, accountId: string): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  for (const col of PULL_COLLECTIONS) {
+    let pageToken: string | null = 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 as Record<string, unknown> | null)?.nextPageToken === 'string' ? ((res.data as Record<string, unknown>).nextPageToken as string) : 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: SyncResource[], opts: { accountId: string; root?: string; occurredAt?: string }) {
+  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: FireworksExecute,
+  opts: { accountId: string; root?: string; occurredAt?: string } = { accountId: '' },
+): Promise<{ observed: number; deltasAppended: number }> {
+  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: string, id: string): string {
+  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: Record<string, string> = {
+  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: string): string {
+  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: string): string | null {
+  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: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+  accountId: string,
+  opts: { externalId?: string } = {},
+): { method: 'POST' | 'DELETE'; path: string; body?: Record<string, unknown> } {
+  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 ?? {}) as Record<string, unknown>;
+  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: FireworksExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+  accountId: string,
+  opts: { externalId?: string } = {},
+): Promise<{ externalId: string }> {
+  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 as Record<string, unknown> | null;
+  // 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: FireworksExecute,
+  opts: { accountId: string; root?: string; occurredAt?: string },
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string>; refused: Array<{ actionId: string; operation: string; reason: string }> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  const refused: Array<{ actionId: string; operation: string; reason: string }> = [];
+  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: string | undefined;
+    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: string;
+    try {
+      ({ externalId } = await pushFireworksAction(execute, action, opts.accountId, ...(external !== undefined ? [{ externalId: external }] as const : [] as const)));
+    } 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: FireworksExecute,
+  opts: { accountId: string; root?: string; occurredAt?: string },
+): Promise<{ pushed: number; observed: number; deltasAppended: number; collections: number; refused: Array<{ actionId: string; operation: string; reason: string }> }> {
+  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: RemoteExecute): FireworksExecute {
+  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: unknown = {};
+    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: RemoteExecute): FireworksExecute {
+  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: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string; accountId?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  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: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  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 }] as const : [] as const));
+  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 as Record<string, unknown> | null;
+  const name = typeof data?.name === 'string' ? data.name : '';
+  const externalId = name.split('/').pop() || vendorId;
+  return { externalId, data: (data ?? {}) as Record<string, unknown> };
+}
+
+// The ledger path is re-exported so an operator can find the spend file without importing the
+// budget module separately.
+export { fireworksBudgetPath };