@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/dist/compiler.d.ts

@@ -0,0 +1,28 @@
+import { type ForageCatalog } from "@fungi.computer/forage";
+import { type ModuleRegistration, type StoredOperation } from "./registration.js";
+/** One deterministically named user operation in an installed capability surface. */
+export type CompiledOperation = Readonly<{
+    /** Grant key of the top-level module whose grant decides this operation. */
+    readonly grantKey: string;
+    readonly path: string;
+    readonly namespace: string;
+    readonly name: string;
+    readonly moduleDescription: string | undefined;
+    readonly operation: StoredOperation;
+}>;
+/** Immutable catalog and user-operation graph installed as one revision. */
+export type CompiledSurface = Readonly<{
+    readonly revision: string;
+    readonly catalog: ForageCatalog;
+    readonly operations: readonly CompiledOperation[];
+    /** Every allocated execution alias mapped to its stable module id. */
+    readonly moduleAliases: Readonly<Record<string, string>>;
+    readonly namespacePaths: Readonly<Record<string, readonly string[]>>;
+}>;
+/** Secret-free source identity included only in the opaque installed revision. */
+export type SourceRevisionFrame = Readonly<{
+    readonly id: string;
+    readonly version: string;
+}>;
+/** Compile opaque declarations and Forage intrinsics into one immutable surface. */
+export declare function compileSurface(registrations: readonly ModuleRegistration[], sourceFrames?: readonly SourceRevisionFrame[]): CompiledSurface;

package/dist/compiler.js

