@volter/twin-openai 0.1.2 → 2.0.1

package/src/semantics/index.ts

@@ -0,0 +1,52 @@
+// OpenAI semantics, by operationId. Families move here from openai-twin.ts's hand-written router;
+// the generative answers (chat, responses, embeddings) come from the pack's behaviour: its
+// deterministic stub or a scripted scenario, never a model.
+import type { Semantics } from '@volter/world-core';
+import type { OpenAIScenarioEngine } from '../openai-scenario.ts';
+import { assistants } from './assistants.ts';
+import { audio } from './audio.ts';
+import { batches } from './batches.ts';
+import { chatCompletions } from './chat-completions.ts';
+import { containers } from './containers.ts';
+import { embeddings } from './embeddings.ts';
+import { evals } from './evals.ts';
+import { files } from './files.ts';
+import { fineTuning } from './fine-tuning.ts';
+import { images } from './images.ts';
+import { models } from './models.ts';
+import { moderations } from './moderations.ts';
+import { organization } from './organization.ts';
+import { live, modelOf, removedAt } from '../openai-models.ts';
+import { READ_ONLY } from './progress.ts';
+import { epoch } from './shared.ts';
+import { responses } from './responses.ts';
+import { uploads } from './uploads.ts';
+import { vectorStores } from './vector-stores.ts';
+
+/** `readOnly`: served by a read-only (mirror) twin, whose reads never write (./progress.ts). */
+
+export type OpenAISemanticsOptions = { scenarioEngine?: OpenAIScenarioEngine; readOnly?: boolean };
+
+export function openaiSemantics(options: OpenAISemanticsOptions): Record<string, Semantics> {
+  const all: Record<string, Semantics> = { ...chatCompletions(options.scenarioEngine), ...responses(options.scenarioEngine), ...models, ...files, ...uploads, ...batches, ...fineTuning, ...vectorStores, ...embeddings, ...moderations, ...images, ...audio, ...assistants, ...organization, ...evals, ...containers };
+  // OpenAI's timeline (../openai-models.ts), at the World's instant: an operation of a removed API family answers as
+  // removed; a request naming a model that is not live (not in the catalog, not yet released, or shut down) answers
+  // OpenAI's model_not_found, as for any model that does not exist. A fine-tuned model is live while the job that made
+  // it holds it and it is not deleted. An operation that names no model runs on its default (DEFAULT_MODEL). The models'
+  // own operations list and read the catalog as it stands (./models.ts).
+  for (const [id, h] of Object.entries(all)) {
+    all[id] = (async (ctx) => {
+      const now = epoch(ctx);
+      const removed = removedAt(id, now);
+      if (removed) return ctx.refuse({ status: removed.status, message: removed.message });
+      if (id in models) return h(ctx);
+      const p = ctx.params as { model?: unknown; data_source?: { model?: unknown } };
+      const named = typeof p.data_source?.model === 'string' && typeof p.model !== 'string' ? p.data_source.model : modelOf(id, p);
+      if (!named) return h(ctx);
+      const tuned = named.startsWith('ft:') && ctx.rowsRaw('FineTuningJob', { withDeleted: true }).some((j) => j.fine_tuned_model === named) && !ctx.rowsRaw('Model', { withDeleted: true }).some((m) => m.id === named && m.deleted);
+      return tuned || live(named, now) ? h(ctx) : ctx.notFound('Model', named);
+    }) as Semantics;
+  }
+  if (!options.readOnly) return all;
+  return Object.fromEntries(Object.entries(all).map(([id, h]) => [id, ((ctx) => h(Object.assign(ctx, { [READ_ONLY]: true }))) as Semantics]));
+}

package/src/semantics/models.ts

