apps 1.0.0-beta.1 → 1.0.0-beta.2

package/src/manifest/index.ts

@@ -1,11 +1,13 @@
 /**
- * Manifest: execute an authored app folder, read its registry, validate
- * every claim, and emit the deterministic publish manifest. Defines run
- * without user context; platform services begin at this boundary.
+ * Manifest: execute an authored app folder and project its registry.
+ * This module owns exactly what differs on a host with a filesystem —
+ * finding and importing authored modules. Everything after the modules
+ * load (validation, canonicalization, digesting) is the shared
+ * execution core in ../runtime; sandboxed guests run that same core.
  */
 
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { Crypto, Effect, FileSystem, Schema, Semaphore } from "effect";
+import { Effect, FileSystem, MutableRef, Semaphore } from "effect";
 import {
   __enterFile,
   __leaveFile,
@@ -13,118 +15,51 @@ import {
   setActiveRegistry,
   type Registry,
 } from "../authoring/index";
-import { collectRegistry, type InputSchemaCompilation } from "./collect";
-import {
-  JsonSchemaObject,
-  PublishError,
-  type AppManifestResult,
-  type JsonSchemaObject as JsonSchemaObjectType,
-} from "./contract";
+import { manifestOf } from "../runtime/index";
+import { PublishError, type AppManifestResult } from "./contract";
 
 export * from "./contract";
 
-interface StandardJsonSchemaCapable {
-  readonly "~standard": {
-    readonly jsonSchema?: {
-      readonly input: (options: { readonly target: string }) => unknown;
-    };
-  };
-}
-
-const hasStandardJsonSchema = (input: object): input is StandardJsonSchemaCapable =>
-  "~standard" in input &&
-  typeof (input as StandardJsonSchemaCapable)["~standard"].jsonSchema?.input === "function";
-
-const compileInputSchema = (
-  input: object,
-  where: string,
-): InputSchemaCompilation => {
-  if ("~standard" in input) {
-    if (!hasStandardJsonSchema(input))
-      return {
-        problem: `${where}: input is a Standard Schema without the jsonSchema extension — use a library that implements it (zod 4+, effect Schema) or pass raw JSON schema`,
-      };
-  }
-
-  try {
-    const compiled = strictify(
-      hasStandardJsonSchema(input)
-        ? input["~standard"].jsonSchema!.input({ target: "draft-2020-12" })
-        : structuredClone(input),
-    );
-    return { value: Schema.decodeUnknownSync(JsonSchemaObject)(compiled) as JsonSchemaObjectType };
-  } catch (error) {
-    return { problem: schemaPublishProblem(where, error) };
-  }
-};
-
-const schemaPublishProblem = (where: string, error: unknown): string =>
-  `${where}: input schema could not compile to JSON schema (${
-    error instanceof Error ? error.message : String(error)
-  })`;
-
-const strictify = (node: unknown): unknown => {
-  if (typeof node !== "object" || node === null) return node;
-  if (Array.isArray(node)) return node.map(strictify);
-  const object = { ...(node as Record<string, unknown>) };
-  if (object.type === "object" && object.additionalProperties === undefined)
-    object.additionalProperties = false;
-  for (const key of ["items", "anyOf", "oneOf", "allOf"])
-    if (key in object) object[key] = strictify(object[key]);
-  for (const key of ["properties", "$defs"])
-    if (object[key] !== undefined && typeof object[key] === "object" && object[key] !== null)
-      object[key] = Object.fromEntries(
-        Object.entries(object[key] as Record<string, unknown>).map(([name, value]) => [
-          name,
-          strictify(value),
-        ]),
-      );
-  return object;
-};
-
-const digestOf = (content: string): Effect.Effect<string, never, Crypto.Crypto> =>
-  Effect.gen(function* () {
-    const crypto = yield* Crypto.Crypto;
-    const bytes = yield* Effect.orDie(
-      crypto.digest("SHA-256", new TextEncoder().encode(content)),
-    );
-    return Array.from(bytes.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("");
-  });
+const moduleProblem = (where: string, error: unknown): string =>
+  `${where}: failed to execute (${error instanceof Error ? error.message : String(error)})`;
 
+/**
+ * Module execution is process-global twice over: the authoring
+ * registry is a singleton the imported modules write into, and the
+ * ESM module cache is shared. One permit serializes loads; the nonce
+ * and first-import memo make re-imports observable across runs.
+ * Module-scoped by necessity — this state IS process state.
+ */
 const loadPermit = Semaphore.makeUnsafe(1);
-let runNonce = 0;
-const baseAppImports = new Set<string>();
-
-const moduleFailure = (where: string, error: unknown): PublishError =>
-  new PublishError({
-    problems: [
-      `${where}: failed to execute (${error instanceof Error ? error.message : String(error)})`,
-    ],
-  });
+const runNonce = MutableRef.make(0);
+const importedAppUrls = MutableRef.make<ReadonlySet<string>>(new Set());
 
 const canonicalModuleUrl = (
   path: string,
   where: string,
 ): Effect.Effect<URL, PublishError, FileSystem.FileSystem> =>
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const realPath = yield* fs.realPath(path).pipe(
-      Effect.mapError((error) => moduleFailure(where, error)),
-    );
-    return pathToFileURL(realPath);
-  });
+  FileSystem.FileSystem.pipe(
+    Effect.flatMap((fs) => fs.realPath(path)),
+    Effect.map(pathToFileURL),
+    Effect.mapError((error) => new PublishError({ problems: [moduleProblem(where, error)] })),
+  );
 
 const importModule = (specifier: string, where: string): Effect.Effect<void, PublishError> =>
   Effect.tryPromise({
-    try: () => import(specifier).then(() => undefined),
-    catch: (error) => moduleFailure(where, error),
-  });
+    try: () => import(specifier),
+    catch: (error) => new PublishError({ problems: [moduleProblem(where, error)] }),
+  }).pipe(Effect.asVoid);
 