@@ -0,0 +1,221 @@
+import { createCatalog, forageDescribeDefinition, forageSearchDefinition, forageListDefinition, } from "@fungi.computer/forage";
+import { sandboxNamespaceSegmentSchema, sandboxTransportAliasSchema, } from "./sandbox-guest.js";
+import { MyceliumDefinitionError } from "./errors.js";
+import { readModule, isModuleRegistration, readOperation, } from "./registration.js";
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function definitionMessage(cause) {
+    return cause instanceof Error
+        ? cause.message
+        : "Capability declarations could not be compiled";
+}
+const maximumModuleIdLength = 160;
+function assertModuleId(value) {
+    if (value.length === 0 || value.length > maximumModuleIdLength) {
+        throw new MyceliumDefinitionError("Module id must be non-empty and bounded");
+    }
+}
+function assertOperationName(value) {
+    if (!value
+        .split(".")
+        .every((segment) => sandboxNamespaceSegmentSchema.safeParse(segment).success)) {
+        throw new MyceliumDefinitionError("Operation key must be a path segment or a dotted relative path");
+    }
+}
+function namespaceName(name) {
+    const sanitized = name.replace(/[^A-Za-z0-9_]/g, "_");
+    return /^[A-Za-z]/.test(sanitized) ? sanitized : `module_${sanitized}`;
+}
+function executionAlias(name) {
+    const segment = namespaceName(name);
+    return sandboxTransportAliasSchema.safeParse(segment).success
+        ? segment
+        : `module_${segment}`;
+}
+function allocateAliases(modules, scope) {
+    const used = new Set(["forage", "env"]);
+    const aliases = new Map();
+    for (const module of modules) {
+        const prefix = scope === "logical" ? module.namespace : [];
+        const base = scope === "logical"
+            ? namespaceName(module.name)
+            : executionAlias(module.name);
+        const fullPath = (name) => [...prefix, name].join(".");
+        let alias = base;
+        let suffix = 2;
+        while (used.has(fullPath(alias))) {
+            alias = `${base}_${String(suffix)}`;
+            suffix += 1;
+        }
+        used.add(fullPath(alias));
+        aliases.set(module.id, alias);
+    }
+    return aliases;
+}
+const fnvOffsetBasis = 0xcbf29ce484222325n;
+const fnvPrime = 0x100000001b3n;
+const unsigned64Mask = 0xffffffffffffffffn;
+/** Hash one length-framed UTF-16 string into the bounded installed identity. */
+function hashFrame(hash, value) {
+    let result = hash;
+    let length = BigInt(value.length);
+    for (let index = 0; index < 8; index += 1) {
+        result = ((result ^ (length & 0xffn)) * fnvPrime) & unsigned64Mask;
+        length >>= 8n;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        result = ((result ^ BigInt(codeUnit & 0xff)) * fnvPrime) & unsigned64Mask;
+        result =
+            ((result ^ BigInt((codeUnit >>> 8) & 0xff)) * fnvPrime) & unsigned64Mask;
+    }
+    return result;
+}
+/** Keep content identity and installed stable-id alias identity distinct. */
+function installedRevision(contentStamp, aliases, sourceFrames) {
+    let hash = hashFrame(fnvOffsetBasis, contentStamp);
+    const mapping = [...aliases.entries()].sort(([left], [right]) => compareCodeUnits(left, right));
+    for (const [stableId, alias] of mapping) {
+        hash = hashFrame(hash, stableId);
+        hash = hashFrame(hash, alias);
+    }
+    const frames = [...sourceFrames].sort((left, right) => compareCodeUnits(left.id, right.id));
+    for (const frame of frames) {
+        hash = hashFrame(hash, frame.id);
+        hash = hashFrame(hash, frame.version);
+    }
+    return `installed-${hash.toString(16).padStart(16, "0")}`;
+}
+function intrinsicOperations() {
+    return [
+        forageDescribeDefinition,
+        forageSearchDefinition,
+        forageListDefinition,
+    ];
+}
+/** Flatten child modules beneath their parent's single authority identity. */
+function flattenOperations(grantKey, module, namespace, path, description, names = []) {
+    return Object.entries(module.operations).flatMap(([name, registration]) => {
+        assertOperationName(name);
+        if (isModuleRegistration(registration)) {
+            const child = readModule(registration);
+            if (child === undefined)
+                throw new MyceliumDefinitionError("Unknown child module registration");
+            return flattenOperations(grantKey, child, namespace, [...path, name, ...child.namespace], child.description ?? description, [...names, name, ...child.namespace]);
+        }
+        const operation = readOperation(registration);
+        if (operation === undefined)
+            throw new MyceliumDefinitionError(`Unknown operation registration: ${[...path, name].join(".")}`);
+        return [
+            Object.freeze({
+                grantKey,
+                path: [...path, name].join("."),
+                namespace,
+                name: [...names, name].join("."),
+                moduleDescription: description,
+                operation,
+            }),
+        ];
+    });
+}
+/** Compile opaque declarations and Forage intrinsics into one immutable surface. */
+export function compileSurface(registrations, sourceFrames = []) {
+    const modules = registrations
+        .map((registration) => {
+        const module = readModule(registration);
+        if (module === undefined) {
+            throw new MyceliumDefinitionError("Unknown module registration");
+        }
+        assertModuleId(module.id);
+        return module;
+    })
+        .sort((left, right) => compareCodeUnits(left.id, right.id));
+    const ids = new Set();
+    for (const module of modules) {
+        if (ids.has(module.id)) {
+            throw new MyceliumDefinitionError(`Duplicate module id: ${module.id}`);
+        }
+        ids.add(module.id);
+    }
+    const aliases = allocateAliases(modules, "transport");
+    const logicalAliases = allocateAliases(modules, "logical");
+    const namespacePaths = Object.freeze(Object.fromEntries(modules.map((module) => {
+        const alias = aliases.get(module.id);
+        if (alias === undefined)
+            throw new MyceliumDefinitionError(`Missing module alias: ${module.id}`);
+        const logical = logicalAliases.get(module.id);
+        if (logical === undefined)
+            throw new MyceliumDefinitionError(`Missing logical alias: ${module.id}`);
+        return [alias, Object.freeze([...module.namespace, logical])];
+    })));
+    const operations = modules
+        .flatMap((module) => {
+        const alias = aliases.get(module.id);
+        if (alias === undefined)
+            throw new MyceliumDefinitionError(`Missing module alias: ${module.id}`);
+        const path = namespacePaths[alias];
+        if (path === undefined)
+            throw new MyceliumDefinitionError(`Missing namespace path: ${module.id}`);
+        return flattenOperations(module.grantKey, module, alias, path, module.description);
+    })
+        .sort((left, right) => compareCodeUnits(left.path, right.path));
+    const operationPaths = new Set(operations.map((operation) => operation.path));
+    if (operationPaths.size !== operations.length)
+        throw new MyceliumDefinitionError("Duplicate operation path");
+    for (const intrinsic of intrinsicOperations()) {
+        if (operationPaths.has(intrinsic.path))
+            throw new MyceliumDefinitionError(`Reserved intrinsic path: ${intrinsic.path}`);
+        operationPaths.add(intrinsic.path);
+    }
+    for (const path of operationPaths) {
+        const segments = path.split(".");
+        for (let length = 1; length < segments.length; length += 1)
+            if (operationPaths.has(segments.slice(0, length).join(".")))
+                throw new MyceliumDefinitionError(`Operation conflicts with namespace: ${path}`);
+    }
+    let prepared;
+    try {
+        prepared = createCatalog({
+            revision: "prepared-content-stamp",
+            operations: [
+                ...operations.map(({ path, moduleDescription, operation }) => {
+                    const catalogOperation = {
+                        path,
+                        input: operation.input,
+                    };
+                    if (operation.description !== undefined) {
+                        catalogOperation.description = operation.description;
+                    }
+                    if (operation.output !== undefined) {
+                        catalogOperation.output = operation.output;
+                    }
+                    if (moduleDescription !== undefined) {
+                        catalogOperation.instructions = moduleDescription;
+                    }
+                    return catalogOperation;
+                }),
+                ...intrinsicOperations(),
+            ],
+        });
+    }
+    catch (cause) {
+        throw new MyceliumDefinitionError(definitionMessage(cause));
+    }
+    const revision = installedRevision(prepared.stamp(), aliases, sourceFrames);
+    const catalog = Object.freeze({
+        revision,
+        search: prepared.search,
+        describe: prepared.describe,
+        list: prepared.list,
+        stamp: prepared.stamp,
+    });
+    const moduleAliases = Object.freeze(Object.fromEntries([...aliases.entries()].map(([moduleId, alias]) => [alias, moduleId])));
+    return Object.freeze({
+        revision,
+        catalog,
+        operations: Object.freeze(operations),
+        moduleAliases,
+        namespacePaths,
+    });
+}

