@volter/world-core 2.0.36 → 3.0.0

package/dist/src/sigv4.d.ts

@@ -0,0 +1,48 @@
+export type SigV4Verdict = {
+    ok: true;
+    keyId: string;
+    region: string;
+    service: string;
+} | {
+    ok: false;
+    reason: 'unsigned' | 'malformed' | 'unknown_key' | 'bad_signature' | 'expired';
+    keyId?: string;
+};
+/** The path a request arrived with, where the kernel routed it by another (a virtual-hosted bucket put in front of the
+ *  path: pack-fetch's `routed`); a client signed the path it sent. */
+export declare const ORIGINAL_PATH_HEADER = "x-volter-original-path";
+/**
+ * Whether `request` is signed with SigV4 by a key `secretOf` knows (its secret, or undefined for a key the twin never
+ * issued). `body` is the bytes it carries (the payload hash of
+ * a service that sends no `x-amz-content-sha256`); `now` is the World's instant, in epoch milliseconds, for a presigned
+ * URL's expiry. The caller decides what an unsigned request is (a public read, or a refusal).
+ */
+export declare function verifySigV4(request: Request, body: Uint8Array | string | undefined, secretOf: (keyId: string) => string | undefined | Promise<string | undefined>, now: number): Promise<SigV4Verdict>;
+/**
+ * The SigV4 headers a client adds (`authorization`, `x-amz-date`, and for S3 `x-amz-content-sha256`), signed over the
+ * request as it will be sent: its method, URL, the headers it carries (host, `x-amz-*` and the content type are signed)
+ * and its body, at `at`. What a walk sends as an AWS SDK sends it; the verifier above is its other side.
+ */
+export declare function signSigV4(input: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+    keyId: string;
+    secret: string;
+    region: string;
+    service: string;
+    at: Date;
+}): Record<string, string>;
+/**
+ * A presigned URL signed again with a key: its date, expiry, region, service and signed headers are the URL's own
+ * (X-Amz-Date, X-Amz-Expires, X-Amz-Credential's scope, X-Amz-SignedHeaders, `host` when it names none), its key and
+ * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it.
+ */
+export declare function presignSigV4(input: {
+    method: string;
+    url: string;
+    keyId: string;
+    secret: string;
+    host?: string;
+}): string;

package/dist/src/sigv4.js

