@volter/twin-openai 0.1.1 → 2.0.0

package/src/openai-conformance.ts

@@ -5,7 +5,7 @@
 // the Responses API, embeddings, models, files, batches, moderations, and the error envelope.
 // Fully offline + deterministic (drives the local handler against a temp root) so it runs in
 // CI without an API key. Honest scope: it checks the protocol envelope, NOT model output
-// (a deterministic stub by design — see the out-of-scope carve-outs in the manifest).
+// (a deterministic stub by design — the labeled stub is the twin's answer).
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';

package/src/openai-connector.ts

@@ -12,9 +12,9 @@
 // The vendor I/O is an INJECTED executor (B3 auth boundary): the kernel + this pack hold NO
 // OpenAI key and import NO SDK at runtime. Tests pass a fake executor; live runs pass
 // `liveOpenAIExecute(apiKey)`. Same code path either way — fully exercisable offline.
-import { assertBudgetGuardIntact, confirmAction, pendingActions, syncPull } from '@volter/twin';
-import type { SyncResource, TwinAction } from '@volter/twin';
-import { OpenAIBudget, openaiCallWeight, type OpenAIBudgetOptions } from './openai-budget.ts';
+import { assertBudgetGuardIntact, type RemoteExecute, type PerformContext, type PushOutcome, observeResource } from '@volter/world-core';
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { OpenAIBudget, OpenAIBudgetError, openaiCallWeight, type OpenAIBudgetOptions } from './openai-budget.ts';
 
 const SERVICE = 'openai';
 
@@ -101,7 +101,14 @@ export function liveOpenAIExecute(
     // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
     // `retry-after` beyond the cap is not something to sleep off) — the cooldown is persisted
     // first either way, so the refusal survives the throw.
-    budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer OpenAI ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof OpenAIBudgetError) || !res.ok) throw error;
+    }
     return parsed;
   };
 }
@@ -212,8 +219,10 @@ export async function syncOpenAIFromReal(
   opts: { root?: string; occurredAt: string },
 ): Promise<{ observed: number; deltasAppended: number }> {
   const resources = await pullOpenAIState(execute);
-  const result = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-  return { observed: result.observed, deltasAppended: result.deltasAppended };
+  // PROTOCOL 2: the pack observes each resource; the kernel diffs it against the tree and folds what changed
+  let appended = 0;
+  for (const r of resources) appended += observeResource(SERVICE, { type: r.type, id: r.id, fields: r.fields }, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt }).appended;
+  return { observed: resources.length, deltasAppended: appended };
 }
 
 // ── PUSH ────────────────────────────────────────────────────────────────────
@@ -295,43 +304,31 @@ function createPayload(action: Pick<TwinAction, 'subject' | 'fields'>): Record<s
   }
 }
 