@@ -0,0 +1,41 @@
+// Model semantics: the static catalog plus the fine-tuned models succeeded jobs minted. The catalog is
+// data, not state, so every operation is a handler; only a fine-tuned model can be deleted.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { findModel, live, OPENAI_MODELS } from '../openai-models.ts';
+import { epoch, invalid } from './shared.ts';
+
+type FineTunedModel = { id: string; object: 'model'; created: number; owned_by: string; shutdown_date: string | null };
+
+/** The models succeeded fine-tuning jobs minted, less those deleted (a deletion is a Model tombstone). */
+function fineTunedModels(ctx: SemanticsContext): FineTunedModel[] {
+  const deleted = new Set(ctx.rowsRaw('Model', { withDeleted: true }).filter((r) => r.deleted).map((r) => String(r.id)));
+  const out: FineTunedModel[] = [];
+  for (const job of ctx.rowsRaw('FineTuningJob', { withDeleted: true })) {
+    const id = job.fine_tuned_model;
+    if (typeof id === 'string' && id && !deleted.has(id)) out.push({ id, object: 'model', created: Number(job.created_at ?? 0), owned_by: 'org-twin', shutdown_date: null });
+  }
+  return out;
+}
+
+// the catalog as it stands at the World's instant: a model not yet released, or shut down, is not there
+const list: Semantics = async (ctx) => ctx.reply({ object: 'list', data: [...OPENAI_MODELS.filter((m) => live(m.id, epoch(ctx))), ...fineTunedModels(ctx)] });
+
+const retrieve: Semantics = async (ctx) => {
+  const id = String(ctx.id);
+  const model = (live(id, epoch(ctx)) ? findModel(id) : undefined) ?? fineTunedModels(ctx).find((m) => m.id === id);
+  return model ? ctx.reply(model) : ctx.notFound('Model', id);
+};
+
+const remove: Semantics = async (ctx) => {
+  const id = String(ctx.id);
+  if (findModel(id)) return invalid(ctx, `The model '${id}' cannot be deleted`, 'model', 'model_not_deletable');
+  if (!fineTunedModels(ctx).some((m) => m.id === id)) return ctx.notFound('Model', id);
+  await ctx.write('Model', id, { deleted: true, object: 'model' }, 'model.delete');
+  return ctx.reply({ id, object: 'model', deleted: true });
+};
+
+export const models: Record<string, Semantics> = {
+  listModels: list,
+  retrieveModel: retrieve,
+  deleteModel: remove,
+};

package/src/semantics/moderations.ts

@@ -0,0 +1,14 @@
+// Moderations: the pack's deterministic classifier, never a model's.
+import type { Semantics } from '@volter/world-core';
+import { handleModerations } from '../openai-twin.ts';
+import { estimateTokens } from '../openai-stub.ts';
+import { recordUsage, send } from './shared.ts';
+
+export const moderations: Record<string, Semantics> = {
+  // a moderation is metered by the tokens of its text (the usage report's `input_tokens`)
+  createModeration: async (ctx) => {
+    const r = handleModerations(ctx.params, ctx.occurredAt);
+    if (r.status === 200) await recordUsage(ctx, 'moderations', String((r.body as { model: string }).model), estimateTokens(JSON.stringify(ctx.params.input ?? '')), 0);
+    return send(ctx, r);
+  },
+};

package/src/semantics/organization.ts

@@ -0,0 +1,76 @@
+// Organization (Admin API) semantics: the usage and costs reports over the usage every billable call
+// recorded, projects, and a project's API keys. Retrieve and archive of a project and a project's
+// keys (under their project) are the derived core's; the machine in ../manifest.ts moves a
+// project's `status`. Keys are the twin's own, never OpenAI credentials.
+import type { Semantics } from '@volter/world-core';
+import { bucketed, costsReport, reportQuery, usageReport } from '../openai-twin.ts';
+import { readOnly } from './progress.ts';
+import { epoch, invalid, newest, page, pick } from './shared.ts';
+
+const PROJECT = 'Project';
+
+/** Every organization has a Default project, where the keys made before any other project live and to
+ *  which the Admin API's own acts are attributed (https://platform.openai.com/docs/api-reference/audit-logs/object:
+ *  "any admin actions taken via Admin API keys are associated with the default project"). The twin makes
+ *  it when the organization's projects are first looked at, dated by the organization's first billed call
+ *  when there was one (the twin keeps no signup date); a read-only twin holds the vendor's own. */
+async function defaultProject(ctx: Parameters<Semantics>[0]): Promise<void> {
+  if (readOnly(ctx) || ctx.rowsRaw(PROJECT, { withDeleted: true }).some((p) => p._default === true)) return;
+  await ctx.write(PROJECT, ctx.mint(PROJECT), { object: 'organization.project', name: 'Default project', created_at: Math.min(epoch(ctx), ...ctx.rowsRaw('_usage_record').map((r) => Number(r.created_at))), archived_at: null, status: 'active', _default: true }, 'project.create');
+}
+
+// one report per kind the spec publishes; the operation's path names the kind
+const usage: Semantics = async (ctx) => {
+  if (ctx.params.start_time === undefined) return invalid(ctx, 'you must provide a start_time parameter', 'start_time');
+  const kind = new URL(ctx.call.request.url).pathname.replace(/\/+$/, '').split('/').at(-1);
+  const q = reportQuery(ctx.params, epoch(ctx), false);
+  // vector store usage is storage, not calls: the bytes the organization's stores held over each bucket, for a bucket in
+  // which any store existed (https://platform.openai.com/docs/api-reference/usage/vector_stores_object)
+  if (kind === 'vector_stores') {
+    const stores = ctx.rowsRaw('VectorStoreObject', { withDeleted: true }).map((r) => ({ from: Number(r.created_at), until: r.deleted ? Date.parse(String(r.updatedAt)) / 1000 : Infinity, bytes: Number(r.usage_bytes ?? 0) }));
+    return ctx.reply(bucketed([], q, (_rows, at, until) => {
+      const held = stores.filter((v) => v.from < until && v.until >= at);
+      return held.length ? [{ object: 'organization.usage.vector_stores.result', usage_bytes: held.reduce((n, v) => n + v.bytes, 0), project_id: null }] : [];
+    }));
+  }
+  return ctx.reply(usageReport(ctx.rowsRaw('_usage_record'), kind, q));
+};
+
+const costs: Semantics = async (ctx) => ctx.params.start_time === undefined ? invalid(ctx, 'you must provide a start_time parameter', 'start_time') : ctx.reply(costsReport(ctx.rowsRaw('_usage_record'), reportQuery(ctx.params, epoch(ctx), true)));
+
+// archived projects are left out unless asked for
+const listProjects: Semantics = async (ctx) => {
+  await defaultProject(ctx);
+  const all = ctx.params.include_archived === 'true';
+  return page(ctx, newest(ctx.rows(PROJECT).filter((p) => all || p.status !== 'archived')));
+};
+
+const createProject: Semantics = async (ctx) => {
+  await defaultProject(ctx);
+  if (ctx.params.name === undefined || ctx.params.name === '') return invalid(ctx, 'you must provide a name parameter', 'name');
+  const fields = { object: 'organization.project', name: String(ctx.params.name), created_at: epoch(ctx), archived_at: null, status: 'active' };
+  return ctx.reply(await ctx.write(PROJECT, ctx.mint(PROJECT), fields, 'project.create'));
+};
+
+const modifyProject: Semantics = async (ctx) => {
+  const id = String(ctx.id);
+  if (!ctx.get(PROJECT, id)) return ctx.notFound(PROJECT, id);
+  return ctx.reply(await ctx.write(PROJECT, id, pick(ctx.params, ['name']), 'project.update'));
+};
+
+export const organization: Record<string, Semantics> = {
+  'usage-audio-speeches': usage,
+  'usage-audio-transcriptions': usage,
+  'usage-code-interpreter-sessions': usage,
+  'usage-completions': usage,
+  'usage-embeddings': usage,
+  'usage-file-search-calls': usage,
+  'usage-images': usage,
+  'usage-moderations': usage,
+  'usage-vector-stores': usage,
+  'usage-web-search-calls': usage,
+  'usage-costs': costs,
+  'list-projects': listProjects,
+  'create-project': createProject,
+  'modify-project': modifyProject,
+};

