@lapxo/head 0.2.0 → 0.2.1

package/dist/src/ports/adapters/mcp.d.ts

@@ -0,0 +1,59 @@
+export interface Tool {
+    readonly name: string;
+    readonly inputSchema: {
+        readonly type: 'object';
+    };
+    readonly annotations?: {
+        readonly readOnlyHint?: boolean;
+    };
+    readonly [key: string]: unknown;
+}
+export interface Options {
+    readonly signal: AbortSignal;
+    readonly timeout: number;
+}
+export interface ClientPort {
+    readonly list: (after: string | undefined, options: Options) => Promise<{
+        tools: Tool[];
+        next?: string;
+    }>;
+    readonly callTool: (params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }, options: Options) => Promise<unknown>;
+    readonly close: () => Promise<void>;
+}
+export interface Limits {
+    readonly pages: number;
+    readonly tools: number;
+    readonly bytes: number;
+    readonly milliseconds: number;
+}
+export declare const fingerprint: (tools: readonly Tool[]) => {
+    tools: readonly Tool[];
+    bytes: Buffer<ArrayBuffer>;
+    digest: string;
+};
+/** The host supplies an already permitted transport. Discovery observes a catalogue; hints never authorize a call. */
+export declare function withCatalogue<T>(connect: (options: Options) => Promise<ClientPort>, limits: Limits, signal: AbortSignal | undefined, use: (session: {
+    readonly read: () => Promise<ReturnType<typeof fingerprint>>;
+    readonly call: (pin: string, tool: string, args: Record<string, unknown>, authorize: () => Promise<boolean>) => Promise<unknown>;
+}) => Promise<T>): Promise<T>;
+export interface ConfiguredSource {
+    readonly protocol: 'head-configured-mcp@1';
+    readonly name: string;
+    readonly endpoint: string;
+    readonly catalogue: string;
+    readonly offers: readonly string[];
+}
+export type PermittedFetch = (url: string, init: RequestInit) => Promise<Response>;
+export type RemoteFactory = (endpoint: string, send: PermittedFetch, options: Options) => Promise<ClientPort>;
+/** Public configuration contains no execution, environment, headers or credentials. A URL never supplies a network capability. */
+export declare function configuredSource(value: unknown): ConfiguredSource;
+/** The host grants every connection, including DNS/address policy and receiver-only credentials, through its fetch capability. */
+export declare function withConfiguredSource<T>(configuration: ConfiguredSource, factory: RemoteFactory, permitted: PermittedFetch | undefined, limits: Limits & {
+    readonly wireBytes: number;
+}, signal: AbortSignal | undefined, use: (call: (tool: string, args: Record<string, unknown>, authorize: () => Promise<boolean>) => Promise<unknown>) => Promise<T>): Promise<T>;
+/** One bounded SDK session; redirects and ambient credentials are never inherited. */
+export declare function transportFor(endpoint: string, permitted: PermittedFetch, wireBytes: number, options: Options): PermittedFetch;
+export { remoteFactory } from './protocol.ts';

