@volter/twin-togetherai 0.1.0

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

@@ -0,0 +1,207 @@
+/** A chat message param as the caller sends it. Together's `ChatCompletionMessageParam` oneOf
+ *  covers system/user/assistant/tool/function; content is a string (Together's schema types
+ *  every param's content as `string | null` — no content-part arrays). */
+export type TogetheraiMessageParam = {
+    role: 'system' | 'user' | 'assistant' | 'tool' | 'function';
+    content?: string | null;
+    name?: string;
+    tool_calls?: TogetheraiToolCall[];
+    tool_call_id?: string;
+    reasoning?: string | null;
+    reasoning_content?: string | null;
+};
+/** A function tool_call inside an assistant message (Together's `ToolChoice`). */
+export type TogetheraiToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/** Together's `UsageData`: the three token counts, REQUIRED and NULLABLE (Together reports
+ *  `null` usage on some streamed/failed turns). No timing fields — that is Groq's block. */
+export type TogetheraiUsage = {
+    prompt_tokens: number | null;
+    completion_tokens: number | null;
+    total_tokens: number | null;
+    /** Reasoning models nest the detail blocks (Together's docs: cached/reasoning token splits). */
+    prompt_tokens_details?: {
+        cached_tokens: number;
+    } | null;
+    completion_tokens_details?: {
+        reasoning_tokens: number;
+    } | null;
+};
+/** Together's assistant message. `reasoning`/`reasoning_content` vary by model (Together's docs:
+ *  "varies by model" — both are declared on the schema). No `refusal` field. */
+export type TogetheraiAssistantMessage = {
+    role: 'assistant';
+    content: string | null;
+    tool_calls?: TogetheraiToolCall[];
+    function_call?: {
+        name: string;
+        arguments: string;
+    };
+    reasoning?: string | null;
+    reasoning_content?: string | null;
+};
+/** Together's `FinishReason`: adds **`eos`** to the OpenAI set. */
+export type TogetheraiFinishReason = 'stop' | 'eos' | 'length' | 'tool_calls' | 'function_call';
+export type TogetheraiChoice = {
+    index: number;
+    message?: TogetheraiAssistantMessage;
+    text?: string;
+    seed?: number;
+    logprobs?: unknown | null;
+    finish_reason: TogetheraiFinishReason | null;
+};
+/** The unary chat.completion response. `prompt` is REQUIRED on Together's schema — the echoed
+ *  prompt parts (empty unless `echo:true`); `warnings` is Together's inference-warnings array. */
+export type TogetheraiChatCompletion = {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: TogetheraiChoice[];
+    prompt: Array<{
+        text?: string;
+        logprobs?: unknown;
+    }>;
+    usage?: TogetheraiUsage | null;
+    warnings?: unknown[];
+};
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = {
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;
+/** A streaming chunk. Together's `ChatCompletionChunk` carries `usage` (nullable) and
+ *  `warnings` on EVERY chunk (OpenAI puts usage only in an opt-in tail chunk). */
+export type TogetheraiChunk = {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    system_fingerprint?: string;
+    choices: Array<{
+        index: number;
+        delta: Record<string, unknown>;
+        logprobs?: unknown | null;
+        finish_reason: TogetheraiFinishReason | null;
+    }>;
+    usage?: TogetheraiUsage | null;
+    warnings?: unknown[];
+};
+/** Together's `ModelInfo`: REQUIRED keys are id/object/created/type — `type` is Together's OWN
+ *  enum (chat|language|code|image|embedding|moderation|rerank), not OpenAI's flat model object. */
+export type TogetheraiModel = {
+    id: string;
+    object: 'model';
+    created: number;
+    type: 'chat' | 'language' | 'code' | 'image' | 'embedding' | 'moderation' | 'rerank';
+    display_name?: string;
+    organization?: string;
+    link?: string;
+    license?: string;
+    context_length?: number;
+    pricing?: Record<string, unknown>;
+};
+export type TogetheraiEmbedding = {
+    object: 'embedding';
+    index: number;
+    embedding: number[];
+};
+/** Together's `EmbeddingsResponse`: REQUIRED object/model/data — and NO `usage` key on the
+ *  schema (Together does not document one on this endpoint). */
+export type TogetheraiEmbeddingResponse = {
+    object: 'list';
+    model: string;
+    data: TogetheraiEmbedding[];
+};
+/** Together's `RerankResponse` — Together-native (NOT an OpenAI endpoint at all). */
+export type TogetheraiRerankResponse = {
+    object: 'rerank';
+    id?: string;
+    model: string;
+    results: Array<{
+        index: number;
+        relevance_score: number;
+        document?: {
+            text?: string | null;
+        };
+    }>;
+    usage?: TogetheraiUsage | null;
+};
+/** Together's `ImageResponse`: `object:'list'` with a discriminated data union
+ *  (`type:'url'` | `type:'b64_json'`). */
+export type TogetheraiImageResponse = {
+    id: string;
+    model: string;
+    object: 'list';
+    data: Array<{
+        index: number;
+        url?: string;
+        b64_json?: string;
+        type: 'url' | 'b64_json';
+    }>;
+};
+/** Together's `FilePurpose` — a CLOSED set (`fine-tune` | `eval` | `batch-api`), NOT OpenAI's. */
+export type TogetheraiFilePurpose = 'fine-tune' | 'eval' | 'batch-api';
+/** Together's `FileType` — csv|jsonl|parquet. */
+export type TogetheraiFileType = 'csv' | 'jsonl' | 'parquet';
+/** The validation pipeline's lifecycle state (fine-tune files only). */
+export type TogetheraiFileProcessingStatus = 'PENDING' | 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'INVALID_FORMAT';
+/** Together's `FileResponse`. REQUIRED keys include Together's own `FileType` (capital F) and
+ *  the deprecated `Processed` boolean. */
+export type TogetheraiFile = {
+    id: string;
+    object: 'file';
+    created_at: number;
+    filename: string;
+    bytes: number;
+    purpose: TogetheraiFilePurpose;
+    Processed: boolean;
+    FileType: TogetheraiFileType;
+    processing_status?: TogetheraiFileProcessingStatus;
+    validation_report?: {
+        valid: boolean;
+        [k: string]: unknown;
+    };
+};
+/** Together's `BatchJobStatus` — UPPER-CASE, not OpenAI's lowercase set. */
+export type TogetheraiBatchStatus = 'VALIDATING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'EXPIRED' | 'CANCELLED';
+/** Together's `CreateBatchRequest.endpoint` — the three documented endpoints. */
+export type TogetheraiBatchEndpoint = '/v1/chat/completions' | '/v1/audio/transcriptions' | '/v1/audio/translations';
+/** Together's `BatchJob`. `error` is a bare STRING (not an ErrorData object), and the
+ *  timestamps are ISO date-time STRINGS (not OpenAI's unix integers). */
+export type TogetheraiBatch = {
+    id: string;
+    user_id?: string;
+    input_file_id: string;
+    file_size_bytes?: number;
+    status: TogetheraiBatchStatus;
+    job_deadline?: string | null;
+    created_at: string;
+    endpoint: string;
+    progress?: number;
+    model_id?: string;
+    output_file_id?: string | null;
+    error_file_id?: string | null;
+    error?: string | null;
+    completed_at?: string | null;
+};
+/** Together's `ErrorData`: `{ error: { message, type, param, code } }` with `message`+`type`
+ *  REQUIRED and `param`/`code` nullable with default null. */
+export type TogetheraiError = {
+    error: {
+        message: string;
+        type: string;
+        param?: string | null;
+        code?: string | null;
+    };
+};

package/dist/src/togetherai-types.js

@@ -0,0 +1,26 @@
+// Shared wire-shape types for the Together AI surface. These mirror the REAL vendor JSON shapes
+// as published by Together's own OpenAPI (https://docs.together.ai/openapi.yaml, fetched
+// 2026-09-16) and the Stainless-generated `together-ai@0.53.0` SDK — NOT the SDK's internal
+// types (the twin never imports the SDK at runtime; the SDK is exercised only in *.test.ts).
+//
+// TOGETHER IS NOT OPENAI, and the differences below are load-bearing (they are what a
+// "just copy the openai pack" twin gets wrong):
+//   • `n` spans 1–128 (OpenAI-compatible; Groq pins it at 1) and `logprobs` is an INTEGER 0–20
+//     (OpenAI's boolean) — Together serves both;
+//   • `finish_reason` adds **`eos`** (Together's end-of-sequence token) alongside stop/length;
+//   • the response carries a REQUIRED `prompt: []` array (the echoed prompt when `echo:true`);
+//   • the error envelope is `{ error: { message, type, param, code } }` with `param`/`code`
+//     nullable, and Together's STATUS TABLE is its own: 402 = monthly spending limit,
+//     **403 = context length exceeded** (a BAD REQUEST, not a permission denial),
+//     503 = engine overloaded, 524 = Cloudflare timeout, 529 = server error;
+//   • the batch surface is Together-NATIVE: `GET /v1/batches` answers a bare ARRAY (not an
+//     OpenAI `{object:'list',data}` envelope), `POST /v1/batches` answers 201 with
+//     `BatchJobWithWarning { job, warning? }`, and every batch error is `{ error: string }`
+//     (a bare string, NOT an ErrorData object);
+//   • files carry Together's own `FileType` (csv|jsonl|parquet) and the validation pipeline's
+//     `processing_status` / `validation_report`;
+//   • model ids are slash-namespaced (`meta-llama/Llama-3.3-70B-Instruct-Turbo`) and an
+//     OpenAI-style flat id like `gpt-4o` is a 404;
+//   • `service_tier` / `store` / `metadata` / `prediction` are ACCEPTED BUT IGNORED (the
+//     OpenAI-compat page's own wording) — accepted here, never echoed into the response.
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@volter/twin-togetherai",
+  "version": "0.1.0",
+  "description": "Local Together AI twin — a faithful, stateful local Together API your real `together-ai` SDK talks to unmodified. The model is stubbed (deterministic) and embeddings/rerank/images/transcripts are deterministic stubs, but the protocol envelope (chat completions/streaming/tool_calls, Together's prompt array + eos finish reasons + 402/403/503 status table, models, files, batches, fine-tunes, audio) is vendor-faithful. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/togetherai"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/togetherai#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-togetherai": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "together-ai": "0.53.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-togetherai CLI: serve the Together API twin or run conformance. Together is an API-first
+// vendor — app.together.ai is a console, not where the work happens
+// (docs/contributing/architecture.md C1b) — so this pack ships no mirror.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createTogetheraiTwinServer } from './togetherai-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON file)
+
+if (cmd === 'serve') {
+  const s = await createTogetheraiTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+  process.stdout.write(`togetherai twin (Together API at /v1; model output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling
+  const { checkTogetheraiConformance } = await import('./togetherai-conformance.ts');
+  const report = await checkTogetheraiConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-togetherai serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+// @volter/twin-togetherai — the Together AI twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The Together API: a vendor-faithful protocol envelope (chat
+// completions/streaming/tool_calls with Together's REQUIRED `prompt` array and per-chunk
+// usage/warnings, `eos` finish reasons, Together's OWN status table — 402 spending limit, 403
+// context length, 503 engine overloaded), a static models catalog, deterministic embeddings/
+// rerank/image/audio stubs, and STATEFUL files + batches + fine-tunes — over an event/action log.
+// (Together is an API-first vendor: app.together.ai is a console, not where the work happens, so
+// this pack ships no mirror.)
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so POST /v1/chat/completions
+// returns a DETERMINISTIC STUB completion (clearly labeled), /v1/embeddings returns DETERMINISTIC
+// pseudo-vectors, and the audio endpoints return DETERMINISTIC labeled stubs — never pretending to
+// be real inference. Everything around them — the wire protocol — is faithful. (Conformance +
+// capability tooling live in @volter/world-tooling, a dev dependency — NOT re-exported here, per
+// E2.)
+export { handleTogetheraiTwinRequest, streamChat, buildChatCompletion, TOGETHERAI_API_PREFIX, TOGETHERAI_UPLOAD_DOOR, handleTogetheraiUploadDoor } from './togetherai-twin.ts';
+export type { TogetheraiRequest, TogetheraiResponseEnvelope } from './togetherai-twin.ts';
+export { createTogetheraiTwinFetch, createTogetheraiTwinServer, type TogetheraiTwinFetchOptions } from './togetherai-server.ts';
+export { TOGETHERAI_MODELS, findModel, SPEECH_MODELS, EMBEDDING_MODELS, EMBEDDING_DIMENSIONS, RERANK_MODELS } from './togetherai-models.ts';
+export {
+  buildUsage, contentToText, countPromptTokens, estimateTokens,
+  fnv1a, lastUserText, pseudoEmbedding, stubAssistantText, stubAudioSeconds, stubJsonObject,
+  stubReasoningText, stubToolArguments, stubToolCall, stubTranscript,
+} from './togetherai-stub.ts';
+export type {
+  TogetheraiAssistantMessage, TogetheraiBatch, TogetheraiBatchEndpoint, TogetheraiBatchStatus,
+  TogetheraiChatCompletion, TogetheraiChoice, TogetheraiEmbedding, TogetheraiEmbeddingResponse,
+  TogetheraiError, TogetheraiFile, TogetheraiFilePurpose, TogetheraiFileType,
+  TogetheraiFinishReason, TogetheraiMessageParam, TogetheraiModel, TogetheraiRerankResponse,
+  TogetheraiToolCall, TogetheraiUsage, SseEvent, SseSink,
+} from './togetherai-types.ts';
+export { createTogetheraiScenarioEngine, togetheraiScenarioAdapter, loadTogetheraiScenarioDocument, realizeTogetheraiRespond } from './togetherai-scenario.ts';
+export type { TogetheraiScenarioEngine, TogetheraiScenarioRequest, TogetheraiScenarioRespond, ScenarioToolCall, ScriptedResult } from './togetherai-scenario.ts';
+export {
+  fullSyncTogetherai,
+  externalIdFor,
+  togetheraiRequestForAction,
+  liveTogetheraiExecute,
+  mapBatch,
+  mapFile,
+  mapModel,
+  pullTogetheraiState,
+  pushTogetheraiAction,
+  pushPendingTogetheraiActions,
+  syncTogetheraiFromReal,
+  unpushableReason,
+} from './togetherai-connector.ts';
+export type { TogetheraiExecute, LiveTogetheraiOptions } from './togetherai-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveTogetheraiExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Together's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `TogetheraiBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  TOGETHERAI_BUDGET_CEILING,
+  TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S,
+  TOGETHERAI_BUDGET_WINDOW_MS,
+  TOGETHERAI_CALL_WEIGHTS,
+  TOGETHERAI_RATE_BUDGET,
+  TogetheraiBudget,
+  TogetheraiBudgetError,
+  togetheraiBudgetPath,
+  togetheraiCallWeight,
+} from './togetherai-budget.ts';
+export type { TogetheraiBudgetErrorKind, TogetheraiBudgetOptions, TogetheraiBudgetReservation, TogetheraiBudgetSnapshot } from './togetherai-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { TOGETHERAI_RATE_BUDGET as RATE_BUDGET } from './togetherai-budget.ts';
+import { performTogetheraiAction, syncTogetheraiFromRemote } from './togetherai-connector.ts';
+export const pack: TwinPack = {
+  vendor: 'togetherai',
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system: perform one entry against Together, refresh the root from it.
+  protocol: '2',
+  stateSystem: { perform: performTogetheraiAction, refresh: syncTogetheraiFromRemote },
+  // the round trip: a file create — the one thing this API mints an id for and keeps, a fresh id
+  // each time, so it repeats cleanly on a branch (the spec's own create door, POST
+  // /v1/files/upload; Together's purposes are a CLOSED set: fine-tune | eval | batch-api)
+  roundTrip: { method: 'POST', path: '/v1/files/upload', body: { purpose: 'batch-api', file_name: 'round-trip.jsonl', content: '' }, headers: { authorization: 'Bearer rt' } },
+  // The SAME object togetherai-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'generative',
+  bin: 'world-togetherai',
+  // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+  resourcesUnreachable: {
+    'model': 'the vendor catalog',
+  },
+  resources: ['file', 'batch', 'finetune', 'model'],
+  specSource: 'Together API — enumerated from Together\'s own published OpenAPI spec (api.together.xyz/openapi.json, captured to test-fixtures/togetherai-openapi.yaml: 141 paths / 156 operations — the /v1 inference half AND the v2 management half, of which this pack models the inference half) + together-ai@0.53.0 (Stainless-generated from Together\'s spec: the model unions, the SDK-only 302-redirect upload flow, whoami, the TOGETHER_BASE_URL/TOGETHER_API_KEY/TOGETHER_PROJECT_ID env contract) + docs.together.ai/{error-codes,serverless/rate-limits,inference/openai-compatibility} (all read 2026-09-16). Envelope-faithful; model output, embedding values, rerank scores, images and audio are labeled deterministic stubs.',
+  description: 'Together AI API twin — faithful protocol envelope (chat completions/streaming/tool_calls, Together\'s prompt array and eos finish reasons, Together\'s own 402/403/503 status table), models, stateful files/batches/fine-tunes (both upload flows, incl. the SDK\'s 302 redirect), embeddings/rerank/images/audio; generative output is a labeled stub.',
+  // ADOPTION (adding-a-twin.md §3): how an app repo betrays that it talks to Together. Declared
+  // HERE, not in world-runtime's central SDK_TWINS/ENV_STEM_VENDORS maps — declaring in both
+  // throws. `together-ai` is Together's own official client (npm).
+  adoption: {
+    sdks: ['together-ai'], envStems: ['TOGETHER'],
+  },
+  // INTERCEPTION: the host the official client addresses by default
+  // (together-ai@0.53.0 client.js: TOGETHER_BASE_URL defaults to https://api.together.ai/v1).
+  hosts: [{ host: 'api.together.ai' }],
+  // App-read endpoint templates RIDE ALONGSIDE the injector (the PLANETSCALE_DATABASE_URL
+  // precedent, init.ts wiringFor): `together-ai`'s custom `files.upload()` reads
+  // `TOGETHER_API_BASE_URL` at MODULE LOAD and IGNORES the client's `baseURL`
+  // (lib/upload.js:12 — it then POSTs `${baseURL}/files?…` itself), so interception of
+  // api.together.ai does NOT cover it: unset, `files.upload()` egresses to the real
+  // https://api.together.xyz with the caller's key. The template points that var at the twin's
+  // `/v1` (the SDK POSTs `/files?…` onto it directly), so the one flow the injector cannot reach
+  // is wired too, while ordinary SDK traffic still rides the injector.
+  endpointEnv: {
+    name: 'TOGETHER_TWIN_URL',
+    templates: { TOGETHER_API_BASE_URL: '${url}/v1' },
+    note: 'the injector covers api.together.ai, but together-ai\'s files.upload() reads TOGETHER_API_BASE_URL at module load and ignores client.baseURL (lib/upload.js:12) — the template points it at the twin\'s /v1 so the SDK upload flow does not egress to the real vendor.',
+  },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/src/togetherai-budget.ts

@@ -0,0 +1,156 @@
+// Together AI's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin
+// typed bindings `liveTogetheraiExecute` uses. The MECHANISM — the durable token-keyed ledger,
+// the rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a
+// corrupt ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` →
+// `rateBudget.ts`). Read that module's header for the full rationale AND for the honest list of
+// what the guard does not guarantee.
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN (live-read, 2026-09-16) ──────────────────────────────────────
+// https://docs.together.ai/serverless/rate-limits (read 2026-09-16) publishes NO scalar a client
+// could be bound by: limits are "dynamic" and PER ORGANIZATION and PER MODEL, and the page's own
+// wording is "there are no fixed per-model limits published" — the account's dashboard is the only
+// place the real numbers live. Success responses carry NO rate-limit headers; a 429 carries only
+// `x-ratelimit-reset` (seconds until the window resets), and its error types are
+// `dynamic_request_limited` / `dynamic_token_limited`; a 503 means the dynamic rate is at/below
+// capacity.
+//
+// So this declaration does not model Together's limit, and nothing here is more permissive than
+// the kernel's undeclared fallback: window 60s, ceiling 60, defaultWeight 2 — i.e. 30
+// calls/minute, EXACTLY `DEFAULT_RATE_BUDGET`, with no endpoint priced cheaper than the fallback
+// would price it. Being stricter than the fallback needs no vendor justification; being looser
+// would, and there is none to have.
+//
+// It bounds the 60s AVERAGE; it does not pace (the kernel refuses, it never sleeps). The backstop
+// for a sub-second burst is the cooldown: Together's `x-ratelimit-reset` (documented on the 429)
+// is read off the response and turns into a persisted refusal.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'togetherai';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const TOGETHERAI_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback, because Together publishes no scalar that would
+ * justify more. See the header.
+ */
+export const TOGETHERAI_BUDGET_CEILING = 60;
+
+/** Seconds. A `x-ratelimit-reset` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const TOGETHERAI_CALL_WEIGHTS = {
+  /** `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/rerank`,
+   *  `/v1/images/generations`, `/v1/audio/*` — token-metered, where Together's DYNAMIC token
+   *  budget (`dynamic_token_limited`) rather than its request budget is usually what binds. */
+  inference: 6,
+  /** Everything else: files, batches, models, whoami, fine-tunes, endpoints. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Together-specific thing in the whole budget. */
+export const TOGETHERAI_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: TOGETHERAI_BUDGET_WINDOW_MS,
+  ceiling: TOGETHERAI_BUDGET_CEILING,
+  defaultWeight: TOGETHERAI_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: TOGETHERAI_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^POST /v1/(chat/completions|completions|embeddings|rerank|images/generations)$', weight: TOGETHERAI_CALL_WEIGHTS.inference },
+    { match: '^POST /v1/audio/', weight: TOGETHERAI_CALL_WEIGHTS.inference },
+  ],
+  reason:
+    'Together publishes NO fixed request limit (docs.together.ai/serverless/rate-limits, read ' +
+    '2026-09-16): limits are DYNAMIC and per organization per model — the page states "there are ' +
+    'no fixed per-model limits published", the real numbers live only on the account dashboard, ' +
+    'and success responses carry no rate-limit headers at all. A 429 carries only ' +
+    '`x-ratelimit-reset` (seconds) with error types `dynamic_request_limited` / ' +
+    '`dynamic_token_limited`; a 503 signals the dynamic rate is at/below capacity. Because no ' +
+    'published figure justifies going higher, the ceiling is pinned at the kernel fallback in ' +
+    'EVERY dimension — 60 units / 60s at defaultWeight 2 = 30 calls/min — and the declaration ' +
+    'buys resolution DOWNWARD, never headroom: the inference endpoints cost 6, so at most 10 land ' +
+    'in a window. The window bounds the 60s AVERAGE and does not pace; the `x-ratelimit-reset` ' +
+    'cooldown is the backstop for a sub-second burst.',
+};
+
+// Declared at module load, so merely importing this module (which `togetherai-connector.ts`
+// does) is enough to arm the real ceiling.
+declareRateBudget(VENDOR, TOGETHERAI_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Together. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function togetheraiCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+  // `execute('post', …)` really does issue a POST and must be priced as one.
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/**
+ * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; NORMALIZED,
+ * because the anchored rules are otherwise trivially evaded: `fetch` upper-cases a known method
+ * before sending, so `execute('post', …)` issues a real WRITE that a `^POST ` rule would price as
+ * a read; and a trailing slash makes a path miss a `$` anchor while most routers treat it as the
+ * same endpoint.
+ */
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  // Collapse REPEATED slashes as well as a trailing one: `/v1//chat/completions` reaches the same
+  // endpoint on most routers but misses a `^POST /v1/(chat/completions|…)$` rule, which would
+  // price an inference call as a 2-unit read (the groq pack's §9 round one, NIT 14).
+  const raw = (at === -1 ? path : path.slice(0, at)).replace(/\/{2,}/g, '/');
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where Together's ledger lives. Token-keyed and cwd-independent by default (Together's limits
+ *  are per ORGANIZATION, i.e. per key, so a cwd-scoped ledger would hand the same key a fresh
+ *  allowance in every checkout, worktree and CI matrix leg); pass `root` for world-scoped
+ *  accounting. */
+export function togetheraiBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for Together's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type TogetheraiBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Together's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof TogetheraiBudget` in `liveTogetheraiExecute`
+ * means "a budget that accounts against TOGETHER's ledger under TOGETHER's ceiling".
+ */
+export class TogetheraiBudget extends RateBudget {
+  constructor(opts: TogetheraiBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as TogetheraiBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as TogetheraiBudgetErrorKind } from '@volter/world-core';
+export type TogetheraiBudgetReservation = RateBudgetReservation;
+export type TogetheraiBudgetSnapshot = RateBudgetSnapshot;