@lapxo/head 0.1.7 → 0.2.1

package/dist/src/places/admit.js

@@ -15,7 +15,7 @@ export const admitted = (asked, context) => inPlace(asked, context, async (place
     const key = (asked['key'] ?? '').split('\n').map((line) => parse(line.trim())).flatMap((got) => (got.kind === 'fact' && got.value.fields['measure'] === 'public-key' ? [got.value.fields['value'] ?? ''] : []))[0];
     if (!name || !key)
         return [say('no-key')];
-    const [root, held] = [rootIn(context, place), await standingOr(context, place, context.policy)];
+    const [root, held] = [await rootIn(context, place), await standingOr(context, place, context.policy)];
     if ('said' in root)
         return root.said;
     if ('said' in held)

package/dist/src/places/found.js

@@ -14,6 +14,8 @@ const birthOf = (lock, root, head, person, place, mine = `${valueOf(lock, 'found
 ];
 /** A place founded in a folder: a root key made in the keychain under the place's name — never a file — the birth lines written, and the first land signed by that root. */
 const founded = async (context, dir, name) => {
+    if (context.files.has(dir, LOCK) || context.files.has(dir, '.bound'))
+        return { refused: 'place-exists' };
     const account = fill(valueOf(context.lock, 'founding/root-account'), { place: name });
     const [head, person] = [deviceKey(context, 'head'), deviceKey(context, 'person')];
     if (head === undefined || person === undefined)
@@ -37,7 +39,7 @@ export const bornPlace = async (asked, context) => {
     if (!isAbsolute(dir))
         return [say('place-absolute')];
     const name = (asked['name'] || basename(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, '-');
-    if (context.files.has(dir, LOCK))
+    if (context.files.has(dir, LOCK) || context.files.has(dir, '.bound'))
         return [say('place-exists', { dir })];
     const refused = await unless(context, say('elicit-place', { name, dir }));
     return refused ?? bornAt(context, dir, name);

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

@@ -0,0 +1,44 @@
+import { type Recipe, type Source } from '../../core/composition.ts';
+export interface Member {
+    readonly path: string;
+    readonly bytes: number;
+    readonly digest: string;
+}
+export interface Runtime {
+    readonly protocol: 'head-runtime-closure@1';
+    readonly files: readonly Member[];
+    readonly bytes: number;
+}
+export interface BundlePort {
+    readonly runtime: Uint8Array;
+    readonly expected: string;
+    readonly take: (path: string) => Uint8Array | undefined;
+    readonly profile: Uint8Array;
+}
+export interface Payload {
+    readonly recipe: Recipe;
+    readonly sources: readonly Source[];
+    readonly files: ReadonlyMap<string, Uint8Array>;
+}
+/** Only the host's pinned public runtime closure is copied. A recipe never supplies executable paths, environment or grants. */
+export declare function bundle(port: BundlePort, payload: Payload | undefined, budget: {
+    readonly bytes: number;
+    readonly selections: number;
+    readonly milliseconds: number;
+    readonly printed: number;
+}, signal?: AbortSignal): Promise<{
+    bytes: NonSharedBuffer;
+    digest: string;
+    sources: string[];
+}>;
+/** A host provisioned closure, pinned by Head's own profile. Never discover an arbitrary node_modules tree or fetch code here. */
+export declare function bundleAt(root: string, lock: readonly import('../../core/lock.ts').Said[], payload: Payload | undefined, signal?: AbortSignal): Promise<{
+    bytes: NonSharedBuffer;
+    digest: string;
+    sources: string[];
+}>;
+/** A bounded snapshot of installed public members, never arbitrary files or symlink targets. */
+export declare function publicAt(root: string, budget: number): {
+    root: string;
+    read: (path: string) => Uint8Array | undefined;
+};

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

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, lstatSync, realpathSync, openSync, closeSync, fstatSync, readSync, constants } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { VERSIONED_MANIFEST_SCHEMAS } from '@anthropic-ai/mcpb';
+import { createRequire } from 'node:module';
+import { spawned } from "../process.js";
+import { compose } from "../../core/composition.js";
+const digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const safe = (path) => /^[A-Za-z0-9_@.+/-]+$/.test(path) && path.split('/').every(part => part !== '' && part !== '.' && part !== '..');
+/** Only the host's pinned public runtime closure is copied. A recipe never supplies executable paths, environment or grants. */
+export async function bundle(port, payload, budget, signal) {
+    signal?.throwIfAborted();
+    if (Object.values(budget).some(n => !Number.isSafeInteger(n) || n < 1))
+        throw Error('bundle/budget');
+    if (digest(port.runtime) !== port.expected)
+        throw Error('bundle/runtime-digest');
+    const runtime = JSON.parse(new TextDecoder().decode(port.runtime));
+    if (runtime.protocol !== 'head-runtime-closure@1' || !Array.isArray(runtime.files) || !runtime.files.length || !Number.isSafeInteger(runtime.bytes) || runtime.bytes < 1)
+        throw Error('bundle/runtime');
+    const files = new Map();
+    let size = 0;
+    for (const member of runtime.files) {
+        if (!safe(member.path) || !/^(dist\/src\/|node_modules\/|package\.json$|LICENSE$)/.test(member.path) || files.has(member.path))
+            throw Error('bundle/runtime-path');
+        const bytes = port.take(member.path);
+        if (!bytes || bytes.byteLength !== member.bytes || digest(bytes) !== member.digest)
+            throw Error('bundle/runtime-member');
+        files.set(member.path, bytes);
+        size += bytes.byteLength;
+    }
+    if (size !== runtime.bytes || !files.has('dist/src/index.js') || !files.has('package.json') || !files.has('LICENSE'))
+        throw Error('bundle/runtime-closure');
+    files.set('runtime.bundle.json', port.runtime).set('TARGET.bound', port.profile).set('.mcpbignore', Buffer.from('!**\n*.mts\n*changelog*\n.env*\n.git/\n.bound/\nbirth.bound\n'));
+    let manifest = { manifest_version: '0.3', name: 'head', version: JSON.parse(new TextDecoder().decode(files.get('package.json'))).version, description: 'Head without connected sources', author: { name: 'Package author' } };
+    if (payload) {
+        const made = compose(payload.recipe, payload.sources, budget.selections);
+        let publicBytes = made.bytes.byteLength;
+        for (const [path, bytes] of payload.files) {
+            if (!safe(path) || /(^|\/)(\.bound|\.git|birth\.bound|node_modules)(\/|$)/.test(path))
+                throw Error('bundle/public-path');
+            publicBytes += bytes.byteLength;
+            if (publicBytes > budget.bytes)
+                throw Error('bundle/public-budget');
+            files.set(`composition/${path}`, bytes);
+        }
+        if (!payload.files.has('TARGET.bound'))
+            throw Error('bundle/public-lock');
+        files.set('composition/selection.json', made.bytes);
+        manifest = { ...manifest, name: payload.recipe.id, version: payload.recipe.revision, display_name: payload.recipe.title, description: payload.recipe.description };
+    }
+    manifest = { ...manifest, server: { type: 'node', entry_point: 'dist/src/index.js', mcp_config: { command: 'node', args: ['${__dirname}/dist/src/index.js', 'run'] } }, compatibility: { platforms: ['darwin'], runtimes: { node: '>=22.18' } } };
+    VERSIONED_MANIFEST_SCHEMAS['0.3'].parse(manifest);
+    files.set('manifest.json', Buffer.from(JSON.stringify(manifest, null, 2) + '\n'));
+    const temporary = mkdtempSync(join(tmpdir(), 'head-export-'));
+    try {
+        const stage = join(temporary, 'package'), output = join(temporary, 'package.mcpb');
+        for (const [path, bytes] of files) {
+            signal?.throwIfAborted();
+            const at = join(stage, path);
+            mkdirSync(dirname(at), { recursive: true });
+            writeFileSync(at, bytes);
+        }
+        const cli = join(dirname(createRequire(import.meta.url).resolve('@anthropic-ai/mcpb')), 'cli/cli.js');
+        const result = await spawned(process.execPath, [cli, 'pack', stage, output], { cwd: temporary, env: { PATH: dirname(process.execPath), HOME: temporary, TMPDIR: temporary } }, { wait: budget.milliseconds, most: budget.printed, ...(signal ? { signal } : {}) });
+        if (result.code !== 0)
+            throw Error('bundle/pack');
+        signal?.throwIfAborted();
+        const bytes = readFileSync(output);
+        return { bytes, digest: digest(bytes), sources: payload?.recipe.sources.map(source => source.source) ?? [] };
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+}
+/** A host provisioned closure, pinned by Head's own profile. Never discover an arbitrary node_modules tree or fetch code here. */
+export async function bundleAt(root, lock, payload, signal) {
+    const { valueOf } = await import("../../core/lock.js");
+    const expected = valueOf(lock, 'dep/runtime-bundle');
+    if (!/^sha256:[a-f0-9]{64}$/.test(expected))
+        throw Error('bundle/runtime-unavailable');
+    const packages = new Map();
+    const take = (path) => {
+        try {
+            return readFileSync(join(root, path));
+        }
+        catch { /* Resolve only the package paths selected by the pinned inventory. */ }
+        try {
+            let rest = path, from = createRequire(join(root, 'package.json')), at = root;
+            while (rest.startsWith('node_modules/')) {
+                const parts = rest.slice(13).split('/'), count = parts[0].startsWith('@') ? 2 : 1, name = parts.slice(0, count).join('/');
+                const key = at + '\0' + name, cached = packages.get(key);
+                if (cached)
+                    at = cached;
+                else {
+                    try {
+                        at = dirname(from.resolve(name + '/package.json'));
+                    }
+                    catch {
+                        at = dirname(from.resolve(name));
+                        while (true) {
+                            try {
+                                if (JSON.parse(readFileSync(join(at, 'package.json'), 'utf8')).name === name)
+                                    break;
+                            }
+                            catch { }
+                            const parent = dirname(at);
+                            if (parent === at)
+                                throw Error('bundle/runtime-member');
+                            at = parent;
+                        }
+                    }
+                    packages.set(key, at);
+                }
+                from = createRequire(join(at, 'package.json'));
+                rest = parts.slice(count).join('/');
+            }
+            return path.startsWith('node_modules/') ? readFileSync(join(at, rest)) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return bundle({ runtime: readFileSync(join(root, 'runtime.bundle.json')), expected, take, profile: readFileSync(join(root, 'TARGET.bound')) }, payload, { bytes: Number(valueOf(lock, 'share/bundle-bytes').split('..')[1]), selections: Number(valueOf(lock, 'share/bundle-selections').split('..')[1]), milliseconds: Number(valueOf(lock, 'bound/wait').split('..')[1]), printed: Number(valueOf(lock, 'bound/printed').split('..')[1]) }, signal);
+}
+/** A bounded snapshot of installed public members, never arbitrary files or symlink targets. */
+export function publicAt(root, budget) {
+    if (!Number.isSafeInteger(budget) || budget < 1)
+        throw Error('bundle/budget');
+    const base = realpathSync(root), held = new Map();
+    let consumed = 0;
+    return { root: base, read: (path) => {
+            if (!safe(path) || !(path === 'manifest.json' || path.startsWith('composition/')))
+                throw Error('bundle/public-path');
+            if (held.has(path))
+                return held.get(path);
+            try {
+                let at = base;
+                for (const part of path.split('/')) {
+                    at = join(at, part);
+                    if (lstatSync(at).isSymbolicLink())
+                        throw Error('bundle/public-path');
+                }
+                const fd = openSync(at, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const stat = fstatSync(fd);
+                    if (!stat.isFile() || stat.size > budget - consumed)
+                        throw Error('bundle/public-budget');
+                    const bytes = Buffer.alloc(stat.size);
+                    let offset = 0;
+                    while (offset < bytes.length) {
+                        const count = readSync(fd, bytes, offset, bytes.length - offset, null);
+                        if (!count)
+                            throw Error('bundle/public-member');
+                        offset += count;
+                    }
+                    if (readSync(fd, Buffer.alloc(1), 0, 1, null))
+                        throw Error('bundle/public-budget');
+                    consumed += bytes.length;
+                    held.set(path, bytes);
+                    return bytes;
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            }
+        } };
+}

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

@@ -0,0 +1,35 @@
+import { type ConfiguredSource, type Tool } from './mcp.ts';
+import type { Asked, Context } from '../../core/answer.ts';
+import type { Said } from '../../core/lock.ts';
+import { vocabOf } from '../../core/read.ts';
+export declare const configuredProtocol: Readonly<{
+    id: "mcp";
+    sourceNeeded: "bundle-mcp-needed";
+    invoke: "elicit-mcp-call";
+    failurePrefix: "mcp/";
+    toolFailure: "mcp/tool";
+    connection: (bytes: Uint8Array, source: string, overlay: boolean, v: Pick<ReturnType<typeof vocabOf>, "offers" | "class">) => {
+        worlds: string[];
+        verify: (lines: readonly Said[]) => void;
+    } | undefined;
+}>;
+export interface ConfiguredDocument {
+    readonly protocol: 'head-configured-mcp-document@1';
+    readonly configuration: ConfiguredSource;
+    readonly tools: readonly Tool[];
+    readonly resource: string;
+}
+/** The public document remains input to the published MCP interpreter. Host metadata supplies transport, never an offer class. */
+export declare function configuredDocument(bytes: Uint8Array): ConfiguredDocument | undefined;
+export declare const configuredBytes: (configuration: ConfiguredSource, tools: readonly Tool[]) => Uint8Array;
+/** Fresh source bytes must be covered by the compiled reading before retained results or a network request can be used. */
+export declare function configuredAt(context: Context, place: string, source: string, lines: readonly Said[]): ConfiguredSource | undefined;
+/** Discovery is explicitly selected by the consumer; there is no automatic protocol guessing or network on package inspection. */
+export declare function discoverConfigured(context: Context, asked: Asked, source: string): Promise<{
+    bytes: Uint8Array<ArrayBufferLike>;
+    kind: string;
+}>;
+/** The same safe, named refusal is used at connect and call, without printing transport exceptions or credentials. */
+export declare const configuredRefusal: (context: Context, error: unknown) => string[];
+/** Verify public configured inputs at inspection, and require an exact compiled operation mapping; never guess tool names. */
+export declare const configuredPackage: (_context: Context, files: ReadonlyMap<string, Uint8Array | undefined>) => ConfiguredDocument[];

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

@@ -0,0 +1,67 @@
+import { configuredSource, fingerprint } from "./mcp.js";
+import { valueOf } from "../../core/lock.js";
+import { fieldsOf, vocabOf } from "../../core/read.js";
+import { digestIn } from "../../core/worlds.js";
+import { sayIn } from "../../core/surface.js";
+export const configuredProtocol = Object.freeze({ id: 'mcp', sourceNeeded: 'bundle-mcp-needed', invoke: 'elicit-mcp-call', failurePrefix: 'mcp/', toolFailure: 'mcp/tool',
+    connection: (bytes, source, overlay, v) => { const doc = configuredDocument(bytes); if (!doc)
+        return undefined; if (doc.configuration.name !== source || overlay)
+        throw Error('mcp/document'); return { worlds: ['topos-mcp'], verify: (lines) => { if (doc.configuration.offers.some(name => !lines.some(l => l.scope === `${v.offers}/${source}/${name}` && l.measure === v.class)))
+            throw Error('mcp/tool-mapping'); } }; }
+});
+/** The public document remains input to the published MCP interpreter. Host metadata supplies transport, never an offer class. */
+export function configuredDocument(bytes) {
+    let doc;
+    try {
+        doc = JSON.parse(Buffer.from(bytes).toString());
+    }
+    catch {
+        return undefined;
+    }
+    if (doc?.protocol !== 'head-configured-mcp-document@1')
+        return undefined;
+    if (Object.keys(doc).sort().join('|') !== 'configuration|protocol|resource|tools' || !Array.isArray(doc.tools))
+        throw Error('mcp/document');
+    const configuration = configuredSource(doc.configuration);
+    if (doc.resource !== configuration.endpoint || doc.tools.some((t) => !t || typeof t.name !== 'string' || t.inputSchema?.type !== 'object')
+        || new Set(doc.tools.map((t) => t.name)).size !== doc.tools.length || fingerprint(doc.tools).digest !== configuration.catalogue
+        || configuration.offers.some(name => !doc.tools.some((t) => t.name === name)))
+        throw Error('mcp/document');
+    return { protocol: doc.protocol, configuration, tools: doc.tools, resource: doc.resource };
+}
+export const configuredBytes = (configuration, tools) => {
+    const bytes = Buffer.from(JSON.stringify({ protocol: 'head-configured-mcp-document@1', configuration, tools, resource: configuration.endpoint }) + '\n');
+    configuredDocument(bytes);
+    return bytes;
+};
+/** Fresh source bytes must be covered by the compiled reading before retained results or a network request can be used. */
+export function configuredAt(context, place, source, lines) {
+    const laid = context.files.read.laidOf(context, place, source).filter(([path]) => !path.includes('.overlay.'));
+    const docs = laid.map(([path, bytes]) => ({ path, bytes, doc: configuredDocument(bytes) })).filter(one => one.doc);
+    if (!docs.length) {
+        if (lines.some(l => l.scope?.startsWith(`offers/${source}/`) && l.measure === 'declares' && ['read-only', 'unhinted', 'destructive'].includes(l.value ?? '')))
+            throw Error('mcp/document-pin');
+        return undefined;
+    }
+    const v = vocabOf(context.lock);
+    if (docs.length !== 1 || docs[0].doc.configuration.name !== source || !(fieldsOf(lines, `${v.region}/${source}`)[valueOf(context.lock, 'vocab/documents')] ?? []).includes(digestIn(context.lock)(docs[0].bytes)))
+        throw Error('mcp/document-pin');
+    return docs[0].doc.configuration;
+}
+/** Discovery is explicitly selected by the consumer; there is no automatic protocol guessing or network on package inspection. */
+export async function discoverConfigured(context, asked, source) {
+    if (!context.remote || !source || !/^[a-z][a-z0-9-]*$/.test(source))
+        throw Error('mcp/unavailable');
+    const endpoint = asked['document'] ?? '', url = new URL(endpoint);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.href !== endpoint)
+        throw Error('mcp/endpoint');
+    if (asked['via'])
+        throw Error('mcp/discovery-access-unsupported');
+    const read = await (await context.remote()).discover(endpoint);
+    const configuration = configuredSource({ protocol: 'head-configured-mcp@1', name: source, endpoint, catalogue: read.digest, offers: read.tools.map(tool => tool.name) });
+    return { bytes: configuredBytes(configuration, read.tools), kind: 'json' };
+}
+/** The same safe, named refusal is used at connect and call, without printing transport exceptions or credentials. */
+export const configuredRefusal = (context, error) => [sayIn(context.lock)('mcp-refused', { why: error instanceof Error && /^mcp\/[a-z-]+$/.test(error.message) ? error.message : 'mcp/transport' })];
+/** Verify public configured inputs at inspection, and require an exact compiled operation mapping; never guess tool names. */
+export const configuredPackage = (_context, files) => [...files].flatMap(([path, bytes]) => { const doc = bytes && path.endsWith('.json') ? configuredDocument(bytes) : undefined; return doc ? [doc] : []; });

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;