@volter/twin-openai 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,168 @@
+# @volter/twin-openai
+
+A local, faithful **OpenAI API** twin your real `openai` SDK talks to unmodified — point the
+SDK at the twin's `baseURL` and `chat.completions.create`, streaming, the Responses API,
+`embeddings`, `models`, `moderations`, `files`, `batches`, fine-tuning jobs, and vector stores
+all work. Built on the shared `@volter/twin` kernel (durable event/action log + projection);
+no parallel side store.
+
+```ts
+import OpenAI from 'openai';
+import { createOpenAITwinServer } from '@volter/twin-openai';
+
+const { port } = createOpenAITwinServer({});
+const client = new OpenAI({ apiKey: 'sk-twin', baseURL: `http://127.0.0.1:${port}/v1` });
+const res = await client.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+// res.choices[0].message.content starts with "[twin-stub:…]" — a deterministic stub, clearly labeled.
+```
+
+## The generative-stub design (be honest)
+
+The twin **cannot run the model** — there are no weights here. So `POST /v1/chat/completions`
+and `POST /v1/responses` return a **deterministic STUB completion** that is unmistakably a twin
+stub (it carries a `[twin-stub:<model>]` marker and echoes your prompt), and `POST /v1/embeddings`
+returns **deterministic pseudo-vectors** (seeded from the input hash). They **never** pretend to
+be real model output / real embedding values.
+
+What **is** faithful is the **entire protocol envelope**:
+
+- chat response shape — `{ id:'chatcmpl-…', object:'chat.completion', created, model, choices:[{index, message:{role:'assistant', content}, finish_reason}], usage:{prompt_tokens, completion_tokens, total_tokens}, system_fingerprint }`
+- **streaming** via SSE — real `data: {…chat.completion.chunk with choices[].delta…}` chunks ending with `data: [DONE]` (role chunk → content/tool_call deltas → finish_reason chunk; driven through an injected sink — no real sockets in the handler)
+- **tool / function calling** — `tool_calls` + `finish_reason:'tool_calls'` (and legacy `functions`)
+- `n`, `max_tokens` / `max_completion_tokens`, `stop`, `temperature`/`top_p` accepted; **deterministic usage**
+- **Responses API** — `POST /v1/responses` (`{ id:'resp_…', object:'response', output:[{type:'message', content:[{type:'output_text', text}]}], usage }`) + streaming events (`response.created` → `response.output_text.delta` → `response.completed` → `[DONE]`)
+- **Embeddings** — `{ object:'list', data:[{object:'embedding', index, embedding:[…]}], model, usage }` with faithful, L2-normalized, deterministic vectors (length controlled by `dimensions`)
+
+The genuinely **stateful + static** surface is real, not a stub:
+
+- `GET /v1/models` (+ `/v1/models/:id`) — static catalog
+- **Files** — `POST/GET/DELETE /v1/files` (+ list + `/content`), kernel-backed
+- **Batches** — `POST/GET /v1/batches` (+ list + cancel)
+- **Moderations** — `POST /v1/moderations` (deterministic keyword classifier; faithful shape)
+- **Fine-tuning jobs** — create / retrieve / list / cancel / events
+- **Vector stores** — create / retrieve / list / delete (+ file attach/list)
+- **Images** — `POST /v1/images/generations` returns the faithful response shape with a placeholder URL
+
+Vendor-shaped errors throughout: `400 invalid_request_error` (with `message`/`type`/`param`/`code`),
+`404`, `405` (read-only guard). (Auth is faked — any bearer key is accepted, like the other twins;
+real `401`/`429` are modeled as `todo` capabilities, not yet built.)
+
+## CLI
+
+```
+world-openai serve       [--port N] [--root DIR] [--read-only]   # the API twin (SDK target)
+world-openai conformance [--root DIR]                            # offline envelope checks
+```
+
+(OpenAI is an API-first vendor with no meaningful product UI worth mirroring — see
+ARCHITECTURE.md C1b — so this pack ships **no mirror**.)
+
+## Connector (pull / push)
+
+`syncOpenAIFromReal` pulls real files / batches / fine-tuning jobs / vector stores into the
+twin; `pushPendingOpenAIActions` pushes pending local writes (create / cancel / delete) to the
+real API and confirms them. All vendor I/O is over an **injected client**
+(`liveOpenAIExecute(apiKey)` live; a fake in tests) — the pack holds no key and imports no SDK
+at runtime.
+
+## Coverage
+
+The capability manifest (`openai-capabilities.ts`) enumerates the **real OpenAI API surface**
+as the honest denominator; `verify()` proves each `done` against the local twin, offline +
+deterministically. Run `bun scripts/twin-capabilities.ts openai` for the live numbers.
+
+### Done (proven, verifiable)
+- **Chat Completions** — create + faithful envelope, validation, labeled stub, `n` choices,
+  `max_tokens`/`max_completion_tokens` cap, system/developer messages, multi-turn, content-part
+  input, `stop`, `temperature` accepted, deterministic usage, `system_fingerprint`,
+  `response_format` json_object/json_schema (valid JSON content), `logprobs`+`top_logprobs`
+  (per-token pseudo-logprobs whose tokens re-join to the text), `seed` (distinct seed → distinct
+  id), `logit_bias` (accepted+validated), predicted outputs (`prediction`), `store`+`metadata`
+  (stored completions: retrieve / list / messages / delete)
+- **Streaming** — chunk sequence + `[DONE]`, content reconstruction, `finish_reason` chunk,
+  tool_call deltas, `stream_options.include_usage` final usage-only chunk
+- **Tools** — `tool_calls` + `finish_reason:'tool_calls'`, legacy `functions`, no-tools → text,
+  `tool_choice` (none/required/named), `parallel_tool_calls`, strict schema-typed arguments
+- **Responses API** — create + envelope, labeled stub, input-item array, validation, streaming,
+  stored-by-default retrieve/delete, `previous_response_id` chaining, input-items list
+- **Embeddings** — list envelope, determinism, batch, `dimensions`, L2-normalized, validation,
+  `encoding_format:'base64'` (Float32 base64 string decoding to the float vector)
+- **Models** — list (catalog + fine-tuned), retrieve (+404 `model_not_found`), delete a fine-tuned
+  model (base models refuse)
+- **Moderations** — faithful shape, deterministic flagging, batch
+- **Files** — upload / retrieve / list / content / delete, purpose-required
+- **Uploads** — create → add parts → complete (assembles a real File from the parts) / cancel
+- **Batches** — create / retrieve / list / cancel, validation, persistence
+- **Fine-tuning** — create / retrieve+list / events / cancel / validation / checkpoints
+- **Vector stores** — create / retrieve+list+delete / file attach+list / seed file_ids,
+  deterministic ranked search, file batches (bulk attach + retrieve + list batch files)
+- **Assistants (beta)** — assistants CRUD, threads + messages CRUD, runs (immediate stub
+  completion) + run steps + cancel
+- **Admin / org** — projects (create/retrieve/modify/list/archive), project API keys
+  (create with one-time synthetic secret / list / retrieve redacted / delete), usage + costs
+  reporting (`/v1/organization/usage/{completions,embeddings}` + `/v1/organization/costs`,
+  aggregated over REAL recorded usage rows — nothing hardcoded; empty with no traffic)
+- **Chat audio** — `input_audio` content parts accepted (count toward prompt_tokens), and
+  `modalities:['text','audio']` → an assistant `audio` envelope (id/data/transcript/expires_at);
+  the bytes are a labeled stub (no real speech synthesis), the shape is faithful
+- **Responses reasoning** — `reasoning.effort` (minimal/low/medium/high) → a faithful reasoning
+  output item (labeled-stub summary) + `usage.output_tokens_details.reasoning_tokens`
+- **Audio** — transcriptions (json/verbose_json/text), translations, text-to-speech (labeled stubs)
+- **Images** — generations shape (placeholder), validation, edits + variations (placeholder shape)
+- **Errors / protocol** — 404, `invalid_request_error` envelope, read-only 405 guard, modeled
+  auth (`401` on a missing/invalid credential when a request carries an auth surface; trusted
+  in-process + real-SDK calls pass), rate-limit `429` (deterministic opt-in trigger header →
+  vendor envelope + `Retry-After` + `x-ratelimit-*`), `Idempotency-Key` dedup (re-issue replays
+  the same response/id; a new key → a new result), cursor pagination (`after`/`limit` +
+  `has_more`/`first_id`/`last_id`)
+- **Connector** — read surface, pull+map (offline), push+confirm (offline), unsupported-op fails,
+  full bi-directional sync (push-then-pull, idempotent)
+- **Conformance** — offline envelope harness
+
+### Planned (todo — covered by default, not yet built)
+- **Evals API** — create/run/list evals + eval runs + output items
+- **Containers API** — containers + container files (code-interpreter sandboxes)
+- **Background responses** — `background:true` → queued status + poll + cancel
+- **Fine-tuning** — job pause / resume
+- **Webhooks** — event signature verification (signing-secret HMAC)
+
+### Out of scope (the honest carve-outs)
+- **`openai.chat.inference`** — *real model inference (generation from model weights).* The twin
+  returns a deterministic stub; the protocol envelope is faithful.
+- **`openai.embeddings.real_vectors`** — *real embedding values.* The twin returns deterministic
+  pseudo-vectors; the shape/dimensions/determinism are faithful.
+- **`openai.images.real_pixels`** — *real generated image bytes.* The response shape is faithful;
+  the URL is a placeholder.
+- **`openai.files.real_bytes`** — *arbitrary binary blob storage.* Metadata + supplied text
+  content are faithful; the twin is not a binary object store.
+- **`openai.responses.tools`** — *hosted built-in tools (web_search / computer_use /
+  code_interpreter).* These require live model + infrastructure side effects that cannot be
+  reproduced offline without fabricating output; user-defined function tools ARE modeled.
+- **`openai.audio.realtime`** — *Realtime API (WebSocket sessions).* A live bidirectional audio
+  socket to a running speech model — both the transport and the inference are irreproducible in
+  the offline, HTTP `verify()` harness.
+
+Everything else is covered by default and is either done or planned.
+
+## Rate budget — the fail-closed backstop on live calls
+
+`liveOpenAIExecute` is the **one place** this pack issues a live request, so every call it makes is charged
+against a persistent, fail-closed spend ledger **before** the request goes out. Past the ceiling, or
+while a `Retry-After`/429 cooldown is armed, it **throws instead of calling**. The ledger is keyed by
+vendor and a hash of the credential (limits are per credential, so it is deliberately *not*
+cwd-scoped) and persists across processes, so a fresh process does not get a fresh allowance; a
+corrupt ledger counts as a **full** window rather than zero spend. There is no option to disable it,
+and no value you can pass for `budget` that yields an unguarded client — an injected budget is
+validated by *method identity*, so a subclass or a `Proxy` that replaces `checkBudget` is refused.
+
+The declared numbers: **60 weighted units / 60s at weight 2 = 30 calls/minute — exactly the kernel's austere fallback**, because OpenAI publishes *no* scalar per-key request limit (limits are per org/project, per model, per tier, and live only on the account's limits page). The one documented scalar that can bind this pack is Vector Store ingestion at 300 requests/minute per store. The declaration therefore buys **resolution, not headroom**: inference paths cost 5, vector-store ingestion 4, and nothing is cheaper than the fallback would price it.
+
+The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/twin` →
+`control-plane/src/rateBudget.ts`); what lives here in [`src/openai-budget.ts`](src/openai-budget.ts) is this vendor's
+**declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
+the vendor-bound `OpenAIBudget`. The rule is ratified as
+[ARCHITECTURE.md](../../../ARCHITECTURE.md) **D8**, and the kernel module's header documents what the
+guard does *not* guarantee — read that before trusting it.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@volter/twin-openai",
+  "version": "0.1.0",
+  "description": "Local OpenAI twin \u2014 a faithful, stateful local OpenAI API your real `openai` SDK talks to unmodified. The model is stubbed (deterministic) and embeddings are deterministic pseudo-vectors, but the protocol envelope (chat completions/streaming/tool_calls, the Responses API, embeddings, models, files, batches, moderations, fine-tuning, vector stores) is vendor-faithful. Built on @volter/twin.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "openai",
+    "gpt",
+    "llm"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/openai"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/openai#readme",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "world-openai": "src/cli.ts"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@volter/twin": "0.1.0"
+  },
+  "devDependencies": {
+    "@volter/twin": "workspace:*",
+    "@volter/twin-tooling": "workspace:*",
+    "openai": "^4.104.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+import { keepProcessAlive } from '@volter/twin/lifecycle';
+// world-openai CLI: serve the OpenAI API twin or run conformance. OpenAI is an API-first
+// vendor with no meaningful product UI worth mirroring (ARCHITECTURE.md C1b), so this pack
+// ships no mirror.
+import { hasFlag, optionValue } from '@volter/twin/args';
+import { createOpenAITwinServer } from './openai-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
+
+if (cmd === 'serve') {
+  const s = createOpenAITwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`openai twin (chat/responses/embeddings output is a deterministic stub)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/twin-tooling
+  const { checkOpenAIConformance } = await import('./openai-conformance.ts');
+  const report = await checkOpenAIConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-openai serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+// @volter/twin-openai — the OpenAI twin (one vendor, one package), built on the shared
+// @volter/twin kernel. The OpenAI API: a vendor-faithful protocol envelope (chat
+// completions/streaming/tool_calls, the Responses API, embeddings), a static models catalog,
+// deterministic moderations, and STATEFUL files / batches / fine-tuning jobs / vector stores —
+// over an event/action log. (OpenAI is an API-first vendor with no meaningful product UI worth
+// mirroring — ARCHITECTURE.md C1b — so this pack ships no mirror.)
+//
+// THE HONEST CARVE-OUTS: the twin cannot run the model, so POST /v1/chat/completions and
+// /v1/responses return a DETERMINISTIC STUB completion (clearly labeled), and /v1/embeddings
+// returns DETERMINISTIC pseudo-vectors — never pretending to be real inference. Everything
+// around them — the wire protocol — is faithful. (Conformance + capability tooling live in
+// @volter/twin-tooling, a dev dependency — NOT re-exported here, per E2.)
+export { handleOpenAITwinRequest, streamChat, streamResponse } from './openai-twin.ts';
+export type { OpenAIRequest, OpenAIResponseEnvelope } from './openai-twin.ts';
+export { createOpenAITwinFetch, createOpenAITwinServer } from './openai-server.ts';
+export type { OpenAITwinFetchOptions } from './openai-server.ts';
+export { OPENAI_MODELS, findModel } from './openai-models.ts';
+export type { OpenAIModel } from './openai-models.ts';
+export {
+  countPromptTokens, estimateTokens, stubAssistantText, stubToolCall, contentToText, lastUserText,
+  pseudoEmbedding, moderateText, MODERATION_CATEGORIES,
+} from './openai-stub.ts';
+export type { ModerationResult } from './openai-stub.ts';
+export type {
+  ChatMessageParam, ChatToolCall, ChatCompletion, ChatChoice, ChatUsage,
+  OpenAIResponse, EmbeddingResponse, Embedding, OpenAIError, SseEvent, SseSink,
+} from './openai-types.ts';
+export {
+  openaiRequestForAction,
+  liveOpenAIExecute,
+  mapFile,
+  mapBatch,
+  mapFineTune,
+  mapVectorStore,
+  pullOpenAIState,
+  pushOpenAIAction,
+  pushPendingOpenAIActions,
+  syncOpenAIFromReal,
+  fullSyncOpenAI,
+} from './openai-connector.ts';
+export type { OpenAIExecute, LiveOpenAIOptions } from './openai-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveOpenAIExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is OpenAI'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
+// `OpenAIBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  OPENAI_BUDGET_CEILING,
+  OPENAI_BUDGET_MAX_RETRY_AFTER_S,
+  OPENAI_BUDGET_WINDOW_MS,
+  OPENAI_CALL_WEIGHTS,
+  OPENAI_RATE_BUDGET,
+  OpenAIBudget,
+  OpenAIBudgetError,
+  openaiBudgetPath,
+  openaiCallWeight,
+} from './openai-budget.ts';
+export type { OpenAIBudgetErrorKind, OpenAIBudgetOptions, OpenAIBudgetReservation, OpenAIBudgetSnapshot } from './openai-budget.ts';
+export {
+  verifyOpenAIWebhook,
+  computeOpenAIWebhookSignature,
+  buildSignedOpenAIWebhook,
+  OpenAIWebhookVerificationError,
+  OPENAI_WEBHOOK_EVENT_TYPES,
+} from './openai-webhooks.ts';
+export type { OpenAIWebhookEvent } from './openai-webhooks.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import type { TwinPack } from '@volter/twin';
+import { OPENAI_RATE_BUDGET as RATE_BUDGET } from './openai-budget.ts';
+export const pack: TwinPack = {
+  vendor: 'openai',
+  // The SAME object openai-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-openai',
+  resources: ['file', 'batch', 'fine_tuning_job', 'vector_store', 'vector_store_file', 'response'],
+  specSource: 'OpenAI API (envelope-faithful; model output is a deterministic stub, embeddings are deterministic pseudo-vectors)',
+  description: 'OpenAI API twin — faithful protocol envelope (chat completions/streaming/tool_calls, Responses API, embeddings), models, moderations, stateful files/batches/fine-tuning/vector stores; generative output is a labeled stub.',
+  // Adoption + interception, all in the pack's one home (TWIN-PACK-CONTRACT back-migration
+  // 2026-08-31; the bare `openai` stem and both SDK names moved off the central maps unchanged).
+  // The stems are the bare OPENAI_* pair plus the credential-var shapes real apps use beside it
+  // (AP_OPENAI_*, OPENAI_MODERATION_*).
+  adoption: {
+    // OpenAI's official Python library and Agents SDK. THE DISTRIBUTION IS THE CLAIM: `openai` stays
+    // this pack's even when a caller points it at DeepSeek, xAI, OpenRouter, Perplexity, an AI Gateway
+    // or an Azure OpenAI endpoint - those packs claim the ENDPOINT ENV that routes it, never this name.
+    // `tiktoken` is deliberately UNCLAIMED: it is a local tokenizer that makes no API call at all.
+    pypi: ['openai', 'openai-agents'],
+    sdks: ['openai', '@ai-sdk/openai'],
+    // 'REWORKDPLATFORMOPENAI' — AgentGPT names its key REWORKD_PLATFORM_OPENAI_API_KEY, the same
+    // app-prefixed shape as APOPENAI (ladder classification 2026-09-02). Deliberately NOT
+    // 'OPENAIOAUTH': postiz's OPENAI_OAUTH_CLIENT_ID is the client id its own MCP OAuth SERVER
+    // accepts from the ChatGPT connector — inbound, no api.openai.com call — so it is ruled
+    // not-a-vendor in the packless registry instead.
+    envStems: ['OPENAI', 'APOPENAI', 'OPENAIMODERATION', 'REWORKDPLATFORMOPENAI'],
+  },
+  // The whole REST surface the `openai` SDK talks to uses one base, https://api.openai.com — the
+  // same default the pack's own connector pins (openai-connector.ts).
+  hosts: [{ host: 'api.openai.com' }],
+  // The SDK calls the same-origin '/v1/…' and loads from api.openai.com — the dev proxy
+  // forwards '/v1/' to the twin and strips the absolute host so calls come back same-origin.
+  browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.openai.com' },
+};
+export { createOpenAIScenarioEngine, loadOpenAIScenarioDocument, openaiScenarioAdapter, realizeOpenAIRespond } from './openai-scenario.ts';
+export type { OpenAIScenarioEngine, OpenAIScenarioRequest, OpenAIScenarioRespond } from './openai-scenario.ts';