@volter/world-core 3.0.155 → 3.0.157

package/dist/src/mongodb/stream.js

@@ -0,0 +1,206 @@
+const TIMED = Symbol('mongodb timed reply');
+/**
+ * `reply` after `afterMs` (0: at once); with `everyMs`, again each `everyMs` until the peer closes, where the sender
+ * allowed more than one reply. The two differ in the vendor's own answers: a hello naming the server's current
+ * topology is first answered after the wait, one naming another process at once, and both then repeat at the wait.
+ */
+export const timedReply = (reply, afterMs, everyMs) => ({ [TIMED]: true, reply, afterMs, ...(everyMs !== undefined ? { everyMs } : {}) });
+const isTimed = (answer) => answer[TIMED] === true;
+export const MongoOp = { REPLY: 1, QUERY: 2004, MSG: 2013 };
+/** OP_MSG's flag bits. */
+export const MongoMsgFlag = { CHECKSUM_PRESENT: 1 << 0, MORE_TO_COME: 1 << 1, EXHAUST_ALLOWED: 1 << 16 };
+const HEADER = 16;
+const dec = new TextDecoder();
+const enc = new TextEncoder();
+const view = (bytes) => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+function header(length, requestId, responseTo, opcode) {
+    const out = new Uint8Array(HEADER), v = view(out);
+    v.setInt32(0, length, true);
+    v.setInt32(4, requestId, true);
+    v.setInt32(8, responseTo, true);
+    v.setInt32(12, opcode, true);
+    return out;
+}
+/** An OP_MSG message carrying one document as its body section. */
+export function encodeMsg(codec, document, requestId, responseTo, flags = 0) {
+    const body = codec.serialize(document), bits = new Uint8Array(5);
+    view(bits).setUint32(0, flags, true);
+    return concat([header(HEADER + 4 + 1 + body.length, requestId, responseTo, MongoOp.MSG), bits, body]);
+}
+/** The command of an OP_MSG message: its body section, with each document sequence as the field it names. */
+export function decodeMsg(codec, message) {
+    const v = view(message), flags = v.getUint32(HEADER, true), end = message.length - (flags & MongoMsgFlag.CHECKSUM_PRESENT ? 4 : 0);
+    let document;
+    const sequences = {};
+    for (let at = HEADER + 4; at < end;) {
+        const kind = message[at];
+        at += 1;
+        if (kind === 0) {
+            const size = v.getInt32(at, true);
+            if (size < 5 || at + size > end)
+                throw new Error('OP_MSG body section runs past the message');
+            document = codec.deserialize(message.subarray(at, at + size));
+            at += size;
+        }
+        else if (kind === 1) {
+            const size = v.getInt32(at, true), stop = at + size;
+            if (size < 4 || stop > end)
+                throw new Error('OP_MSG document sequence runs past the message');
+            const nameEnd = message.indexOf(0, at + 4);
+            if (nameEnd < 0 || nameEnd >= stop)
+                throw new Error('OP_MSG document sequence names no field');
+            const name = dec.decode(message.subarray(at + 4, nameEnd)), documents = [];
+            for (let cursor = nameEnd + 1; cursor < stop;) {
+                const length = v.getInt32(cursor, true);
+                if (length < 5 || cursor + length > stop)
+                    throw new Error('OP_MSG document sequence holds a document that runs past it');
+                documents.push(codec.deserialize(message.subarray(cursor, cursor + length)));
+                cursor += length;
+            }
+            sequences[name] = documents;
+            at = stop;
+        }
+        else
+            throw new Error(`OP_MSG section kind ${kind} is unknown`);
+    }
+    if (!document)
+        throw new Error('OP_MSG carries no body section');
+    return { flags, document: { ...document, ...sequences } };
+}
+/** MongoDB's wire, served: each command document answered by the pack, in arrival order, on one connection. */
+export function createMongoStream(options) {
+    const limit = options.maxMessageSizeBytes ?? 48_000_000;
+    let nextResponse = 0;
+    return (sink, peer) => {
+        const session = options.open(peer);
+        let buffer = new Uint8Array(0);
+        let closed = false;
+        let chain = Promise.resolve();
+        // A reply being held or repeated (a timed reply): its timer, and the messages that arrived meanwhile. A
+        // connection serves one command at a time, so nothing else is answered until a held reply is sent, and nothing
+        // at all while a repeating one runs (recording:hello-awaitable-exhaust-then-command.json: a ping sent into the
+        // stream has no reply). The timer is not work: `settled` does not wait for it, it does not keep the process
+        // alive (unref), and a close from either side clears it at once.
+        let held;
+        const parked = [];
+        const release = () => { if (held !== undefined) {
+            clearTimeout(held);
+            held = undefined;
+        } parked.length = 0; };
+        const hold = (ms, then) => {
+            held = setTimeout(() => { held = undefined; if (!closed)
+                then(); }, Math.max(0, ms));
+            held.unref?.();
+        };
+        const end = (reason) => {
+            if (closed)
+                return;
+            closed = true;
+            release();
+            (options.ended ?? ((why, from) => console.error(`mongodb wire: ended the connection from ${from}: ${why}`)))(reason, peer);
+            options.close?.(session);
+            sink.end();
+        };
+        const answer = async (message) => {
+            const v = view(message), requestId = v.getInt32(4, true), opcode = v.getInt32(12, true);
+            if (opcode === MongoOp.MSG) {
+                const { flags, document } = decodeMsg(options.codec, message);
+                const database = typeof document.$db === 'string' ? document.$db : 'admin';
+                const exhaustAllowed = (flags & MongoMsgFlag.EXHAUST_ALLOWED) !== 0;
+                const answered = await options.command(session, database, document, { exhaustAllowed });
+                // the sender waits for no reply to a message it marked moreToCome
+                if (flags & MongoMsgFlag.MORE_TO_COME)
+                    return;
+                if (!isTimed(answered)) {
+                    sink.write(encodeMsg(options.codec, answered, ++nextResponse, requestId));
+                    return;
+                }
+                if (answered.everyMs === undefined || !exhaustAllowed) {
+                    // held once: one reply after the wait, with no flag; then what arrived meanwhile is answered in order
+                    // source: recording:hello-awaitable-no-exhaust.json "received"
+                    hold(answered.afterMs, () => {
+                        sink.write(encodeMsg(options.codec, answered.reply, ++nextResponse, requestId));
+                        for (const message of parked.splice(0))
+                            take(message);
+                    });
+                    return;
+                }
+                // repeated: each reply marked moreToCome; the first answers the request, each later one answers this
+                // wire's own previous reply, until the peer closes
+                // source: recording:hello-awaitable-exhaust.json "received"
+                let answers = requestId;
+                const again = () => {
+                    const id = ++nextResponse;
+                    sink.write(encodeMsg(options.codec, answered.reply, id, answers, MongoMsgFlag.MORE_TO_COME));
+                    answers = id;
+                    hold(answered.everyMs, again);
+                };
+                // source: recording:hello-stale-process-exhaust.json "received" (the first at once, the rest at the wait)
+                hold(answered.afterMs, again);
+                return;
+            }
+            if (opcode === MongoOp.QUERY) {
+                // the legacy form a driver's first hello may take: a query on `<database>.$cmd` whose document is the command
+                const nameEnd = message.indexOf(0, HEADER + 4);
+                if (nameEnd < 0)
+                    throw new Error('OP_QUERY names no collection');
+                const namespace = dec.decode(message.subarray(HEADER + 4, nameEnd));
+                if (!namespace.endsWith('.$cmd'))
+                    throw new Error(`OP_QUERY on ${namespace}: only a command on <database>.$cmd is served`);
+                const command = options.codec.deserialize(message.subarray(nameEnd + 1 + 8));
+                // the legacy form has no flags of OP_MSG's: nothing is held or repeated for it
+                const legacy = await options.command(session, namespace.slice(0, -'.$cmd'.length), command, { exhaustAllowed: false });
+                const reply = options.codec.serialize(isTimed(legacy) ? legacy.reply : legacy);
+                // OP_REPLY: responseFlags (AwaitCapable), cursorID 0, startingFrom 0, numberReturned 1, then the document
+                const fixed = new Uint8Array(20), f = view(fixed);
+                f.setInt32(0, 8, true);
+                f.setInt32(16, 1, true);
+                sink.write(concat([header(HEADER + 20 + reply.length, ++nextResponse, requestId, MongoOp.REPLY), fixed, reply]));
+                return;
+            }
+            throw new Error(`opcode ${opcode} is not served`);
+        };
+        // One message, in arrival order: parked while a reply is held, answered otherwise.
+        const take = (message) => {
+            chain = chain.then(() => (closed ? undefined : held !== undefined ? void parked.push(message) : answer(message))).catch((error) => end(error instanceof Error ? error.message : String(error)));
+        };
+        return {
+            data(chunk) {
+                if (closed)
+                    return;
+                buffer = buffer.length ? concat([buffer, chunk]) : chunk;
+                while (buffer.length >= 4) {
+                    const length = view(buffer).getInt32(0, true);
+                    // where the citation stops: what the vendor's server does with a malformed or oversized message is not
+                    // read; this ends the connection, which no driver's well-formed message reaches
+                    if (length < HEADER || length > limit) {
+                        end(`a message of ${length} bytes (accepted: ${HEADER} to ${limit})`);
+                        return;
+                    }
+                    if (buffer.length < length)
+                        break;
+                    const message = buffer.subarray(0, length);
+                    buffer = buffer.subarray(length);
+                    take(message.slice());
+                }
+            },
+            settled: () => chain,
+            close: () => { if (!closed) {
+                closed = true;
+                release();
+                options.close?.(session);
+            } },
+        };
+    };
+}
+/** The bytes of a C string, for a client's OP_QUERY. */
+export const cstring = (text) => concat([enc.encode(text), new Uint8Array(1)]);