package/src/semantics/progress.ts

@@ -0,0 +1,72 @@
+// The work OpenAI does on its own. A batch, a fine-tuning job, a run, an eval run and a vector store's
+// files are created where OpenAI starts them (validating, queued, in progress) and OpenAI moves them
+// on; the twin does that work when a read first looks, walking the vendor's declared moves in
+// ../manifest.ts (actor 'vendor') to where they end, deciding and writing at once so concurrent reads
+// move a subject once. A subject the caller holds (a paused job) or that is already done stays put.
+// A read-only (mirror) twin answers stored state as it is and never moves anything.
+import type { SemanticsContext } from '@volter/world-core';
+import { manifest } from '../manifest.ts';
+import type { Row } from './shared.ts';
+
+/** Marks a context served by a read-only (mirror) twin: its subjects come from the real vendor, so it
+ *  has no vendor progress to simulate and a read never writes. */
+export const READ_ONLY = Symbol('openai.readOnly');
+
+/** Whether this request is served by a read-only twin. */
+export const readOnly = (ctx: SemanticsContext): boolean => (ctx as unknown as Record<symbol, unknown>)[READ_ONLY] === true;
+
+/** Where the vendor takes each in-flight state next, per resource. */
+export const PROGRESS: Record<string, Record<string, string>> = {
+  Batch: { validating: 'in_progress', in_progress: 'finalizing', finalizing: 'completed', cancelling: 'cancelled' },
+  FineTuningJob: { validating_files: 'queued', queued: 'running', running: 'succeeded' },
+  RunObject: { queued: 'in_progress', in_progress: 'completed', cancelling: 'cancelled' },
+  EvalRun: { queued: 'in_progress', in_progress: 'completed' },
+  VectorStoreFileObject: { in_progress: 'completed' },
+  VectorStoreFileBatchObject: { in_progress: 'completed' },
+};
+
+/** Whether the vendor still has work to do on a stored subject. */
+export const inFlight = (resource: string, row: Row): boolean => String(row.status) in (PROGRESS[resource] ?? {});
+
+/** The effects the manifest declares on the vendor's move `from` → `to`, as values. */
+function effects(ctx: SemanticsContext, resource: string, from: string, to: string): Row {
+  const t = manifest.resources[resource]?.state?.status?.transitions.find((x) => x.actor === 'vendor' && x.to === to && x.from !== '*' && x.from.includes(from));
+  const out: Row = {};
+  for (const [k, rule] of Object.entries(t?.effects ?? {})) out[k] = 'now' in rule ? ctx.now() : 'value' in rule ? rule.value : null;
+  return out;
+}
+
+/** Walk one subject to where the vendor leaves it. `finish` adds what its end state carries (an
+ *  output file, a fine-tuned model). Answers the end state when this read is the one that moved it. */
+export async function progress(ctx: SemanticsContext, resource: string, id: string, finish?: (row: Row, end: string) => Row): Promise<{ from: string; to: string; row: Row } | undefined> {
+  if (readOnly(ctx)) return undefined;
+  const storedAs = manifest.resources[resource]?.storedAs ?? resource;
+  return ctx.atomically<{ from: string; to: string; row: Row } | undefined>((rows) => {
+    const current = rows(resource).find((r) => r.id === id);
+    if (!current || !inFlight(resource, current)) return { value: undefined };
+    const path = PROGRESS[resource]!;
+    const from = String(current.status);
+    let state = from;
+    const fields: Row = {};
+    while (state in path) {
+      const to = path[state]!;
+      // the vendor's move, never the caller's: the machine must declare it
+      if (ctx.legal(resource, 'status', ctx.call.operation.id, state, to, id, 'vendor')) break;
+      Object.assign(fields, effects(ctx, resource, state, to));
+      state = to;
+    }
+    Object.assign(fields, { status: state }, finish?.(current, state) ?? {});
+    return { value: { from, to: state, row: { ...current, ...fields } }, write: { resource, id, fields, operation: `${storedAs}.update` } };
+  });
+}
+
+/** Every in-flight subject a read is about to show, walked on (a list observes as a get does). */
+export async function progressAll(ctx: SemanticsContext, resource: string, finish?: (row: Row, end: string) => Row, only: (row: Row) => boolean = () => true): Promise<void> {
+  if (readOnly(ctx)) return;
+  for (const row of ctx.rowsRaw(resource)) if (only(row) && inFlight(resource, row)) await progress(ctx, resource, String(row.id), finish);
+}
+
+/** The derived core's answer for this read, once the vendor's work is observed. */
+export async function coreAnswer(ctx: SemanticsContext): Promise<Response> {
+  return (await ctx.core()) ?? ctx.refuse({ status: 404, message: `Unknown request URL: ${ctx.call.request.method} ${new URL(ctx.call.request.url).pathname}. Please check the URL for typos.` });
+}