package/dist/define.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime-free authoring: declare modules and operations without loading the
+ * execute runtime, so a definition can be bundled into an isolate that only
+ * describes and invokes it (for example a hosted Agent extension).
+ */
+import type { MyceliumApi } from "./index.js";
+/** The authoring half of {@link MyceliumApi}; registrations are the same handles. */
+export declare const Mycelium: Pick<MyceliumApi, "module" | "operation" | "gate">;

package/dist/define.js

@@ -0,0 +1,7 @@
+import { defineModule, defineOperation, gateModule } from "./registration.js";
+/** The authoring half of {@link MyceliumApi}; registrations are the same handles. */
+export const Mycelium = Object.freeze({
+    module: defineModule,
+    operation: defineOperation,
+    gate: gateModule,
+});

package/dist/effect.d.ts

@@ -0,0 +1,89 @@
+import type { SandboxFailureEvent } from "./sandbox-failure-event.js";
+import type { ForageCatalog } from "@fungi.computer/forage";
+import type { MuleTool } from "@fungi.computer/mule/effect";
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import { type SandboxFailure } from "./sandbox-failure.js";
+import type { MyceliumError } from "./errors.js";
+import type { ExecutionOptions } from "./execute-tool.js";
+import type { CapabilitySession, CapabilitySource, ModuleRegistration, Sandbox as PromiseSandbox, SandboxBinding, SandboxRequest, SandboxValue } from "./index.js";
+import type { AccessOptions, LabelledTool } from "./access.js";
+export type { CapabilitySession, CapabilitySource, ModuleRegistration, SandboxBinding, SandboxRequest, };
+export type { ExecutionOptions } from "./execute-tool.js";
+export type { Access, AccessContext, AccessLabel, AccessOptions, AccessRefusal, AccessRefusalReason, ConfirmRequest, Grant, Grants, LabelledTool, ToolPolicy, } from "./access.js";
+/**
+ * Effect-native host seam for sandbox execution.
+ *
+ * Interrupting `execute` must not complete until the backing work has actually
+ * settled. Mycelium bounds that wait by the acknowledgement grace and reports
+ * `abort_unacknowledged` when it expires, keeping the work's source revision
+ * alive until it exits. A host with Promise-shaped work adapts it with
+ * {@link fromTypedSandbox}; `Effect.tryPromise` alone completes interruption
+ * without awaiting the Promise and so breaks that settlement law.
+ */
+export type Sandbox = Readonly<{
+    /**
+     * Evaluate one bounded program within the caller's Effect scope. `signal` is
+     * Mycelium's invocation abort projection for Promise-shaped host work.
+     */
+    execute: (request: SandboxRequest, signal: AbortSignal) => Effect.Effect<SandboxValue, SandboxFailure>;
+    /** Operator identity supplied by the host. */
+    adapter?: string;
+    /** Source revision embedded by the build, absent in an unpacked source run. */
+    buildSha?: string | undefined;
+}>;
+/**
+ * Adapt a Promise-shaped sandbox to the Effect seam. This is Mycelium's one
+ * Promise sandbox conversion: interruption waits for the host Promise to
+ * settle, while cancellation reaches the host through the abort signal.
+ */
+export declare function fromTypedSandbox(sandbox: PromiseSandbox): Sandbox;
+/** Inputs used to construct the canonical Effect runtime. */
+export type MyceliumOptions = Readonly<{
+    /** Unordered module registrations compiled into one immutable revision. */
+    modules?: readonly ModuleRegistration[];
+    /** Versioned host projections reconciled into immutable revisions. */
+    sources?: readonly CapabilitySource[];
+    /** Session every source acquisition is made for; absent for session-free hosts. */
+    session?: CapabilitySession;
+    /** Bounded Mycelium-owned deadline and cancellation acknowledgement policy. */
+    execution?: ExecutionOptions;
+    /** Host-owned Effect boundary for model-authored programs. */
+    sandbox: Sandbox;
+    /** Operator-only failure sink; never contributes a model message. */
+    onSandboxFailure?: (event: SandboxFailureEvent) => Effect.Effect<void>;
+    /** Labelled direct tools offered beside execute under the same access check. */
+    tools?: readonly LabelledTool[];
+    /** Host grants and approval, checked against each call's labels. */
+    access?: AccessOptions;
+}>;
+/** One immutable Effect-facing capability revision. */
+export type Lease = Readonly<{
+    /** Installed capability revision captured by this immutable lease. */
+    revision: string;
+    /** Bounded discovery catalog for the captured revision. */
+    catalog: ForageCatalog;
+    /** Single Effect-native Mule tool for discovery and scoped execution. */
+    executeTool: MuleTool;
+    /** The runtime's labelled direct tools, each behind the access check. */
+    tools: readonly MuleTool[];
+    /**
+     * Release explicitly with a typed failure. The owning scope also awaits this
+     * cleanup; automatic-finalizer failure terminates that scope as the same
+     * identifiable defect because Effect finalizers are infallible.
+     */
+    release: () => Effect.Effect<void, MyceliumError>;
+}>;
+/** Warm Effect lifecycle for acquiring scope-owned run leases. */
+export type Runtime = Readonly<{
+    /** Acquire one immutable lease owned by the caller's Effect scope. */
+    acquire: () => Effect.Effect<Lease, MyceliumError, Scope.Scope>;
+    /**
+     * Stop acquisition and await cleanup with a typed failure when called
+     * explicitly. Automatic scope cleanup retains a failure as an identifiable
+     * defect under Effect's infallible-finalizer contract.
+     */
+    close: () => Effect.Effect<void, MyceliumError>;
+}>;
+/** Construct the canonical scoped Effect runtime. */
+export declare function make(options: MyceliumOptions): Effect.Effect<Runtime, MyceliumError, Scope.Scope>;

