@volter/twin-tunnel 0.1.36 → 1.0.0

package/dist/src/manifest.js

@@ -0,0 +1,42 @@
+export const manifest = {
+    vendor: 'tunnel',
+    service: 'tunnel',
+    body: { json: 'always' },
+    ids: { template: '{letters:8}' },
+    time: 'iso',
+    error: '{message}',
+    readOnly: { status: 403, message: 'This twin was started read-only; writes are refused.' },
+    notFound: { status: 404, message: 'Not Found' },
+    gap: { status: 404, message: 'Not Found' },
+    list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+    deleted: {},
+    resources: {
+        _account: { idPrefix: '' },
+        // a tunnel id an account holds (one minted when a client names none)
+        _tunnel: { idPrefix: '' },
+    },
+    sockets: [
+        { id: 'control', path: '/ws', note: "a client's control channel: register, then answer each request the relay sends", source: 'https://github.com/volter-ai/volter-tunnel/blob/main/packages/core/src/protocol.ts' },
+    ],
+    doors: [
+        { id: 'accounts', method: 'POST', path: '/_twin/accounts', note: '{ slug }: an account on the relay and its token (the World application\'s TUNNEL_SECRET)' },
+    ],
+    discovery: {
+        twinOf: "Volter's tunnel relay (volter-tunnel) as Volter Harness's remote access uses it: a client's control socket, and every request to its tunnel answered through it",
+        stores: 'accounts and their tokens (by their SHA-256), and the tunnel ids they hold',
+        identity: "the account's token in the control channel's register frame",
+    },
+    descriptor: {
+        protocol: '3',
+        transport: 'rest',
+        archetype: 'proxy',
+        bin: 'world-tunnel',
+        resources: [],
+        specSource: 'written from volter-ai/volter-tunnel (spec/SOURCE.md)',
+        description: "Tunnel relay twin — a client's control socket (register, then each public request sent down it and answered by the frames it sends back), as Volter Harness's remote access shares a local server.",
+        adoption: { sdks: ['@volter/tunnel'], envStems: ['TUNNEL', 'VOLTERTUNNEL'] },
+        hosts: [{ host: 'voltertest.xyz' }, { suffix: '.voltertest.xyz' }, { host: 'www.voltertest.xyz', exclude: true }, { host: 'twins.voltertest.xyz', exclude: true }],
+        credentialDoor: { path: '/_twin/accounts', body: { slug: 'world' }, fill: { TUNNEL_SECRET: 'token', TUNNEL_SERVER_URL: 'server', SUPERCODE_TUNNEL_SERVER_URL: 'server' } },
+        endpointEnvNone: 'the relay URL is the credential door\'s (TUNNEL_SERVER_URL, SUPERCODE_TUNNEL_SERVER_URL), the World claiming voltertest.xyz',
+    },
+};

package/dist/src/semantics/around.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response>;

package/dist/src/semantics/around.js

@@ -0,0 +1,39 @@
+import { b64encode, DOMAIN, holder, RESERVED } from "./shared.js";
+const text = (status, body) => new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+const HOP = new Set(['host', 'connection', 'upgrade', 'keep-alive', 'transfer-encoding', 'content-length']);
+/** The tunnel a request is for: its host's label, or `?__tunnel=` on a direct host (the relay's local testing). */
+function tunnelOf(request) {
+    const url = new URL(request.url);
+    const host = (request.headers.get('host') ?? url.host).toLowerCase().replace(/:\d+$/, '');
+    const label = host.endsWith(`.${DOMAIN}`) ? host.slice(0, -DOMAIN.length - 1) : undefined;
+    if (label && !label.includes('.') && !RESERVED.has(label))
+        return label;
+    const direct = host === 'localhost' || host.startsWith('127.') || host === '0.0.0.0' || !host.endsWith(DOMAIN);
+    return direct ? url.searchParams.get('__tunnel') ?? undefined : undefined;
+}
+export async function around(ctx, next) {
+    const request = ctx.call.request;
+    const id = tunnelOf(request);
+    if (!id)
+        return next();
+    const client = holder(ctx, id);
+    if (!client)
+        return text(502, 'Tunnel not connected');
+    const url = new URL(request.url);
+    url.searchParams.delete('__tunnel');
+    const body = request.method === 'GET' || request.method === 'HEAD' ? null : new Uint8Array(await request.arrayBuffer());
+    // a body goes in one frame: over the relay's limit it is refused at once
+    if (body && body.length > 750_000)
+        return text(413, 'Request body too large to tunnel (limit ~750KB)');
+    const headers = Object.fromEntries([...request.headers].filter(([k]) => !HOP.has(k.toLowerCase()) && !k.toLowerCase().startsWith('x-volter')));
+    // the relay's correlation key for this request on this client's socket: the socket's own count, not World state (a
+    // request the relay forwards is no subject of the World)
+    const reqId = `${client.id}-${(client.state.requests = Number(client.state.requests ?? 0) + 1)}`;
+    client.send({ type: 'request', reqId, method: request.method, path: `${url.pathname}${url.search}`, headers, body: body?.length ? b64encode(body) : null });
+    try {
+        return (await client.expect(reqId, 30_000));
+    }
+    catch {
+        return text(504, 'Tunnel timeout');
+    }
+}