package/src/semantics/responses.ts

@@ -0,0 +1,151 @@
+// Responses API semantics. A response is the pack's behaviour, never a model: a scripted scenario's
+// turn when one is loaded and a handler matches, else the labeled deterministic stub. A stored
+// response (the default) reads back with its input items; `previous_response_id` continues one; a
+// background response is created queued and processed on its first poll. The machine in
+// ../manifest.ts declares `status` (the vendor's work a poll observes, cancel) and refuses what OpenAI refuses; delete is the
+// derived core's. Every operation has a beta twin (`?beta=true`) with the same semantics.
+import type { ScenarioDecision, Semantics } from '@volter/world-core';
+import { type OpenAIScenarioEngine, serveScenario } from '../openai-scenario.ts';
+import { buildResponse, createStoredResponse, emitResponse, responseMessages, responseSuffix, validateResponses, type ResponsesArgs } from '../openai-twin.ts';
+import type { OpenAIResponse } from '../openai-types.ts';
+import { readOnly } from './progress.ts';
+import { epoch, recordUsage, req, send, vendorView, type Row } from './shared.ts';
+
+type Ops = { resource: string; get: string; cancel: string };
+const GA: Ops = { resource: 'Response', get: 'getResponse', cancel: 'cancelResponse' };
+const BETA: Ops = { resource: 'BetaResponse', get: 'beta_getResponse', cancel: 'beta_cancelResponse' };
+
+/** Each built-in tool call a response made is billed as one (the usage reports' web search and file search calls). */
+async function recordToolCalls(ctx: Parameters<Semantics>[0], resp: OpenAIResponse): Promise<void> {
+  for (const item of resp.output) {
+    if (item.type === 'web_search_call') await recordUsage(ctx, 'web_search_calls', resp.model, 0, 0);
+    if (item.type === 'file_search_call') await recordUsage(ctx, 'file_search_calls', resp.model, 0, 0);
+  }
+}
+
+const create = (engine: OpenAIScenarioEngine | undefined, ops: Ops): Semantics => async (ctx) => {
+  const validated = validateResponses(ctx.params);
+  if ('error' in validated) return send(ctx, validated.error);
+  const args = validated.args;
+  // each stored input already holds its ancestry: continuing appends the prior output once
+  if (args.previousResponseId) {
+    const prior = ctx.row(ops.resource, args.previousResponseId);
+    if (!prior) return ctx.notFound(ops.resource, args.previousResponseId);
+    args.inputItems = [...((prior._input_items ?? []) as Row[]), ...((prior.output ?? []) as Row[]), ...args.inputItems];
+    args.messages = responseMessages(args.inputItems, args.instructions);
+  }
+  // the scenario decides the turn and honors a fault before any response exists, as on chat
+  const decision = engine ? await serveScenario(engine, { model: args.model, messages: args.messages, tools: args.tools, maxTokens: args.maxTokens }, new URL(ctx.call.request.url).pathname) : undefined;
+  if (decision?.kind === 'fault') return send(ctx, decision.result);
+  // a background response keeps its decision until its first poll, and streams nothing now
+  if (args.background) {
+    const queued = await createStoredResponse(args, req(ctx), decision);
+    return args.stream ? ctx.sse([]) : ctx.reply(queued);
+  }
+  const resp = args.store ? ((await createStoredResponse(args, req(ctx), decision)) as OpenAIResponse) : buildResponse(args, ctx.occurredAt, responseSuffix(args), decision);
+  const events: Array<{ event?: string; data: unknown }> = [];
+  if (args.stream) emitResponse(resp, (e) => { if (e.data) events.push({ event: String((e.data as { type?: unknown }).type ?? ''), data: e.data }); });
+  await recordUsage(ctx, 'responses', resp.model, resp.usage.input_tokens, resp.usage.output_tokens);
+  await recordToolCalls(ctx, resp);
+  return args.stream ? ctx.sse(events) : ctx.reply(resp);
+};
+
+// A background response is OpenAI's work, done over time: it is `queued`, then `in_progress` as its output is written,
+// then `completed` (https://platform.openai.com/docs/guides/background: "you can poll the response object... while the
+// status is `queued` or `in_progress`"). Extrapolation, the twin's own timing: a response waits a second in the queue, then
+// writes its output at 50 tokens a second; a poll in between sees the text written so far in a message still in progress.
+const QUEUED_SECONDS = 1;
+const TOKENS_PER_SECOND = 50;
+
+/** Where a background response has got to at `now`: its status and, in progress, the output written so far. */
+function backgroundAt(current: Row, now: number, occurredAt: string | undefined): { status: 'queued' } | { status: 'in_progress'; output: unknown[] } | { status: 'completed'; resp: OpenAIResponse; at: number } {
+  const created = Number(current.created_at);
+  const start = created + QUEUED_SECONDS;
+  if (now < start) return { status: 'queued' };
+  const args = JSON.parse(String(current._bg_args ?? '{}')) as ResponsesArgs;
+  const decision = current._bg_decision ? (JSON.parse(String(current._bg_decision)) as ScenarioDecision) : undefined;
+  const resp = buildResponse(args, occurredAt, String(current._bg_suffix ?? responseSuffix(args)), decision);
+  const finish = start + Math.max(1, Math.ceil(resp.usage.output_tokens / TOKENS_PER_SECOND));
+  if (now >= finish) return { status: 'completed', resp: { ...resp, created_at: created, completed_at: finish }, at: finish };
+  const share = (now - start) / (finish - start);
+  const output = resp.output.flatMap((item): unknown[] => {
+    if (item.type !== 'message') return item.type === 'reasoning' ? [item] : [];
+    const whole = item.content[0]?.text ?? '';
+    return [{ ...item, status: 'in_progress', content: [{ ...item.content[0], text: whole.slice(0, Math.floor(whole.length * share)) }] }];
+  });
+  return { status: 'in_progress', output };
+}
+
+/** Observe OpenAI's work on a background response up to now, deciding and writing at once so concurrent reads move it
+ *  once (and record its usage once, when it completes). */
+async function observe(ctx: Parameters<Semantics>[0], ops: Ops, id: string): Promise<Row | undefined> {
+  const now = epoch(ctx);
+  const polled = await ctx.atomically<{ row?: Row; completed?: OpenAIResponse }>((rows) => {
+    const current = rows(ops.resource).find((r) => r.id === id);
+    if (!current) return { value: {} };
+    if (current.status !== 'queued' && current.status !== 'in_progress') return { value: { row: current } };
+    const at = backgroundAt(current, now, ctx.occurredAt);
+    if (at.status === current.status && at.status === 'queued') return { value: { row: current } };
+    // the vendor's move, not the caller's: a poll finds it moved on
+    // (further text in a response already in progress is no move of its status)
+    const refusal = at.status === current.status ? undefined : ctx.legal(ops.resource, 'status', ops.get, current.status, at.status, id, 'vendor');
+    if (refusal) return { value: { row: current } };
+    const fields = at.status === 'completed'
+      ? { ...at.resp, background: true, _bg_args: null, _bg_suffix: null, _bg_decision: null }
+      : { status: 'in_progress', output: (at as { output: unknown[] }).output };
+    return { value: { row: { ...current, ...fields }, ...(at.status === 'completed' ? { completed: at.resp } : {}) }, write: { resource: ops.resource, id, fields, operation: 'response.update' } };
+  });
+  if (polled.completed) {
+    await recordUsage(ctx, 'responses', polled.completed.model, polled.completed.usage.input_tokens, polled.completed.usage.output_tokens);
+    await recordToolCalls(ctx, polled.completed);
+  }
+  return polled.row;
+}
+
+const retrieve = (ops: Ops): Semantics => async (ctx) => {
+  const id = String(ctx.id);
+  const row = ctx.row(ops.resource, id);
+  if (!row) return ctx.notFound(ops.resource, id);
+  // a read-only (mirror) twin holds the vendor's own state: it answers it as stored
+  if ((row.status !== 'queued' && row.status !== 'in_progress') || readOnly(ctx)) return ctx.reply(vendorView(row));
+  const seen = await observe(ctx, ops, id);
+  return seen ? ctx.reply(vendorView(seen)) : ctx.notFound(ops.resource, id);
+};
+
+// cancelling stops the response where OpenAI's work has got to: a queued one with no output, one in progress with the
+// output written so far, its message still `in_progress` (the reference's cancel example); a finished one is refused
+const cancel = (ops: Ops): Semantics => async (ctx) => {
+  const id = String(ctx.id);
+  let row = ctx.row(ops.resource, id);
+  if (!row) return ctx.notFound(ops.resource, id);
+  if ((row.status === 'queued' || row.status === 'in_progress') && !readOnly(ctx)) row = (await observe(ctx, ops, id)) ?? row;
+  const refusal = ctx.legal(ops.resource, 'status', ops.cancel, row.status, 'cancelled');
+  if (refusal) return ctx.refuse(refusal);
+  // cancelling a cancelled response again answers it as it is
+  if (row.status === 'cancelled') return ctx.reply(vendorView(row));
+  return ctx.reply(await ctx.write(ops.resource, id, { status: 'cancelled', _bg_args: null, _bg_suffix: null, _bg_decision: null }, 'response.cancel'));
+};
+
+// the input items folded into a stored response (its ancestry included)
+const inputItems = (ops: Ops): Semantics => async (ctx) => {
+  const id = String(ctx.id);
+  const row = ctx.row(ops.resource, id);
+  if (!row) return ctx.notFound(ops.resource, id);
+  // the list page names its first and last items, as every OpenAI list does
+  // (https://platform.openai.com/docs/api-reference/responses/input-items)
+  const data = (row._input_items as Row[] | undefined) ?? [];
+  return ctx.reply({ object: 'list', data, first_id: data[0]?.id ?? null, last_id: data.at(-1)?.id ?? null, has_more: false });
+};
+
+export function responses(engine: OpenAIScenarioEngine | undefined): Record<string, Semantics> {
+  return {
+    createResponse: create(engine, GA),
+    getResponse: retrieve(GA),
+    cancelResponse: cancel(GA),
+    listInputItems: inputItems(GA),
+    beta_createResponse: create(engine, BETA),
+    beta_getResponse: retrieve(BETA),
+    beta_cancelResponse: cancel(BETA),
+    beta_listInputItems: inputItems(BETA),
+  };
+}