@@ -0,0 +1,167 @@
+// AWS Signature Version 4, VERIFIED: what an AWS-shaped twin (S3, Secrets Manager, R2's S3 endpoint) checks before it
+// answers a signed request. The published algorithm (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html,
+// "Create a signed AWS API request"), the same one executor.ts signs with, run from the other side: the request names
+// its access key, its credential scope and the headers it signed; the twin finds the key's secret, builds the canonical
+// request from what arrived, and compares signatures. A presigned URL carries the same parts in its query
+// (X-Amz-Credential, X-Amz-SignedHeaders, X-Amz-Signature; its payload `UNSIGNED-PAYLOAD`).
+//
+// Where the request reached the twin rather than the vendor, the host it signed is the vendor's: the World's injector
+// names it (`x-volter-twin-original-host`), else the Host the request carries, else its URL's. S3 signs its path as
+// sent and every other service encodes it a second time (the specification's own clause, as in executor.ts). A
+// streaming upload (`STREAMING-AWS4-HMAC-SHA256-PAYLOAD`) is checked by its seed signature; its chunk signatures are
+// not (the twin's reading: the seed binds the request, and the chunks are the body the twin keeps).
+import * as nodeCrypto from 'node:crypto';
+/** The path a request arrived with, where the kernel routed it by another (a virtual-hosted bucket put in front of the
+ *  path: pack-fetch's `routed`); a client signed the path it sent. */
+export const ORIGINAL_PATH_HEADER = 'x-volter-original-path';
+const rfc3986 = (v) => encodeURIComponent(v).replace(/[!\x27()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+const sha256Hex = (data) => nodeCrypto.createHash('sha256').update(data).digest('hex');
+const hmac = (key, data) => nodeCrypto.createHmac('sha256', key).update(data).digest();
+/** The time a SigV4 date names (`20260105T093000Z`), in epoch milliseconds. */
+const dateOf = (amz) => Date.parse(`${amz.slice(0, 4)}-${amz.slice(4, 6)}-${amz.slice(6, 8)}T${amz.slice(9, 11)}:${amz.slice(11, 13)}:${amz.slice(13, 15)}Z`);
+/**
+ * Whether `request` is signed with SigV4 by a key `secretOf` knows (its secret, or undefined for a key the twin never
+ * issued). `body` is the bytes it carries (the payload hash of
+ * a service that sends no `x-amz-content-sha256`); `now` is the World's instant, in epoch milliseconds, for a presigned
+ * URL's expiry. The caller decides what an unsigned request is (a public read, or a refusal).
+ */
+export async function verifySigV4(request, body, secretOf, now) {
+    const url = new URL(request.url);
+    const header = request.headers.get('authorization') ?? '';
+    const presigned = url.searchParams.get('X-Amz-Algorithm') === 'AWS4-HMAC-SHA256';
+    let credential;
+    let signedHeaders;
+    let signature;
+    let amzDate;
+    let payloadHash;
+    if (/^AWS4-HMAC-SHA256\s/i.test(header)) {
+        const parts = Object.fromEntries(header.replace(/^AWS4-HMAC-SHA256\s+/i, '').split(/,\s*/).map((p) => { const at = p.indexOf('='); return [p.slice(0, at).trim(), p.slice(at + 1).trim()]; }));
+        if (!parts.Credential || !parts.SignedHeaders || !parts.Signature)
+            return { ok: false, reason: 'malformed' };
+        credential = parts.Credential;
+        signedHeaders = parts.SignedHeaders;
+        signature = parts.Signature;
+        amzDate = request.headers.get('x-amz-date') ?? '';
+        const declared = request.headers.get('x-amz-content-sha256');
+        payloadHash = declared ?? sha256Hex(body ?? '');
+    }
+    else if (presigned) {
+        credential = url.searchParams.get('X-Amz-Credential') ?? '';
+        signedHeaders = url.searchParams.get('X-Amz-SignedHeaders') ?? '';
+        signature = url.searchParams.get('X-Amz-Signature') ?? '';
+        amzDate = url.searchParams.get('X-Amz-Date') ?? '';
+        payloadHash = 'UNSIGNED-PAYLOAD';
+        const expires = Number(url.searchParams.get('X-Amz-Expires') ?? '');
+        if (!Number.isFinite(expires) || !/^\d{8}T\d{6}Z$/.test(amzDate))
+            return { ok: false, reason: 'malformed' };
+        if (now > dateOf(amzDate) + expires * 1000)
+            return { ok: false, reason: 'expired' };
+    }
+    else {
+        return { ok: false, reason: 'unsigned' };
+    }
+    const [keyId = '', dateStamp = '', region = '', service = '', terminal = ''] = credential.split('/');
+    if (!keyId || terminal !== 'aws4_request' || !/^\d{8}$/.test(dateStamp) || !/^\d{8}T\d{6}Z$/.test(amzDate))
+        return { ok: false, reason: 'malformed', ...(keyId ? { keyId } : {}) };
+    const secret = await secretOf(keyId);
+    if (secret === undefined)
+        return { ok: false, reason: 'unknown_key', keyId };
+    // A canonical request binds the declared hash; the declaration must also describe the bytes received.
+    // S3's UNSIGNED-PAYLOAD and streaming markers are separate wire modes, not ordinary payload digests.
+    // https://docs.aws.amazon.com/AmazonS3/latest/developerguide/sig-v4-header-based-auth.html
+    const declaredPayload = request.headers.get('x-amz-content-sha256');
+    if (declaredPayload !== null && /^[0-9a-f]{64}$/i.test(declaredPayload)
+        && declaredPayload.toLowerCase() !== sha256Hex(body ?? '')) {
+        return { ok: false, reason: 'bad_signature', keyId };
+    }
+    const host = request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host;
+    const sentPath = request.headers.get(ORIGINAL_PATH_HEADER) ?? url.pathname;
+    const raw = sentPath === '' ? '/' : sentPath;
+    const canonicalUri = service === 's3' ? raw : raw.split('/').map((segment) => rfc3986(decodeURIComponent(segment))).map(rfc3986).join('/');
+    const canonicalQuery = [...url.searchParams.entries()]
+        .filter(([k]) => !(presigned && k === 'X-Amz-Signature'))
+        .map(([k, v]) => [rfc3986(k), rfc3986(v)])
+        .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const names = signedHeaders.toLowerCase().split(';').filter(Boolean);
+    const value = (name) => (name === 'host' ? host : (request.headers.get(name) ?? '')).trim().replace(/\s+/g, ' ');
+    const canonicalHeaders = names.map((n) => `${n}:${value(n)}\n`).join('');
+    const canonicalRequest = [request.method.toUpperCase(), canonicalUri, canonicalQuery, canonicalHeaders, names.join(';'), payloadHash].join('\n');
+    const scope = `${dateStamp}/${region}/${service}/aws4_request`;
+    const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n');
+    let key = hmac(`AWS4${secret}`, dateStamp);
+    for (const part of [region, service, 'aws4_request'])
+        key = hmac(key, part);
+    const expected = hmac(key, stringToSign).toString('hex');
+    const given = Buffer.from(signature.toLowerCase(), 'utf8');
+    const want = Buffer.from(expected, 'utf8');
+    if (given.length !== want.length || !nodeCrypto.timingSafeEqual(given, want))
+        return { ok: false, reason: 'bad_signature', keyId };
+    return { ok: true, keyId, region, service };
+}
+/**
+ * The SigV4 headers a client adds (`authorization`, `x-amz-date`, and for S3 `x-amz-content-sha256`), signed over the
+ * request as it will be sent: its method, URL, the headers it carries (host, `x-amz-*` and the content type are signed)
+ * and its body, at `at`. What a walk sends as an AWS SDK sends it; the verifier above is its other side.
+ */
+export function signSigV4(input) {
+    const url = new URL(input.url);
+    const amzDate = `${input.at.toISOString().slice(0, 19).replace(/[:-]/g, '')}Z`;
+    const dateStamp = amzDate.slice(0, 8);
+    const payloadHash = sha256Hex(input.body ?? '');
+    const raw = url.pathname === '' ? '/' : url.pathname;
+    const canonicalUri = input.service === 's3' ? raw : raw.split('/').map((segment) => rfc3986(decodeURIComponent(segment))).map(rfc3986).join('/');
+    const canonicalQuery = [...url.searchParams.entries()]
+        .map(([k, v]) => [rfc3986(k), rfc3986(v)])
+        .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const added = { 'x-amz-date': amzDate, ...(input.service === 's3' ? { 'x-amz-content-sha256': payloadHash } : {}) };
+    const signable = new Map([['host', url.host]]);
+    for (const [name, value] of Object.entries({ ...(input.headers ?? {}), ...added })) {
+        const n = name.toLowerCase();
+        if (n.startsWith('x-amz-') || n === 'content-type')
+            signable.set(n, value.trim().replace(/\s+/g, ' '));
+    }
+    const names = [...signable.keys()].sort();
+    const canonicalRequest = [input.method.toUpperCase(), canonicalUri, canonicalQuery, names.map((n) => `${n}:${signable.get(n)}\n`).join(''), names.join(';'), payloadHash].join('\n');
+    const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+    const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n');
+    let key = hmac(`AWS4${input.secret}`, dateStamp);
+    for (const part of [input.region, input.service, 'aws4_request'])
+        key = hmac(key, part);
+    return { ...added, authorization: `AWS4-HMAC-SHA256 Credential=${input.keyId}/${scope}, SignedHeaders=${names.join(';')}, Signature=${hmac(key, stringToSign).toString('hex')}` };
+}
+/**
+ * A presigned URL signed again with a key: its date, expiry, region, service and signed headers are the URL's own
+ * (X-Amz-Date, X-Amz-Expires, X-Amz-Credential's scope, X-Amz-SignedHeaders, `host` when it names none), its key and
+ * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it.
+ */
+export function presignSigV4(input) {
+    const url = new URL(input.url);
+    const q = url.searchParams;
+    const [, dateStamp = '', region = '', service = ''] = (q.get('X-Amz-Credential') ?? '').split('/');
+    const amzDate = q.get('X-Amz-Date') ?? '';
+    q.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+    q.set('X-Amz-Credential', `${input.keyId}/${dateStamp}/${region}/${service}/aws4_request`);
+    if (!q.has('X-Amz-SignedHeaders'))
+        q.set('X-Amz-SignedHeaders', 'host');
+    q.delete('X-Amz-Signature');
+    const raw = url.pathname === '' ? '/' : url.pathname;
+    const canonicalUri = service === 's3' ? raw : raw.split('/').map((segment) => rfc3986(decodeURIComponent(segment))).map(rfc3986).join('/');
+    const canonicalQuery = [...q.entries()]
+        .map(([k, v]) => [rfc3986(k), rfc3986(v)])
+        .sort((left, right) => (left[0] === right[0] ? (left[1] < right[1] ? -1 : 1) : left[0] < right[0] ? -1 : 1))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const names = (q.get('X-Amz-SignedHeaders') ?? 'host').toLowerCase().split(';').filter(Boolean);
+    const canonicalHeaders = names.map((n) => `${n}:${n === 'host' ? (input.host ?? url.host) : ''}\n`).join('');
+    const canonicalRequest = [input.method.toUpperCase(), canonicalUri, canonicalQuery, canonicalHeaders, names.join(';'), 'UNSIGNED-PAYLOAD'].join('\n');
+    const stringToSign = ['AWS4-HMAC-SHA256', amzDate, `${dateStamp}/${region}/${service}/aws4_request`, sha256Hex(canonicalRequest)].join('\n');
+    let key = hmac(`AWS4${input.secret}`, dateStamp);
+    for (const part of [region, service, 'aws4_request'])
+        key = hmac(key, part);
+    q.set('X-Amz-Signature', hmac(key, stringToSign).toString('hex'));
+    return url.toString();
+}

package/dist/src/smtp.d.ts

@@ -0,0 +1,16 @@
+/** Where a mail goes: the SMTP host and port, and the sender. */
+export type SmtpRoute = {
+    host: string;
+    port: number;
+    from: string;
+    senderName?: string;
+};
+/** One mail: its recipient, subject and HTML body. */
+export type Mail = {
+    to: string;
+    subject: string;
+    html: string;
+};
+/** Send one mail. Throws when it cannot be delivered (refused by the World's egress rule, unreachable, or refused by the
+ *  server), so the vendor answers its own mailer failure. */
+export declare function sendMail(route: SmtpRoute, mail: Mail, headers?: Record<string, string>): Promise<void>;

package/dist/src/smtp.js

@@ -0,0 +1,72 @@
+// A vendor's mail to a person, sent over SMTP (plain, no authentication) to the host the vendor's settings name — in a
+// World, the World's mail twin — as the vendor's own mailer sends it (GoTrue's confirmation and magic links). A handler
+// reaches it as `ctx.mail`. The World's egress rule is applied before the socket opens: a sealed World or one with a
+// network policy refuses a host outside it; a local World with neither lets a configured outside host be reached, as it
+// lets the application reach one. The socket is opened only when a mail is sent (nothing at import).
+class SmtpSession {
+    socket;
+    buffer = '';
+    waiting = [];
+    constructor(socket) {
+        this.socket = socket;
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            this.buffer += chunk;
+            let end;
+            // a reply is complete at a line whose code is followed by a space (multi-line replies use a dash)
+            while ((end = this.buffer.search(/^\d{3} .*\r?\n/m)) >= 0) {
+                const lineEnd = this.buffer.indexOf('\n', end);
+                const reply = this.buffer.slice(0, lineEnd + 1);
+                this.buffer = this.buffer.slice(lineEnd + 1);
+                this.waiting.shift()?.(reply.trim().split(/\r?\n/).pop());
+            }
+        });
+    }
+    reply() { return new Promise((resolve) => this.waiting.push(resolve)); }
+    async command(line, expect) {
+        const next = this.reply();
+        this.socket.write(`${line}\r\n`);
+        const reply = await next;
+        if (!reply.startsWith(String(expect)))
+            throw new Error(`SMTP ${line.split(' ')[0]}: ${reply}`);
+    }
+}
+/** How long a mail may take, connect to QUIT (a host that never answers must not hold the request open). */
+const SMTP_TIMEOUT_MS = 10_000;
+/** Send one mail. Throws when it cannot be delivered (refused by the World's egress rule, unreachable, or refused by the
+ *  server), so the vendor answers its own mailer failure. */
+export async function sendMail(route, mail, headers = {}) {
+    const [{ connect }, { worldEgressRefusal }] = await Promise.all([
+        import('node:net'),
+        import('../network-policy.cjs'),
+    ]);
+    const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`);
+    if (refusal !== null)
+        throw new Error(refusal);
+    const socket = connect(route.port, route.host);
+    socket.setTimeout(SMTP_TIMEOUT_MS, () => socket.destroy(new Error(`SMTP ${route.host}:${route.port}: no answer in ${SMTP_TIMEOUT_MS} ms`)));
+    const session = new SmtpSession(socket);
+    const greeting = session.reply();
+    const failed = new Promise((_, reject) => { socket.once('error', reject); socket.once('close', () => reject(new Error('SMTP connection closed'))); });
+    failed.catch(() => { });
+    const step = (p) => Promise.race([p, failed]);
+    await step(new Promise((resolve) => { socket.once('connect', () => resolve()); }));
+    try {
+        if (!(await step(greeting)).startsWith('220'))
+            throw new Error('SMTP: no greeting');
+        await step(session.command(`EHLO ${route.from.split('@')[1] ?? 'localhost'}`, 250));
+        await step(session.command(`MAIL FROM:<${route.from}>`, 250));
+        await step(session.command(`RCPT TO:<${mail.to}>`, 250));
+        await step(session.command('DATA', 354));
+        const from = route.senderName ? `"${route.senderName.replace(/"/g, '')}" <${route.from}>` : route.from;
+        const lines = [
+            `From: ${from}`, `To: ${mail.to}`, `Subject: ${mail.subject}`, 'MIME-Version: 1.0', 'Content-Type: text/html; charset=utf-8',
+            ...Object.entries(headers).map(([k, v]) => `${k}: ${v}`), '', ...mail.html.split(/\r?\n/).map((l) => (l.startsWith('.') ? `.${l}` : l)),
+        ];
+        await step(session.command(`${lines.join('\r\n')}\r\n.`, 250));
+        await step(session.command('QUIT', 221)).catch(() => { });
+    }
+    finally {
+        socket.destroy();
+    }
+}