package/dist/src/semantics/doors.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerContext } from '@volter/world-core';
+/** An account by its slug (answered again for the same slug) and its token, drawn from the World's secret. */
+export declare function accounts(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/doors.js

@@ -0,0 +1,18 @@
+import { ACCOUNT, sha256 } from "./shared.js";
+/** An account by its slug (answered again for the same slug) and its token, drawn from the World's secret. */
+export async function accounts(ctx) {
+    const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {});
+    const slug = String(b.slug ?? '');
+    // the relay's account slug (server-cf/src/credits.ts, SLUG_RE)
+    if (!/^[a-z0-9][a-z0-9-]{1,62}$/.test(slug))
+        return Response.json({ message: 'slug must be lowercase letters, digits and dashes' }, { status: 400 });
+    let account = ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.slug === slug);
+    // Where the documentation stops: a token's form is the relay's own; the twin's is `vt_` and 40 letters and digits
+    const tokenOf = async (id) => `vt_${(await ctx.secret(`tunnel-token:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 40)}`;
+    if (!account) {
+        const id = ctx.mint(ACCOUNT);
+        await ctx.record(ACCOUNT, { slug, token_sha256: sha256(ctx, await tokenOf(id)) }, id);
+        account = ctx.row(ACCOUNT, id);
+    }
+    return Response.json({ slug, token: await tokenOf(String(account.id)), server: `https://voltertest.xyz` }, { status: 201 });
+}

package/dist/src/semantics/index.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const tunnelSemantics: Record<string, Handler>;

package/dist/src/semantics/index.js

@@ -0,0 +1 @@
+export const tunnelSemantics = {};

package/dist/src/semantics/shared.d.ts

@@ -0,0 +1,17 @@
+import type { HandlerContext, SocketSession } from '@volter/world-core';
+export type Row = Record<string, unknown>;
+export type { HandlerContext };
+export declare const ACCOUNT = "_account";
+export declare const TUNNEL = "_tunnel";
+export declare const DOMAIN = "voltertest.xyz";
+/** Labels of the domain that are not tunnels: the relay's own front (`www`, its RESERVED_HOSTS default) and the twins
+ *  cloud Volter serves there. */
+export declare const RESERVED: Set<string>;
+export declare const sha256: (ctx: Pick<HandlerContext, "crypto">, v: string) => string;
+export declare const tunnelUrl: (id: string) => string;
+/** A tunnel id as the relay's registry takes one: lowercase letters, digits and inner dashes. */
+export declare const validId: (id: string) => boolean;
+/** The registered control session holding a tunnel, if a client holds it now. */
+export declare const holder: (ctx: Pick<HandlerContext, "sockets">, id: string) => SocketSession | undefined;
+export declare const b64encode: (bytes: Uint8Array) => string;
+export declare const b64decode: (text: string) => Uint8Array;

package/dist/src/semantics/shared.js

