@volter/world-core 3.0.156 → 3.0.157

package/src/managed-go-programs.ts

@@ -0,0 +1,146 @@
+/** Tagged managed Go operation metadata. This structural reader grants no
+ * source/image correspondence, filesystem custody, catalog admission or exec. */
+import { posix } from 'node:path';
+
+export interface NativeGoKitReference {
+  package: { name: string; version: string };
+  target: 'wasm32-wali-go-single-thread';
+  releaseSha256: string;
+  producerSha256: string;
+  sourceSha256: string;
+  selection: { path: string; sha256: string };
+  recipe: { path: string; sha256: string };
+  installedRoot: string;
+}
+export interface NativeGoOperation {
+  sourceService: string;
+  role: 'server' | 'prerequisite' | 'health';
+  kit: string;
+  program: { name: string; version: string; manifestId: string; manifestSha256: string; path: string };
+  /** Resolved arguments require separate comparison with the full source. */
+  args: string[];
+  /** Names of existing World values, never caller secrets in this record. */
+  environmentBindings: Record<string, string>;
+  requires: { service: string; condition: 'service_started' | 'service_healthy' | 'service_completed_successfully' }[];
+}
+export interface NativeGoReference {
+  version: 2;
+  implementation: string;
+  release: string;
+  directory: string;
+  snapshotSha256: string;
+  declarationSha256: string;
+  image: string;
+  kits: Record<string, NativeGoKitReference>;
+  server: NativeGoOperation;
+  prerequisites: NativeGoOperation[];
+  health: NativeGoOperation;
+}
+
+const fail = (field: string): never => { throw new Error('Native Go operation metadata is invalid: ' + field); };
+function object(value: unknown, fields: readonly string[], label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return fail(label);
+  const row = value as Record<string, unknown>;
+  if (Object.keys(row).length !== fields.length || fields.some(key => !Object.hasOwn(row, key))) return fail(label);
+  return row;
+}
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value || value.includes('\0')) return fail(label);
+  return value;
+}
+function digest(value: unknown, label: string): string {
+  const out = text(value, label);
+  if (!/^[a-f0-9]{64}$/u.test(out)) return fail(label);
+  return out;
+}
+function relativePath(value: unknown, label: string): string {
+  const out = text(value, label);
+  if (out.startsWith('/') || out.includes('\\') || posix.normalize(out) !== out
+    || out.split('/').some(part => !part || part === '.' || part === '..')) return fail(label);
+  return out;
+}
+function installedPath(value: unknown, label: string): string {
+  const out = text(value, label);
+  if (!out.startsWith('/opt/programs/') || out.includes('\\') || posix.normalize(out) !== out
+    || out.split('/').slice(1).some(part => !part || part === '.' || part === '..')) return fail(label);
+  return out;
+}
+function pin(value: unknown, label: string): { path: string; sha256: string } {
+  const row = object(value, ['path', 'sha256'], label);
+  return { path: relativePath(row.path, label + '.path'), sha256: digest(row.sha256, label + '.sha256') };
+}
+function kit(value: unknown, label: string): NativeGoKitReference {
+  const row = object(value, ['package', 'target', 'releaseSha256', 'producerSha256', 'sourceSha256', 'selection', 'recipe', 'installedRoot'], label);
+  const pack = object(row.package, ['name', 'version'], label + '.package');
+  if (row.target !== 'wasm32-wali-go-single-thread') return fail(label + '.target');
+  return { package: { name: text(pack.name, label + '.package.name'), version: text(pack.version, label + '.package.version') },
+    target: row.target, releaseSha256: digest(row.releaseSha256, label + '.releaseSha256'),
+    producerSha256: digest(row.producerSha256, label + '.producerSha256'), sourceSha256: digest(row.sourceSha256, label + '.sourceSha256'),
+    selection: pin(row.selection, label + '.selection'), recipe: pin(row.recipe, label + '.recipe'),
+    installedRoot: installedPath(row.installedRoot, label + '.installedRoot') };
+}
+function operation(value: unknown, role: NativeGoOperation['role'], kits: Record<string, NativeGoKitReference>, label: string): NativeGoOperation {
+  const row = object(value, ['sourceService', 'role', 'kit', 'program', 'args', 'environmentBindings', 'requires'], label);
+  const selected = text(row.kit, label + '.kit');
+  if (row.role !== role || !Object.hasOwn(kits, selected)) return fail(label + '.role/kit');
+  const provider = kits[selected]!;
+  const command = object(row.program, ['name', 'version', 'manifestId', 'manifestSha256', 'path'], label + '.program');
+  const path = installedPath(command.path, label + '.program.path'), version = text(command.version, label + '.program.version');
+  if (version !== provider.package.version || !path.startsWith(provider.installedRoot + '/')) return fail(label + '.program placement/version');
+  if (!Array.isArray(row.args)) return fail(label + '.args');
+  const args: string[] = [];
+  for (const arg of row.args) {
+    if (typeof arg !== 'string' || arg.includes('\0')) return fail(label + '.args.' + args.length);
+    args.push(arg);
+  }
+  if (!row.environmentBindings || typeof row.environmentBindings !== 'object' || Array.isArray(row.environmentBindings)) return fail(label + '.environmentBindings');
+  const bindings: Record<string, string> = Object.create(null);
+  for (const [name, value] of Object.entries(row.environmentBindings)) {
+    const source = text(value, label + '.environmentBindings.' + name);
+    if (![name, source].every(item => /^[A-Za-z_][A-Za-z0-9_]*$/u.test(item))) return fail(label + '.environmentBindings name');
+    bindings[name] = source;
+  }
+  if (!Array.isArray(row.requires)) return fail(label + '.requires');
+  const dependencies: NativeGoOperation['requires'] = [];
+  for (const value of row.requires) {
+    const edge = object(value, ['service', 'condition'], label + '.requires');
+    if (edge.condition !== 'service_started' && edge.condition !== 'service_healthy' && edge.condition !== 'service_completed_successfully')
+      return fail(label + '.requires.condition');
+    const service = text(edge.service, label + '.requires.service');
+    if (dependencies.some(prior => prior.service === service)) return fail(label + '.requires duplicate service');
+    dependencies.push({ service, condition: edge.condition });
+  }
+  return { sourceService: text(row.sourceService, label + '.sourceService'), role, kit: selected,
+    program: { name: text(command.name, label + '.program.name'), version, manifestId: text(command.manifestId, label + '.program.manifestId'),
+      manifestSha256: digest(command.manifestSha256, label + '.program.manifestSha256'), path },
+    args, environmentBindings: bindings, requires: dependencies };
+}
+
+/** All fields are declared data. The later owned consumer must authenticate
+ * the complete source, kit, original image and admitted installed manifests. */
+export function nativeGoReference(value: unknown): NativeGoReference {
+  const row = object(value, ['version', 'implementation', 'release', 'directory', 'snapshotSha256', 'declarationSha256', 'image', 'kits', 'server', 'prerequisites', 'health'], 'reference');
+  if (row.version !== 2) return fail('version');
+  const image = text(row.image, 'image');
+  if (!/^[^\s@]+@sha256:[a-f0-9]{64}$/u.test(image)) return fail('image');
+  if (!row.kits || typeof row.kits !== 'object' || Array.isArray(row.kits) || !Object.keys(row.kits).length) return fail('kits');
+  const kits: Record<string, NativeGoKitReference> = Object.create(null);
+  for (const [name, value] of Object.entries(row.kits)) kits[text(name, 'kit name')] = kit(value, 'kits.' + name);
+  const server = operation(row.server, 'server', kits, 'server'), health = operation(row.health, 'health', kits, 'health');
+  const implementation = text(row.implementation, 'implementation'), release = text(row.release, 'release');
+  if (kits[server.kit]!.package.name !== implementation || kits[server.kit]!.package.version !== release
+    || health.sourceService !== server.sourceService) return fail('server/health implementation');
+  if (!Array.isArray(row.prerequisites)) return fail('prerequisites');
+  const prerequisites: NativeGoOperation[] = [];
+  for (const value of row.prerequisites)
+    prerequisites.push(operation(value, 'prerequisite', kits, 'prerequisites.' + prerequisites.length));
+  if (new Set(prerequisites.map(item => item.sourceService)).size !== prerequisites.length
+    || prerequisites.some(item => item.sourceService === server.sourceService)) return fail('prerequisite service');
+  const usedKits = new Set([server.kit, health.kit, ...prerequisites.map(item => item.kit)]);
+  if (Object.keys(kits).some(name => !usedKits.has(name))) return fail('unconsumed kit');
+  for (const item of prerequisites) if (!server.requires.some(edge => edge.service === item.sourceService && edge.condition === 'service_completed_successfully'))
+    return fail('server prerequisite completion edge');
+  return { version: 2, implementation, release, directory: relativePath(row.directory, 'directory'),
+    snapshotSha256: digest(row.snapshotSha256, 'snapshotSha256'), declarationSha256: digest(row.declarationSha256, 'declarationSha256'),
+    image, kits, server, prerequisites, health };
+}

