@fungi.computer/mycelium 0.0.0-stage → 0.0.1

package/dist/mcp.js

@@ -0,0 +1,250 @@
+import { sameMcpPrincipal, } from "./internal/mcp-principal.js";
+export { sameMcpPrincipal };
+export { createMcpCatalog } from "./mcp-catalog.js";
+import { nanoid } from "@fungi.computer/cairn";
+import { McpServer as ProtocolServer, WebStandardStreamableHTTPServerTransport, specTypeSchemas, } from "@modelcontextprotocol/server";
+import * as Schema from "effect/Schema";
+/** Serve the host's principal-bound Mycelium catalog through one MCP implementation. */
+export function createMcp(options) {
+    const live = new Map();
+    const opening = new Set();
+    let closed = false;
+    const isClosed = () => closed;
+    async function current(principal, id) {
+        const session = await options.catalog.resume(principal, id);
+        if (session?.id !== id || !sameMcpPrincipal(session.principal, principal))
+            throw new Error("MCP connection is unavailable");
+        await session.refresh();
+        return session;
+    }
+    async function connect(session, canElicit) {
+        const { instructions } = await session.describe();
+        const server = new ProtocolServer({ name: "mycelium", version: "1" }, {
+            capabilities: { tools: {} },
+            instructions,
+            // The durable execution remains suspended during a form elicitation.
+            // Do not negotiate a protocol that requires replaying the program.
+            supportedProtocolVersions: ["2025-11-25"],
+        });
+        server.server.setRequestHandler("tools/list", async () => {
+            try {
+                const active = await current(session.principal, session.id);
+                const { tools } = await active.describe();
+                return {
+                    tools: tools.map((tool) => {
+                        const parsed = specTypeSchemas.Tool["~standard"].validate({
+                            name: tool.name,
+                            description: tool.description,
+                            inputSchema: tool.parameters,
+                        });
+                        if (parsed.issues !== undefined)
+                            throw new Error("Invalid MCP tool descriptor");
+                        return parsed.value;
+                    }),
+                };
+            }
+            catch {
+                throw new Error("MCP catalog is unavailable");
+            }
+        });
+        server.server.setRequestHandler("tools/call", async (request, context) => {
+            try {
+                const active = await current(session.principal, session.id);
+                const confirm = canElicit
+                    ? async (approval, signal) => {
+                        const answer = await context.mcpReq.send({
+                            method: "elicitation/create",
+                            params: {
+                                mode: "form",
+                                message: `Allow ${approval.module}.${approval.operation} (${approval.access})?`,
+                                requestedSchema: {
+                                    type: "object",
+                                    properties: {
+                                        approve: {
+                                            type: "boolean",
+                                            title: "Approve this operation",
+                                        },
+                                    },
+                                    required: ["approve"],
+                                },
+                            },
+                        }, { signal });
+                        return (answer.action === "accept" && answer.content?.approve === true);
+                    }
+                    : undefined;
+                const access = {
+                    confirmWrites: true,
+                    confirm,
+                    beforeCall: async (signal) => {
+                        signal.throwIfAborted();
+                        const request = context.http?.req;
+                        if (request === undefined)
+                            throw new Error("MCP request is unavailable");
+                        const admission = await options.authenticate(request);
+                        if (admission.kind !== "admitted" ||
+                            !sameMcpPrincipal(admission.principal, session.principal))
+                            throw new Error("MCP authority is unavailable");
+                        await current(session.principal, session.id);
+                        signal.throwIfAborted();
+                    },
+                };
+                let progress = 0;
+                const progressToken = request.params._meta?.progressToken;
+                const callOptions = {
+                    signal: context.mcpReq.signal,
+                    access,
+                    onPart: async (part) => {
+                        if (progressToken === undefined)
+                            return;
+                        await context.mcpReq.notify({
+                            method: "notifications/progress",
+                            params: {
+                                progressToken,
+                                progress: ++progress,
+                                message: JSON.stringify(part),
+                            },
+                        });
+                    },
+                };
+                const result = await active.call({
+                    id: nanoid(),
+                    name: request.params.name,
+                    arguments: Schema.decodeUnknownSync(Schema.Record(Schema.String, Schema.MutableJson))(request.params.arguments ?? {}),
+                }, callOptions);
+                return { content: result.content, isError: result.isError };
+            }
+            catch {
+                throw new Error("MCP tool call failed");
+            }
+        });
+        const metadata = {
+            id: session.id,
+            principal: session.principal,
+        };
+        const transportOptions = {
+            sessionIdGenerator: () => nanoid(),
+            onsessioninitialized: async (id) => {
+                await options.persistence?.initialized(id, metadata);
+                live.set(id, Promise.resolve({ server, transport, session }));
+            },
+            onsessionclosed: async (id) => {
+                live.delete(id);
+                await session.disconnect();
+                await options.persistence?.closed(id, metadata);
+            },
+        };
+        if (options.persistence !== undefined)
+            transportOptions.eventStore = options.persistence.eventStore(session.id);
+        const transport = new WebStandardStreamableHTTPServerTransport(transportOptions);
+        await server.connect(transport);
+        return { server, transport, session };
+    }
+    async function handleRequest(request) {
+        const admission = await options.authenticate(request);
+        if (admission.kind === "refused")
+            return new Response("Access refused", {
+                status: admission.status,
+                headers: admission.retryAfter === undefined
+                    ? {}
+                    : { "Retry-After": String(admission.retryAfter) },
+            });
+        if (isClosed())
+            return new Response("MCP is closed", { status: 503 });
+        const principal = admission.principal;
+        const id = request.headers.get("Mcp-Session-Id");
+        let session;
+        const created = id === null;
+        let canElicit = false;
+        if (created) {
+            if (request.method !== "POST")
+                return new Response("Not found", { status: 404 });
+            let body;
+            try {
+                body = await request.clone().json();
+            }
+            catch {
+                return new Response("Invalid initialization", { status: 400 });
+            }
+            const parsed = specTypeSchemas.InitializeRequest["~standard"].validate(body);
+            if (parsed.issues !== undefined)
+                return new Response("Invalid initialization", { status: 400 });
+            canElicit =
+                parsed.value.params.capabilities.elicitation?.form !== undefined;
+            session = await options.catalog.open(principal, {
+                id: nanoid(),
+                title: `${parsed.value.params.clientInfo.name} · MCP`,
+                maxOpenSessions: 8,
+            });
+            if (session === null)
+                return new Response("Too many open MCP Sessions", { status: 429 });
+        }
+        else {
+            const active = live.get(id);
+            if (active === undefined)
+                return new Response("Not found", { status: 404 });
+            session = (await active).session;
+        }
+        if (!sameMcpPrincipal(session.principal, principal))
+            return new Response("Not found", { status: 404 });
+        if (isClosed()) {
+            if (created)
+                await session.disconnect();
+            return new Response("MCP is closed", { status: 503 });
+        }
+        let active;
+        try {
+            active =
+                id === null
+                    ? (async () => {
+                        await session.refresh();
+                        return connect(session, canElicit);
+                    })()
+                    : live.get(id);
+            if (active === undefined)
+                return new Response("Not found", { status: 404 });
+            if (created)
+                opening.add(active);
+            const connection = await active;
+            if (isClosed())
+                return new Response("MCP is closed", { status: 503 });
+            const response = await connection.transport.handleRequest(request);
+            if (created && !response.ok) {
+                await session.disconnect();
+                await connection.server.close();
+            }
+            return response;
+        }
+        catch {
+            if (id !== null && live.get(id) === active)
+                live.delete(id);
+            if (active !== undefined) {
+                const [result] = await Promise.allSettled([active]);
+                if (result.status === "fulfilled")
+                    await result.value.server.close();
+            }
+            if (created)
+                await session.disconnect();
+            return new Response("MCP is unavailable", { status: 503 });
+        }
+        finally {
+            if (active !== undefined)
+                opening.delete(active);
+        }
+    }
+    return {
+        async handleRequest(request) {
+            try {
+                return await handleRequest(request);
+            }
+            catch {
+                return new Response("MCP is unavailable", { status: 503 });
+            }
+        },
+        async close() {
+            closed = true;
+            const connections = [...new Set([...live.values(), ...opening])];
+            live.clear();
+            await Promise.all(connections.map(async (connection) => (await connection).server.close()));
+        },
+    };
+}