package/dist/src/sockets.d.ts

@@ -0,0 +1,51 @@
+import type { EventWrite } from './events.js';
+import type { ScenarioEngine } from './scenario.js';
+import type { WebSocketUpgrade } from './serve-http.js';
+/** A socket the vendor serves: its path (and host, when the vendor serves it on a host of its own), as the manifest
+ *  declares it. */
+/** A vendor's socket: its id, path and host; `protocols` are the subprotocols its server selects from those a client
+ *  offers in `Sec-WebSocket-Protocol` (OpenAI Realtime's `realtime`), the first offered that it lists. */
+export type SocketDecl = {
+    id: string;
+    path: string;
+    host?: string;
+    note: string;
+    source?: string;
+    protocols?: ReadonlyArray<string>;
+};
+/** One open connection, as its engine sees it: its own state, and the frames it sends (an object is sent as JSON). */
+export type SocketSession = {
+    readonly id: number;
+    readonly socket: string;
+    state: Record<string, unknown>;
+    send(frame: unknown): void;
+    close(code?: number, reason?: string): void;
+    /** A reply this session will send, by its correlation key: settles when the engine calls `fulfil(key, value)`, and
+     *  rejects when `ms` pass or the session closes (a request answered by a session: the tunnel's relay). */
+    expect(key: string, ms: number): Promise<unknown>;
+    /** Settles what `expect(key)` awaits; false when nothing awaits it (a late or unknown reply). */
+    fulfil(key: string, value: unknown): boolean;
+    /** The World's scenario's decision for a turn this session asks (a model vendor's turn spoken over a socket: a voice
+     *  agent's reply), the turn given as the pack's scenario adapter reads a request; undefined when the pack has no
+     *  scenario or the World carries none. A fault decision is the engine's to answer in its own frames. */
+    decide(asked: unknown): Promise<ScenarioServed | undefined>;
+};
+/** What the World's scenario serves a turn: a handler's decision, a miss, or a fault (scenario.ts `serve`). */
+export type ScenarioServed = Awaited<ReturnType<ScenarioEngine<unknown>['serve']>>;
+/** A socket's protocol, over the handler contract's context (a read of the World as the request that opened it). */
+export type SocketEngine<C> = {
+    open?(session: SocketSession, ctx: C): void | Promise<void>;
+    message(session: SocketSession, data: string, ctx: C): void | Promise<void>;
+    /** A write of the World: the frames it sends this session, if any (the engine decides who is told what). */
+    write?(session: SocketSession, write: EventWrite, ctx: C): void | Promise<void>;
+    /** The session ended (the client hung up, or the engine closed it): the World is read and written as at a frame, so
+     *  what the end settles is written (a call's final status). */
+    close?(session: SocketSession, ctx: C): void | Promise<void>;
+};
+/** The open sessions of one socket of the vendor in a World (a handler reaches them as `ctx.sockets(id)`). */
+export declare function openSessions(service: string, root: string | undefined, socket: string): SocketSession[];
+/** Offer a write to every open session of the vendor, each in its turn after what it is already doing. Queued, never
+ *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
+export declare function socketWrite(service: string, root: string | undefined, write: EventWrite): void;
+/** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
+export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<C>>, context: (request: Request, decl: SocketDecl) => Promise<C>, hostOf: (request: Request) => string, pathOf?: (request: Request) => string, decide?: (asked: unknown) => Promise<ScenarioServed | undefined>): WebSocketUpgrade;

package/dist/src/sockets.js

@@ -0,0 +1,90 @@
+const sessions = new Map();
+let nextSession = 1;
+const keyOf = (service, root) => `${service}\0${root ?? ''}`;
+/** The open sessions of one socket of the vendor in a World (a handler reaches them as `ctx.sockets(id)`). */
+export function openSessions(service, root, socket) {
+    return [...(sessions.get(keyOf(service, root)) ?? [])].filter((o) => o.session.socket === socket).map((o) => o.session);
+}
+/** Offer a write to every open session of the vendor, each in its turn after what it is already doing. Queued, never
+ *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
+export function socketWrite(service, root, write) {
+    const open = sessions.get(keyOf(service, root));
+    if (!open?.size)
+        return;
+    for (const o of open) {
+        const { engine } = o;
+        if (!engine.write)
+            continue;
+        o.queue = o.queue.then(async () => engine.write(o.session, write, await o.context())).catch((error) => o.session.close(1011, String(error.message ?? error).slice(0, 120)));
+    }
+}
+/** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
+export function socketUpgrade(service, root, decls, engines, context, hostOf, pathOf = (request) => new URL(request.url).pathname, decide = async () => undefined) {
+    const declFor = (request) => decls.find((d) => {
+        const path = pathOf(request).replace(/\/+$/, '') || '/';
+        return (d.path.replace(/\/+$/, '') || '/') === path && (!d.host || d.host.toLowerCase() === hostOf(request)) && engines[d.id] !== undefined;
+    });
+    const byPeer = new WeakMap();
+    const key = keyOf(service, root);
+    return {
+        accepts: (request) => declFor(request) !== undefined,
+        // the subprotocol the server answers with: the first the client offers that the socket declares, or, for a socket
+        // that declares none, the first offered (what the ws library and Bun answer by themselves)
+        protocol: (request) => {
+            const offered = (request.headers.get('sec-websocket-protocol') ?? '').split(',').map((p) => p.trim()).filter(Boolean);
+            const declared = declFor(request)?.protocols;
+            return declared ? offered.find((p) => declared.includes(p)) : offered[0];
+        },
+        open: (peer, request) => {
+            const decl = declFor(request);
+            const engine = engines[decl.id];
+            const pending = new Map();
+            const session = {
+                id: nextSession++, socket: decl.id, state: {},
+                send: (frame) => { peer.send(typeof frame === 'string' || frame instanceof Uint8Array ? frame : JSON.stringify(frame)); },
+                close: (code, reason) => { peer.close(code, reason); },
+                expect: (key, ms) => new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { pending.delete(key); reject(new Error('no reply in time')); }, ms);
+                    pending.set(key, { resolve, reject, timer });
+                }),
+                fulfil: (key, value) => {
+                    const p = pending.get(key);
+                    if (!p)
+                        return false;
+                    clearTimeout(p.timer);
+                    pending.delete(key);
+                    p.resolve(value);
+                    return true;
+                },
+                decide,
+            };
+            const o = { session, engine, context: () => context(request.clone(), decl), queue: Promise.resolve(), pending };
+            byPeer.set(peer, o);
+            (sessions.get(key) ?? sessions.set(key, new Set()).get(key)).add(o);
+            if (engine.open)
+                o.queue = o.queue.then(async () => engine.open(session, await o.context())).catch((error) => session.close(1011, String(error.message ?? error).slice(0, 120)));
+        },
+        message: (peer, data) => {
+            const o = byPeer.get(peer);
+            if (!o)
+                return;
+            const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+            o.queue = o.queue.then(async () => o.engine.message(o.session, text, await o.context())).catch((error) => o.session.close(1011, String(error.message ?? error).slice(0, 120)));
+        },
+        close: (peer) => {
+            const o = byPeer.get(peer);
+            if (!o)
+                return;
+            sessions.get(key)?.delete(o);
+            // what awaited this session's replies is told it closed
+            for (const [k, p] of o.pending) {
+                clearTimeout(p.timer);
+                p.reject(new Error('the session closed'));
+                o.pending.delete(k);
+            }
+            // the end is written after what the session is still doing, over its own context
+            if (o.engine.close)
+                o.queue = o.queue.then(async () => o.engine.close(o.session, await o.context())).catch(() => { });
+        },
+    };
+}

package/dist/src/state-system.d.ts

@@ -32,6 +32,7 @@ export type StateSystemAdapters = {
         root?: string;
         origin?: string;
         credential?: string;
+        scope?: string;
     }) => Promise<unknown>;
     ingest?: (request: Request, ctx: {
         root?: string;

package/dist/src/state-system.js

@@ -9,7 +9,7 @@
 //               from the vendor (the pack's refresh adapter). Reads never egress.
 // The binding is a file in the twin's state dir (`root.json`), written by `volter twin <vendor>
 // root`, read here — no env var, no pack code. The adapters come from the pack's descriptor
-// (protocol 2 `stateSystem`) or its anchored exports, registered by whoever mounts the twin.
+// (`stateSystem`), registered by whoever mounts the twin.
 // CHECKS run before any entry is performed: a check that fails lands the entry as `refused` with
 // its reason and the deploy stops there. Checks are the world's files; the runtime loads them.
 import { dirname, join } from 'node:path';

package/dist/src/storage.d.ts

@@ -61,7 +61,7 @@ export declare function twinLog(kind: string, details: Record<string, unknown>):
  *  critical sections atomic. Public so world-runtime can guard concurrent `upWorld`
  *  claims of one instance dir with the SAME lock semantics the event log uses (TWIN-36). */
 export declare function withFileLock<T>(lockPath: string, fn: () => T): T;
