@volter/twin-cohere 0.1.0

package/src/cohere-connector.ts

@@ -0,0 +1,709 @@
+// Cohere CONNECTOR — the live-vendor pull/push path that gives the Cohere twin the full
+// "git for SaaS" lifecycle (pull real state → mirror; push local writes → real).
+//
+// PULL  (real → twin):  fetch real Datasets / Connectors / Embed jobs, map the vendor JSON →
+//                       SyncResource[], fold into the event log via syncPull (shadow-diff dedup,
+//                       so re-pulling identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action (create / update / cancel / delete), call
+//                       the real Cohere REST API and confirmAction on success (records the
+//                       confirmed fields as an observed event + suppresses the local projection —
+//                       counted exactly once).
+//
+// The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO Cohere
+// key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
+// `liveCohereExecute(apiKey)`. Same code path either way — fully exercisable offline.
+import { assertBudgetGuardIntact, confirmAction, pendingActions, projectResources, syncPull } from '@volter/world-core';
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { CohereBudget, CohereBudgetError, cohereCallWeight, type CohereBudgetOptions } from './cohere-budget.ts';
+
+const SERVICE = 'cohere';
+
+/** The real Cohere API base — `CohereEnvironment.Production` in cohere-ai@8.1.0's
+ *  `environments.d.ts`, which is the ONLY host either SDK ships. */
+export const COHERE_API_BASE = 'https://api.cohere.com';
+
+/**
+ * The injected real-Cohere boundary. `request` issues ONE Cohere REST call:
+ *   method  — 'GET' | 'POST' | 'PATCH' | 'DELETE'
+ *   path    — e.g. '/v1/datasets' or '/v1/embed-jobs/<id>/cancel'
+ *   body    — JSON body for POST/PATCH (omitted otherwise)
+ * Returns the parsed JSON: one of Cohere's per-collection list envelopes, a single object, or its
+ * `{ message }` error envelope.
+ */
+export type CohereExecute = (
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<unknown>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveCohereOptions = {
+  /** 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?: CohereBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: CohereBudgetOptions;
+};
+
+/**
+ * A live executor against the real Cohere REST API (the user's own API key). Sends
+ * `Authorization: Bearer <key>` — the scheme BOTH SDKs use (cohere-ai's `BearerAuthProvider`,
+ * which falls back to the `CO_API_KEY` env var, and @ai-sdk/cohere's provider, which reads
+ * `COHERE_API_KEY`). Never imported by the pack's own serving path — only constructed by a caller
+ * that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live api.cohere.com request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `CohereBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `retry-after` / 429 signal becomes a persisted cooldown that makes every later call fail fast
+ * WITHOUT touching Cohere. 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 `cohere-budget.ts` and the kernel's `rateBudget.ts`
+ * header for the limits of the guarantee.
+ */
+export function liveCohereExecute(
+  apiKey: string,
+  base = COHERE_API_BASE,
+  opts: LiveCohereOptions = {},
+): CohereExecute {
+  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 CohereBudget — 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.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, CohereBudget, 'liveCohereExecute')
+    : new CohereBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    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 = cohereCallWeight(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; });
+    // READ AS TEXT, then parse only if there is something to parse. `res.json()` throws a
+    // SyntaxError on an empty body — and the vendor HAS body-less responses (`embedJobs.cancel`
+    // is declared `-> void`). That throw would land BEFORE `recordCall`, leaving the budget
+    // reservation unsettled and dropping a `retry-after` on that very response on the floor.
+    // Settlement must not depend on the body parsing.
+    const text = await res.text();
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // `retry-after` beyond the cap is not something to sleep off) — the cooldown is persisted
+    // first either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Cohere 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 CohereBudgetError) || !res.ok) throw error;
+    }
+    if (text.trim() === '') return {};
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new Error(`cohere: ${method} ${path} answered ${res.status} with a body that is not JSON: ${text.slice(0, 200)}`);
+    }
+  };
+}
+
+/**
+ * A REFUSED pull is NOT an empty account. Cohere answers a failure with its BARE `{ message }`
+ * envelope; mapping that to "no resources" would fold an empty account OVER real observed state
+ * and silently delete the mirror. Throw instead.
+ *
+ * Note the envelope is what identifies a refusal, not the HTTP status — the executor has already
+ * consumed the status, and a caller supplying its own executor may not preserve it at all.
+ */
+function throwIfError(res: unknown, ctx: string): void {
+  const e = res as { message?: unknown } | null;
+  if (e && typeof e === 'object' && typeof e.message === 'string') {
+    throw new Error(`cohere ${ctx} failed: ${e.message}`);
+  }
+}
+
+/**
+ * Read one collection out of Cohere's per-collection list envelope.
+ *
+ * Cohere does NOT use a uniform `{ data: [...] }` wrapper: datasets answer `{ datasets }`,
+ * connectors `{ connectors, total_count }`, embed jobs `{ embed_jobs }`. Reading a shape the
+ * collection does not use would silently yield zero rows — which `syncPull` would then fold as an
+ * emptied account.
+ *
+ * The key must be PRESENT. Cohere's own schemas make each list key optional-and-nullable, so an
+ * explicit `null` genuinely means "no rows" and is accepted; a response with the key MISSING
+ * ENTIRELY is not an empty account, it is a response this connector does not understand, and it
+ * throws rather than reporting zero.
+ */
+function listOf(res: unknown, key: string, nullable: boolean, ctx: string): Array<Record<string, unknown>> {
+  if (!res || typeof res !== 'object' || Array.isArray(res)) {
+    throw new Error(`cohere ${ctx} failed: expected an object carrying "${key}", got ${JSON.stringify(res).slice(0, 120)}`);
+  }
+  if (!Object.hasOwn(res as object, key)) {
+    throw new Error(`cohere ${ctx} failed: the response has no "${key}" key — an unrecognized envelope is not an empty account`);
+  }
+  const v = (res as Record<string, unknown>)[key];
+  if (v === null || v === undefined) {
+    // NULLABILITY IS PER COLLECTION, read from the vendor's own schemas — not assumed uniform.
+    // `DatasetsListResponse.datasets` and `ListEmbedJobResponse.embed_jobs` are declared
+    // `?: Raw[] | null`, so an explicit null genuinely means "no rows". `ListConnectorsResponse`
+    // declares `connectors: Connector.Raw[]` REQUIRED and NON-nullable, so a null there is a
+    // response the vendor says cannot occur — accepting it as an empty account would fold an empty
+    // list over real observed connector state, which is the exact hazard this module exists to
+    // close (§9 round 1, connector m1: an earlier version waved all three through on a premise
+    // that was false for one of them).
+    if (nullable) return [];
+    throw new Error(`cohere ${ctx} failed: "${key}" is null, but the vendor declares it required and non-nullable — an unexpected null is not an empty account`);
+  }
+  if (!Array.isArray(v)) throw new Error(`cohere ${ctx} failed: "${key}" is not a list`);
+  return v as Array<Record<string, unknown>>;
+}
+
+// ── PULL ────────────────────────────────────────────────────────────────────
+
+/** Map a real-Cohere Dataset → a twin sync resource. Every field the vendor's `Dataset` schema
+ *  declares REQUIRED (`id`, `name`, `created_at`, `updated_at`, `dataset_type`,
+ *  `validation_status`) is carried; a pulled row that lost one would be unparseable by the
+ *  official SDK the moment the twin served it back. */
+export function mapDataset(d: Record<string, unknown>): SyncResource {
+  return {
+    type: 'dataset',
+    id: String(d.id),
+    fields: {
+      name: (d.name as string) ?? null,
+      created_at: (d.created_at as string) ?? null,
+      updated_at: (d.updated_at as string) ?? (d.created_at as string) ?? null,
+      dataset_type: (d.dataset_type as string) ?? null,
+      validation_status: (d.validation_status as string) ?? null,
+      validation_error: (d.validation_error as string) ?? null,
+      validation_warnings: (d.validation_warnings as string[]) ?? [],
+      required_fields: (d.required_fields as string[]) ?? [],
+      preserve_fields: (d.preserve_fields as string[]) ?? [],
+      dataset_parts: (d.dataset_parts as unknown[]) ?? [],
+    },
+  };
+}
+
+/** Map a real-Cohere Connector → a twin sync resource. */
+export function mapConnector(c: Record<string, unknown>): SyncResource {
+  return {
+    type: 'connector',
+    id: String(c.id),
+    fields: {
+      organization_id: (c.organization_id as string) ?? null,
+      name: (c.name as string) ?? null,
+      description: (c.description as string) ?? null,
+      url: (c.url as string) ?? null,
+      created_at: (c.created_at as string) ?? null,
+      updated_at: (c.updated_at as string) ?? (c.created_at as string) ?? null,
+      excludes: (c.excludes as string[]) ?? [],
+      auth_type: (c.auth_type as string) ?? null,
+      oauth: (c.oauth as Record<string, unknown>) ?? null,
+      auth_status: (c.auth_status as string) ?? null,
+      active: c.active === undefined ? true : c.active === true,
+      continue_on_failure: c.continue_on_failure === true,
+    },
+  };
+}
+
+/**
+ * Map a real-Cohere EmbedJob → a twin sync resource.
+ *
+ * The vendor's key for an embed job is `job_id`, NOT `id` — there is no `id` on the schema at all.
+ * Subjecting the resource under `d.id` would make every pulled job land under the string
+ * "undefined" and collapse the whole collection onto one row.
+ */
+export function mapEmbedJob(j: Record<string, unknown>): SyncResource {
+  return {
+    type: 'embed_job',
+    id: String(j.job_id),
+    fields: {
+      job_id: String(j.job_id),
+      name: (j.name as string) ?? null,
+      status: (j.status as string) ?? null,
+      created_at: (j.created_at as string) ?? null,
+      input_dataset_id: (j.input_dataset_id as string) ?? null,
+      output_dataset_id: (j.output_dataset_id as string) ?? null,
+      model: (j.model as string) ?? null,
+      truncate: (j.truncate as string) ?? null,
+    },
+  };
+}
+
+/** `nullable` mirrors each list key's own declaration in cohere-ai@8.1.0's serializers:
+ *  `DatasetsListResponse.datasets?: Raw[] | null`, `ListEmbedJobResponse.embed_jobs?: Raw[] | null`,
+ *  but `ListConnectorsResponse.connectors: Connector.Raw[]` — required and non-nullable. */
+const COLLECTIONS: Array<{ path: string; key: string; nullable: boolean; map: (r: Record<string, unknown>) => SyncResource }> = [
+  { path: '/v1/datasets', key: 'datasets', nullable: true, map: mapDataset },
+  { path: '/v1/connectors', key: 'connectors', nullable: false, map: mapConnector },
+  { path: '/v1/embed-jobs', key: 'embed_jobs', nullable: true, map: mapEmbedJob },
+];
+
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export async function pullCohereState(execute: CohereExecute): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  for (const c of COLLECTIONS) {
+    const res = await execute('GET', c.path);
+    throwIfError(res, `pull ${c.path}`);
+    for (const item of listOf(res, c.key, c.nullable, `pull ${c.path}`)) out.push(c.map(item));
+  }
+  return out;
+}
+
+/**
+ * A MOVING poll timestamp, forced strictly increasing within the process. NOT a pinned constant:
+ * the kernel hashes an observed event over (`occurredAt` + post-state), so under a fixed poll time
+ * a vendor value that REVERTS (a connector toggled active→inactive→active across polls) collides
+ * with its own earlier observation and `syncPull` reports `deltasAppended: 1` while nothing lands
+ * — a phantom delta, with the projection still serving the stale value.
+ */
+let lastPoll = 0;
+export function pollTimestamp(): string {
+  const now = Math.max(Date.now(), lastPoll + 1);
+  lastPoll = now;
+  return new Date(now).toISOString();
+}
+
+/**
+ * Pull from real Cohere and fold into the twin (mirror seeding). syncPull's shadow-diff makes a
+ * re-pull of identical state a no-op.
+ */
+export async function syncCohereFromReal(
+  execute: CohereExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources = await pullCohereState(execute);
+  const result = syncPull({
+    service: SERVICE,
+    resources,
+    occurredAt: opts.occurredAt ?? pollTimestamp(),
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+  });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}
+
+// ── PUSH ────────────────────────────────────────────────────────────────────
+
+/** The twin operations this connector knows how to push. Anything not here must FAIL LOUDLY
+ *  rather than be silently dropped — pushing an unrecognized op risks hitting the wrong endpoint
+ *  or no-op'ing a real change. */
+const PUSHABLE_VERBS = new Set(['create', 'update', 'cancel', 'delete']);
+
+/**
+ * Subject types NO verb of which can be pushed, keyed by TYPE rather than by operation.
+ *
+ * A type-wide rule is the only shape that cannot be out-flanked by a verb nobody thought of: an
+ * op-keyed list covering `token.observe` would let a hypothetical `token.delete` through, and the
+ * request builder's `/v1/${type}s` fallback would then fire `DELETE /v1/tokens/<id>` — an endpoint
+ * Cohere does not have — at a REAL account.
+ */
+const UNPUSHABLE_TYPES: Record<string, string> = {
+  token: "the tokenizer vocabulary is twin-local state with no vendor endpoint in either direction — Cohere's tokenizer is fixed server-side, so there is nothing to push and nothing to pull",
+};
+
+/**
+ * Individual operations whose verb and type are otherwise pushable, but whose vendor request this
+ * connector cannot faithfully reproduce from stored state. Refusing them by name is the honest
+ * answer; pushing an approximation would write the wrong thing to a real account, which is worse
+ * than not pushing at all. Each is filed as a todo in the manifest.
+ */
+const UNPUSHABLE_OPS: Record<string, string> = {
+  'dataset.create': "the vendor's dataset create is a multipart/form-data upload whose `data` part is the dataset FILE, and whose name/type travel as query parameters — not the JSON body this executor sends, and the twin does not retain the original bytes; see cohere.connector.push_dataset_multipart",
+};
+
+/**
+ * Why this op is a KNOWN, filed, un-pushable gap — or undefined if the connector can push it.
+ *
+ * This answers only for gaps that have been REASONED ABOUT. An operation the connector has simply
+ * never heard of is NOT this function's business: it is a coding gap, and `assertPushable` throws
+ * on it, loudly. Routing every unknown verb through the skip-and-count path would turn a genuine
+ * unhandled write into an anonymous integer that ticks up and tells nobody.
+ */
+export function unpushableReason(op: string, subjectType?: string): string | undefined {
+  if (subjectType !== undefined && UNPUSHABLE_TYPES[subjectType] !== undefined) return UNPUSHABLE_TYPES[subjectType];
+  return UNPUSHABLE_OPS[op];
+}
+
+/**
+ * Does this subject have a VENDOR identity, or only a twin-minted one?
+ *
+ * THE BUG THIS CLOSES (§9 round 1, connector B1 + M1 — one BLOCKER and one MAJOR, both the same
+ * root class). The twin mints UUID-SHAPED ids, so a twin id is indistinguishable from a real
+ * Cohere id in an operator's logs. Two ordinary sequences fired one at the REAL account:
+ *
+ *   B1  create a connector, PATCH it, push. The create confirms under the vendor's id, but the
+ *       QUEUED update still carries the twin-minted id, so `PATCH /v1/connectors/<twin-uuid>` went
+ *       out. Real Cohere 404s, `throwIfError` aborts the batch mid-run, and the update stays
+ *       PENDING — so every later push re-issues the same doomed request forever.
+ *   M1  create a dataset, delete it, push. `dataset.create` is a FILED multipart gap, so it is
+ *       skipped — and skipping it is exactly what made the delete reachable:
+ *       `DELETE /v1/datasets/<twin-uuid>` went out. Aborting at the refused create would have
+ *       stopped the run; the skip is what let it through. That is the "trace what a fix makes
+ *       newly REACHABLE" class, and the fix's own reasoning had it backwards.
+ *
+ * The discriminator is the `_twin_minted` marker the handler stamps on every local create. A row
+ * that arrived through `syncPull` carries no marker and IS known to the vendor under its own id, so
+ * a mutation on it pushes normally — that path must keep working, which is why "does a local create
+ * action exist" is the question rather than "does the id look local".
+ */
+type Identity =
+  | { kind: 'vendor' }                       // the vendor knows this id; push it as-is
+  | { kind: 'superseded'; externalId: string } // the vendor knows it under a DIFFERENT id
+  | { kind: 'local' };                       // the vendor has never seen it
+
+/**
+ * What identity does this subject have AT THE VENDOR? Read from the durable projection, so the
+ * answer survives a restart, an aborted batch and a fresh process.
+ *
+ * §9 ROUND TWO, BLOCKER. Round one fixed B1 with an in-loop `Map` and M1 with a `_twin_minted`
+ * marker — and the two fixes DESTROYED each other on the same state. `confirmAction` suppresses the
+ * confirmed create's whole projection, and the supersede tombstone it writes carries only
+ * `{_deleted, _superseded_by}` — so `_twin_minted`, which lived on the now-suppressed create,
+ * VANISHES. The local id then looked vendor-known, and the per-batch map was the only thing left
+ * holding the line:
+ *
+ *     create + PATCH queued → push #1 confirms the create, then the PATCH throws (a budget refusal
+ *     mid-batch, a retry-after past the cap, a network error, any vendor `{message}`) → batch
+ *     aborts, the PATCH stays pending → push #2 has an EMPTY map and a marker-less tombstone
+ *     → `PATCH /v1/connectors/<twin-uuid>` at the REAL account, every run, forever.
+ *
+ * That is byte-for-byte the outcome B1 claimed to close, and neither the capability written to
+ * prove B1 nor its revert-matrix cell could see it — both are single-batch by construction.
+ *
+ * The tombstone the confirm already writes IS the durable mapping; reading it is what makes the
+ * resolution survive the batch. `mintedExternal` is now only a within-run cache for rows confirmed
+ * moments ago, whose tombstone this same call would find anyway.
+ */
+function vendorIdentity(subjectType: string, subjectId: string, root?: string): Identity {
+  const row = projectResources(SERVICE, root).find((r) => r.type === subjectType && r.id === subjectId);
+  // No row at all: nothing local ever claimed this id, so it can only have come from the vendor.
+  if (row === undefined) return { kind: 'vendor' };
+  // A supersede tombstone records exactly which vendor id this local id became.
+  if (typeof row._superseded_by === 'string' && row._superseded_by) return { kind: 'superseded', externalId: row._superseded_by };
+  if (row._twin_minted === true) return { kind: 'local' };
+  return { kind: 'vendor' };
+}
+
+/** Fields to CONFIRM with — the twin's own bookkeeping removed. `_twin_minted` must not ride along
+ *  to the vendor-id row: that row IS vendor-known, and leaving the marker on it would make every
+ *  later mutation of a converged resource refuse itself. */
+function confirmFields(fields: Record<string, unknown> | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...(fields ?? {}) };
+  delete out._twin_minted;
+  return out;
+}
+
+
+/**
+ * Resolve every id a payload REFERENCES, by the same rule the subject gets.
+ *
+ * The only foreign key this twin pushes is an embed job's `input_dataset_id`. It matters because
+ * `dataset.create` is an un-pushable filed gap, so a locally created dataset is PERMANENTLY
+ * vendor-unknown — and the embed-job create would then have posted
+ * `{"dataset_id": "<twin-uuid>"}` to the real account (§9 round two, MAJOR). Worse, the capability
+ * written to pin the read-shape→write-shape rename ASSERTED that it did.
+ */
+function resolveForeignKeys<A extends Pick<TwinAction, 'operation' | 'subject' | 'fields'>>(
+  action: A,
+  cache: Map<string, string>,
+  root?: string,
+): { action: A; refusal?: string } {
+  const op = action.operation ?? '';
+  if (op !== 'embed_job.create') return { action };
+  const datasetId = (action.fields ?? {}).input_dataset_id;
+  if (typeof datasetId !== 'string' || datasetId === '') return { action };
+  const cached = cache.get(`dataset:${datasetId}`);
+  const identity: Identity = cached !== undefined ? { kind: 'superseded', externalId: cached } : vendorIdentity('dataset', datasetId, root);
+  if (identity.kind === 'local') {
+    return {
+      action,
+      refusal: `the embed job references dataset '${datasetId}', which this twin minted and the vendor has never seen (dataset creates are an un-pushable multipart gap) — posting that id would ask the real account to embed a dataset that does not exist there`,
+    };
+  }
+  if (identity.kind === 'superseded') {
+    return { action: { ...action, fields: { ...(action.fields ?? {}), input_dataset_id: identity.externalId } } };
+  }
+  return { action };
+}
+
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+function assertPushable(op: string, subjectType?: string): void {
+  // NAMED GAP FIRST, so a filed, reasoned gap always answers with ITS reason rather than the
+  // generic "unsupported operation" — otherwise a caller cannot tell a thought-about gap from a
+  // hole nobody has looked at, which is the whole distinction this pair encodes.
+  const why = unpushableReason(op, subjectType);
+  if (why !== undefined) throw new Error(`cohere push: cannot faithfully push '${op}' — ${why}`);
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  if (!PUSHABLE_VERBS.has(verb)) {
+    throw new Error(`cohere push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+}
+
+/** Map a subject type → its REST collection path. */
+const COLLECTION_PATH: Record<string, string> = {
+  dataset: '/v1/datasets',
+  connector: '/v1/connectors',
+  embed_job: '/v1/embed-jobs',
+};
+
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real Cohere REST
+ * surface for every write op the twin records:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.update → PATCH  <collection>/:id
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export function cohereRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): { method: 'GET' | 'POST' | 'PATCH' | 'DELETE'; path: string } {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  const collection = COLLECTION_PATH[action.subject.type] ?? `/v1/${action.subject.type}s`;
+  if (verb === 'create') return { method: 'POST', path: collection };
+  if (verb === 'update') return { method: 'PATCH', path: `${collection}/${action.subject.id}` };
+  if (verb === 'cancel') return { method: 'POST', path: `${collection}/${action.subject.id}/cancel` };
+  if (verb === 'delete') return { method: 'DELETE', path: `${collection}/${action.subject.id}` };
+  // assertPushable rejects anything else, so this is only reached for the pushable verbs above.
+  return { method: 'POST', path: collection };
+}
+
+/** The vendor-accepted payload for a create/update. The stored fields include derived lifecycle
+ *  data the endpoints do not accept, so the twin's own bookkeeping is stripped. */
+function payloadFor(action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, verb: string): Record<string, unknown> | undefined {
+  const f = (action.fields ?? {}) as Record<string, unknown>;
+  if (verb === 'update') {
+    // `UpdateConnectorRequest` is a strict subset: name / url / excludes / active /
+    // continue_on_failure. Replaying `auth_status` or `created_at` would be sending the vendor
+    // fields its own PATCH schema does not declare.
+    const out: Record<string, unknown> = {};
+    for (const k of ['name', 'url', 'excludes', 'active', 'continue_on_failure'] as const) {
+      if (f[k] !== undefined) out[k] = f[k];
+    }
+    return out;
+  }
+  if (verb !== 'create') return undefined;
+  switch (action.subject.type) {
+    case 'connector':
+      // `CreateConnectorRequest` REQUIRES name + url; the rest are optional. `auth_type` and
+      // `auth_status` are DERIVED server-side and are not accepted on create.
+      return {
+        name: f.name,
+        url: f.url,
+        ...(f.description ? { description: f.description } : {}),
+        ...(Array.isArray(f.excludes) && f.excludes.length ? { excludes: f.excludes } : {}),
+        ...(f.oauth ? { oauth: f.oauth } : {}),
+        ...(f.active !== undefined ? { active: f.active } : {}),
+        ...(f.continue_on_failure !== undefined ? { continue_on_failure: f.continue_on_failure } : {}),
+      };
+    case 'embed_job':
+      // `CreateEmbedJobRequest` REQUIRES model + dataset_id + input_type. The twin stores the
+      // dataset reference as `input_dataset_id` (the READ shape) and the create endpoint wants
+      // `dataset_id` (the WRITE shape) — the two names differ on the vendor's own schemas.
+      //
+      // `dataset_id` is resolved by the caller BEFORE this runs (§9 round two, MAJOR): the
+      // identity guard covers `subject.id`, and a FOREIGN KEY is just as capable of carrying a
+      // twin-minted UUID to the real account. See `resolveForeignKeys`.
+      return {
+        model: f.model,
+        dataset_id: f.input_dataset_id,
+        input_type: f.input_type ?? 'search_document',
+        ...(f.name ? { name: f.name } : {}),
+        ...(f.truncate ? { truncate: f.truncate } : {}),
+      };
+    // `dataset.create` is refused by `assertPushable` above (multipart), so it has no payload.
+    default:
+      return {};
+  }
+}
+
+/**
+ * The id the VENDOR minted, read out of the create response.
+ *
+ * Cohere's create responses do NOT share one envelope, and a generic `res.id` would silently fall
+ * back to the twin's local id on two of the three types — which is exactly the shape that makes a
+ * push-then-pull serve one account row TWICE:
+ *   • dataset   → `{ id }`                 (`DatasetsCreateResponse`)
+ *   • connector → `{ connector: { id } }`  (`CreateConnectorResponse` — NESTED)
+ *   • embed job → `{ job_id }`             (`CreateEmbedJobResponse` — a different key)
+ */
+function externalIdOf(subjectType: string, res: unknown): string {
+  const o = (res ?? {}) as Record<string, unknown>;
+  const found = subjectType === 'connector'
+    ? (o.connector as { id?: unknown } | undefined)?.id
+    : subjectType === 'embed_job'
+      ? o.job_id
+      : o.id;
+  if (typeof found === 'string' && found) return found;
+  // NO FALLBACK TO THE LOCAL ID (§9 round two, m-R2.1). Confirming under the twin's own UUID would
+  // MANUFACTURE a vendor identity: no tombstone is written, so `vendorIdentity` would afterwards
+  // report that id as vendor-known and every later mutation would push the twin's UUID at the real
+  // account. A create response that carries no id is a malformed response, not a successful create.
+  throw new Error(`cohere push: the ${subjectType} create response carried no vendor id — refusing to confirm under the twin's own id`);
+}
+
+/**
+ * Push ONE pending action to REAL Cohere via the injected executor. Returns the real external id.
+ * WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushCohereAction(
+  execute: CohereExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+): Promise<{ externalId: string }> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  assertPushable(op, action.subject.type);
+  const { method, path } = cohereRequestForAction(action);
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  const payload = payloadFor(action, verb);
+  const res = await execute(method, path, payload);
+  throwIfError(res, `push ${action.subject.type}`);
+  return { externalId: verb === 'create' ? externalIdOf(action.subject.type, res) : action.subject.id };
+}
+
+/**
+ * Push the twin's PENDING local actions to real Cohere and CONFIRM each: for every pending action,
+ * call the real API; on success, confirmAction records the confirmed fields as an observed event
+ * and maps action → event (suppressing the local projection — counted exactly once). Idempotency:
+ * a confirmed action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * COMPOUND-ACTION AUDIT (the `confirmAction` hazard in ADDING_A_TWIN.md §5): every action this
+ * connector pushes is SINGLE-RESOURCE — a connector or embed-job create/update, an embed-job
+ * cancel, a dataset or connector delete — so `fields` alone is the complete post-state and no
+ * `additionalObservations` are needed for the payload. The one write this twin makes that touches
+ * several resources at once is a TOKENIZE (one `token.observe` per fresh segment) — and those are
+ * separate single-resource actions on a type that is refused push-wide, so the hazard cannot
+ * arise here.
+ */
+export async function pushPendingCohereActions(
+  execute: CohereExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string>; refused: Array<{ actionId: string; operation: string; subjectId: string; reason: string }> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  const refused: Array<{ actionId: string; operation: string; subjectId: string; reason: string }> = [];
+  // Vendor ids minted DURING this run, keyed by the local subject they replaced. A create confirms
+  // under the vendor's id; every later action in the same batch that names the superseded local id
+  // must be rewritten through this map before its request is built.
+  const mintedExternal = new Map<string, string>();
+  const subjectKey = (type: string, id: string) => `${type}:${id}`;
+
+  for (const pending of pendingActions(SERVICE, opts.root)) {
+    const operation = pending.operation ?? `${pending.subject.type}.update`;
+    const verb = operation.includes('.') ? operation.slice(operation.indexOf('.') + 1) : operation;
+    // A KNOWN, filed gap is REPORTED BY NAME and skipped: throwing would abort the batch and
+    // leave the account half-pushed over a write we already decided not to send, while dropping
+    // it silently is what the doctrine forbids. Anything NOT on that list falls through to
+    // `pushCohereAction` → `assertPushable`, which THROWS — an operation nobody has reasoned about
+    // must stop the run, not become an anonymous tally.
+    const why = unpushableReason(operation, pending.subject.type);
+    if (why !== undefined) {
+      refused.push({ actionId: pending.id, operation, subjectId: pending.subject.id, reason: why });
+      continue;
+    }
+
+    // IDENTITY RESOLUTION, before any request is built (§9 round 1 B1/M1, hardened in round two).
+    // A non-create acts on a subject that must already exist AT THE VENDOR:
+    //   • superseded — a create already mapped this local id to a vendor id (this run's cache, or
+    //     the DURABLE supersede tombstone from any earlier run): address the vendor's id;
+    //   • local — the subject is twin-minted and was never successfully pushed, so there is NOTHING
+    //     at the vendor to act on. Sending the twin's own UUID would mutate or delete whatever (if
+    //     anything) carries that id in the real account. Refuse BY NAME, so it is visible every run;
+    //   • vendor — the id came from a pull and is the vendor's own: push it as-is.
+    let action: Pick<TwinAction, 'id' | 'operation' | 'subject' | 'fields'> = pending;
+    if (verb !== 'create') {
+      const cached = mintedExternal.get(subjectKey(pending.subject.type, pending.subject.id));
+      const identity: Identity = cached !== undefined
+        ? { kind: 'superseded', externalId: cached }
+        : vendorIdentity(pending.subject.type, pending.subject.id, opts.root);
+      if (identity.kind === 'local') {
+        refused.push({
+          actionId: pending.id,
+          operation,
+          subjectId: pending.subject.id,
+          reason: `the subject was minted by this twin and the vendor has never seen it (its create was refused or never pushed), so '${operation}' has nothing to act on — sending the twin's own id would address an unrelated resource in the real account`,
+        });
+        continue;
+      }
+      if (identity.kind === 'superseded') {
+        action = { ...pending, subject: { ...pending.subject, id: identity.externalId } };
+      }
+    }
+
+    // FOREIGN KEYS are resolved by the SAME rule as the subject (§9 round two, MAJOR). The subject
+    // guard above says nothing about the ids a payload REFERENCES, and an embed-job create carries
+    // its dataset's id in the body — so a locally-minted dataset id sailed straight to the real
+    // account, where the vendor rejects it and the batch wedges exactly as B1 did.
+    const fk = resolveForeignKeys(action, mintedExternal, opts.root);
+    if (fk.refusal !== undefined) {
+      refused.push({ actionId: pending.id, operation, subjectId: pending.subject.id, reason: fk.refusal });
+      continue;
+    }
+    action = fk.action;
+
+    const { externalId } = await pushCohereAction(execute, action);
+    // CONFIRM UNDER THE VENDOR'S ID, not the twin's locally-minted one. The local mint is a
+    // placeholder that only ever existed here; the account knows the row by the id its create
+    // response returned. Confirming under the local id would leave the local projection standing
+    // while the next `pullCohereState` folded the SAME resource in under its real id — one account
+    // row served as TWO. Re-subjecting the confirm suppresses the local action's projection and
+    // rebuilds the row at the real id, so push-then-pull converges.
+    const subject = { ...action.subject, id: externalId };
+    // TOMBSTONE THE SUPERSEDED LOCAL ID, IN THE SAME CONFIRM. Re-subjecting suppresses the local
+    // action's projection entirely, so without this the placeholder id would leave the row set with
+    // NO record that it ever existed or what it became — a client still holding it gets a bare 404
+    // and no way to follow the resource to its real id. The tombstone keeps that provenance
+    // (`_superseded_by`) auditable and the id visibly occupied.
+    //
+    // HONEST SCOPE (§9 round 1, m4, corrected by its own revert-matrix cell): this does NOT stop
+    // `nextId` re-issuing the id. That mint takes its ordinal from the row-set SIZE and only ever
+    // probes upward, so a superseded id is not a re-issue candidate with or without the tombstone.
+    // An earlier version of this note claimed otherwise, and the pin written to prove that claim
+    // came out hollow.
+    //
+    // It rides `additionalObservations` — the
+    // kernel's own seam for a compound confirm — rather than a second `applyTwinWrite`: a local
+    // write here would itself be a PENDING action, which the very next push would try to send to
+    // the vendor as `<type>.superseded`.
+    const tombstone = externalId !== action.subject.id
+      ? [{ subject: action.subject, fields: { _deleted: true, _superseded_by: externalId } }]
+      : [];
+    if (externalId !== action.subject.id) mintedExternal.set(subjectKey(action.subject.type, action.subject.id), externalId);
+    confirmAction({
+      service: SERVICE, actionId: action.id, subject, fields: confirmFields(action.fields),
+      ...(tombstone.length ? { additionalObservations: tombstone } : {}),
+      occurredAt: opts.occurredAt, ...(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
+ * Cohere and confirm it, then (2) PULL all modeled 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 (push 0,
+ * deltasAppended 0). Same code path offline (fake executor) and live (real key).
+ */
+export async function fullSyncCohere(
+  execute: CohereExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; refused: Array<{ actionId: string; operation: string; subjectId: string; reason: string }>; observed: number; deltasAppended: number; collections: number }> {
+  const push = await pushPendingCohereActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  const resources = await pullCohereState(execute);
+  const pull = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  // The REFUSALS THEMSELVES, not a count: a bare integer that ticks up and never comes down is not
+  // a signal an operator can act on.
+  return { pushed: push.pushed, refused: push.refused, observed: pull.observed, deltasAppended: pull.deltasAppended, collections: COLLECTIONS.length };
+}