package/dist/operation-schema.d.ts

@@ -0,0 +1,47 @@
+import type { JsonSchemaSource } from "@fungi.computer/forage";
+import * as Schema from "effect/Schema";
+import type { SandboxValue } from "./index.js";
+/** One Standard Schema issue. */
+export type OperationSchemaIssue = Readonly<{
+    message: string;
+    path?: readonly (PropertyKey | Readonly<{
+        key: PropertyKey;
+    }>)[] | undefined;
+}>;
+/** Standard Schema validation result. */
+export type OperationSchemaResult<T> = Readonly<{
+    value: T;
+    issues?: undefined;
+}> | Readonly<{
+    issues: readonly OperationSchemaIssue[];
+}>;
+/**
+ * Any Standard Schema that also implements Standard JSON Schema, such as a
+ * Zod 4 schema. Mycelium validates with `validate` and describes the operation
+ * to the model with `jsonSchema`.
+ */
+export type StandardOperationSchema<T> = Readonly<{
+    "~standard": Readonly<{
+        /** Decode or validate one value, synchronously or not. */
+        validate: (value: SandboxValue) => OperationSchemaResult<T> | Promise<OperationSchemaResult<T>>;
+        /** Describe the accepted and produced JSON to the model. */
+        jsonSchema: JsonSchemaSource["~standard"]["jsonSchema"];
+    }>;
+}>;
+/**
+ * Schema for one operation's input or output: an Effect schema (exchanged as
+ * its canonical JSON codec, `Schema.toCodecJson`), or any Standard Schema with
+ * Standard JSON Schema such as Zod 4.
+ */
+export type OperationSchema<T> = Schema.Codec<T, unknown> | StandardOperationSchema<T>;
+/** One operation schema reduced to the three things Mycelium needs. */
+export type CompiledOperationSchema<T> = Readonly<{
+    /** What Forage renders for the model: always the JSON the sandbox exchanges. */
+    description: JsonSchemaSource;
+    /** Untrusted sandbox JSON → the value the operation receives. */
+    decode: (value: SandboxValue) => Promise<OperationSchemaResult<T>>;
+    /** The operation's result → the JSON value the sandbox receives. */
+    encode: (value: T) => Promise<OperationSchemaResult<unknown>>;
+}>;
+/** Reduce an Effect or Standard operation schema to Mycelium's internal port. */
+export declare function compileOperationSchema<T>(schema: OperationSchema<T>): CompiledOperationSchema<T>;