package/src/semantics/shared.ts

@@ -0,0 +1,82 @@
+// What every OpenAI family's semantics share: its error answers, its cursor page, its update pick,
+// the usage ledger every billable call writes, and the request shape the pack's helpers in
+// ../openai-twin.ts take. All of it is over the SemanticsContext.
+import type { SemanticsContext } from '@volter/world-core';
+import { usageCost, type OpenAIRequest, type OpenAIResponseEnvelope } from '../openai-twin.ts';
+
+export type Row = Record<string, unknown>;
+
+/** The request shape the pack's shared helpers take. */
+export function req(ctx: SemanticsContext): OpenAIRequest {
+  const url = new URL(ctx.call.request.url);
+  return { method: ctx.call.request.method, path: url.pathname + url.search, occurredAt: ctx.occurredAt, ...(ctx.root !== undefined ? { root: ctx.root } : {}) };
+}
+
+/** An answer a pack helper built, with the headers it carries (a scripted fault's rate-limit family). */
+export function send(ctx: SemanticsContext, r: OpenAIResponseEnvelope): Response {
+  if (!r.headers) return ctx.reply(r.body, r.status);
+  return new Response(JSON.stringify(r.body), { status: r.status, headers: { 'content-type': 'application/json', ...r.headers } });
+}
+
+/** OpenAI's invalid_request_error: 400 with the parameter it names and the code when there is one. */
+export const invalid = (ctx: SemanticsContext, message: string, param?: string, code?: string): Response =>
+  ctx.refuse({ status: 400, message, ...(param ? { param } : {}), ...(code ? { code } : {}) });
+
+/** A 404 in OpenAI's error shape, with the message the family uses. */
+export const missing = (ctx: SemanticsContext, message: string, code?: string): Response => ctx.refuse({ status: 404, message, ...(code ? { code } : {}) });
+
+/** The world clock as OpenAI's unix seconds. */
+export const epoch = (ctx: SemanticsContext): number => Number(ctx.now());
+
+/** A path parameter, by the name the spec gives it. */
+export const at = (ctx: SemanticsContext, name: string): string => ctx.call.params[name] ?? '';
+
+/** An object parameter, or the fallback when the caller sent none. */
+export const objectOr = (v: unknown, fallback: unknown): unknown => (v && typeof v === 'object' ? v : fallback);
+
+/** Only the updatable fields present in the request (OpenAI's modify-by-POST). */
+export function pick(params: Row, keys: string[]): Row {
+  const out: Row = {};
+  for (const k of keys) if (params[k] !== undefined) out[k] = params[k];
+  return out;
+}
+
+/** Where a page starts after the cursor `after`: past that id, or past the end for an unknown one. */
+function startAfter(items: Row[], after: string): number {
+  const i = items.findIndex((it) => it.id === after);
+  return i >= 0 ? i + 1 : items.length;
+}
+
+/** OpenAI's cursor page over items already in list order: `after` starts past that id (an unknown
+ *  one past the end), `limit` defaults to 20 and caps at 100. */
+export function page(ctx: SemanticsContext, items: Row[]): Response {
+  const after = typeof ctx.params.after === 'string' ? ctx.params.after : '';
+  let limit = Number(ctx.params.limit);
+  if (!Number.isInteger(limit) || limit < 1) limit = 20;
+  if (limit > 100) limit = 100;
+  const start = after ? startAfter(items, after) : 0;
+  const data = items.slice(start, start + limit);
+  return ctx.reply({ object: 'list', data, has_more: start + limit < items.length, first_id: data[0]?.id ?? null, last_id: data[data.length - 1]?.id ?? null });
+}
+
+/** A stored row as OpenAI shows it, from the raw row a handler read for its bookkeeping: its id
+ *  first, the kernel's fields and the twin's own (`_`-prefixed) left out. */
+export function vendorView(r: Row): Row {
+  const out: Row = { id: r.id };
+  for (const [k, v] of Object.entries(r)) if (k !== 'type' && k !== 'updatedAt' && !k.startsWith('_')) out[k] = v;
+  return out;
+}
+
+/** Newest first by `created_at`, rows of one instant by mint order (`proj-twin-10` newer than `proj-twin-9`), as the
+ *  derived core lists. */
+export const newest = (items: Row[], field = 'created_at'): Row[] => [...items].sort((a, b) => Number(b[field]) - Number(a[field]) || String(b.id).localeCompare(String(a.id), undefined, { numeric: true }));
+
+/** A billable call's usage, priced per model: what the organization usage and costs reports read. `extra` is what the
+ *  call's own report counts besides tokens (a speech's characters, a transcription's seconds, an image call's images,
+ *  size and source, a container's session). */
+export async function recordUsage(ctx: SemanticsContext, kind: string, model: string, inputTokens: number, outputTokens: number, extra: Row = {}): Promise<void> {
+  await ctx.record('_usage_record', {
+    object: '_usage_record', kind, model, input_tokens: inputTokens, output_tokens: outputTokens,
+    num_model_requests: 1, cost_usd: usageCost(model, inputTokens, outputTokens), created_at: epoch(ctx), ...extra,
+  });
+}