package/dist/src/ports/adapters/mcp.js

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+export const fingerprint = (tools) => {
+    const stable = (value) => Array.isArray(value) ? value.map(stable) : value !== null && typeof value === 'object'
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, child]) => [key, stable(child)])) : value;
+    const bytes = Buffer.from(JSON.stringify(stable([...tools].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0))));
+    return { tools, bytes, digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}` };
+};
+/** The host supplies an already permitted transport. Discovery observes a catalogue; hints never authorize a call. */
+export async function withCatalogue(connect, limits, signal, use) {
+    if (Object.values(limits).some(value => !Number.isSafeInteger(value) || value < 1))
+        throw Error('mcp/budget');
+    let client;
+    const stop = AbortSignal.any([AbortSignal.timeout(limits.milliseconds), ...(signal ? [signal] : [])]);
+    const close = () => { void client?.close().catch(() => { }); };
+    stop.addEventListener('abort', close, { once: true });
+    const options = { signal: stop, timeout: limits.milliseconds };
+    try {
+        stop.throwIfAborted();
+        client = await connect(options);
+        const connected = client;
+        const read = async () => {
+            const tools = [], names = new Set(), pages = new Set();
+            let after, size = 0;
+            for (let page = 0; page < limits.pages; page++) {
+                stop.throwIfAborted();
+                const result = await connected.list(after, options);
+                size += Buffer.byteLength(JSON.stringify(result));
+                if (size > limits.bytes || tools.length + result.tools.length > limits.tools)
+                    throw Error('mcp/budget');
+                for (const tool of result.tools) {
+                    if (names.has(tool.name))
+                        throw Error('mcp/collision');
+                    names.add(tool.name);
+                    tools.push(tool);
+                }
+                after = result.next;
+                if (after === undefined)
+                    return fingerprint(tools);
+                if (!after || pages.has(after))
+                    throw Error('mcp/page-loop');
+                pages.add(after);
+            }
+            throw Error('mcp/budget');
+        };
+        return await use({ read, call: async (pin, tool, args, authorize) => {
+                const current = await read();
+                if (current.digest !== pin)
+                    throw Error('mcp/catalogue-changed');
+                if (!current.tools.some(entry => entry.name === tool))
+                    throw Error('mcp/tool');
+                if (!await authorize())
+                    throw Error('mcp/not-authorized');
+                if ((await read()).digest !== pin)
+                    throw Error('mcp/catalogue-changed');
+                stop.throwIfAborted();
+                return connected.callTool({ name: tool, arguments: args }, options);
+            } });
+    }
+    finally {
+        stop.removeEventListener('abort', close);
+        await client?.close();
+    }
+}
+/** Public configuration contains no execution, environment, headers or credentials. A URL never supplies a network capability. */
+export function configuredSource(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw Error('mcp/configuration');
+    const one = value;
+    if (Object.keys(one).sort().join('|') !== 'catalogue|endpoint|name|offers|protocol' || one['protocol'] !== 'head-configured-mcp@1'
+        || typeof one['name'] !== 'string' || !/^[a-z][a-z0-9-]*$/.test(one['name']) || typeof one['catalogue'] !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(one['catalogue'])
+        || typeof one['endpoint'] !== 'string' || !URL.canParse(one['endpoint']) || !Array.isArray(one['offers']) || !one['offers'].length || one['offers'].some(n => typeof n !== 'string' || !n.trim()) || new Set(one['offers']).size !== one['offers'].length)
+        throw Error('mcp/configuration');
+    const url = new URL(one['endpoint']);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.href !== one['endpoint'])
+        throw Error('mcp/endpoint');
+    return { protocol: 'head-configured-mcp@1', name: one['name'], endpoint: url.href, catalogue: one['catalogue'], offers: [...one['offers']] };
+}
+/** The host grants every connection, including DNS/address policy and receiver-only credentials, through its fetch capability. */
+export async function withConfiguredSource(configuration, factory, permitted, limits, signal, use) {
+    const source = configuredSource(configuration);
+    if (!permitted)
+        throw Error('mcp/network-unavailable');
+    if (!Number.isSafeInteger(limits.wireBytes) || limits.wireBytes < 1)
+        throw Error('mcp/budget');
+    if (source.offers.length > limits.tools || Buffer.byteLength(JSON.stringify(source)) > limits.bytes)
+        throw Error('mcp/budget');
+    return withCatalogue(options => factory(source.endpoint, transportFor(source.endpoint, permitted, limits.wireBytes, options), options), limits, signal, async (session) => {
+        const current = await session.read();
+        if (current.digest !== source.catalogue || source.offers.some(name => !current.tools.some(tool => tool.name === name)))
+            throw Error('mcp/catalogue-changed');
+        return use((tool, args, authorize) => {
+            if (!source.offers.includes(tool))
+                return Promise.reject(Error('mcp/tool'));
+            return session.call(source.catalogue, tool, args, authorize);
+        });
+    });
+}
+/** One bounded SDK session; redirects and ambient credentials are never inherited. */
+export function transportFor(endpoint, permitted, wireBytes, options) {
+    if (!Number.isSafeInteger(wireBytes) || wireBytes < 1)
+        throw Error('mcp/budget');
+    let bytes = 0;
+    return async (url, init) => {
+        if (url !== endpoint || !['GET', 'POST', 'DELETE'].includes(init.method ?? 'GET'))
+            throw Error('mcp/endpoint');
+        options.signal.throwIfAborted();
+        const got = await permitted(url, { ...init, redirect: 'manual', credentials: 'omit', signal: options.signal });
+        if (got.status >= 300 && got.status < 400) {
+            await got.body?.cancel();
+            throw Error('mcp/redirect');
+        }
+        const body = got.body?.pipeThrough(new TransformStream({ transform(chunk, controller) {
+                options.signal.throwIfAborted();
+                bytes += chunk.byteLength;
+                if (bytes > wireBytes)
+                    throw Error('mcp/budget');
+                controller.enqueue(chunk);
+            } }));
+        return new Response(body ?? null, { status: got.status, statusText: got.statusText, headers: got.headers });
+    };
+}
+export { remoteFactory } from "./protocol.js";

package/dist/src/ports/adapters/network.d.ts

@@ -0,0 +1,12 @@
+import { lookup } from 'node:dns/promises';
+import type { PermittedFetch } from './mcp.ts';
+export interface NetworkPolicy {
+    readonly internal?: readonly {
+        readonly hostname: string;
+        readonly address: string;
+    }[];
+    readonly ca?: string;
+}
+export declare const publicAddress: (address: string) => boolean;
+/** Receiver-owned transport: payloads cannot supply DNS policy, private bindings, trust roots or credentials. */
+export declare function networkFor(endpoint: string, policy?: NetworkPolicy, resolve?: typeof lookup): PermittedFetch;

package/dist/src/ports/adapters/network.js

@@ -0,0 +1,67 @@
+import { lookup } from 'node:dns/promises';
+import { BlockList, isIP } from 'node:net';
+import { request } from 'node:https';
+import { Readable } from 'node:stream';
+const excluded = new BlockList();
+for (const [net, bits] of [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4]])
+    excluded.addSubnet(net, bits);
+for (const [net, bits] of [['2001::', 23], ['2001:db8::', 32], ['2002::', 16], ['3fff::', 20]])
+    excluded.addSubnet(net, bits, 'ipv6');
+const global = new BlockList();
+global.addSubnet('2000::', 3, 'ipv6');
+export const publicAddress = (address) => isIP(address) === 4 ? !excluded.check(address) : isIP(address) === 6 && global.check(address, 'ipv6') && !excluded.check(address, 'ipv6');
+/** Receiver-owned transport: payloads cannot supply DNS policy, private bindings, trust roots or credentials. */
+export function networkFor(endpoint, policy = {}, resolve = lookup) {
+    const target = new URL(endpoint);
+    if (target.protocol !== 'https:' || target.username || target.password || target.search || target.hash || target.href !== endpoint)
+        throw Error('mcp/endpoint');
+    return async (url, init) => {
+        if (url !== endpoint || !['GET', 'POST', 'DELETE'].includes(init.method ?? 'GET') || init.redirect !== 'manual' || init.credentials !== 'omit' || !init.signal)
+            throw Error('mcp/network-policy');
+        const signal = init.signal;
+        signal.throwIfAborted();
+        const host = target.hostname.replace(/^\[|\]$/g, '');
+        let abort;
+        const stopped = new Promise((_, reject) => { abort = () => reject(Error('mcp/cancelled')); signal.addEventListener('abort', abort, { once: true }); });
+        let addresses;
+        try {
+            addresses = await Promise.race([resolve(host, { all: true, verbatim: true }), stopped]);
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+        }
+        signal.throwIfAborted();
+        if (!addresses.length || addresses.some(({ address }) => !publicAddress(address) && !policy.internal?.some(one => one.hostname === host && one.address === address)))
+            throw Error('mcp/destination');
+        const chosen = addresses[0];
+        const headers = Object.fromEntries(new Headers(init.headers));
+        if (Object.keys(headers).some(k => ['host', 'connection', 'transfer-encoding', 'content-length', 'proxy-authorization', 'cookie'].includes(k)) || Buffer.byteLength(JSON.stringify(headers)) > 16384)
+            throw Error('mcp/headers');
+        const body = init.body;
+        if (body !== undefined && body !== null && typeof body !== 'string' && !(body instanceof Uint8Array))
+            throw Error('mcp/request-body');
+        if (body && Buffer.byteLength(body) > 16777216)
+            throw Error('mcp/request-budget');
+        return new Promise((resolveResponse, reject) => {
+            const req = request(target, { method: init.method, headers, agent: false, signal, rejectUnauthorized: true, maxHeaderSize: 16384, ...(policy.ca ? { ca: policy.ca } : {}), family: chosen.family,
+                lookup: (_hostname, options, done) => options.all ? done(null, [chosen]) : done(null, chosen.address, chosen.family) }, response => {
+                const responseHeaders = new Headers();
+                for (const [name, value] of Object.entries(response.headers))
+                    if (value !== undefined)
+                        for (const item of Array.isArray(value) ? value : [value])
+                            responseHeaders.append(name, item);
+                const status = response.statusCode ?? 500;
+                if ([204, 205, 304].includes(status)) {
+                    response.resume();
+                    resolveResponse(new Response(null, { status, headers: responseHeaders }));
+                }
+                else
+                    resolveResponse(new Response(Readable.toWeb(response), { status, headers: responseHeaders }));
+            });
+            req.on('error', () => reject(Error(signal.aborted ? 'mcp/cancelled' : 'mcp/transport')));
+            if (body)
+                req.write(body);
+            req.end();
+        });
+    };
+}

package/dist/src/ports/adapters/protocol.d.ts

@@ -0,0 +1,6 @@
+import { type Said } from '../../core/lock.ts';
+import type { RemoteFactory } from './mcp.ts';
+/** Incoming and outgoing SDK bindings; application decisions stay behind the existing ports. */
+export declare function serve(lock: readonly Said[], root: string, ext: string, doorName: string): Promise<void>;
+/** Concrete outgoing SDK transport. Every network operation still goes through the separately permitted host capability. */
+export declare const remoteFactory: RemoteFactory;

package/dist/src/ports/adapters/protocol.js

@@ -0,0 +1,51 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Client as RemoteClient } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { aboutOf, valueOf } from "../../core/lock.js";
+import { fill } from "../../core/surface.js";
+import { shapeOf, shapeSchema } from "../surface.js";
+import { folderOf } from "../place.js";
+import { askedOf, headOf } from "../../doors/head.js";
+/** Incoming and outgoing SDK bindings; application decisions stay behind the existing ports. */
+export async function serve(lock, root, ext, doorName) {
+    const offered = (n) => (n ? { listChanged: false } : undefined);
+    const head = headOf(lock, root, ext, {
+        can: () => ((e) => ({ url: Boolean(e?.url), form: e !== undefined && (e.form !== undefined || Object.keys(e).length === 0) }))(server.getClientCapabilities()?.elicitation), elicit: (params) => server.elicitInput(params, { timeout: Number(valueOf(lock, 'access/wait').split('..')[1]) }),
+        roots: async () => (server.getClientCapabilities()?.roots ? (await server.listRoots()).roots.flatMap((root) => folderOf(root.uri) ?? []) : []), client: () => ((c) => (c ? `${c.name}@${c.version}` : undefined))(server.getClientVersion()), name: doorName,
+    }), surface = head.surface;
+    const server = new Server({ name: surface.name, version: surface.version }, { capabilities: { tools: offered(surface.tools.length), resources: offered(surface.resources.length), prompts: offered(surface.prompts.length) }, instructions: aboutOf(lock, 'prose/en/instructions') });
+    const schemaOf = (fields) => ({ type: 'object',
+        properties: Object.fromEntries(fields.map((f) => [f.name, { type: f.type, description: f.about }])), required: fields.filter((f) => f.required).map((f) => f.name) });
+    if (surface.tools.length)
+        server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: surface.tools.map((tool) => ({ name: tool.name, description: tool.about,
+                inputSchema: schemaOf([...tool.fields]), outputSchema: shapeSchema(lock), annotations: Object.fromEntries(tool.hints.map((hint) => [`${hint}Hint`, true])) })) }));
+    if (surface.tools.length)
+        server.setRequestHandler(CallToolRequestSchema, async (request, extra) => ((answer) => (answer === undefined ? { isError: true, content: [] } : { content: [{ type: 'text', text: answer.join('\n') }], structuredContent: shapeOf(answer) }))(await head.call(request.params.name, request.params.arguments, extra.signal)));
+    if (surface.resources.length)
+        server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
+    if (surface.resources.length)
+        server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({ resourceTemplates: surface.resources.map((r) => ({ name: r.name, uriTemplate: r.template, description: r.about, mimeType: r.mime })) }));
+    if (surface.resources.length)
+        server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => ((got) => ({ contents: got === undefined ? [] : [{ uri: request.params.uri, mimeType: got.mime, text: got.lines.join('\n') }] }))(await head.resource(request.params.uri, extra.signal)));
+    if (surface.prompts.length)
+        server.setRequestHandler(ListPromptsRequestSchema, () => ({ prompts: surface.prompts.map((p) => ({ name: p.name, description: p.about, arguments: p.fields.map((f) => ({ name: f.name, description: f.about, required: f.required })) })) }));
+    if (surface.prompts.length)
+        server.setRequestHandler(GetPromptRequestSchema, (request) => ((p) => ({ messages: p === undefined ? [] : [{ role: 'user', content: { type: 'text', text: [p.text, p.line].filter(Boolean).map((t) => fill(t, askedOf(request.params.arguments))).join('\n') } }] }))(surface.prompts.find((one) => one.name === request.params.name)));
+    await server.connect(new StdioServerTransport());
+}
+/** Concrete outgoing SDK transport. Every network operation still goes through the separately permitted host capability. */
+export const remoteFactory = async (endpoint, send, options) => {
+    const client = new RemoteClient({ name: 'head', version: '0' });
+    const transport = new StreamableHTTPClientTransport(new URL(endpoint), { fetch: (input, init) => send(String(input), init ?? {}), reconnectionOptions: { maxRetries: 0, maxReconnectionDelay: 0, initialReconnectionDelay: 0, reconnectionDelayGrowFactor: 1 } });
+    try {
+        await client.connect(transport, options);
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+    return { list: async (after, opts) => { const got = await client.listTools(after ? { cursor: after } : {}, opts); return { tools: got.tools, ...(got.nextCursor ? { next: got.nextCursor } : {}) }; },
+        callTool: (params, opts) => client.callTool(params, undefined, opts), close: () => client.close() };
+};

package/dist/src/ports/adapters/remote.d.ts

@@ -0,0 +1,13 @@
+import { type ConfiguredSource, type Limits, type PermittedFetch } from './mcp.ts';
+import type { Prepared } from './request.ts';
+export interface RemotePort {
+    readonly discover: (endpoint: string) => Promise<{
+        readonly tools: readonly import('./mcp.ts').Tool[];
+        readonly digest: string;
+    }>;
+    readonly prepare: (source: ConfiguredSource, tool: string, args: Record<string, unknown>, authorize: () => Promise<boolean>) => Prepared;
+}
+/** This port owns no permission. Callers bind the receiver's consent and existing access flow; SDK hints grant nothing. */
+export declare function remoteAt(limits: Limits & {
+    readonly wireBytes: number;
+}, signal?: AbortSignal, network?: (endpoint: string) => PermittedFetch): RemotePort;

package/dist/src/ports/adapters/remote.js

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto';
+import { transportFor, withCatalogue, withConfiguredSource, remoteFactory } from "./mcp.js";
+import { networkFor } from "./network.js";
+/** This port owns no permission. Callers bind the receiver's consent and existing access flow; SDK hints grant nothing. */
+export function remoteAt(limits, signal, network = networkFor) {
+    return {
+        discover: endpoint => withCatalogue(options => remoteFactory(endpoint, transportFor(endpoint, network(endpoint), limits.wireBytes, options), options), limits, signal, session => session.read()),
+        prepare: (source, tool, args, authorize) => {
+            if (!source.offers.includes(tool))
+                return { refused: 'mcp-tool' };
+            const sentArgs = JSON.parse(JSON.stringify(args));
+            const key = createHash('sha256').update(JSON.stringify([source.endpoint, source.catalogue, tool, sentArgs])).digest('hex');
+            return { key, describe: `${source.endpoint} · ${tool} · sha256:${key}`, send: async (attachment, most) => {
+                    if (!Number.isSafeInteger(most) || most < 1 || Object.keys(attachment?.query ?? {}).length)
+                        return { kind: 'failed', why: 'mcp/access-location' };
+                    try {
+                        const permitted = network(source.endpoint);
+                        const result = await withConfiguredSource(source, remoteFactory, (url, init) => {
+                            const headers = new Headers(init.headers);
+                            for (const [key, value] of Object.entries(attachment?.headers ?? {}))
+                                headers.set(key, value);
+                            return permitted(url, { ...init, headers });
+                        }, limits, signal, call => call(tool, sentArgs, authorize));
+                        const bytes = Buffer.from(JSON.stringify(result));
+                        return bytes.length > most ? { kind: 'over' } : { kind: 'got', status: 200, bytes, type: 'application/json' };
+                    }
+                    catch (error) {
+                        return { kind: 'failed', why: error instanceof Error && /^mcp\/[a-z-]+$/.test(error.message) ? error.message : 'mcp/transport' };
+                    }
+                } };
+        },
+    };
+}

package/dist/src/sources/connect.d.ts

@@ -17,5 +17,6 @@ type Connection = {
     readonly connected: boolean;
 };
 type Laid = (source: string, document: string, doc: Read, overlay: Read | undefined, started: number) => Promise<Connection>;
+export declare const received: (context: Context, place: string, document: string, bytes: Uint8Array, named: string, laid: Laid, account: string, publicFiles?: ReadonlyMap<string, Uint8Array | undefined>) => Promise<readonly string[]>;
 export declare const laidIn: (context: Context, place: string, account: string) => Laid;
 export {};

package/dist/src/sources/connect.js

@@ -1,3 +1,5 @@
+import { discoverConfigured, configuredRefusal, configuredProtocol } from "../ports/adapters/configured.js";
+import { receiverConnect } from "../core/receiver.js";
 import { canonical, EXTENSION } from '@lapxo/topos/wire';
 import { inPlace, placeOf, unless } from "../core/answer.js";
 import { members, valueOf } from "../core/lock.js";
@@ -24,8 +26,8 @@ import { attachedFor } from "./access.js";
  * its pins rest in, its pin held to the package's; one that differs is refused by name, and the place holds what it
  * compiled. Nothing the sharing place was granted comes with it: access is asked here, issuer by issuer.
  */
-export const connected = async (asked, context, covered = false) => (await receivedBirth(asked, context)) ?? (members(valueOf(context.lock, 'link/prefixes')).some(prefix => (asked['document'] ?? '').startsWith(prefix)) ? linked(asked, context)
-    : ((got) => ('said' in got ? got.said : connectedAs(got.asked, context, covered)))(await resolved(asked, context)));
+export const connected = async (asked, context, covered = false) => (await receiverConnect(asked, context)) ?? (await receivedBirth(asked, context)) ?? (members(valueOf(context.lock, 'link/prefixes')).some(prefix => (asked['document'] ?? '').startsWith(prefix)) ? linked(asked, context)
+    : ((got) => ('said' in got ? got.said : connectedAs(got.asked, context, covered)))(asked['protocol'] === configuredProtocol.id ? { asked } : await resolved(asked, context)));
 const connectedAs = async (asked, context, covered = false) => (asked['source'] && !(await placeOf(asked, context)) ? firstRun(asked, context, (dir, covered) => connected({ ...asked, place: dir }, context, covered))
     : ((started) => inPlace(asked, context, async (place) => {
         const say = sayIn(context.lock), digest = digestIn(context.lock), { documentOf, fetchedAs, kindOf } = context.files.read;
@@ -35,7 +37,7 @@ const connectedAs = async (asked, context, covered = false) => (asked['source']
             return [say('parent-lock', { place, parent: source || document })];
         if (!source && !lock)
             return [say('missing-param', { operation: 'connect', param: 'source' })];
-        const root = rootIn(context, place);
+        const root = await rootIn(context, place);
         if ('said' in root)
             return root.said;
         if (named && !/^sha256:[0-9a-f]{64}$/.test(named))
@@ -49,7 +51,7 @@ const connectedAs = async (asked, context, covered = false) => (asked['source']
         const got = via ? await attachedFor(context, place, via) : undefined;
         if (got && 'said' in got)
             return got.said;
-        const [read, overlay] = [got ? await fetchedAs(context, document, via, got, named, accept) : await documentOf(context, place, document, named), asked['overlay'] ? await documentOf(context, place, asked['overlay']) : undefined];
+        const [read, overlay] = [asked['protocol'] === configuredProtocol.id ? await discoverConfigured(context, asked, source) : got ? await fetchedAs(context, document, via, got, named, accept) : await documentOf(context, place, document, named), asked['overlay'] ? await documentOf(context, place, asked['overlay']) : undefined];
         if (read !== undefined && 'said' in read)
             return read.said;
         if (read === undefined || (asked['overlay'] && overlay === undefined))
@@ -57,13 +59,14 @@ const connectedAs = async (asked, context, covered = false) => (asked['source']
         if (named && digest(read.bytes) !== named)
             return [say('document-digest', { document, digest: named, got: digest(read.bytes) })];
         return `.${read.kind}` === EXTENSION ? [say('parent-lock', { place, parent: source })] : (await laidIn(context, place, root.account)(source, document, read, overlay, started)).said;
-    }))(context.machine()));
-const received = async (context, place, document, bytes, named, laid, account) => {
-    const [say, got] = [sayIn(context.lock), unpacked(context, document, bytes, await context.files.read.besideOf(context, document, linesOf(bytes)))];
+    }))(context.machine())).catch(error => { if (asked['protocol'] === configuredProtocol.id || error instanceof Error && error.message.startsWith(configuredProtocol.failurePrefix))
+    return configuredRefusal(context, error); throw error; });
+export const received = async (context, place, document, bytes, named, laid, account, publicFiles) => {
+    const [say, got] = [sayIn(context.lock), unpacked(context, document, bytes, publicFiles ?? await context.files.read.besideOf(context, document, linesOf(bytes)))];
     if (!got.sources)
         return got.said ?? [];
     const [names, said, before] = [got.sources.map((s) => s.source).join(', '), [], await context.policy(place)];
-    const refused = coveredIn(context, 'refused' in before ? [] : before.lines, got.sources, named) ? undefined : await unless(context, say('elicit-receive', { place, package: named, sources: names || '—', open: (got.open ?? []).map((o) => o.source).join(', ') || '—' }));
+    const refused = publicFiles || coveredIn(context, 'refused' in before ? [] : before.lines, got.sources, named) ? undefined : await unless(context, say('elicit-receive', { place, package: named, sources: names || '—', open: (got.open ?? []).map((o) => o.source).join(', ') || '—' }));
     if (refused)
         return refused;
     for (const s of got.sources)
@@ -77,8 +80,8 @@ export const laidIn = (context, place, account) => (source, document, doc, overl
     const say = sayIn(context.lock), v = vocabOf(context.lock), word = (k) => valueOf(context.lock, k), digest = digestIn(context.lock);
     const lands = (lot) => context.landRoot(place, lot, account);
     const line = (scope, measure, value, more = {}) => canonical({ at: 'policy:head/connect', by: 'target', form: 'alphabet', measure, role: 'writes', scope, value, ...more });
-    const pin = pinIn(context, place, lands, line);
-    const worlds = await adopted(context, place, lands, line);
+    const configured = configuredProtocol.connection(doc.bytes, source, overlay !== undefined, v);
+    const [pin, worlds] = [pinIn(context, place, lands, line, configured?.verify), await adopted(context, place, lands, line, configured?.worlds ?? [])];
     if ('refused' in worlds)
         return { said: [say('not-landed', { why: worlds.refused })], connected: false };
     const laid = [[`${word('place/connected')}/${source}.${doc.kind}`, doc.bytes], ...(overlay ? [[`${word('place/connected')}/${source}.overlay.${overlay.kind}`, overlay.bytes]] : [])];

package/dist/src/verbs/ask.js

@@ -1,3 +1,4 @@
+import { receiverQuestion } from "../core/receiver.js";
 import { join } from 'node:path';
 import { LOCK } from '@lapxo/topos/wire';
 import { answerOf, placeOf } from "../core/answer.js";
@@ -10,6 +11,11 @@ import { viewed } from "../claims/view.js";
 import { cardAt } from "./card.js";
 /** Route a question at the declared resolution, then attach the card of the place it read. */
 export const asked = async (asked, context) => {
+    const packaged = await receiverQuestion(asked, context);
+    if (packaged && 'said' in packaged)
+        return packaged.said;
+    if (packaged)
+        asked = { ...asked, place: packaged.place };
     const why = asked['why'] === 'true', at = (form) => ((v) => (v && v !== valueOf(context.lock, 'resolution/own') ? v : undefined))(valueOf(context.lock, `resolution/${form}/${why ? 'why' : 'person'}`));
     const read = async (form, tool, more = {}) => [...(why && at(form) === undefined ? [sayIn(context.lock)('why-undeclared', { form })] : []),
         ...await (await answerOf('tools', tool))({ ...asked, ...more, at: at(form) }, context)];

package/dist/src/verbs/do.js

@@ -2,6 +2,7 @@ import { answerOf, placeOf } from "../core/answer.js";
 import { members, valueOf } from "../core/lock.js";
 import { sayIn } from "../core/surface.js";
 import { cardAt } from "./card.js";
+import { LOCK } from '@lapxo/topos/wire';
 /**
  * What a person does, carried out by the action it names and only on the card it was asked on: an act on a place that
  * moved since is refused before anything is done. An action the place does not allow is said not to be in the card, by
@@ -16,7 +17,7 @@ export const done = async (asked, context) => {
     const place = asked['place'] || asked['dir'] || await placeOf(asked, context), held = await cardAt(context, place);
     if ('said' in held)
         return held.said;
-    if (held.card !== asked['card'])
+    if (held.card !== asked['card'] && !(action === 'place' && place !== undefined && !context.files.has(place, LOCK) && !context.files.has(place, '.bound')))
         return [say('card-stale', { action, place: place ?? '', card: asked['card'] ?? '' })];
     const answer = await (await answerOf('tools', action))(asked, context);
     const [bound, own] = [members(word('do/not-in-card/bound')), members(word('do/not-in-card/head'))];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lapxo/head",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "An MCP server that folds: it runs bound as a process, hands a model what bound printed, and lands what it read as receipts.",
   "license": "MIT",
@@ -18,7 +18,8 @@
   "files": [
     "dist/src",
     "TARGET.bound",
-    "LICENSE"
+    "LICENSE",
+    "runtime.bundle.json"
   ],
   "scripts": {
     "build": "tsc -p . --incremental false --tsBuildInfoFile null",
@@ -28,10 +29,10 @@
   "dependencies": {
     "@lapxo/bound": "0.2.8",
     "@lapxo/topos": "0.2.4",
-    "@modelcontextprotocol/sdk": "1.32.1"
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@anthropic-ai/mcpb": "2.1.2"
   },
   "devDependencies": {
-    "@anthropic-ai/mcpb": "2.1.2",
     "@types/node": "22.20.5",
     "typescript": "5.9.3"
   }