@@ -0,0 +1,15 @@
+export const ACCOUNT = '_account';
+export const TUNNEL = '_tunnel';
+// the relay's TUNNEL_DOMAIN (server-cf/wrangler.jsonc, spec/SOURCE.md)
+export const DOMAIN = 'voltertest.xyz';
+/** Labels of the domain that are not tunnels: the relay's own front (`www`, its RESERVED_HOSTS default) and the twins
+ *  cloud Volter serves there. */
+export const RESERVED = new Set(['www', 'twins']);
+export const sha256 = (ctx, v) => ctx.crypto.digest('sha256', v);
+export const tunnelUrl = (id) => `https://${id}.${DOMAIN}`;
+/** A tunnel id as the relay's registry takes one: lowercase letters, digits and inner dashes. */
+export const validId = (id) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(id);
+/** The registered control session holding a tunnel, if a client holds it now. */
+export const holder = (ctx, id) => ctx.sockets('control').find((s) => s.state.registered === true && s.state.tunnelId === id);
+export const b64encode = (bytes) => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(''));
+export const b64decode = (text) => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));

package/dist/src/semantics/sockets.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext, SocketEngine } from '@volter/world-core';
+export declare const control: SocketEngine<HandlerContext>;

package/dist/src/semantics/sockets.js

@@ -0,0 +1,80 @@
+import { ACCOUNT, b64decode, holder, sha256, TUNNEL, tunnelUrl, validId } from "./shared.js";
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const streams = (s) => (s.state.streams ??= new Map());
+const headersOf = (v) => { const h = new Headers(); for (const [k, x] of Object.entries(obj(v)))
+    h.set(k, String(x)); return h; };
+/** A rejected registration: the error frame, then the close (protocol.ts `ErrorMsg`; tunnel-do's rejection). */
+function reject(s, message, code, reason) {
+    s.send({ type: 'error', message });
+    s.close(code, reason);
+}
+async function register(s, msg, ctx) {
+    const token = typeof msg.secret === 'string' ? msg.secret : '';
+    const account = token ? ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.token_sha256 === sha256(ctx, token)) : undefined;
+    if (!account)
+        return reject(s, 'Tunnel rejected: credential is invalid or revoked. On an owner-authenticated device, run "volter-tunnel tokens" and restore this host token, or sign in again on the host.', 4003, 'badToken');
+    // the control URL's ?id= names the tunnel (the routing relay's authority), else the register frame's, else one minted
+    // This id names a stored reservation: mint it, then record the reservation with its owner below. ctx.issue is for
+    // issued ids whose subjects the vendor does not store; its empty row would look like another account's reservation.
+    const id = String(s.state.tunnelId || msg.tunnelId || ctx.mint(TUNNEL));
+    if (!validId(id))
+        return reject(s, `Tunnel rejected: invalid tunnel id ${id}`, 4029, 'invalidId');
+    const held = ctx.row(TUNNEL, id);
+    // Where the documentation stops: a tunnel id another account holds is refused, as the relay's reservation refuses it
+    if (held && held._owner !== account.id)
+        return reject(s, `Tunnel rejected: ${id} is reserved by another account`, 4029, 'reserved');
+    const live = holder(ctx, id);
+    if (live && live !== s) {
+        // Where the documentation stops: a live registration of the id is refused unless this one replaces it
+        if (msg.replace !== true)
+            return reject(s, `Tunnel rejected: ${id} is already connected`, 4029, 'inUse');
+        live.state.registered = false;
+        live.close(4001, 'Replaced by new client');
+    }
+    if (!held)
+        await ctx.record(TUNNEL, { _owner: account.id, reservedAt: ctx.occurredAt }, id);
+    Object.assign(s.state, { registered: true, tunnelId: id, account: account.id, authRequired: msg.authRequired !== false });
+    s.send({ type: 'registered', tunnelId: id, url: tunnelUrl(id) });
+}
+export const control = {
+    open(s, ctx) {
+        s.state.tunnelId = new URL(ctx.call.request.url).searchParams.get('id') ?? '';
+    },
+    async message(s, data, ctx) {
+        let msg;
+        try {
+            msg = obj(JSON.parse(data));
+        }
+        catch {
+            return;
+        }
+        if (msg.type === 'register')
+            return register(s, msg, ctx);
+        if (s.state.registered !== true)
+            return;
+        const reqId = String(msg.reqId ?? '');
+        if (msg.type === 'response') {
+            s.fulfil(reqId, new Response(msg.body ? b64decode(String(msg.body)) : null, { status: Number(msg.status ?? 502), headers: headersOf(msg.headers) }));
+        }
+        else if (msg.type === 'response-start') {
+            const body = new ReadableStream({ start: (c) => { streams(s).set(reqId, c); } });
+            s.fulfil(reqId, new Response(body, { status: Number(msg.status ?? 502), headers: headersOf(msg.headers) }));
+        }
+        else if (msg.type === 'response-chunk') {
+            streams(s).get(reqId)?.enqueue(b64decode(String(msg.data ?? '')));
+        }
+        else if (msg.type === 'response-end') {
+            streams(s).get(reqId)?.close();
+            streams(s).delete(reqId);
+        }
+    },
+    close(s) {
+        for (const c of streams(s).values()) {
+            try {
+                c.error(new Error('Tunnel closed'));
+            }
+            catch { /* already ended */ }
+        }
+        streams(s).clear();
+    },
+};

