@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/docs/api/sandbox-guest.md

@@ -0,0 +1,191 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / sandbox-guest
+
+# sandbox-guest
+
+## Variables
+
+### 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"
+>;
+```
+
+Closed guest envelope: guest exceptions cannot masquerade as host failures.
+
+---
+
+### sandboxNamespaceSegmentSchema
+
+```ts
+const sandboxNamespaceSegmentSchema: ZodString;
+```
+
+Parsed guest namespace segments; callbacks never cross this wire.
+
+---
+
+### sandboxTransportAliasSchema
+
+```ts
+const sandboxTransportAliasSchema: ZodString;
+```
+
+A transport alias is interpolated as a strict JavaScript binding identifier.
+
+---
+
+### sandboxNamespacePathsSchema
+
+```ts
+const sandboxNamespacePathsSchema: ZodRecord<ZodString, ZodArray<ZodString>>;
+```
+
+Transport aliases mapped to their logical namespace paths.
+
+---
+
+### sandboxBindingNamesSchema
+
+```ts
+const sandboxBindingNamesSchema: ZodRecord<ZodString, ZodArray<ZodString>>;
+```
+
+Serializable flat transport table; operation keys may have any namespace depth.
+
+## Functions
+
+### submittedSourceLocation()
+
+```ts
+function submittedSourceLocation(
+  normalized,
+  submitted,
+): Readonly<{
+  line: number;
+  column: number;
+  excerpt: string;
+}> | null;
+```
+
+Locate syntax in the submitted code, accounting for Codemode's normalization.
+
+#### Parameters
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `normalized` | `string` |
+| `submitted`  | `string` |
+
+#### Returns
+
+\| `Readonly`\<\{ `line`: `number`; `column`: `number`; `excerpt`: `string`;
+\}\> \| `null`
+
+---
+
+### sandboxBindingNames()
+
+```ts
+function sandboxBindingNames<A>(
+  bindings,
+): Readonly<Record<string, readonly string[]>>;
+```
+
+Serializable operation names; callbacks stay in the host's existing binding
+table.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `A`            |
+
+#### Parameters
+
+| Parameter  | Type                                                                        |
+| ---------- | --------------------------------------------------------------------------- |
+| `bindings` | `Readonly`\<`Record`\<`string`, `Readonly`\<`Record`\<`string`, `A`\>\>\>\> |
+
+#### Returns
+
+`Readonly`\<`Record`\<`string`, readonly `string`[]\>\>
+
+---
+
+### sandboxProviderOperationName()
+
+```ts
+function sandboxProviderOperationName(operation): string;
+```
+
+Injective provider identifier: Codemode sanitizes dotted function names.
+
+#### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `operation` | `string` |
+
+#### Returns
+
+`string`
+
+---
+
+### sandboxGuestProgram()
+
+```ts
+function sandboxGuestProgram(
+  normalized,
+  bindings?,
+  namespacePaths?,
+  transportName?,
+): string;
+```
+
+Capture name and text inside the guest, before Codemode erases Error.name.
+
+#### Parameters
+
+| Parameter        | Type                                                    |
+| ---------------- | ------------------------------------------------------- |
+| `normalized`     | `string`                                                |
+| `bindings`       | `Readonly`\<`Record`\<`string`, readonly `string`[]\>\> |
+| `namespacePaths` | `Readonly`\<`Record`\<`string`, readonly `string`[]\>\> |
+| `transportName?` | (`operation`) => `string`                               |
+
+#### Returns
+
+`string`

package/docs/api/sandbox-wire.md

@@ -0,0 +1,117 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / sandbox-wire
+
+# sandbox-wire
+
+## Type Aliases
+
+### SandboxWire
+
+```ts
+type SandboxWire = z.output<typeof sandboxWireSchema>;
+```
+
+Typed, decoded host wire value.
+
+## Variables
+
+### sandboxWireSchema
+
+```ts
+const sandboxWireSchema: ZodDiscriminatedUnion<
+  [
+    ZodObject<
+      {
+        ok: ZodLiteral<true>;
+        value: ZodJSONSchema;
+      },
+      $strict
+    >,
+    ZodObject<
+      {
+        ok: ZodLiteral<false>;
+        error: ZodDiscriminatedUnion<
+          [
+            ZodObject<
+              {
+                kind: ZodLiteral<"invalid_source">;
+                line: ZodNumber;
+                column: ZodNumber;
+                excerpt: ZodString;
+              },
+              $strict
+            >,
+            ZodObject<
+              {
+                kind: ZodLiteral<"guest_threw">;
+                name: ZodString;
+                message: ZodString;
+                transportMessage: ZodOptional<ZodString>;
+              },
+              $strict
+            >,
+            ZodObject<
+              {
+                kind: ZodLiteral<"deadline_exceeded">;
+                limitMs: ZodNumber;
+                elapsedMs: ZodNumber;
+              },
+              $strict
+            >,
+          ],
+          "kind"
+        >;
+      },
+      $strict
+    >,
+  ],
+  "ok"
+>;
+```
+
+The host-to-host result contract; raw diagnostic fields never go to guest code.
+
+## Functions
+
+### sandboxWireFailure()
+
+```ts
+function sandboxWireFailure(error): SandboxFailure;
+```
+
+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`; \} |
+
+#### Returns
+
+[`SandboxFailure`](sandbox-failure.md#sandboxfailure)
+
+---
+
+### sandboxFailureWire()
+
+```ts
+function sandboxFailureWire(failure): JSONType;
+```
+
+Host-only encoding; the guest receives only the admitted diagnostic text.
+
+#### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `failure` | [`SandboxFailure`](sandbox-failure.md#sandboxfailure) |
+
+#### Returns
+
+`JSONType`

package/docs/api/sandbox.md

@@ -0,0 +1,81 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / sandbox
+
+# sandbox
+
+## Type Aliases
+
+### MyceliumJsonValue
+
+```ts
+type MyceliumJsonValue = output<ZodJSONSchema>;
+```
+
+JSON value allowed to cross the sandbox and capability boundary.
+
+---
+
+### SandboxValue
+
+```ts
+type SandboxValue = input<ZodUnknown>;
+```
+
+Untrusted value supplied by or returned from a host sandbox boundary.
+
+---
+
+### SandboxBinding
+
+```ts
+type SandboxBinding = (input) => Promise<MyceliumJsonValue>;
+```
+
+One invocation binding visible to the host-provided sandbox.
+
+#### Parameters
+
+| Parameter | Type                            |
+| --------- | ------------------------------- |
+| `input`   | [`SandboxValue`](#sandboxvalue) |
+
+#### Returns
+
+`Promise`\<[`MyceliumJsonValue`](#myceliumjsonvalue)\>
+
+---
+
+### SandboxRequest
+
+```ts
+type SandboxRequest = Readonly<{
+  executionId: string;
+  code: string;
+  timeoutMs: number;
+  bindings: Readonly<Record<string, Readonly<Record<string, SandboxBinding>>>>;
+  namespacePaths?: Readonly<Record<string, readonly string[]>>;
+  modules?: Readonly<Record<string, string>>;
+  sessionId?: string | null;
+}>;
+```
+
+Request crossing the root Promise-shaped sandbox seam.
+
+---
+
+### Sandbox
+
+```ts
+type Sandbox = Readonly<{
+  adapter?: string;
+  buildSha?: string;
+  execute: (request, signal) => Promise<SandboxValue>;
+}>;
+```
+
+Promise-shaped sandbox interface implemented by a host or stranger.

package/docs/api/semaphore-transition.md

@@ -0,0 +1,40 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / semaphore-transition
+
+# semaphore-transition
+
+## Functions
+
+### claimThenSettle()
+
+```ts
+function claimThenSettle<A, B, E>(gate, claim, settle): Effect<B, E>;
+```
+
+Serialize a synchronous state claim and settle its Effect outside the gate.
+Interruption cannot release the caller until settlement finishes.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `A`            |
+| `B`            |
+| `E`            |
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `gate`    | `Semaphore`                         |
+| `claim`   | () => `A`                           |
+| `settle`  | (`claimed`) => `Effect`\<`B`, `E`\> |
+
+#### Returns
+
+`Effect`\<`B`, `E`\>

package/docs/api/testing.md

@@ -0,0 +1,72 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / testing
+
+# testing
+
+## Type Aliases
+
+### DirectSandboxCallback
+
+```ts
+type DirectSandboxCallback = (bindings, signal) => Promise<SandboxValue>;
+```
+
+A test callback receives the admitted bindings and cancellation.
+
+#### Parameters
+
+| Parameter  | Type                                                          |
+| ---------- | ------------------------------------------------------------- |
+| `bindings` | [`SandboxRequest`](sandbox.md#sandboxrequest)\[`"bindings"`\] |
+| `signal`   | `AbortSignal`                                                 |
+
+#### Returns
+
+`Promise`\<[`SandboxValue`](sandbox.md#sandboxvalue)\>
+
+## Functions
+
+### directSandbox()
+
+```ts
+function directSandbox(callback): Sandbox;
+```
+
+Dispatch a known-binding callback directly in this process. NOT isolation:
+submitted code is ignored, and the callback retains all host privileges. Use
+only trusted tests and examples, never model-authored code execution.
+
+#### Parameters
+
+| Parameter  | Type                                              |
+| ---------- | ------------------------------------------------- |
+| `callback` | [`DirectSandboxCallback`](#directsandboxcallback) |
+
+#### Returns
+
+[`Sandbox`](sandbox.md#sandbox)
+
+---
+
+### rejectingSandbox()
+
+```ts
+function rejectingSandbox(message): Sandbox;
+```
+
+A test transport that always refuses execution with the supplied message.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `message` | `string` |
+
+#### Returns
+
+[`Sandbox`](sandbox.md#sandbox)

package/docs/api/workers.md

@@ -0,0 +1,55 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / workers
+
+# workers
+
+## Type Aliases
+
+### CodemodeLoader
+
+```ts
+type CodemodeLoader = WorkerLoader;
+```
+
+The Worker Loader binding Codemode runs guests on.
+
+---
+
+### CodemodeSandboxOptions
+
+```ts
+type CodemodeSandboxOptions = Readonly<{
+  localDevUnenforcedLimits?: readonly (
+    "cpu" | "memory" | "output" | "cancel"
+  )[];
+}>;
+```
+
+Local development facts supplied by the host, never by guest code.
+
+## Functions
+
+### createCodemodeSandbox()
+
+```ts
+function createCodemodeSandbox(loader, adapter?, options?): Sandbox;
+```
+
+Construct a network-isolated Codemode sandbox over a Worker Loader.
+
+#### Parameters
+
+| Parameter | Type                                                | Default value        |
+| --------- | --------------------------------------------------- | -------------------- |
+| `loader`  | `WorkerLoader`                                      | `undefined`          |
+| `adapter` | `string`                                            | `"codemode-workerd"` |
+| `options` | [`CodemodeSandboxOptions`](#codemodesandboxoptions) | `{}`                 |
+
+#### Returns
+
+[`Sandbox`](sandbox.md#sandbox)

package/package.json

@@ -1,6 +1,135 @@
 {
   "name": "@fungi.computer/mycelium",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Effect-native scoped capability lifecycle with a Zod-authored execute door",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js"
+    },
+    "./effect": {
+      "types": "./dist/effect.d.ts",
+      "import": "./dist/effect.js"
+    },
+    "./remote": {
+      "types": "./dist/remote.d.ts",
+      "import": "./dist/remote.js"
+    },
+    "./semaphore-transition": {
+      "types": "./dist/semaphore-transition.d.ts",
+      "import": "./dist/semaphore-transition.js"
+    },
+    "./sandbox-guest": {
+      "types": "./dist/sandbox-guest.d.ts",
+      "import": "./dist/sandbox-guest.js"
+    },
+    "./sandbox-wire": {
+      "types": "./dist/sandbox-wire.d.ts",
+      "import": "./dist/sandbox-wire.js"
+    },
+    "./sandbox-failure": {
+      "types": "./dist/sandbox-failure.d.ts",
+      "import": "./dist/sandbox-failure.js"
+    },
+    "./sandbox-boundary": {
+      "types": "./dist/sandbox-boundary.d.ts",
+      "import": "./dist/sandbox-boundary.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./workers": {
+      "types": "./dist/workers/index.d.ts",
+      "import": "./dist/workers/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox.d.ts",
+      "import": "./dist/sandbox.js"
+    }
+  },
+  "imports": {
+    "#build-identity": {
+      "node": "./dist/internal/build-identity.node.js",
+      "default": "./dist/internal/build-identity.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE",
+    "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",
+    "effect": "4.0.2",
+    "zod": "4.4.3",
+    "acorn": "8.18.0",
+    "@cloudflare/codemode": "0.5.1",
+    "@modelcontextprotocol/server": "2.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "1.1.2",
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11",
+    "@cloudflare/workers-types": "5.20260828.1",
+    "@modelcontextprotocol/client": "2.0.0"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/mycelium.git"
+  },
+  "fungi": {
+    "build": {
+      "typescript": [
+        "src/workers/tsconfig.json"
+      ]
+    }
+  },
+  "scripts": {
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p src/workers/tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc -p src/workers/tsconfig.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "vitest run && pnpm run test:workers",
+    "test:workers": "vitest run --config test/vitest.workers.config.mts",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "pack": "pnpm run build && node scripts/stamp-build.mjs && mkdir -p ../../.botanical/mycelium-pack && pnpm pack --pack-destination ../../.botanical/mycelium-pack",
+    "smoke": "node --input-type=module -e \"import('./dist/index.js').then(({Mycelium}) => { if (!Mycelium) process.exit(1); })\"",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }