@fungi.computer/mycelium 0.0.2 → 0.2.0

package/dist/sandbox-wire.js

@@ -1,6 +1,6 @@
 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";
+import { SourceInvalid, DeadlineExceeded, SandboxBusy, 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() }),
@@ -24,6 +24,12 @@ export const sandboxWireSchema = z.discriminatedUnion("ok", [
                 limitMs: z.number().int().positive(),
                 elapsedMs: z.number().nonnegative(),
             }),
+            z.strictObject({
+                kind: z.literal("sandbox_busy"),
+                code: z.literal("sandbox-busy"),
+                capacity: z.int().positive(),
+                waitedMs: z.number().nonnegative(),
+            }),
             z.strictObject({
                 kind: z.literal("result_not_json"),
                 valueKind: z.string().max(80),
@@ -82,6 +88,11 @@ export function sandboxWireFailure(error) {
             return sandboxGuestFailure(error);
         case "deadline_exceeded":
             return new DeadlineExceeded(error);
+        case "sandbox_busy":
+            return new SandboxBusy({
+                capacity: error.capacity,
+                waitedMs: error.waitedMs,
+            });
         case "result_not_json":
             return new ResultNotJson({
                 kind: error.valueKind,
@@ -131,6 +142,14 @@ export function sandboxFailureWire(failure) {
                 elapsedMs: failure.elapsedMs,
             };
             break;
+        case "SandboxBusy":
+            error = {
+                kind: "sandbox_busy",
+                code: failure.code,
+                capacity: failure.capacity,
+                waitedMs: failure.waitedMs,
+            };
+            break;
         case "Cancelled":
             error = { kind: "cancelled", by: failure.by };
             break;

package/dist/source-runtime.js

@@ -9,11 +9,11 @@ function compareCodeUnits(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
 const maximumCapabilitySources = 128;
-const sourceIdSchema = z.string().min(1).max(160);
-const sourceSnapshotSchema = z.object({
+const sourceIdSchema = z.lazy(() => z.string().min(1).max(160));
+const sourceSnapshotSchema = z.lazy(() => z.object({
     version: z.string().min(1).max(160),
     modules: z.array(z.unknown()),
-});
+}));
 const maximumCandidateModules = 1_000;
 function validateSources(input) {
     if (input.length > maximumCapabilitySources) {

package/docs/api/index.md

@@ -378,7 +378,6 @@ type AccessOptions = Readonly<{
   sessionGrants?: (context) => Grants;
   beforeCall?: (signal) => Promise<void>;
   confirmWrites?: boolean;
-  approvedWrites?: (context) => readonly string[];
   confirm?: (request, signal) => Promise<boolean>;
   onRefused?: (refusal, context) => void;
 }>;
@@ -387,7 +386,8 @@ type AccessOptions = Readonly<{
 Host-supplied access data and the one way to ask a person. Every field is
 optional: hosted defaults allow unnamed modules, and no `confirm` means an
 operation requiring approval is refused, never run unasked. MCP catalogs
-explicitly default unnamed modules to none and require approval for writes.
+explicitly default unnamed modules to none. Native hosts own durable approval
+policy for admitted writes; explicit author confirmation still uses this port.
 
 ---
 
@@ -503,10 +503,11 @@ Closed failure vocabulary for the first Mycelium runtime slice.
 type ExecutionOptions = Readonly<{
   timeoutMs?: number;
   abortGraceMs?: number;
-}>;
+}> &
+  SandboxAdmissionOptions;
 ```
 
-Host-selectable execution limits; neither budget can be disabled.
+Host execution limits plus the reserved, host-only admission contract.
 
 ---
 
@@ -515,7 +516,7 @@ Host-selectable execution limits; neither budget can be disabled.
 ```ts
 type CollectedImage = Readonly<{
   data: string;
-  mimeType: "image/jpeg" | "image/png" | "image/webp";
+  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
   path: string;
   bytes: number;
 }>;
@@ -543,10 +544,14 @@ The collector as one execution's operations see it: push only.
 type InvocationContext = Readonly<{
   executionId: string;
   toolCallId?: string;
+  operationOrdinal?: number;
   toolCallCode?: string;
   deadlineAt: number | null;
   signal: AbortSignal;
   images?: ExecutionImages;
+  output?: Readonly<{
+    write: (stream, bytes) => void;
+  }>;
 }>;
 ```
 
@@ -835,6 +840,32 @@ Asked before every call of a gated module's operations.
 
 ---
 
+### SandboxAdmissionOptions
+
+```ts
+type SandboxAdmissionOptions = Readonly<{
+  sandboxCapacity?: number;
+  admissionWaitMs?: number;
+}>;
+```
+
+Host-owned admission inputs; never part of guest execute arguments.
+
+---
+
+### SandboxAdmissionPolicy
+
+```ts
+type SandboxAdmissionPolicy = Readonly<{
+  capacity: number;
+  waitMs: number;
+}>;
+```
+
+Captured once per runtime and shared across backing-work groups.
+
+---
+
 ### SandboxFailureEvent
 
 ```ts
@@ -925,6 +956,7 @@ const SandboxFailureEventSchema: Struct<{
       "SourceInvalid",
       "GuestThrew",
       "DeadlineExceeded",
+      "SandboxBusy",
       "Cancelled",
       "DispatchLost",
       "SandboxCrashed",
@@ -942,6 +974,31 @@ const SandboxFailureEventSchema: Struct<{
 
 Shared structural grammar for durable operator facts and client inspection.
 
+## Functions
+
+### normalizeSandboxAdmissionPolicy()
+
+```ts
+function normalizeSandboxAdmissionPolicy(
+  options,
+  availableCores?,
+): SandboxAdmissionPolicy;
+```
+
+Validate host policy and resolve defaults from a platform-owned core
+observation.
+
+#### Parameters
+
+| Parameter         | Type                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
+| `options`         | \| `Readonly`\<\{ `sandboxCapacity?`: `number`; `admissionWaitMs?`: `number`; \}\> \| `undefined` |
+| `availableCores?` | `number`                                                                                          |
+
+#### Returns
+
+[`SandboxAdmissionPolicy`](#sandboxadmissionpolicy)
+
 ## References
 
 ### sandboxFailure
@@ -1010,6 +1067,12 @@ Re-exports [DeadlineExceeded](sandbox-failure.md#deadlineexceeded)
 
 ---
 
+### SandboxBusy
+
+Re-exports [SandboxBusy](sandbox-failure.md#sandboxbusy)
+
+---
+
 ### Cancelled
 
 Re-exports [Cancelled](sandbox-failure.md#cancelled)

package/docs/api/mcp.md

@@ -44,7 +44,6 @@ type McpCatalogSnapshot = Readonly<{
   instructions: string;
   sources: readonly CapabilitySource[];
   grants: Grants;
-  approvedWrites?: readonly string[];
 }>;
 ```
 
@@ -93,7 +92,6 @@ type McpExecutionContext = Readonly<{
   onPart?: (part) => Promise<void>;
   access: Pick<AccessOptions, "confirm"> &
     Readonly<{
-      confirmWrites: true;
       beforeCall: (signal) => Promise<void>;
     }>;
 }>;

package/docs/api/sandbox-failure.md

@@ -312,6 +312,95 @@ Data.TaggedError("DeadlineExceeded").acknowledged;
 
 ---
 
+### SandboxBusy
+
+Admission expired before any sandbox work started.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new SandboxBusy(args): SandboxBusy;
+```
+
+###### Parameters
+
+| Parameter       | Type                                                                |
+| --------------- | ------------------------------------------------------------------- |
+| `args`          | \{ `ref?`: `string`; `capacity`: `number`; `waitedMs`: `number`; \} |
+| `args.ref?`     | `string`                                                            |
+| `args.capacity` | `number`                                                            |
+| `args.waitedMs` | `number`                                                            |
+
+###### Returns
+
+[`SandboxBusy`](#sandboxbusy)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxBusy")<
+  SandboxFailureReference & {
+    readonly capacity: number;
+    readonly waitedMs: number;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxBusy").ref;
+```
+
+##### capacity
+
+```ts
+readonly capacity: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxBusy").capacity;
+```
+
+##### waitedMs
+
+```ts
+readonly waitedMs: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxBusy").waitedMs;
+```
+
+##### code
+
+```ts
+readonly code: "sandbox-busy" = "sandbox-busy";
+```
+
+Stable contention code, not a sandbox health failure.
+
+---
+
 ### Cancelled
 
 The invocation owner accepted cancellation.
@@ -1078,6 +1167,7 @@ type SandboxFailure =
   | SourceInvalid
   | GuestThrew
   | DeadlineExceeded
+  | SandboxBusy
   | Cancelled
   | DispatchLost
   | SandboxCrashed

package/docs/api/sandbox-guest.md

@@ -13,32 +13,34 @@
 ### sandboxGuestResultSchema
 
 ```ts
-const sandboxGuestResultSchema: ZodDiscriminatedUnion<
-  [
-    ZodObject<
-      {
-        ok: ZodLiteral<true>;
-        value: ZodUnknown;
-      },
-      $strict
-    >,
-    ZodObject<
-      {
-        ok: ZodLiteral<false>;
-        error: ZodObject<
-          {
-            kind: ZodLiteral<"guest_threw">;
-            name: ZodString;
-            message: ZodString;
-            transportMessage: ZodOptional<ZodString>;
-          },
-          $strict
-        >;
-      },
-      $strict
-    >,
-  ],
-  "ok"
+const sandboxGuestResultSchema: ZodLazy<
+  ZodDiscriminatedUnion<
+    [
+      ZodObject<
+        {
+          ok: ZodLiteral<true>;
+          value: ZodUnknown;
+        },
+        $strict
+      >,
+      ZodObject<
+        {
+          ok: ZodLiteral<false>;
+          error: ZodObject<
+            {
+              kind: ZodLiteral<"guest_threw">;
+              name: ZodString;
+              message: ZodString;
+              transportMessage: ZodOptional<ZodString>;
+            },
+            $strict
+          >;
+        },
+        $strict
+      >,
+    ],
+    "ok"
+  >
 >;
 ```
 
@@ -49,7 +51,7 @@ Closed guest envelope: guest exceptions cannot masquerade as host failures.
 ### sandboxNamespaceSegmentSchema
 
 ```ts
-const sandboxNamespaceSegmentSchema: ZodString;
+const sandboxNamespaceSegmentSchema: ZodLazy<ZodString>;
 ```
 
 Parsed guest namespace segments; callbacks never cross this wire.
@@ -59,7 +61,7 @@ Parsed guest namespace segments; callbacks never cross this wire.
 ### sandboxTransportAliasSchema
 
 ```ts
-const sandboxTransportAliasSchema: ZodString;
+const sandboxTransportAliasSchema: ZodLazy<ZodString>;
 ```
 
 A transport alias is interpolated as a strict JavaScript binding identifier.
@@ -69,7 +71,9 @@ A transport alias is interpolated as a strict JavaScript binding identifier.
 ### sandboxNamespacePathsSchema
 
 ```ts
-const sandboxNamespacePathsSchema: ZodRecord<ZodString, ZodArray<ZodString>>;
+const sandboxNamespacePathsSchema: ZodLazy<
+  ZodRecord<ZodLazy<ZodString>, ZodArray<ZodLazy<ZodString>>>
+>;
 ```
 
 Transport aliases mapped to their logical namespace paths.
@@ -79,7 +83,9 @@ Transport aliases mapped to their logical namespace paths.
 ### sandboxBindingNamesSchema
 
 ```ts
-const sandboxBindingNamesSchema: ZodRecord<ZodString, ZodArray<ZodString>>;
+const sandboxBindingNamesSchema: ZodLazy<
+  ZodRecord<ZodLazy<ZodString>, ZodArray<ZodString>>
+>;
 ```
 
 Serializable flat transport table; operation keys may have any namespace depth.

package/docs/api/sandbox-wire.md

@@ -88,9 +88,9 @@ Convert one validated wire failure into the shared error channel.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `error`   | \| \{ `kind`: `"invalid_source"`; `line`: `number`; `column`: `number`; `excerpt`: `string`; \} \| \{ `kind`: `"guest_threw"`; `name`: `string`; `message`: `string`; `transportMessage?`: `string`; \} \| \{ `kind`: `"deadline_exceeded"`; `limitMs`: `number`; `elapsedMs`: `number`; \} \| \{ `kind`: `"result_not_json"`; `valueKind`: `string`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"sandbox_crashed"`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"bad_response"`; `reason`: `string`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"dispatch_lost"`; `elapsedMs`: `number`; `transport`: `string`; `errno?`: `string`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"cancelled"`; `by`: `"caller"` \| `"operator"`; \} \| \{ `kind`: `"result_too_large"`; `size`: `number`; \} \| \{ `kind`: `"capability_failed"`; `namespace`: `string`; `operation`: `string`; `cause`: \{ `kind`: `"Files"` \| `"Forage"` \| `"InvalidInput"` \| `"Unavailable"` \| `"OperationFailed"`; `message`: `string`; \}; `rawCause`: `JSONType`; \} \| \{ `kind`: `"unknown"`; `rawCause`: `JSONType`; \} |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `error`   | \| \{ `kind`: `"invalid_source"`; `line`: `number`; `column`: `number`; `excerpt`: `string`; \} \| \{ `kind`: `"guest_threw"`; `name`: `string`; `message`: `string`; `transportMessage?`: `string`; \} \| \{ `kind`: `"deadline_exceeded"`; `limitMs`: `number`; `elapsedMs`: `number`; \} \| \{ `kind`: `"sandbox_busy"`; `code`: `"sandbox-busy"`; `capacity`: `number`; `waitedMs`: `number`; \} \| \{ `kind`: `"result_not_json"`; `valueKind`: `string`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"sandbox_crashed"`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"bad_response"`; `reason`: `string`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"dispatch_lost"`; `elapsedMs`: `number`; `transport`: `string`; `errno?`: `string`; `rawCause`: `JSONType`; \} \| \{ `kind`: `"cancelled"`; `by`: `"caller"` \| `"operator"`; \} \| \{ `kind`: `"result_too_large"`; `size`: `number`; \} \| \{ `kind`: `"capability_failed"`; `namespace`: `string`; `operation`: `string`; `cause`: \{ `kind`: `"Files"` \| `"Forage"` \| `"InvalidInput"` \| `"Unavailable"` \| `"OperationFailed"`; `message`: `string`; \}; `rawCause`: `JSONType`; \} \| \{ `kind`: `"unknown"`; `rawCause`: `JSONType`; \} |
 
 #### Returns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/mycelium",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Effect-native scoped capability lifecycle with a Zod-authored execute door",
   "type": "module",
@@ -61,6 +61,10 @@
     }
   },
   "imports": {
+    "#host-cores": {
+      "node": "./dist/internal/host-cores.node.js",
+      "default": "./dist/internal/host-cores.js"
+    },
     "#build-identity": {
       "node": "./dist/internal/build-identity.node.js",
       "default": "./dist/internal/build-identity.js"
@@ -74,10 +78,10 @@
     "THIRD_PARTY_NOTICES"
   ],
   "dependencies": {
-    "@fungi.computer/cairn": "0.0.1",
-    "@fungi.computer/forage": "0.0.2",
-    "@fungi.computer/mule": "0.0.2",
-    "@fungi.computer/puffball": "0.0.2",
+    "@fungi.computer/cairn": "0.1.0",
+    "@fungi.computer/forage": "0.2.0",
+    "@fungi.computer/mule": "0.1.0",
+    "@fungi.computer/puffball": "0.2.0",
     "effect": "4.0.2",
     "zod": "4.4.3",
     "acorn": "8.18.0",