package/dist/src/semantics/states.d.ts

@@ -0,0 +1 @@
+export declare const states: {};

package/dist/src/semantics/states.js

@@ -0,0 +1,3 @@
+// The relay's state rulings (architecture, "State"): a tunnel id is held by the account that registered it first; a
+// session's registration is the connection's, never World state.
+export const states = {};

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { type PackFetchOptions } from '@volter/world-core';
+export declare function createTunnelTwinServer(options?: PackFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/server.js

@@ -0,0 +1,9 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp } from '@volter/world-core';
+import { createTunnelFetch } from "./fetch.js";
+export async function createTunnelTwinServer(options = {}) {
+    const fetch = createTunnelFetch(options);
+    // the vendor's sockets, when its manifest declares any (the kernel's sockets.ts)
+    const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch, ...(fetch.upgrade ? { upgrade: fetch.upgrade } : {}) });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/generated/pack-facts.json

@@ -0,0 +1,54 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "tunnel": {
+      "adoption": {
+        "sdks": [
+          "@volter/tunnel"
+        ],
+        "envStems": [
+          "TUNNEL",
+          "VOLTERTUNNEL"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "voltertest.xyz"
+        },
+        {
+          "suffix": ".voltertest.xyz"
+        },
+        {
+          "host": "www.voltertest.xyz",
+          "exclude": true
+        },
+        {
+          "host": "twins.voltertest.xyz",
+          "exclude": true
+        }
+      ],
+      "archetype": "proxy",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [],
+      "endpointEnvNone": "the relay URL is the credential door's (TUNNEL_SERVER_URL, SUPERCODE_TUNNEL_SERVER_URL), the World claiming voltertest.xyz",
+      "credentialDoor": {
+        "path": "/_twin/accounts",
+        "body": {
+          "slug": "world"
+        },
+        "fill": {
+          "TUNNEL_SECRET": "token",
+          "TUNNEL_SERVER_URL": "server",
+          "SUPERCODE_TUNNEL_SERVER_URL": "server"
+        }
+      },
+      "serveExport": "createTunnelTwinServer"
+    }
+  },
+  "undeclared": []
+}

package/package.json