package/dist/effect.js

@@ -0,0 +1,42 @@
+import { sandboxFailure } from "./sandbox-boundary.js";
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import {} from "./sandbox-failure.js";
+import { openCoreRuntime } from "./runtime.js";
+/**
+ * Adapt a Promise-shaped sandbox to the Effect seam. This is Mycelium's one
+ * Promise sandbox conversion: interruption waits for the host Promise to
+ * settle, while cancellation reaches the host through the abort signal.
+ */
+export function fromTypedSandbox(sandbox) {
+    return Object.freeze({
+        adapter: sandbox.adapter ?? "promise",
+        buildSha: sandbox.buildSha,
+        execute: (request, signal) => Effect.uninterruptible(Effect.tryPromise({
+            try: () => sandbox.execute(request, signal),
+            catch: sandboxFailure,
+        })),
+    });
+}
+/** Construct the canonical scoped Effect runtime. */
+export function make(options) {
+    return openCoreRuntime({
+        modules: options.modules ?? [],
+        sources: options.sources ?? [],
+        session: options.session,
+        execution: options.execution,
+        sandbox: options.sandbox,
+        onSandboxFailure: options.onSandboxFailure,
+        tools: options.tools ?? [],
+        access: options.access ?? {},
+    }).pipe(Effect.map((runtime) => Object.freeze({
+        acquire: () => runtime.acquire().pipe(Effect.map((lease) => Object.freeze({
+            revision: lease.revision,
+            catalog: lease.catalog,
+            executeTool: lease.effectExecuteTool,
+            tools: lease.tools,
+            release: lease.release,
+        }))),
+        close: runtime.close,
+    })));
+}

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+import type { OperationSchemaIssue } from "./operation-schema.js";
+import type { SandboxFailure } from "./sandbox-failure.js";
+/** Lifecycle phase in which a capability source failed. */
+export type MyceliumSourcePhase = "acquire" | "release" | "stale";
+/** A capability declaration could not form one coherent installed surface. */
+export declare class MyceliumDefinitionError extends Error {
+    /** Stable machine-readable failure code. */
+    readonly code = "invalid_definition";
+    constructor(message: string);
+}
+/** An operation attempted to use a closed Mycelium runtime. */
+export declare class MyceliumClosedError extends Error {
+    /** Stable machine-readable failure code. */
+    readonly code = "runtime_closed";
+    constructor(message?: string);
+}
+/** A capability source failed at its bounded host boundary. */
+export declare class MyceliumSourceError extends Error {
+    /** Stable identity of the source, absent for whole-candidate failures. */
+    readonly sourceId: string | undefined;
+    /** Lifecycle phase that could not settle. */
+    readonly phase: MyceliumSourcePhase;
+    /** Stable machine-readable failure code. */
+    readonly code = "source_failure";
+    constructor(
+    /** Stable identity of the source, absent for whole-candidate failures. */
+    sourceId: string | undefined, 
+    /** Lifecycle phase that could not settle. */
+    phase: MyceliumSourcePhase);
+}
+/** Closed failure vocabulary for the first Mycelium runtime slice. */
+export type MyceliumError = MyceliumClosedError | MyceliumDefinitionError | MyceliumSourceError | SandboxFailure;
+/** Untrusted operation input failed the operation's declared input schema. */
+export declare class InvalidOperationInput extends Error {
+    /** Schema issues, formatted for the model by the execute door. */
+    readonly issues: readonly OperationSchemaIssue[];
+    constructor(
+    /** Schema issues, formatted for the model by the execute door. */
+    issues: readonly OperationSchemaIssue[]);
+}
+/** An operation's result failed its declared output schema. */
+export declare class InvalidOperationOutput extends Error {
+    /** Schema issues, kept for operators; never shown to the model. */
+    readonly issues: readonly OperationSchemaIssue[];
+    constructor(
+    /** Schema issues, kept for operators; never shown to the model. */
+    issues: readonly OperationSchemaIssue[]);
+}

package/dist/errors.js

@@ -0,0 +1,62 @@
+const invalidDefinitionCode = "invalid_definition";
+const runtimeClosedCode = "runtime_closed";
+const sourceFailureCode = "source_failure";
+/** A capability declaration could not form one coherent installed surface. */
+export class MyceliumDefinitionError extends Error {
+    /** Stable machine-readable failure code. */
+    code = invalidDefinitionCode;
+    constructor(message) {
+        super(message);
+        this.name = "MyceliumDefinitionError";
+    }
+}
+/** An operation attempted to use a closed Mycelium runtime. */
+export class MyceliumClosedError extends Error {
+    /** Stable machine-readable failure code. */
+    code = runtimeClosedCode;
+    constructor(message = "Mycelium runtime is closed") {
+        super(message);
+        this.name = "MyceliumClosedError";
+    }
+}
+/** A capability source failed at its bounded host boundary. */
+export class MyceliumSourceError extends Error {
+    sourceId;
+    phase;
+    /** Stable machine-readable failure code. */
+    code = sourceFailureCode;
+    constructor(
+    /** Stable identity of the source, absent for whole-candidate failures. */
+    sourceId, 
+    /** Lifecycle phase that could not settle. */
+    phase) {
+        super(sourceId === undefined
+            ? `Capability source ${phase} failed`
+            : `Capability source ${phase} failed: ${sourceId}`);
+        this.sourceId = sourceId;
+        this.phase = phase;
+        this.name = "MyceliumSourceError";
+    }
+}
+/** Untrusted operation input failed the operation's declared input schema. */
+export class InvalidOperationInput extends Error {
+    issues;
+    constructor(
+    /** Schema issues, formatted for the model by the execute door. */
+    issues) {
+        super("Invalid operation input");
+        this.issues = issues;
+        this.name = "InvalidOperationInput";
+    }
+}
+/** An operation's result failed its declared output schema. */
+export class InvalidOperationOutput extends Error {
+    issues;
+    constructor(
+    /** Schema issues, kept for operators; never shown to the model. */
+    issues) {
+        super("Operation output failed its declared schema");
+        this.issues = issues;
+        this.name = "InvalidOperationOutput";
+    }
+}