package/dist/operation-schema.js

@@ -0,0 +1,50 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+const formatIssues = SchemaIssue.makeFormatterStandardSchemaV1();
+/**
+ * Run one Effect parse. A schema failure becomes issues; a defect (a throwing
+ * filter or transformation) is a host bug and rethrows as a host error, so its
+ * message and stack never reach the model as "invalid input".
+ */
+async function parsed(parse) {
+    const exit = await Effect.runPromiseExit(parse);
+    if (Exit.isSuccess(exit))
+        return { value: exit.value };
+    const failure = Cause.findError(exit.cause);
+    if (Result.isFailure(failure))
+        throw Cause.squash(exit.cause);
+    return { issues: formatIssues(failure.success.issue).issues };
+}
+function fromEffect(schema) {
+    // One canonical JSON codec owns decode, encode and the description, so the
+    // model is told exactly the JSON Mycelium accepts and returns.
+    const codec = Schema.toCodecJson(schema);
+    const json = Schema.toStandardJSONSchemaV1(codec)["~standard"].jsonSchema;
+    const decode = Schema.decodeUnknownEffect(codec);
+    const encode = Schema.encodeUnknownEffect(codec);
+    return Object.freeze({
+        description: {
+            "~standard": { jsonSchema: { input: json.input, output: json.input } },
+        },
+        decode: (value) => parsed(decode(value)),
+        encode: (value) => parsed(encode(value)),
+    });
+}
+function fromStandard(schema) {
+    const validate = async (value) => schema["~standard"].validate(value);
+    return Object.freeze({
+        description: schema,
+        decode: validate,
+        // Standard Schema has no encoder: the result must already be JSON and is
+        // validated as declared.
+        encode: validate,
+    });
+}
+/** Reduce an Effect or Standard operation schema to Mycelium's internal port. */
+export function compileOperationSchema(schema) {
+    return Schema.isSchema(schema) ? fromEffect(schema) : fromStandard(schema);
+}

package/dist/promise-facade.d.ts

