@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/dist/sandbox-guest.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/** Closed guest envelope: guest exceptions cannot masquerade as host failures. */
+export declare const sandboxGuestResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    value: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        kind: z.ZodLiteral<"guest_threw">;
+        name: z.ZodString;
+        message: z.ZodString;
+        transportMessage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "ok">;
+/** Locate syntax in the submitted code, accounting for Codemode's normalization. */
+export declare function submittedSourceLocation(normalized: string, submitted: string): Readonly<{
+    line: number;
+    column: number;
+    excerpt: string;
+}> | null;
+/** Parsed guest namespace segments; callbacks never cross this wire. */
+export declare const sandboxNamespaceSegmentSchema: z.ZodString;
+/** A transport alias is interpolated as a strict JavaScript binding identifier. */
+export declare const sandboxTransportAliasSchema: z.ZodString;
+/** Transport aliases mapped to their logical namespace paths. */
+export declare const sandboxNamespacePathsSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+/** Serializable flat transport table; operation keys may have any namespace depth. */
+export declare const sandboxBindingNamesSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+/** Serializable operation names; callbacks stay in the host's existing binding table. */
+export declare function sandboxBindingNames<A>(bindings: Readonly<Record<string, Readonly<Record<string, A>>>>): Readonly<Record<string, readonly string[]>>;
+/** Injective provider identifier: Codemode sanitizes dotted function names. */
+export declare function sandboxProviderOperationName(operation: string): string;
+/** Capture name and text inside the guest, before Codemode erases Error.name. */
+export declare function sandboxGuestProgram(normalized: string, bindings?: Readonly<Record<string, readonly string[]>>, namespacePaths?: Readonly<Record<string, readonly string[]>>, transportName?: (operation: string) => string): string;

package/dist/sandbox-guest.js

