@volter/twin-togetherai 0.1.0

package/src/togetherai-conformance.ts

@@ -0,0 +1,459 @@
+// Together AI twin conformance — an offline check with REAL TEETH: delete a handler branch and
+// it goes RED. The harness runs THREE passes (the groq pack's method):
+//
+//   1. PROBES — one real request per CLAIMED endpoint, graded on the OUTCOME a live handler
+//      produces: an expected status set PLUS a predicate over the body. A handler that returned
+//      `{}`, or whose branch was deleted (so the router falls through to its not-found), fails.
+//   2. BIJECTION — the probe table and the claimed-endpoint snapshot must match two ways, so a
+//      claim with no probe and a probe with no claim are both RED.
+//   3. ROUTER_SURFACE — a HAND-AUTHORED census of every method/path pair `routeTogetherai`
+//      branches on. Every entry must be claimed; and the paths Together serves but this twin does
+//      NOT model (plus the surface Together does NOT have — OpenAI's assistants/threads/responses/
+//      moderations, OpenAI-shaped batch/file/fine-tune endpoints) must answer the vendor-shaped
+//      not-found envelope. This closes the served-but-unclaimed direction that probe⇄claim alone
+//      is blind to.
+//
+// Fully offline + deterministic (drives the local handler against a temp root) so it runs in CI
+// without an API key. Honest scope: it checks the protocol envelope, NOT model output (a
+// deterministic labeled stub by design).
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleTogetheraiTwinRequest, type TogetheraiResponseEnvelope } from './togetherai-twin.ts';
+import type { SseEvent } from './togetherai-types.ts';
+
+export type ConformanceViolation = { check: string; detail: string };
+export type TogetheraiConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  probes: number;
+  violations: ConformanceViolation[];
+};
+
+type Body = Record<string, any>;
+const isObj = (v: unknown): v is Body => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * THE CLAIMED SURFACE. Every entry is a real request plus the OUTCOME a live handler produces.
+ * The expected values are LITERALS here, never imported from the handler — an assertion against
+ * the module's own constant is a tautology that cannot catch the value drifting.
+ */
+type Probe = {
+  /** `"<METHOD> <path>"` — the claim key, and the bijection key. */
+  key: string;
+  method: string;
+  path: string;
+  body?: unknown;
+  /** Which statuses a live handler may answer with. */
+  statuses: number[];
+  /** What a live handler's body must look like. */
+  ok: (body: unknown, status: number) => boolean;
+  /** Seed the root before probing (returns nothing; failures surface as probe failures). */
+  seed?: (h: (m: string, p: string, b?: unknown) => Promise<TogetheraiResponseEnvelope>) => Promise<void>;
+};
+
+const CHAT = { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', messages: [{ role: 'user', content: 'hi' }] };
+
+const PROBES: Probe[] = [
+  {
+    key: 'POST /v1/chat/completions',
+    method: 'POST', path: '/v1/chat/completions', body: CHAT, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'chat.completion' && Array.isArray(b.choices)
+      && (b.choices as Body[])[0]?.message?.role === 'assistant'
+      && typeof (b.choices as Body[])[0]?.message?.content === 'string'
+      && isObj(b.usage) && typeof b.usage.total_tokens === 'number'
+      && Array.isArray(b.prompt),
+  },
+  {
+    key: 'GET /v1/models',
+    method: 'GET', path: '/v1/models', statuses: [200],
+    ok: (b) => Array.isArray(b) && (b as Body[]).some((m) => m.id === 'meta-llama/Llama-3.3-70B-Instruct-Turbo' && m.object === 'model' && typeof m.created === 'number' && typeof m.type === 'string'),
+  },
+  {
+    key: 'GET /v1/models/{model}',
+    method: 'GET', path: '/v1/models/meta-llama/Llama-3.3-70B-Instruct-Turbo', statuses: [200],
+    ok: (b) => isObj(b) && b.id === 'meta-llama/Llama-3.3-70B-Instruct-Turbo' && b.object === 'model',
+  },
+  {
+    key: 'POST /v1/completions',
+    method: 'POST', path: '/v1/completions', body: { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', prompt: 'Once' }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'text.completion' && Array.isArray(b.prompt) && isObj(b.usage),
+  },
+  {
+    key: 'POST /v1/embeddings',
+    method: 'POST', path: '/v1/embeddings', body: { model: 'WhereIsAI/UAE-Large-V1', input: 'x' }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'list' && Array.isArray(b.data) && (b.data as Body[])[0]?.embedding?.length === 1024 && !('usage' in b),
+  },
+  {
+    key: 'POST /v1/rerank',
+    method: 'POST', path: '/v1/rerank', body: { model: 'Salesforce/Llama-Rank-v1', query: 'q', documents: ['a', 'b'] }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'rerank' && Array.isArray(b.results) && (b.results as Body[])[0]?.relevance_score !== undefined,
+  },
+  {
+    key: 'POST /v1/images/generations',
+    method: 'POST', path: '/v1/images/generations', body: { model: 'black-forest-labs/FLUX.1-schnell', prompt: 'a cat' }, statuses: [200],
+    ok: (b) => isObj(b) && Array.isArray(b.data) && (b.data as Body[])[0]?.url !== undefined,
+  },
+  {
+    key: 'POST /v1/audio/speech',
+    method: 'POST', path: '/v1/audio/speech', body: { model: 'cartesia/sonic', input: 'hi', voice: 'female' }, statuses: [200],
+    ok: (b) => typeof b === 'string' && b.includes('[twin-stub:'),
+  },
+  {
+    key: 'POST /v1/audio/transcriptions',
+    method: 'POST', path: '/v1/audio/transcriptions', body: { model: 'cartesia/sonic', file: 'a.wav' }, statuses: [200],
+    ok: (b) => isObj(b) && typeof b.text === 'string',
+  },
+  {
+    key: 'POST /v1/audio/translations',
+    method: 'POST', path: '/v1/audio/translations', body: { model: 'cartesia/sonic', file: 'a.wav', response_format: 'verbose_json' }, statuses: [200],
+    ok: (b) => isObj(b) && b.task === 'translate' && typeof b.text === 'string',
+  },
+  {
+    key: 'GET /v1/whoami',
+    method: 'GET', path: '/v1/whoami', statuses: [200],
+    ok: (b) => isObj(b) && typeof b.api_key_id === 'string' && typeof b.project_id === 'string' && typeof b.organization_id === 'string',
+  },
+  {
+    key: 'POST /v1/files/upload',
+    method: 'POST', path: '/v1/files/upload', body: { purpose: 'fine-tune', filename: 'a.jsonl', content: 'x' }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'file' && b.Processed === true && b.FileType === 'jsonl',
+  },
+  {
+    key: 'GET /v1/files',
+    method: 'GET', path: '/v1/files', statuses: [200],
+    ok: (b) => isObj(b) && Array.isArray(b.data),
+  },
+  {
+    key: 'GET /v1/files/{file_id}',
+    method: 'GET', path: '/v1/files/file_twin_1', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 'a.jsonl', content: 'x' }); },
+    ok: (b) => isObj(b) && b.id === 'file_twin_1' && b.object === 'file',
+  },
+  {
+    key: 'GET /v1/files/{file_id}/content',
+    method: 'GET', path: '/v1/files/file_twin_1/content', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 'a.jsonl', content: 'x' }); },
+    ok: (b) => b === 'x',
+  },
+  {
+    key: 'DELETE /v1/files/{file_id}',
+    method: 'DELETE', path: '/v1/files/file_twin_1', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 'a.jsonl', content: 'x' }); },
+    ok: (b) => isObj(b) && b.deleted === true,
+  },
+  {
+    key: 'POST /v1/batches',
+    method: 'POST', path: '/v1/batches', statuses: [201],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'batch-api', filename: 'in.jsonl', content: '{"custom_id":"a"}' }); },
+    body: { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions' },
+    ok: (b) => isObj(b) && isObj(b.job) && typeof b.job.id === 'string' && b.job.status === 'VALIDATING',
+  },
+  {
+    key: 'GET /v1/batches',
+    method: 'GET', path: '/v1/batches', statuses: [200],
+    ok: (b) => Array.isArray(b),
+  },
+  {
+    key: 'GET /v1/batches/{batch_id}',
+    method: 'GET', path: '/v1/batches/batch_twin_1', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'batch-api', filename: 'in.jsonl', content: '{}' }); await h('POST', '/v1/batches', { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions' }); },
+    ok: (b) => isObj(b) && b.id === 'batch_twin_1' && (b.error === null || isObj(b.error)),
+  },
+  {
+    key: 'POST /v1/batches/{batch_id}/cancel',
+    method: 'POST', path: '/v1/batches/batch_twin_1/cancel', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'batch-api', filename: 'in.jsonl', content: '{}' }); await h('POST', '/v1/batches', { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions' }); },
+    ok: (b) => isObj(b) && b.status === 'CANCELLED',
+  },
+  {
+    key: 'POST /v1/fine-tunes',
+    method: 'POST', path: '/v1/fine-tunes', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 't.jsonl', content: 'x' }); },
+    body: { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', training_file: 'file_twin_1' },
+    ok: (b) => isObj(b) && b.status === 'pending' && typeof b.id === 'string' && b.id.startsWith('ft'),
+  },
+  {
+    key: 'GET /v1/fine-tunes',
+    method: 'GET', path: '/v1/fine-tunes', statuses: [200],
+    ok: (b) => Array.isArray(b),
+  },
+  {
+    key: 'GET /v1/fine-tunes/{id}',
+    method: 'GET', path: '/v1/fine-tunes/ft_twin_1', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 't.jsonl', content: 'x' }); await h('POST', '/v1/fine-tunes', { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', training_file: 'file_twin_1' }); },
+    ok: (b) => isObj(b) && b.id === 'ft_twin_1',
+  },
+  {
+    key: 'POST /v1/fine-tunes/{id}/cancel',
+    method: 'POST', path: '/v1/fine-tunes/ft_twin_1/cancel', statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 't.jsonl', content: 'x' }); await h('POST', '/v1/fine-tunes', { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', training_file: 'file_twin_1' }); },
+    ok: (b) => isObj(b) && b.status === 'cancel_requested',
+  },
+  {
+    // Together's estimate-price is a discriminated union on `estimation_available`
+    // (together-ai@0.53.0 fine-tuning.d.ts:1323), not OpenAI's {cost_usd, estimated_tokens}.
+    // The probe seeds a real file — an unknown training_file answers the OTHER arm of the union
+    // (UnavailableEstimate / train_file_invalid), asserted by the capabilities verify.
+    key: 'POST /v1/fine-tunes/estimate-price',
+    method: 'POST', path: '/v1/fine-tunes/estimate-price', body: { model: 'm', training_file: 'file_twin_1' }, statuses: [200],
+    seed: async (h) => { await h('POST', '/v1/files/upload', { purpose: 'fine-tune', filename: 'est.jsonl', content: '{"text":"r"}\n' }); },
+    ok: (b) => isObj(b) && b.estimation_available === true && typeof b.estimated_total_price === 'number',
+  },
+  {
+    // Together's FinetuneModelLimits for ONE model — `model_name` is REQUIRED
+    // (together-ai@0.53.0 fine-tuning.d.ts:1798), so the probe names a catalog model and
+    // asserts the shape's REQUIRED keys; an unknown model is a 404, asserted by the
+    // capabilities verify.
+    key: 'GET /v1/fine-tunes/models/limits',
+    method: 'GET', path: '/v1/fine-tunes/models/limits?model_name=meta-llama/Llama-3.3-70B-Instruct-Turbo', statuses: [200],
+    ok: (b) => isObj(b) && b.model_name === 'meta-llama/Llama-3.3-70B-Instruct-Turbo' && typeof b.max_num_epochs === 'number' && typeof b.lora_training?.max_rank === 'number',
+  },
+];
+
+const ROUTER_SURFACE: Array<{ key: string; method: string; path: string; body?: unknown }> = [
+  { key: 'GET /v1/models', method: 'GET', path: '/v1/models' },
+  { key: 'GET /v1/models/{model}', method: 'GET', path: '/v1/models/meta-llama/Llama-3.3-70B-Instruct-Turbo' },
+  { key: 'POST /v1/chat/completions', method: 'POST', path: '/v1/chat/completions', body: CHAT },
+  { key: 'POST /v1/completions', method: 'POST', path: '/v1/completions', body: { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', prompt: 'Once' } },
+  { key: 'POST /v1/embeddings', method: 'POST', path: '/v1/embeddings', body: { model: 'WhereIsAI/UAE-Large-V1', input: 'x' } },
+  { key: 'POST /v1/rerank', method: 'POST', path: '/v1/rerank', body: { model: 'Salesforce/Llama-Rank-v1', query: 'q', documents: ['a'] } },
+  { key: 'POST /v1/images/generations', method: 'POST', path: '/v1/images/generations', body: { model: 'black-forest-labs/FLUX.1-schnell', prompt: 'a cat' } },
+  { key: 'POST /v1/audio/speech', method: 'POST', path: '/v1/audio/speech', body: { model: 'cartesia/sonic', input: 'hi', voice: 'female' } },
+  { key: 'POST /v1/audio/transcriptions', method: 'POST', path: '/v1/audio/transcriptions', body: { model: 'cartesia/sonic', file: 'a.wav' } },
+  { key: 'POST /v1/audio/translations', method: 'POST', path: '/v1/audio/translations', body: { model: 'cartesia/sonic', file: 'a.wav' } },
+  { key: 'GET /v1/whoami', method: 'GET', path: '/v1/whoami' },
+  { key: 'POST /v1/files/upload', method: 'POST', path: '/v1/files/upload', body: { purpose: 'fine-tune', filename: 'a.jsonl', content: 'x' } },
+  { key: 'GET /v1/files', method: 'GET', path: '/v1/files' },
+  { key: 'GET /v1/files/{file_id}', method: 'GET', path: '/v1/files/file_twin_1' },
+  { key: 'GET /v1/files/{file_id}/content', method: 'GET', path: '/v1/files/file_twin_1/content' },
+  { key: 'DELETE /v1/files/{file_id}', method: 'DELETE', path: '/v1/files/file_twin_1' },
+  { key: 'POST /v1/batches', method: 'POST', path: '/v1/batches', body: { input_file_id: 'file_twin_1', endpoint: '/v1/chat/completions' } },
+  { key: 'GET /v1/batches', method: 'GET', path: '/v1/batches' },
+  { key: 'GET /v1/batches/{batch_id}', method: 'GET', path: '/v1/batches/batch_twin_1' },
+  { key: 'POST /v1/batches/{batch_id}/cancel', method: 'POST', path: '/v1/batches/batch_twin_1/cancel' },
+  { key: 'POST /v1/fine-tunes', method: 'POST', path: '/v1/fine-tunes', body: { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', training_file: 'file_twin_1' } },
+  { key: 'GET /v1/fine-tunes', method: 'GET', path: '/v1/fine-tunes' },
+  { key: 'GET /v1/fine-tunes/{id}', method: 'GET', path: '/v1/fine-tunes/ft_twin_1' },
+  { key: 'POST /v1/fine-tunes/{id}/cancel', method: 'POST', path: '/v1/fine-tunes/ft_twin_1/cancel' },
+  { key: 'POST /v1/fine-tunes/estimate-price', method: 'POST', path: '/v1/fine-tunes/estimate-price', body: { model: 'm', training_file: 'f' } },
+  { key: 'GET /v1/fine-tunes/models/limits', method: 'GET', path: '/v1/fine-tunes/models/limits' },
+];
+
+/** The literal the router falls through to when NO branch matched. A census entry answering this
+ *  means its branch is gone. Kept as a LITERAL — importing the handler's string would be a
+ *  tautology that could not catch the message drifting. */
+const ROUTER_MISS = 'Unknown request URL';
+
+const ROUTER_SURFACE_KEYS: string[] = ROUTER_SURFACE.map((e) => e.key);
+
+/**
+ * Surface the twin must NOT serve: real Together endpoints this twin does not model yet (unmodeled
+ * ops fail like the vendor, never a fake success), plus the OpenAI-shaped surface Together does
+ * NOT have (Together's OpenAI compatibility is the INFERENCE endpoints only — its Batch/Files/
+ * Fine-tuning APIs are Together-native and are served at their own shapes here; assistants,
+ * threads, responses and moderations do not exist at Together at all).
+ */
+const MUST_NOT_SERVE: Array<{ method: string; path: string; why: string }> = [
+  { method: 'POST', path: '/v1/responses', why: "OpenAI's Responses API does not exist at Together" },
+  { method: 'POST', path: '/v1/moderations', why: "OpenAI's moderations endpoint does not exist at Together" },
+  { method: 'GET', path: '/v1/threads', why: "OpenAI's Assistants/Threads surface does not exist at Together" },
+  { method: 'POST', path: '/v1/fine_tuning/jobs', why: "OpenAI's fine-tuning shape — Together's own is /v1/fine-tunes (modeled)" },
+  { method: 'POST', path: '/v1/vector_stores', why: "OpenAI's vector stores do not exist at Together" },
+  { method: 'POST', path: '/v2/endpoints', why: 'the v2 management half is real Together surface this twin does not serve' },
+  { method: 'POST', path: '/v1/chat/completions/extra', why: 'a path under /v1 the router does not model' },
+];
+
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkTogetheraiConformance(opts: { root?: string } = {}): Promise<TogetheraiConformanceReport> {
+  const violations: ConformanceViolation[] = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  // `--root DIR` is the PARENT the throwaway probe roots are minted under; a dir that does not
+  // exist yet is created (mkdtempSync would otherwise die on a raw ENOENT).
+  if (opts.root !== undefined) mkdirSync(opts.root, { recursive: true });
+
+  // ── 1. PROBES: each in its OWN throwaway root, so a probe's seed can't leak into another. ──
+  for (const probe of PROBES) {
+    checksRun++;
+    // A FRESH root per probe, always. `opts.root` is the PARENT directory, never a shared root:
+    // sharing it let `nextId` ratchet across probes, so the `files/file_twin_1` probe read the id
+    // an earlier probe had minted and reported false violations (the groq pack's §9 round two,
+    // finding 12).
+    const root = mkdtempSync(join(opts.root ?? tmpdir(), 'togetherai-conf-'));
+    const h = (method: string, path: string, body?: unknown) =>
+      handleTogetheraiTwinRequest({ method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }), root });
+    try {
+      if (probe.seed) await probe.seed(h);
+      const res = await h(probe.method, probe.path, probe.body);
+      if (!probe.statuses.includes(res.status)) {
+        fail(`probe:${probe.key}`, `status ${res.status} (expected one of ${probe.statuses.join('/')}) body=${JSON.stringify(res.body).slice(0, 200)}`);
+      } else if (!probe.ok(res.body, res.status)) {
+        fail(`probe:${probe.key}`, `body did not satisfy the live-handler predicate: ${JSON.stringify(res.body).slice(0, 300)}`);
+      }
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  // ── 2. BIJECTION: probe table ⇄ router census, both directions. ──
+  checksRun++;
+  const probeKeys = new Set(PROBES.map((p) => p.key));
+  for (const key of ROUTER_SURFACE_KEYS) if (!probeKeys.has(key)) fail('bijection', `router branch "${key}" has no probe`);
+  for (const key of probeKeys) if (!ROUTER_SURFACE_KEYS.includes(key)) fail('bijection', `probe "${key}" is not in the hand-authored router census`);
+  if (PROBES.length !== new Set(PROBES.map((p) => p.key)).size) fail('bijection', 'duplicate probe key');
+  if (ROUTER_SURFACE.length !== ROUTER_SURFACE_KEYS.length) fail('bijection', 'the router census and its key list disagree');
+
+  // ── 2b. THE CENSUS HAS TEETH: every declared branch must actually be REACHED. A branch whose
+  //       handler was deleted falls through to the router's own not-found, which is what this
+  //       catches — independently of that endpoint's own probe.
+  for (const entry of ROUTER_SURFACE) {
+    checksRun++;
+    const root = mkdtempSync(join(opts.root ?? tmpdir(), 'togetherai-conf-'));
+    try {
+      const res = await handleTogetheraiTwinRequest({ method: entry.method, path: entry.path, ...(entry.body === undefined ? {} : { body: JSON.stringify(entry.body) }), root });
+      const message = String(((res.body as Body)?.error as Body)?.message ?? '');
+      if (message.includes(ROUTER_MISS)) {
+        fail('router_surface', `${entry.key} fell through to the router's not-found — the branch is gone (answered ${res.status}: ${message})`);
+      }
+      if (!ROUTER_SURFACE_KEYS.includes(entry.key)) fail('router_surface', `${entry.key} is exercised but not declared`);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  // ── 3. The twin must not serve surface it does not model (or the vendor does not have). ──
+  {
+    const root = opts.root ?? mkdtempSync(join(tmpdir(), 'togetherai-conf-'));
+    try {
+      for (const entry of MUST_NOT_SERVE) {
+        checksRun++;
+        const res = await handleTogetheraiTwinRequest({ method: entry.method, path: entry.path, root });
+        if (res.status !== 404) fail('must_not_serve', `${entry.method} ${entry.path} answered ${res.status}, not 404 — ${entry.why}`);
+        else if (!isObj(res.body) || !isObj((res.body as Body).error)) fail('must_not_serve', `${entry.method} ${entry.path} 404 body is not the vendor error envelope`);
+      }
+
+      // ── 4. The error envelope must carry the keys Together's own published schema declares
+      //      (`ErrorData`: message + type REQUIRED, param + code nullable-with-default-null).
+      //      The key list is a LITERAL here — asserting against the handler's own constant would
+      //      be a tautology that could not catch it drifting.
+      checksRun++;
+      const ERROR_DATA_KEYS = new Set(['message', 'type', 'param', 'code']);
+      const bad = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify({ model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', messages: [] }), root });
+      const eb = bad.body as Body;
+      if (bad.status !== 400 || !isObj(eb?.error)) {
+        fail('error.envelope', `empty messages did not yield a 400 with an error envelope (status ${bad.status})`);
+      } else {
+        const undeclared = Object.keys(eb.error).filter((k) => !ERROR_DATA_KEYS.has(k));
+        if (undeclared.length) fail('error.envelope', `error object carries key(s) Together's ErrorData does not declare: ${undeclared.join(', ')}`);
+        if (typeof eb.error.message !== 'string' || !eb.error.message) fail('error.envelope', 'error.message is not a non-empty string');
+        if (typeof eb.error.type !== 'string' || !eb.error.type) fail('error.envelope', 'error.type is not a non-empty string');
+      }
+
+      // ── 4b. Together's OWN status table (docs.together.ai/docs/error-codes, read 2026-09-16):
+      //      402 = monthly spending limit; 403 = context length exceeded; 503 = engine overloaded.
+      //      A twin answering 400/429/500 there would be OpenAI's table, not Together's.
+      checksRun++;
+      const long = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify({ ...CHAT, max_tokens: 200_000 }) });
+      if (long.status !== 403) fail('vendor_status_table', `over-window request answered ${long.status}, not Together's 403`);
+      const forced402 = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify(CHAT), headers: { authorization: 'Bearer key_twin', 'x-twin-force-spending-limit': '1' } });
+      if (forced402.status !== 402) fail('vendor_status_table', `the spending-limit trigger answered ${forced402.status}, not Together's 402`);
+      const forced503 = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify(CHAT), headers: { authorization: 'Bearer key_twin', 'x-twin-force-engine-overloaded': '1' } });
+      if (forced503.status !== 503) fail('vendor_status_table', `the engine-overloaded trigger answered ${forced503.status}, not Together's 503`);
+
+      // ── 4c. The fields Together ACCEPTS BUT IGNORES must not change the answer, and the fields
+      //      it 400s must not be served (docs.together.ai openai-compatibility, read 2026-09-16).
+      checksRun++;
+      const plain = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify(CHAT) });
+      const decorated = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify({ ...CHAT, service_tier: 'flex', store: true, metadata: { k: 'v' }, prediction: { content: 'x' } }) });
+      if (plain.status !== 200 || decorated.status !== 200) fail('accepted_ignored_fields', `plain=${plain.status} decorated=${decorated.status}`);
+      else if ((plain.body as Body).choices[0].message.content !== (decorated.body as Body).choices[0].message.content) {
+        fail('accepted_ignored_fields', 'an accepted-but-ignored field changed the answer');
+      }
+      const n129 = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify({ ...CHAT, n: 129 }) });
+      if (n129.status !== 400) fail('rejected_fields', 'n:129 answered ' + n129.status + ', not 400');
+      const logprobs21 = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify({ ...CHAT, logprobs: 21 }) });
+      if (logprobs21.status !== 400) fail('rejected_fields', 'logprobs:21 answered ' + logprobs21.status + ', not 400');
+      const badBehavior = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify({ ...CHAT, context_length_exceeded_behavior: 'shrink' }) });
+      if (badBehavior.status !== 400) fail('rejected_fields', 'an off-enum context_length_exceeded_behavior answered ' + badBehavior.status + ', not 400');
+      const noSchemaName = await handleTogetheraiTwinRequest({ method: 'POST', path: '/v1/chat/completions', root, body: JSON.stringify({ ...CHAT, response_format: { type: 'json_schema', json_schema: { schema: {} } } }) });
+      if (noSchemaName.status !== 400) fail('rejected_fields', 'json_schema without .name answered ' + noSchemaName.status + ', not 400');
+
+      // ── 5. The streaming chunk sequence: role chunk → content/reasoning/tool deltas →
+      //      finish_reason chunk → Together's usage-bearing tail (empty choices) → [DONE].
+      //      Every chunk carries Together's nullable usage + warnings (the schema declares both
+      //      on ChatCompletionChunk itself — OpenAI puts usage only in an opt-in tail chunk).
+      checksRun++;
+      const events: SseEvent[] = [];
+      await handleTogetheraiTwinRequest({
+        method: 'POST', path: '/v1/chat/completions', root,
+        body: JSON.stringify({ ...CHAT, stream: true }),
+        sseSink: (e) => events.push(e),
+      });
+      const data = events.filter((e) => !e.done).map((e) => e.data as Body);
+      const hasRole = data.some((c) => ((c.choices as Body[])?.[0]?.delta as Body)?.role === 'assistant');
+      const doneFrame = events.length > 0 && events[events.length - 1]!.done === true;
+      const firstObj = data[0]?.object;
+      const tail = data[data.length - 1];
+      if (!hasRole) fail('chat.stream', 'no role delta chunk');
+      if (!doneFrame) fail('chat.stream', 'stream did not end with [DONE]');
+      if (firstObj !== 'chat.completion.chunk') fail('chat.stream', `first chunk object is ${String(firstObj)}`);
+      if (!data.every((c) => 'usage' in c && 'warnings' in c)) fail('chat.stream', 'a chunk is missing Together\'s usage/warnings keys');
+      if (!tail || !Array.isArray(tail.choices) || tail.choices.length !== 0 || !isObj(tail.usage) || typeof tail.usage.total_tokens !== 'number') {
+        fail('chat.stream', "final chunk is not Together's empty-choices usage tail");
+      }
+
+      // ── 5b. The LEGACY completions endpoint streams too (the SDK types it
+      //      Stream<CompletionChunk>): token/text chunks with `object: 'completion.chunk'`,
+      //      then the finish chunk carrying the real usage, then [DONE].
+      checksRun++;
+      const compEvents: SseEvent[] = [];
+      await handleTogetheraiTwinRequest({
+        method: 'POST', path: '/v1/completions', root,
+        body: JSON.stringify({ model: CHAT.model, prompt: 'Once', stream: true, max_tokens: 20 }),
+        sseSink: (e) => compEvents.push(e),
+      });
+      const compData = compEvents.filter((e) => !e.done).map((e) => e.data as Body);
+      const compTail = compData[compData.length - 1];
+      if (compData.length === 0) fail('completions.stream', 'no chunks emitted');
+      if (!compData.every((c) => c.object === 'completion.chunk')) fail('completions.stream', "a chunk's object is not 'completion.chunk'");
+      if (!compData.every((c) => 'usage' in c)) fail('completions.stream', "a chunk is missing Together's nullable usage key");
+      if (!compData.slice(0, -1).every((c) => c.finish_reason === null)) fail('completions.stream', 'a mid-stream chunk carries a finish_reason');
+      if (!compTail || compTail.finish_reason === null || !isObj(compTail.usage) || typeof compTail.usage.total_tokens !== 'number') {
+        fail('completions.stream', 'the finish chunk does not carry finish_reason + the real usage');
+      }
+      const compDone = compEvents.length > 0 && compEvents[compEvents.length - 1]!.done === true;
+      if (!compDone) fail('completions.stream', 'stream did not end with [DONE]');
+
+      // ── 6. tool_calls envelope when tools are provided, and the message shape Together's
+      //      schema declares (reasoning/reasoning_content, NO OpenAI `refusal`).
+      checksRun++;
+      const tool = await handleTogetheraiTwinRequest({
+        method: 'POST', path: '/v1/chat/completions', root,
+        body: JSON.stringify({ ...CHAT, tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }] }),
+      });
+      const choice = ((tool.body as Body).choices as Body[])?.[0];
+      if (choice?.finish_reason !== 'tool_calls') fail('chat.tool_calls', 'finish_reason not tool_calls');
+      const calls = choice?.message?.tool_calls as Body[];
+      if (!Array.isArray(calls) || calls[0]?.type !== 'function' || calls[0]?.function?.name !== 'get_weather') fail('chat.tool_calls', 'no get_weather function tool_call');
+      if (choice && 'refusal' in (choice.message as Body)) fail('chat.message_shape', "assistant message carries a `refusal` field Together's schema does not define");
+
+      // ── 7. The deprecated `functions` parameter answers with the deprecated `function_call`
+      //      response shape, not `tool_calls` (Together's ChatCompletionMessage.function_call +
+      //      FinishReason 'function_call').
+      checksRun++;
+      const legacy = await handleTogetheraiTwinRequest({
+        method: 'POST', path: '/v1/chat/completions', root,
+        body: JSON.stringify({ ...CHAT, functions: [{ name: 'legacy_fn', parameters: { type: 'object', properties: { q: { type: 'string' } } } }] }),
+      });
+      const lc = ((legacy.body as Body).choices as Body[])?.[0];
+      if (lc?.finish_reason !== 'function_call') fail('chat.legacy_functions', `finish_reason is ${String(lc?.finish_reason)}, not function_call`);
+      if (lc?.message?.function_call?.name !== 'legacy_fn') fail('chat.legacy_functions', 'no function_call on the assistant message');
+      if (lc?.message?.tool_calls !== undefined) fail('chat.legacy_functions', 'legacy functions must not answer with tool_calls');
+    } finally {
+      if (opts.root === undefined) rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  return { ok: violations.length === 0, checksRun, probes: PROBES.length, violations };
+}