@volter/twin-togetherai 0.1.0

package/src/togetherai-twin.ts

@@ -0,0 +1,1448 @@
+// Together AI twin REQUEST HANDLER — the canonical Together AI surface for the twin.
+// Contract: handleTogetheraiTwinRequest({method, path, body}) -> {status, body}. It is the
+// faithful Together AI API the real `together-ai` SDK (pointed at this baseURL) talks to
+// UNMODIFIED — with ONE documented exception: the SDK's `files.upload()` (its custom 302-redirect
+// upload) reads `TOGETHER_API_BASE_URL` at MODULE LOAD and ignores the client's `baseURL`
+// (together-ai@0.53.0 lib/upload.js:12), so it must be pointed at the twin explicitly with
+// `TOGETHER_API_BASE_URL=<twin>/v1` — unset, it egresses to https://api.together.xyz with the
+// caller's real key. Every other SDK call rides `baseURL` (or the injector's api.together.ai
+// interception) and needs nothing else.
+//
+// THE HONEST DESIGN: the twin cannot run the model, so `POST /v1/chat/completions` returns a
+// DETERMINISTIC STUB completion (togetherai-stub.ts) clearly labeled a twin stub — it NEVER
+// pretends to be real model output. `/v1/embeddings` returns DETERMINISTIC pseudo-vectors and
+// the audio endpoints return DETERMINISTIC labeled stubs. But the ENTIRE PROTOCOL ENVELOPE is
+// vendor-faithful: response shapes (including Together's REQUIRED `prompt` array and its `eos`
+// finish_reason), streaming SSE chunks with the nullable per-chunk `usage`/`warnings`,
+// tool_calls, and Together's OWN status table (402 spending limit, 403 context length, 503
+// engine overloaded). The genuinely stateful + static surface is real:
+//   • GET /v1/models                        — static catalog (togetherai-models.ts)
+//   • GET /v1/whoami                        — static identity for the presented key
+//   • POST /v1/files/upload + GET/DELETE /v1/files{,/:id,/content} — stateful (kernel action
+//     log), BOTH upload flows: the spec's multipart POST /v1/files/upload AND the together-ai
+//     SDK's own redirect dance
+//     (POST /v1/files?<params> → 302 + x-together-file-id → PUT the bytes).
+//     There is NO JSON create at POST /v1/files — the spec lists GET only there; a bodyless or
+//     JSON POST is a 400 naming the real doors.
+//   • POST/GET /v1/batches (+ cancel)       — stateful, Together-native shapes (201
+//     BatchJobWithWarning, bare-array list, `{error: string}` failures)
+//   • POST/GET/DELETE /v1/fine-tunes (+ cancel/events) — stateful, Together-native
+//
+// THE OPENAI-COMPATIBILITY LINE (docs.together.ai/docs/inference/openai-compatibility, read
+// 2026-09-16): Together's OpenAI-compatible surface is the INFERENCE endpoints only. Assistants/
+// Threads/Runs are NOT implemented; `moderations.create` is NOT implemented; OpenAI-shaped
+// Batch/Files/Fine-tuning APIs are NOT supported (Together ships its own native equivalents,
+// modeled here); `service_tier`/`store`/`metadata`/`prediction` are ACCEPTED BUT IGNORED. A twin
+// that served the OpenAI shapes on those stateful resources would be surface the vendor does not
+// have — the inverse false-green (ADDING_A_TWIN.md §6).
+//
+// State lives in the kernel action log (D1): all writes are local actions, reads are the
+// projection. No real Together API is ever called from this path (D4). Streaming uses an
+// INJECTED sink — no real sockets / setTimeout (D5 verify is offline + deterministic).
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import {
+  EMBEDDING_DIMENSIONS,
+  EMBEDDING_MODELS,
+  RERANK_MODELS,
+  SPEECH_MODELS,
+  TOGETHERAI_MODELS,
+  findModel,
+} from './togetherai-models.ts';
+import {
+  buildUsage,
+  contentToText,
+  countPromptTokens,
+  estimateTokens,
+  fnv1a,
+  pseudoEmbedding,
+  stubAssistantText,
+  stubAudioSeconds,
+  stubJsonObject,
+  stubReasoningText,
+  stubToolCall,
+  stubTranscript,
+} from './togetherai-stub.ts';
+import { type TogetheraiScenarioEngine, type TogetheraiScenarioRespond, realizeTogetheraiRespond, type ScriptedResult } from './togetherai-scenario.ts';
+import type {
+  TogetheraiAssistantMessage,
+  TogetheraiBatch,
+  TogetheraiBatchEndpoint,
+  TogetheraiBatchStatus,
+  TogetheraiChatCompletion,
+  TogetheraiChoice,
+  TogetheraiEmbedding,
+  TogetheraiEmbeddingResponse,
+  TogetheraiError,
+  TogetheraiFile,
+  TogetheraiFilePurpose,
+  TogetheraiFileType,
+  TogetheraiFinishReason,
+  TogetheraiMessageParam,
+  TogetheraiModel,
+  TogetheraiRerankResponse,
+  TogetheraiToolCall,
+  TogetheraiUsage,
+  SseSink,
+} from './togetherai-types.ts';
+
+const SERVICE = 'togetherai';
+
+/** The ONE base path Together's inference API serves. Everything the twin routes hangs off this. */
+export const TOGETHERAI_API_PREFIX = '/v1';
+
+export type TogetheraiRequest = {
+  /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts chat turns. */
+  scenarioEngine?: TogetheraiScenarioEngine;
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The credential the caller presents (the SDK's bearer `Authorization` header). When a request
+   *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the real
+   *  vendor rule: a credential is required → 401 on missing/invalid. In-process trusted calls
+   *  (capability verify, connector) omit BOTH and are not auth-gated. */
+  apiKey?: string;
+  /** Lower-cased request headers the HTTP server passes through so the handler can model auth
+   *  (401) and the deterministic fault triggers (429 / 402 / 503). */
+  headers?: Record<string, string>;
+  /** When set on a streaming POST, chunks are written here (no sockets). */
+  sseSink?: SseSink;
+};
+
+/** The handler response. `headers` (when present) are response headers the HTTP server should set
+ *  — e.g. `x-ratelimit-reset` on a modeled 429, or the redirect pair on the SDK's upload flow. */
+export type TogetheraiResponseEnvelope = { status: number; body: unknown; headers?: Record<string, string> };
+
+// ── vendor-shaped errors ──────────────────────────────────────────────────────────────
+/**
+ * Together's error envelope (`ErrorData`): `{ error: { message, type, param, code } }` with
+ * `message` + `type` REQUIRED and `param`/`code` nullable with default null. The twin emits all
+ * four keys so the served shape matches the vendor's REQUIRED+DEFAULT shape exactly.
+ */
+function errBody(type: string, message: string, param: string | null = null, code: string | null = null): TogetheraiError {
+  return { error: { message, type, param, code } };
+}
+function invalidRequest(message: string): TogetheraiResponseEnvelope {
+  return { status: 400, body: errBody('invalid_request_error', message) };
+}
+function notFound(message: string): TogetheraiResponseEnvelope {
+  return { status: 404, body: errBody('invalid_request_error', message) };
+}
+function authError(message: string): TogetheraiResponseEnvelope {
+  return { status: 401, body: errBody('invalid_request_error', message) };
+}
+/** Together's 403 is NOT a permission denial — docs.together.ai/docs/error-codes: 403 means
+ *  "the sum of input tokens plus max_tokens exceeds the context length of the model". */
+function contextLengthError(model: string, needed: number, limit: number): TogetheraiResponseEnvelope {
+  return {
+    status: 403,
+    body: errBody('invalid_request_error', `This model's maximum context length is ${limit} tokens. However, you requested ${needed} tokens (${needed - limit} in the messages, Please reduce the length of the messages or max_tokens.`),
+  };
+}
+
+// ── modeled authentication (401) ────────────────────────────────────────────────────────
+// Real Together requires a bearer credential on every request and returns 401 when it is missing
+// or invalid (docs.together.ai/docs/error-codes: 401 = "A missing or invalid API key"). The twin
+// can't validate against real keys, so it models the CHECKABLE failures: a missing credential,
+// and a reserved sentinel for the invalid-key path. Any other non-empty key is accepted. Trusted
+// in-process calls carry NEITHER `headers` nor `apiKey` and are NOT auth-gated; both official
+// clients always send a key → they pass.
+function checkAuth(req: TogetheraiRequest): TogetheraiResponseEnvelope | null {
+  const auth = req.headers?.['authorization'];
+  const bearer = typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : '';
+  const key = (req.apiKey ?? '').trim() || bearer;
+  if (!key) return authError('Missing or invalid API Key');
+  if (key === 'twin_invalid' || key === 'invalid') return authError('Missing or invalid API Key');
+  return null;
+}
+
+// ── modeled rate limiting (429), spending limit (402), overload (503) ───────────────────
+// All three are non-deterministic in production, so the twin exposes DETERMINISTIC opt-in
+// triggers. Together's documented behaviors (docs.together.ai/docs/error-codes +
+// /docs/serverless/rate-limits, read 2026-09-16):
+//   • 429 — serverless rate limit exceeded; error types `dynamic_request_limited` /
+//     `dynamic_token_limited`; carries `x-ratelimit-reset` (seconds until reset). Success
+//     responses carry NO rate-limit headers.
+//   • 402 — the account hit its monthly spending limit ("Payment Required").
+//   • 503 — "Engine Overloaded: servers are under heavy traffic".
+function rateLimitError(kind: 'dynamic_request_limited' | 'dynamic_token_limited' = 'dynamic_request_limited'): TogetheraiResponseEnvelope {
+  return {
+    status: 429,
+    body: errBody(kind, 'Rate limit exceeded: dynamic request limit reached for this model. Please retry after the reset window.'),
+    headers: { 'x-ratelimit-reset': '60' },
+  };
+}
+function spendingLimitError(): TogetheraiResponseEnvelope {
+  return { status: 402, body: errBody('insufficient_quota', 'The account associated with the API key has reached its maximum allowed monthly spending limit.') };
+}
+function engineOverloadedError(): TogetheraiResponseEnvelope {
+  return { status: 503, body: errBody('engine_overloaded', 'Engine overloaded: servers are under heavy traffic. Please retry after a short wait.') };
+}
+function triggered(req: TogetheraiRequest, header: string): boolean {
+  const v = req.headers?.[header];
+  return v === '1' || v === 'true';
+}
+
+function nowEpoch(occurredAt?: string): number {
+  return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+/**
+ * Mint the next local id for `type`. Derived from the ID SET ALREADY IN STATE (a scan of the
+ * projection), never a row count — a count-mint silently clobbers a pulled vendor id sitting in a
+ * gap above the count (ADDING_A-TWIN.md §5). Two further properties matter:
+ *   • the `_twin_` infix namespaces LOCAL mints, so a pulled Together id can never be matched by
+ *     this regex and therefore can never be re-minted;
+ *   • the scan includes TOMBSTONED rows (a soft-deleted file keeps its projection row), so the
+ *     counter RATCHETS across delete→recreate and a deleted id is never handed out twice.
+ */
+function nextId(type: string, prefix: string, root?: string): string {
+  let max = 0;
+  for (const r of rows(type, root)) {
+    const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(String(r.id));
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `${prefix}_twin_${max + 1}`;
+}
+/** Models observed by a connector pull (mapModel), reshaped into the served model object. */
+function pulledModels(root?: string): TogetheraiModel[] {
+  return rows('model', root)
+    .filter((r) => !r._deleted)
+    .map((r) => ({ id: String(r.id), object: 'model', created: Number(r.created ?? 0), type: (r.type as TogetheraiModel['type']) ?? 'language' }));
+}
+/** The catalog a request sees: the static table, with any PULLED row of the same id OVERRIDING it
+ *  (the groq pack's §9-round-two lesson: a pulled row must stay served, not shadowed). */
+function servedModels(root?: string): TogetheraiModel[] {
+  const pulled = pulledModels(root);
+  const byId = new Map<string, TogetheraiModel>();
+  for (const m of TOGETHERAI_MODELS) byId.set(m.id, m);
+  for (const m of pulled) byId.set(m.id, m);
+  return [...byId.values()];
+}
+function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+/** Strip the kernel's housekeeping fields and the twin's private underscore-prefixed fields. */
+function strip(r: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(r)) {
+    if (k === 'type' || k === 'updatedAt' || k.startsWith('_')) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// ── request parsing ─────────────────────────────────────────────────────────────────────
+function parseJson(body?: string): Record<string, unknown> {
+  if (!body || !body.trim()) return {};
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+// ── chat completions: validate the request the way Together does ────────────────────────
+type ToolChoice = 'auto' | 'none' | 'required' | { name: string };
+type ResponseFormat = { kind: 'text' } | { kind: 'json_object' } | { kind: 'json_schema'; schema: unknown };
+
+/** Together's `ChatCompletionRequest.context_length_exceeded_behavior` — a CLOSED documented
+ *  enum with default `error`. */
+const CONTEXT_LENGTH_BEHAVIORS = ['truncate', 'error'] as const;
+type ContextLengthBehavior = (typeof CONTEXT_LENGTH_BEHAVIORS)[number];
+/** Together's `reasoning_effort` — a CLOSED documented enum. */
+const REASONING_EFFORTS = ['low', 'medium', 'high'] as const;
+type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+type ChatArgs = {
+  model: string;
+  messages: TogetheraiMessageParam[];
+  tools?: unknown;
+  n: number;
+  maxTokens?: number;
+  stop?: string[];
+  stream: boolean;
+  toolChoice?: ToolChoice;
+  parallelToolCalls: boolean;
+  legacyFunctions: boolean;
+  responseFormat: ResponseFormat;
+  seed?: number;
+  echo: boolean;
+  logprobs?: number;
+  reasoningEffort?: ReasoningEffort;
+  contextBehavior: ContextLengthBehavior;
+};
+
+function validateChat(params: Record<string, unknown>): { args: ChatArgs } | { error: TogetheraiResponseEnvelope } {
+  if (params.model === undefined || params.model === '') return { error: invalidRequest("'model' is a required property") };
+  if (typeof params.model !== 'string') return { error: invalidRequest("'model' must be a string") };
+  if (!Array.isArray(params.messages)) return { error: invalidRequest("'messages' is a required property") };
+  if (params.messages.length === 0) return { error: invalidRequest("[] is too short - 'messages'") };
+  const messages = params.messages as TogetheraiMessageParam[];
+  for (const m of messages) {
+    if (!m || typeof m !== 'object' || typeof m.role !== 'string') {
+      return { error: invalidRequest("each message must have a valid 'role'") };
+    }
+  }
+  // Together's audio/embedding/rerank/image models are not chat models — asking one to chat is
+  // a 404 (Together's docs: 404 = "An invalid endpoint URL or model name"), not a stub. A model
+  // id the catalog does not know AT ALL (an OpenAI-style flat id like `gpt-4o`) is the same 404:
+  // Together serves only its slash-namespaced catalog.
+  if (EMBEDDING_MODELS.has(params.model) || RERANK_MODELS.has(params.model) || SPEECH_MODELS.has(params.model)
+    || !findModel(params.model) || findModel(params.model)?.type === 'image') {
+    return { error: notFound(`Model ${params.model} does not exist or is not a chat model.`) };
+  }
+  // `n`: Together's schema pins minimum 1, maximum 128 — an OpenAI-compatible freedom Groq does
+  // not have. A number outside the documented range is a 400.
+  if (params.n !== undefined && params.n !== null) {
+    if (typeof params.n !== 'number' || !Number.isInteger(params.n) || params.n < 1 || params.n > 128) {
+      return { error: invalidRequest("'n' must be an integer between 1 and 128") };
+    }
+  }
+  // `logprobs` is an INTEGER 0–20 on Together (OpenAI's boolean; Groq 400s the field outright).
+  if (params.logprobs !== undefined && params.logprobs !== null) {
+    if (typeof params.logprobs !== 'number' || !Number.isInteger(params.logprobs) || params.logprobs < 0 || params.logprobs > 20) {
+      return { error: invalidRequest("'logprobs' must be an integer between 0 and 20") };
+    }
+  }
+  // `context_length_exceeded_behavior` — a CLOSED documented enum, default 'error'.
+  let contextBehavior: ContextLengthBehavior = 'error';
+  if (params.context_length_exceeded_behavior !== undefined && params.context_length_exceeded_behavior !== null) {
+    if (typeof params.context_length_exceeded_behavior !== 'string' || !CONTEXT_LENGTH_BEHAVIORS.includes(params.context_length_exceeded_behavior as ContextLengthBehavior)) {
+      return { error: invalidRequest(`'context_length_exceeded_behavior' must be one of ${CONTEXT_LENGTH_BEHAVIORS.map((t) => `'${t}'`).join(', ')}`) };
+    }
+    contextBehavior = params.context_length_exceeded_behavior as ContextLengthBehavior;
+  }
+  // `reasoning_effort` — a CLOSED documented enum.
+  let reasoningEffort: ReasoningEffort | undefined;
+  if (params.reasoning_effort !== undefined && params.reasoning_effort !== null) {
+    if (typeof params.reasoning_effort !== 'string' || !REASONING_EFFORTS.includes(params.reasoning_effort as ReasoningEffort)) {
+      return { error: invalidRequest(`'reasoning_effort' must be one of ${REASONING_EFFORTS.map((t) => `'${t}'`).join(', ')}`) };
+    }
+    reasoningEffort = params.reasoning_effort as ReasoningEffort;
+  }
+  // `compliance` is a CONST ('hipaa') on Together's schema — any other value is not surface.
+  if (params.compliance !== undefined && params.compliance !== null && params.compliance !== 'hipaa') {
+    return { error: invalidRequest("'compliance' must be 'hipaa'") };
+  }
+  // `response_format`: text | json_object | json_schema. Together's ResponseFormatJsonSchema
+  // REQUIRES `json_schema.name` (a-z A-Z 0-9 underscore/dash, ≤64) — an omission Together's
+  // Structured Outputs documents as invalid.
+  let responseFormat: ResponseFormat = { kind: 'text' };
+  const rf = params.response_format as { type?: unknown; json_schema?: { name?: unknown; schema?: unknown } } | undefined;
+  if (rf && typeof rf === 'object') {
+    if (rf.type === 'json_object') responseFormat = { kind: 'json_object' };
+    else if (rf.type === 'json_schema') {
+      const name = rf.json_schema?.name;
+      if (typeof name !== 'string' || !name) return { error: invalidRequest("'response_format.json_schema.name' is a required property") };
+      if (name.length > 64 || !/^[a-zA-Z0-9_-]+$/.test(name)) {
+        return { error: invalidRequest("'response_format.json_schema.name' must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64") };
+      }
+      responseFormat = { kind: 'json_schema', schema: rf.json_schema };
+    } else if (rf.type !== undefined && rf.type !== 'text') {
+      return { error: invalidRequest("'response_format.type' must be one of 'text', 'json_object', 'json_schema'") };
+    }
+  }
+  let toolChoice: ToolChoice | undefined;
+  const tcRaw = params.tool_choice;
+  if (tcRaw !== undefined && tcRaw !== null) {
+    if (typeof tcRaw === 'string') {
+      if (!['auto', 'none', 'required'].includes(tcRaw)) return { error: invalidRequest("'tool_choice' must be one of 'none', 'auto', 'required' or a named function") };
+      toolChoice = tcRaw as ToolChoice;
+    } else if (typeof tcRaw === 'object') {
+      const name = (tcRaw as { function?: { name?: unknown } }).function?.name;
+      if (typeof name !== 'string' || !name) return { error: invalidRequest("'tool_choice.function.name' is required for a named tool choice") };
+      toolChoice = { name };
+    }
+  }
+  const maxRaw = params.max_tokens;
+  let maxTokens: number | undefined;
+  if (maxRaw !== undefined && maxRaw !== null) {
+    maxTokens = Number(maxRaw);
+    if (!Number.isInteger(maxTokens) || maxTokens < 1) return { error: invalidRequest("'max_tokens' must be an integer >= 1") };
+  }
+  let stop: string[] | undefined;
+  if (params.stop !== undefined && params.stop !== null) {
+    if (typeof params.stop === 'string') stop = [params.stop];
+    else if (Array.isArray(params.stop)) stop = params.stop as string[];
+    else return { error: invalidRequest("'stop' must be a string or an array of strings") };
+  }
+  return {
+    args: {
+      model: params.model,
+      messages,
+      ...(params.tools !== undefined ? { tools: params.tools } : (params.functions !== undefined ? { tools: params.functions } : {})),
+      // The DEPRECATED `functions` request parameter has a deprecated RESPONSE shape too:
+      // Together's ChatCompletionMessage carries `function_call` (not `tool_calls`) and
+      // `FinishReason` includes 'function_call'.
+      legacyFunctions: params.tools === undefined && params.functions !== undefined,
+      n: typeof params.n === 'number' ? params.n : 1,
+      ...(maxTokens !== undefined ? { maxTokens } : {}),
+      ...(stop !== undefined ? { stop } : {}),
+      stream: params.stream === true,
+      ...(toolChoice !== undefined ? { toolChoice } : {}),
+      parallelToolCalls: params.parallel_tool_calls !== false,
+      responseFormat,
+      ...(typeof params.seed === 'number' ? { seed: params.seed } : {}),
+      echo: params.echo === true,
+      ...(typeof params.logprobs === 'number' ? { logprobs: params.logprobs } : {}),
+      ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+      contextBehavior,
+    },
+  };
+}
+
+/** Build ONE deterministic stub choice (index `idx`). */
+function buildChoice(args: ChatArgs, idx: number): { choice: TogetheraiChoice; completionTokens: number } {
+  const hasTools = Array.isArray(args.tools) && args.tools.length > 0;
+  const forbidTools = args.toolChoice === 'none';
+  const forcedName = typeof args.toolChoice === 'object' ? args.toolChoice.name : undefined;
+  if (hasTools && !forbidTools) {
+    const list = args.tools as unknown[];
+    const calls: TogetheraiToolCall[] = [];
+    if (forcedName || args.parallelToolCalls === false) {
+      const tc = stubToolCall(args.tools, idx + 1, forcedName);
+      if (tc) calls.push(tc);
+    } else {
+      for (let t = 0; t < list.length; t++) {
+        const tc = stubToolCall([list[t]], idx * 100 + t + 1);
+        if (tc) calls.push(tc);
+      }
+    }
+    if (calls.length) {
+      if (args.legacyFunctions) {
+        const fc = calls[0]!.function;
+        return {
+          choice: { index: idx, message: { role: 'assistant', content: null, function_call: { name: fc.name, arguments: fc.arguments } }, finish_reason: 'function_call' },
+          completionTokens: estimateTokens(JSON.stringify(fc)),
+        };
+      }
+      return {
+        choice: { index: idx, message: { role: 'assistant', content: null, tool_calls: calls }, finish_reason: 'tool_calls' },
+        completionTokens: estimateTokens(JSON.stringify(calls)),
+      };
+    }
+  }
+  let text = args.responseFormat.kind === 'json_object'
+    ? stubJsonObject(args.messages, args.model)
+    : args.responseFormat.kind === 'json_schema'
+      ? stubJsonObject(args.messages, args.model, args.responseFormat.schema)
+      : stubAssistantText(args.messages, args.model);
+  let finish: TogetheraiFinishReason = 'stop';
+  // Truncate at the EARLIEST-occurring stop sequence across the whole `stop` list.
+  let stopAt = -1;
+  for (const s of args.stop ?? []) {
+    if (!s) continue;
+    const i = text.indexOf(s);
+    if (i >= 0 && (stopAt < 0 || i < stopAt)) stopAt = i;
+  }
+  if (stopAt >= 0) text = text.slice(0, stopAt);
+  if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+    text = text.slice(0, args.maxTokens * 4);
+    finish = 'length';
+  }
+  const message: TogetheraiAssistantMessage = { role: 'assistant', content: text };
+  // `reasoning_effort` present → Together's reasoning models surface the reasoning on the
+  // assistant message's own `reasoning` field (varies by model; the stub always populates it
+  // when effort is requested so the field's presence is observable).
+  if (args.reasoningEffort !== undefined) message.reasoning = stubReasoningText(args.messages, args.model);
+  return {
+    choice: { index: idx, message, finish_reason: finish },
+    completionTokens: estimateTokens(String(message.content ?? '')) + estimateTokens(message.reasoning ?? ''),
+  };
+}
+
+/** A deterministic id suffix from the request (so ids are stable + assertable). */
+function stableSuffix(args: ChatArgs): string {
+  const s = JSON.stringify(args.messages) + args.model + (args.seed !== undefined ? `|seed=${args.seed}` : '');
+  return fnv1a(s).toString(36);
+}
+
+export function buildChatCompletion(args: ChatArgs, occurredAt?: string, scenarioEngine?: TogetheraiScenarioEngine): TogetheraiChatCompletion | TogetheraiResponseEnvelope {
+  // THE 403: Together's documented context-length refusal. Input tokens + max_tokens beyond the
+  // model's context length answers 403 (NOT 400, NOT 413) — unless
+  // `context_length_exceeded_behavior:'truncate'` overrides max_tokens down to the window.
+  const info = findModel(args.model);
+  const promptTokens = countPromptTokens(args.messages);
+  if (info?.context_length && info.context_length > 0) {
+    const needed = promptTokens + (args.maxTokens ?? 0);
+    if (needed > info.context_length) {
+      if (args.contextBehavior === 'truncate') {
+        args = { ...args, maxTokens: Math.max(1, info.context_length - promptTokens) };
+      } else {
+        return contextLengthError(args.model, needed, info.context_length);
+      }
+    }
+  }
+  let scripted: ScriptedResult | null = null;
+  let missTeach = '';
+  if (scenarioEngine) {
+    const decision = scenarioEngine.next({ model: args.model, messages: args.messages, tools: args.tools, reasoningEffort: args.reasoningEffort });
+    if (decision.kind === 'handler') {
+      const respond = decision.respond as TogetheraiScenarioRespond;
+      // A scripted FAILURE short-circuits into Together's own error envelope + status.
+      if (respond.error) return scriptedError(respond.error);
+      scripted = realizeTogetheraiRespond(respond);
+    } else {
+      missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/togetherai.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
+    }
+  }
+  const choices: TogetheraiChoice[] = [];
+  let completionTokens = 0;
+  for (let i = 0; i < args.n; i++) {
+    if (scripted) {
+      const message: TogetheraiAssistantMessage = scripted.toolCalls.length
+        ? { role: 'assistant', content: scripted.text, tool_calls: scripted.toolCalls }
+        : { role: 'assistant', content: scripted.text ?? '' };
+      if (scripted.reasoning !== null) message.reasoning = scripted.reasoning;
+      choices.push({ index: i, message, finish_reason: scripted.finishReason });
+      completionTokens += estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? ''));
+      continue;
+    }
+    const { choice, completionTokens: ct } = buildChoice(args, i);
+    if (missTeach && typeof choice.message?.content === 'string') choice.message.content += missTeach;
+    choices.push(choice);
+    completionTokens += ct;
+  }
+  const usage: TogetheraiUsage = buildUsage(promptTokens, completionTokens);
+  const id = `chatcmpl-twin-${stableSuffix(args)}`;
+  // Together's REQUIRED `prompt` array: the echoed prompt when `echo:true` (the vendor's schema
+  // documents it as "When echo is true, the prompt is included in the response"). REQUIRED on
+  // the schema, so it is served even when empty.
+  const prompt = args.echo ? [{ text: args.messages.map((m) => contentToText(m.content)).join('\n') }] : [];
+  return {
+    id,
+    object: 'chat.completion',
+    created: nowEpoch(occurredAt),
+    model: args.model,
+    choices,
+    prompt,
+    usage,
+  };
+}
+
+/** Map a scripted scenario failure onto Together's real status + envelope. */
+function scriptedError(err: NonNullable<TogetheraiScenarioRespond['error']>): TogetheraiResponseEnvelope {
+  if (err.type === 'rate_limit_exceeded') {
+    const base = rateLimitError();
+    return err.message ? { ...base, body: errBody('dynamic_request_limited', err.message) } : base;
+  }
+  if (err.type === 'engine_overloaded') {
+    const base = engineOverloadedError();
+    return err.message ? { ...base, body: errBody('engine_overloaded', err.message) } : base;
+  }
+  return { status: 500, body: errBody('internal_server_error', err.message ?? 'Internal Server Error') };
+}
+
+const isEnvelope = (v: TogetheraiChatCompletion | TogetheraiResponseEnvelope): v is TogetheraiResponseEnvelope =>
+  typeof (v as TogetheraiResponseEnvelope).status === 'number' && 'body' in v;
+
+/** Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order. */
+function chunkText(text: string): string[] {
+  if (!text) return [];
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += 20) out.push(text.slice(i, i + 20));
+  return out;
+}
+
+/**
+ * Emit the vendor-faithful Together streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). Together's order: a first chunk with `delta:{role:'assistant'}`, then
+ * `delta:{content}` chunks (or tool_calls deltas), then a chunk carrying `finish_reason`. 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). Ends with
+ * `data: [DONE]`. Deterministic + synchronous.
+ */
+export function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, scenarioEngine?: TogetheraiScenarioEngine): TogetheraiChatCompletion | TogetheraiResponseEnvelope {
+  const built = buildChatCompletion(args, occurredAt, scenarioEngine);
+  if (isEnvelope(built)) return built;
+  const full = built;
+  const base = { id: full.id, object: 'chat.completion.chunk' as const, created: full.created, model: full.model };
+  for (const choice of full.choices) {
+    const idx = choice.index;
+    sink({ data: { ...base, choices: [{ index: idx, delta: { role: 'assistant', content: '' }, finish_reason: null }], usage: null, warnings: [] } });
+    if (choice.message?.reasoning) {
+      sink({ data: { ...base, choices: [{ index: idx, delta: { reasoning: choice.message.reasoning }, finish_reason: null }], usage: null, warnings: [] } });
+    }
+    if (choice.message?.tool_calls && choice.message.tool_calls.length) {
+      choice.message.tool_calls.forEach((tc, tIdx) => {
+        sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, id: tc.id, type: 'function', function: { name: tc.function.name, arguments: '' } }] }, finish_reason: null }], usage: null, warnings: [] } });
+        sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, function: { arguments: tc.function.arguments } }] }, finish_reason: null }], usage: null, warnings: [] } });
+      });
+    } else {
+      for (const piece of chunkText(choice.message?.content ?? '')) {
+        sink({ data: { ...base, choices: [{ index: idx, delta: { content: piece }, finish_reason: null }], usage: null, warnings: [] } });
+      }
+    }
+    sink({ data: { ...base, choices: [{ index: idx, delta: {}, finish_reason: choice.finish_reason }], usage: null, warnings: [] } });
+  }
+  // Together carries usage on the chunks themselves; the FINAL chunk reports the real counts.
+  sink({ data: { ...base, choices: [], usage: full.usage, warnings: [] } });
+  sink({ done: true });
+  return full;
+}
+
+// ── Embeddings (deterministic pseudo-vectors) ───────────────────────────────────────────
+function handleEmbeddings(params: Record<string, unknown>): TogetheraiResponseEnvelope {
+  if (params.model === undefined || typeof params.model !== 'string' || !params.model) return invalidRequest("'model' is a required property");
+  if (params.input === undefined) return invalidRequest("'input' is a required property");
+  const model = params.model;
+  if (!EMBEDDING_MODELS.has(model)) return notFound(`Model ${model} does not exist or is not an embedding model.`);
+  const inputs = Array.isArray(params.input) ? (params.input as unknown[]).map(String) : [String(params.input)];
+  if (inputs.some((s) => s.length === 0)) return invalidRequest("'input' must not be an empty string");
+  const dims = EMBEDDING_DIMENSIONS[model] ?? 768;
+  const data: TogetheraiEmbedding[] = inputs.map((text, index) => {
+    const vec = pseudoEmbedding(text, dims);
+    return { object: 'embedding', index, embedding: vec };
+  });
+  // Together's EmbeddingsResponse REQUIRED keys are object/model/data — NO usage key on the
+  // schema (Together does not document one on this endpoint).
+  const body: TogetheraiEmbeddingResponse = { object: 'list', model, data };
+  return { status: 200, body };
+}
+
+// ── Rerank (Together-native) ────────────────────────────────────────────────────────────
+/**
+ * Deterministic rerank: score each document by a pure function of (query, document text) so the
+ * ORDER is stable and assertable, then return the top `top_n` with Together's
+ * `{object:'rerank', model, results:[{index, relevance_score, document}]}` shape. NOT a real
+ * ranker — the values carry no semantic meaning; only the SHAPE and DETERMINISM are faithful.
+ */
+function handleRerank(params: Record<string, unknown>): TogetheraiResponseEnvelope {
+  if (params.model === undefined || typeof params.model !== 'string' || !params.model) return invalidRequest("'model' is a required property");
+  if (!RERANK_MODELS.has(params.model)) return notFound(`Model ${params.model} does not exist or is not a rerank model.`);
+  if (typeof params.query !== 'string' || !params.query) return invalidRequest("'query' is a required property");
+  if (!Array.isArray(params.documents)) return invalidRequest("'documents' is a required property");
+  if (params.documents.length === 0) return invalidRequest("'documents' must not be empty");
+  // Documents may be strings OR objects (Together's oneOf); an object is ranked by its text-ish
+  // fields (`rank_fields` names the keys, defaulting to all of them).
+  const rankFields = Array.isArray(params.rank_fields) ? (params.rank_fields as unknown[]).map(String) : null;
+  const textOf = (doc: unknown): string => {
+    if (typeof doc === 'string') return doc;
+    if (doc && typeof doc === 'object') {
+      const o = doc as Record<string, unknown>;
+      const keys = rankFields ?? Object.keys(o);
+      return keys.map((k) => String(o[k] ?? '')).join(' ');
+    }
+    return String(doc ?? '');
+  };
+  const query = params.query as string;
+  const scored = (params.documents as unknown[]).map((doc, index) => {
+    const text = textOf(doc);
+    // A deterministic pseudo-score in (0,1): hash(query + text) — same inputs, same order.
+    const score = (fnv1a(`${query}\0${text}`) % 10_000) / 10_000;
+    return { index, score, doc };
+  });
+  scored.sort((a, b) => b.score - a.score || a.index - b.index);
+  const topN = typeof params.top_n === 'number' && Number.isInteger(params.top_n) && params.top_n > 0 ? params.top_n : scored.length;
+  const returnDocuments = params.return_documents === undefined ? true : params.return_documents === true;
+  const usageTokens = countPromptTokens([{ role: 'user', content: query }, ...((params.documents as unknown[]).map((d) => ({ role: 'user' as const, content: textOf(d) })))]);
+  const body: TogetheraiRerankResponse = {
+    object: 'rerank',
+    id: `rrank-twin-${fnv1a(`${query}|${JSON.stringify(params.documents)}`).toString(36)}`,
+    model: params.model,
+    results: scored.slice(0, topN).map((s) => ({
+      index: s.index,
+      relevance_score: s.score,
+      ...(returnDocuments ? { document: { text: typeof s.doc === 'string' ? s.doc : JSON.stringify(s.doc) } } : {}),
+    })),
+    usage: buildUsage(usageTokens, 0),
+  };
+  return { status: 200, body };
+}
+
+// ── Images (deterministic stub) ─────────────────────────────────────────────────────────
+function handleImages(params: Record<string, unknown>): TogetheraiResponseEnvelope {
+  if (typeof params.prompt !== 'string' || !params.prompt) return invalidRequest("'prompt' is a required property");
+  if (params.model === undefined || typeof params.model !== 'string' || !params.model) return invalidRequest("'model' is a required property");
+  if (findModel(params.model)?.type !== 'image') return notFound(`Model ${params.model} does not exist or is not an image model.`);
+  // The SDK documents the default as `jpeg` ("Defaults to `jpeg`", images.d.ts:80) — NOT png.
+  const format = params.output_format === undefined ? 'jpeg' : params.output_format;
+  if (format !== 'jpeg' && format !== 'png') return invalidRequest("'output_format' must be one of 'jpeg', 'png'");
+  const responseFormat = params.response_format === undefined ? 'url' : params.response_format;
+  // Together's enum is 'base64' | 'url' (together-ai@0.53.0 images.d.ts:95) — NOT OpenAI's
+  // 'b64_json'. Serving OpenAI's value here would be exactly the shape contamination the pack
+  // refuses elsewhere (the OpenAI-compatibility line: Together's image API is its own).
+  if (responseFormat !== 'url' && responseFormat !== 'base64') return invalidRequest("'response_format' must be one of 'url', 'base64'");
+  const n = params.n === undefined ? 1 : params.n;
+  if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) return invalidRequest("'n' must be a positive integer");
+  const steps = params.steps === undefined ? 20 : params.steps;
+  if (typeof steps !== 'number' || !Number.isInteger(steps) || steps < 1) return invalidRequest("'steps' must be a positive integer");
+  // No diffusion here: each image is a labeled stub — a data: URL carrying the deterministic
+  // marker (so `type:'url'` still carries retrievable bytes) or a base64 body.
+  const marker = fnv1a(`${params.prompt}|${params.model}|${params.seed ?? ''}`);
+  const data = Array.from({ length: n }, (_, index) => {
+    // The format is named IN the label so the (documented) default is observable on the wire.
+    const stub = `[twin-stub:${params.model}] deterministic ${format} image stub (no diffusion is run) for prompt "${String(params.prompt).slice(0, 80)}" #${index} (${marker.toString(36)})`;
+    if (responseFormat === 'base64') return { index, b64_json: Buffer.from(stub).toString('base64'), type: 'b64_json' as const };
+    return { index, url: `data:text/plain;base64,${Buffer.from(stub).toString('base64')}`, type: 'url' as const };
+  });
+  return {
+    status: 200,
+    body: { id: `img-twin-${marker.toString(36)}`, model: params.model, object: 'list', data },
+  };
+}
+
+// ── Audio (deterministic labeled stubs stand in for acoustic model output) ──────────────
+const TRANSCRIPTION_FORMATS = new Set(['json', 'text', 'verbose_json']);
+
+function handleTranscription(params: Record<string, unknown>, translate: boolean): TogetheraiResponseEnvelope {
+  const model = params.model;
+  if (typeof model !== 'string' || !model) return invalidRequest("'model' is a required property");
+  if (findModel(model)?.type !== 'language' || !SPEECH_MODELS.has(model)) return notFound(`Model ${model} does not exist or is not an audio model.`);
+  // "Either a file or a URL must be provided" (together-ai TranscriptionCreateParams).
+  const source = typeof params.file === 'string' && params.file ? params.file : (typeof params.url === 'string' && params.url ? params.url : '');
+  if (!source) return invalidRequest("Either 'file' or 'url' must be provided");
+  const format = params.response_format === undefined ? 'json' : params.response_format;
+  if (typeof format !== 'string' || !TRANSCRIPTION_FORMATS.has(format)) {
+    return invalidRequest(`'response_format' must be one of ${[...TRANSCRIPTION_FORMATS].map((f) => `'${f}'`).join(', ')}`);
+  }
+  const text = stubTranscript(model, source, translate);
+  // `response_format:'text'` returns the bare transcript as plain text, not a JSON envelope.
+  if (format === 'text') return { status: 200, body: text, headers: { 'content-type': 'text/plain; charset=utf-8' } };
+  if (format === 'json') return { status: 200, body: { text } };
+  const duration = stubAudioSeconds(source);
+  return {
+    status: 200,
+    body: {
+      task: translate ? 'translate' : 'transcribe',
+      language: 'english',
+      duration,
+      text,
+      segments: [{ id: 0, seek: 0, start: 0, end: duration, text, tokens: [], temperature: Number(params.temperature ?? 0), avg_logprob: -0.25, compression_ratio: 1.2, no_speech_prob: 0.01 }],
+    },
+  };
+}
+
+function handleSpeech(params: Record<string, unknown>): TogetheraiResponseEnvelope {
+  const model = params.model;
+  if (typeof model !== 'string' || !model) return invalidRequest("'model' is a required property");
+  if (!SPEECH_MODELS.has(model)) return notFound(`Model ${model} does not exist or is not a speech model.`);
+  if (typeof params.input !== 'string' || !params.input) return invalidRequest("'input' is a required property");
+  if (typeof params.voice !== 'string' || !params.voice) return invalidRequest("'voice' is a required property");
+  const format = params.response_format === undefined ? 'mp3' : params.response_format;
+  if (typeof format !== 'string' || !['mp3', 'wav', 'opus', 'flac'].includes(format)) {
+    return invalidRequest("'response_format' must be one of 'mp3', 'wav', 'opus', 'flac'");
+  }
+  // No vocoder here: the body is a clearly-labeled deterministic stub, and the server serves it
+  // with the audio content-type the vendor would use.
+  return {
+    status: 200,
+    body: `[twin-stub:${model}] no real speech synthesis — voice=${params.voice} format=${format}; text: ${params.input}`,
+    headers: { 'content-type': `audio/${format}` },
+  };
+}
+
+// ── Files (stateful; BOTH upload flows) ─────────────────────────────────────────────────
+/** Together's `FilePurpose` — a CLOSED documented set (NOT OpenAI's). */
+const FILE_PURPOSES = new Set<TogetheraiFilePurpose>(['fine-tune', 'eval', 'batch-api']);
+/** Together's `FileType` — a CLOSED documented set. */
+const FILE_TYPES = new Set<TogetheraiFileType>(['csv', 'jsonl', 'parquet']);
+
+/** Build the vendor-faithful FileResponse view of a stored row. */
+function fileView(r: Record<string, unknown>): Record<string, unknown> {
+  const s = strip(r);
+  return {
+    id: r.id,
+    object: 'file',
+    created_at: s.created_at,
+    filename: s.filename,
+    bytes: s.bytes,
+    purpose: s.purpose,
+    Processed: s.Processed ?? true,
+    FileType: s.FileType,
+    ...(s.processing_status !== undefined ? { processing_status: s.processing_status } : {}),
+    ...(s.validation_report !== undefined ? { validation_report: s.validation_report } : {}),
+  };
+}
+
+/** Validate + derive the stored fields for a file create (shared by both upload flows).
+ *
+ *  The REQUIRED parts are the vendor's, not ours: the SDK types `purpose: FilePurpose` as
+ *  REQUIRED (files.d.ts:48, `upload(file: string, purpose: FilePurpose, …)`) and the multipart
+ *  form's `file` part names the upload (`filename`); the 302 flow's query carries `file_name` +
+ *  `purpose` (lib/upload.js:40). A request missing one answers the vendor's 400 and stores
+ *  NOTHING — a defaulted `fine-tune`/`upload.jsonl` minted a file from a bodyless POST (the §9
+ *  round-three blocker; the class fix, not the one instance). */
+function fileFieldsFrom(params: Record<string, unknown>): { fields: Record<string, unknown> } | { error: TogetheraiResponseEnvelope } {
+  if (params.purpose === undefined || params.purpose === null || params.purpose === '') {
+    return { error: invalidRequest("'purpose' is a required property") };
+  }
+  const purpose = params.purpose;
+  if (typeof purpose !== 'string' || !FILE_PURPOSES.has(purpose as TogetheraiFilePurpose)) {
+    return { error: invalidRequest(`'purpose' must be one of ${[...FILE_PURPOSES].map((p) => `'${p}'`).join(', ')} (got '${String(purpose)}')`) };
+  }
+  const rawName = params.filename ?? params.file_name;
+  if (rawName === undefined || rawName === null || String(rawName).trim() === '') {
+    return { error: invalidRequest("'filename' is a required property") };
+  }
+  const filename = String(rawName);
+  // An EXPLICIT file_type wins; otherwise it is derived from the filename's extension (§9 round
+  // two, R2-D3: the old OR discarded an explicit file_type whenever FileType was absent, and no
+  // value was ever validated against the closed set).
+  const fileType = params.file_type !== undefined ? String(params.file_type)
+    : params.FileType !== undefined ? String(params.FileType)
+    : (filename.includes('.') ? String(filename.split('.').pop()).toLowerCase() : 'jsonl');
+  if (!FILE_TYPES.has(fileType as TogetheraiFileType)) {
+    return { error: invalidRequest(`'file_type' must be one of ${[...FILE_TYPES].map((t) => `'${t}'`).join(', ')} (got '${fileType}')`) };
+  }
+  const content = typeof params.content === 'string' ? params.content : '';
+  const bytes = typeof params.bytes === 'number' ? params.bytes : content.length;
+  // Files for non-`fine-tune` purposes SKIP validation (Together's own schema wording); a
+  // fine-tune file enters the pipeline as PENDING.
+  const processing_status = purpose === 'fine-tune' ? 'PENDING' : undefined;
+  return {
+    fields: {
+      object: 'file', bytes, created_at: 0, filename, purpose, Processed: true, FileType: fileType,
+      ...(processing_status ? { processing_status } : {}),
+      _content: content,
+    },
+  };
+}
+
+async function createFileMultipart(params: Record<string, unknown>, req: TogetheraiRequest): Promise<TogetheraiResponseEnvelope> {
+  const built = fileFieldsFrom(params);
+  if ('error' in built) return built.error;
+  const id = nextId('file', 'file', req.root);
+  await applyTwinWrite(SERVICE, {
+    operation: 'file.create',
+    subjectType: 'file',
+    subjectId: id,
+    fields: { ...built.fields, created_at: nowEpoch(req.occurredAt) },
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+    actor: { kind: 'agent' },
+  }, req.root);
+  return { status: 200, body: fileView(getRow('file', id, req.root) ?? {}) };
+}
+
+/**
+ * The together-ai SDK's OWN upload flow (lib/upload.js, together-ai@0.53.0) — NOT the spec's
+ * multipart form: it POSTs `/files?file_name=…&file_type=…&purpose=…` as
+ * `application/x-www-form-urlencoded`, requires a **302** with a `Location` upload URL and an
+ * `x-together-file-id` header, PUTs the bytes there, then confirms with `files.retrieve`. The
+ * twin answers the 302 with a twin-local upload URL and mints the file row immediately; the PUT
+ * below fills its content.
+ */
+async function createFileSdkRedirect(params: Record<string, unknown>, req: TogetheraiRequest, query: URLSearchParams): Promise<TogetheraiResponseEnvelope> {
+  const built = fileFieldsFrom(params);
+  if ('error' in built) return built.error;
+  const id = nextId('file', 'file', req.root);
+  await applyTwinWrite(SERVICE, {
+    operation: 'file.create',
+    subjectType: 'file',
+    subjectId: id,
+    fields: { ...built.fields, created_at: nowEpoch(req.occurredAt) },
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+    actor: { kind: 'agent' },
+  }, req.root);
+  return {
+    status: 302,
+    body: '',
+    headers: {
+      // Twin-LOCAL on purpose: the handler knows only paths. The HTTP server absolutizes it
+      // against the twin's public base — the real SDK fetches `Location` with no base URL.
+      location: `/twin/upload/${id}`,
+      'x-together-file-id': id,
+    },
+  };
+}
+
+async function storeUploadBytes(fileId: string, content: string, req: TogetheraiRequest): Promise<TogetheraiResponseEnvelope> {
+  const f = getRow('file', fileId, req.root);
+  if (!f || f._deleted) return notFound(`No such File object: ${fileId}`);
+  await applyTwinWrite(SERVICE, {
+    operation: 'file.update',
+    subjectType: 'file', subjectId: fileId,
+    fields: { _content: content, bytes: content.length },
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+  }, req.root);
+  return { status: 200, body: { ok: true } };
+}
+
+// ── Batches (Together-native shapes) ────────────────────────────────────────────────────
+/** Together's `CreateBatchRequest.endpoint` — the THREE documented endpoints. */
+const BATCH_ENDPOINTS = new Set<TogetheraiBatchEndpoint>(['/v1/chat/completions', '/v1/audio/transcriptions', '/v1/audio/translations']);
+
+/** The batch view of a stored row. `error` stays a bare STRING (Together's BatchJob.error). */
+function batchView(r: Record<string, unknown>): Record<string, unknown> {
+  const s = strip(r);
+  return {
+    id: r.id,
+    user_id: s.user_id,
+    input_file_id: s.input_file_id,
+    file_size_bytes: s.file_size_bytes,
+    status: s.status,
+    job_deadline: s.job_deadline ?? null,
+    created_at: s.created_at,
+    endpoint: s.endpoint,
+    progress: s.progress ?? 0,
+    ...(s.model_id !== undefined ? { model_id: s.model_id } : {}),
+    output_file_id: s.output_file_id ?? null,
+    error_file_id: s.error_file_id ?? null,
+    error: s.error ?? null,
+    completed_at: s.completed_at ?? null,
+  };
+}
+
+async function createBatch(params: Record<string, unknown>, req: TogetheraiRequest): Promise<TogetheraiResponseEnvelope> {
+  const inputFileId = params.input_file_id;
+  if (typeof inputFileId !== 'string' || !inputFileId) return invalidRequest("'input_file_id' is a required property");
+  const endpoint = params.endpoint;
+  if (typeof endpoint !== 'string' || !BATCH_ENDPOINTS.has(endpoint as TogetheraiBatchEndpoint)) {
+    return invalidRequest(`'endpoint' must be one of ${[...BATCH_ENDPOINTS].map((e) => `'${e}'`).join(', ')}`);
+  }
+  const file = getRow('file', inputFileId, req.root);
+  if (!file || file._deleted) return notFound(`No such File object: ${inputFileId}`);
+  const created = nowEpoch(req.occurredAt);
+  const id = nextId('batch', 'batch', req.root);
+  await applyTwinWrite(SERVICE, {
+    operation: 'batch.create',
+    subjectType: 'batch',
+    subjectId: id,
+    fields: {
+      object: 'batch',
+      endpoint,
+      input_file_id: inputFileId,
+      status: 'VALIDATING' as TogetheraiBatchStatus,
+      created_at: new Date(created * 1000).toISOString(),
+      file_size_bytes: typeof file.bytes === 'number' ? file.bytes : 0,
+      progress: 0,
+      ...(params.completion_window !== undefined ? { completion_window: params.completion_window } : {}),
+      ...(params.priority !== undefined ? { priority: params.priority } : {}),
+      ...(params.model_id !== undefined ? { model_id: params.model_id } : {}),
+    },
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+    actor: { kind: 'agent' },
+  }, req.root);
+  // Together's create answers **201** with `BatchJobWithWarning { job, warning? }` — NOT an
+  // OpenAI-style 200 batch object.
+  return { status: 201, body: { job: batchView(getRow('batch', id, req.root) ?? {}) } };
+}
+
+// ── Fine-tunes (Together-native shapes) ─────────────────────────────────────────────────
+/** Together's `FinetuneJobStatus` enum. */
+const FINETUNE_STATUSES = ['pending', 'queued', 'running', 'compressing', 'uploading', 'cancel_requested', 'cancelled', 'error', 'completed'] as const;
+
+function finetuneView(r: Record<string, unknown>): Record<string, unknown> {
+  const s = strip(r);
+  return {
+    id: r.id,
+    status: s.status,
+    user_id: s.user_id,
+    ...(s.training_file !== undefined ? { training_file: s.training_file } : {}),
+    ...(s.validation_file !== undefined ? { validation_file: s.validation_file } : {}),
+    ...(s.model !== undefined ? { model: s.model } : {}),
+    ...(s.model_output_name !== undefined ? { model_output_name: s.model_output_name } : {}),
+    ...(s.created_at !== undefined ? { created_at: s.created_at } : {}),
+    ...(s.updated_at !== undefined ? { updated_at: s.updated_at } : {}),
+    ...(s.n_epochs !== undefined ? { n_epochs: s.n_epochs } : {}),
+  };
+}
+
+async function createFinetune(params: Record<string, unknown>, req: TogetheraiRequest): Promise<TogetheraiResponseEnvelope> {
+  if (params.model === undefined || typeof params.model !== 'string' || !params.model) return invalidRequest("'model' is a required property");
+  if (typeof params.training_file !== 'string' || !params.training_file) return invalidRequest("'training_file' is a required property");
+  const base = servedModels(req.root).find((row) => row.id === params.model);
+  if (!base || base.type !== 'chat') return notFound(`Model ${params.model} does not exist or is not a fine-tunable model.`);
+  const training = getRow('file', params.training_file, req.root);
+  if (!training || training._deleted) return notFound(`No such File object: ${params.training_file}`);
+  if (training.purpose !== 'fine-tune') return invalidRequest(`File ${params.training_file} must have purpose 'fine-tune' (has '${String(training.purpose)}')`);
+  if (params.validation_file !== undefined && params.validation_file !== null) {
+    const validation = getRow('file', String(params.validation_file), req.root);
+    if (!validation || validation._deleted) return notFound(`No such File object: ${String(params.validation_file)}`);
+    if (validation.purpose !== 'fine-tune') return invalidRequest(`File ${params.validation_file} must have purpose 'fine-tune' (has '${String(validation.purpose)}')`);
+  }
+  const id = nextId('finetune', 'ft', req.root);
+  const at = new Date(nowEpoch(req.occurredAt) * 1000).toISOString();
+  await applyTwinWrite(SERVICE, {
+    operation: 'finetune.create',
+    subjectType: 'finetune',
+    subjectId: id,
+    fields: {
+      object: 'finetune',
+      status: 'pending',
+      user_id: 'user_twin',
+      model: params.model,
+      training_file: params.training_file,
+      ...(params.validation_file !== undefined && params.validation_file !== null ? { validation_file: params.validation_file } : {}),
+      created_at: at,
+      updated_at: at,
+      ...(typeof params.n_epochs === 'number' ? { n_epochs: params.n_epochs } : {}),
+    },
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+    actor: { kind: 'agent' },
+  }, req.root);
+  return { status: 200, body: finetuneView(getRow('finetune', id, req.root) ?? {}) };
+}
+
+// ── Fine-tune aux endpoints (modeled against Together's documented shapes) ──────────────
+/** The content of a fine-tune-purpose file row, JSONL-decoded into per-row objects. */
+function jsonlRows(content: unknown): Array<Record<string, unknown>> {
+  if (typeof content !== 'string' || !content.trim()) return [];
+  return content.split('\n').filter((l) => l.trim()).map((l) => {
+    try {
+      const v = JSON.parse(l);
+      return v && typeof v === 'object' ? (v as Record<string, unknown>) : {};
+    } catch {
+      return {};
+    }
+  });
+}
+
+/** GET /v1/fine-tunes/models/limits — Together's `FinetuneModelLimits` for ONE model
+ *  (together-ai@0.53.0 fine-tuning.d.ts:270, `model_name` REQUIRED — fine-tuning.d.ts:1798).
+ *  A model the catalog does not know fails like the vendor. The numbers are the twin's
+ *  deterministic stand-ins for the vendor's per-model training limits; the SHAPE is the vendor's
+ *  REQUIRED+OPTIONAL contract. */
+function finetuneModelLimits(req: TogetheraiRequest): TogetheraiResponseEnvelope {
+  const search = req.path.includes('?') ? new URLSearchParams(req.path.slice(req.path.indexOf('?') + 1)) : new URLSearchParams();
+  const modelName = search.get('model_name');
+  if (!modelName) return invalidRequest("'model_name' is a required property");
+  const m = servedModels(req.root).find((pm) => pm.id === modelName);
+  if (!m || m.type !== 'chat') return notFound(`Model ${modelName} does not exist or is not a fine-tunable model.`);
+  const seq = m.context_length || 8_192;
+  const seed = fnv1a(modelName);
+  return {
+    status: 200,
+    body: {
+      model_name: m.id,
+      default_gradient_accumulation_steps: 16,
+      lora_training: {
+        max_batch_size: 8,
+        max_batch_size_dpo: 4,
+        max_rank: 64,
+        min_batch_size: 1,
+        target_modules: ['q_proj', 'k_proj', 'v_proj', 'o_proj', 'gate_proj', 'up_proj', 'down_proj'],
+      },
+      max_learning_rate: 0.0002,
+      max_num_checkpoints: 10,
+      max_num_epochs: 36,
+      max_num_evals: 36,
+      max_seq_length_dpo: seq,
+      max_seq_length_sft: seq,
+      merge_output_lora: true,
+      min_learning_rate: 0.000001,
+      min_max_seq_length: 128,
+      supports_full_training: false,
+      supports_reasoning: false,
+      supports_tools: true,
+      supports_vision: false,
+      // deterministic per-model jitter so two models never answer identical limits
+      ...(seed % 2 === 0 ? { full_training: { max_batch_size: 4, max_batch_size_dpo: 2, min_batch_size: 1 } } : {}),
+    },
+  };
+}
+
+/** POST /v1/fine-tunes/estimate-price — Together's DISCRIMINATED union
+ *  (together-ai@0.53.0 fine-tuning.d.ts:1323 — AvailableEstimate | UnavailableEstimate on
+ *  `estimation_available`). A training_file the twin has seen and validated resolves to an
+ *  AvailableEstimate whose token counts are DETERMINISTIC functions of the file's stored
+ *  content; an unknown id is `false` with the vendor's `train_file_invalid` reason. */
+function estimateFinetunePrice(params: Record<string, unknown>, req: TogetheraiRequest): TogetheraiResponseEnvelope {
+  // together-ai@0.53.0 fine-tuning.d.ts:1688-1691: training_file is REQUIRED, model optional. A
+  // request without the file has nothing to estimate over; the vendor refuses it, never invents 64 tokens.
+  if (params.training_file === undefined || typeof params.training_file !== 'string' || !params.training_file) return invalidRequest("'training_file' is a required property");
+  const file = params.training_file !== undefined ? getRow('file', String(params.training_file), req.root) : undefined;
+  if (params.training_file !== undefined && (!file || file._deleted)) {
+    return { status: 200, body: { estimation_available: false, unavailable_reason: 'train_file_invalid' } };
+  }
+  const dataset = jsonlRows(file?._content);
+  const totalTokens = dataset.reduce((n, row) => n + estimateTokens(JSON.stringify(row)), 0) || 64;
+  const epochs = typeof params.n_epochs === 'number' && params.n_epochs > 0 ? params.n_epochs : 1;
+  return {
+    status: 200,
+    body: {
+      estimation_available: true,
+      allowed_to_proceed: true,
+      estimated_total_price: Math.round(totalTokens * epochs * 0.000002 * 1_000_000) / 1_000_000,
+      estimated_train_token_count: totalTokens * epochs,
+      estimated_eval_token_count: 0,
+      user_limit: 100,
+    },
+  };
+}
+
+/** POST /v1/fine-tunes/preview — Together's `FineTunePreviewResponse` (fine-tuning.d.ts:160):
+ *  tokenized preview rows over the SAMPLED training file, not a prose string. The token ids are
+ *  the twin's deterministic stand-ins; the shape and the per-row contract (input_ids/labels/
+ *  num_tokens/num_trained_tokens/tokens/trained_spans/truncated) are the vendor's. An unknown
+ *  training_file fails like the vendor. */
+function previewFinetuneTokenization(params: Record<string, unknown>, req: TogetheraiRequest): TogetheraiResponseEnvelope {
+  if (typeof params.model !== 'string' || !params.model) return invalidRequest("'model' is a required property");
+  if (typeof params.training_file !== 'string' || !params.training_file) return invalidRequest("'training_file' is a required property");
+  const m = servedModels(req.root).find((pm) => pm.id === params.model);
+  if (!m || m.type !== 'chat') return notFound(`Model ${params.model} does not exist or is not a fine-tunable model.`);
+  const file = getRow('file', params.training_file, req.root);
+  if (!file || file._deleted) return notFound(`No such File object: ${params.training_file}`);
+  const maxSeq = m.context_length || 8_192;
+  const topK = typeof params.top_k === 'number' && Number.isInteger(params.top_k) && params.top_k > 0 ? Math.min(params.top_k, 100) : 5;
+  const trainOnInputs = params.train_on_inputs === undefined ? true : params.train_on_inputs === true;
+  const sampled = jsonlRows(file._content).slice(0, topK);
+  // The SDK documents dataset_format as DETECTED per sampled rows ("Detected SFT dataset format
+  // for the sampled rows", fine-tuning.d.ts:158) — the check the vendor's own uploader runs
+  // (lib/check-file.mjs: JSONL_REQUIRED_COLUMNS_MAP: general=['text'], conversation=['messages'],
+  // instruction=['prompt','completion']). A file whose rows carry no recognizable column set
+  // answers 'general', the format a bare text row is.
+  const datasetFormat = (() => {
+    const first = sampled[0];
+    if (!first) return 'general';
+    if ('messages' in first) return 'conversation';
+    if ('prompt' in first && 'completion' in first) return 'instruction';
+    return 'general';
+  })();
+  const rows = (sampled.length ? sampled : [{}]).map((row) => {
+    const text = JSON.stringify(row);
+    // Deterministic pseudo-token ids: one per ~4 chars (fnv1a-seeded), same input → same ids.
+    const words = text.length > 0 ? Math.max(1, Math.ceil(text.length / 4)) : 1;
+    const inputIds = Array.from({ length: words }, (_, i) => fnv1a(`${text}:${i}`) % 50_000);
+    const labels = trainOnInputs ? [...inputIds] : inputIds.map(() => -100);
+    const numTrained = labels.filter((l) => l !== -100).length;
+    const truncated = words > maxSeq;
+    return {
+      input_ids: inputIds.slice(0, maxSeq),
+      labels: labels.slice(0, maxSeq),
+      num_tokens: Math.min(words, maxSeq),
+      num_trained_tokens: Math.min(numTrained, maxSeq),
+      tokens: inputIds.map((id) => `tok_${id.toString(36)}`).slice(0, maxSeq),
+      trained_spans: trainOnInputs && numTrained > 0 ? [[0, Math.min(numTrained, maxSeq)]] : [],
+      truncated,
+    };
+  });
+  return {
+    status: 200,
+    body: {
+      dataset_format: datasetFormat,
+      max_seq_length: maxSeq,
+      model: m.id,
+      rows,
+      train_on_inputs: trainOnInputs,
+    },
+  };
+}
+
+/** GET /v1/fine-tunes/{id}/events — Together's `FinetuneEvent` list (fine-tuning.d.ts:234).
+ *  A job still `pending` has NO events yet (the vendor's job has not started); a job the twin
+ *  has seen move (cancel_requested or beyond) carries the events its history grounds — the
+ *  lifecycle events the vendor's own enum names, derived from the STORED row, never invented
+ *  progress. */
+function finetuneEvents(ft: Record<string, unknown>): Array<Record<string, unknown>> {
+  const status = String(ft.status ?? 'pending');
+  const at = (ft.created_at as string) ?? new Date(0).toISOString();
+  const events: Array<Record<string, unknown>> = [];
+  if (status !== 'pending') {
+    events.push({ object: 'fine-tune-event', created_at: at, message: 'Job started', type: 'job_start' });
+  }
+  if (status === 'cancel_requested') {
+    events.push({ object: 'fine-tune-event', created_at: at, message: 'Cancel requested', type: 'cancel_requested' });
+  }
+  return events;
+}
+
+/** GET /v1/fine-tunes/{id}/checkpoints — Together's `FineTuningListCheckpointsResponse`
+ *  (fine-tuning.d.ts:1362). Checkpoints are artifacts a COMPLETED training run produced; the
+ *  twin runs no training and its jobs never progress past the states above, so an honest answer
+ *  over stored state is an EMPTY list — the vendor's shape, not a fabricated artifact. */
+function finetuneCheckpoints(ft: Record<string, unknown>): Array<Record<string, unknown>> {
+  return String(ft.status) === 'completed'
+    ? [{ checkpoint_type: 'final', created_at: String(ft.updated_at ?? ft.created_at ?? new Date(0).toISOString()), path: `twin://finetune/${String(ft.id)}/final`, step: 1 }]
+    : [];
+}
+
+// ── public entry: cross-cutting protocol (auth / fault triggers) then route ─────────────
+export async function handleTogetheraiTwinRequest(req: TogetheraiRequest): Promise<TogetheraiResponseEnvelope> {
+  const method = req.method.toUpperCase();
+  if (req.headers !== undefined || req.apiKey !== undefined) {
+    const authErr = checkAuth(req);
+    if (authErr) return authErr;
+  }
+  if (triggered(req, 'x-twin-force-rate-limit')) return rateLimitError();
+  if (triggered(req, 'x-twin-force-spending-limit')) return spendingLimitError();
+  if (triggered(req, 'x-twin-force-engine-overloaded')) return engineOverloadedError();
+  return routeTogetherai(req, method);
+}
+
+// ── router ──────────────────────────────────────────────────────────────────────────────
+async function routeTogetherai(req: TogetheraiRequest, method: string): Promise<TogetheraiResponseEnvelope> {
+  const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+  const search = req.path.includes('?') ? req.path.slice(req.path.indexOf('?') + 1) : '';
+  const params = parseJson(req.body);
+  // A percent-decode that never throws: `GET /v1/files/%zz` is a malformed escape, and the vendor
+  // answers it like any other unknown object (404), not an internal error. decodeURIComponent
+  // throws URIError on it — the same trap the upload door's decSafe guards.
+  const dec = decSafe;
+
+  // D3: a read-only twin rejects any mutation with a vendor-shaped error.
+  if (req.readOnly && method !== 'GET') {
+    return { status: 405, body: errBody('invalid_request_error', 'twin is read-only; omit readOnly to accept writes') };
+  }
+
+  // Everything Together's inference API serves hangs off /v1. A request outside it is a 404 like
+  // any other unknown path.
+  if (path !== TOGETHERAI_API_PREFIX && !path.startsWith(`${TOGETHERAI_API_PREFIX}/`)) {
+    return notFound(`Unknown request URL: ${method} ${path}. Together's inference API is served under ${TOGETHERAI_API_PREFIX}/.`);
+  }
+  const seg = path.slice(TOGETHERAI_API_PREFIX.length).replace(/^\/+/, '').split('/').filter(Boolean);
+
+  // ---- whoami (static identity for the presented key) ----
+  if (seg[0] === 'whoami' && seg.length === 1 && method === 'GET') {
+    return {
+      status: 200,
+      body: {
+        api_key_id: 'key_twin',
+        project_id: 'proj_twin',
+        project_name: 'Twin Project',
+        project_slug: 'twin-project',
+        organization_id: 'org_twin',
+        organization_name: 'Twin Organization',
+        user_id: 'user_twin',
+      },
+    };
+  }
+
+  // ---- models (static catalog) ----
+  if (seg[0] === 'models' && seg.length === 1 && method === 'GET') {
+    // Together answers a BARE ARRAY of ModelInfo (ModelInfoList), not an OpenAI list envelope.
+    return { status: 200, body: servedModels(req.root) };
+  }
+  if (seg[0] === 'models' && seg.length >= 2 && method === 'GET') {
+    // Together model ids contain slashes (`meta-llama/Llama-3.3-70B-Instruct-Turbo`), so the id
+    // is EVERY remaining segment joined.
+    const mid = seg.slice(1).map(dec).join('/');
+    const m = servedModels(req.root).find((pm) => pm.id === mid);
+    return m ? { status: 200, body: m } : notFound(`Model ${mid} does not exist.`);
+  }
+
+  // ---- chat completions (the generative stub; envelope is faithful) ----
+  if (seg[0] === 'chat' && seg[1] === 'completions' && seg.length === 2 && method === 'POST') {
+    const validated = validateChat(params);
+    if ('error' in validated) return validated.error;
+    const args = validated.args;
+    const result = args.stream && req.sseSink
+      ? streamChat(args, req.sseSink, req.occurredAt, req.scenarioEngine)
+      : buildChatCompletion(args, req.occurredAt, req.scenarioEngine);
+    if (isEnvelope(result)) return result;
+    return { status: 200, body: result };
+  }
+
+  // ---- completions (legacy text) ----
+  if (seg[0] === 'completions' && seg.length === 1 && method === 'POST') {
+    if (params.model === undefined || typeof params.model !== 'string' || !params.model) return invalidRequest("'model' is a required property");
+    if (typeof params.prompt !== 'string') return invalidRequest("'prompt' is a required property");
+    const info = findModel(params.model);
+    if (!info || info.type !== 'chat' && info.type !== 'language' && info.type !== 'code') {
+      return notFound(`Model ${params.model} does not exist or is not a completion model.`);
+    }
+    const prompt = params.prompt;
+    let text = `[twin-stub:${params.model}] deterministic completion stub (no model weights are run) continuing: ${prompt.slice(0, 120) || '(empty)'}`;
+    let finish: TogetheraiFinishReason = 'stop';
+    const maxRaw = params.max_tokens;
+    if (maxRaw !== undefined && maxRaw !== null) {
+      const maxTokens = Number(maxRaw);
+      if (!Number.isInteger(maxTokens) || maxTokens < 1) return invalidRequest("'max_tokens' must be an integer >= 1");
+      if (estimateTokens(text) > maxTokens) {
+        text = text.slice(0, maxTokens * 4);
+        finish = 'length';
+      }
+    }
+    const completion = {
+      id: `cmpl-twin-${fnv1a(prompt + params.model).toString(36)}`,
+      object: 'text.completion' as const,
+      created: nowEpoch(req.occurredAt),
+      model: params.model,
+      prompt: [{ text: prompt }],
+      choices: [{ text, index: 0, finish_reason: finish }],
+      usage: buildUsage(estimateTokens(prompt), estimateTokens(text)),
+    };
+    // stream:true streams Together's CompletionChunk sequence (the legacy API streams too — the
+    // SDK types it `Stream<CompletionChunk>`): a `token` chunk per piece, then the finish chunk.
+    if (params.stream === true && req.sseSink) {
+      const base = { id: completion.id, object: 'completion.chunk' as const, created: completion.created, model: params.model };
+      for (const piece of chunkText(text)) {
+        req.sseSink({ data: { ...base, token: { id: 0, logprob: 0, special: false, text: piece }, choices: [{ index: 0, text: piece }], finish_reason: null, usage: null } });
+      }
+      req.sseSink({ data: { ...base, token: { id: 0, logprob: 0, special: true, text: '' }, choices: [{ index: 0 }], finish_reason: finish, usage: completion.usage } });
+      req.sseSink({ done: true });
+      return { status: 200, body: completion };
+    }
+    return { status: 200, body: completion };
+  }
+
+  // ---- embeddings ----
+  if (seg[0] === 'embeddings' && seg.length === 1 && method === 'POST') return handleEmbeddings(params);
+
+  // ---- rerank (Together-native) ----
+  if (seg[0] === 'rerank' && seg.length === 1 && method === 'POST') return handleRerank(params);
+
+  // ---- images ----
+  if (seg[0] === 'images' && seg[1] === 'generations' && seg.length === 2 && method === 'POST') return handleImages(params);
+
+  // ---- audio ----
+  if (seg[0] === 'audio' && seg[1] === 'transcriptions' && seg.length === 2 && method === 'POST') return handleTranscription(params, false);
+  if (seg[0] === 'audio' && seg[1] === 'translations' && seg.length === 2 && method === 'POST') return handleTranscription(params, true);
+  if (seg[0] === 'audio' && seg[1] === 'speech' && seg.length === 2 && method === 'POST') return handleSpeech(params);
+
+  // ---- files (stateful; BOTH upload flows) ----
+  if (seg[0] === 'files' && seg.length === 1 && method === 'POST') {
+    // The together-ai SDK's redirect upload flow addresses POST /files with its params in the
+    // QUERY STRING and a form-urlencoded body (lib/upload.js:41). That query-param shape is the
+    // ONLY create on this path: Together's spec inventory has no JSON create on /files
+    // (test-fixtures/togetherai-openapi-operations.json — GET only), and a JSON or EMPTY body
+    // mints nothing. Serving a create here would be an invented door (§ round two, defect 1);
+    // the vendor's own table answers a misconfigured request 400 invalid_request_error
+    // (docs.together.ai/docs/error-codes). The flow is recognized by PARSING the query for the
+    // params it sends (file_name/purpose — lib/upload.js:40), never by substring-matching the
+    // raw string: `?file_type=jsonl` alone must NOT be mistaken for the flow.
+    const q = new URLSearchParams(search);
+    const hasFile = q.has('file_name');
+    const hasPurpose = q.has('purpose');
+    if (hasFile || hasPurpose) {
+      return createFileSdkRedirect({
+        ...(hasPurpose ? { purpose: q.get('purpose') ?? undefined } : {}),
+        ...(hasFile ? { file_name: q.get('file_name') ?? undefined } : {}),
+        ...(q.has('file_type') ? { file_type: q.get('file_type') ?? undefined } : {}),
+        ...(typeof params.content === 'string' ? { content: params.content } : {}),
+      }, req, q);
+    }
+    return invalidRequest("POST /v1/files takes the upload flow's urlencoded query parameters (?file_name=&file_type=&purpose=); the create itself is POST /v1/files/upload (multipart)");
+  }
+  if (seg[0] === 'files' && seg.length === 1 && method === 'GET') {
+    // Together answers `{ data: [...] }` (FileList), NOT OpenAI's `{object:'list',data}`.
+    return { status: 200, body: { data: rows('file', req.root).filter((r) => !r._deleted).map(fileView) } };
+  }
+  if (seg[0] === 'files' && seg[1] === 'upload' && seg.length === 2 && method === 'POST') {
+    // The spec's multipart form upload (the server adapts multipart → JSON before the handler).
+    return createFileMultipart(params, req);
+  }
+  if (seg[0] === 'files' && seg.length === 2 && method === 'GET') {
+    const f = getRow('file', dec(seg[1]!), req.root);
+    return f && !f._deleted ? { status: 200, body: fileView(f) } : notFound(`No such File object: ${dec(seg[1]!)}`);
+  }
+  if (seg[0] === 'files' && seg.length === 3 && seg[2] === 'content' && method === 'GET') {
+    const f = getRow('file', dec(seg[1]!), req.root);
+    if (!f || f._deleted) return notFound(`No such File object: ${dec(seg[1]!)}`);
+    return { status: 200, body: String(f._content ?? ''), headers: { 'content-type': 'application/octet-stream' } };
+  }
+  if (seg[0] === 'files' && seg.length === 2 && method === 'DELETE') {
+    const fid = dec(seg[1]!);
+    const f = getRow('file', fid, req.root);
+    if (!f || f._deleted) return notFound(`No such File object: ${fid}`);
+    await applyTwinWrite(SERVICE, {
+      operation: 'file.delete', subjectType: 'file', subjectId: fid, fields: { _deleted: true, object: 'file' },
+      ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: { id: fid, deleted: true } };
+  }
+
+  // ---- batches (stateful, Together-native shapes) ----
+  if (seg[0] === 'batches' && seg.length === 1 && method === 'POST') return createBatch(params, req);
+  if (seg[0] === 'batches' && seg.length === 1 && method === 'GET') {
+    // Together answers a BARE ARRAY of BatchJob (its own published schema), NOT an OpenAI
+    // `{object:'list',data}` envelope.
+    return { status: 200, body: rows('batch', req.root).map(batchView) };
+  }
+  if (seg[0] === 'batches' && seg.length === 2 && method === 'GET') {
+    const b = getRow('batch', dec(seg[1]!), req.root);
+    if (!b) return notFound(`No such Batch object: ${dec(seg[1]!)}`);
+    return { status: 200, body: batchView(b) };
+  }
+  if (seg[0] === 'batches' && seg.length === 3 && seg[2] === 'cancel' && method === 'POST') {
+    const bid = dec(seg[1]!);
+    const b = getRow('batch', bid, req.root);
+    if (!b) return notFound(`No such Batch object: ${bid}`);
+    if (b.status === 'CANCELLED') return invalidRequest(`Cannot cancel a batch with status '${String(b.status)}'.`);
+    // NOTE: the twin does not simulate the asynchronous VALIDATING→IN_PROGRESS→COMPLETED
+    // progression. Doing it on a READ made a GET write (breaking the read-only contract) and
+    // minted actions the connector has no vendor endpoint to push (the groq pack's §9 round-one
+    // findings 4 + 5). The terminal transitions are filed as todos.
+    await applyTwinWrite(SERVICE, {
+      operation: 'batch.cancel', subjectType: 'batch', subjectId: bid,
+      fields: { status: 'CANCELLED' as TogetheraiBatchStatus },
+      ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: batchView(getRow('batch', bid, req.root) ?? {}) };
+  }
+
+  // ---- fine-tunes (stateful, Together-native shapes) ----
+  if (seg[0] === 'fine-tunes' && seg.length === 1 && method === 'POST') return createFinetune(params, req);
+  if (seg[0] === 'fine-tunes' && seg.length === 1 && method === 'GET') {
+    return { status: 200, body: rows('finetune', req.root).filter((r) => !r._deleted).map(finetuneView) };
+  }
+  if (seg[0] === 'fine-tunes' && seg[1] === 'models' && seg[2] === 'limits' && seg.length === 3 && method === 'GET') {
+    return finetuneModelLimits(req);
+  }
+  if (seg[0] === 'fine-tunes' && seg[1] === 'estimate-price' && seg.length === 2 && method === 'POST') {
+    return estimateFinetunePrice(params, req);
+  }
+  if (seg[0] === 'fine-tunes' && seg[1] === 'preview' && seg.length === 2 && method === 'POST') {
+    return previewFinetuneTokenization(params, req);
+  }
+  if (seg[0] === 'fine-tunes' && seg.length === 2 && method === 'GET') {
+    const ft = getRow('finetune', dec(seg[1]!), req.root);
+    return ft && !ft._deleted ? { status: 200, body: finetuneView(ft) } : notFound(`No such Fine-tune object: ${dec(seg[1]!)}`);
+  }
+  if (seg[0] === 'fine-tunes' && seg.length === 3 && seg[2] === 'cancel' && method === 'POST') {
+    const fid = dec(seg[1]!);
+    const ft = getRow('finetune', fid, req.root);
+    if (!ft || ft._deleted) return notFound(`No such Fine-tune object: ${fid}`);
+    if (ft.status === 'cancelled' || ft.status === 'cancel_requested' || ft.status === 'completed' || ft.status === 'error') {
+      return invalidRequest(`Cannot cancel a fine-tune with status '${String(ft.status)}'.`);
+    }
+    await applyTwinWrite(SERVICE, {
+      operation: 'finetune.cancel', subjectType: 'finetune', subjectId: fid,
+      fields: { status: 'cancel_requested' },
+      ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: finetuneView(getRow('finetune', fid, req.root) ?? {}) };
+  }
+  if (seg[0] === 'fine-tunes' && seg.length === 3 && seg[2] === 'events' && method === 'GET') {
+    const ft = getRow('finetune', dec(seg[1]!), req.root);
+    if (!ft || ft._deleted) return notFound(`No such Fine-tune object: ${dec(seg[1]!)}`);
+    return { status: 200, body: { data: finetuneEvents(ft) } };
+  }
+  if (seg[0] === 'fine-tunes' && seg.length === 3 && seg[2] === 'checkpoints' && method === 'GET') {
+    const ft = getRow('finetune', dec(seg[1]!), req.root);
+    if (!ft || ft._deleted) return notFound(`No such Fine-tune object: ${dec(seg[1]!)}`);
+    return { status: 200, body: { data: finetuneCheckpoints(ft) } };
+  }
+  if (seg[0] === 'fine-tunes' && seg.length === 2 && method === 'DELETE') {
+    const fid = dec(seg[1]!);
+    const ft = getRow('finetune', fid, req.root);
+    if (!ft || ft._deleted) return notFound(`No such Fine-tune object: ${fid}`);
+    await applyTwinWrite(SERVICE, {
+      operation: 'finetune.delete', subjectType: 'finetune', subjectId: fid, fields: { _deleted: true, object: 'finetune' },
+      ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    }, req.root);
+    // Together's fine-tune delete answers {message} (together-ai@0.53.0 fine-tuning.d.ts:1073) —
+    // NOT OpenAI's {id, deleted} (which is the FILE delete shape, files.d.ts:168, served above).
+    return { status: 200, body: { message: `Fine-tune ${fid} deleted.` } };
+  }
+
+  // Unmodeled operation → fail like the vendor (never a fake success).
+  return notFound(`Unknown request URL: ${method} ${path}.`);
+}
+
+/** The twin-only door the SDK redirect flow uploads bytes through (kept OUT of the manifest:
+ *  twin-only scaffolding, not vendor surface — the same rule the `/twin` doors follow). */
+export const TOGETHERAI_UPLOAD_DOOR = '/twin/upload';
+export async function handleTogetheraiUploadDoor(req: TogetheraiRequest): Promise<TogetheraiResponseEnvelope> {
+  const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '');
+  const m = new RegExp(`^${TOGETHERAI_UPLOAD_DOOR}/([^/]+)$`).exec(path);
+  if (!m || req.method.toUpperCase() !== 'PUT') return notFound(`Unknown request URL: ${req.method} ${path}.`);
+  // D3: the door WRITES (file.update), so a read-only twin refuses it with the same vendor-shaped
+  // 405 every other write door answers — the server forwards readOnly here, and ignoring it let
+  // `PUT /twin/upload/<id>` write on a --read-only server (§ round three, defect 2).
+  if (req.readOnly) {
+    return { status: 405, body: errBody('invalid_request_error', 'twin is read-only; omit readOnly to accept writes') };
+  }
+  return storeUploadBytes(decSafe(m[1]!), typeof req.body === 'string' ? req.body : '', req);
+}
+function decSafe(s: string): string {
+  try { return decodeURIComponent(s); } catch { return s; }
+}