package/dist/execute-tool.d.ts

@@ -0,0 +1,22 @@
+import { type ForageCatalog } from "@fungi.computer/forage";
+import { type MuleTool } from "@fungi.computer/mule/effect";
+import * as Effect from "effect/Effect";
+import { type AccessOptions } from "./access.js";
+import type { CompiledOperation } from "./compiler.js";
+import { type BackingWorkGroup, type SerializedSandboxValue } from "./internal/execution-lifecycle.js";
+import { type MyceliumError } from "./errors.js";
+import type { EffectSandbox } from "./runtime.js";
+/** Host-selectable execution limits; neither budget can be disabled. */
+export type ExecutionOptions = Readonly<{
+    /** Total execution deadline in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum acknowledgement wait after cancellation in milliseconds. */
+    abortGraceMs?: number;
+}>;
+/** The Effect-owned execute implementation shared by both public projections. */
+export type ExecuteDoor = Readonly<{
+    readonly effectTool: MuleTool;
+    readonly execute: (code: string, signal?: AbortSignal) => Effect.Effect<SerializedSandboxValue, MyceliumError>;
+}>;
+/** Construct one execute door over a stable compiled surface and sandbox adapter. */
+export declare function createExecuteDoor(operations: readonly CompiledOperation[], catalog: ForageCatalog, sandbox: EffectSandbox, backingWork: BackingWorkGroup, modules: Readonly<Record<string, string>>, namespacePaths: Readonly<Record<string, readonly string[]>>, sessionId: string | null, access: AccessOptions): ExecuteDoor;