@@ -0,0 +1,3 @@
+import type { MyceliumOptions, Runtime } from "./index.js";
+/** Adapt the canonical scoped runtime at the named Promise boundary. */
+export declare function openPromiseRuntime(options: MyceliumOptions): Promise<Runtime>;

package/dist/promise-facade.js

@@ -0,0 +1,82 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
+import { fromTypedSandbox } from "./effect.js";
+import { openCoreRuntime } from "./runtime.js";
+async function runPromiseAtBoundary(effect, options) {
+    const exit = await Effect.runPromiseExit(effect, options);
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    const failure = Cause.findErrorOption(exit.cause);
+    if (Option.isSome(failure))
+        throw failure.value;
+    if (Cause.hasInterruptsOnly(exit.cause)) {
+        throw options?.signal?.reason instanceof Error
+            ? options.signal.reason
+            : new DOMException("The operation was aborted", "AbortError");
+    }
+    const squashed = Cause.squash(exit.cause);
+    if (squashed instanceof Error)
+        throw squashed;
+    throw new Error("Effect failed without an Error cause");
+}
+/** Adapt the canonical scoped runtime at the named Promise boundary. */
+export async function openPromiseRuntime(options) {
+    const runtimeScope = await runPromiseAtBoundary(Scope.make());
+    const onSandboxFailure = options.onSandboxFailure;
+    try {
+        const runtime = await runPromiseAtBoundary(openCoreRuntime({
+            modules: options.modules ?? [],
+            sources: options.sources ?? [],
+            session: options.session,
+            execution: options.execution,
+            sandbox: fromTypedSandbox(options.sandbox),
+            onSandboxFailure: onSandboxFailure === undefined
+                ? undefined
+                : (event) => Effect.promise(() => onSandboxFailure(event)),
+            tools: options.tools ?? [],
+            access: options.access ?? {},
+        }).pipe(Scope.provide(runtimeScope)));
+        const acquire = async (acquireOptions) => {
+            const leaseScope = await runPromiseAtBoundary(Scope.make());
+            try {
+                const lease = await runPromiseAtBoundary(runtime.acquire().pipe(Scope.provide(leaseScope)), acquireOptions?.signal === undefined
+                    ? undefined
+                    : { signal: acquireOptions.signal });
+                // One release attempt; a retry observes its outcome, never a fresh success.
+                let releasing;
+                return Object.freeze({
+                    revision: lease.revision,
+                    catalog: lease.catalog,
+                    executeTool: lease.effectExecuteTool,
+                    tools: lease.tools,
+                    release: () => {
+                        releasing ??= runPromiseAtBoundary(lease
+                            .release()
+                            .pipe(Effect.ensuring(Scope.close(leaseScope, Exit.void))));
+                        return releasing;
+                    },
+                });
+            }
+            catch (cause) {
+                await runPromiseAtBoundary(Scope.close(leaseScope, Exit.void));
+                throw cause;
+            }
+        };
+        // One close attempt; a retry observes its outcome, never a fresh success.
+        let closing;
+        const close = () => {
+            closing ??= runPromiseAtBoundary(runtime
+                .close()
+                .pipe(Effect.ensuring(Scope.close(runtimeScope, Exit.void))));
+            return closing;
+        };
+        return Object.freeze({ acquire, close });
+    }
+    catch (cause) {
+        await runPromiseAtBoundary(Scope.close(runtimeScope, Exit.void));
+        throw cause;
+    }
+}

package/dist/registration.d.ts