-/**
- * Push the twin's PENDING local actions to real OpenAI and CONFIRM each: for every pending
- * action, call the real API; on success, confirmAction records the confirmed fields as an
- * observed event and maps action → event (suppressing the local projection — counted exactly
- * once). Idempotency: a confirmed action is no longer pending, so a re-push enacts NOTHING.
- */
-export async function pushPendingOpenAIActions(
-  execute: OpenAIExecute,
-  opts: { root?: string; occurredAt: string },
-): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
-  const confirmed: string[] = [];
-  const externalIds: Record<string, string> = {};
-  for (const action of pendingActions(SERVICE, opts.root)) {
-    const { externalId } = await pushOpenAIAction(execute, action);
-    confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-    confirmed.push(action.id);
-    externalIds[action.id] = externalId;
-  }
-  return { pushed: confirmed.length, confirmed, externalIds };
+
+
+// ── THE PERFORM ADAPTER (protocol 2, state-system.ts) ─────────────────────────────────────────
+// One entry against the real account over the kernel executor. A generative vendor's change is
+// the CALL: a recorded completion crosses as the same request (its model and messages), and the
+// vendor's completion id is the receipt. The account-shaped writes (files, batches, fine-tuning
+// jobs, vector stores) cross through `pushOpenAIAction` as before. The credential never enters
+// this file: the executor applies it.
+export function openaiExecuteOver(execute: RemoteExecute): OpenAIExecute {
+  return async (method, path, body) => {
+    const res = await execute({ method, path, headers: { 'content-type': 'application/json' }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    try { return JSON.parse(res.body) as Awaited<ReturnType<OpenAIExecute>>; } catch { return { error: { message: `openai answered ${res.status} with a body that is not JSON` } }; }
+  };
 }
 
-// ── FULL bi-directional sync ─────────────────────────────────────────────────
-/**
- * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to
- * real OpenAI and confirm it, then (2) PULL all modeled collections back and fold them into the
- * event log. Pushing first means the pull observes the twin's own writes as confirmed external
- * state (no double-count). Re-running with no pending writes and identical real state is a
- * no-op (push 0, deltasAppended 0). Same code path offline (fake executor) and live (real key).
- */
-export async function fullSyncOpenAI(
-  execute: OpenAIExecute,
-  opts: { root?: string; occurredAt: string },
-): Promise<{ pushed: number; observed: number; deltasAppended: number; collections: number }> {
-  // 1. PUSH pending local changes to real OpenAI (and confirm each).
-  const push = await pushPendingOpenAIActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-  // 2. PULL all modeled collections back into the twin.
-  const resources = await pullOpenAIState(execute);
-  const pull = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-  return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.deltasAppended, collections: COLLECTIONS.length };
+export async function performOpenAIAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  if (action.subject.type === 'chat_completion') {
+    const f = (action.fields ?? {}) as Record<string, unknown>;
+    const messages = Array.isArray(f._input_messages) ? (f._input_messages as Array<{ role: string; content: unknown }>).map((m) => ({ role: m.role, content: m.content })) : [];
+    const res = await openaiExecuteOver(execute)('POST', '/v1/chat/completions', { model: f.model, messages, ...(f._stored === true ? { store: true } : {}) });
+    throwIfError(res, 'perform chat.completions.create');
+    const id = (res as { id?: unknown }).id;
+    // the vendor's completion is the answer: it rides on the receipt and reaches the app under live use
+    return { externalId: typeof id === 'string' && id ? id : action.subject.id, data: res as Record<string, unknown> };
+  }
+  const { externalId } = await pushOpenAIAction(openaiExecuteOver(execute), action);
+  return { externalId };
 }

package/src/openai-media.ts

@@ -0,0 +1,225 @@
+// The media an image or audio endpoint takes and gives. OpenAI takes an uploaded image or audio file only in the
+// formats its reference names, told by the file's bytes, and a GPT image model answers the image itself as base64:
+//   • an image to edit is "a `png`, `webp`, or `jpg` file" for the GPT image models, and for `dall-e-2` "a square
+//     `png`" (developers.openai.com/api/reference/resources/images/methods/edit, `image`); a variation's is "a valid
+//     PNG file, less than 4MB, and square" (…/images/methods/create_variation, `image`);
+//   • a transcription or translation takes "the audio file object (not file name)" in "one of these formats: flac,
+//     mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm" (…/audio/subresources/transcriptions/methods/create, `file`);
+//   • the GPT image models "always return base64-encoded images" (…/images/methods/generate, `response_format`).
+// Where the documentation stops and the twin decides: a format is told by its signature bytes; the image the twin
+// answers is a real PNG of the requested size in one flat colour drawn from the prompt, labeled in its own text
+// chunk, since the twin renders no pixels.
+import { createHash } from 'node:crypto';
+import { deflateSync } from 'node:zlib';
+
+/** The raw bytes of an uploaded file part, as the request's multipart parse keeps them; undefined for a string. */
+export function partBytes(v: unknown): Uint8Array | undefined {
+  const b = v && typeof v === 'object' ? (v as { bytes?: unknown }).bytes : undefined;
+  return b instanceof Uint8Array ? b : undefined;
+}
+
+const has = (b: Uint8Array, sig: string | number[], at = 0): boolean =>
+  (typeof sig === 'string' ? [...sig].map((c) => c.charCodeAt(0)) : sig).every((x, i) => b[at + i] === x);
+
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/** Each image format a signature tells, checked in this order. */
+const IMAGE: Array<['png' | 'jpg' | 'webp', (b: Uint8Array) => boolean]> = [
+  ['jpg', (b) => has(b, [0xff, 0xd8, 0xff])],
+  ['webp', (b) => has(b, 'RIFF') && has(b, 'WEBP', 8)],
+  ['png', (b) => has(b, PNG) && has(b, 'IHDR', 12)],
+];
+/** An image's format by its signature: png, jpg or webp, else undefined. */
+export const imageFormat = (b: Uint8Array): 'png' | 'jpg' | 'webp' | undefined => IMAGE.find(([, is]) => is(b))?.[0];
+
+/** A PNG's width and height from its IHDR chunk. */
+export function pngSize(b: Uint8Array): { width: number; height: number } {
+  const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  return { width: v.getUint32(16), height: v.getUint32(20) };
+}
+
+/** Each audio format OpenAI transcribes that a signature tells, checked in this order. */
+const AUDIO: Array<[string, (b: Uint8Array) => boolean]> = [
+  ['flac', (b) => has(b, 'fLaC')],
+  ['ogg', (b) => has(b, 'OggS')],
+  ['webm', (b) => has(b, [0x1a, 0x45, 0xdf, 0xa3])],
+  ['mp4', (b) => has(b, 'ftyp', 4)],
+  ['mp3', (b) => has(b, 'ID3') || (b[0] === 0xff && ((b[1] ?? 0) & 0xe0) === 0xe0)],
+  ['wav', (b) => has(b, 'RIFF') && has(b, 'WAVE', 8)],
+];
+/** An audio file's format by its signature, among those OpenAI transcribes, else undefined. */
+export const audioFormat = (b: Uint8Array): string | undefined => AUDIO.find(([, is]) => is(b))?.[0];
+
+/** A WAV file's length in seconds, from its `fmt ` byte rate and its `data` size (RIFF chunks in any order); undefined
+ *  for any other format, whose length the twin does not read. */
+export function wavSeconds(b: Uint8Array): number | undefined {
+  if (!has(b, 'RIFF') || !has(b, 'WAVE', 8)) return undefined;
+  const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  let rate = 0;
+  let data = 0;
+  for (let at = 12; at + 8 <= b.length; at += 8 + v.getUint32(at + 4, true) + (v.getUint32(at + 4, true) & 1)) {
+    if (has(b, 'fmt ', at)) rate = v.getUint32(at + 16, true);
+    if (has(b, 'data', at)) data = v.getUint32(at + 4, true);
+  }
+  return rate > 0 ? Math.round((data / rate) * 1000) / 1000 : undefined;
+}
+
+const CRC = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+function crc32(b: Uint8Array): number {
+  let c = 0xffffffff;
+  for (const x of b) c = CRC[(c ^ x) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const out = new Uint8Array(12 + data.length);
+  const v = new DataView(out.buffer);
+  v.setUint32(0, data.length);
+  out.set([...type].map((c) => c.charCodeAt(0)), 4);
+  out.set(data, 8);
+  v.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+  return out;
+}
+
+/** The size an image request asks for (`1536x1024`), or the fallback for `auto` or none. */
+export function requestedSize(size: unknown, fallback: { width: number; height: number } = { width: 1024, height: 1024 }): { width: number; height: number } {
+  const m = typeof size === 'string' ? /^(\d+)x(\d+)$/.exec(size) : null;
+  return m ? { width: Number(m[1]), height: Number(m[2]) } : fallback;
+}
+
+/** A real PNG of the size asked, one flat colour drawn from `seed`, labeled as the twin's placeholder. */
+export function placeholderPng(size: { width: number; height: number }, seed: string): Uint8Array {
+  const [r, g, bl] = createHash('sha256').update(seed).digest();
+  const { width, height } = size;
+  const ihdr = new Uint8Array(13);
+  const v = new DataView(ihdr.buffer);
+  v.setUint32(0, width);
+  v.setUint32(4, height);
+  ihdr.set([8, 2, 0, 0, 0], 8); // 8-bit RGB, no interlace
+  const row = new Uint8Array(1 + width * 3);
+  for (let x = 0; x < width; x++) row.set([r!, g!, bl!], 1 + x * 3);
+  const raw = new Uint8Array(row.length * height);
+  for (let y = 0; y < height; y++) raw.set(row, y * row.length);
+  const text = new TextEncoder().encode(`Comment\0[twin-stub] placeholder image, no model is run: ${seed}`);
+  const parts = [Uint8Array.from(PNG), chunk('IHDR', ihdr), chunk('tEXt', text), chunk('IDAT', new Uint8Array(deflateSync(raw))), chunk('IEND', new Uint8Array(0))];
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+
+/** Bytes as base64. */
+export function base64(b: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < b.length; i += 0x8000) bin += String.fromCharCode(...b.subarray(i, i + 0x8000));
+  return btoa(bin);
+}
+
+// ── Speech: the audio file itself ────────────────────────────────────────────────────────────────────────────────
+// Text to speech answers "the audio file content" in the requested `response_format`, `mp3` by default, of mp3, opus,
+// aac, flac, wav and pcm (developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create); its
+// audio is 24 kHz mono. The twin speaks nothing: each is a real file of that format, a second of silence.
+const RATE = 24000;
+
+/** A second of 24 kHz 16-bit mono silence as samples' bytes: `pcm`, raw little-endian with no header. */
+export const silentPcm = (): Uint8Array => new Uint8Array(RATE * 2);
+
+/** The same second as a WAV file. */
+export function silentWav(): Uint8Array {
+  const data = RATE * 2;
+  const b = new Uint8Array(44 + data);
+  const v = new DataView(b.buffer);
+  b.set(ascii('RIFF'), 0); v.setUint32(4, 36 + data, true); b.set(ascii('WAVEfmt '), 8);
+  v.setUint32(16, 16, true); v.setUint16(20, 1, true); v.setUint16(22, 1, true); v.setUint32(24, RATE, true); v.setUint32(28, RATE * 2, true); v.setUint16(32, 2, true); v.setUint16(34, 16, true);
+  b.set(ascii('data'), 36); v.setUint32(40, data, true);
+  return b;
+}
+
+/** The same second as MP3: MPEG-2 Layer III frames at 24 kHz, 32 kbit/s, mono, each 576 samples in 96 bytes whose
+ *  side information codes no spectral data, which a decoder plays as silence. */
+export function silentMp3(): Uint8Array {
+  const frames = Math.ceil(RATE / 576);
+  const b = new Uint8Array(frames * 96);
+  for (let i = 0; i < frames; i++) b.set([0xff, 0xf3, 0x44, 0xc4], i * 96);
+  return b;
+}
+
+/** The same second as FLAC: a STREAMINFO block and frames of 4096 samples, each one CONSTANT subframe of zero. */
+export function silentFlac(): Uint8Array {
+  const block = 4096;
+  const info = new Bits();
+  info.put(block, 16); info.put(block, 16); info.put(0, 24); info.put(0, 24);
+  info.put(RATE, 20); info.put(0, 3); info.put(15, 5); info.put(0, 4); info.put(RATE, 32);
+  for (let i = 0; i < 16; i++) info.put(0, 8); // MD5 unknown
+  const out: number[] = [...ascii('fLaC'), 0x80, 0, 0, 34, ...info.bytes()];
+  for (let n = 0, left = RATE; left > 0; n++, left -= block) {
+    const size = Math.min(block, left);
+    // blocksize 4096 (code 12) or, for the last, 16 bits of size-1 at the header's end (code 7); 24 kHz is code 7
+    const head = [0xff, 0xf8, ((size === block ? 12 : 7) << 4) | 7, 0x08, n, ...(size === block ? [] : [(size - 1) >> 8, (size - 1) & 0xff])];
+    const frame = [...head, crc8(head), 0x00, 0x00, 0x00];
+    const c = crc16(frame);
+    out.push(...frame, c >> 8, c & 0xff);
+  }
+  return Uint8Array.from(out);
+}
+
+/** The same second as AAC in ADTS: AAC-LC frames of 1024 samples at 24 kHz, mono, each one channel element with
+ *  no scale-factor bands, which a decoder plays as silence. */
+export function silentAac(): Uint8Array {
+  const payload = [0x00, 0x00, 0x00, 0x07]; // SCE, global gain 0, max_sfb 0, no tools; END
+  const length = 7 + payload.length;
+  const frame = new Bits();
+  frame.put(0xfff, 12); frame.put(0, 1); frame.put(0, 2); frame.put(1, 1); // MPEG-4, no CRC
+  frame.put(1, 2); frame.put(6, 4); frame.put(0, 1); frame.put(1, 3); // AAC-LC, 24 kHz, mono
+  frame.put(0, 4); frame.put(length, 13); frame.put(0x7ff, 11); frame.put(0, 2);
+  const one = [...frame.bytes(), ...payload];
+  return Uint8Array.from(Array.from({ length: Math.ceil(RATE / 1024) }, () => one).flat());
+}
+
+/** The same second as Opus in Ogg: its identification and comment headers, then 20 ms packets of silence. */
+export function silentOpus(): Uint8Array {
+  const head = [...ascii('OpusHead'), 1, 1, 0x38, 0x01, ...le32(RATE), 0, 0, 0];
+  const tags = [...ascii('OpusTags'), ...le32(4), ...ascii('twin'), ...le32(0)];
+  const packets = Array.from({ length: 50 }, () => [0xf8, 0xff, 0xfe]);
+  return Uint8Array.from([...oggPage(0x02, 0, 0, [head]), ...oggPage(0, 0, 1, [tags]), ...oggPage(0x04, 312 + 48000, 2, packets)]);
+}
+
+const ascii = (s: string): number[] => [...s].map((c) => c.charCodeAt(0));
+const le32 = (n: number): number[] => [n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >>> 24) & 0xff];
+
+/** A big-endian bit writer. */
+class Bits {
+  private out: number[] = [];
+  private acc = 0;
+  private n = 0;
+  put(value: number, bits: number): void {
+    for (let i = bits - 1; i >= 0; i--) {
+      this.acc = (this.acc << 1) | (Math.floor(value / 2 ** i) & 1);
+      if (++this.n === 8) { this.out.push(this.acc); this.acc = 0; this.n = 0; }
+    }
+  }
+  bytes(): number[] { return this.out; }
+}
+
+function crc8(b: number[]): number {
+  let c = 0;
+  for (const x of b) { c ^= x; for (let k = 0; k < 8; k++) c = c & 0x80 ? ((c << 1) ^ 0x07) & 0xff : (c << 1) & 0xff; }
+  return c;
+}
+function crc16(b: number[]): number {
+  let c = 0;
+  for (const x of b) { c ^= x << 8; for (let k = 0; k < 8; k++) c = c & 0x8000 ? ((c << 1) ^ 0x8005) & 0xffff : (c << 1) & 0xffff; }
+  return c;
+}
+/** One Ogg page of stream 1 holding whole packets, its CRC over the page with the field zeroed. */
+function oggPage(flags: number, granule: number, seq: number, packets: number[][]): number[] {
+  const lacing = packets.flatMap((p) => [...Array(Math.floor(p.length / 255)).fill(255), p.length % 255]);
+  const page = [...ascii('OggS'), 0, flags, ...le32(granule), 0, 0, 0, 0, ...le32(1), ...le32(seq), 0, 0, 0, 0, lacing.length, ...lacing, ...packets.flat()];
+  let c = 0;
+  for (const x of page) { c ^= x << 24; for (let k = 0; k < 8; k++) c = c & 0x80000000 ? ((c << 1) ^ 0x04c11db7) >>> 0 : (c << 1) >>> 0; }
+  page.splice(22, 4, ...le32(c));
+  return page;
+}

package/src/openai-models.ts

@@ -10,27 +10,157 @@ export type OpenAIModel = {
   object: 'model';
   created: number;
   owned_by: string;
+  /** When the model shuts down, or null when no date is announced (https://platform.openai.com/docs/api-reference/models/object) */
+  shutdown_date: string | null;
 };
 
-// A faithful slice of the published catalog (ids are the exact vendor strings).
+// OpenAI's timeline, as data (the catalog, each API family's removal, and the dated policy changes).
+//
+// Every model the pack's walks name, with its release (`created`) and its shutdown. Sources: the changelog
+// (https://developers.openai.com/api/docs/changelog) dates a release: "Released GPT-6 Astra" 2026-09-03, "Released GPT
+// Image 2.5 Sunburst and GPT Image 2.5 Flare" 2026-09-08, "Released GPT-5.2" 2025-12-11, "Released gpt-image-1.5"
+// 2025-12-16, "Added a new image generation model, `gpt-image-1`" 2025-04-23, "Released GPT-5 family of models"
+// 2025-08-07, "Added two new o-series reasoning models, `o3` and `o4-mini`" 2025-04-16, "Launched o3-mini" 2025-01-31,
+// "Added `gpt-4o-mini-tts`, `gpt-4o-transcribe`..." 2025-03-20, "Released GPT-4o mini" 2024-07-18, "Released new
+// `omni-moderation-latest`" 2024-09-26. The deprecations page (https://developers.openai.com/api/docs/deprecations) dates
+// a shutdown: gpt-3.5-turbo, gpt-4-turbo, o4-mini, o3-mini and gpt-image-1 on 2026-10-23; dall-e-2 and dall-e-3 on
+// 2026-05-12; gpt-image-1.5 on 2026-12-01; whisper-1 and the gpt-4o transcribe models on 2027-02-26.
+// Where neither page dates a release, `created` is the value OpenAI's own model object answers (the earlier catalog's
+// entries, and dall-e-2's and tts-1's). Extrapolation: gpt-4o-transcribe-diarize's release is documented nowhere the twin could
+// read; it is dated with the transcribe family it belongs to (2025-03-20).
+const model = (id: string, created: number, shutdown_date: string | null = null, owned_by = 'system'): OpenAIModel => ({ id, object: 'model', created, owned_by, shutdown_date });
 export const OPENAI_MODELS: OpenAIModel[] = [
-  { id: 'gpt-4o', object: 'model', created: 1715367049, owned_by: 'system' },
-  { id: 'gpt-4o-mini', object: 'model', created: 1721172741, owned_by: 'system' },
-  { id: 'gpt-4.1', object: 'model', created: 1744316542, owned_by: 'system' },
-  { id: 'gpt-4.1-mini', object: 'model', created: 1744317547, owned_by: 'system' },
-  { id: 'gpt-4-turbo', object: 'model', created: 1712361441, owned_by: 'system' },
-  { id: 'o3', object: 'model', created: 1744225308, owned_by: 'system' },
-  { id: 'o4-mini', object: 'model', created: 1744225351, owned_by: 'system' },
-  { id: 'gpt-3.5-turbo', object: 'model', created: 1677610602, owned_by: 'openai' },
-  { id: 'text-embedding-3-small', object: 'model', created: 1705948997, owned_by: 'system' },
-  { id: 'text-embedding-3-large', object: 'model', created: 1705953180, owned_by: 'system' },
-  { id: 'text-embedding-ada-002', object: 'model', created: 1671217299, owned_by: 'openai-internal' },
-  { id: 'dall-e-3', object: 'model', created: 1698785189, owned_by: 'system' },
-  { id: 'whisper-1', object: 'model', created: 1677532384, owned_by: 'openai-internal' },
-  { id: 'omni-moderation-latest', object: 'model', created: 1731689265, owned_by: 'system' },
+  model('gpt-6-astra', 1788393600, null, 'openai'),
+  model('gpt-5.2', 1765411200),
+  model('gpt-5', 1754524800),
+  model('gpt-4o', 1715367049),
+  model('gpt-4o-mini', 1721172741),
+  model('gpt-4o-mini-2024-07-18', 1721260800),
+  model('gpt-4.1', 1744316542),
+  model('gpt-4.1-mini', 1744317547),
+  model('gpt-4-turbo', 1712361441, '2026-10-23'),
+  model('o3', 1744761600),
+  model('o4-mini', 1744761600, '2026-10-23'),
+  model('o3-mini', 1738281600, '2026-10-23'),
+  model('gpt-3.5-turbo', 1677610602, '2026-10-23', 'openai'),
+  model('text-embedding-3-small', 1705948997),
+  model('text-embedding-3-large', 1705953180),
+  model('text-embedding-ada-002', 1671217299, null, 'openai-internal'),
+  model('dall-e-2', 1698798177, '2026-05-12'),
+  model('dall-e-3', 1698785189, '2026-05-12'),
+  model('gpt-image-1', 1745366400, '2026-10-23'),
+  model('gpt-image-1.5', 1765843200, '2026-12-01'),
+  model('gpt-image-2.5-flare', 1788825600),
+  model('whisper-1', 1677532384, '2027-02-26', 'openai-internal'),
+  model('gpt-4o-transcribe', 1742428800, '2027-02-26'),
+  model('gpt-4o-mini-transcribe', 1742428800, '2027-02-26'),
+  model('gpt-4o-transcribe-diarize', 1742428800, '2027-02-26'),
+  model('tts-1', 1681940951, null, 'openai-internal'),
+  model('gpt-4o-mini-tts', 1742428800),
+  model('omni-moderation-latest', 1727308800),
+];
+
+/** The instant a shutdown date takes effect: "At the time of the shut down, the model or endpoint will no longer be
+ *  accessible" (the deprecations page); the twin takes the date's first instant, UTC. */
+export const shutdownAt = (date: string): number => Date.parse(`${date}T00:00:00Z`) / 1000;
+
+/** Whether a catalogued model is live at the World instant `now` (unix seconds): released, and not yet shut down. A model
+ *  the catalog does not hold is not live: it does not exist. */
+export function live(id: string, now: number): boolean {
+  const m = OPENAI_MODELS.find((x) => x.id === id);
+  return !!m && m.created <= now && (m.shutdown_date === null || now < shutdownAt(m.shutdown_date));
+}
+
+/** The API families OpenAI removed, by the operations they serve, and the instant each is gone: the Assistants API on
+ *  2026-08-26 ("removal from the API one year later, on August 26, 2026"), the Evals API on 2026-11-30 ("The Evals
+ *  dashboard and API are scheduled to shut down"), its evals read-only from 2026-10-31 ("Existing evals become
+ *  read-only") (https://developers.openai.com/api/docs/deprecations). */
+export const REMOVED_FAMILIES: Array<{ family: string; removed: string; operations: RegExp; readOnlyFrom?: string; writes?: RegExp }> = [
+  { family: 'Assistants API', removed: '2026-08-26', operations: /^(createAssistant|listAssistants|getAssistant|modifyAssistant|deleteAssistant|createThread|createThreadAndRun|getThread|modifyThread|deleteThread|createMessage|listMessages|getMessage|modifyMessage|deleteMessage|createRun|listRuns|getRun|modifyRun|cancelRun|submitToolOuputsToRun|listRunSteps|getRunStep)$/ },
+  { family: 'Evals API', removed: '2026-11-30', operations: /^(createEval|listEvals|getEval|updateEval|deleteEval|createEvalRun|getEvalRuns|getEvalRun|cancelEvalRun|deleteEvalRun|getEvalRunOutputItems|getEvalRunOutputItem)$/, readOnlyFrom: '2026-10-31', writes: /^(createEval|updateEval|deleteEval|createEvalRun|cancelEvalRun|deleteEvalRun)$/ },
 ];
 
+/** A removed family's answer to an operation at `now`, or none while it is served. The deprecations page says only that
+ *  a removed endpoint "will no longer be accessible": the status and wording of the answer are the twin's own. */
+export function removedAt(operation: string, now: number): { status: number; message: string } | undefined {
+  for (const f of REMOVED_FAMILIES) {
+    if (!f.operations.test(operation)) continue;
+    if (now >= shutdownAt(f.removed)) return { status: 404, message: `The ${f.family} was removed on ${f.removed}.` };
+    if (f.readOnlyFrom && f.writes?.test(operation) && now >= shutdownAt(f.readOnlyFrom)) return { status: 400, message: `Evals are read-only since ${f.readOnlyFrom}.` };
+  }
+  return undefined;
+}
+
+/** Fine-tuning's dated availability (the deprecations page, "Self-serve fine-tuning availability"): from 2026-05-07
+ *  "Creating fine-tuning jobs or training is not available to organizations that have not previously run fine-tuning";
+ *  from 2026-07-02 "Creating fine-tuning jobs is no longer available to organizations that have not run inference on a
+ *  fine-tuned model in the past 60 days"; from 2027-01-06 "Active existing customers will no longer be able to create
+ *  new fine-tuning jobs". The page documents no error: the refusal (403, its wording) is the twin's own. */
+export function fineTuningClosed(now: number, org: { everFineTuned: boolean; lastFineTunedInference?: number }): string | undefined {
+  if (now >= shutdownAt('2027-01-06')) return 'Creating fine-tuning jobs is no longer available (since 2027-01-06).';
+  if (now >= shutdownAt('2026-07-02') && (org.lastFineTunedInference === undefined || now - org.lastFineTunedInference > 60 * 86400)) return 'Creating fine-tuning jobs is not available to organizations that have not run inference on a fine-tuned model in the past 60 days (since 2026-07-02).';
+  if (now >= shutdownAt('2026-05-07') && !org.everFineTuned) return 'Creating fine-tuning jobs is not available to organizations that have not previously run fine-tuning (since 2026-05-07).';
+  return undefined;
+}
+
 /** Resolve a model object by id, or undefined if the twin doesn't model it. */
 export function findModel(id: string): OpenAIModel | undefined {
   return OPENAI_MODELS.find((m) => m.id === id);
 }
+
+/** Whether a model reasons, so that its responses list the reasoning item that describes its chain of thought and count
+ *  its reasoning tokens (the spec's ReasoningItem: "A description of the chain of thought used by a reasoning model while
+ *  generating a response"). The o-series and the GPT models from GPT-5 on reason: the spec speaks of "all reasoning models
+ *  after `gpt-5`", and the reasoning guide (https://developers.openai.com/api/docs/guides/reasoning) lists gpt-6-astra,
+ *  gpt-5.6, gpt-5.5 and gpt-5.4 among them; gpt-6-astra's page names "Reasoning token support"
+ *  (https://developers.openai.com/api/docs/models/gpt-6-astra). A fine-tuned model reasons as its base does. */
+export function reasons(model: string): boolean {
+  const base = model.startsWith('ft:') ? model.split(':')[1] ?? '' : model;
+  return /^o\d/.test(base) || /^gpt-([5-9]|\d{2,})(\b|[.-])/.test(base);
+}
+
+/** The reasoning efforts the spec's ReasoningEffort names; a model may document fewer. */
+export const REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+/** The effort a reasoning model spends when the request names none: the spec's ReasoningEffort `default: medium`. */
+export const DEFAULT_EFFORT = 'medium';
+
+/** What a model's page says it takes and refuses. gpt-6-astra: "`reasoning.effort` supports `low`, `medium`, `high`,
+ *  `xhigh`, and `max`" (its model page); "GPT-6 Astra does not support `none` reasoning effort. Setting
+ *  `reasoning.effort` (Responses) or `reasoning_effort` (Chat Completions) to `none` returns HTTP 400" (the reasoning
+ *  guide); "does not support custom `temperature` or `top_p` values or log probabilities (`logprobs`)" (the changelog,
+ *  2026-09-03). */
+const LIMITS: Record<string, { efforts: string[]; sampling: false; logprobs: false; chatTools: false }> = {
+  'gpt-6-astra': { efforts: ['low', 'medium', 'high', 'xhigh', 'max'], sampling: false, logprobs: false, chatTools: false },
+};
+
+/** OpenAI's refusal of a request a model does not take (an effort, custom sampling, log probabilities), or none. */
+export function unsupported(model: string, req: { effort?: unknown; effortParam: string; temperature?: unknown; top_p?: unknown; logprobs?: unknown; chatTools?: unknown }): { message: string; param: string } | undefined {
+  const base = model.startsWith('ft:') ? model.split(':')[1] ?? '' : model;
+  const limits = LIMITS[base];
+  const efforts = limits?.efforts ?? REASONING_EFFORTS;
+  if (req.effort !== undefined && (typeof req.effort !== 'string' || !efforts.includes(req.effort))) {
+    return { message: `Unsupported value: '${req.effortParam}' does not support ${JSON.stringify(req.effort)} with this model. Supported values are: ${efforts.map((e) => `'${e}'`).join(', ')}.`, param: req.effortParam };
+  }
+  if (!limits) return undefined;
+  for (const k of ['temperature', 'top_p'] as const) {
+    if (req[k] !== undefined && req[k] !== 1) return { message: `Unsupported value: '${k}' does not support ${JSON.stringify(req[k])} with this model. Only the default (1) value is supported.`, param: k };
+  }
+  if (req.logprobs === true) return { message: "Unsupported parameter: 'logprobs' is not supported with this model.", param: 'logprobs' };
+  // "Tool calling requires the Responses API. If you use tools with Chat Completions, follow the Responses migration
+  // guide" (https://developers.openai.com/api/docs/changelog, 2026-09-03). The changelog gives no wording for the
+  // refusal: this message is the twin's own.
+  if (Array.isArray(req.chatTools) && req.chatTools.length) return { message: 'Tool calling with this model requires the Responses API: send the request to /v1/responses.', param: 'tools' };
+  return undefined;
+}
+
+/** The model an operation runs on when the request names none, from the spec's request schemas: a generation's
+ *  `dall-e-2` (CreateImageRequest `model` default), an edit's `gpt-image-1.5` (CreateImageEditRequest), a variation's
+ *  `dall-e-2` (it takes no other), a moderation's `omni-moderation-latest` (CreateModerationRequest). */
+export const DEFAULT_MODEL: Record<string, string> = { createImage: 'dall-e-2', createImageEdit: 'gpt-image-1.5', createImageVariation: 'dall-e-2', createModeration: 'omni-moderation-latest' };
+
+/** The model a request runs on: the one it names, else its operation's default (a variation runs on dall-e-2 whatever it names). */
+export function modelOf(operation: string, params: { model?: unknown }): string | undefined {
+  if (operation === 'createImageVariation') return DEFAULT_MODEL.createImageVariation;
+  return typeof params.model === 'string' && params.model ? params.model : DEFAULT_MODEL[operation];
+}

package/src/openai-scenario.ts

@@ -1,10 +1,10 @@
-// The openai pack's scenario system on the kernel's ONE engine (@volter/twin scenario.ts):
+// The openai pack's scenario system on the kernel's ONE engine (@volter/world-core scenario.ts):
 // chat-completions vocabulary + the scripted-turn respond shape. New with the
 // TWIN-PROGRAMMING-MODEL consolidation — this pack previously had no scripting at all. The
 // handler FILE (handlers/openai.json in a world dir) is the only write surface.
-import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/twin';
-import { contentToText, lastUserText } from './openai-stub.ts';
-import type { ChatMessageParam, ChatToolCall } from './openai-types.ts';
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, type ScenarioDecision, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, estimateTokens, lastUserText } from './openai-stub.ts';
+import type { ChatChoice, ChatMessageParam, ChatToolCall } from './openai-types.ts';
 
 export type OpenAIScenarioRequest = { model: string; messages: ChatMessageParam[]; tools?: unknown; maxTokens?: number };
 export type OpenAIScenarioEngine = ScenarioEngine<OpenAIScenarioRequest>;