package/src/mongodb/stream.ts

@@ -13,6 +13,16 @@ export type MongoDocument = Record<string, unknown>;
 /** BSON, as the pack supplies it (the `bson` library, installed by the pack's package.json). The kernel frames
  *  documents and never reads inside one but for a command's `$db`. */
 export type MongoCodec = { serialize(document: MongoDocument): Uint8Array; deserialize(bytes: Uint8Array): MongoDocument };
+/** What a pack's stream reads of the `bson` library its generated fetch's `loadBson` resolves from the pack: the codec,
+ *  extended JSON, and the number kinds a reply names. The kernel declares the shape and imports nothing of it. */
+export type BsonLibrary = {
+  serialize(document: MongoDocument): Uint8Array;
+  deserialize(bytes: Uint8Array, options?: { promoteValues?: boolean; promoteLongs?: boolean; bsonRegExp?: boolean }): MongoDocument;
+  EJSON: { serialize(value: unknown, options?: { relaxed?: boolean }): MongoDocument; deserialize(value: unknown, options?: { relaxed?: boolean }): MongoDocument };
+  Double: new (value: number) => unknown;
+  Int32: new (value: number) => unknown;
+  Long: { fromNumber(value: number): unknown };
+};
 
 /** What the sender's message said beside its command: whether it will take more than one reply to it (OP_MSG's exhaustAllowed). */
 export type MongoAsked = { exhaustAllowed: boolean };