@@ -0,0 +1,74 @@
+import { type Access } from "./access.js";
+import type { InvocationContext, ModuleDefinition, MyceliumJsonValue, OperationDefinition, SandboxValue } from "./index.js";
+import type { JsonSchemaSource } from "@fungi.computer/forage";
+declare const operationBrand: unique symbol;
+declare const operationTypes: unique symbol;
+declare const moduleBrand: unique symbol;
+/** Opaque handle for one schema-described operation. */
+export type OperationRegistration<I = unknown, O = unknown> = Readonly<{
+    readonly [operationBrand]: true;
+    readonly [operationTypes]?: Readonly<{
+        input: I;
+        output: O;
+    }>;
+}>;
+/** Opaque handle for one namespaced capability module. */
+export type ModuleRegistration = Readonly<{
+    readonly [moduleBrand]: true;
+}>;
+/** Captured operation data available only to the package compiler. */
+export type StoredOperation = Readonly<{
+    /** Replay classification of this operation, not of the enclosing execute tool. */
+    replay: "safe" | "unsafe";
+    /** What the operation does, as its author declared it; unlabelled is `write`. */
+    access: Access;
+    /** The author asks that a person approve each call first. */
+    confirm: boolean;
+    description?: string;
+    /** Model-facing description of the JSON the operation accepts. */
+    input: JsonSchemaSource;
+    /** Model-facing description of the JSON the operation returns. */
+    output?: JsonSchemaSource;
+    /** Returns the declared result; the execute door checks it is JSON. */
+    invoke: (input: SandboxValue, context: InvocationContext) => Promise<SandboxValue>;
+}>;
+/** Captured module data available only to the package compiler. */
+export type StoredModule = Readonly<{
+    id: string;
+    /** The key a host's grant names for this module; its id unless reassigned. */
+    grantKey: string;
+    name: string;
+    namespace: readonly string[];
+    description?: string;
+    operations: Readonly<Record<string, OperationRegistration | ModuleRegistration>>;
+}>;
+/** Construct an opaque operation handle and retain its private definition. */
+export declare function defineOperation<I, O>(definition: OperationDefinition<I, O>): OperationRegistration<I, O>;
+/** Construct an opaque module handle and retain a frozen declaration copy. */
+export declare function defineModule(definition: ModuleDefinition): ModuleRegistration;
+/** Distinguish registered child modules without exposing their private declarations. */
+export declare function isModuleRegistration(registration: OperationRegistration | ModuleRegistration): registration is ModuleRegistration;
+/** Resolve private operation data for a compiler-owned handle. */
+export declare function readOperation(registration: OperationRegistration): StoredOperation | undefined;
+/** Resolve private module data for a compiler-owned handle. */
+export declare function readModule(registration: ModuleRegistration): StoredModule | undefined;
+/** A gate's verdict for one call: run the operation, or return `value` instead. */
+export type GateDecision = Readonly<{
+    kind: "allow";
+}> | Readonly<{
+    kind: "refuse";
+    value: MyceliumJsonValue;
+}>;
+/** Asked before every call of a gated module's operations. */
+export type OperationGate = (call: Readonly<{
+    operation: string;
+    context: InvocationContext;
+}>) => GateDecision | Promise<GateDecision>;
+/**
+ * Look this module's grant up by `grantKey` instead of its id, for a host
+ * that grants by a wider owner, such as the extension that built the module.
+ */
+export declare function grantModuleAs(registration: ModuleRegistration, grantKey: string): ModuleRegistration;
+/** Gate an entire module tree while preserving its authority identity. */
+export declare function gateModule(registration: ModuleRegistration, gate: OperationGate): ModuleRegistration;
+export {};