-/** The parent log as a protocol 1 pack reads it: every entry the branch inherited or landed, as
+/** The parent log as observed rows: every entry the branch inherited or landed, as
  *  observed rows (log.ts `toEvent`). A branched world sees its base world's logs to the branch
  *  position first. */
 export declare function listEvents(service: string, root?: string): WorldServiceEvent[];

package/dist/src/storage.js

@@ -1,5 +1,5 @@
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { assertNotBeingRemoved, withAncestryLock, withStateRemoval } from "./ancestry.js";
+import { withStateLock, withStateRemoval } from "./ancestry.js";
 import { appendParentEntry, toEntry } from "./log.js";
 import { GenericWorldStateSchema, WorldServiceEventSchema, } from "./schemas.js";
 import { getActiveWorldStore } from "./world-store.js";
@@ -181,12 +181,12 @@ function appendJsonl(path, value) {
  *  critical sections atomic. Public so world-runtime can guard concurrent `upWorld`
  *  claims of one instance dir with the SAME lock semantics the event log uses (TWIN-36). */
 export function withFileLock(lockPath, fn) {
-    return withAncestryLock(() => { assertNotBeingRemoved(dirname(lockPath)); return getActiveWorldStore().withLock(lockPath, fn); });
+    return withStateLock(lockPath, fn);
 }
 function writeJsonAtomic(path, value) {
     getActiveWorldStore().writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
 }
-/** The parent log as a protocol 1 pack reads it: every entry the branch inherited or landed, as
+/** The parent log as observed rows: every entry the branch inherited or landed, as
  *  observed rows (log.ts `toEvent`). A branched world sees its base world's logs to the branch
  *  position first. */
 export function listEvents(service, root) {

package/dist/src/trace-context.js

@@ -8,7 +8,7 @@
 // same trace-id, a new parent-id — so the app's handler continues the same trace.
 //
 // Nothing here is vendor knowledge, and nothing runs at import: the async-context store is made on
-// first use (a browser bundle of a mirror client carries the kernel and has no AsyncLocalStorage).
+// first use (a browser bundle carrying the kernel and has no AsyncLocalStorage).
 import { AsyncLocalStorage } from 'node:async_hooks';
 export const TRACEPARENT_HEADER = 'traceparent';
 // version-traceid-parentid-flags, lowercase hex only (the spec's HEXDIGLC). Version ff is invalid;

package/dist/src/twin-fetch.d.ts

@@ -62,13 +62,6 @@ export interface TwinFetchAdapterConfig {
     manifest: unknown | (() => unknown);
     /** GET /twin/scenario body (thunk) — scenario-carrying packs only. */
     scenarioStatus?: () => unknown;
-    /** THE STORE DOOR (R5c, mirror purity R3): named, deterministic projections over stored
-     *  state, served at `GET /twin/store/<name>` and listed in the manifest as `stores`. A
-     *  mirror reads twin state ONLY through this door — never by importing the handler or a
-     *  `-twin-internal` module — so the vendor API lacking a listing endpoint (resend has no
-     *  list-emails) no longer breeds a bespoke `/_twin/*` route per mirror. Keyed in the skin
-     *  like every state read (only bare `GET /twin` is keyless). */
-    stores?: Record<string, () => unknown | Promise<unknown>>;
     /** Per-request vendor extras (header threading: stripe-version, notion-version, …). */
     extras?: (request: Request, url: URL) => Record<string, unknown>;
     /** Static per-instance handler options (e.g. rateLimitPerSecond). */

package/dist/src/twin-fetch.js

@@ -91,25 +91,11 @@ export function createTwinFetchFromHandler(handler, config) {
         const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
         if (request.method === 'GET' && cleanPath === '/twin') {
             const manifest = typeof config.manifest === 'function' ? config.manifest() : config.manifest;
-            const storeNames = Object.keys(config.stores ?? {}).sort();
-            if (storeNames.length > 0 && manifest !== null && typeof manifest === 'object') {
-                const m = manifest;
-                const doors = m.doors !== null && typeof m.doors === 'object' ? m.doors : {};
-                // The manifest EDUCATES: it lists the store names and names the door's path.
-                return Response.json({ ...m, stores: storeNames, doors: { ...doors, store: 'GET /twin/store/<name>' } });
-            }
             return Response.json(manifest);
         }
         if (request.method === 'GET' && cleanPath === '/twin/scenario' && config.scenarioStatus !== undefined) {
             return Response.json(config.scenarioStatus());
         }
-        if (request.method === 'GET' && cleanPath.startsWith('/twin/store/')) {
-            const name = cleanPath.slice('/twin/store/'.length);
-            const store = config.stores?.[name];
-            if (store === undefined)
-                return Response.json({ error: 'unknown store', store: name, stores: Object.keys(config.stores ?? {}).sort() }, { status: 404 });
-            return Response.json(await store()); // a projection may read through the handler (async) — the door awaits it
-        }
         const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
         const headers = {};
         request.headers.forEach((value, key) => { headers[key] = value; });

package/dist/src/vendor-call.d.ts

@@ -0,0 +1,6 @@
+/** A call to a vendor the World runs no twin of. */
+export declare class VendorUnreachableError extends Error {
+    constructor(message: string);
+}
+/** `url`, a vendor's own address, answered by the World's twin of that vendor. */
+export declare function vendorFetch(url: string | URL, init?: RequestInit): Promise<Response>;

package/dist/src/vendor-call.js

@@ -0,0 +1,41 @@
+// A TWIN'S CALL TO ANOTHER VENDOR (architecture.md, "What an author writes, and how": `ctx.vendorFetch`). A vendor's
+// service calls another vendor as part of its own behaviour — Clerk trades a Google sign-in's code for the person at
+// Google's token endpoint — and in a World that other vendor is the World's twin of it. The call is addressed as the
+// vendor's own URL and reaches that twin by the same host rules the injector routes an application by (vendor-hosts.cjs),
+// carrying the World's twins key; a vendor the World runs no twin of is refused, never reached: a twin makes no direct
+// vendor call (simulated execution is deterministic and stays inside the World). This is the one network a handler has;
+// importing this module does nothing.
+import { twinOrigins, VENDOR_HOSTS } from '../vendor-hosts.cjs';
+/** A call to a vendor the World runs no twin of. */
+export class VendorUnreachableError extends Error {
+    constructor(message) { super(message); this.name = 'VendorUnreachableError'; }
+}
+/** The World's twins by vendor: the instance's env (every twin's URL, whenever this process started) over this
+ *  process's own. */
+async function worldTwins() {
+    const env = process.env;
+    let instanceEnv = {};
+    const file = env.VOLTER_WORLD_INSTANCE;
+    if (file) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            instanceEnv = JSON.parse(await readFile(file, 'utf8')).env ?? {};
+        }
+        catch { /* no instance yet: this process's env alone */ }
+    }
+    return { ...twinOrigins(env), ...twinOrigins(instanceEnv) };
+}
+/** `url`, a vendor's own address, answered by the World's twin of that vendor. */
+export async function vendorFetch(url, init = {}) {
+    const target = new URL(String(url));
+    const twins = await worldTwins();
+    const vendor = Object.keys(VENDOR_HOSTS).find((v) => twins[v] !== undefined && VENDOR_HOSTS[v](target.hostname, target.pathname));
+    if (vendor === undefined)
+        throw new VendorUnreachableError(`${target.host}${target.pathname}: this World runs no twin of it, and a twin calls only the World's twins`);
+    const headers = new Headers(init.headers);
+    headers.set('x-volter-twin-original-host', target.host);
+    const key = process.env.VOLTER_TWINS_KEY;
+    if (key && !headers.has('x-twins-key'))
+        headers.set('x-twins-key', key);
+    return fetch(`${twins[vendor].replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers });
+}

package/dist/src/world-store.js

@@ -10,7 +10,7 @@
 // without touching a line of twin business logic.
 //
 // The interface is SYNCHRONOUS on purpose. The kernel's internals (append-then-
-// project, read-then-append critical sections) are synchronous, and `clerk-twin.ts`'s
+// project, read-then-append critical sections) are synchronous, and a pack's
 // request handler is a pure sync function keyed by `root`. Making the store async
 // would ripple `await` through every one of those call sites and change the handler's
 // shape — precisely the blast radius this seam exists to avoid. An async backend is