@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

package/src/bridge/surface/context.ts

@@ -1,21 +1,25 @@
 /**
- * The execution context every rendered tool hands its operation handler.
+ * The execution context every rendered tool hands its operation handler in
+ * the bridge process.
  *
- * One context per sandbox. Its dispatcher is the union of the two halves of
- * the default surface: the forwarded families through the shared
- * `buildSandboxDispatcher`, and the in-process families (the rules engine and
- * the stdlib catalogue) through their own handlers. An operation that maps
- * onto an existing tool therefore executes exactly the code path that tool
- * always did, whichever half it lives in.
+ * One context per sandbox. It widens the sandbox context (`./sandbox-context.ts`)
+ * with the project directory and the in-process tool families. Its dispatcher
+ * is the union of the two halves of the default surface: the forwarded families
+ * through the shared `buildSandboxDispatcher`, and the in-process families (the
+ * rules engine and the stdlib catalogue) through their own handlers. An
+ * operation that maps onto an existing tool therefore executes exactly the code
+ * path that tool always did, whichever half it lives in.
  */
 import type { ToolHandler } from 'pyric/sandbox/internal';
 import type { LocalSandbox } from 'pyric/sandbox';
 import type { CheckpointBackend } from 'pyric/sandbox/checkpoints';
-import { buildSandboxDispatcher, type SandboxDispatch } from '../client/dispatch.js';
+import type { SandboxDispatch } from '../client/dispatch.js';
 import { getInProcessToolHandlers } from '../server/tool-metadata.js';
