@volter/world-core 3.0.38 → 3.0.39

package/dist/src/scenario.js

@@ -1,23 +1,4 @@
-// THE scenario engine — System 2 of the twin programming model (one grammar, per-pack
-// vocabulary). See company-repo BRIEFS/TWIN-PROGRAMMING-MODEL.md (LOCKED, 2026-08-27).
-//
-// A HANDLER is an MSW-shaped data rule: { on, respond, once?, scope?, phase?, advancePhase? }.
-// Handlers are evaluated IN ORDER; the FIRST handler whose `on` conditions ALL hold fires.
-// No match → the caller serves its labeled deterministic stub and records the MISS (with the
-// request's extracted features — the authoring signal). The handler FILE in the world dir is
-// the only write surface; `engine.use(...)` exists for in-process tests only (LIFO over the
-// baseline, removable). There are NO runtime write doors — a running world is never mutated.
-//
-// The GRAMMAR (structure, ordering, once/scope/phase, strict validation, extractors,
-// placeholders, miss records) is this module's and identical for every vendor. The
-// VOCABULARY (which `on` keys exist and how each matches; what `respond` may contain; which
-// routes are stateful and therefore refuse success-shaped handlers) is the pack's, declared
-// through a PackScenarioAdapter. Determinism: the engine is a pure state machine — same
-// handler list + same request sequence → same decisions, byte for byte.
-//
-// STRICT EVERYWHERE (the gemini discipline): unknown top-level keys, unknown `on` keys,
-// unknown placeholder names, malformed extractors — all THROW with the valid vocabulary in
-// the message. A typo must fail loudly at load, never silently mis-match at serve.
+import { exactInteger, compareExactNumbers, isExactIntegerValue } from "./exact-json.js";
 export class ScenarioError extends Error {
 }
 // `$comment` is allowed (and ignored) at document and handler level — JSON has no comments
@@ -112,22 +93,38 @@ function parseHandler(raw, index, adapter, extractors) {
     if (h.fault !== undefined) {
         const f = h.fault;
         if (typeof f !== "object" || f === null || Array.isArray(f))
-            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault is an object { kind: "slow" | "status" | "drop", ... }`);
-        const kinds = ["slow", "status", "drop"];
+            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault is an object { kind: "slow" | "status" | "drop" | "generation", ... }`);
+        const kinds = ["slow", "status", "drop", "generation"];
         if (!kinds.includes(f.kind))
             throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.kind is one of ${kinds.join(", ")}, got ${JSON.stringify(f.kind)}`);
-        const keysFor = { slow: ["kind", "ms"], status: ["kind", "status", "retryAfterSeconds", "message"], drop: ["kind", "holdMs"] };
+        const keysFor = { slow: ["kind", "ms"], status: ["kind", "status", "retryAfterSeconds", "message", "metadata", "errorType"], generation: ["kind", "status", "message", "errorType", "metadata", "partialText", "event"], drop: ["kind", "holdMs"] };
         for (const key of Object.keys(f))
             if (!keysFor[f.kind].includes(key))
                 throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.${key} is not a key of a ${String(f.kind)} fault (valid: ${keysFor[f.kind].join(", ")})`);
         if (f.kind === "slow" && !(Number.isInteger(f.ms) && f.ms >= 0 && f.ms <= 600_000))
             throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.ms is an integer 0..600000 (milliseconds)`);
-        if (f.kind === "status" && !(Number.isInteger(f.status) && f.status >= 400 && f.status <= 599))
+        if ((f.kind === "status" || f.kind === "generation") && !(Number.isInteger(f.status) && f.status >= 400 && f.status <= 599))
             throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.status is an integer 400..599 — a fault is a refusal or a failure, never a success`);
         if (f.kind === "status" && f.retryAfterSeconds !== undefined && !(Number.isInteger(f.retryAfterSeconds) && f.retryAfterSeconds >= 0))
             throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.retryAfterSeconds is a non-negative integer`);
         if (f.kind === "status" && f.message !== undefined && typeof f.message !== "string")
             throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.message is a string`);