@@ -1,20 +1,9 @@
 {
   "name": "@volter/twin-tunnel",
-  "version": "0.1.36",
-  "description": "Local Cloudflare Quick Tunnel control-plane and Volter relay twin with a genuine loopback HTTP data path.",
+  "version": "1.0.0",
+  "description": "The tunnel twin (Protocol 3).",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
-  "files": [
-    "src",
-    "README.md",
-    "!**/*.test.ts",
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
-    "directory": "packages/twin/tunnel"
-  },
   "type": "module",
   "exports": {
     ".": {
@@ -25,28 +14,23 @@
   "bin": {
     "world-tunnel": "dist/src/cli.js"
   },
-  "scripts": {
-    "test": "bun test src/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "build": "node ../../../scripts/publish/build.mjs",
-    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
-    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
-  },
+  "files": [
+    "src",
+    "spec",
+    "README.md",
+    "!**/*.test.ts",
+    "dist",
+    "generated"
+  ],
   "peerDependencies": {
-    "@volter/world-core": "2.0.36"
-  },
-  "devDependencies": {
-    "@types/bun": "^1.2.20",
-    "@types/node": "^24.0.0",
-    "@types/ws": "^8.18.1",
-    "@volter/tunnel": "^2.0.5",
-    "@volter/tunnel-core": "0.1.3",
-    "@volter/world-core": "2.0.36",
-    "@volter/world-tooling": "0.1.0",
-    "typescript": "^5.9.0"
+    "@volter/world-core": "^3.0.1"
   },
   "engines": {
     "node": ">=22.3"
   },
-  "homepage": "https://world.volter.ai/twins/tunnel"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin-packs-p3.git",
+    "directory": "tunnel"
+  }
 }

package/spec/SOURCE.md

@@ -0,0 +1,14 @@
+# volter-tunnel relay spec — provenance
+
+- **Why this document:** the relay publishes no OpenAPI document. Its contract is volter-ai/volter-tunnel at
+  `c14b6e3` (2026-09-28): `packages/core/src/protocol.ts` (the control channel's frames, "the single source of truth
+  for the messages exchanged over the control WebSocket between a client and the relay") and the Cloudflare relay,
+  `server-cf/src/worker.ts` (routing: the control channel at `/ws?id=<tunnelId>`; a tunnel at `<tunnelId>.<domain>`,
+  or `?__tunnel=<id>` on a direct host such as localhost; `/api/status` at the apex) and `server-cf/src/tunnel-do.ts`
+  (registration: `registered` with `url: https://<tunnelId>.<domain>`, a rejected credential `{type:"error"}` then
+  close 4003, a replaced client closed 4001 "Replaced by new client"; a public request: 502 "Tunnel not connected",
+  504 "Tunnel timeout" after 30 s, 413 over 750000 bytes of body; the reply frames `response`, `response-start`,
+  `response-chunk`, `response-end`). The domain is `voltertest.xyz` (`server-cf/wrangler.jsonc`, `TUNNEL_DOMAIN`).
+- **Corrections:** none.
+- **Read by:** the twin orchestrator, 2026-09-30.
+- **Vendored bytes (sha256):** `openapi.json` `b4fcdc3d599026bef687c946cea3c8837c63ff982e5d899df1425e585832aebd`.

package/spec/openapi.json

@@ -0,0 +1,18 @@
+{
+ "openapi": "3.0.2",
+ "info": {
+  "title": "volter-tunnel relay",
+  "version": "2",
+  "description": "The volter-tunnel relay's HTTP surface at its apex: its status. A client's control channel (a WebSocket at /ws?id=<tunnelId>) and the public requests it answers (every path of <tunnelId>.<domain>) are the relay's protocol, recorded in spec/SOURCE.md. Written from volter-ai/volter-tunnel (spec/SOURCE.md)."
+ },
+ "servers": [{ "url": "https://voltertest.xyz" }],
+ "paths": {
+  "/api/status": {
+   "get": {
+    "operationId": "getStatus",
+    "summary": "The relay's status.",
+    "responses": { "200": { "description": "The relay is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "relay": { "type": "string", "example": "cloudflare-do" } } } } } } }
+   }
+  }
+ }
+}

package/src/cli.ts

@@ -1,48 +1,22 @@
 #!/usr/bin/env node
-import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-tunnel: serve the tunnel twin.
 import { hasFlag, optionValue } from '@volter/world-core/args';
-import { createTunnelTwinServer, parseTunnelLoopbackOrigin } from './tunnel-server.ts';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createTunnelTwinServer } from './server.ts';
 
-const [command, ...args] = process.argv.slice(2);
-const rawPort = optionValue(args, '--port');
-const port = rawPort === undefined ? undefined : Number(rawPort);
-if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535)) {
-  process.stderr.write(`world-tunnel: --port must be an integer 0-65535 (got ${JSON.stringify(rawPort)})\n`);
-  process.exit(2);
-}
-const root = optionValue(args, '--root') || undefined;
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+// the World's managed Postgres, which the runtime binds a pack declaring managedDatabase to
+const database = optionValue(rest, '--database') || undefined;
+// the World's scenario file, for a model vendor's turns
+const scenarioPath = optionValue(rest, '--scenario') || undefined;
 
-if (command === 'serve') {
-  const server = createTunnelTwinServer({
-    ...(port ? { port } : {}),
-    ...(root ? { root } : {}),
-    readOnly: hasFlag(args, '--read-only'),
-    requireTid: hasFlag(args, '--require-tid'),
-  });
-  process.stdout.write(`tunnel twin listening on ${server.url}\n`);
-  process.stdout.write(`Volter SDK host=${server.url}; Cloudflare quick service=${server.url}\n`);
-  await keepProcessAlive();
-} else if (command === 'quick' || command === 'tunnel') {
-  const origin = optionValue(args, '--url');
-  if (!origin) { process.stderr.write('world-tunnel quick requires --url http://127.0.0.1:<port>\n'); process.exit(2); }
-  try { parseTunnelLoopbackOrigin(origin); }
-  catch (error) { process.stderr.write(`world-tunnel quick: ${error instanceof Error ? error.message : String(error)}\n`); process.exit(2); }
-  const server = createTunnelTwinServer({ ...(port ? { port } : {}), ...(root ? { root } : {}) });
-  const allocation = await fetch(`${server.url}/tunnel`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
-  const body = await allocation.json() as { success: boolean; result?: { id: string } };
-  if (!allocation.ok || !body.success || !body.result) throw new Error('quick-tunnel allocation failed');
-  server.registerQuickOrigin(body.result.id, origin);
-  // The world runtime discovers the first URL in stdout. This is deliberately a loopback URL:
-  // the twin proves the control plane and genuine HTTP forwarding, not Cloudflare edge/DNS/TLS.
-  process.stdout.write(`VOLTER_SHARE_URL=${server.url}\n`);
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createTunnelTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {}) });
+  process.stdout.write(`tunnel twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
   await keepProcessAlive();
-} else if (command === 'conformance') {
-  // Dev-only and lazy: the runtime entrypoint does not pull conformance into normal serve/share.
-  const { checkTunnelConformance } = await import('./tunnel-conformance.ts');
-  const report = await checkTunnelConformance({ ...(root ? { root } : {}) });
-  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  if (!report.ok) process.exitCode = 1;
 } else {
-  process.stdout.write('Usage: world-tunnel serve|conformance [--port N] [--root DIR] [--read-only] [--require-tid]\n');
-  process.stdout.write('       world-tunnel quick --url http://127.0.0.1:<port> [--port N] [--root DIR]\n');
+  process.stdout.write('Usage: world-tunnel serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]\n');
 }

package/src/fetch.ts

@@ -0,0 +1,20 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { around } from './semantics/around.ts';
+import * as sockets from './semantics/sockets.ts';
+import * as doors from './semantics/doors.ts';
+import { tunnelSemantics } from './semantics/index.ts';
+
+export function createTunnelFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as DerivedSurface,
+    handlers: tunnelSemantics,
+    doors,
+    around,
+    sockets,
+  }, options);
+}

package/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.json","format":"openapi","version":"2","resources":[],"operations":[{"id":"getStatus","method":"get","path":"/api/status","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"}]}

package/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"_account":{"actions":[],"states":{},"embeds":{}},"_tunnel":{"actions":[],"states":{},"embeds":{}}}}

package/src/index.ts

@@ -1,53 +1,10 @@
-export { createTunnelTwinFetch, createTunnelTwinHandler, createTunnelTwinServer } from './tunnel-server.ts';
-export { handleTunnelRelayMessage, handleTunnelTwinRequest } from './tunnel-twin.ts';
-export { liveTunnelExecute, mapTunnelRelay, pullTunnelRelay, syncTunnelFromReal } from './tunnel-connector.ts';
-export {
-  TunnelBudget, TunnelBudgetError, TUNNEL_RATE_BUDGET, TUNNEL_BUDGET_CEILING,
-  TUNNEL_BUDGET_WINDOW_MS, TUNNEL_CALL_WEIGHTS,
-} from './tunnel-budget.ts';
-export type { RelayControlMessage, RelaySession, TunnelRequest, TunnelResponse } from './tunnel-twin.ts';
+// @volter/twin-tunnel — the tunnel twin (Protocol 3). A fixed file: the descriptor is the manifest's.
+import { packOf, registerPack } from '@volter/world-core';
+import { manifest } from './manifest.ts';
 
-// Registry descriptor (#1): the pack self-describes so tooling can discover it.
-// A consumer does `registerPack(pack)` after importing this package.
-import type { TwinPack } from '@volter/world-core';
-import { TUNNEL_RATE_BUDGET as RATE_BUDGET } from './tunnel-budget.ts';
-export const pack: TwinPack = {
-  vendor: 'tunnel',
-  // The SAME object tunnel-budget.ts declares at module load — one source of truth, so
-  // registering the pack and importing the connector can never arm two different ceilings.
-  rateBudget: RATE_BUDGET,
-  // The CONTROL plane is HTTP/REST (POST /tunnel, GET /api/status). The relay's control link is a
-  // WebSocket and its data path is real loopback HTTP — neither is a raw line protocol, so this is
-  // not the `raw-tcp` class; the split is described in the README and spec-sources.json.
-  transport: 'rest',
-  archetype: 'proxy',
-  bin: 'world-tunnel',
-  // The subject types the twin stores: `quick_tunnel`/`relay_tunnel` written by tunnel-twin.ts,
-  // and `relay` folded by the connector's status pull (mapTunnelRelay).
-  resources: ['quick_tunnel', 'relay_tunnel', 'relay'],
-  specSource:
-    'No single first-party machine-readable spec spans this combined pack. The Cloudflare Quick Tunnel ' +
-    'half is pinned to first-party cloudflared commit 733bfb939963e150dcf5c4faddb1603f744fbc98 (POST ' +
-    '/tunnel and its {success,result,errors} envelope) plus Cloudflare\'s own Quick Tunnels docs; the ' +
-    'owned Volter relay half is pinned to volter-ai/volter-tunnel commit ' +
-    'a5abc6287384429d32cde200d8ecd042814e6619 (@volter/tunnel 2.0.5, @volter/tunnel-core\'s 15 control ' +
-    'frames). See spec-sources.json.',
-  description:
-    'Cloudflare Quick Tunnel control-plane and owned Volter relay twin — POST /tunnel allocation and the ' +
-    '@volter/tunnel WebSocket control protocol, with a genuine loopback HTTP data path (no Cloudflare ' +
-    'edge, DNS, TLS or SLA claimed).',
-  // INTERCEPTION RULING — hostsNone, the pack's own home for it: no injector entry by design:
-  // native cloudflared is an external binary, while @volter/tunnel opens a configurable
-  // WebSocket control channel and the CLI reads TUNNEL_SERVER_URL. Worlds wire that app-read
-  // endpoint directly; claiming api.trycloudflare.com in the Node injector would not redirect
-  // cloudflared and would falsely imply the Cloudflare edge data plane was twinned.
-  hostsNone:
-    "no injector entry by design: native cloudflared is an external binary, while @volter/tunnel opens a configurable WebSocket control channel and the CLI reads TUNNEL_SERVER_URL. Worlds wire that app-read endpoint directly; claiming api.trycloudflare.com in the Node injector would not redirect cloudflared and would falsely imply the Cloudflare edge data plane was twinned",
-  // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
-  // 2026-08-31).
-  adoption: {
-    // Internal Volter tunnel; the client is `@volter/tunnel` and there is no Python distribution.
-    pypi: [],
-    sdks: ['@volter/tunnel'], envStems: ['TUNNEL', 'VOLTERTUNNEL'],
-  },
-};
+export { createTunnelFetch } from './fetch.ts';
+export { createTunnelTwinServer } from './server.ts';
+export { manifest };
+
+// The descriptor: twin-world's architecture, "The descriptor"; declared in manifest.ts.
+export const pack = registerPack(packOf(manifest));