package/dist/registration.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { sandboxNamespaceSegmentSchema } from "./sandbox-guest.js";
+import { parseAccessLabels } from "./access.js";
+import { InvalidOperationInput, InvalidOperationOutput, MyceliumDefinitionError, } from "./errors.js";
+import { compileOperationSchema } from "./operation-schema.js";
+import { BadResponse } from "./sandbox-failure.js";
+const operationBrand = Symbol("mycelium.operation");
+const operationTypes = Symbol("mycelium.operation.types");
+const moduleBrand = Symbol("mycelium.module");
+const operationDefinitions = new WeakMap();
+const moduleDefinitions = new WeakMap();
+/** Construct an opaque operation handle and retain its private definition. */
+export function defineOperation(definition) {
+    const registration = Object.freeze({
+        [operationBrand]: true,
+    });
+    const input = compileOperationSchema(definition.input);
+    const output = definition.output === undefined
+        ? undefined
+        : compileOperationSchema(definition.output);
+    const captured = {
+        replay: definition.replay ?? "unsafe",
+        ...parseAccessLabels(definition),
+        input: input.description,
+        invoke: async (raw, context) => {
+            const decoded = await input.decode(raw);
+            if (decoded.issues !== undefined)
+                throw new InvalidOperationInput(decoded.issues);
+            const result = await definition.execute(decoded.value, context);
+            if (output === undefined)
+                return result;
+            const encoded = await output.encode(result);
+            if (encoded.issues !== undefined)
+                throw new BadResponse({
+                    reason: "Capability output failed its declared schema",
+                    rawCause: new InvalidOperationOutput(encoded.issues),
+                });
+            return encoded.value;
+        },
+    };
+    if (definition.description !== undefined)
+        captured.description = definition.description;
+    if (output !== undefined)
+        captured.output = output.description;
+    const stored = Object.freeze(captured);
+    operationDefinitions.set(registration, stored);
+    return registration;
+}
+/** Construct an opaque module handle and retain a frozen declaration copy. */
+export function defineModule(definition) {
+    const namespace = z
+        .array(sandboxNamespaceSegmentSchema)
+        .safeParse(definition.namespace ?? []);
+    if (!namespace.success)
+        throw new MyceliumDefinitionError("Invalid module namespace");
+    const registration = Object.freeze({
+        [moduleBrand]: true,
+    });
+    const captured = {
+        id: definition.id,
+        grantKey: definition.id,
+        name: definition.name ?? definition.id,
+        namespace: Object.freeze(namespace.data),
+        operations: Object.freeze({ ...definition.operations }),
+    };
+    if (definition.description !== undefined)
+        captured.description = definition.description;
+    const stored = Object.freeze(captured);
+    moduleDefinitions.set(registration, stored);
+    return registration;
+}
+/** Distinguish registered child modules without exposing their private declarations. */
+export function isModuleRegistration(registration) {
+    return moduleDefinitions.has(registration);
+}
+/** Resolve private operation data for a compiler-owned handle. */
+export function readOperation(registration) {
+    return operationDefinitions.get(registration);
+}
+/** Resolve private module data for a compiler-owned handle. */
+export function readModule(registration) {
+    return moduleDefinitions.get(registration);
+}
+/**
+ * Wrap every operation of one module behind a host gate, keeping its
+ * identity, alias, description and schemas. A refused call never reaches the
+ * operation (not even its input decoder) and returns the gate's typed value.
+ */
+function gateModuleAt(registration, gate, prefix) {
+    const stored = readModule(registration);
+    if (stored === undefined)
+        throw new MyceliumDefinitionError("Unknown module registration");
+    const operations = {};
+    for (const [name, handle] of Object.entries(stored.operations)) {
+        const operation = prefix === "" ? name : `${prefix}.${name}`;
+        if (isModuleRegistration(handle)) {
+            const child = readModule(handle);
+            if (child === undefined)
+                throw new MyceliumDefinitionError("Unknown child module registration");
+            operations[name] = gateModuleAt(handle, gate, [operation, ...child.namespace].join("."));
+            continue;
+        }
+        const inner = readOperation(handle);
+        if (inner === undefined)
+            throw new MyceliumDefinitionError(`Unknown operation registration: ${name}`);
+        const gated = Object.freeze({
+            [operationBrand]: true,
+        });
+        operationDefinitions.set(gated, Object.freeze({
+            ...inner,
+            invoke: async (input, context) => {
+                const decision = await gate({ operation, context });
+                return decision.kind === "refuse"
+                    ? decision.value
+                    : await inner.invoke(input, context);
+            },
+        }));
+        operations[name] = gated;
+    }
+    const definition = stored.description === undefined
+        ? {
+            id: stored.id,
+            name: stored.name,
+            namespace: stored.namespace,
+            operations,
+        }
+        : {
+            id: stored.id,
+            name: stored.name,
+            namespace: stored.namespace,
+            description: stored.description,
+            operations,
+        };
+    return withGrantKey(defineModule(definition), stored.grantKey);
+}
+/** Copy one module registration under a different grant key. */
+function withGrantKey(registration, grantKey) {
+    const stored = readModule(registration);
+    if (stored === undefined)
+        throw new MyceliumDefinitionError("Unknown module registration");
+    const copy = Object.freeze({ [moduleBrand]: true });
+    moduleDefinitions.set(copy, Object.freeze({ ...stored, grantKey }));
+    return copy;
+}
+/**
+ * Look this module's grant up by `grantKey` instead of its id, for a host
+ * that grants by a wider owner, such as the extension that built the module.
+ */
+export function grantModuleAs(registration, grantKey) {
+    if (grantKey.length === 0 || grantKey.length > 160)
+        throw new MyceliumDefinitionError("Grant key must be non-empty and bounded");
+    return withGrantKey(registration, grantKey);
+}
+/** Gate an entire module tree while preserving its authority identity. */
+export function gateModule(registration, gate) {
+    return gateModuleAt(registration, gate, "");
+}