+        if ((f.kind === "status" || f.kind === "generation") && f.metadata !== undefined && (typeof f.metadata !== "object" || f.metadata === null || Array.isArray(f.metadata)))
+            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.metadata is an object`);
+        if (f.kind === "status" && f.errorType !== undefined && typeof f.errorType !== "string")
+            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.errorType is a string`);
+        if (f.kind === "generation") {
+            if (typeof f.message !== "string" || typeof f.errorType !== "string" || !f.errorType)
+                throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation fault requires message and nonempty errorType`);
+            for (const key of ["partialText", "event"])
+                if (f[key] !== undefined && typeof f[key] !== "string")
+                    throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.${key} is a string`);
+            if (!adapter.validateGenerationFault)
+                throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation faults require a compute-only adapter`);
+            const refusal = adapter.validateGenerationFault(f, h);
+            if (refusal)
+                throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
+        }
         if (f.kind === "drop" && f.holdMs !== undefined && !(Number.isInteger(f.holdMs) && f.holdMs >= 0))
             throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.holdMs is a non-negative integer`);
         if (f.kind !== "slow" && "respond" in h)
@@ -185,10 +182,11 @@ function applyTransform(value, transform, vendor, where) {
     if (!transform)
         return value;
     const [op, rawN] = transform.slice(1).split(":");
-    if (typeof value !== "number")
+    if (typeof value !== "number" && !(typeof value === "string" && isExactIntegerValue(value)))
         throw new ScenarioError(`${vendor} scenario: ${where} applies |${op}:${rawN} to a non-numeric extractor value ${JSON.stringify(value)}`);
-    const n = Number(rawN);
-    return op === "min" ? Math.min(value, n) : Math.max(value, n);
+    const n = /^-?\d+$/.test(rawN) ? exactInteger(rawN) : Number(rawN);
+    const cmp = compareExactNumbers(value, n);
+    return op === "min" ? (cmp <= 0 ? value : n) : (cmp >= 0 ? value : n);
 }
 const MISS_KEEP = 20;
 /** The engine: pure state machine over registered handlers. One instance per twin server. */