@@ -50,6 +50,18 @@ function toolNames(tools: unknown): string[] {
 }
 
 export const openaiScenarioAdapter: PackScenarioAdapter<OpenAIScenarioRequest> = {
+  // R15 — a status fault in THIS vendor's envelope: the same {error:{message,type,param,code}}
+  // openai-twin.ts serves for its own refusals (its 429 is `type: 'rate_limit_exceeded'`).
+  renderFault: (f) => ({
+    body: {
+      error: {
+        message: f.message ?? (f.status === 429 ? 'Rate limit reached for requests. Limit your request rate or retry after the indicated delay.' : f.status >= 500 ? 'The server had an error while processing your request. Sorry about that!' : 'The request was refused by a scripted fault.'),
+        type: f.status === 429 ? 'rate_limit_exceeded' : f.status >= 500 ? 'server_error' : 'invalid_request_error',
+        param: null,
+        code: f.status === 429 ? 'rate_limit_exceeded' : null,
+      },
+    },
+  }),
   vendor: 'openai',
   features: (req): ScenarioFeatures => ({
     model: req.model,
@@ -116,17 +128,41 @@ export function loadOpenAIScenarioDocument(path: string): ScenarioDocument {
   return parseScenarioDocument(parsed, openaiScenarioAdapter);
 }
 
+/** What the scenario makes of one request: the decision a builder realizes, or a fault answered at once
+ *  (a status the script names; the script's own authoring failure is a 500 before any stream starts). */
+export async function serveScenario(engine: OpenAIScenarioEngine, req: OpenAIScenarioRequest, path: string): Promise<ScenarioDecision | { kind: 'fault'; result: { status: number; body: unknown; headers?: Record<string, string> } }> {
+  try {
+    return await engine.serve(req);
+  } catch (error) {
+    if (!(error instanceof ScenarioError)) throw error;
+    console.error(`[openai twin] scenario error on ${path}: ${error.message}`);
+    return { kind: 'fault', result: { status: 500, body: { error: { message: error.message, type: 'twin_scenario_error', param: null, code: 'scenario_error' } }, headers: { 'x-request-id': 'req_twin' } } };
+  }
+}
+
+/** A decision as a turn: the scripted result, or, on a miss, the note that teaches where to script it. */
+export function scenarioTurn(decision: ScenarioDecision, callIdPrefix?: string): { scripted: ScriptedResult; missTeach?: undefined } | { scripted?: undefined; missTeach: string } {
+  if (decision.kind === 'handler') return { scripted: realizeOpenAIRespond(decision.respond as OpenAIScenarioRespond, callIdPrefix) };
+  return { missTeach: `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/openai.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]` };
+}
+
+/** A scripted turn as a chat completion's choice. */
+export function scriptedChoice(scripted: ScriptedResult, index: number): { choice: ChatChoice; completionTokens: number } {
+  const message = scripted.toolCalls.length
+    ? { role: 'assistant' as const, content: scripted.text, tool_calls: scripted.toolCalls, refusal: null }
+    : { role: 'assistant' as const, content: scripted.text ?? '', refusal: null };
+  return { choice: { index, message, logprobs: null, finish_reason: scripted.finishReason }, completionTokens: estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? '')) };
+}
+
 export function createOpenAIScenarioEngine(document?: ScenarioDocument): OpenAIScenarioEngine {
   return new ScenarioEngine(openaiScenarioAdapter, document);
 }
 
-let scriptedCallSeq = 0;
-
-export function realizeOpenAIRespond(respond: OpenAIScenarioRespond): ScriptedResult {
+export function realizeOpenAIRespond(respond: OpenAIScenarioRespond, callIdPrefix = 'call_scripted'): ScriptedResult {
   const toolCalls: ChatToolCall[] = [];
-  for (const tc of respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : []) {
-    scriptedCallSeq += 1;
-    toolCalls.push({ id: tc.id ?? `call_scripted_${scriptedCallSeq}`, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
+  // Responses supplies a response-specific prefix so chained calls keep distinct identities.
+  for (const [i, tc] of (respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : []).entries()) {
+    toolCalls.push({ id: tc.id ?? `${callIdPrefix}_${i + 1}`, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
   }
   return {
     text: respond.text ?? (toolCalls.length ? null : ''),