package/dist/src/observe.js

@@ -162,5 +162,5 @@ function foldResources(service, resources, opts) {
             }
         }
         return report;
-    });
+    }, { operation: 'observation batch' });
 }

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

@@ -1,4 +1,4 @@
-import { type DerivedManifest, type Handler, type HandlerContext, type VendorManifest } from './derived-core.js';
+import { type DerivedManifest, type Handler, type HandlerContext, type ScreenDecl, type VendorManifest } from './derived-core.js';
 import { type DerivedFetch, type DerivedSurface, type BoardFrame } from './derived.js';
 import { type PackScenarioAdapter } from './scenario.js';
 import type { ApplicationStandIn } from './events.js';
@@ -86,5 +86,10 @@ export type PackFetchOptions = {
     /** the application a walk stands in for (a life's `application` answers): this fetch's `ctx.ask` is answered by it */
     application?: ApplicationStandIn;
 };
+/** 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 declare function shownRecord(url: URL, workspaces: ReadonlyArray<ScreenDecl>, params: Record<string, string>): string | undefined;
 export declare function createPackFetch(parts: PackParts, options?: PackFetchOptions): DerivedFetch;
 export declare function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): DerivedFetch;

package/dist/src/pack-fetch.js

@@ -1,4 +1,5 @@
 import { parseExactJson } from "./exact-json.js";
+import { redisServiceTimes } from "./redis/service-times.js";
 import { readHostPort } from "./host-port.js";
 // A Protocol 3 pack's whole HTTP surface, served by the kernel from the pack's declarations (docs/contributing/
 // architecture.md, "The pack contract: the kernel's root"): the discovery door (`GET /twin`, the manifest's
@@ -22,7 +23,7 @@ import { withCors } from "./cors.js";
 import { contentAddressOf } from "./content-route.js";
 import { getPack } from "./packRegistry.js";
 import { hostRules } from '../host-routing.cjs';
-import { socketUpgrade } from "./sockets.js";
+import { expireSocketWaits, socketUpgrade } from "./sockets.js";
 import { liveIngest } from "./live/ingest.js";
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from "./resource-blob.js";
 import { resourcesOfType } from "./derived-core.js";
@@ -70,6 +71,32 @@ function hostMatcher(pattern) {
 }
 /** The host a request is for: the vendor host the World's injector names, else its own. */
 const hostOf = (request) => 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, workspaces, params) {
+    const asked = /^([^:]+):(.+)$/.exec(url.searchParams.get('show') ?? '');
+    if (!asked)
+        return undefined;
+    const [, type, id] = asked;
+    const fill = (path, extra) => {
+        let unfilled = false;
+        const filled = path.replace(/\{([^}]+)\}|<([^>]+)>/g, (_, a, b) => {
+            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, request, otherMethod = false) {
@@ -124,6 +151,16 @@ async function encoded(m, request, res) {
 /** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 /** A door's path as it is served and listed: under `/_twin/`, whether the manifest writes the prefix or not. */
 const doorPath = (path) => (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) {
+    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, options = {}) {
     const m = parts.manifest;
     const scope = {
@@ -257,7 +294,7 @@ export function createPackFetch(parts, options = {}) {
         }
     };
     // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
-    const open = (request, id, method, path, params) => contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' }, params }, scope);
+    const open = (request, id, method, path, params, streamed) => contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' }, params, ...(streamed ? { streamed } : {}) }, scope);
     const advanceClock = async (request) => {
         if (parts.clock)
             await runAsVendorMove(async () => parts.clock(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
@@ -369,7 +406,7 @@ export function createPackFetch(parts, options = {}) {
             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). */
@@ -392,7 +429,9 @@ export function createPackFetch(parts, options = {}) {
         const readable = await prepared(arrived);
         return readable instanceof Response ? readable : readable ? atContentHost(readable) : undecodable(arrived);
     };
-    const fetch = async (arrived) => {
+    const fetch = async (received) => {
+        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(/\/+$/, '') || '/';
         const discovery = arrived.method === 'GET' && m.discovery !== undefined && (asked === '/twin' || asked === '/twin/scenario');
@@ -427,6 +466,7 @@ export function createPackFetch(parts, options = {}) {
         const url = new URL(request.url);
         const path = url.pathname.replace(/\/+$/, '') || '/';
         const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
+        redisServiceTimes.lap('2 content and lane routes, decoding, routing');
         if (request.method === 'GET' && path === '/twin' && m.discovery) {
             const d = m.discovery;
             const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: light | docker | none | fake, images?: { image: { context, command?, runtime? } } }.' }] : [])];
@@ -466,6 +506,9 @@ export function createPackFetch(parts, options = {}) {
         // 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') {
@@ -523,9 +566,12 @@ export function createPackFetch(parts, options = {}) {
             ?? (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;
@@ -549,12 +595,19 @@ export function createPackFetch(parts, options = {}) {
             return encoded(m, request, await decided(request));
         // The front reads a context before forwarding (possibly with new headers). Materialize a transport body before
         // those independent reads, rather than chaining tees of the incoming stream through the front and the scenario.
+        redisServiceTimes.lap('3 doors, screens and machine routes passed');
         const bytes = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
         const buffered = new Request(request.url, { method: request.method, headers: request.headers, signal: request.signal, ...(bytes ? { body: bytes } : {}) });
         const matched = matchOperation(routes, buffered.method, url.pathname, url.searchParams, buffered.headers);
         const operation = matched?.operation ?? { id: 'unmatched', method: buffered.method, path: url.pathname, class: buffered.method === 'GET' ? 'retrieve' : 'action' };
+        redisServiceTimes.lap('4 body buffered, operation matched');
         const ctx = await contextFor(m, { request: buffered.clone(), operation, params: matched?.params ?? pathParams(routes, url.pathname) }, scope);
-        return encoded(m, buffered, await parts.around(ctx, (rewritten) => decided(rewritten ?? buffered)));
+        redisServiceTimes.lap('5 the around context opened');
+        const answered = await parts.around(ctx, (rewritten) => decided(rewritten ?? buffered));
+        redisServiceTimes.lap('6d the handler, and the around after it');
+        const sent = await encoded(m, buffered, answered);
+        redisServiceTimes.lap('7 answer encoded');
+        return sent;
     };
     // the request's id is the correlation of every entry it appends (runtime contract D3), minted here, always: it is the
     // group a perform sends as one call (the real-system adapters, "Perform"). Under `auto` the group is performed once
@@ -609,7 +662,7 @@ export function createPackFetch(parts, options = {}) {
     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, 
+    const ownUpgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets, (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);
@@ -739,9 +792,17 @@ export function createVendorFetch(manifest, lanes) {
     const ingest = Object.values(lanes).find((l) => l.fetch.ingest)?.fetch.ingest;
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+        // the discovery door is answered before any lane's clock moves, as a pack's own is (createPackFetch): reading what
+        // the twin is moves no vendor clock
+        if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
+            // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
+            const screens = lanesWorkspaces(lanes);
+            const laneDiscovery = await laneDoors(lanes, request, '/twin');
+            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) });
+        }
         for (const part of Object.values(lanes))
             await part.fetch.advanceClock?.(request);
-        const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
         // the vendor's board is the frames of the lanes that lay one out, each drawn when any lane's screen takes its url
         if (request.method === 'GET' && path === '/twin/board') {
             const frames = [];
@@ -758,12 +819,6 @@ export function createVendorFetch(manifest, lanes) {
             const draws = (url) => Object.values(lanes).some((l) => l.fetch.draws?.(url) ?? false);
             return Response.json({ frames: frames.map((f) => ({ ...f, drawn: draws(f.url) })) });
         }
-        if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
-            // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
-            const screens = lanesWorkspaces(lanes);
-            const laneDiscovery = await laneDoors(lanes, request, '/twin');
-            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) });
-        }
         if (request.method === 'GET' && path === '/twin/scenario') {
             const laneScenarios = await laneDoors(lanes, request, '/twin/scenario');
             if (Object.keys(laneScenarios).length)

package/dist/src/pack-paths.d.ts

@@ -8,7 +8,8 @@ export declare function installedVendorPacks(from: string, options?: {
 }): Map<string, string>;
 /** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
 export declare function installedPackageDir(from: string, name: string): string | undefined;
-/** 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 declare function packRepository(from: string): string | undefined;
 /** Resolve one vendor's package directory for host-side reads (assets, infrastructure launchers). */

package/dist/src/pack-paths.js

@@ -121,7 +121,8 @@ export function installedPackageDir(from, name) {
         dir = up;
     }
 }
-/** 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) {
     let dir = resolve(from);
@@ -129,6 +130,10 @@ export function packRepository(from) {
         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/dist/src/packRegistry.d.ts

@@ -5,6 +5,7 @@ import type { DerivedManifest } from './derived-core.js';
 import type { DerivedSurface } from './derived.js';
 import type { TwinEmitter } from './emit.js';
 import { type StateSystemAdapters } from './state-system.js';
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './protocol.js';
 /**
  * How a pack's clients ADDRESS it. The first three are HTTP API styles; `raw-tcp` is the
  * RAW-PROTOCOL class — a pack whose clients speak their protocol directly over a TCP socket
@@ -37,19 +38,6 @@ export type PackTransport = 'rest' | 'graphql' | 'web-api' | 'raw-tcp';
  *                       seam (fly's runtime, github's git plane, supabase's external stack).
  *   'proxy'           — the vendor itself is a forwarding plane (tunnel).
  */
-/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
- *  descriptor shape, the factory signature, the doors and the adapter contract a package is
- *  written against, and the build form it is made in (the derived pack); a change that removes or
- *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
- *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
- *  declares another, or none, is refused. */
-export declare const PROTOCOL_VERSION = "3.0";
-export declare const PROTOCOL_MAJOR: number;
-/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
-export declare function protocolStanding(declared: string | undefined): {
-    major: number;
-    standing: 'current' | 'refused';
-};
 export declare const PACK_ARCHETYPES: readonly ["crud", "generative", "signed-protocol", "engine-control", "proxy"];
 export type PackArchetype = (typeof PACK_ARCHETYPES)[number];
 /**
@@ -223,9 +211,17 @@ export type TwinPack = {
         urlEnv: string;
     };
     managedService?: {
-        kind: 'redis' | 'mongodb';
+        kind: string;
         scheme: string;
         note: string;
+        configurationArg?: '--configuration';
+        originalInputs?: {
+            version: 1;
+            manifestArg: '--original-inputs';
+            rootArg: '--original-root';
+            digestArg: '--original-inputs-sha256';
+            paths: string[];
+        };
     };
     managedDatabase?: {
         kind: 'postgres';

package/dist/src/packRegistry.js

@@ -11,6 +11,8 @@ import { declareRateBudget } from "./rateBudget.js";
 import { referenceField, registerReferences } from "./references.js";
 import { deriveStateSystem, deriveVendorStateSystem } from "./derived-real.js";
 import { registerAuthStrategy, registerStateSystem } from "./state-system.js";
+import { PROTOCOL_VERSION, protocolStanding } from "./protocol.js";
+export { PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from "./protocol.js";
 /**
  * The pack's SERVE-FAMILY — the axis the invariant matrix keys strictness off, DECLARED
  * because it is the pack's own claim about what kind of thing it is (a heuristic over file
@@ -26,19 +28,6 @@ import { registerAuthStrategy, registerStateSystem } from "./state-system.js";
  *                       seam (fly's runtime, github's git plane, supabase's external stack).
  *   'proxy'           — the vendor itself is a forwarding plane (tunnel).
  */
-/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
- *  descriptor shape, the factory signature, the doors and the adapter contract a package is
- *  written against, and the build form it is made in (the derived pack); a change that removes or
- *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
- *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
- *  declares another, or none, is refused. */
-export const PROTOCOL_VERSION = '3.0';
-export const PROTOCOL_MAJOR = Number(PROTOCOL_VERSION.split('.')[0]);
-/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
-export function protocolStanding(declared) {
-    const major = declared === undefined ? Number.NaN : Number(String(declared).split('.')[0]);
-    return major === PROTOCOL_MAJOR ? { major, standing: 'current' } : { major, standing: 'refused' };
-}
 export const PACK_ARCHETYPES = ['crud', 'generative', 'signed-protocol', 'engine-control', 'proxy'];
 /** The posture to assume for a pack that doesn't declare one. Conservative on purpose. */
 export const DEFAULT_PULL_POSTURE = 'on-demand';

package/dist/src/protocol.d.ts

@@ -0,0 +1,13 @@
+/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
+ *  descriptor shape, the factory signature, the doors and the adapter contract a package is
+ *  written against, and the build form it is made in (the derived pack); a change that removes or
+ *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
+ *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
+ *  declares another, or none, is refused. */
+export declare const PROTOCOL_VERSION = "3.0";
+export declare const PROTOCOL_MAJOR: number;
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
+export declare function protocolStanding(declared: string | undefined): {
+    major: number;
+    standing: 'current' | 'refused';
+};

package/dist/src/protocol.js

@@ -0,0 +1,13 @@
+/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
+ *  descriptor shape, the factory signature, the doors and the adapter contract a package is
+ *  written against, and the build form it is made in (the derived pack); a change that removes or
+ *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
+ *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
+ *  declares another, or none, is refused. */
+export const PROTOCOL_VERSION = '3.0';
+export const PROTOCOL_MAJOR = Number(PROTOCOL_VERSION.split('.')[0]);
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
+export function protocolStanding(declared) {
+    const major = declared === undefined ? Number.NaN : Number(String(declared).split('.')[0]);
+    return major === PROTOCOL_MAJOR ? { major, standing: 'current' } : { major, standing: 'refused' };
+}

package/dist/src/redis/engine.d.ts

@@ -45,9 +45,9 @@ type StoredZSet = Array<[string, string]>;
 export type StreamEntries = Array<[string, HashPairs]>;
 /** A point-in-time copy of a run's whole mutable state, for script rollback. */
 type Snapshot = {
-    rows: Map<string, KeyRow>;
+    rows: OverlayState<KeyRow>;
     touched: Map<string, string>;
-    scripts: Map<string, string>;
+    scripts: OverlayState<string>;
     touchedScripts: Map<string, string>;
 };
 export type KeyRow = {
@@ -168,12 +168,17 @@ export type KeyspaceImage = {
     scripts: Map<string, string>;
     revs: Map<string, number>;
 };
+declare const GONE: unique symbol;
+type OverlayState<V> = {
+    own: Map<string, V | typeof GONE>;
+    moved: Set<string>;
+};
 /**
  * A synchronous, in-memory image of the keyspace for the duration of ONE request.
  *
  * Seeded from the keyspace's image (the tree folded by `projectResources`, memoized per World state — the kernel IS
  * the source of truth); every mutation records the key name in `touched`, and the flush writes exactly those keys
- * back. This run's maps are its own copies: nothing a run changes reaches the image or a later request except
+ * back. This run owns its overlays: nothing a run changes reaches the image or a later request except
  * through the tree.
  */
 export declare class KeySpace {
@@ -185,7 +190,7 @@ export declare class KeySpace {
     private readonly touchedScripts;
     /** name → the last write ordinal seen, INCLUDING for keys currently deleted or expired. */
     private readonly revs;
-    /** The keyspace as the tree held it when this run began: shared, never changed in place. */
+    /** The shared base maps are patched by the next image(); a KeySpace must finish reading its base before it yields. */
     readonly image: KeyspaceImage;
     constructor(ctx: RedisContext, nowMs: number);
     /**
@@ -323,5 +328,6 @@ export declare function execRedisRun(commands: string[][], ctx: RedisContext): P
     items: RunItem[];
     wrote: boolean;
     instant: number;
+    touched: string[];
 }>;
 export {};