@@ -322,7 +320,7 @@ export class ScenarioEngine {
                 throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": pattern did not match the request (the handler demanded a value the request never stated)`);
             const captured = m[1] ?? m[0];
             if (tp.as === "number") {
-                const n = Number(captured);
+                const n = /^-?\d+$/.test(captured) ? exactInteger(captured) : Number(captured);
                 if (Number.isNaN(n))
                     throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": captured "${captured}" is not a number`);
                 value = n;
@@ -375,6 +373,8 @@ function waitForScenarioFault(ms, signal) {
 }
 export async function scenarioFaultResult(fault, render, signal) {
     throwIfScenarioAborted(signal);
+    if (fault.kind === "generation")
+        return null; // compute handler renders the admitted generation failure
     if (fault.kind === "slow") {
         await waitForScenarioFault(fault.ms, signal);
         throwIfScenarioAborted(signal);
@@ -393,18 +393,22 @@ export async function scenarioFaultResult(fault, render, signal) {
     return { status: fault.status, headers, body: rendered?.body ?? { error: { message: fault.message ?? `twin fault: ${fault.status}`, type: "twin_fault" } } };
 }
 export function statefulTwinManifest(input) {
+    // the World's doors the pack declares (what the vendor's own pages do that its API does not: issuing an account's key)
+    const doors = input.doors ?? [];
     return {
         twin: true,
         vendor: input.vendor,
         twinOf: input.twinOf,
         program: {
-            state: `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here — there is no fixture language and no write door besides the vendor's.`,
+            state: doors.length
+                ? `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here; what the vendor does on its own pages (not its API) is a door of the World, listed under doors. There is no fixture language.`
+                : `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here — there is no fixture language and no write door besides the vendor's.`,
             identity: input.identity ?? 'Authenticate as the vendor does; the twin accepts any non-sentinel credential.',
             time: 'Writes are stamped from the WORLD CLOCK (volter-world clock <world> set/advance) — deterministic history is clock-set, seed, clock-advance.',
-            behavior: 'This twin is state, not scripting — answers are functions of what you seeded. Judgment/fault scripting lives on the scripted vendor twins (their GET /twin explains).',
+            behavior: input.behavior ?? 'This twin is state, not scripting — answers are functions of what you seeded. Judgment/fault scripting lives on the scripted vendor twins (their GET /twin explains).',
             ...(input.notes ? { notes: input.notes } : {}),
         },
-        doors: { manifest: 'GET /twin' },
+        doors: { manifest: 'GET /twin', ...Object.fromEntries(doors.map((d) => [`${d.method} ${d.path}`, d.note ?? 'a door of the World'])) },
     };
 }
 /** The GET /twin manifest — the discovery door's body. Education ships INSIDE the twin:

package/dist/src/serve-http.d.ts

@@ -1,4 +1,5 @@
 import type { TwinStream } from './twin-fetch.js';
+export declare function connectWebSocket(url: string, headers: Record<string, string>, protocols?: string[]): Promise<WebSocket>;
 export type HttpHandler = (request: Request) => Response | Promise<Response>;
 export type WebSocketPeer = {
     send: (data: string | Uint8Array) => unknown;
@@ -28,7 +29,7 @@ export type ServeHttpOptions = {
     fetch: HttpHandler;
     /** seconds a connection may idle (Bun honors it; Node's keep-alive timeout is set from it) */
     idleTimeout?: number;
-    /** the largest request body accepted, in bytes (Bun's default is 128 MB; Node sets none) */
+    /** Explicit transport limit in bytes; absent, Bun retains its 128 MiB default. */
     maxRequestBodySize?: number;
     /** what a thrown handler answers with; absent, a 500 carrying the error (as Bun.serve) */
     error?: (error: Error) => Response | Promise<Response>;

package/dist/src/serve-http.js

@@ -7,6 +7,12 @@
 // Nothing here runs at module scope, and `node:http` is reached through `process.getBuiltinModule`
 // rather than a static import: this module rides into browser client bundles through the kernel's
 // entrypoint, where a static `node:` import is the 2026-09-06 class of break.
+/** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
+const socketLibrary = () => import('ws');
+export async function connectWebSocket(url, headers, protocols = []) {
+    const { WebSocket: Client } = await socketLibrary();
+    return new Client(url, protocols, { headers });
+}
 /** A decorator the request journal installs: every server made through the seam serves through it. */
 let decorate;
 export function setServeDecorator(fn) { decorate = fn; }
@@ -18,6 +24,9 @@ export async function serveHttp(options) {
     // twin from a leftover World's that holds the same port. Outside a World nothing changes.
     // a pack's fetch carries the upgrade its sockets take (pack-fetch.ts), read before anything wraps the fetch: served on
     // its own or in a World, its sockets answer
+    const declaredCap = options.fetch.maxRequestBodySize;
+    if (options.maxRequestBodySize === undefined && declaredCap !== undefined)
+        options = { ...options, maxRequestBodySize: declaredCap };
     const carried = options.upgrade ?? options.fetch.upgrade;
     if (carried)
         options = { ...options, upgrade: carried };
@@ -327,7 +336,7 @@ async function serveOnNode(options) {
     });
     let socketServer;
     if (options.upgrade) {
-        const { WebSocketServer } = await import('ws');
+        const { WebSocketServer } = await socketLibrary();
         const upgrade = options.upgrade;
         const requestOf = (req) => new Request(`${protocol}://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { headers: Object.fromEntries(Object.entries(req.headers).filter((entry) => typeof entry[1] === 'string')) });
         // the subprotocol the socket selects, answered as Bun's branch answers it

package/dist/src/serve.js

@@ -1,3 +1,4 @@
+import { parseExactJson } from "./exact-json.js";
 // Twin serve layer (the twins architecture notes, increment 1): answer vendor-shaped
 // READS from the local event-sourced state — the "local twin" read path. An app
 // or agent points at this instead of the real vendor; it responds from local
@@ -56,7 +57,7 @@ export function readTwinRequestJournal(service, root, options = {}) {
             if (!line)
                 continue;
             try {
-                rows.push(JSON.parse(line));
+                rows.push(parseExactJson(line));
             }
             catch { /* a torn line */ }
         }
@@ -107,7 +108,7 @@ export function readTwinRequestJournalFrom(service, root, cursor, options = {})
             if (!line)
                 continue;
             try {
-                entries.push(JSON.parse(line));
+                entries.push(parseExactJson(line));
             }
             catch { /* a torn line */ }
         }
@@ -363,8 +364,10 @@ function journalingFetch(config, callSiteVendor) {
                 const response = (await identitySlot().run(slot, () => inner.call(this, request, server)));
                 if (response instanceof Response)
                     status = response.status;
-                else if (response === undefined)
-                    return response; // upgraded (websocket) — nothing served
+                else if (response === undefined) {
+                    status = 101;
+                    return response;
+                } // accepted WebSocket upgrade
                 return response;
             }
             finally {

package/dist/src/signing.d.ts

@@ -7,14 +7,22 @@ export type Jwk = {
     kid: string;
     n: string;
     e: string;
+} | {
+    kty: 'OKP';
+    use: 'sig';
+    alg: 'EdDSA';
+    crv: 'Ed25519';
+    kid: string;
+    x: string;
 };
 export type Jwks = {
     keys: Jwk[];
 };
-/** A signing key: an RSA private key as a PEM (its public half, given or derived, is what a JWKS serves and names by
- *  `kid`), or a shared secret. Only deterministic algorithms: an ECDSA signature is random, so a World signs none. */
+/** A signing key: an RSA or Ed25519 private key as a PEM (its public half, given or derived, is what a JWKS serves and
+ *  names by `kid`), or a shared secret. Only deterministic algorithms: an ECDSA signature is random, so a World signs
+ *  none; Ed25519's is deterministic (RFC 8032), Better Auth's default (`EdDSA`). */
 export type SigningKey = {
-    alg: 'RS256' | 'RS384' | 'RS512';
+    alg: 'RS256' | 'RS384' | 'RS512' | 'EdDSA';
     privatePem: string;
     publicPem?: string;
 } | {
@@ -32,18 +40,19 @@ export type JwtVerdict = {
 /** A public key's id: a prefix and the first 16 hex of SHA-256 over its DER (what its JWKS and every token name). */
 export declare function keyId(publicPem: string, prefix?: string): string;
 /** A JWT: `iat` and `nbf` are `now` (seconds, the World's), `exp` `now` plus the lifetime (60 s when none is given),
- *  unless the claims name their own. RS256 tokens carry the key's `kid`. */
+ *  unless the claims name their own. A token of a key pair carries the key's `kid`. */
 export declare function jwtSign(claims: Row, key: SigningKey, opts: {
     now: number;
     expiresInSeconds?: number;
     kidPrefix?: string;
+    typ?: string;
 }): string;
 /** A JWT's header and payload, unverified. */
 export declare function jwtDecode(token: string): {
     header: Row;
     payload: Row;
 };
-/** A token checked: an RS256 one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
+/** A token checked: an RS256 or EdDSA one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
  *  then its `exp`/`nbf` at `now` (seconds). */
 export declare function jwtVerify(token: string, key: Jwks | {
     alg: 'HS256' | 'HS384' | 'HS512';
@@ -79,6 +88,9 @@ export declare const md5: (value: string | Uint8Array) => string;
 export declare function uuidFrom(seed: string): string;
 /** `count` lowercase letters derived from `seed` (a 20-letter project ref, a slug's suffix), the same every run. */
 export declare function lettersFrom(seed: string, count?: number): string;
+/** `count` base62 characters (0-9A-Za-z) derived from `seed`, the same every run: the opaque tail of an id a vendor
+ *  writes in base62 (OpenAI's `call_unLAR8MvFNptuiZK6K6HCy5k`, 24 after its prefix). */
+export declare function base62From(seed: string, count?: number): string;
 /** Two strings compared in constant time. */
 export declare function equalSecrets(a: string, b: string): boolean;
 /** Bytes signed with a private key (RSA with SHA-256, or Ed25519), in the encoding asked: a certificate's signature,
@@ -123,6 +135,7 @@ export declare const handlerCrypto: {
     readonly digest: typeof digest;
     readonly uuidFrom: typeof uuidFrom;
     readonly lettersFrom: typeof lettersFrom;
+    readonly base62From: typeof base62From;
     readonly equalSecrets: typeof equalSecrets;
     readonly sealedBoxKeyPair: typeof sealedBoxKeyPair;
     readonly sealedBoxOpen: typeof sealedBoxOpen;
@@ -132,4 +145,9 @@ export declare const handlerCrypto: {
     readonly certificateOf: typeof certificateOf;
 };
 export type HandlerCrypto = typeof handlerCrypto;
+/** A [KSUID](https://github.com/segmentio/ksuid) as 27 base62 characters (0-9A-Za-z, most significant first): `seconds`
+ *  past KSUID's epoch (1400000000) in four bytes, then `n` in four, then twelve bytes derived from `seed`, so KSUIDs
+ *  made in one second sort by `n`, at `width` characters (27 unless a vendor's id is longer or shorter). Deterministic:
+ *  the same arguments give the same id. */
+export declare function ksuidFrom(seconds: number, n: number, seed: string, width?: number): string;
 export {};

package/dist/src/signing.js

@@ -1,6 +1,7 @@
+import { parseExactJson, compareExactNumbers } from "./exact-json.js";
 // SIGNING ON THE CONTEXT (docs/contributing/architecture.md, "What an author writes, and how": the tokens-and-keys row)
 // — one deterministic implementation of what vendors sign with, given to handlers as `ctx.crypto`, so no pack reaches
-// `node:crypto` itself: JWTs (RS256 with a pack's instance key, HS256 with a shared secret), their verification, a
+// `node:crypto` itself: JWTs (RS256 or EdDSA with a pack's instance key, HS256 with a shared secret), their verification, a
 // JWKS for a public key, an HMAC and a SHA-256. Nothing here is random: a key is the pack's data (a PEM it declares),
 // and every value a signature carries comes from the call.
 // A namespace, never named imports: a browser client bundles the kernel, and the browser's `node:crypto` polyfill has no
@@ -8,7 +9,7 @@
 import * as nodeCrypto from 'node:crypto';
 import { sealedBoxKeyPair, sealedBoxOpen } from "./sealed-box.js";
 /** The algorithms `jwtSign` signs with. */
-export const SIGNING_ALGORITHMS = ['RS256', 'RS384', 'RS512', 'HS256', 'HS384', 'HS512'];
+export const SIGNING_ALGORITHMS = ['RS256', 'RS384', 'RS512', 'EdDSA', 'HS256', 'HS384', 'HS512'];
 const digestOf = (alg) => `sha${alg.slice(2)}`;
 const base64url = (input) => Buffer.from(input).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
 const fromBase64url = (s) => Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
@@ -19,15 +20,24 @@ export function keyId(publicPem, prefix = 'ins_') {
     return `${prefix}${nodeCrypto.createHash('sha256').update(der).digest('hex').slice(0, 16)}`;
 }
 /** A JWT: `iat` and `nbf` are `now` (seconds, the World's), `exp` `now` plus the lifetime (60 s when none is given),
- *  unless the claims name their own. RS256 tokens carry the key's `kid`. */
+ *  unless the claims name their own. A token of a key pair carries the key's `kid`. */
 export function jwtSign(claims, key, opts) {
+    // a key of another kind than its algorithm's is refused by name (an RSA key under EdDSA would fail inside the signer)
+    if ('privatePem' in key) {
+        const kind = nodeCrypto.createPrivateKey(key.privatePem).asymmetricKeyType;
+        const wants = key.alg === 'EdDSA' ? 'ed25519' : 'rsa';
+        if (kind !== wants)
+            throw new Error(`jwtSign: ${key.alg} signs with an ${wants === 'rsa' ? 'RSA' : 'Ed25519'} key, and this key is ${kind ?? 'of no known type'}`);
+    }
     const header = 'privatePem' in key
-        ? { alg: key.alg, typ: 'JWT', kid: keyId(key.publicPem ?? nodeCrypto.createPublicKey(key.privatePem).export({ type: 'spki', format: 'pem' }).toString(), opts.kidPrefix) }
-        : { alg: key.alg, typ: 'JWT' };
+        ? { alg: key.alg, typ: opts.typ ?? 'JWT', kid: keyId(key.publicPem ?? nodeCrypto.createPublicKey(key.privatePem).export({ type: 'spki', format: 'pem' }).toString(), opts.kidPrefix) }
+        : { alg: key.alg, typ: opts.typ ?? 'JWT' };
     const payload = { iat: opts.now, exp: opts.now + (opts.expiresInSeconds ?? 60), nbf: opts.now, ...claims };
     const input = `${jsonPart(header)}.${jsonPart(payload)}`;
     if ('secret' in key)
         return `${input}.${base64url(nodeCrypto.createHmac(digestOf(key.alg), key.secret).update(input).digest())}`;
+    if (key.alg === 'EdDSA')
+        return `${input}.${base64url(nodeCrypto.sign(null, Buffer.from(input), key.privatePem))}`;
     const signer = nodeCrypto.createSign(`RSA-SHA${key.alg.slice(2)}`);
     signer.update(input);
     signer.end();
@@ -38,17 +48,17 @@ export function jwtDecode(token) {
     const parts = token.split('.');
     if (parts.length !== 3)
         throw new Error('malformed jwt');
-    const part = (s) => JSON.parse(fromBase64url(s).toString('utf8'));
+    const part = (s) => parseExactJson(fromBase64url(s).toString('utf8'));
     return { header: part(parts[0]), payload: part(parts[1]) };
 }
 function timely(payload, now) {
-    if (typeof payload.exp === 'number' && now >= payload.exp)
+    if ((typeof payload.exp === 'number' || typeof payload.exp === 'string' && /^-?\d+$/.test(payload.exp)) && compareExactNumbers(now, payload.exp) >= 0)
         return { valid: false, reason: 'expired' };
-    if (typeof payload.nbf === 'number' && now < payload.nbf)
+    if ((typeof payload.nbf === 'number' || typeof payload.nbf === 'string' && /^-?\d+$/.test(payload.nbf)) && compareExactNumbers(now, payload.nbf) < 0)
         return { valid: false, reason: 'not_yet_valid' };
     return { valid: true, payload };
 }
-/** A token checked: an RS256 one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
+/** A token checked: an RS256 or EdDSA one against a JWKS (its `kid`'s key), an HS256 one against its secret (constant time),
  *  then its `exp`/`nbf` at `now` (seconds). */
 export function jwtVerify(token, key, opts) {
     let decoded;
@@ -68,12 +78,20 @@ export function jwtVerify(token, key, opts) {
             return { valid: false, reason: 'bad_signature' };
         return timely(decoded.payload, opts.now);
     }
-    if (!['RS256', 'RS384', 'RS512'].includes(String(decoded.header.alg)))
+    if (!['RS256', 'RS384', 'RS512', 'EdDSA'].includes(String(decoded.header.alg)))
         return { valid: false, reason: 'unexpected_alg' };
     // a token naming a key the set does not hold matches none; one naming no key is tried against the set's only key
     const jwk = decoded.header.kid !== undefined ? key.keys.find((k) => k.kid === decoded.header.kid) : key.keys.length === 1 ? key.keys[0] : undefined;
     if (!jwk)
         return { valid: false, reason: 'no_matching_key' };
+    if ((jwk.kty === 'OKP') !== (decoded.header.alg === 'EdDSA'))
+        return { valid: false, reason: 'unexpected_alg' };
+    if (jwk.kty === 'OKP') {
+        const edKey = nodeCrypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' });
+        if (!nodeCrypto.verify(null, Buffer.from(`${h}.${p}`), edKey, fromBase64url(s)))
+            return { valid: false, reason: 'bad_signature' };
+        return timely(decoded.payload, opts.now);
+    }
     const verifier = nodeCrypto.createVerify(`RSA-SHA${String(decoded.header.alg).slice(2)}`);
     verifier.update(`${h}.${p}`);
     verifier.end();
@@ -85,6 +103,8 @@ export function jwtVerify(token, key, opts) {
 /** The JWKS that verifies every token a public key's pair signs. */
 export function jwks(publicPem, kidPrefix) {
     const jwk = nodeCrypto.createPublicKey(publicPem).export({ format: 'jwk' });
+    if (jwk.kty === 'OKP')
+        return { keys: [{ kty: 'OKP', use: 'sig', alg: 'EdDSA', crv: 'Ed25519', kid: keyId(publicPem, kidPrefix), x: String(jwk.x) }] };
     return { keys: [{ kty: 'RSA', use: 'sig', alg: 'RS256', kid: keyId(publicPem, kidPrefix), n: String(jwk.n), e: String(jwk.e) }] };
 }
 /** An HMAC of a value, hex or base64 (a webhook's signature, a signed id): SHA-256 unless the vendor names another
@@ -158,6 +178,23 @@ export function lettersFrom(seed, count = 20) {
     }
     return out;
 }
+/** `count` base62 characters (0-9A-Za-z) derived from `seed`, the same every run: the opaque tail of an id a vendor
+ *  writes in base62 (OpenAI's `call_unLAR8MvFNptuiZK6K6HCy5k`, 24 after its prefix). */
+export function base62From(seed, count = 24) {
+    const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+    let out = '';
+    for (let round = 0; out.length < count; round += 1) {
+        // each byte below 248 (4 x 62) maps evenly onto the alphabet; the rest are skipped
+        for (const byte of sha256(`${seed}:${round}`).match(/../g)) {
+            if (out.length === count)
+                break;
+            const b = Number.parseInt(byte, 16);
+            if (b < 248)
+                out += ALPHABET[b % 62];
+        }
+    }
+    return out;
+}
 /** Two strings compared in constant time. */
 export function equalSecrets(a, b) {
     const left = Buffer.from(a, 'utf8');
@@ -219,4 +256,30 @@ export function certificateOf(cert) {
     }
 }
 /** What a handler signs and hashes with: `ctx.crypto`. */
-export const handlerCrypto = { jwtSign, jwtVerify, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf };
+export const handlerCrypto = { jwtSign, jwtVerify, jwtDecode, jwks, keyId, hmac, sha256, md5, digest, uuidFrom, lettersFrom, base62From, equalSecrets, sealedBoxKeyPair, sealedBoxOpen, signWith, verifyWith, publicKeyOf, certificateOf };
+/** A [KSUID](https://github.com/segmentio/ksuid) as 27 base62 characters (0-9A-Za-z, most significant first): `seconds`
+ *  past KSUID's epoch (1400000000) in four bytes, then `n` in four, then twelve bytes derived from `seed`, so KSUIDs
+ *  made in one second sort by `n`, at `width` characters (27 unless a vendor's id is longer or shorter). Deterministic:
+ *  the same arguments give the same id. */
+export function ksuidFrom(seconds, n, seed, width = 27) {
+    const bytes = new Uint8Array(20);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, Math.max(0, seconds - 1_400_000_000) >>> 0);
+    view.setUint32(4, n >>> 0);
+    const tail = sha256(seed);
+    for (let i = 0; i < 12; i++)
+        bytes[8 + i] = parseInt(tail.slice(i * 2, i * 2 + 2), 16);
+    const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+    let value = 0n;
+    for (const b of bytes)
+        value = (value << 8n) | BigInt(b);
+    let out = '';
+    while (value > 0n) {
+        out = ALPHABET[Number(value % 62n)] + out;
+        value /= 62n;
+    }
+    const full = out.padStart(27, '0');
+    // another width than KSUID's 27 (a vendor's id of 24 or 29 characters): its first `width` characters, which keep the
+    // instant and the mint count (and so the order) from 11 on, or more base62 characters derived from the seed after them
+    return width <= 27 ? full.slice(0, width) : `${full}${base62From(`${seed}:ksuid`, width - 27)}`;
+}

package/dist/src/sigv4.d.ts

@@ -37,7 +37,8 @@ export declare function signSigV4(input: {
 /**
  * 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.
+ * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it. A
+ * signed header other than `host` (a Content-Type the URL binds) is signed with the value the request sends (`headers`).
  */
 export declare function presignSigV4(input: {
     method: string;
@@ -45,4 +46,5 @@ export declare function presignSigV4(input: {
     keyId: string;
     secret: string;
     host?: string;
+    headers?: Record<string, string>;
 }): string;

package/dist/src/sigv4.js

@@ -136,7 +136,8 @@ export function signSigV4(input) {
 /**
  * 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.
+ * signature this key's. What an SDK's getSignedUrl makes, for a walk that wrote the URL as its client printed it. A
+ * signed header other than `host` (a Content-Type the URL binds) is signed with the value the request sends (`headers`).
  */
 export function presignSigV4(input) {
     const url = new URL(input.url);
@@ -156,7 +157,8 @@ export function presignSigV4(input) {
         .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 sent = new Headers(input.headers ?? {});
+    const canonicalHeaders = names.map((n) => `${n}:${(n === 'host' ? (input.host ?? url.host) : sent.get(n) ?? '').trim().replace(/\s+/g, ' ')}\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);

package/dist/src/smtp.js

@@ -40,7 +40,8 @@ export async function sendMail(route, mail, headers = {}) {
         import('node:net'),
         import('../network-policy.cjs'),
     ]);
-    const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`);
+    // sending mail is a write: an external relay needs a `writes` grant
+    const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`, process.env, 'SMTP');
     if (refusal !== null)
         throw new Error(refusal);
     const socket = connect(route.port, route.host);

package/dist/src/sockets.js

@@ -1,5 +1,7 @@
 const sessions = new Map();
-let nextSession = 1;
+/** A World's next session number, per World (its service and root): a session's id is the World's, never the
+ *  process's, so a life replayed on a fresh World numbers its sessions as it did the first time. */
+const nextSession = new Map();
 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) {
@@ -40,7 +42,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
             const engine = engines[decl.id];
             const pending = new Map();
             const session = {
-                id: nextSession++, socket: decl.id, state: {},
+                id: (() => { const n = (nextSession.get(key) ?? 0) + 1; nextSession.set(key, n); return n; })(), 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) => {
@@ -83,8 +85,11 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                 o.pending.delete(k);
             }
             // the end is written after what the session is still doing, over its own context
+            // the session is gone, so a failure has no frame to go in: it is reported, never swallowed
             if (o.engine.close)
-                o.queue = o.queue.then(async () => o.engine.close(o.session, await o.context())).catch(() => { });
+                o.queue = o.queue.then(async () => o.engine.close(o.session, await o.context())).catch((error) => {
+                    console.error(`${service}: the ${o.session.socket} socket's end was not written: ${String(error?.message ?? error)}`);
+                });
         },
     };
 }

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

