@volter/twin-cohere 0.1.0

package/dist/src/cohere-connector.js

@@ -0,0 +1,625 @@
+// 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 { CohereBudget, CohereBudgetError, cohereCallWeight } from "./cohere-budget.js";
+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';
+/**
+ * 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, base = COHERE_API_BASE, 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 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 = { 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 = 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 = {};
+        res.headers.forEach((v, k) => { 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);
+        }
+        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, ctx) {
+    const e = res;
+    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, key, nullable, ctx) {
+    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, key)) {
+        throw new Error(`cohere ${ctx} failed: the response has no "${key}" key — an unrecognized envelope is not an empty account`);
+    }
+    const v = res[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;
+}
+// ── 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) {
+    return {
+        type: 'dataset',
+        id: String(d.id),
+        fields: {
+            name: d.name ?? null,
+            created_at: d.created_at ?? null,
+            updated_at: d.updated_at ?? d.created_at ?? null,
+            dataset_type: d.dataset_type ?? null,
+            validation_status: d.validation_status ?? null,
+            validation_error: d.validation_error ?? null,
+            validation_warnings: d.validation_warnings ?? [],
+            required_fields: d.required_fields ?? [],
+            preserve_fields: d.preserve_fields ?? [],
+            dataset_parts: d.dataset_parts ?? [],
+        },
+    };
+}
+/** Map a real-Cohere Connector → a twin sync resource. */
+export function mapConnector(c) {
+    return {
+        type: 'connector',
+        id: String(c.id),
+        fields: {
+            organization_id: c.organization_id ?? null,
+            name: c.name ?? null,
+            description: c.description ?? null,
+            url: c.url ?? null,
+            created_at: c.created_at ?? null,
+            updated_at: c.updated_at ?? c.created_at ?? null,
+            excludes: c.excludes ?? [],
+            auth_type: c.auth_type ?? null,
+            oauth: c.oauth ?? null,
+            auth_status: c.auth_status ?? 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) {
+    return {
+        type: 'embed_job',
+        id: String(j.job_id),
+        fields: {
+            job_id: String(j.job_id),
+            name: j.name ?? null,
+            status: j.status ?? null,
+            created_at: j.created_at ?? null,
+            input_dataset_id: j.input_dataset_id ?? null,
+            output_dataset_id: j.output_dataset_id ?? null,
+            model: j.model ?? null,
+            truncate: j.truncate ?? 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 = [
+    { 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) {
+    const out = [];
+    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() {
+    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, opts = {}) {
+    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 = {
+    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 = {
+    '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, subjectType) {
+    if (subjectType !== undefined && UNPUSHABLE_TYPES[subjectType] !== undefined)
+        return UNPUSHABLE_TYPES[subjectType];
+    return UNPUSHABLE_OPS[op];
+}
+/**
+ * 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, subjectId, root) {
+    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) {
+    const out = { ...(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(action, cache, root) {
+    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 = 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, subjectType) {
+    // 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 = {
+    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) {
+    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, verb) {
+    const f = (action.fields ?? {});
+    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 = {};
+        for (const k of ['name', 'url', 'excludes', 'active', 'continue_on_failure']) {
+            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, res) {
+    const o = (res ?? {});
+    const found = subjectType === 'connector'
+        ? o.connector?.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, action) {
+    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, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    const refused = [];
+    // 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();
+    const subjectKey = (type, id) => `${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 = pending;
+        if (verb !== 'create') {
+            const cached = mintedExternal.get(subjectKey(pending.subject.type, pending.subject.id));
+            const 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, opts) {
+    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 };
+}

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

@@ -0,0 +1,21 @@
+import { COHERE_ENDPOINTS, type CohereEndpoint, type CohereModelCard } from './cohere-types.js';
+/**
+ * The catalog. `tokenizer_url` is DERIVED from Cohere's published tokenizer URL pattern
+ * (`storage.googleapis.com/cohere-public/tokenizers/<model>.json`) and is NOT individually verified
+ * per model — several of these (the rerank and embed cards especially) may have no such artifact,
+ * and neither SDK carries the per-model URLs to check against. Saying so is the honest scope: an
+ * earlier note called this "Cohere's real published artifacts", which overstated what was read
+ * (§9 round two, m-R2.6). The twin never FETCHES it either way — that would be request-time egress
+ * and would break serve-path determinism.
+ */
+export declare const COHERE_MODELS: CohereModelCard[];
+/** Look a model up by its exact id. Cohere has no alias resolution on this endpoint. */
+export declare function findModel(name: string): CohereModelCard | undefined;
+/**
+ * Does `name` name a model that serves `endpoint`? Used to reject `POST /v2/chat` with an embed
+ * model (and vice versa) the way the vendor does, rather than happily generating from it — an
+ * unmodeled-op-fails-like-the-vendor property that is TESTABLE.
+ */
+export declare function modelServes(name: string, endpoint: CohereEndpoint): boolean;
+/** The closed `CompatibleEndpoint` set, re-exported so tests can assert against it by name. */
+export { COHERE_ENDPOINTS };