package/src/pack-fetch.ts

@@ -12,7 +12,7 @@ import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
-import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
+import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type ScreenDecl, type VendorManifest } from './derived-core.ts';
 import { compileSurface, createDerivedFetch, matchOperation, pathParams, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.ts';
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './request-scope.ts';
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
@@ -27,7 +27,7 @@ import { hostRules } from '../host-routing.cjs';
 
 /** A descriptor's host rules, as data. */
 type PackDescriptorHosts = ReadonlyArray<HostRule> | undefined;
-import { socketUpgrade, type SocketEngine } from './sockets.ts';
+import { expireSocketWaits, socketUpgrade, type SocketEngine } from './sockets.ts';
 import { liveIngest } from './live/ingest.ts';
 import type { LiveEngine } from './live/types.ts';
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
@@ -144,6 +144,29 @@ function hostMatcher(pattern: string): (host: string) => Match | undefined {
 /** The host a request is for: the vendor host the World's injector names, else its own. */
 const hostOf = (request: Request): string => readHostPort(request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host)?.host ?? '';
 
+/** Where a workspace asked `?show=<type>:<id>` opens the record (architecture, "Workspace"): the built workspace page
+ *  that shows that type, its parameter the id; else the one that lists the type; else the workspace's home (its root
+ *  page). Every other parameter a page's path names is the asking page's, and a page that cannot be filled is passed
+ *  over. Undefined when nothing is asked; the path (with no `show`) otherwise. */
+export function shownRecord(url: URL, workspaces: ReadonlyArray<ScreenDecl>, params: Record<string, string>): string | undefined {
+  const asked = /^([^:]+):(.+)$/.exec(url.searchParams.get('show') ?? '');
+  if (!asked) return undefined;
+  const [, type, id] = asked;
+  const fill = (path: string, extra: Record<string, string>): string | undefined => {
+    let unfilled = false;
+    const filled = path.replace(/\{([^}]+)\}|<([^>]+)>/g, (_, a?: string, b?: string) => {
+      const v = { ...params, ...extra }[(a ?? b)!];
+      if (v === undefined || v === '') { unfilled = true; return ''; }
+      return encodeURIComponent(v);
+    });
+    return unfilled ? undefined : filled;
+  };
+  const shows = workspaces.filter((s) => s.shows?.type === type).map((s) => fill(s.path, { [s.shows!.param]: id! })).find((p) => p !== undefined);
+  const lists = workspaces.filter((s) => s.lists?.includes(type!)).map((s) => fill(s.path, {})).find((p) => p !== undefined);
+  const home = workspaces.find((s) => s.path.replace(/\/+$/, '') === '') ? '/' : undefined;
+  return shows ?? lists ?? home ?? url.pathname;
+}
+
 /** The answer for a path no operation, door or screen serves, and for an operation nothing models: the manifest's
  *  `gap`, its `{method}` and `{path}` filled, else the manifest's not-found refusal. */
 function gapAnswer(m: DerivedManifest, request: Request, otherMethod = false): Response {
@@ -195,6 +218,16 @@ async function encoded(m: DerivedManifest, request: Request, res: Response): Pro
 /** A door's path as it is served and listed: under `/_twin/`, whether the manifest writes the prefix or not. */
 const doorPath = (path: string): string => (path.startsWith('/_twin/') ? path : `/_twin${path.startsWith('/') ? '' : '/'}${path}`);
 
+/** A request with its path's repeated slashes merged, as a front that merges them routes it (the manifest's
+ *  `mergeSlashes`); one with none is itself. */
+function slashesMerged(request: Request): Request {
+  const url = new URL(request.url);
+  const merged = url.pathname.replace(/\/{2,}/g, '/');
+  if (merged === url.pathname) return request;
+  url.pathname = merged;
+  return new Request(url, request);
+}
+
 export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}): DerivedFetch {
   const m = parts.manifest;
   const scope: CoreScope = {
@@ -311,8 +344,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     } catch { return false; }
   };
   // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