@@ -0,0 +1,131 @@
+import { parse } from "acorn";
+import { z } from "zod";
+import { sandboxSourceError } from "./sandbox-boundary.js";
+/** Closed guest envelope: guest exceptions cannot masquerade as host failures. */
+export const sandboxGuestResultSchema = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), value: z.unknown() }),
+    z.strictObject({
+        ok: z.literal(false),
+        error: z.strictObject({
+            kind: z.literal("guest_threw"),
+            name: z.string().max(80),
+            message: z.string().max(512),
+            transportMessage: z.string().max(512).optional(),
+        }),
+    }),
+]);
+/** Locate syntax in the submitted code, accounting for Codemode's normalization. */
+export function submittedSourceLocation(normalized, submitted) {
+    try {
+        parse(`(${normalized})`, { ecmaVersion: "latest", sourceType: "module" });
+        return null;
+    }
+    catch (cause) {
+        const diagnostic = sandboxSourceError(cause);
+        if (diagnostic === undefined)
+            throw cause;
+        const { pos } = diagnostic;
+        const prelude = "async () => {\n";
+        const source = normalized.startsWith(prelude)
+            ? normalized.slice(prelude.length, -"\n}".length)
+            : normalized;
+        const start = submitted.indexOf(source);
+        if (start < 0)
+            throw cause;
+        const offset = Math.min(submitted.length, Math.max(0, pos - 1 - normalized.indexOf(source) + start));
+        const prefix = submitted.slice(0, offset).split(/\r\n|[\n\r\u2028\u2029]/u);
+        const line = prefix.length;
+        return {
+            line,
+            column: (prefix.at(-1)?.length ?? 0) + 1,
+            excerpt: (submitted.split(/\r\n|[\n\r\u2028\u2029]/u)[line - 1] ?? "")
+                .replace(/\p{Cc}|\p{Cf}/gu, " ")
+                .slice(0, 160),
+        };
+    }
+}
+/** Parsed guest namespace segments; callbacks never cross this wire. */
+export const sandboxNamespaceSegmentSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/u);
+/** A transport alias is interpolated as a strict JavaScript binding identifier. */
+export const sandboxTransportAliasSchema = sandboxNamespaceSegmentSchema.refine((alias) => {
+    if (alias === "env")
+        return false;
+    try {
+        parse(`let ${alias};`, { ecmaVersion: "latest", sourceType: "module" });
+        return true;
+    }
+    catch (cause) {
+        if (!(cause instanceof SyntaxError))
+            throw cause;
+        return false;
+    }
+}, "Invalid sandbox transport alias");
+/** Transport aliases mapped to their logical namespace paths. */
+export const sandboxNamespacePathsSchema = z.record(sandboxTransportAliasSchema, z.array(sandboxNamespaceSegmentSchema).min(1));
+/** Serializable flat transport table; operation keys may have any namespace depth. */
+export const sandboxBindingNamesSchema = z.record(sandboxTransportAliasSchema, z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/u)));
+/** Serializable operation names; callbacks stay in the host's existing binding table. */
+export function sandboxBindingNames(bindings) {
+    return Object.fromEntries(Object.entries(bindings).map(([namespace, operations]) => [
+        namespace,
+        Object.keys(operations),
+    ]));
+}
+/** Project compiler-owned paths without changing any callback or authority identity. */
+function guestEnvironment(bindings, namespacePaths, transportName) {
+    const root = { kind: "namespace", children: new Map() };
+    const paths = sandboxNamespacePathsSchema.parse(namespacePaths);
+    for (const [alias, operations] of Object.entries(sandboxBindingNamesSchema.parse(bindings))) {
+        for (const operation of operations) {
+            const path = [...(paths[alias] ?? [alias]), ...operation.split(".")];
+            let parent = root;
+            for (const segment of path.slice(0, -1)) {
+                const found = parent.children.get(segment);
+                if (found?.kind === "operation")
+                    throw new Error("Operation conflicts with namespace");
+                const child = found ?? {
+                    kind: "namespace",
+                    children: new Map(),
+                };
+                parent.children.set(segment, child);
+                parent = child;
+            }
+            const name = path.at(-1);
+            if (name === undefined || parent.children.has(name))
+                throw new Error("Duplicate guest operation path");
+            parent.children.set(name, {
+                kind: "operation",
+                call: `(...args) => ${alias}[${JSON.stringify(transportName(operation))}](...args)`,
+            });
+        }
+    }
+    const expression = (node) => `Object.freeze({${[...node.children]
+        .map(([name, child]) => `[${JSON.stringify(name)}]: ${child.kind === "operation" ? child.call : expression(child)}`)
+        .join(",")}})`;
+    return expression(root);
+}
+/** Injective provider identifier: Codemode sanitizes dotted function names. */
+export function sandboxProviderOperationName(operation) {
+    return `operation_${Array.from(new TextEncoder().encode(operation), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+/** Capture name and text inside the guest, before Codemode erases Error.name. */
+export function sandboxGuestProgram(normalized, bindings = {}, namespacePaths = {}, transportName) {
+    return `async () => {
+    const env = ${guestEnvironment(bindings, namespacePaths, transportName ?? ((operation) => operation))};
+    return await (async (${Object.keys(bindings).join(",")}) => {
+    try { return { ok: true, value: await (${normalized})() }; }
+    catch (cause) {
+      const name = cause instanceof Error ? cause.name : "ThrownValue";
+      const message = cause instanceof Error ? cause.message : String(cause);
+      const transportMessage = cause instanceof Error && cause.cause instanceof Error ? cause.cause.message.slice(0, 512) : undefined;
+      return { ok: false, error: { kind: "guest_threw", name: String(name).slice(0, 80), message: String(message).replace(/\\p{Cc}/gu, " ").slice(0, 512), ...(transportMessage === undefined ? {} : { transportMessage }) } };
+    }
+    })(${Object.keys(bindings)
+        .map((alias) => transportName === undefined
+        ? alias
+        : (namespacePaths[alias] ?? [alias]).reduce((value, segment) => `${value}[${JSON.stringify(segment)}]`, "env"))
+        .join(",")});
+  }`;
+}

package/dist/sandbox-wire.d.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { type SandboxFailure } from "./sandbox-failure.js";
+/** The host-to-host result contract; raw diagnostic fields never go to guest code. */
+export declare const sandboxWireSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    value: z.ZodJSONSchema;
+}, z.core.$strict>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"invalid_source">;
+        line: z.ZodNumber;
+        column: z.ZodNumber;
+        excerpt: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"guest_threw">;
+        name: z.ZodString;
+        message: z.ZodString;
+        transportMessage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"deadline_exceeded">;
+        limitMs: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"result_not_json">;
+        valueKind: z.ZodString;
+        rawCause: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"sandbox_crashed">;
+        rawCause: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"bad_response">;
+        reason: z.ZodString;
+        rawCause: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"dispatch_lost">;
+        elapsedMs: z.ZodNumber;
+        transport: z.ZodString;
+        errno: z.ZodOptional<z.ZodString>;
+        rawCause: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"cancelled">;
+        by: z.ZodEnum<{
+            caller: "caller";
+            operator: "operator";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"result_too_large">;
+        size: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"capability_failed">;
+        namespace: z.ZodString;
+        operation: z.ZodString;
+        cause: z.ZodObject<{
+            kind: z.ZodEnum<{
+                Files: "Files";
+                Forage: "Forage";
+                InvalidInput: "InvalidInput";
+                Unavailable: "Unavailable";
+                OperationFailed: "OperationFailed";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strict>;
+        rawCause: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"unknown">;
+        rawCause: z.ZodJSONSchema;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>], "ok">;
+/** Typed, decoded host wire value. */
+export type SandboxWire = z.output<typeof sandboxWireSchema>;
+/** Convert one validated wire failure into the shared error channel. */
+export declare function sandboxWireFailure(error: Extract<SandboxWire, {
+    ok: false;
+}>["error"]): SandboxFailure;
+/** Host-only encoding; the guest receives only the admitted diagnostic text. */
+export declare function sandboxFailureWire(failure: SandboxFailure): z.core.util.JSONType;

package/dist/sandbox-wire.js

@@ -0,0 +1,190 @@
+import { sandboxOperatorValue, sandboxGuestFailure, } from "./sandbox-boundary.js";
+import { z } from "zod";
+import { SourceInvalid, DeadlineExceeded, ResultNotJson, SandboxCrashed, BadResponse, DispatchLost, Cancelled, ResultTooLarge, CapabilityFailed, Unknown, } from "./sandbox-failure.js";
+/** The host-to-host result contract; raw diagnostic fields never go to guest code. */
+export const sandboxWireSchema = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), value: z.json() }),
+    z.strictObject({
+        ok: z.literal(false),
+        error: z.discriminatedUnion("kind", [
+            z.strictObject({
+                kind: z.literal("invalid_source"),
+                line: z.number().int().min(1),
+                column: z.number().int().min(1),
+                excerpt: z.string().max(160),
+            }),
+            z.strictObject({
+                kind: z.literal("guest_threw"),
+                name: z.string().max(80),
+                message: z.string().max(512),
+                transportMessage: z.string().max(512).optional(),
+            }),
+            z.strictObject({
+                kind: z.literal("deadline_exceeded"),
+                limitMs: z.number().int().positive(),
+                elapsedMs: z.number().nonnegative(),
+            }),
+            z.strictObject({
+                kind: z.literal("result_not_json"),
+                valueKind: z.string().max(80),
+                rawCause: z.json(),
+            }),
+            z.strictObject({
+                kind: z.literal("sandbox_crashed"),
+                rawCause: z.json(),
+            }),
+            z.strictObject({
+                kind: z.literal("bad_response"),
+                reason: z.string(),
+                rawCause: z.json(),
+            }),
+            z.strictObject({
+                kind: z.literal("dispatch_lost"),
+                elapsedMs: z.number().nonnegative(),
+                transport: z.string(),
+                errno: z.string().optional(),
+                rawCause: z.json(),
+            }),
+            z.strictObject({
+                kind: z.literal("cancelled"),
+                by: z.enum(["caller", "operator"]),
+            }),
+            z.strictObject({
+                kind: z.literal("result_too_large"),
+                size: z.number().nonnegative(),
+            }),
+            z.strictObject({
+                kind: z.literal("capability_failed"),
+                namespace: z.string(),
+                operation: z.string(),
+                cause: z.strictObject({
+                    kind: z.enum([
+                        "Files",
+                        "Forage",
+                        "InvalidInput",
+                        "Unavailable",
+                        "OperationFailed",
+                    ]),
+                    message: z.string().max(1000),
+                }),
+                rawCause: z.json(),
+            }),
+            z.strictObject({ kind: z.literal("unknown"), rawCause: z.json() }),
+        ]),
+    }),
+]);
+/** Convert one validated wire failure into the shared error channel. */
+export function sandboxWireFailure(error) {
+    switch (error.kind) {
+        case "invalid_source":
+            return new SourceInvalid(error);
+        case "guest_threw":
+            return sandboxGuestFailure(error);
+        case "deadline_exceeded":
+            return new DeadlineExceeded(error);
+        case "result_not_json":
+            return new ResultNotJson({
+                kind: error.valueKind,
+                rawCause: error.rawCause,
+            });
+        case "sandbox_crashed":
+            return new SandboxCrashed(error);
+        case "bad_response":
+            return new BadResponse(error);
+        case "dispatch_lost":
+            return new DispatchLost(error);
+        case "cancelled":
+            return new Cancelled(error);
+        case "result_too_large":
+            return new ResultTooLarge(error);
+        case "capability_failed":
+            return new CapabilityFailed(error);
+        case "unknown":
+            return new Unknown(error);
+    }
+}
+/** Host-only encoding; the guest receives only the admitted diagnostic text. */
+export function sandboxFailureWire(failure) {
+    let error;
+    switch (failure._tag) {
+        case "SourceInvalid":
+            error = {
+                kind: "invalid_source",
+                line: failure.line,
+                column: failure.column,
+                excerpt: failure.excerpt,
+            };
+            break;
+        case "GuestThrew":
+            error = {
+                kind: "guest_threw",
+                name: failure.name.slice(0, 80),
+                message: failure.message.slice(0, 512),
+            };
+            if (failure.transportMessage !== undefined)
+                error.transportMessage = failure.transportMessage;
+            break;
+        case "DeadlineExceeded":
+            error = {
+                kind: "deadline_exceeded",
+                limitMs: failure.limitMs,
+                elapsedMs: failure.elapsedMs,
+            };
+            break;
+        case "Cancelled":
+            error = { kind: "cancelled", by: failure.by };
+            break;
+        case "DispatchLost":
+            error = {
+                kind: "dispatch_lost",
+                elapsedMs: failure.elapsedMs,
+                transport: failure.transport,
+                rawCause: sandboxOperatorValue(failure.rawCause),
+            };
+            if (failure.errno !== undefined)
+                error.errno = failure.errno;
+            break;
+        case "SandboxCrashed":
+            error = {
+                kind: "sandbox_crashed",
+                rawCause: sandboxOperatorValue(failure.rawCause),
+            };
+            break;
+        case "BadResponse":
+            error = {
+                kind: "bad_response",
+                reason: failure.reason,
+                rawCause: sandboxOperatorValue(failure.rawCause),
+            };
+            break;
+        case "ResultNotJson":
+            error = {
+                kind: "result_not_json",
+                valueKind: failure.kind,
+                rawCause: sandboxOperatorValue(failure.rawCause),
+            };
+            break;
+        case "ResultTooLarge":
+            error = { kind: "result_too_large", size: failure.size };
+            break;
+        case "CapabilityFailed":
+            error = {
+                kind: "capability_failed",
+                namespace: failure.namespace,
+                operation: failure.operation,
+                cause: {
+                    kind: failure.cause.kind,
+                    message: failure.cause.message.slice(0, 1000),
+                },
+                rawCause: sandboxOperatorValue(failure.rawCause),
+            };
+            break;
+        case "Unknown":
+            error = {
+                kind: "unknown",
+                rawCause: sandboxOperatorValue(failure.rawCause),
+            };
+            break;
+    }
+    return z.json().parse({ ok: false, error });
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,41 @@
+import type { input, output, ZodJSONSchema, ZodUnknown } from "zod";
+/** JSON value allowed to cross the sandbox and capability boundary. */
+export type MyceliumJsonValue = output<ZodJSONSchema>;
+/** Untrusted value supplied by or returned from a host sandbox boundary. */
+export type SandboxValue = input<ZodUnknown>;
+/** One invocation binding visible to the host-provided sandbox. */
+export type SandboxBinding = (input: SandboxValue) => Promise<MyceliumJsonValue>;
+/** Request crossing the root Promise-shaped sandbox seam. */
+export type SandboxRequest = Readonly<{
+    /** Fresh identity shared by the request and every bound operation call. */
+    executionId: string;
+    /** Model-authored program to evaluate inside the host sandbox. */
+    code: string;
+    /** Effective Mycelium execution budget; cancellation remains authoritative. */
+    timeoutMs: number;
+    /** Transport aliases mapped to flat relative operation paths. */
+    bindings: Readonly<Record<string, Readonly<Record<string, SandboxBinding>>>>;
+    /** Logical namespace path for each transport alias; defaults to `[alias]`. */
+    namespacePaths?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Every bound execution alias mapped to its stable module id. Always
+     * present on a request built by `runExecution`; optional only so a
+     * hand-built request from an older call site keeps compiling.
+     */
+    modules?: Readonly<Record<string, string>>;
+    /**
+     * Stable Session identity for this run; null for session-free hosts.
+     * Always present on a request built by `runExecution`; optional only so a
+     * hand-built request from an older call site keeps compiling.
+     */
+    sessionId?: string | null;
+}>;
+/** Promise-shaped sandbox interface implemented by a host or stranger. */
+export type Sandbox = Readonly<{
+    /** Operator identity of this transport. */
+    adapter?: string;
+    /** Source revision supplied by the host build. */
+    buildSha?: string;
+    /** Evaluate one bounded program and settle only after cancellation is observed. */
+    execute: (request: SandboxRequest, signal: AbortSignal) => Promise<SandboxValue>;
+}>;

package/dist/sandbox.js

@@ -0,0 +1 @@
+export {};

package/dist/semaphore-transition.d.ts

@@ -0,0 +1,7 @@
+import * as Effect from "effect/Effect";
+import * as Semaphore from "effect/Semaphore";
+/**
+ * Serialize a synchronous state claim and settle its Effect outside the gate.
+ * Interruption cannot release the caller until settlement finishes.
+ */
+export declare function claimThenSettle<A, B, E>(gate: Semaphore.Semaphore, claim: () => A, settle: (claimed: A) => Effect.Effect<B, E>): Effect.Effect<B, E>;

package/dist/semaphore-transition.js

@@ -0,0 +1,9 @@
+import * as Effect from "effect/Effect";
+import * as Semaphore from "effect/Semaphore";
+/**
+ * Serialize a synchronous state claim and settle its Effect outside the gate.
+ * Interruption cannot release the caller until settlement finishes.
+ */
+export function claimThenSettle(gate, claim, settle) {
+    return Effect.uninterruptibleMask((restore) => restore(gate.take(1)).pipe(Effect.flatMap(() => Effect.sync(claim).pipe(Effect.ensuring(gate.release(1)))), Effect.flatMap(settle)));
+}

package/dist/source-runtime.d.ts

@@ -0,0 +1,28 @@
+import * as Effect from "effect/Effect";
+import type { CapabilitySession, CapabilitySource } from "./capability-source.js";
+import { type CompiledSurface } from "./compiler.js";
+import { type MyceliumError } from "./errors.js";
+import { type ExecuteDoor } from "./execute-tool.js";
+import type { AccessOptions } from "./access.js";
+import type { BackingWorkTracker } from "./internal/execution-lifecycle.js";
+import type { EffectSandbox } from "./runtime.js";
+import type { ModuleRegistration } from "./registration.js";
+/** Coherent candidate revision built from static and acquired modules. */
+export type SourceCandidate = Readonly<{
+    readonly compiled: CompiledSurface;
+    readonly executeDoor: ExecuteDoor;
+    readonly isStale: () => boolean;
+    readonly close: () => Effect.Effect<void, MyceliumError>;
+}>;
+/** Inputs needed to build one off-to-the-side candidate revision. */
+export type SourceCandidateOptions = Readonly<{
+    readonly modules: readonly ModuleRegistration[];
+    readonly sources: readonly CapabilitySource[];
+    readonly session?: CapabilitySession | undefined;
+    readonly sandbox: EffectSandbox;
+    readonly backingWork: BackingWorkTracker;
+    readonly precompiled?: CompiledSurface;
+    readonly access: AccessOptions;
+}>;
+/** Acquire one non-stale candidate or fail after one bounded retry. */
+export declare function acquireSourceCandidate(options: SourceCandidateOptions): Effect.Effect<SourceCandidate, MyceliumError>;