@volter/twin-togetherai 0.1.0

package/dist/src/togetherai-conformance.d.ts

@@ -0,0 +1,14 @@
+export type ConformanceViolation = {
+    check: string;
+    detail: string;
+};
+export type TogetheraiConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    probes: number;
+    violations: ConformanceViolation[];
+};
+/** Run the offline conformance checks against a fresh temp root. */
+export declare function checkTogetheraiConformance(opts?: {
+    root?: string;
+}): Promise<TogetheraiConformanceReport>;

package/dist/src/togetherai-conformance.js

@@ -0,0 +1,452 @@
+// 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 } from "./togetherai-twin.js";
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const CHAT = { model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo', messages: [{ role: 'user', content: 'hi' }] };
+const PROBES = [
+    {
+        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[0]?.message?.role === 'assistant'
+            && typeof b.choices[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.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[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[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[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 = [
+    { 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 = 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 = [
+    { 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 = {}) {
+    const violations = [];
+    let checksRun = 0;
+    const fail = (check, detail) => 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, path, body) => 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?.error?.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.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;
+            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.choices[0].message.content !== decorated.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 = [];
+            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);
+            const hasRole = data.some((c) => c.choices?.[0]?.delta?.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 = [];
+            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);
+            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.choices?.[0];
+            if (choice?.finish_reason !== 'tool_calls')
+                fail('chat.tool_calls', 'finish_reason not tool_calls');
+            const calls = choice?.message?.tool_calls;
+            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)
+                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.choices?.[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 };
+}

package/dist/src/togetherai-connector.d.ts

@@ -0,0 +1,164 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { TogetheraiBudget, type TogetheraiBudgetOptions } from './togetherai-budget.js';
+/**
+ * The injected real-Together boundary. `request` issues ONE Together REST call:
+ *   method  — 'GET' | 'POST' | 'DELETE'
+ *   path    — e.g. '/v1/files' or '/v1/batches/batch_123/cancel'
+ *   body    — JSON body for POST (omitted otherwise)
+ * Returns the parsed JSON (an object, a `{ data }` list, or an `{ error }` envelope).
+ */
+export type TogetheraiExecute = (method: 'GET' | 'POST' | 'DELETE', path: string, body?: Record<string, unknown>) => Promise<{
+    data?: any;
+    error?: {
+        message?: string;
+        type?: string;
+    };
+    [k: string]: unknown;
+}>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveTogetheraiOptions = {
+    /** 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?: TogetheraiBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: TogetheraiBudgetOptions;
+};
+/**
+ * A live executor against the real Together REST API (the user's own API key). Sends the required
+ * `Authorization: Bearer` header. Never imported by the pack's own serve path — only constructed
+ * by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.together.xyz` 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 `TogetheraiBudgetError` instead of returning
+ * when the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `x-ratelimit-reset` / 429 signal becomes a persisted cooldown that makes every later call fail
+ * fast WITHOUT touching Together. 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 `togetherai-budget.ts` and the kernel header for the
+ * limits of the guarantee.
+ */
+export declare function liveTogetheraiExecute(apiKey: string, base?: string, opts?: LiveTogetheraiOptions): TogetheraiExecute;
+/** Map a real-Together ModelInfo object → a twin sync resource. */
+export declare function mapModel(m: Record<string, unknown>): SyncResource;
+/** Map a real-Together FileResponse object → a twin sync resource. */
+export declare function mapFile(f: Record<string, unknown>): SyncResource;
+/** Map a real-Together BatchJob object → a twin sync resource. */
+export declare function mapBatch(b: Record<string, unknown>): SyncResource;
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export declare function pullTogetheraiState(execute: TogetheraiExecute): Promise<SyncResource[]>;
+/**
+ * Pull from real Together and fold into the twin (mirror seeding).
+ *
+ * `occurredAt` has NO pinned default on purpose: the kernel hashes an observed event over
+ * (occurredAt + post-state), so under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the fold reports a phantom delta while the
+ * projection keeps the stale value (ADDING_A_TWIN.md §6). Callers pass a moving timestamp.
+ */
+export declare function syncTogetheraiFromReal(execute: TogetheraiExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** Why this action cannot be pushed, or null if it can. Pure — no vendor call on its path. */
+export declare function unpushableReason(op: string): string | null;
+/**
+ * Resolve the id the VENDOR knows this subject by.
+ *
+ * §9 ROUND TWO, BLOCKER (transcribed from the groq pack): a request builder that addresses the
+ * vendor straight from `action.subject.id` uses the twin's OWN mint for anything created locally.
+ * So a create's real id is written into the resource as `_external_id` at confirm time, and every
+ * later delete/cancel addresses the vendor by THAT. A locally-minted subject with no recorded
+ * external id is refused rather than guessed at.
+ */
+export declare function externalIdFor(subjectType: string, subjectId: string, root?: string): string | null;
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real Together REST
+ * surface:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export declare function togetheraiRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>, 
+/** The id the VENDOR knows this subject by. Required for anything but a create — see
+ *  `externalIdFor`; passing the twin's own mint would address a resource the vendor never had. */
+externalId?: string): {
+    method: 'GET' | 'POST' | 'DELETE';
+    path: string;
+};
+/** A push that must not go to the vendor (an unresolvable reference, a local id offered as a
+ *  vendor id). In the SWEEP it is caught and reported as a refusal — one bad action never aborts
+ *  the rest (the groq pack's §9 round one, finding 5); in PERFORM the head catches the throw and
+ *  records a failed receipt, which is exactly the entry-level answer a deploy wants. */
+export declare class PushRefusalError extends Error {
+}
+/**
+ * Push ONE pending action to REAL Together via the injected executor. Returns the real external
+ * id (the object id from the response; for a create that's a freshly minted id, otherwise it
+ * echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export declare function pushTogetheraiAction(execute: TogetheraiExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, opts?: {
+    externalId?: string;
+    root?: string;
+}): Promise<{
+    externalId: string;
+}>;
+/**
+ * Push the twin's PENDING local actions to real Together and CONFIRM each. Idempotency: a
+ * confirmed action is no longer pending, so a re-push enacts NOTHING.
+ *
+ * Every action this pack records is SINGLE-RESOURCE (one file, one batch), so confirming with
+ * `fields` alone is correct — see ADDING_A_TWIN.md §5 on compound actions, which this pack has
+ * none of. If a compound write is ever added here, it must ride its extra resources in
+ * `additionalObservations` or the push will silently delete them.
+ */
+export declare function pushPendingTogetheraiActions(execute: TogetheraiExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        reason: string;
+    }>;
+}>;
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to real
+ * Together 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.
+ */
+export declare function fullSyncTogetherai(execute: TogetheraiExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pushed: number;
+    observed: number;
+    deltasAppended: number;
+    collections: number;
+    refused: Array<{
+        actionId: string;
+        operation: string;
+        reason: string;
+    }>;
+}>;
+/** The pack's executor over the kernel's: the same Together call, carried by the head. */
+export declare function togetheraiExecuteOver(execute: RemoteExecute): TogetheraiExecute;
+/** The refresh adapter: pull the account's models/files/batches through the executor and fold. */
+export declare function syncTogetheraiFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<ReturnType<typeof syncTogetheraiFromReal>>;
+/** The perform adapter: one entry crosses to Together, or settles with the reason it never could.
+ *  Account-shaped writes (batches, files, fine-tunes) cross through `pushTogetheraiAction`; the
+ *  stub-only subjects (a chat completion, its record) are the twin's own record of a call already
+ *  answered — nothing at Together to write. */
+export declare function performTogetheraiAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;