@@ -38,6 +38,9 @@ export type StateSystemAdapters = {
         root?: string;
         secret?: string;
     }) => Response | Promise<Response>;
+    /** Why a recorded write is the World's own and sent nowhere, or undefined when perform sends it: a unit of the pack that
+     *  declares `vendorBacked.none` beside lanes that are vendor-backed (PlanetScale's SQL wire beside its API lane). */
+    unsent?: (input: Record<string, unknown> | undefined) => string | undefined;
 };
 /** Register a twin's adapters (the mounting host does this from the pack's descriptor or its
  *  anchored exports). Replaces any earlier registration for the service. */

package/dist/src/storage.js

@@ -1,3 +1,4 @@
+import { parseExactJson } from "./exact-json.js";
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { withStateLock, withStateRemoval } from "./ancestry.js";
 import { appendParentEntry, toEntry } from "./log.js";
@@ -121,7 +122,7 @@ function readJsonl(path) {
         if (!line.trim())
             continue;
         try {
-            rows.push(JSON.parse(line));
+            rows.push(parseExactJson(line));
         }
         catch (error) {
             throw new Error(`${path}:${index + 1}: invalid JSONL row: ${error.message}`);
@@ -137,7 +138,7 @@ export function readJsonFile(path) {
         const raw = getActiveWorldStore().read(path);
         if (raw === null)
             throw new Error('no such file');
-        return JSON.parse(raw);
+        return parseExactJson(raw);
     }
     catch (error) {
         throw new Error(`${path}: invalid JSON: ${error.message}`);
@@ -292,6 +293,8 @@ export function createEvent(input) {
  *  one of them so scrubService never demands --force for an ordinary twin. */
 const KNOWN_SERVICE_ENTRIES = new Set([
     'ancestry.json', 'history-format.json', 'views', 'origin.jsonl', 'origin-head.json',
+    'answer-count',
+    'answer-count.lock',
     'events.jsonl',
     'events.jsonl.lock',
     'event-queue.jsonl',

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

@@ -50,12 +50,14 @@ export type TwinStream = (sink: TwinStreamSink, peer: string) => TwinStreamConne
 export declare const TWIN_REQUEST_SCOPES: readonly string[];
 /**
  * THE READ SCOPE for a pack that writes its own fetch (the derived packs, the byte-wire packs): a
- * request carrying the read-only marker runs with the kernel's write seam refusing its writes, and a
+ * request carrying the read-only marker, or an instance mounted read-only, runs with the kernel's
+ * write seam refusing its writes, and a
  * refused write answers `refuse` (the vendor's own read-only error; a generic 405 without one) —
  * whatever the handler made of the refusal. `GET /twin` advertises `requestScopes`. Everything else
  * passes through untouched; the wrapped fetch keeps its own properties (a derived fetch's `owners`).
  */
 export declare function withRequestScopes<F extends (request: Request) => Promise<Response>>(fetch: F, opts?: {
+    readOnly?: boolean;
     refuse?: (request: Request, error: ReadOnlyRequestError) => Response | Promise<Response>;
 }): F;
 export type TwinFetchHandlerResult = {

package/dist/src/twin-fetch.js

@@ -130,7 +130,8 @@ function readOnlyRefusal(error) {
 }
 /**
  * THE READ SCOPE for a pack that writes its own fetch (the derived packs, the byte-wire packs): a
- * request carrying the read-only marker runs with the kernel's write seam refusing its writes, and a
+ * request carrying the read-only marker, or an instance mounted read-only, runs with the kernel's
+ * write seam refusing its writes, and a
  * refused write answers `refuse` (the vendor's own read-only error; a generic 405 without one) —
  * whatever the handler made of the refusal. `GET /twin` advertises `requestScopes`. Everything else
  * passes through untouched; the wrapped fetch keeps its own properties (a derived fetch's `owners`).
@@ -149,7 +150,7 @@ export function withRequestScopes(fetch, opts = {}) {
         // the request's W3C traceparent follows every entry the fetch writes, as through the kernel's own adapters
         // (a custom fetch never entered it, so the timeline's trace filter missed its entries)
         return runWithRequestTrace(request, async () => {
-            if (!isReadOnlyRequest(request))
+            if (!opts.readOnly && !isReadOnlyRequest(request))
                 return fetch(request);
             const out = await runAsReadOnlyRequest(() => fetch(request));
             if (!out.refused)

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

@@ -1,6 +1,13 @@
+import type { ApplicationStandIn } from './events.js';
 /** A call to a vendor the World runs no twin of. */
 export declare class VendorUnreachableError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
-/** `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>;
+/** A twin answered in this process: its fetch, as a World's server hands it a request. */
+export type InProcessTwin = (request: Request) => Response | Promise<Response>;
+/** The twins this process answers itself, by routing key (a key of VENDOR_HOSTS: a journey walk's companions, over the
+ *  walk's own World), consulted before the instance's; returns those set before, which the caller puts back. */
+export declare function setInProcessTwins(twins: Readonly<Record<string, InProcessTwin>>): Readonly<Record<string, InProcessTwin>>;
+/** A vendor URL (or the World's application), including redirects, always answered inside the World; `standIn` is the
+ *  calling fetch's application stand-in (PackFetchOptions.application), consulted at every hop. */
+export declare function vendorFetch(url: string | URL, init?: RequestInit, standIn?: ApplicationStandIn): Promise<Response>;