@volter/twin-openai 0.1.2 → 2.0.0

package/dist/src/openai-conformance.d.ts

@@ -0,0 +1,13 @@
+export type ConformanceViolation = {
+    check: string;
+    detail: string;
+};
+export type OpenAIConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    violations: ConformanceViolation[];
+};
+/** Run the offline conformance checks against a fresh temp root. */
+export declare function checkOpenAIConformance(opts?: {
+    root?: string;
+}): Promise<OpenAIConformanceReport>;

package/dist/src/openai-conformance.js

@@ -0,0 +1,116 @@
+// 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 — the labeled stub is the twin's answer).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleOpenAITwinRequest } from "./openai-twin.js";
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkOpenAIConformance(opts = {}) {
+    const root = opts.root ?? mkdtempSync(join(tmpdir(), 'openai-conf-'));
+    const owned = opts.root === undefined;
+    const violations = [];
+    let checksRun = 0;
+    const fail = (check, detail) => violations.push({ check, detail });
+    const H = (method, path, body, sseSink) => 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;
+        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;
+            if (!Array.isArray(choices) || !isObj(choices[0]) || choices[0].message?.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;
+            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 = [];
+        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?.[0]?.delta?.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.choices;
+        if ((tc?.[0]?.finish_reason) !== 'tool_calls')
+            fail('chat.tool_calls', 'finish_reason not tool_calls');
+        const calls = tc?.[0]?.message?.tool_calls;
+        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;
+        if (rb.object !== 'response' || !Array.isArray(rb.output) || rb.output[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.data?.[0]?.embedding;
+        const v2 = e2.body.data?.[0]?.embedding;
+        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.data))
+            fail('models.list', 'no data array');
+        const one = await H('GET', '/v1/models/gpt-4o');
+        if (one.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.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.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.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' }] }));
+        const eb = bad.body;
+        if (bad.status !== 400 || !isObj(eb.error) || eb.error.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.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/dist/src/openai-connector.d.ts

@@ -0,0 +1,86 @@
+import { type RemoteExecute, type PerformContext, type PushOutcome } from '@volter/world-core';
+import type { SyncResource, TwinAction } from '@volter/world-core';
+import { OpenAIBudget, type OpenAIBudgetOptions } from './openai-budget.js';
+/**
+ * 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 declare function liveOpenAIExecute(apiKey: string, base?: string, opts?: LiveOpenAIOptions): OpenAIExecute;
+/** Map a real-OpenAI File object → a twin sync resource. */
+export declare function mapFile(f: Record<string, unknown>): SyncResource;
+/** Map a real-OpenAI Batch object → a twin sync resource. */
+export declare function mapBatch(b: Record<string, unknown>): SyncResource;
+/** Map a real-OpenAI fine-tuning job → a twin sync resource. */
+export declare function mapFineTune(j: Record<string, unknown>): SyncResource;
+/** Map a real-OpenAI vector store → a twin sync resource. */
+export declare function mapVectorStore(v: Record<string, unknown>): SyncResource;
+/** Pull all modeled real collections via the executor and map them to twin sync resources. */
+export declare function pullOpenAIState(execute: OpenAIExecute): Promise<SyncResource[]>;
+/**
+ * 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 declare function syncOpenAIFromReal(execute: OpenAIExecute, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * 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 declare function openaiRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): {
+    method: 'GET' | 'POST' | 'DELETE';
+    path: string;
+};
+/**
+ * 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 declare function pushOpenAIAction(execute: OpenAIExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): Promise<{
+    externalId: string;
+}>;
+export declare function openaiExecuteOver(execute: RemoteExecute): OpenAIExecute;
+export declare function performOpenAIAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/openai-connector.js

@@ -0,0 +1,291 @@
+// 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, observeResource } from '@volter/world-core';
+import { OpenAIBudget, OpenAIBudgetError, openaiCallWeight } from "./openai-budget.js";
+const SERVICE = 'openai';
+/**
+ * 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, base = 'https://api.openai.com', opts = {}) {
+    // `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 = { authorization: `Bearer ${apiKey}` };
+        const init = { 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 = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const parsed = (await res.json());
+        // 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.
+        // 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;
+    };
+}
+function listOf(res) {
+    return Array.isArray(res.data) ? res.data : [];
+}
+function throwIfError(res, ctx) {
+    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) {
+    return {
+        type: 'file',
+        id: String(f.id),
+        fields: {
+            object: 'file',
+            bytes: f.bytes ?? 0,
+            created_at: f.created_at ?? null,
+            filename: f.filename ?? null,
+            purpose: f.purpose ?? null,
+            status: f.status ?? null,
+        },
+    };
+}
+/** Map a real-OpenAI Batch object → a twin sync resource. */
+export function mapBatch(b) {
+    const counts = (b.request_counts && typeof b.request_counts === 'object') ? b.request_counts : {};
+    return {
+        type: 'batch',
+        id: String(b.id),
+        fields: {
+            object: 'batch',
+            endpoint: b.endpoint ?? null,
+            input_file_id: b.input_file_id ?? null,
+            completion_window: b.completion_window ?? null,
+            status: b.status ?? null,
+            output_file_id: b.output_file_id ?? null,
+            created_at: b.created_at ?? null,
+            completed_at: b.completed_at ?? null,
+            request_counts: counts,
+        },
+    };
+}
+/** Map a real-OpenAI fine-tuning job → a twin sync resource. */
+export function mapFineTune(j) {
+    return {
+        type: 'fine_tuning_job',
+        id: String(j.id),
+        fields: {
+            object: 'fine_tuning.job',
+            model: j.model ?? null,
+            status: j.status ?? null,
+            fine_tuned_model: j.fine_tuned_model ?? null,
+            training_file: j.training_file ?? null,
+            created_at: j.created_at ?? null,
+            finished_at: j.finished_at ?? null,
+        },
+    };
+}
+/** Map a real-OpenAI vector store → a twin sync resource. */
+export function mapVectorStore(v) {
+    const counts = (v.file_counts && typeof v.file_counts === 'object') ? v.file_counts : {};
+    return {
+        type: 'vector_store',
+        id: String(v.id),
+        fields: {
+            object: 'vector_store',
+            name: v.name ?? null,
+            status: v.status ?? null,
+            created_at: v.created_at ?? null,
+            usage_bytes: v.usage_bytes ?? 0,
+            file_counts: counts,
+        },
+    };
+}
+const COLLECTIONS = [
+    { 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) {
+    const out = [];
+    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, opts) {
+    const resources = await pullOpenAIState(execute);
+    // 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 ────────────────────────────────────────────────────────────────────
+// 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) {
+    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 = {
+    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) {
+    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, action) {
+    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.id;
+    return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+function createPayload(action) {
+    const f = (action.fields ?? {});
+    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 {};
+    }
+}
+// ── 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) {
+    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);
+        }
+        catch {
+            return { error: { message: `openai answered ${res.status} with a body that is not JSON` } };
+        }
+    };
+}
+export async function performOpenAIAction(execute, action, _ctx) {
+    if (action.subject.type === 'chat_completion') {
+        const f = (action.fields ?? {});
+        const messages = Array.isArray(f._input_messages) ? f._input_messages.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.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 };
+    }
+    const { externalId } = await pushOpenAIAction(openaiExecuteOver(execute), action);
+    return { externalId };
+}

package/dist/src/openai-media.d.ts

@@ -0,0 +1,43 @@
+/** The raw bytes of an uploaded file part, as the request's multipart parse keeps them; undefined for a string. */
+export declare function partBytes(v: unknown): Uint8Array | undefined;
+/** An image's format by its signature: png, jpg or webp, else undefined. */
+export declare const imageFormat: (b: Uint8Array) => "png" | "jpg" | "webp" | undefined;
+/** A PNG's width and height from its IHDR chunk. */
+export declare function pngSize(b: Uint8Array): {
+    width: number;
+    height: number;
+};
+/** An audio file's format by its signature, among those OpenAI transcribes, else undefined. */
+export declare const audioFormat: (b: Uint8Array) => string | undefined;
+/** 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 declare function wavSeconds(b: Uint8Array): number | undefined;
+/** The size an image request asks for (`1536x1024`), or the fallback for `auto` or none. */
+export declare function requestedSize(size: unknown, fallback?: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+};
+/** A real PNG of the size asked, one flat colour drawn from `seed`, labeled as the twin's placeholder. */
+export declare function placeholderPng(size: {
+    width: number;
+    height: number;
+}, seed: string): Uint8Array;
+/** Bytes as base64. */
+export declare function base64(b: Uint8Array): string;
+/** A second of 24 kHz 16-bit mono silence as samples' bytes: `pcm`, raw little-endian with no header. */
+export declare const silentPcm: () => Uint8Array;
+/** The same second as a WAV file. */
+export declare function silentWav(): Uint8Array;
+/** 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 declare function silentMp3(): Uint8Array;
+/** The same second as FLAC: a STREAMINFO block and frames of 4096 samples, each one CONSTANT subframe of zero. */
+export declare function silentFlac(): Uint8Array;
+/** 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 declare function silentAac(): Uint8Array;
+/** The same second as Opus in Ogg: its identification and comment headers, then 20 ms packets of silence. */
+export declare function silentOpus(): Uint8Array;