package/src/semantics/uploads.ts

@@ -0,0 +1,92 @@
+// Upload semantics: a large file sent in parts. Create an Upload, add parts, then complete it (the
+// parts, in the order the caller names, become one File) or cancel it. An Upload is stored as
+// 'upload' beside the File it becomes; its parts are bookkeeping on it (`_parts`). The spec names no
+// Upload resource, so the manifest declares one for its id and its `status` machine.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { expiresAt } from './files.ts';
+import { epoch, invalid, type Row } from './shared.ts';
+
+const UPLOAD = 'Upload';
+
+/** The Upload the path names, when the machine in ../manifest.ts lets `operationId` act on it (only a
+ *  pending one takes parts, completes or cancels), or OpenAI's answer. */
+async function pending(ctx: SemanticsContext, operationId: string, to?: string): Promise<{ upload: Row } | { answer: Response }> {
+  const id = String(ctx.id);
+  let upload = ctx.row(UPLOAD, id, { withDeleted: true });
+  if (!upload) return { answer: ctx.notFound(UPLOAD, id) };
+  // a pending Upload expires an hour after it was created (its expires_at): the clock's move, seen when a use looks
+  if (upload.status === 'pending' && Number(upload.expires_at) <= epoch(ctx) && !ctx.legal(UPLOAD, 'status', operationId, 'pending', 'expired', id, 'time')) {
+    upload = { ...upload, ...(await ctx.write(UPLOAD, id, { status: 'expired' }, 'upload.update')) };
+  }
+  const refusal = ctx.legal(UPLOAD, 'status', operationId, upload.status, to, id);
+  return refusal ? { answer: ctx.refuse(refusal) } : { upload };
+}
+
+const create: Semantics = async (ctx) => {
+  const p = ctx.params;
+  for (const k of ['filename', 'purpose', 'bytes', 'mime_type']) {
+    if (p[k] === undefined || p[k] === '') return invalid(ctx, `you must provide a ${k} parameter`, k);
+  }
+  const created = epoch(ctx);
+  const fields = {
+    object: 'upload', created_at: created, filename: String(p.filename), bytes: Number(p.bytes),
+    purpose: String(p.purpose), mime_type: String(p.mime_type), status: 'pending',
+    expires_at: created + 3600, file: null,
+  };
+  return ctx.reply(await ctx.write(UPLOAD, ctx.mint(UPLOAD), fields, 'upload.create'));
+};
+
+// A part's `data` is a multipart file from the SDK, or a string from an in-process caller.
+const addPart: Semantics = async (ctx) => {
+  const found = await pending(ctx, 'addUploadPart');
+  if ('answer' in found) return found.answer;
+  const data = ctx.params.data;
+  if (data === undefined) return invalid(ctx, 'you must provide a data parameter', 'data');
+  const id = String(found.upload.id);
+  const parts = Array.isArray(found.upload._parts) ? [...(found.upload._parts as unknown[])] : [];
+  const partId = `part-twin-${id}-${parts.length + 1}`;
+  parts.push({ id: partId, data: data && typeof data === 'object' ? String((data as { content?: unknown }).content ?? '') : String(data) });
+  await ctx.write(UPLOAD, id, { _parts: parts }, 'upload.update');
+  return ctx.reply({ id: partId, object: 'upload.part', created_at: epoch(ctx), upload_id: id });
+};
+
+const complete: Semantics = async (ctx) => {
+  const found = await pending(ctx, 'completeUpload', 'completed');
+  if ('answer' in found) return found.answer;
+  const upload = found.upload;
+  const partIds = ctx.params.part_ids;
+  if (!Array.isArray(partIds) || partIds.length === 0) return invalid(ctx, 'you must provide a part_ids array', 'part_ids');
+  const parts = Array.isArray(upload._parts) ? (upload._parts as Array<{ id: string; data: string }>) : [];
+  const byId = new Map(parts.map((part) => [part.id, part.data]));
+  let content = '';
+  for (const pid of partIds) {
+    if (!byId.has(String(pid))) return invalid(ctx, `unknown part_id '${pid}'`, 'part_ids');
+    content += byId.get(String(pid));
+  }
+  // OpenAI refuses to assemble a file whose parts do not add up to the bytes declared at creation
+  // (https://platform.openai.com/docs/api-reference/uploads/complete). Extrapolation: the wording is
+  // not sourced from a recording.
+  const sent = new TextEncoder().encode(content).length;
+  const declared = Number(upload.bytes);
+  if (sent !== declared) return invalid(ctx, `The number of bytes uploaded (${sent}) does not match the number of bytes specified when the Upload was created (${declared}).`, 'bytes');
+  const file = await ctx.write(
+    'OpenAIFile',
+    ctx.mint('OpenAIFile'),
+    { object: 'file', bytes: Number(upload.bytes ?? content.length), created_at: epoch(ctx), expires_at: expiresAt(String(upload.purpose), epoch(ctx), undefined), filename: String(upload.filename), purpose: String(upload.purpose), status: 'processed', _content: content },
+    'file.create',
+  );
+  return ctx.reply(await ctx.write(UPLOAD, String(upload.id), { status: 'completed', file }, 'upload.update'));
+};
+
+const cancel: Semantics = async (ctx) => {
+  const found = await pending(ctx, 'cancelUpload', 'cancelled');
+  if ('answer' in found) return found.answer;
+  return ctx.reply(await ctx.write(UPLOAD, String(found.upload.id), { status: 'cancelled' }, 'upload.cancel'));
+};
+
+export const uploads: Record<string, Semantics> = {
+  createUpload: create,
+  addUploadPart: addPart,
+  completeUpload: complete,
+  cancelUpload: cancel,
+};