-import { accountLookupFor } from './app-session.js';
-import { SurfaceIdentity } from './identity.js';
-import type { OperationResult, SurfaceContext } from './types.js';
+import { projectDatabaseInstances } from './database-instance-project.js';
+import { createSandboxSurfaceContext } from './sandbox-context.js';
+import type { SurfaceContext, SurfaceTargetRouter } from './types.js';
+
+export { callSandboxTool, operationFailure } from './sandbox-context.js';
 
 /** The minimal tool context the in-process handlers read. */
 function handlerContext(): never {
@@ -23,8 +27,7 @@ function handlerContext(): never {
 }
 
 /** A dispatcher over both halves of the default tool surface. */
-function buildSurfaceDispatch(sandbox: LocalSandbox): SandboxDispatch {
-  const forwarded = buildSandboxDispatcher(sandbox);
+function withInProcessFamilies(forwarded: SandboxDispatch): SandboxDispatch {
   const inProcess = new Map<string, ToolHandler>(
     getInProcessToolHandlers().map((handler) => [handler.name, handler]),
   );
@@ -41,38 +44,24 @@ function buildSurfaceDispatch(sandbox: LocalSandbox): SandboxDispatch {
  * session's `.pyric/` files live under; it defaults to the process working
  * directory, which is what a caller that never leaves its own project gets.
  * `checkpoints` is where the host keeps checkpoints when it is not that
- * directory.
+ * directory. The RTDB instances are read from the project's files on each
+ * call, unless a host replaces `databaseInstances` with its own.
  */
 export function createSurfaceContext(
   sandbox: LocalSandbox,
   projectDir: string = process.cwd(),
-  targetRouter?: import('./types.js').SurfaceTargetRouter,
+  targetRouter?: SurfaceTargetRouter,
   checkpoints?: CheckpointBackend,
 ): SurfaceContext {
-  return {
-    sandbox,
-    dispatch: buildSurfaceDispatch(sandbox),
-    identity: new SurfaceIdentity(accountLookupFor(sandbox)),
+  const base = createSandboxSurfaceContext(sandbox, () =>
+    projectDatabaseInstances(context.sandbox, context.projectDir),
+  );
+  const context: SurfaceContext = {
+    ...base,
+    dispatch: withInProcessFamilies(base.dispatch),
     projectDir,
     targetRouter,
     checkpoints,
   };
-}
-
-/**
- * Call one existing sandbox tool under the held identity. Arguments are
- * objects in and objects out; nothing is JSON-encoded on the way through.
- */
-export async function callSandboxTool(
-  ctx: SurfaceContext,
-  name: string,
-  args: Record<string, unknown>,
-): Promise<OperationResult> {
-  return ctx.dispatch(name, args, ctx.identity.lens());
-}
-
-/** Report a failure in the shape every handler returns. */
-export function operationFailure(summary: string, data?: unknown): OperationResult {
-  if (data === undefined) return { ok: false, summary };
-  return { ok: false, summary, data };
+  return context;
 }

package/src/bridge/surface/database-instance-catalog.ts

@@ -3,18 +3,12 @@
  *
  * An instance is known when `firebase.json` declares it or the sandbox already
  * holds data for it, because an app can open an instance `firebase.json` never
- * names. The Node host builds its catalog from the instances it serves
+ * names. A host builds its catalog from the instances it serves
  * (`serve/worker/host/rtdb-instance-catalog.ts`); the in-process sandbox and
- * the CLI runner read the project's files here.
+ * the CLI runner read the project's files (`./database-instance-project.ts`).
+ * This module reads no files, so a host in a browser can import it.
  */
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { heldDatabaseInstances } from 'pyric/database/internal';
-import { UNNAMED_DEFAULT_DATABASE_INSTANCE, isDefaultDatabaseInstance } from 'pyric/sandbox/internal';
-import type { LocalSandbox } from 'pyric/sandbox';
-import { readFirebaseJson } from '../../cli/firebase-json.js';
-import { resolveFirebaseProject } from '../../cli/firebase-project.js';
-import { databaseRulesTargets } from '../../serve/rules.js';
+import { isDefaultDatabaseInstance } from 'pyric/sandbox/internal';
 
 /** The instances a caller may name, as the refusal lists them. */
 export interface KnownDatabaseInstances {
@@ -55,25 +49,3 @@ export function databaseInstanceCatalog(known: KnownDatabaseInstances, projectId
 export function distinctNames(names: readonly string[], exclude: string | undefined): string[] {
   return [...new Set(names)].filter((name) => name !== exclude);
 }
-
-/** The catalog for a project directory: its `firebase.json`, its project, and what `sandbox` holds. */
-export async function projectDatabaseInstances(
-  sandbox: LocalSandbox,
-  projectDir: string,
-): Promise<DatabaseInstanceCatalog> {
-  const hasFirebaseJson = existsSync(join(projectDir, 'firebase.json'));
-  const config = hasFirebaseJson ? await readFirebaseJson(projectDir) : null;
-  const project = resolveFirebaseProject({ projectDir });
-  const targets = databaseRulesTargets(projectDir, config, project);
-  const isNamed = targets.defaultInstance !== UNNAMED_DEFAULT_DATABASE_INSTANCE;
-  const defaultInstance = isNamed ? targets.defaultInstance : undefined;
-  const declared = targets.targets.map((target) => target.instance);
-  const projectId = project.projectId;
-  const named = distinctNames([...declared, ...heldDatabaseInstances(sandbox)], targets.defaultInstance)
-    .filter((name) => !isDefaultDatabaseInstance(name, projectId));
-  return databaseInstanceCatalog({
-    ...(defaultInstance === undefined ? {} : { defaultInstance }),
-    named,
-    pending: targets.pending.map((target) => `${target.label} target "${target.target}" selects no instance yet: ${target.reason}.`),
-  }, projectId);
-}

package/src/bridge/surface/database-instance-project.ts

@@ -0,0 +1,40 @@
+/**
+ * The Realtime Database instances a project directory declares, for the
+ * in-process sandbox and the CLI runner, which have no host to ask. It reads
+ * `firebase.json`, so it runs only in the bridge process.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { heldDatabaseInstances } from 'pyric/database/internal';
+import { UNNAMED_DEFAULT_DATABASE_INSTANCE, isDefaultDatabaseInstance } from 'pyric/sandbox/internal';
+import type { LocalSandbox } from 'pyric/sandbox';
+import { readFirebaseJson } from '../../cli/firebase-json.js';
+import { resolveFirebaseProject } from '../../cli/firebase-project.js';
+import { databaseRulesTargets } from '../../serve/rules.js';
+import {
+  databaseInstanceCatalog,
+  distinctNames,
+  type DatabaseInstanceCatalog,
+} from './database-instance-catalog.js';
+
+/** The catalog for a project directory: its `firebase.json`, its project, and what `sandbox` holds. */
+export async function projectDatabaseInstances(
+  sandbox: LocalSandbox,
+  projectDir: string,
+): Promise<DatabaseInstanceCatalog> {
+  const hasFirebaseJson = existsSync(join(projectDir, 'firebase.json'));
+  const config = hasFirebaseJson ? await readFirebaseJson(projectDir) : null;
+  const project = resolveFirebaseProject({ projectDir });
+  const targets = databaseRulesTargets(projectDir, config, project);
+  const isNamed = targets.defaultInstance !== UNNAMED_DEFAULT_DATABASE_INSTANCE;
+  const defaultInstance = isNamed ? targets.defaultInstance : undefined;
+  const declared = targets.targets.map((target) => target.instance);
+  const projectId = project.projectId;
+  const named = distinctNames([...declared, ...heldDatabaseInstances(sandbox)], targets.defaultInstance)
+    .filter((name) => !isDefaultDatabaseInstance(name, projectId));
+  return databaseInstanceCatalog({
+    ...(defaultInstance === undefined ? {} : { defaultInstance }),
+    named,
+    pending: targets.pending.map((target) => `${target.label} target "${target.target}" selects no instance yet: ${target.reason}.`),
+  }, projectId);
+}

package/src/bridge/surface/database-instance.ts

@@ -8,8 +8,8 @@
  * a typo would otherwise open an empty instance and read back nothing.
  */
 import { resolveDatabaseInstance } from 'pyric/sandbox/internal';
-import { projectDatabaseInstances, type KnownDatabaseInstances } from './database-instance-catalog.js';
-import type { SurfaceContext } from './types.js';
+import type { KnownDatabaseInstances } from './database-instance-catalog.js';
+import type { SandboxSurfaceContext } from './types.js';
 
 /** The instances listed in a refusal, the default first. */
 function describeKnown(known: KnownDatabaseInstances): string {
@@ -32,11 +32,11 @@ export function unknownInstanceMessage(name: string, known: KnownDatabaseInstanc
  * the default instance, else the instance name. Throws the refusal for an
  * instance the project does not have.
  */
-export async function instanceSelector(ctx: SurfaceContext, raw: unknown): Promise<string | undefined> {
+export async function instanceSelector(ctx: SandboxSurfaceContext, raw: unknown): Promise<string | undefined> {
   if (raw === undefined) return undefined;
   const instance = resolveDatabaseInstance(String(raw));
   if (instance === undefined) return undefined;
-  const catalog = ctx.databaseInstances ?? await projectDatabaseInstances(ctx.sandbox, ctx.projectDir);
+  const catalog = await ctx.databaseInstances();
   const selector = catalog.select(instance.name);
   if (selector === null) throw new Error(unknownInstanceMessage(instance.name, catalog.known()));
   return selector;

package/src/bridge/surface/functions-runtime.ts

@@ -3,7 +3,7 @@
  * runtime from a project directory, rather than each method repeating the
  * "where does this project keep its Functions source" question.
  *
- * `discoverFunctionsRtdbProject` answers three ways: no `firebase.json`, or a
+ * `discoverFunctionsProject` answers three ways: no `firebase.json`, or a
  * `firebase.json` with no `functions` key, both mean the project declares no
  * Functions source and this reports an empty discovery rather than an error;
  * a declared source that does not resolve (a missing directory, a malformed
@@ -14,9 +14,9 @@ import {
   inspectOnValueCreated,
   type DiscoveredOnValueCreated,
   type UnsupportedOnValueCreated,
-} from '../../functions-rtdb/discovery.js';
-import { loadFunctionsModuleExports } from '../../functions-rtdb/module-loader.js';
-import { discoverFunctionsRtdbProject } from '../../functions-rtdb/project.js';
+} from '../../functions/rtdb/discovery.js';
+import { loadFunctionsModuleExports } from '../../functions/module-loader.js';
+import { discoverFunctionsProject } from '../../functions/project.js';
 
 export interface FunctionsDiscovery {
   /** Where this project's Functions source was looked for. */
@@ -28,7 +28,7 @@ export interface FunctionsDiscovery {
 /** Discover the RTDB triggers one project's Functions source defines, if it has one. */
 export async function discoverFunctionsTriggers(projectDir: string): Promise<FunctionsDiscovery> {
   const lookedAt = `${projectDir}/firebase.json`;
-  const project = discoverFunctionsRtdbProject(projectDir);
+  const project = discoverFunctionsProject(projectDir);
   if (project === null) return { lookedAt, triggers: [], unsupported: [] };
   const exported = await loadFunctionsModuleExports(project.entry);
   const inspected = inspectOnValueCreated(exported);

package/src/bridge/surface/held-identity.ts

@@ -15,7 +15,7 @@
  */
 import { describeAppSession, readAppSession } from './app-session.js';
 import type { IdentityInput } from './identity.js';
-import type { OperationResult, SurfaceContext } from './types.js';
+import type { OperationResult, SandboxSurfaceContext } from './types.js';
 
 /**
  * One line naming the agent identity.
@@ -44,7 +44,7 @@ function reported(held: { mode: string; uid?: string }): OperationResult {
 }
 
 /** Set the identity every later call runs under, and report it. */
-export function switchHeldIdentity(ctx: SurfaceContext, input: IdentityInput): OperationResult {
+export function switchHeldIdentity(ctx: SandboxSurfaceContext, input: IdentityInput): OperationResult {
   return reported(ctx.identity.switchTo(input));
 }
 
@@ -68,7 +68,7 @@ export interface HeldSession {
  * `--target` takes. These two are neither of those: they are the identities
  * this process itself holds.
  */
-export function listHeldSessions(ctx: SurfaceContext): OperationResult {
+export function listHeldSessions(ctx: SandboxSurfaceContext): OperationResult {
   const agent = ctx.identity.describe();
   const appSession = readAppSession(ctx.sandbox);
 
@@ -101,7 +101,7 @@ export function listHeldSessions(ctx: SurfaceContext): OperationResult {
  * identity, said again in one phrase, because that is the question a caller
  * asks this method to answer.
  */
-export function describeBothIdentities(ctx: SurfaceContext): OperationResult {
+export function describeBothIdentities(ctx: SandboxSurfaceContext): OperationResult {
   const agent = ctx.identity.describe();
   const appSession = readAppSession(ctx.sandbox);
   const runsAs = describeAgentIdentity(agent);

package/src/bridge/surface/manifest.sandbox.generated.ts

@@ -0,0 +1,137 @@
+// Generated by scripts/generate-surface-manifest.ts. Do not edit.
+import type { SandboxMethodRecord } from './method-types.js';
+import aiLogicClearScripts from './methods/ai_logic/clearScripts.js';
+import aiLogicScript from './methods/ai_logic/script.js';
+import aiLogicScripts from './methods/ai_logic/scripts.js';
+import aiLogicStatus from './methods/ai_logic/status.js';
+import authActAsAdmin from './methods/auth/actAsAdmin.js';
+import authActAsAnonymous from './methods/auth/actAsAnonymous.js';
+import authCreateCustomToken from './methods/auth/createCustomToken.js';
+import authCreateUser from './methods/auth/createUser.js';
+import authDeleteUser from './methods/auth/deleteUser.js';
+import authGetUser from './methods/auth/getUser.js';
+import authGetUserByEmail from './methods/auth/getUserByEmail.js';
+import authImpersonate from './methods/auth/impersonate.js';
+import authImportUsers from './methods/auth/importUsers.js';
+import authListUsers from './methods/auth/listUsers.js';
+import authSessions from './methods/auth/sessions.js';
+import authSetCustomUserClaims from './methods/auth/setCustomUserClaims.js';
+import authSignInAnonymously from './methods/auth/signInAnonymously.js';
+import authSignInWithCredential from './methods/auth/signInWithCredential.js';
+import authSignInWithCustomToken from './methods/auth/signInWithCustomToken.js';
+import authSignInWithEmailAndPassword from './methods/auth/signInWithEmailAndPassword.js';
+import authSignOut from './methods/auth/signOut.js';
+import authTakeAuthMail from './methods/auth/takeAuthMail.js';
+import authUpdateUser from './methods/auth/updateUser.js';
+import authUseAppSession from './methods/auth/useAppSession.js';
+import authWhoami from './methods/auth/whoami.js';
+import databaseCrawl from './methods/database/crawl.js';
+import databaseGet from './methods/database/get.js';
+import databasePush from './methods/database/push.js';
+import databaseQuery from './methods/database/query.js';
+import databaseRemove from './methods/database/remove.js';
+import databaseSet from './methods/database/set.js';
+import databaseUpdate from './methods/database/update.js';
+import firestoreAddDoc from './methods/firestore/addDoc.js';
+import firestoreDeleteDoc from './methods/firestore/deleteDoc.js';
+import firestoreDiscoverPaths from './methods/firestore/discoverPaths.js';
+import firestoreExtractIndexes from './methods/firestore/extractIndexes.js';
+import firestoreFindCollectionGroup from './methods/firestore/findCollectionGroup.js';
+import firestoreGetAggregateFromServer from './methods/firestore/getAggregateFromServer.js';
+import firestoreGetCountFromServer from './methods/firestore/getCountFromServer.js';
+import firestoreGetDoc from './methods/firestore/getDoc.js';
+import firestoreGetDocs from './methods/firestore/getDocs.js';
+import firestoreSetDoc from './methods/firestore/setDoc.js';
+import firestoreUpdateDoc from './methods/firestore/updateDoc.js';
+import firestoreWriteBatch from './methods/firestore/writeBatch.js';
+import functionsExecutions from './methods/functions/executions.js';
+import messagingDeliveries from './methods/messaging/deliveries.js';
+import messagingSend from './methods/messaging/send.js';
+import messagingSubscribeToTopic from './methods/messaging/subscribeToTopic.js';
+import messagingTokens from './methods/messaging/tokens.js';
+import messagingUnsubscribeFromTopic from './methods/messaging/unsubscribeFromTopic.js';
+import sandboxActivity from './methods/sandbox/activity.js';
+import sandboxAdvanceClock from './methods/sandbox/advanceClock.js';
+import sandboxEvents from './methods/sandbox/events.js';
+import sandboxInspect from './methods/sandbox/inspect.js';
+import sandboxListeners from './methods/sandbox/listeners.js';
+import sandboxReset from './methods/sandbox/reset.js';
+import sandboxResetClock from './methods/sandbox/resetClock.js';
+import sandboxSeed from './methods/sandbox/seed.js';
+import sandboxSetClock from './methods/sandbox/setClock.js';
+import storageDeleteObject from './methods/storage/deleteObject.js';
+import storageGetBytes from './methods/storage/getBytes.js';
+import storageGetDownloadURL from './methods/storage/getDownloadURL.js';
+import storageGetMetadata from './methods/storage/getMetadata.js';
+import storageListAll from './methods/storage/listAll.js';
+import storageSetCrossServiceIam from './methods/storage/setCrossServiceIam.js';
+import storageUpdateMetadata from './methods/storage/updateMetadata.js';
+
+export const SANDBOX_METHOD_RECORDS: ReadonlyArray<readonly [string, string, SandboxMethodRecord]> = [
+  ['ai_logic', 'clearScripts', aiLogicClearScripts],
+  ['ai_logic', 'script', aiLogicScript],
+  ['ai_logic', 'scripts', aiLogicScripts],
+  ['ai_logic', 'status', aiLogicStatus],
+  ['auth', 'actAsAdmin', authActAsAdmin],
+  ['auth', 'actAsAnonymous', authActAsAnonymous],
+  ['auth', 'createCustomToken', authCreateCustomToken],
+  ['auth', 'createUser', authCreateUser],
+  ['auth', 'deleteUser', authDeleteUser],
+  ['auth', 'getUser', authGetUser],
+  ['auth', 'getUserByEmail', authGetUserByEmail],
+  ['auth', 'impersonate', authImpersonate],
+  ['auth', 'importUsers', authImportUsers],
+  ['auth', 'listUsers', authListUsers],
+  ['auth', 'sessions', authSessions],
+  ['auth', 'setCustomUserClaims', authSetCustomUserClaims],
+  ['auth', 'signInAnonymously', authSignInAnonymously],
+  ['auth', 'signInWithCredential', authSignInWithCredential],
+  ['auth', 'signInWithCustomToken', authSignInWithCustomToken],
+  ['auth', 'signInWithEmailAndPassword', authSignInWithEmailAndPassword],
+  ['auth', 'signOut', authSignOut],
+  ['auth', 'takeAuthMail', authTakeAuthMail],
+  ['auth', 'updateUser', authUpdateUser],
+  ['auth', 'useAppSession', authUseAppSession],
+  ['auth', 'whoami', authWhoami],
+  ['database', 'crawl', databaseCrawl],
+  ['database', 'get', databaseGet],
+  ['database', 'push', databasePush],
+  ['database', 'query', databaseQuery],
+  ['database', 'remove', databaseRemove],
+  ['database', 'set', databaseSet],
+  ['database', 'update', databaseUpdate],
+  ['firestore', 'addDoc', firestoreAddDoc],
+  ['firestore', 'deleteDoc', firestoreDeleteDoc],
+  ['firestore', 'discoverPaths', firestoreDiscoverPaths],
+  ['firestore', 'extractIndexes', firestoreExtractIndexes],
+  ['firestore', 'findCollectionGroup', firestoreFindCollectionGroup],
+  ['firestore', 'getAggregateFromServer', firestoreGetAggregateFromServer],
+  ['firestore', 'getCountFromServer', firestoreGetCountFromServer],
+  ['firestore', 'getDoc', firestoreGetDoc],
+  ['firestore', 'getDocs', firestoreGetDocs],
+  ['firestore', 'setDoc', firestoreSetDoc],
+  ['firestore', 'updateDoc', firestoreUpdateDoc],
+  ['firestore', 'writeBatch', firestoreWriteBatch],
+  ['functions', 'executions', functionsExecutions],
+  ['messaging', 'deliveries', messagingDeliveries],
+  ['messaging', 'send', messagingSend],
+  ['messaging', 'subscribeToTopic', messagingSubscribeToTopic],
+  ['messaging', 'tokens', messagingTokens],
+  ['messaging', 'unsubscribeFromTopic', messagingUnsubscribeFromTopic],
+  ['sandbox', 'activity', sandboxActivity],
+  ['sandbox', 'advanceClock', sandboxAdvanceClock],
+  ['sandbox', 'events', sandboxEvents],
+  ['sandbox', 'inspect', sandboxInspect],
+  ['sandbox', 'listeners', sandboxListeners],
+  ['sandbox', 'reset', sandboxReset],
+  ['sandbox', 'resetClock', sandboxResetClock],
+  ['sandbox', 'seed', sandboxSeed],
+  ['sandbox', 'setClock', sandboxSetClock],
+  ['storage', 'deleteObject', storageDeleteObject],
+  ['storage', 'getBytes', storageGetBytes],
+  ['storage', 'getDownloadURL', storageGetDownloadURL],
+  ['storage', 'getMetadata', storageGetMetadata],
+  ['storage', 'listAll', storageListAll],
+  ['storage', 'setCrossServiceIam', storageSetCrossServiceIam],
+  ['storage', 'updateMetadata', storageUpdateMetadata],
+];

package/src/bridge/surface/method-types.ts

@@ -10,7 +10,7 @@
  * the evaluation variants serve, and the `pyric <tool> <method>` command line.
  */
 import type { z } from 'zod';
-import type { OperationResult, SurfaceContext } from './types.js';
+import type { OperationResult, SandboxSurfaceContext, SurfaceContext } from './types.js';
 
 /** Arguments as they arrive from a client. */
 export type Args = Record<string, unknown>;
@@ -95,10 +95,19 @@ export type CanonicalOperation =
     };
 
 /**
- * One authored method record. The tool and the method are also the record's
- * path, and the loader refuses a record whose fields disagree with it.
+ * Where a record's handler runs.
+ *
+ * - `sandbox`: wherever the sandbox lives, including a host that keeps it in a
+ *   browser. The handler is given only a `SandboxSurfaceContext`, and its
+ *   module graph imports nothing Node-only and dispatches no in-process tool
+ *   family (`test/bridge/surface/methods/sandbox-registry.test.ts`).
+ * - `bridge`: in the bridge process only, because it reads the project
+ *   directory, imports a Node-only module, or dispatches an in-process family.
  */
-export interface MethodRecord {
+export type RunsIn = 'sandbox' | 'bridge';
+
+/** The fields every record carries, whichever side its handler runs on. */
+interface MethodRecordFields {
   /** The service tool this method belongs to, which is its directory. */
   tool: string;
   /** The method name, which is its filename. */
@@ -119,15 +128,40 @@ export interface MethodRecord {
   example: Args;
   /** Rules a schema cannot state. Returns a rejection or null. */
   validate?(args: Args, ctx: MethodValidationContext): InvalidArguments | null;
+}
+
+/** A record whose handler runs wherever the sandbox lives. */
+export interface SandboxMethodRecord extends MethodRecordFields {
+  runsIn: 'sandbox';
+  /**
+   * The one implementation. Declared as a property, not a method, so its
+   * parameter is checked strictly: a handler that annotates `ctx` as the wider
+   * `SurfaceContext` to reach `projectDir` does not compile.
+   */
+  handler: (args: Args, ctx: SandboxSurfaceContext) => Promise<OperationResult>;
+}
+
+/** A record whose handler runs only in the bridge process. */
+export interface BridgeMethodRecord extends MethodRecordFields {
+  runsIn: 'bridge';
   /** The one implementation. */
-  handler(args: Args, ctx: SurfaceContext): Promise<OperationResult>;
+  handler: (args: Args, ctx: SurfaceContext) => Promise<OperationResult>;
 }
 
+/**
+ * One authored method record. The tool and the method are also the record's
+ * path, and the loader refuses a record whose fields disagree with it.
+ */
+export type MethodRecord = SandboxMethodRecord | BridgeMethodRecord;
+
 /** A loaded record: the authored fields plus the key read from the path. */
-export interface Method extends MethodRecord {
+export type Method = MethodRecord & {
   /** `<tool>.<method>`, the key every derived surface joins on. */
   readonly key: string;
-}
+};
+
+/** A loaded record that runs wherever the sandbox lives. */
+export type SandboxMethod = SandboxMethodRecord & { readonly key: string };
 
 /** One service tool, authored as `tools/<tool>.ts`. */
 export interface ToolRecord {
@@ -143,6 +177,26 @@ export interface Tool extends ToolRecord {
   readonly methods: readonly Method[];
 }
 
+/**
+ * Stamp one record with the key its path carries. Throws when the record's own
+ * `tool` or `method` disagrees with where it lives, because a record that says
+ * one thing and is filed under another would be reachable under two names and
+ * auditable under neither.
+ */
+export function stampRecord<R extends MethodRecord>(
+  owner: string,
+  name: string,
+  record: R,
+): R & { readonly key: string } {
+  if (record.tool !== owner) {
+    throw new Error(`method record methods/${owner}/${name}.ts declares tool '${record.tool}'`);
+  }
+  if (record.method !== name) {
+    throw new Error(`method record methods/${owner}/${name}.ts declares method '${record.method}'`);
+  }
+  return { ...record, key: `${owner}.${name}` };
+}
+
 /** Every canonical id one record can reach. */
 export function operationIds(record: MethodRecord): readonly string[] {
   if (typeof record.operation === 'string') return [record.operation];

package/src/bridge/surface/methods/ai_logic/clearScripts.ts

@@ -9,13 +9,14 @@
 import { z } from 'zod';
 import { AIError, AIErrorCode } from 'pyric/ai';
 import { clearScripts as clearScriptsEngine } from 'pyric/ai/scripting';
-import { operationFailure } from '../../context.js';
+import { operationFailure } from '../../sandbox-context.js';
 import { aiFor } from '../../service-handles.js';
 import type { MethodRecord } from '../../method-types.js';
 
 export default {
   tool: 'ai_logic',
   method: 'clearScripts',
+  runsIn: 'sandbox',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature: 'clearScripts()',

package/src/bridge/surface/methods/ai_logic/script.ts

@@ -18,7 +18,7 @@ import { z } from 'zod';
 import { AIError, AIErrorCode } from 'pyric/ai';
 import { script as scriptEngine } from 'pyric/ai/scripting';
 import { scriptMatchArgument, scriptResponseArgument } from '../../arguments/ai_logic.js';
-import { operationFailure } from '../../context.js';
+import { operationFailure } from '../../sandbox-context.js';
 import { aiFor } from '../../service-handles.js';
 import { matcherFor, respondFor, type ScriptMatch, type ScriptResponse } from '../../ai-logic-matchers.js';
 import type {
@@ -65,6 +65,7 @@ function refusePayloadMismatch(args: Args, ctx: MethodValidationContext): Invali
 export default {
   tool: 'ai_logic',
   method: 'script',
+  runsIn: 'sandbox',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature: 'script(match{substring?, model?}, response{type: text|json|error, payload})',

package/src/bridge/surface/methods/ai_logic/scripts.ts

@@ -8,7 +8,7 @@
 import { z } from 'zod';
 import { AIError, AIErrorCode } from 'pyric/ai';
 import { scripts as scriptsEngine } from 'pyric/ai/scripting';
-import { operationFailure } from '../../context.js';
+import { operationFailure } from '../../sandbox-context.js';
 import { aiFor } from '../../service-handles.js';
 import { describeMatch, describeRespond } from '../../ai-logic-matchers.js';
 import type { MethodRecord } from '../../method-types.js';
@@ -16,6 +16,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'ai_logic',
   method: 'scripts',
+  runsIn: 'sandbox',
   sdkOrigin: 'pyric',
   effect: 'read',
   signature: 'scripts()',

package/src/bridge/surface/methods/ai_logic/status.ts

@@ -17,6 +17,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'ai_logic',
   method: 'status',
+  runsIn: 'sandbox',
   sdkOrigin: 'pyric',
   effect: 'read',
   signature: 'status()',

package/src/bridge/surface/methods/assurance/attach.ts

@@ -16,6 +16,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'assurance',
   method: 'attach',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature: 'attach(campaignId?, maxRuns?)',

package/src/bridge/surface/methods/assurance/canIUse.ts

@@ -30,6 +30,7 @@ function summaryFor(result: ReturnType<typeof canIUse>, feature: string): string
 export default {
   tool: 'assurance',
   method: 'canIUse',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'read',
   signature: 'canIUse(feature)',

package/src/bridge/surface/methods/assurance/define.ts

@@ -14,6 +14,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'assurance',
   method: 'define',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature:

package/src/bridge/surface/methods/assurance/export.ts

@@ -21,6 +21,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'assurance',
   method: 'export',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature: 'export(campaignId, path?)',

package/src/bridge/surface/methods/assurance/inspect.ts

@@ -13,6 +13,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'assurance',
   method: 'inspect',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'read',
   signature: 'inspect(campaignId, probeId)',

package/src/bridge/surface/methods/assurance/map.ts

@@ -20,6 +20,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'assurance',
   method: 'map',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature:

package/src/bridge/surface/methods/assurance/minimize.ts

@@ -14,6 +14,7 @@ import type { MethodRecord } from '../../method-types.js';
 export default {
   tool: 'assurance',
   method: 'minimize',
+  runsIn: 'bridge',
   sdkOrigin: 'pyric',
   effect: 'write',
   signature: 'minimize(campaignId, probeId)',