-const recordModuleProblems = (
+/** Import one authored module, converting failure into registry problems. */
+const executeModule = (
   registry: Registry,
-  effect: Effect.Effect<void, PublishError, FileSystem.FileSystem>,
+  where: string,
+  load: Effect.Effect<void, PublishError, FileSystem.FileSystem>,
 ): Effect.Effect<void, never, FileSystem.FileSystem> =>
-  effect.pipe(
+  Effect.suspend(() => {
+    __enterFile(where);
+    return load;
+  }).pipe(
     Effect.catchTag("PublishError", (error) =>
       Effect.sync(() => {
         registry.problems.push(...error.problems.map((message) => ({ message })));
@@ -132,58 +67,70 @@ const recordModuleProblems = (
     ),
   );
 
+/**
+ * The app entry loads through its plain canonical URL the first time
+ * so relative imports resolve normally, and through a nonce query on
+ * every later run so edits are observed instead of served stale from
+ * the module cache.
+ */
+const appEntrySpecifier = (appUrl: URL, nonce: number): string => {
+  const seen = MutableRef.get(importedAppUrls);
+  if (!seen.has(appUrl.href)) {
+    MutableRef.set(importedAppUrls, new Set([...seen, appUrl.href]));
+    return appUrl.href;
+  }
+  return `${fileURLToPath(appUrl)}?m=${nonce}`;
+};
+
 const executeModules = (
   appDir: string,
   files: readonly string[],
 ): Effect.Effect<Registry, never, FileSystem.FileSystem> =>
   loadPermit.withPermit(
-    Effect.uninterruptibleMask((restore) =>
-      Effect.gen(function* () {
+    Effect.acquireUseRelease(
+      Effect.sync(() => {
         const registry = newRegistry();
-        const previous = yield* Effect.sync(() => setActiveRegistry(registry));
-        const nonce = yield* Effect.sync(() => ++runNonce);
-
-        const execute = Effect.gen(function* () {
-          __enterFile("app.ts");
-          yield* recordModuleProblems(
+        return { registry, previous: setActiveRegistry(registry) };
+      }),
+      ({ registry }) =>
+        Effect.gen(function* () {
+          const nonce = MutableRef.incrementAndGet(runNonce);
+          yield* executeModule(
             registry,
-            Effect.gen(function* () {
-              const appUrl = yield* canonicalModuleUrl(`${appDir}/app.ts`, "app.ts");
-              const baseUrl = appUrl.href;
-              const specifier = baseAppImports.has(baseUrl)
-                ? `${fileURLToPath(appUrl)}?m=${nonce}`
-                : baseUrl;
-              yield* importModule(specifier, "app.ts");
-              yield* Effect.sync(() => baseAppImports.add(baseUrl));
-            }),
+            "app.ts",
+            canonicalModuleUrl(`${appDir}/app.ts`, "app.ts").pipe(
+              Effect.flatMap((appUrl) => importModule(appEntrySpecifier(appUrl, nonce), "app.ts")),
+            ),
           );
-
           for (const file of files) {
             const where = `tools/${file}`;
-            __enterFile(where);
-            yield* recordModuleProblems(
+            yield* executeModule(
               registry,
-              Effect.gen(function* () {
-                const url = yield* canonicalModuleUrl(`${appDir}/tools/${file}`, where);
-                yield* importModule(`${fileURLToPath(url)}?m=${nonce}`, where);
-              }),
+              where,
+              canonicalModuleUrl(`${appDir}/tools/${file}`, where).pipe(
+                Effect.flatMap((url) => importModule(`${fileURLToPath(url)}?m=${nonce}`, where)),
+              ),
             );
           }
-        });
-
-        yield* restore(execute).pipe(
-          Effect.ensuring(
-            Effect.sync(() => {
-              __leaveFile();
-              setActiveRegistry(previous);
-            }),
-          ),
-        );
-        return registry;
-      }),
+          return registry;
+        }),
+      ({ previous }) =>
+        Effect.sync(() => {
+          __leaveFile();
+          setActiveRegistry(previous);
+        }),
     ),
   );
 
+const toolFiles = (
+  appDir: string,
+): Effect.Effect<readonly string[], PublishError, FileSystem.FileSystem> =>
+  FileSystem.FileSystem.pipe(
+    Effect.flatMap((fs) => fs.readDirectory(`${appDir}/tools`)),
+    Effect.mapError((error) => new PublishError({ problems: [`tools/: ${error.message}`] })),
+    Effect.map((entries) => entries.filter((file) => file.endsWith(".ts")).sort()),
+  );
+
 /** A registry and its validated public projection. @internal */
 export interface LoadedApp {
   readonly registry: Registry;
@@ -193,32 +140,17 @@ export interface LoadedApp {
 /** Loads an app once and returns both its live registry and manifest. @internal */
 export const loadApp = (
   appDir: string,
-): Effect.Effect<LoadedApp, PublishError, Crypto.Crypto | FileSystem.FileSystem> =>
+): Effect.Effect<LoadedApp, PublishError, FileSystem.FileSystem> =>
   Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const files = (yield* fs.readDirectory(`${appDir}/tools`).pipe(
-      Effect.mapError((error) => new PublishError({ problems: [`tools/: ${error.message}`] })),
-    ))
-      .filter((file) => file.endsWith(".ts"))
-      .sort();
+    const files = yield* toolFiles(appDir);
     const registry = yield* executeModules(appDir, files);
-    const collected = collectRegistry(registry, compileInputSchema);
-    if (collected.problems.length > 0)
-      return yield* new PublishError({ problems: collected.problems });
-    if (!("manifest" in collected))
-      return yield* Effect.die("validated registry projection unexpectedly missing");
-
-    return {
-      registry,
-      result: {
-        digest: `snap:${yield* digestOf(collected.canonical)}`,
-        ...collected.manifest,
-      },
-    };
+    const outcome = yield* Effect.promise(() => manifestOf(registry));
+    if (!outcome.ok) return yield* new PublishError({ problems: outcome.problems });
+    return { registry, result: outcome.result };
   });
 
 /** Executes an app and returns its deterministic publish manifest. */
 export const manifest = (
   appDir: string,
-): Effect.Effect<AppManifestResult, PublishError, Crypto.Crypto | FileSystem.FileSystem> =>
+): Effect.Effect<AppManifestResult, PublishError, FileSystem.FileSystem> =>
   Effect.map(loadApp(appDir), ({ result }) => result);

package/src/runner/index.ts

@@ -1,73 +1,21 @@
-import { Crypto, Effect, FileSystem } from "effect";
-import type { ToolSpec } from "../authoring/index";
+import { Effect, FileSystem } from "effect";
 import {
   loadApp,
   type LoadedApp,
   type PublishError,
 } from "../manifest/index";
-import { CallError, type AppRunner, type ToolCtx } from "./protocol";
+import { callTool, discoverTool, type CallOutcome } from "../runtime/index";
+import { CallError, type AppRunner } from "./protocol";
 
 export * from "./protocol";
 
-interface StandardSchemaCapable {
-  readonly "~standard": {
-    readonly validate: (
-      value: unknown,
-    ) =>
-      | { readonly value: unknown; readonly issues?: undefined }
-      | { readonly issues: ReadonlyArray<{ readonly message: string }> }
-      | Promise<
-          | { readonly value: unknown; readonly issues?: undefined }
-          | { readonly issues: ReadonlyArray<{ readonly message: string }> }
-        >;
-  };
-}
-
-const hasStandardValidate = (input: object): input is StandardSchemaCapable =>
-  "~standard" in input &&
-  typeof (input as StandardSchemaCapable)["~standard"].validate === "function";
-
-const parseInput = (name: string, spec: ToolSpec, input: unknown): Effect.Effect<unknown, CallError> => {
-  if (!hasStandardValidate(spec.input))
-    return Effect.fail(
-      new CallError({ target: name, reason: "input schema does not implement Standard Schema validate" }),
-    );
-  const standard = spec.input["~standard"];
-
-  return Effect.tryPromise({
-    try: () => Promise.resolve(standard.validate(input)),
-    catch: (error) =>
-      new CallError({
-        target: name,
-        reason: `input validation threw (${error instanceof Error ? error.message : String(error)})`,
-      }),
-  }).pipe(
-    Effect.flatMap((result) =>
-      result.issues === undefined
-        ? Effect.succeed(result.value)
-        : Effect.fail(
-            new CallError({
-              target: name,
-              reason: `invalid input (${result.issues.map((issue) => issue.message).join("; ")})`,
-            }),
-          ),
-    ),
-  );
-};
-
 /** Creates a permissive in-process runner for local development and tests. */
 export const localRunner = (appDir: string): AppRunner => {
-  let cachedLoad: Effect.Effect<
-    LoadedApp,
-    PublishError,
-    Crypto.Crypto | FileSystem.FileSystem
-  > | undefined;
+  let cachedLoad:
+    | Effect.Effect<LoadedApp, PublishError, FileSystem.FileSystem>
+    | undefined;
 
-  const loaded = (): Effect.Effect<
-    LoadedApp,
-    PublishError,
-    Crypto.Crypto | FileSystem.FileSystem
-  > =>
+  const loaded = (): Effect.Effect<LoadedApp, PublishError, FileSystem.FileSystem> =>
     Effect.suspend(() => {
       if (cachedLoad !== undefined) return cachedLoad;
       return Effect.flatMap(Effect.cached(loadApp(appDir)), (effect) =>
@@ -78,40 +26,32 @@ export const localRunner = (appDir: string): AppRunner => {
       );
     });
 
-  const loadedFor = (
-    target: string,
-  ): Effect.Effect<LoadedApp, CallError, Crypto.Crypto | FileSystem.FileSystem> =>
+  const registryFor = (target: string) =>
     loaded().pipe(
+      Effect.map(({ registry }) => registry),
       Effect.mapError(
         (error) => new CallError({ target, reason: `app failed to load (${error.message})` }),
       ),
     );
 
+  const settle = (target: string, outcome: CallOutcome): Effect.Effect<unknown, CallError> =>
+    outcome.ok
+      ? Effect.succeed(outcome.value)
+      : Effect.fail(new CallError({ target, reason: outcome.reason }));
+
   return {
     manifest: () => Effect.map(loaded(), ({ result }) => result),
     call: (name, input, ctx) =>
-      Effect.gen(function* () {
-        const { registry } = yield* loadedFor(name);
-        const registered = registry.tools.get(name);
-        if (registered === undefined)
-          return yield* new CallError({ target: name, reason: "unknown tool" });
-        const parsed = yield* parseInput(name, registered.spec, input);
-        return yield* Effect.tryPromise({
-          // SAFETY: ToolSpec intentionally erases authored handler inputs to keep
-          // authoring generic-free; validation and ToolCtx establish this call boundary.
-          try: () =>
-            (registered.spec.handler as (value: unknown, toolCtx: ToolCtx) => Promise<unknown>)(
-              parsed,
-              ctx,
-            ),
-          catch: (error) =>
-            new CallError({
-              target: name,
-              reason: `handler failed (${error instanceof Error ? error.message : String(error)})`,
-            }),
-        });
-      }),
-    discover: (name, _binding) =>
-      Effect.fail(new CallError({ target: name, reason: "no dynamic tools yet" })),
+      registryFor(name).pipe(
+        Effect.flatMap((registry) => Effect.promise(() => callTool(registry, name, input, ctx))),
+        Effect.flatMap((outcome) => settle(name, outcome)),
+      ),
+    discover: (name, binding) =>
+      registryFor(name).pipe(
+        Effect.flatMap((registry) =>
+          Effect.promise(() => discoverTool(registry, name, binding)),
+        ),
+        Effect.flatMap((outcome) => settle(name, outcome)),
+      ),
   };
 };

package/src/runner/protocol.ts

@@ -1,16 +1,8 @@
-import { Crypto, Data, type Effect, FileSystem } from "effect";
+import { Data, type Effect, FileSystem } from "effect";
 import type { AppManifestResult, PublishError } from "../manifest/contract";
+import type { ToolCtx, ToolCtxEntry } from "../runtime/index";
 
-/** The capability exposed to one tool requirement role. */
-export interface ToolCtxEntry {
-  readonly grant: string;
-  readonly token?: string;
-  readonly secrets?: Readonly<Record<string, string>>;
-  fetch(path: string, init?: RequestInit): Promise<Response>;
-}
-
-/** Tool capabilities keyed by requirement role. */
-export type ToolCtx = Readonly<Record<string, ToolCtxEntry>>;
+export type { ToolCtx, ToolCtxEntry } from "../runtime/index";
 
 /** A runner operation failure associated with its target. */
 export class CallError extends Data.TaggedError("CallError")<{
@@ -24,18 +16,14 @@ export class CallError extends Data.TaggedError("CallError")<{
 
 /** The platform protocol implemented by an app execution environment. */
 export interface AppRunner {
-  manifest(): Effect.Effect<
-    AppManifestResult,
-    PublishError,
-    Crypto.Crypto | FileSystem.FileSystem
-  >;
+  manifest(): Effect.Effect<AppManifestResult, PublishError, FileSystem.FileSystem>;
   call(
     name: string,
     input: unknown,
     ctx: ToolCtx,
-  ): Effect.Effect<unknown, CallError, Crypto.Crypto | FileSystem.FileSystem>;
+  ): Effect.Effect<unknown, CallError, FileSystem.FileSystem>;
   discover(
     name: string,
     binding: unknown,
-  ): Effect.Effect<unknown, CallError, Crypto.Crypto | FileSystem.FileSystem>;
+  ): Effect.Effect<unknown, CallError, FileSystem.FileSystem>;
 }