-  const open = (request: Request, id: string, method: string, path: string, params: Record<string, string>): Promise<HandlerContext> =>
-    contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' } as DerivedOperation, params }, scope);
+  const open = (request: Request, id: string, method: string, path: string, params: Record<string, string>, streamed?: true): Promise<HandlerContext> =>
+    contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' } as DerivedOperation, params, ...(streamed ? { streamed } : {}) }, scope);
   const advanceClock = async (request: Request): Promise<void> => {
     if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
   };
@@ -409,7 +442,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const asked = options.readOnly && !isReadOnlyRequest(there) ? withHeaders(there, new Headers([...there.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : there;
     if (method === 'POST' && ((options.readOnly ?? false) || isReadOnlyRequest(asked))) return refusedReadOnly();
     if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(asked.url, m.tenant ? { headers: asked.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
-    return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit!.params }));
+    return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit!.params }, true));
   };
   /** A request as the kernel reads it: the headers only the kernel names taken off, its body decoded (undefined when it
    *  does not decode as its Content-Encoding says). */
@@ -431,7 +464,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const readable = await prepared(arrived);
     return readable instanceof Response ? readable : readable ? atContentHost(readable) : undecodable(arrived);
   };
-  const fetch = async (arrived: Request): Promise<Response> => {
+  const fetch = async (received: Request): Promise<Response> => {
+    const arrived = m.mergeSlashes ? slashesMerged(received) : received;
     redisServiceTimes.lap('1 request made by the stream');
     // the discovery door is the pack's own, whichever lane would take its path
     const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
@@ -499,6 +533,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
     // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
     await advanceClock(request);
+    // a reply a session awaits that the World's clock has run out (sockets.ts)
+    if (m.sockets?.length) expireSocketWaits(m.service, options.root);
     if (path.startsWith('/_twin/')) {
       // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
       if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
@@ -547,8 +583,10 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
       ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? (addressed ? undefined : hits.find((x) => !rooted(x))
         ?? (placed ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined)));
     if (byPath) {
+      const asked = byPath.s.decl.kind === 'workspace' && request.method === 'GET' ? shownRecord(url, screens.filter((x) => x.decl.kind === 'workspace').map((x) => x.decl), { ...(byPath.onHost?.params ?? {}), ...byPath.hit!.params }) : undefined;
+      if (asked !== undefined && asked !== path) return new Response(null, { status: 302, headers: { location: `${(request.headers.get(TWIN_PREFIX_HEADER) ?? '').replace(/\/+$/, '')}${asked}` } });
       if (readOnly && request.method !== 'GET' && request.method !== 'HEAD') return refusedReadOnly();
-      return byPath.s.answer(await open(request, byPath.s.decl.id, request.method, byPath.s.decl.path, { ...(byPath.onHost?.params ?? {}), ...byPath.hit!.params }));
+      return byPath.s.answer(await open(request, byPath.s.decl.id, request.method, byPath.s.decl.path, { ...(byPath.onHost?.params ?? {}), ...byPath.hit!.params }, true));
     }
     for (const route of m.machineRoutes ?? []) {
       const host = request.headers.get('x-volter-twin-original-host') ?? new URL(request.url).hostname;
@@ -622,7 +660,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   // request that opened it (operation `socket:<id>`)
   for (const d of m.sockets ?? []) if (!parts.sockets?.[d.id]) throw new Error(`${m.vendor}: the manifest declares the socket ${d.id}, and semantics/sockets.ts exports no ${d.id}`);
   const ownUpgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets!,
-    (request, d) => open(request, `socket:${d.id}`, 'GET', d.path, {}), hostOf, (request) => new URL(routed(request).url).pathname,
+    (request, d, params) => open(request, `socket:${d.id}`, 'GET', d.path, params), hostOf, (request) => new URL(routed(request).url).pathname,
     // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
     async (asked) => engineOf()?.serve(asked)) : undefined;
   const upgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);

package/src/pack-paths.ts

@@ -102,13 +102,17 @@ export function installedPackageDir(from: string, name: string): string | undefi
   }
 }
 
-/** A pack repository itself, or the P3 repository beside a platform checkout. Applications do not acquire a
+/** A pack repository itself, or a platform checkout's P3 repository: the one `VOLTER_PACKS` names (a worktree's own
+ *  pinned packs, as the repository's scripts read it), else the one beside it. Applications do not acquire a
  *  sibling checkout merely because one happens to be beside them. */
 export function packRepository(from: string): string | undefined {
   let dir = resolve(from);
   for (;;) {
     if (packageName(dir) === 'twin-packs-p3') return dir;
     if (packageName(join(dir, 'packages', 'world-core')) === '@volter/world-core') {
+      const env = globalThis.process?.env?.VOLTER_PACKS;
+      const named = env ? resolve(env) : undefined;
+      if (named && packageName(named) === 'twin-packs-p3') return named;
       const sibling = join(dirname(dir), 'twin-packs-p3');
       if (packageName(sibling) === 'twin-packs-p3') return sibling;
     }

package/src/resource-blob.ts

@@ -1,5 +1,5 @@
 import { isAbsolute, join, relative } from 'node:path';
-import { getActiveBlobStore, readBlobRange } from './blob-store.ts';
+import { type BlobWritten, getActiveBlobStore, readBlobRange, streamChunks, writeBlobStream } from './blob-store.ts';
 import { readBranchMeta } from './log.ts';
 import { worldPaths } from './storage.ts';
 
@@ -19,6 +19,14 @@ export async function writeResourceBlob(service: string, key: string, bytes: Uin
   await getActiveBlobStore().put(resourceBlobFile(worldPaths(service, root).resources, key), bytes);
 }
 
+/** Write a resource payload on this branch from a body as it arrives (a model's weights, an upload's bytes), kept only
+ *  when `accept` holds for its size and SHA-256 (the blob seam's `writeBlobStream`). True when kept. */
+export async function writeResourceBlobStream(service: string, key: string, body: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, accept: (written: BlobWritten) => boolean, root?: string): Promise<boolean> {
+  assertResourceKey(key);
+  const chunks = body instanceof ReadableStream ? streamChunks(body) : body;
+  return writeBlobStream(resourceBlobFile(worldPaths(service, root).resources, key), chunks, accept);
+}
+
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export async function removeResourceBlob(service: string, key: string, root?: string): Promise<void> {

package/src/runtime.ts

@@ -157,8 +157,10 @@ export {
   setActiveBlobStore,
   withBlobStore,
   readBlobRange,
+  streamChunks,
+  writeBlobStream,
 } from './blob-store.ts';
-export type { BlobStore } from './blob-store.ts';
+export type { BlobStore, BlobWritten } from './blob-store.ts';
 export {
   applyTwinWrite,
   applyTwinWrites,
@@ -338,7 +340,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.ts';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from './resource-blob.ts';
 
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.ts';
 

package/src/serve-http.ts

@@ -105,6 +105,28 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
     // the global `Bun.serve` — the request journal's wrap of it (serve.ts) applies to packs and to
     // this seam alike, so the seam never decorates twice on Bun
     const upgrade = options.upgrade;
+    // the sockets open now, by the seam's own count: Bun keeps a socket its server closed (a refused key's 1008, from
+    // `open` or later) in `pendingWebSockets` after its close handler ran, and `stop()`'s promise then never settles
+    // (measured on Bun 1.3.11, macOS arm64, alone: a Bun.serve whose open() calls ws.close(1008) leaves
+    // pendingWebSockets at 1 with its close handler called once, and an awaited stop(true) had not settled after 3 s;
+    // unawaited, the listener closed and the process used 4 ms of CPU over the next 2 s; a client-initiated close
+    // stops in 0 ms). Conform's life hung on it after OpenAI's keyless Realtime step.
+    // and the requests whose handlers have not answered: a stop that drops connections (closeActive) aborts each one's
+    // signal, and Bun's stop still waits for the handler to settle, which a handler that never answers never does
+    // (measured on Bun 1.3.11, macOS arm64, alone: a Bun.serve whose fetch never resolves, its request's signal aborted
+    // by stop(true), pendingRequests 1, the stop unsettled after 3 s). Conform's client check hung on a pack served with
+    // a scenario that answered nothing. Node's path below reports such a handler as cleanup and resolves; so does this one.
+    const live = new Set<unknown>();
+    const inflight = new Set<Request>();
+    const served = options.fetch;
+    const tracked = (request: Request, ...rest: unknown[]): Response | Promise<Response> => {
+      inflight.add(request);
+      let answer: Response | Promise<Response>;
+      try { answer = (served as (r: Request, ...x: unknown[]) => Response | Promise<Response>)(request, ...rest); } catch (error) { inflight.delete(request); throw error; }
+      if (!(answer instanceof Promise)) { inflight.delete(request); return answer; }
+      return answer.finally(() => { inflight.delete(request); });
+    };
+    options = { ...options, fetch: tracked };
     const server = bun.serve({ ...options, hostname, port: options.port ?? 0,
       ...(upgrade ? {
         fetch: (request: Request, server: { upgrade: (request: Request, options: { data: { request: Request } }) => boolean }) => {
@@ -114,14 +136,32 @@ export async function serveHttp(options: ServeHttpOptions): Promise<HttpServer>
           return options.fetch(request);
         },
         websocket: {
-          open: (peer: WebSocketPeer & { data: { request: Request } }) => upgrade.open(peer, peer.data.request),
+          open: (peer: WebSocketPeer & { data: { request: Request } }) => { live.add(peer); return upgrade.open(peer, peer.data.request); },
           message: (peer: WebSocketPeer, data: string | Uint8Array) => upgrade.message(peer, data),
-          close: upgrade.close,
+          close: (peer: WebSocketPeer, ...rest: unknown[]) => { live.delete(peer); return (upgrade.close as (p: WebSocketPeer, ...r: unknown[]) => unknown)(peer, ...rest); },
         },
       } : {}),
     });
     const port = server.port ?? 0;
-    return keepHandler({ hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => { await server.stop(closeActive); } }, options.fetch);
+    return keepHandler({ hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => {
+      const stopping = Promise.resolve(server.stop(closeActive));
+      // stop closes the sockets still open (closeActive), each a close Bun may then keep counting, and drops the
+      // connections of handlers still running: once every socket the seam opened has closed and every handler left is
+      // one whose request was dropped, Bun's stop would never settle on them (above), and the seam has stopped
+      let settled = false;
+      stopping.then(() => { settled = true; }, () => { settled = true; });
+      while (!settled) {
+        const orphaned = [...inflight].every((request) => request.signal.aborted);
+        const counted = ((server as { pendingWebSockets?: number }).pendingWebSockets ?? 0) > 0;
+        if (live.size === 0 && orphaned && (counted || (closeActive && inflight.size > 0))) {
+          stopping.catch(() => {});
+          if (inflight.size) console.error(`serveHttp: forced stop left pending handler cleanup: ${inflight.size} request(s)`);
+          return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+      await stopping;
+    } }, options.fetch);
   }
   return keepHandler(await serveOnNode({ ...options, hostname, urlHost, fetch: decorate ? decorate(options) : options.fetch }), options.fetch);
 }

package/src/sockets.ts

@@ -6,6 +6,7 @@
 // upgrade through the serve seam, and offers every write to every open session of the vendor, after the write's
 // webhooks. A session's own counters (a sequence number, a heartbeat) are the connection's, never the World's state.
 // Nothing here runs at module scope beyond the empty registry.
+import { worldNow } from './world-clock.ts';
 import type { EventWrite } from './events.ts';
 import type { ScenarioEngine } from './scenario.ts';
 import type { WebSocketPeer, WebSocketUpgrade } from './serve-http.ts';
@@ -48,7 +49,7 @@ export type SocketEngine<C> = {
   close?(session: SocketSession, ctx: C): void | Promise<void>;
 };
 
-type Open = { session: SocketSession; engine: SocketEngine<unknown>; context: () => Promise<unknown>; queue: Promise<void>; pending: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }> };
+type Open = { session: SocketSession; engine: SocketEngine<unknown>; context: () => Promise<unknown>; queue: Promise<void>; pending: Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>; due: number }> };
 const sessions = new Map<string, Set<Open>>();
 /** 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. */
@@ -60,6 +61,15 @@ export function openSessions(service: string, root: string | undefined, socket:
   return [...(sessions.get(keyOf(service, root)) ?? [])].filter((o) => o.session.socket === socket).map((o) => o.session);
 }
 
+/** What a session awaits that the World's clock has run out (a life's `wait` past a relay's timeout), rejected as the
+ *  machine's clock would reject it; called as the vendor serves a request ("A request answered by a session"). */
+export function expireSocketWaits(service: string, root: string | undefined): void {
+  const open = sessions.get(keyOf(service, root));
+  if (!open?.size) return;
+  const now = Date.parse(worldNow());
+  for (const o of open) for (const [k, p] of o.pending) if (p.due <= now) { clearTimeout(p.timer); o.pending.delete(k); p.reject(new Error('no reply in time')); }
+}
+
 /** 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: string, root: string | undefined, write: EventWrite): void {
@@ -72,21 +82,42 @@ export function socketWrite(service: string, root: string | undefined, write: Ev
   }
 }
 
+/** A declared socket path's parameters for a request's path, or undefined when it does not match: a `{name}` segment
+ *  matches one segment, as an operation's path parameter does (architecture, sockets). */
+function socketParams(declared: string, path: string): Record<string, string> | undefined {
+  const names: string[] = [];
+  const pattern = (declared.replace(/\/+$/, '') || '/').split(/(\{[^}/]+\})/).map((part) => {
+    const name = /^\{([^}/]+)\}$/.exec(part)?.[1];
+    if (name === undefined) return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    names.push(name);
+    return '([^/]+)';
+  }).join('');
+  const hit = new RegExp(`^${pattern}$`).exec(path);
+  if (!hit) return undefined;
+  try { return Object.fromEntries(names.map((name, i) => [name, decodeURIComponent(hit[i + 1]!)])); } catch { return undefined; }
+}
+
 /** 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<C>(
   service: string,
   root: string | undefined,
   decls: ReadonlyArray<SocketDecl>,
   engines: Record<string, SocketEngine<C>>,
-  context: (request: Request, decl: SocketDecl) => Promise<C>,
+  context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>,
   hostOf: (request: Request) => string,
   pathOf: (request: Request) => string = (request) => new URL(request.url).pathname,
   decide: (asked: unknown) => Promise<ScenarioServed | undefined> = async () => undefined,
 ): WebSocketUpgrade {
-  const declFor = (request: Request): SocketDecl | undefined => decls.find((d) => {
+  const matchFor = (request: Request): { decl: SocketDecl; params: Record<string, string> } | undefined => {
     const path = pathOf(request).replace(/\/+$/, '') || '/';
-    return (d.path.replace(/\/+$/, '') || '/') === path && (!d.host || d.host.toLowerCase() === hostOf(request)) && engines[d.id] !== undefined;
-  });
+    for (const d of decls) {
+      if ((d.host && d.host.toLowerCase() !== hostOf(request)) || engines[d.id] === undefined) continue;
+      const params = socketParams(d.path, path);
+      if (params) return { decl: d, params };
+    }
+    return undefined;
+  };
+  const declFor = (request: Request): SocketDecl | undefined => matchFor(request)?.decl;
   const byPeer = new WeakMap<WebSocketPeer, Open>();
   const key = keyOf(service, root);
   return {
@@ -99,7 +130,7 @@ export function socketUpgrade<C>(
       return declared ? offered.find((p) => declared.includes(p)) : offered[0];
     },
     open: (peer, request) => {
-      const decl = declFor(request)!;
+      const { decl, params } = matchFor(request)!;
       const engine = engines[decl.id]! as SocketEngine<unknown>;
       const pending: Open['pending'] = new Map();
       const session: SocketSession = {
@@ -108,7 +139,7 @@ export function socketUpgrade<C>(
         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 });
+          pending.set(key, { resolve, reject, timer, due: Date.parse(worldNow()) + ms });
         }),
         fulfil: (key, value) => {
           const p = pending.get(key);
@@ -118,7 +149,7 @@ export function socketUpgrade<C>(
         },
         decide,
       };
-      const o: Open = { session, engine, context: () => context(request.clone(), decl), queue: Promise.resolve(), pending };
+      const o: Open = { session, engine, context: () => context(request.clone(), decl, params), 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 as Error).message ?? error).slice(0, 120)));

package/src/vendor-call.ts

@@ -41,6 +41,50 @@ async function worldTwins(): Promise<Record<string, string>> {
   return { ...twinOrigins(env), ...twinOrigins(instanceEnv) };
 }
 
+/** The hosts each claiming twin last listed at its `hostsClaimed` door, by the door's address, and when; read again
+ *  after CLAIMS_TTL_MS or for a host it lacks, as the injector polls the doors every five seconds (inject.cjs, "HOSTS A TWIN CLAIMS WHILE IT
+ *  RUNS"). */
+const claimsRead = new Map<string, { hosts: Set<string>; at: number }>();
+const CLAIMS_TTL_MS = 5_000;
+
+/** The hosts a twin claims at its door: in process (a journey walk's companion) or at its address, within the injector's
+ *  first-read deadline (inject.cjs CLAIMS_WAIT_MS, 1500 ms, measured beside it); a door that does not answer claims
+ *  nothing. */
+async function claimedHosts(at: string, ask: () => Promise<Response>, host: string): Promise<Set<string>> {
+  const held = claimsRead.get(at);
+  // a host the held list lacks is asked for again once, as the injector refreshes before it refuses: a domain claimed a
+  // moment ago is found
+  if (held && Date.now() - held.at < CLAIMS_TTL_MS && held.hosts.has(host)) return held.hosts;
+  let hosts = new Set<string>();
+  try {
+    const r = await ask();
+    const body = r.ok ? await r.json() as { hosts?: unknown[] } : null;
+    hosts = new Set((body?.hosts ?? []).map((h) => String(h).toLowerCase()));
+  } catch { /* an unanswered door claims nothing */ }
+  claimsRead.set(at, { hosts, at: Date.now() });
+  return hosts;
+}
+
+/** The twin that claims a host at its `hostsClaimed` door (an R2 bucket's custom domain, a Worker's), as the injector
+ *  routes it: a twin this process answers first, the World's twins after. */
+async function claimingTwin(target: URL, twins: Record<string, string>): Promise<{ vendor: string; local: boolean } | undefined> {
+  const { packFacts } = await import('../pack-facts.cjs') as { packFacts: () => { packs: Record<string, { hostsClaimed?: { door?: string } }> } };
+  const host = target.hostname.toLowerCase();
+  const key = process.env.VOLTER_TWINS_KEY;
+  const doors = Object.entries(packFacts().packs).flatMap(([vendor, facts]) => (facts.hostsClaimed?.door ? [[vendor, facts.hostsClaimed.door] as const] : []));
+  for (const [vendor, door] of doors) {
+    const twin = inProcessTwins[vendor];
+    if (twin && (await claimedHosts(`in-process:${vendor}${door}`, async () => twin(new Request(`http://${vendor}.twin${door}`)), host)).has(host)) return { vendor, local: true };
+  }
+  for (const [vendor, door] of doors) {
+    const origin = twins[vendor];
+    if (origin === undefined) continue;
+    const at = `${origin.replace(/\/$/, '')}${door}`;
+    if ((await claimedHosts(at, () => fetch(at, { headers: key ? { 'x-twins-key': key } : {}, signal: AbortSignal.timeout(1500) }), host)).has(host)) return { vendor, local: false };
+  }
+  return undefined;
+}
+
 /** One URL answered only by a World-held application or vendor twin: the fetch's application stand-in first (its answer
  *  is the application's; `'unreachable'` leaves no application to reach, the World's twins still reachable). */
 async function worldResponse(target: URL, init: RequestInit, standIn?: ApplicationStandIn): Promise<Response> {
@@ -67,8 +111,18 @@ async function worldResponse(target: URL, init: RequestInit, standIn?: Applicati
     if (key && !headers.has('x-twins-key')) headers.set('x-twins-key', key);
     return fetch(`${twins[vendor]!.replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
   }
+  // the application's own hosts before any twin's claimed ones: a call to the application asks no door
   const { appDestination, appFetch } = await import('../app-route.cjs') as { appDestination: (url: URL) => unknown; appFetch: (url: URL, init: RequestInit) => Promise<Response> };
   if (scripted !== 'unreachable' && appDestination(target)) return appFetch(target, { ...init, redirect: 'manual' });
+  const claimer = await claimingTwin(target, twins);
+  if (claimer !== undefined) {
+    const headers = new Headers(init.headers);
+    headers.set('x-volter-twin-original-host', target.host);
+    if (claimer.local) return inProcessTwins[claimer.vendor]!(new Request(target, { ...init, headers, redirect: 'manual' }));
+    const key = process.env.VOLTER_TWINS_KEY;
+    if (key && !headers.has('x-twins-key')) headers.set('x-twins-key', key);
+    return fetch(`${twins[claimer.vendor]!.replace(/\/$/, '')}${target.pathname}${target.search}`, { ...init, headers, redirect: 'manual' });
+  }
   throw new VendorUnreachableError(`${target.host}${target.pathname}: this World holds no application or vendor twin at this URL`);
 }