@volter/twin-openai 0.1.0

package/src/openai-conformance.ts

@@ -0,0 +1,112 @@
+// OpenAI twin conformance — a lightweight, offline structural check that the twin's served
+// response ENVELOPES match the documented OpenAI shapes. (Unlike the OpenAPI-backed packs,
+// OpenAI's published OpenAPI is huge and not vendored here, so this harness validates the
+// load-bearing envelope SHAPES directly: chat.completion, the streaming chunk sequence,
+// 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).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleOpenAITwinRequest, type OpenAIResponseEnvelope } from './openai-twin.ts';
+import type { SseEvent } from './openai-types.ts';
+
+export type ConformanceViolation = { check: string; detail: string };
+export type OpenAIConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  violations: ConformanceViolation[];
+};
+
+type Body = Record<string, unknown>;
+const isObj = (v: unknown): v is Body => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkOpenAIConformance(opts: { root?: string } = {}): Promise<OpenAIConformanceReport> {
+  const root = opts.root ?? mkdtempSync(join(tmpdir(), 'openai-conf-'));
+  const owned = opts.root === undefined;
+  const violations: ConformanceViolation[] = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  const H = (method: string, path: string, body?: string, sseSink?: (e: SseEvent) => void) =>
+    handleOpenAITwinRequest({ method, path, body, root, ...(sseSink ? { sseSink } : {}) });
+
+  try {
+    // 1. chat.completion response envelope.
+    checksRun++;
+    const chat = await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'gpt-4o', messages: [{ role: 'user', content: 'hi' }] }));
+    const cb = chat.body as Body;
+    if (chat.status !== 200) fail('chat.envelope', `status ${chat.status}`);
+    else {
+      for (const k of ['id', 'object', 'created', 'model', 'choices', 'usage']) if (!(k in cb)) fail('chat.envelope', `missing field "${k}"`);
+      if (cb.object !== 'chat.completion') fail('chat.envelope', `object is ${String(cb.object)}`);
+      const choices = cb.choices as Body[];
+      if (!Array.isArray(choices) || !isObj(choices[0]) || (choices[0]!.message as Body)?.role !== 'assistant') fail('chat.envelope', 'choices[0].message not assistant');
+      if ((choices[0]!.finish_reason) !== 'stop') fail('chat.envelope', `finish_reason is ${String(choices[0]!.finish_reason)}`);
+      const usage = cb.usage as Body;
+      if (!isObj(usage) || typeof usage.prompt_tokens !== 'number' || typeof usage.total_tokens !== 'number') fail('chat.usage', 'usage missing prompt/total tokens');
+    }
+
+    // 2. chat streaming chunk sequence (ends with done).
+    checksRun++;
+    const events: SseEvent[] = [];
+    await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'gpt-4o', stream: true, messages: [{ role: 'user', content: 'stream' }] }), (e) => events.push(e));
+    const hasRole = events.some((e) => !e.done && ((e.data!.choices as Body[])?.[0]?.delta as Body)?.role === 'assistant');
+    const hasDone = events.length > 0 && events[events.length - 1]!.done === true;
+    const firstChunkObj = events[0]?.data?.object;
+    if (!hasRole) fail('chat.stream', 'no role delta chunk');
+    if (!hasDone) fail('chat.stream', 'stream did not end with [DONE]');
+    if (firstChunkObj !== 'chat.completion.chunk') fail('chat.stream', `first chunk object is ${String(firstChunkObj)}`);
+
+    // 3. tool_calls envelope when tools provided.
+    checksRun++;
+    const tool = await H('POST', '/v1/chat/completions', JSON.stringify({ model: 'gpt-4o', tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object' } } }], messages: [{ role: 'user', content: 'weather?' }] }));
+    const tc = (tool.body as Body).choices as Body[];
+    if ((tc?.[0]?.finish_reason) !== 'tool_calls') fail('chat.tool_calls', 'finish_reason not tool_calls');
+    const calls = (tc?.[0]?.message as Body)?.tool_calls as Body[];
+    if (!Array.isArray(calls) || calls[0]?.type !== 'function') fail('chat.tool_calls', 'no function tool_call');
+
+    // 4. Responses API envelope.
+    checksRun++;
+    const resp = await H('POST', '/v1/responses', JSON.stringify({ model: 'gpt-4o', input: 'hello' }));
+    const rb = resp.body as Body;
+    if (rb.object !== 'response' || !Array.isArray(rb.output) || (rb.output as Body[])[0]?.type !== 'message') fail('responses.envelope', 'bad responses envelope');
+
+    // 5. embeddings shape + determinism.
+    checksRun++;
+    const e1 = await H('POST', '/v1/embeddings', JSON.stringify({ model: 'text-embedding-3-small', input: 'vectorize me' }));
+    const e2 = await H('POST', '/v1/embeddings', JSON.stringify({ model: 'text-embedding-3-small', input: 'vectorize me' }));
+    const v1 = ((e1.body as Body).data as Body[])?.[0]?.embedding as number[];
+    const v2 = ((e2.body as Body).data as Body[])?.[0]?.embedding as number[];
+    if (!Array.isArray(v1) || v1.length === 0) fail('embeddings.shape', 'no embedding vector');
+    else if (JSON.stringify(v1) !== JSON.stringify(v2)) fail('embeddings.deterministic', 'same input produced different vectors');
+
+    // 6. models list + retrieve.
+    checksRun++;
+    const models = await H('GET', '/v1/models');
+    if (!Array.isArray((models.body as Body).data)) fail('models.list', 'no data array');
+    const one = await H('GET', '/v1/models/gpt-4o');
+    if ((one.body as Body).object !== 'model') fail('models.retrieve', 'object is not a model');
+
+    // 7. files create + batches create + moderations.
+    checksRun++;
+    const file = await H('POST', '/v1/files', JSON.stringify({ purpose: 'batch', filename: 'in.jsonl', content: '{}' }));
+    if ((file.body as Body).object !== 'file') fail('files.create', 'object is not a file');
+    const batch = await H('POST', '/v1/batches', JSON.stringify({ input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' }));
+    if ((batch.body as Body).object !== 'batch') fail('batches.create', 'object is not a batch');
+    const mod = await H('POST', '/v1/moderations', JSON.stringify({ input: 'hello' }));
+    if (!Array.isArray((mod.body as Body).results)) fail('moderations', 'no results array');
+
+    // 8. vendor-shaped error envelope.
+    checksRun++;
+    const bad = await H('POST', '/v1/chat/completions', JSON.stringify({ messages: [{ role: 'user', content: 'hi' }] })) as OpenAIResponseEnvelope;
+    const eb = bad.body as Body;
+    if (bad.status !== 400 || !isObj(eb.error) || (eb.error as Body).type !== 'invalid_request_error') fail('error.envelope', 'missing model did not yield a 400 invalid_request_error envelope');
+    const nf = await H('GET', '/v1/nonexistent');
+    if (nf.status !== 404 || !isObj((nf.body as Body).error)) fail('error.not_found', 'unknown route did not 404');
+  } finally {
+    if (owned) rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: violations.length === 0, checksRun, violations };
+}

package/src/openai-connector.ts

@@ -0,0 +1,337 @@
+// OpenAI CONNECTOR — the live-vendor pull/push path that gives the OpenAI twin the full
+// "git for SaaS" lifecycle (pull real state → mirror; push local writes → real).
+//
+// PULL  (real → twin):  fetch real Files / Batches / Fine-tuning jobs / Vector stores, map
+//                       snake_case → SyncResource[], fold into the event log via syncPull
+//                       (shadow-diff dedup, so re-pulling identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action (create / cancel / delete), call the
+//                       real OpenAI REST API and confirmAction on success (records the
+//                       confirmed fields as an observed event + suppresses the local
+//                       projection — counted exactly once).
+//
+// 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';
+
+const SERVICE = 'openai';
+
+/**
+ * The injected real-OpenAI boundary. `request` issues ONE OpenAI REST call:
+ *   method  — 'GET' | 'POST' | 'DELETE'
+ *   path    — e.g. '/v1/files' or '/v1/batches/batch_123/cancel'
+ *   body    — JSON body for POST (omitted otherwise)
+ * Returns the parsed JSON (an object, a `{ data }` list, or an `{ error }` envelope).
+ */
+export type OpenAIExecute = (
+  method: 'GET' | 'POST' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<{ data?: any; error?: { message?: string; type?: string }; [k: string]: unknown }>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveOpenAIOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: OpenAIBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: OpenAIBudgetOptions;
+};
+
+/**
+ * A live executor against the real OpenAI REST API (the user's own API key). Sends the
+ * required `Authorization: Bearer` header. Never imported by the pack's own code path — only
+ * constructed by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.openai.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `OpenAIBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `retry-after` /
+ * 429 / `x-ratelimit-remaining-requests: 0` signal becomes a persisted cooldown that makes every
+ * later call fail fast WITHOUT touching OpenAI. There is deliberately no OPTION to disable the guard, and no
+ * value a caller can pass for `budget` that yields an unguarded client. What that does NOT claim is
+ * immunity from a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an injected
+ * clock, restores the allowance, because the same seam tests need cannot be denied to a determined
+ * caller in the same process. The kernel header says so up front and this does not upgrade it — see `openai-budget.ts` for why, and for the limits of the guarantee.
+ */
+export function liveOpenAIExecute(
+  apiKey: string,
+  base = 'https://api.openai.com',
+  opts: LiveOpenAIOptions = {},
+): OpenAIExecute {
+  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+  // UNMODIFIED OpenAIBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
+  // Proxy that traps it are all refused, because all three are one-liners that would otherwise
+  // hand back a client with no ceiling at all (§9 finding, 2026-07-26 — `instanceof` alone was
+  // not a check). What this cannot stop is deliberate sabotage from inside the process (an
+  // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
+  // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
+  const doFetch = opts.fetchImpl ?? fetch;
+  // The default ledger is keyed by a hash of THIS key — OpenAI limits per organization/project,
+  // so a cwd-scoped ledger would hand the same key a fresh allowance per checkout/worktree/CI leg.
+  // ONE expression decides which budget is used, so there is no second, weaker test that could
+  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+  // must be an UNMODIFIED OpenAIBudget — a duck-typed stand-in, a SUBCLASS overriding
+  // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+  // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
+  // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
+  // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
+  // header states that limit rather than pretending otherwise. This closes the accident and the
+  // one-liner, which are the shapes that actually happen.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, OpenAIBudget, 'liveOpenAIExecute')
+    : new OpenAIBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    const headers: Record<string, string> = { authorization: `Bearer ${apiKey}` };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (method === 'POST') {
+      headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(body ?? {});
+    }
+    const weight = openaiCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${base}${path}`, init);
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const parsed = (await res.json()) as { data?: any; error?: { message?: string; type?: string } };
+    // 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 });
+    return parsed;
+  };
+}
+
+function listOf(res: { data?: unknown }): any[] {
+  return Array.isArray(res.data) ? res.data : [];
+}
+function throwIfError(res: { error?: { message?: string } }, ctx: string): void {
+  if (res.error) throw new Error(`openai ${ctx} failed: ${res.error.message ?? 'unknown error'}`);
+}
+
+// ── PULL ────────────────────────────────────────────────────────────────────
+
+/** Map a real-OpenAI File object → a twin sync resource. */
+export function mapFile(f: Record<string, unknown>): SyncResource {
+  return {
+    type: 'file',
+    id: String(f.id),
+    fields: {
+      object: 'file',
+      bytes: (f.bytes as number) ?? 0,
+      created_at: (f.created_at as number) ?? null,
+      filename: (f.filename as string) ?? null,
+      purpose: (f.purpose as string) ?? null,
+      status: (f.status as string) ?? null,
+    },
+  };
+}
+
+/** Map a real-OpenAI Batch object → a twin sync resource. */
+export function mapBatch(b: Record<string, unknown>): SyncResource {
+  const counts = (b.request_counts && typeof b.request_counts === 'object') ? (b.request_counts as Record<string, unknown>) : {};
+  return {
+    type: 'batch',
+    id: String(b.id),
+    fields: {
+      object: 'batch',
+      endpoint: (b.endpoint as string) ?? null,
+      input_file_id: (b.input_file_id as string) ?? null,
+      completion_window: (b.completion_window as string) ?? null,
+      status: (b.status as string) ?? null,
+      output_file_id: (b.output_file_id as string) ?? null,
+      created_at: (b.created_at as number) ?? null,
+      completed_at: (b.completed_at as number) ?? null,
+      request_counts: counts,
+    },
+  };
+}
+
+/** Map a real-OpenAI fine-tuning job → a twin sync resource. */
+export function mapFineTune(j: Record<string, unknown>): SyncResource {
+  return {
+    type: 'fine_tuning_job',
+    id: String(j.id),
+    fields: {
+      object: 'fine_tuning.job',
+      model: (j.model as string) ?? null,
+      status: (j.status as string) ?? null,
+      fine_tuned_model: (j.fine_tuned_model as string) ?? null,
+      training_file: (j.training_file as string) ?? null,
+      created_at: (j.created_at as number) ?? null,
+      finished_at: (j.finished_at as number) ?? null,
+    },
+  };
+}
+
+/** Map a real-OpenAI vector store → a twin sync resource. */
+export function mapVectorStore(v: Record<string, unknown>): SyncResource {
+  const counts = (v.file_counts && typeof v.file_counts === 'object') ? (v.file_counts as Record<string, unknown>) : {};
+  return {
+    type: 'vector_store',
+    id: String(v.id),
+    fields: {
+      object: 'vector_store',
+      name: (v.name as string) ?? null,
+      status: (v.status as string) ?? null,
+      created_at: (v.created_at as number) ?? null,
+      usage_bytes: (v.usage_bytes as number) ?? 0,
+      file_counts: counts,
+    },
+  };
+}
+
+const COLLECTIONS: Array<{ path: string; map: (r: Record<string, unknown>) => SyncResource }> = [
+  { path: '/v1/files', map: mapFile },
+  { path: '/v1/batches', map: mapBatch },
+  { path: '/v1/fine_tuning/jobs', map: mapFineTune },
+  { path: '/v1/vector_stores', map: mapVectorStore },
+];
+
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export async function pullOpenAIState(execute: OpenAIExecute): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  for (const c of COLLECTIONS) {
+    const res = await execute('GET', `${c.path}?limit=100`);
+    throwIfError(res, `pull ${c.path}`);
+    for (const item of listOf(res)) out.push(c.map(item));
+  }
+  return out;
+}
+
+/**
+ * Pull from real OpenAI and fold into the twin (mirror seeding). syncPull's shadow-diff makes
+ * a re-pull of identical state a no-op.
+ */
+export async function syncOpenAIFromReal(
+  execute: OpenAIExecute,
+  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 };
+}
+
+// ── PUSH ────────────────────────────────────────────────────────────────────
+
+// The twin operations this connector knows how to push to real OpenAI. Anything not here must
+// FAIL LOUDLY rather than be silently dropped — pushing an unrecognized op risks hitting the
+// wrong endpoint or no-op'ing a real change.
+const PUSHABLE_VERBS = new Set(['create', 'cancel', 'delete']);
+
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+function assertPushable(op: string): void {
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  if (!PUSHABLE_VERBS.has(verb)) {
+    throw new Error(`openai push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+}
+
+// Map a subject type → its REST collection path.
+const COLLECTION_PATH: Record<string, string> = {
+  file: '/v1/files',
+  batch: '/v1/batches',
+  fine_tuning_job: '/v1/fine_tuning/jobs',
+  vector_store: '/v1/vector_stores',
+  vector_store_file: '/v1/vector_stores',
+};
+
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real OpenAI REST
+ * surface for every write op the twin records:
+ *   - <type>.create → POST   <collection>
+ *   - <type>.cancel → POST   <collection>/:id/cancel
+ *   - <type>.delete → DELETE <collection>/:id
+ */
+export function openaiRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): { method: 'GET' | 'POST' | 'DELETE'; path: string } {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  const collection = COLLECTION_PATH[action.subject.type] ?? `/v1/${action.subject.type}s`;
+  if (verb === 'create') return { method: 'POST', path: collection };
+  if (verb === 'cancel') return { method: 'POST', path: `${collection}/${action.subject.id}/cancel` };
+  if (verb === 'delete') return { method: 'DELETE', path: `${collection}/${action.subject.id}` };
+  // assertPushable rejects anything else, so this is only reached for the pushable verbs above.
+  return { method: 'POST', path: collection };
+}
+
+/**
+ * Push ONE pending action to REAL OpenAI via the injected executor. Returns the real external
+ * id (the object id from the response; for a create that's a freshly minted id, otherwise it
+ * echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushOpenAIAction(
+  execute: OpenAIExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+): Promise<{ externalId: string }> {
+  assertPushable(action.operation ?? `${action.subject.type}.update`);
+  const { method, path } = openaiRequestForAction(action);
+  const verb = (action.operation ?? '').includes('.') ? action.operation!.slice(action.operation!.indexOf('.') + 1) : '';
+  // On create, push the vendor-accepted create payload (the stored fields include derived
+  // lifecycle data the create endpoint does not accept; strip the twin's private fields).
+  const payload = verb === 'create' ? createPayload(action) : undefined;
+  const res = await execute(method, path, payload);
+  throwIfError(res, `push ${action.subject.type}`);
+  const id = (res as { id?: unknown }).id;
+  return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+
+function createPayload(action: Pick<TwinAction, 'subject' | 'fields'>): Record<string, unknown> {
+  const f = (action.fields ?? {}) as Record<string, unknown>;
+  switch (action.subject.type) {
+    case 'batch':
+      return { input_file_id: f.input_file_id, endpoint: f.endpoint, completion_window: f.completion_window, ...(f.metadata ? { metadata: f.metadata } : {}) };
+    case 'fine_tuning_job':
+      return { model: f.model, training_file: f.training_file, ...(f.validation_file ? { validation_file: f.validation_file } : {}) };
+    case 'vector_store':
+      return { ...(f.name ? { name: f.name } : {}) };
+    case 'file':
+      return { purpose: f.purpose, filename: f.filename };
+    default:
+      return {};
+  }
+}
+
+/**
+ * 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 };
+}
+
+// ── 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 };
+}

package/src/openai-models.ts

@@ -0,0 +1,36 @@
+// OpenAI model catalog — the static `GET /v1/models` surface. Real OpenAI serves a list of
+// model objects ({ id, object:'model', created, owned_by }). The twin returns a faithful,
+// deterministic subset so `client.models.list()` / `client.models.retrieve(id)` round-trip
+// exactly like the vendor.
+//
+// This is a STATIC surface (the model registry doesn't change at runtime), so it is a plain
+// data table rather than kernel state — listing/retrieving models is a pure read.
+export type OpenAIModel = {
+  id: string;
+  object: 'model';
+  created: number;
+  owned_by: string;
+};
+
+// A faithful slice of the published catalog (ids are the exact vendor strings).
+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' },
+];
+
+/** 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);
+}

package/src/openai-scenario.ts

@@ -0,0 +1,136 @@
+// The openai pack's scenario system on the kernel's ONE engine (@volter/twin 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';
+
+export type OpenAIScenarioRequest = { model: string; messages: ChatMessageParam[]; tools?: unknown; maxTokens?: number };
+export type OpenAIScenarioEngine = ScenarioEngine<OpenAIScenarioRequest>;
+
+export type ScenarioToolCall = { name: string; arguments: Record<string, unknown>; id?: string };
+
+export type OpenAIScenarioRespond = {
+  text?: string;
+  toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+  finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+
+export type ScriptedResult = {
+  text: string | null;
+  toolCalls: ChatToolCall[];
+  finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+const positiveNumber = (cond: unknown): cond is number => typeof cond === 'number' && Number.isFinite(cond) && cond > 0;
+
+function lastToolResultNames(messages: ChatMessageParam[]): Set<string> {
+  const names = new Set<string>();
+  const last = messages[messages.length - 1] as { role?: string; tool_call_id?: unknown } | undefined;
+  if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string') return names;
+  for (const m of messages) {
+    const am = m as { role?: string; tool_calls?: Array<{ id?: unknown; function?: { name?: unknown } }> };
+    if (am.role !== 'assistant' || !Array.isArray(am.tool_calls)) continue;
+    for (const tc of am.tool_calls) {
+      if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string') names.add(tc.function.name);
+    }
+  }
+  return names;
+}
+
+function toolNames(tools: unknown): string[] {
+  if (!Array.isArray(tools)) return [];
+  return (tools as Array<{ function?: { name?: unknown }; name?: unknown }>).map((t) =>
+    typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null,
+  ).filter((n): n is string => n !== null);
+}
+
+export const openaiScenarioAdapter: PackScenarioAdapter<OpenAIScenarioRequest> = {
+  vendor: 'openai',
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageIsToolResult: (req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool',
+    toolResultFor: [...lastToolResultNames(req.messages)],
+    // The output cap the caller asked for (max_tokens / max_completion_tokens), or 0 when it sent none. A
+    // proxy between the agent and this twin may clamp it; a handler keyed on it makes that clamp visible.
+    maxTokens: req.maxTokens ?? 0,
+  }),
+  matchers: {
+    modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+    userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+    anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+    lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && ((req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool') === cond,
+    toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+    hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+    // A request whose output cap is below N (a cap it did not send counts as below every N).
+    maxTokensBelow: (req, cond) => positiveNumber(cond) && (req.maxTokens ?? 0) < cond,
+    maxTokensAtLeast: (req, cond) => positiveNumber(cond) && (req.maxTokens ?? 0) >= cond,
+  },
+  text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+  validateOn: (on) => {
+    for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'] as const) if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k])) return `on.${k} is a non-empty string`;
+    if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean') return 'on.lastMessageIsToolResult is a boolean';
+    for (const k of ['maxTokensBelow', 'maxTokensAtLeast'] as const) if (on[k] !== undefined && !positiveNumber(on[k])) return `on.${k} is a positive number`;
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { text?, toolCalls?, finishReason? }';
+    const r = respond as Record<string, unknown>;
+    for (const k of Object.keys(r)) if (!RESPOND_KEYS.has(k)) return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+    if (r.text !== undefined && typeof r.text !== 'string') return 'respond.text is a string';
+    if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason))) return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+    if (r.toolCalls !== undefined) {
+      for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+        const t = tc as Record<string, unknown>;
+        if (!t || typeof t !== 'object' || Array.isArray(t)) return 'respond.toolCalls entries are objects';
+        if (typeof t.name !== 'string' || !t.name) return 'respond.toolCalls[].name is a non-empty string';
+        if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments)) return 'respond.toolCalls[].arguments is an object';
+        if (t.id !== undefined && typeof t.id !== 'string') return 'respond.toolCalls[].id is a string';
+      }
+    }
+    if (r.text === undefined && r.toolCalls === undefined) return 'respond needs text or toolCalls';
+    return null;
+  },
+};
+
+export function loadOpenAIScenarioDocument(path: string): ScenarioDocument {
+  let parsed: unknown;
+  try {
+    // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+    // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+    // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+    // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+    // so the loud load-time failure reads byte-identically to the read it replaces.
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new ScenarioError(`openai scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, openaiScenarioAdapter);
+}
+
+export function createOpenAIScenarioEngine(document?: ScenarioDocument): OpenAIScenarioEngine {
+  return new ScenarioEngine(openaiScenarioAdapter, document);
+}
+
+let scriptedCallSeq = 0;
+
+export function realizeOpenAIRespond(respond: OpenAIScenarioRespond): 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) } });
+  }
+  return {
+    text: respond.text ?? (toolCalls.length ? null : ''),
+    toolCalls,
+    finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+  };
+}