fireemu 0.13.0 → 0.15.0

package/README.md

@@ -14,7 +14,7 @@ Fireemu is being developed to close these gaps. For example, it provides:
 
 Fireemu is still in development and does not yet reproduce every feature and behavior of production Firebase. Before relying on Fireemu’s test results in CI or other automated workflows, we recommend differential testing against production Firebase services for the features and critical workflows your application uses. Run the same tests against Fireemu and a dedicated Firebase test project, and check for differences in results and behavior that could affect your application. Use a dedicated test project, not your live production project.
 
-See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.13.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.13.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
+See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.15.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.15.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
 
 ## Quick start
 
@@ -66,13 +66,13 @@ Fireemu supports Cloud Firestore, Firebase Authentication (Identity Platform), C
 | Cloud Pub/Sub | Schemas, BigQuery and Cloud Storage subscription delivery, and some APIs such as `UpdateTopic` are not supported.  |
 | Firebase App Check | Local testing with debug tokens is supported. Real attestation through Play Integrity, App Attest, DeviceCheck, or reCAPTCHA, and replay protection using limited-use tokens, are not supported.  |
 
-This table highlights key limitations; it is not exhaustive. Check individual API support and conditions with the following command or the [capability manifest](https://github.com/t-k/fireemu/blob/v0.13.0/crates/fireemu/src/capabilities.json).
+This table highlights key limitations; it is not exhaustive. Check individual API support and conditions with the following command or the [capability manifest](https://github.com/t-k/fireemu/blob/v0.15.0/crates/fireemu/src/capabilities.json).
 
 ```sh
 npx fireemu capabilities
 ```
 
-See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.13.0/docs/functions-export-inventory.md) for support by trigger type.
+See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.15.0/docs/functions-export-inventory.md) for support by trigger type.
 
 ### Unsupported products
 
@@ -131,6 +131,8 @@ Use `--ui-port 0` to disable the UI. When automatic UI startup cannot bind the d
 
 When a Functions codebase is loaded, the Functions page shows registered functions, triggers, invocation results, and logs. You can run scheduled functions immediately or advance the virtual clock to their next scheduled execution. 
 
+For clock-sensitive and parallel integration tests, [test clocks and independent worlds](https://github.com/t-k/fireemu/blob/v0.15.0/docs/test-worlds.md) describes explicit Node Date/timer/Cloud Tasks policies and the `fireemu/testing` helper. Separate worlds isolate their clocks, Rules, Functions and service state, including when they use the same project ID.
+
 ### Export data
 
 To save data from a running emulator, run the following command in another terminal.
@@ -204,7 +206,7 @@ You can specify the configuration file with `--config`.
 npx fireemu up --config ./fireemu.json
 ```
 
-Keep Fireemu-specific settings in a Fireemu configuration file containing `"schemaVersion": 1`, rather than in `firebase.json`. See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.13.0/spec/config/fireemu.schema.json) for all available settings. 
+Keep Fireemu-specific settings in a Fireemu configuration file containing `"schemaVersion": 1`, rather than in `firebase.json`. See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.15.0/spec/config/fireemu.schema.json) for all available settings. 
 
 ### Firebase Authentication (Identity Platform) configuration
 
@@ -228,9 +230,9 @@ The `auth` section of `fireemu.json` lets you configure sign-in methods, passwor
 | Public keys for verifying custom tokens and OIDC ID tokens | `auth.customTokenSigners`, `auth.idpSigners` |
 | Sign-up quota configuration and local quota-exceeded simulation | `auth.quota`, `auth.quotaSimulation` |
 
-See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.13.0/spec/config/fireemu.schema.json) for the format and accepted values of each setting.  
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.15.0/spec/config/fireemu.schema.json) for the format and accepted values of each setting.  
 
-Declare `auth.authorizedDomains`, for example `["localhost", "app.test"]`, to set the initial project-wide list in either profile. The list replaces the defaults, so include `localhost` if your tests use it. An empty list authorizes no host under `strict`; an absent or `null` setting keeps the existing defaults (`localhost` and the project's `firebaseapp.com` and `web.app` domains). Validation uses the Admin API's rules for the selected profile, including its conversion of numeric and boolean entries to strings and omission of `null` entries; use strings when writing the list. Fireemu intentionally keeps `localhost` in its defaults for development. The [recorded production sandbox baseline](https://github.com/t-k/fireemu/blob/v0.13.0/conformance/auth-action-production.json) does not include it; new production projects may also omit it. This default is a Fireemu-only convenience, and declaring the list replaces it. Tenant-scoped strict action links currently check the tenant's default domains rather than this project declaration; support for the parent project's live list is pending.
+Declare `auth.authorizedDomains`, for example `["localhost", "app.test"]`, to set the initial project-wide list in either profile. The list replaces the defaults, so include `localhost` if your tests use it. An empty list authorizes no host under `strict`; an absent or `null` setting keeps the existing defaults (`localhost` and the project's `firebaseapp.com` and `web.app` domains). Validation uses the Admin API's rules for the selected profile, including its conversion of numeric and boolean entries to strings and omission of `null` entries; use strings when writing the list. Fireemu intentionally keeps `localhost` in its defaults for development. The [recorded production sandbox baseline](https://github.com/t-k/fireemu/blob/v0.15.0/conformance/auth-action-production.json) does not include it; new production projects may also omit it. This default is a Fireemu-only convenience, and declaring the list replaces it. Tenant-scoped strict action links currently check the tenant's default domains rather than this project declaration; support for the parent project's live list is pending.
 
 An Admin update changes the live list. A session reset restores the declared list, when present, and preserves an Admin-written list when no initial list was declared. Projects created later receive the declaration word for word, independently of the default project's live list; listing a particular project's `firebaseapp.com` or `web.app` domain therefore gives later projects that same domain. Clearing accounts leaves the live list alone. Auth export/import carries accounts without the domain list or its declaration. The `emulator` profile accepts the setting and exposes the list, while continuing to allow action-link continue URLs outside it.
 
@@ -324,7 +326,7 @@ Under the `strict` profile, TOTP is enabled only through the project's MFA confi
 
 #### Enable multi-tenancy
 
-Under the `strict` profile, enable `multiTenant.allowTenants` before using multi-tenancy: through the Admin API, or with `auth.multiTenant` in the file (see "Start with tenants" below). See the [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.13.0/docs/compatibility-contract.md) for the supported Admin API scope. 
+Under the `strict` profile, enable `multiTenant.allowTenants` before using multi-tenancy: through the Admin API, or with `auth.multiTenant` in the file (see "Start with tenants" below). See the [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.15.0/docs/compatibility-contract.md) for the supported Admin API scope. 
 
 #### Start with tenants
 
@@ -375,7 +377,7 @@ A schedule is driven by the virtual clock alone: real time passing runs nothing.
 
 A manual run (`POST /v1/sessions/{session}/functions/{name}:run`) enqueues one run of a scheduled function stamped with the current virtual time. It does not consume the next occurrence, which still comes due and is subject to `scheduler.overlap` like any run. It answers `400 INVALID_ARGUMENT` for an unknown function, a function that is not scheduled, an overlap policy refusal, or a runtime that is shutting down, and `429 RESOURCE_EXHAUSTED` when the event queue is full. This is fireemu's own control, not a claim about production's run-now.
 
-See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.13.0/spec/config/fireemu.schema.json) for available settings and values. 
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.15.0/spec/config/fireemu.schema.json) for available settings and values. 
 
 ### Firestore history limits
 
@@ -453,7 +455,7 @@ Fireemu is compatible with the listed Local Emulator Suite products as shipped b
 
 The `strict` and `emulator` profiles differ in some behaviors to serve their respective purposes. Where the official emulator and production Firebase disagree, Fireemu also adopts production behavior in some cases and records the difference.
 
-Check support for the specific APIs and conditions your application uses, rather than relying on product names alone. The [compatibility contract](https://github.com/t-k/fireemu/blob/v0.13.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.13.0/docs/compatibility-contract.md) explains the verification process and how to interpret its records. 
+Check support for the specific APIs and conditions your application uses, rather than relying on product names alone. The [compatibility contract](https://github.com/t-k/fireemu/blob/v0.15.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.15.0/docs/compatibility-contract.md) explains the verification process and how to interpret its records. 
 
 ### Network exposure of the Storage port
 
@@ -461,7 +463,7 @@ Like the official emulator, the Storage port reflects the requested object name
 
 ### Changes between versions
 
-Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.13.0/CHANGELOG.md) for release changes.
+Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.15.0/CHANGELOG.md) for release changes.
 
 ## Performance
 
@@ -478,7 +480,7 @@ The following results come from one `standard` run at commit `f3b942c`. Ratios a
 
 The 95% confidence interval for the startup-time ratio is `[21.4, 21.8]`. For the peak-memory ratio, calculated as official emulator divided by Fireemu, it is `[10.2, 11.1]`.
 
-See [benchmark.yml](https://github.com/t-k/fireemu/blob/v0.13.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.13.0/tools/bench/) for the benchmark implementation. 
+See [benchmark.yml](https://github.com/t-k/fireemu/blob/v0.15.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.15.0/tools/bench/) for the benchmark implementation. 
 
 ## Reporting issues and contributing
 
@@ -486,8 +488,8 @@ When reporting an issue, include the Fireemu and Firebase SDK versions, the prof
 
 For compatibility issues, also state whether you are comparing against the actual Firebase service or the official emulator, along with the expected and actual results. Remove credentials and personal information before sharing configuration files or logs.
 
-See the [development guide](https://github.com/t-k/fireemu/blob/v0.13.0/docs/development.md) for build and test instructions.
+See the [development guide](https://github.com/t-k/fireemu/blob/v0.15.0/docs/development.md) for build and test instructions.
 
 ## License
 
-Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.13.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.13.0/THIRD_PARTY_LICENSES.txt).
+Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.15.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.15.0/THIRD_PARTY_LICENSES.txt).

package/bin/fireemu.mjs

@@ -12,13 +12,12 @@
 // published beside this launcher.
 
 import { spawn } from "node:child_process";
-import { chmodSync, accessSync, constants as fsConstants, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { resolveBinary, ensureExecutable } from "../binary.mjs";
 import { constants as osConstants } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url));
 
 /** This launcher's own manifest: the version, and the platforms published with it. */
@@ -31,33 +30,6 @@ function platformPackage() {
   return `@fireemu/${process.platform}-${process.arch}`;
 }
 
-/** The daemon's file name inside a platform package. */
-function binaryName() {
-  return process.platform === "win32" ? "fireemu.exe" : "fireemu";
-}
-
-/**
- * The daemon to run.
- *
- * `FIREEMU_BINARY_PATH` wins so a vendored, air-gapped or locally built binary can be used
- * without touching `node_modules`. Otherwise the platform package is resolved through Node's
- * own algorithm, which finds it wherever the package manager put it -- a flat `node_modules`,
- * a pnpm store, or a workspace root.
- */
-function resolveBinary() {
-  const override = process.env.FIREEMU_BINARY_PATH;
-  if (override) {
-    return { path: override, from: "FIREEMU_BINARY_PATH" };
-  }
-  const pkg = platformPackage();
-  try {
-    const root = dirname(require.resolve(`${pkg}/package.json`));
-    return { path: join(root, "bin", binaryName()), from: pkg };
-  } catch {
-    return undefined;
-  }
-}
-
 /** The error a user can act on: what this host is, and what was published. */
 function noBinaryMessage() {
   const supported = Object.keys(manifest().optionalDependencies ?? {})
@@ -84,29 +56,6 @@ function noBinaryMessage() {
   ].join("\n");
 }
 
-/**
- * Makes sure the binary is executable.
- *
- * npm preserves the executable bit through a tarball, but a registry proxy, a `pnpm` store on
- * a filesystem that drops modes, or an archive round-tripped through a zip can lose it. Fixing
- * it here keeps the package free of an install script; a read-only installation that is
- * already executable is left alone.
- */
-function ensureExecutable(path) {
-  if (process.platform === "win32") return;
-  try {
-    accessSync(path, fsConstants.X_OK);
-    return;
-  } catch {
-    // Fall through and try to grant it.
-  }
-  try {
-    chmodSync(path, 0o755);
-  } catch {
-    // A read-only install: let the spawn below report the real failure.
-  }
-}
-
 function main() {
   const binary = resolveBinary();
   if (!binary) {

package/binary.mjs

@@ -0,0 +1,15 @@
+// Resolve package-local optional platform dependencies without starting the CLI.
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { accessSync, chmodSync, constants } from 'node:fs';
+const require = createRequire(import.meta.url);
+export function resolveBinary(override = process.env.FIREEMU_BINARY_PATH) {
+  if (override) return {path:override,from:'FIREEMU_BINARY_PATH'};
+  const name = `@fireemu/${process.platform}-${process.arch}`;
+  try { return {path:join(dirname(require.resolve(`${name}/package.json`)),'bin',process.platform==='win32'?'fireemu.exe':'fireemu'),from:name}; }
+  catch { return undefined; }
+}
+export function ensureExecutable(path) {
+  if(process.platform==='win32')return;
+  try {accessSync(path,constants.X_OK);} catch {try{chmodSync(path,0o755);}catch{/* Spawn reports the actionable failure. */}}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireemu",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "A local runtime for testing Firebase SDK and Functions code, checked against production Firebase behavior",
   "keywords": [
     "emulator",
@@ -21,19 +21,27 @@
   },
   "files": [
     "bin/fireemu.mjs",
+    "binary.mjs",
+    "testing.mjs",
+    "testing-snapshot.mjs",
+    "testing-process.mjs",
     "README.md",
     "LICENSE",
     "THIRD_PARTY_LICENSES.txt"
   ],
   "type": "module",
   "optionalDependencies": {
-    "@fireemu/darwin-arm64": "0.13.0",
-    "@fireemu/darwin-x64": "0.13.0",
-    "@fireemu/linux-x64": "0.13.0",
-    "@fireemu/linux-arm64": "0.13.0",
-    "@fireemu/win32-x64": "0.13.0"
+    "@fireemu/darwin-arm64": "0.15.0",
+    "@fireemu/darwin-x64": "0.15.0",
+    "@fireemu/linux-x64": "0.15.0",
+    "@fireemu/linux-arm64": "0.15.0",
+    "@fireemu/win32-x64": "0.15.0"
   },
   "engines": {
     "node": ">=20"
+  },
+  "exports": {
+    "./testing": "./testing.mjs",
+    "./package.json": "./package.json"
   }
 }

package/testing-process.mjs

@@ -0,0 +1,27 @@
+// Unix command group owner. The application runs in a separate process, so its code
+// cannot block this native lifecycle loop or consume the parent's lifetime pipe.
+import { spawn } from 'node:child_process';
+
+const [command, ...args] = process.argv.slice(2);
+let stopping = false;
+function retire() {
+  if (stopping) return;
+  stopping = true;
+  // This process remains the group's leader until escalation, preventing ID reuse.
+  try { process.kill(-process.pid, 'SIGTERM'); } catch {}
+  setTimeout(() => {
+    try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(1); }
+  }, 100);
+}
+process.on('SIGTERM', retire);
+process.on('SIGINT', retire);
+process.stdin.on('end', retire);
+process.stdin.on('error', retire);
+process.stdin.resume();
+const child = spawn(command, args, {stdio:['ignore','inherit','inherit']});
+function finish(result) {
+  if (process.connected) process.send(result, retire);
+  else retire();
+}
+child.once('error', error => finish({type:'command-exit',error:error.message}));
+child.once('exit', (code, signal) => finish({type:'command-exit',code,signal}));

package/testing-snapshot.mjs

@@ -0,0 +1,146 @@
+// Snapshot caller-owned input once; each generation gets its own writable copy.
+import { constants } from 'node:fs';
+import { cp, mkdir, readFile, writeFile, realpath, symlink, lstat, stat, unlink, readdir, readlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve, relative, sep, delimiter, isAbsolute } from 'node:path';
+
+export async function snapshotInputs(options, root) {
+  const cwd=resolve(options.cwd??process.cwd());
+  const privateRoot=await realpath(root);
+  const baseline=join(root,'baseline');
+  await mkdir(baseline,{mode:0o700});
+  let sequence=0;
+  const copyFile=async(value,base)=>{
+    if(typeof value!=='string')return value;
+    const destination=join(baseline,`input-${sequence++}-${basename(value)}`);
+    await cp(resolve(base,value),destination,{recursive:true,mode:constants.COPYFILE_FICLONE,dereference:true});
+    return destination;
+  };
+  const graph=new Map();
+  const inside=(parent,path)=>{const suffix=relative(parent,path);return suffix===''||(!suffix.startsWith(`..${sep}`)&&suffix!=='..'&&!isAbsolute(suffix));};
+  const captureTree=async(source,destination)=>{
+    const canonical=await realpath(source);
+    graph.set(canonical,destination);
+    const links=[];
+    await cp(canonical,destination,{recursive:true,mode:constants.COPYFILE_FICLONE,dereference:false,verbatimSymlinks:true,filter:async(path,target)=>{
+      if(['.git','.worktree'].includes(basename(path)))return false;
+      if((await lstat(path)).isSymbolicLink())links.push([path,target]);
+      return true;
+    }});
+    for(const [sourceLink,targetLink] of links){
+      const target=await realpath(sourceLink);
+      let copied;
+      const owners=[...graph].filter(([original])=>inside(original,target)).sort((a,b)=>b[0].length-a[0].length);
+      if(owners.length){const [original,snapshot]=owners[0];copied=join(snapshot,relative(original,target));}
+      else{
+        if(graph.size>=4096)throw Error('Functions dependency graph exceeds the snapshot budget');
+        // pnpm packages resolve dependencies from their enclosing node_modules,
+        // including siblings that are not explicit links inside the package.
+        let context=dirname(target);
+        while(basename(context)!=='node_modules'&&dirname(context)!==context)context=dirname(context);
+        if(basename(context)!=='node_modules')context=target;
+        const destination=join(baseline,`linked-${sequence++}`,...(basename(context)==='node_modules'?['node_modules']:[]));
+        await captureTree(context,destination);
+        copied=join(destination,relative(context,target));
+      }
+      await unlink(targetLink);
+      const kind=(await lstat(target)).isDirectory()?'dir':'file';
+      await symlink(process.platform==='win32'?copied:relative(dirname(targetLink),copied),targetLink,process.platform==='win32'&&kind==='dir'?'junction':kind);
+    }
+  };
+  const copySource=async(value,base)=>{
+    if(typeof value!=='string')return value;
+    const source=await realpath(resolve(base,value));
+    if(inside(source,privateRoot))throw Error('world temporary directory must be outside the Functions source');
+    const dependencies=[];
+    for(let ancestor=dirname(source),level=1;;ancestor=dirname(ancestor),level++){
+      const modules=join(ancestor,'node_modules');
+      try{if((await stat(modules)).isDirectory())dependencies.push({modules,level});}catch(error){if(error.code!=='ENOENT')throw error;}
+      if(dirname(ancestor)===ancestor)break;
+    }
+    const container=join(baseline,`functions-${sequence++}`);
+    const depth=dependencies.at(-1)?.level??0;
+    const destination=join(container,...Array(depth).fill('source'));
+    await captureTree(source,destination);
+    for(const {modules,level} of dependencies){
+      let ancestor=destination;for(let count=0;count<level;count++)ancestor=dirname(ancestor);
+      const target=join(ancestor,'node_modules'),canonical=await realpath(modules);
+      if(graph.has(canonical))await symlink(process.platform==='win32'?graph.get(canonical):relative(ancestor,graph.get(canonical)),target,process.platform==='win32'?'junction':'dir');
+      else await captureTree(modules,target);
+    }
+    return destination;
+  };
+  const snapshotFirebase=async(input,base)=>{
+    const value=structuredClone(input);
+    for(const service of ['firestore','storage']){
+      const sections=Array.isArray(value[service])?value[service]:[value[service]];
+      for(const section of sections){if(!section)continue;for(const key of ['rules','indexes'])if(section[key])section[key]=await copyFile(section[key],base);}
+    }
+    const codebases=Array.isArray(value.functions)?value.functions:[value.functions];
+    for(const codebase of codebases)if(codebase?.source)codebase.source=await copySource(codebase.source,base);
+    for(const emulator of Object.values(value.emulators??{}))if(emulator&&typeof emulator==='object'){emulator.host='127.0.0.1';emulator.port=0;}
+    const path=join(baseline,'firebase.json');
+    await writeFile(path,JSON.stringify(value),{mode:0o600});
+    // Storage target associations require the original project's alias file.
+    try{await cp(join(base,'.firebaserc'),join(baseline,'.firebaserc'));}catch(error){if(error.code!=='ENOENT')throw error;}
+    return path;
+  };
+  let input=options.config??{schemaVersion:1};
+  let configBase=cwd;
+  if(typeof input==='string'){const path=resolve(cwd,input);input=JSON.parse(await readFile(path,'utf8'));configBase=dirname(path);}
+  let config;
+  if(input.schemaVersion===undefined){config={schemaVersion:1,firebaseJson:await snapshotFirebase(input,configBase)};}
+  else{
+    config=structuredClone(input);
+    if(config.firebaseJson){const path=resolve(configBase,config.firebaseJson);config.firebaseJson=await snapshotFirebase(JSON.parse(await readFile(path,'utf8')),dirname(path));}
+    for(const [section,key] of [['rules','source'],['firestore','indexFile'],['firestore','textIndexDefinitionFile'],['storage','rules'],['functions','manifest']]){
+      if(config[section]?.[key])config[section][key]=await copyFile(config[section][key],cwd);
+    }
+    if(config.functions?.source)config.functions.source=await copySource(config.functions.source,cwd);
+  }
+  if(options.firebaseJson){const path=resolve(cwd,options.firebaseJson);config.firebaseJson=await snapshotFirebase(JSON.parse(await readFile(path,'utf8')),dirname(path));}
+  if(options.functionsSource){config.functions??={};config.functions.source=await copySource(options.functionsSource,cwd);}
+  const functionsConfigured=Boolean(graph.size||config.functions?.manifest||config.functions?.runner);
+  const nodePaths=[];
+  for(const entry of (functionsConfigured?options.env?.NODE_PATH??'':'').split(delimiter).filter(Boolean)){
+    let original;
+    try{original=await realpath(resolve(cwd,entry));}catch(error){if(error.code==='ENOENT')continue;throw error;}
+    let destination=graph.get(original);
+    if(!destination){destination=join(baseline,`node-path-${sequence++}`,'node_modules');await captureTree(original,destination);}
+    nodePaths.push(destination);
+  }
+  config.daemon={...config.daemon,clockStart:options.clockStart??config.daemon?.clockStart??'2026-01-01T00:00:00Z',seed:options.seed??config.daemon?.seed??1,authProject:options.projectId??config.daemon?.authProject??'demo-test-world'};
+  for(const service of ['firestore','http','storage','functions','eventarc','tasks','pubsub','hub','ui','logging'])config.daemon[`${service}Port`]=0;
+  config.functions={...config.functions,clock:{date:'virtual',timers:'real',tasks:'virtual',...config.functions?.clock,...options.clock}};
+  await writeFile(join(baseline,'fireemu.json'),JSON.stringify(config),{mode:0o600});
+  let seed;
+  if(options.import){seed=join(baseline,'seed');await cp(resolve(cwd,options.import),seed,{recursive:true,mode:constants.COPYFILE_FICLONE,dereference:true});}
+  return {baseline,config,seed,nodePaths,functionsConfigured};
+}
+
+export async function prepareGeneration(snapshot,directory){
+  await mkdir(directory,{mode:0o700});
+  const inputs=join(directory,'inputs');
+  await cp(snapshot.baseline,inputs,{recursive:true,mode:constants.COPYFILE_FICLONE,dereference:false,verbatimSymlinks:true});
+  const rewrite=value=>typeof value==='string'&&value.startsWith(`${snapshot.baseline}${sep}`)?`${inputs}${value.slice(snapshot.baseline.length)}`:Array.isArray(value)?value.map(rewrite):value&&typeof value==='object'?Object.fromEntries(Object.entries(value).map(([key,item])=>[key,rewrite(item)])):value;
+  // Windows junctions are absolute; copying them verbatim would expose the baseline.
+  const relocateLinks=async path=>{
+    for(const entry of await readdir(path,{withFileTypes:true})){
+      const child=join(path,entry.name);
+      if(entry.isSymbolicLink()){
+        const target=await readlink(child);
+        const relocated=rewrite(target);
+        if(relocated!==target){
+          const kind=(await lstat(target)).isDirectory()?'dir':'file';
+          await unlink(child);
+          await symlink(relocated,child,process.platform==='win32'&&kind==='dir'?'junction':kind);
+        }
+      }else if(entry.isDirectory())await relocateLinks(child);
+    }
+  };
+  await relocateLinks(inputs);
+  const config=rewrite(snapshot.config);
+  if(config.firebaseJson){const firebase=rewrite(JSON.parse(await readFile(config.firebaseJson,'utf8')));await writeFile(config.firebaseJson,JSON.stringify(firebase),{mode:0o600});}
+  await writeFile(join(inputs,'fireemu.json'),JSON.stringify(config),{mode:0o600});
+  await mkdir(join(directory,'tmp'),{mode:0o700});
+  return {configPath:join(inputs,'fireemu.json'),cwd:inputs,seed:snapshot.seed?rewrite(snapshot.seed):undefined,nodePath:(snapshot.nodePaths??[]).map(rewrite).join(delimiter)};
+}

package/testing.mjs

@@ -0,0 +1,169 @@
+// A test world owns a daemon, private input snapshots and generation-scoped clients.
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { resolveBinary, ensureExecutable } from './binary.mjs';
+import { snapshotInputs, prepareGeneration } from './testing-snapshot.mjs';
+
+const endpointVariables = {firestore:'FIRESTORE_EMULATOR_HOST',auth:'FIREBASE_AUTH_EMULATOR_HOST',storage:'FIREBASE_STORAGE_EMULATOR_HOST',functions:'FIREEMU_FUNCTIONS_HOST',eventarc:'CLOUD_EVENTARC_EMULATOR_HOST',tasks:'CLOUD_TASKS_EMULATOR_HOST',pubsub:'PUBSUB_EMULATOR_HOST',hub:'FIREBASE_EMULATOR_HUB',logging:'FIREBASE_LOGGING_EMULATOR_HOST'};
+const emulatorVariables = new Set([...Object.values(endpointVariables),'FIREBASE_CONFIG','NODE_PATH','FIREBASE_FIRESTORE_EMULATOR_ADDRESS','STORAGE_EMULATOR_HOST','FIREEMU_CONTROL_TOKEN','FIREEMU_CONTROL_URL','FIREEMU_APP_CHECK_EMULATOR_HOST','FIREEMU_APP_CHECK_JWKS_URL','FIREEMU_APP_CHECK_DEBUG_TOKEN_URL','FIREBASE_DATABASE_EMULATOR_HOST']);
+const emptyEnvironment=base=>Object.fromEntries(Object.entries(base).filter(([name])=>!emulatorVariables.has(name)));
+
+function supervise(command,args,options){
+  const child=spawn(command,args,{...options,stdio:options.stdio??['ignore','pipe','pipe'],windowsHide:true,detached:process.platform!=='win32'});
+  let output='',errorOutput='',result,commandResult;
+  if(options.commandOwner)child.on('message',message=>{if(message?.type==='command-exit')commandResult=message;});
+  child.stdin?.on('error',()=>{});
+  child.stdout?.on('data',data=>{output=(output+data).slice(-65536);});
+  child.stderr?.on('data',data=>{errorOutput=(errorOutput+data).slice(-65536);});
+  const exited=new Promise(resolve=>{
+    child.once('error',error=>{result={error};resolve(result);});
+    child.once('close',(code,signal)=>{result??=commandResult?.error?{error:Error(commandResult.error)}:commandResult??{code,signal};resolve(result);});
+  });
+  return {child,exited,result:()=>result,output:()=>output,errorOutput:()=>errorOutput};
+}
+async function stop(process,timeout=5000){
+  if(!process||process.result())return;
+  const signal=kind=>{if(process.result())return;try{if(globalThis.process.platform==='win32')process.child.kill(kind);else globalThis.process.kill(-process.child.pid,kind);}catch(error){if(error.code!=='ESRCH')throw error;}};
+  process.child.stdin?.end();
+  signal('SIGTERM');
+  let timer;
+  const grace=new Promise(resolve=>{timer=setTimeout(()=>resolve(false),timeout);});
+  const retired=await Promise.race([process.exited.then(()=>true),grace]);
+  clearTimeout(timer);
+  if(!retired){
+    signal('SIGKILL');
+    const forced=new Promise(resolve=>{timer=setTimeout(()=>resolve(false),5000);});
+    const closed=await Promise.race([process.exited.then(()=>true),forced]);
+    clearTimeout(timer);
+    if(!closed)throw Error('test world process tree did not close after forced retirement');
+  }
+}
+function endpoints(descriptor){
+  const result={};
+  const decode=value=>{const url=new URL(value.includes('://')?value:`http://${value}`);return Object.freeze({host:url.hostname,port:Number(url.port),url:`${url.protocol}//${url.host}`});};
+  result.control=decode(descriptor.controlUrl);
+  for(const [service,name] of Object.entries(endpointVariables))if(descriptor.environment[name])result[service]=decode(descriptor.environment[name]);
+  return Object.freeze(result);
+}
+
+/** Create an independent emulator world; no method changes the parent's environment. */
+export async function createTestWorld(options={}){
+  options={...options,config:typeof options.config==='object'?structuredClone(options.config):options.config,services:options.services?[...options.services]:undefined,env:{...(options.env??process.env)},clock:options.clock?{...options.clock}:undefined};
+  const binary=resolveBinary(options.binaryPath?resolve(options.binaryPath):undefined);
+  if(!binary)throw Error('fireemu could not start a test world: install the platform package or supply binaryPath');
+  const timeout=options.startupTimeoutMs??60_000;
+  if(!Number.isSafeInteger(timeout)||timeout<=0)throw TypeError('startupTimeoutMs must be a positive integer');
+  let services=options.services;
+  if(services&&(!Array.isArray(services)||!services.length||services.some(name=>typeof name!=='string'||! /^(auth|firestore|storage|functions(?::[A-Za-z0-9_-]+)?|pubsub|appcheck)$/.test(name))))throw TypeError('services must name supported test-world services');
+  const id=randomUUID();
+  const directory=await mkdtemp(join(resolve(options.tempRoot??tmpdir()),'fireemu-world-'));
+  let snapshot,current,tail=Promise.resolve(),closing=false,disposed=false,generation=0;
+  const clients=new Set();
+  const retiring=new Set();
+  const enqueue=operation=>{const job=tail.then(operation);tail=job.catch(()=>{});return job;};
+  const check=()=>{if(closing||disposed)throw Error('test world is disposed');if(!current?.descriptor||current.process.result())throw Error('test world generation is unavailable');};
+  const retire=async()=>{
+    if(current)retiring.add(current);
+    current=undefined;
+    const clientResults=await Promise.allSettled([...clients].map(async client=>{await stop(client);clients.delete(client);}));
+    const daemonResults=await Promise.allSettled([...retiring].map(async active=>{
+      await stop(active.process,options.shutdownTimeoutMs??5000);
+      if(!clients.size){await rm(active.directory,{recursive:true,force:true});retiring.delete(active);}
+    }));
+    const failures=[...clientResults,...daemonResults].filter(result=>result.status==='rejected').map(result=>result.reason);
+    if(failures.length)throw new AggregateError(failures,'test world retirement failed; cleanup can be retried');
+  };
+  const requestFor=async(active,method,path,body,signal)=>{
+    const response=await fetch(`${active.descriptor.controlUrl}${path}`,{method,headers:{authorization:`Bearer ${active.descriptor.controlToken}`,...(body===undefined?{}:{'content-type':'application/json'})},body:body===undefined?undefined:JSON.stringify(body),signal:signal??AbortSignal.timeout(options.requestTimeoutMs??10_000)});
+    const value=await response.json();
+    if(!response.ok)throw Error(`test world control ${response.status}: ${value.error?.message??JSON.stringify(value)}`);
+    return value;
+  };
+  const start=async()=>{
+    options.signal?.throwIfAborted();
+    const next=generation+1;
+    const generationDirectory=join(directory,`generation-${next}`);
+    const prepared=await prepareGeneration(snapshot,generationDirectory);
+    const readyFile=join(generationDirectory,'ready.json');
+    const args=['up','--config',prepared.configPath,'--project',snapshot.config.daemon.authProject,'--only',services.join(','),'--ready-file',readyFile,'--owner-stdin','--log-verbosity','quiet'];
+    for(const name of ['firestore','http','storage','functions','eventarc','tasks','pubsub','hub','ui','logging'])args.push(`--${name}-port`,'0');
+    if(prepared.seed)args.push('--import',prepared.seed);
+    const temporary=join(generationDirectory,'tmp');
+    const environment={...emptyEnvironment(options.env??process.env),NODE_PATH:prepared.nodePath,TMPDIR:temporary,TEMP:temporary,TMP:temporary,FIREEMU_TEST_WORLD_ID:id,FIREEMU_TEST_WORLD_GENERATION:String(next)};
+    ensureExecutable(binary.path);
+    const daemon=supervise(binary.path,args,{cwd:prepared.cwd,env:environment,stdio:['pipe','pipe','pipe']});
+    const active={process:daemon,directory:generationDirectory};current=active;
+    const deadline=Date.now()+timeout;
+    try{
+      while(Date.now()<deadline){
+        options.signal?.throwIfAborted();
+        if(daemon.result())throw Error(`fireemu could not start test world: ${daemon.result().error?.message??daemon.errorOutput()??'daemon exited'}`);
+        try{
+          const descriptor=JSON.parse(await readFile(readyFile,'utf8'));
+          if(descriptor.schemaVersion!==1||descriptor.pid!==daemon.child.pid||descriptor.projectId!==snapshot.config.daemon.authProject)throw Error('invalid test-world readiness descriptor');
+          active.descriptor=descriptor;
+          await requestFor(active,'GET','/health/ready',undefined,AbortSignal.timeout(Math.min(1000,timeout)));
+          if(daemon.result())throw Error('daemon exited during test-world readiness');
+          active.endpoints=endpoints(descriptor);
+          active.environment=Object.freeze({...descriptor.environment,NODE_PATH:prepared.nodePath,TMPDIR:temporary,TEMP:temporary,TMP:temporary,FIREEMU_TEST_WORLD_ID:id,FIREEMU_TEST_WORLD_GENERATION:String(next)});
+          generation=next;
+          return;
+        }catch(error){if(error.code!=='ENOENT'&&!(error instanceof SyntaxError)&&error.name!=='TimeoutError'&&error.name!=='TypeError')throw error;}
+        await delay(10);
+      }
+      throw Error('fireemu test-world startup timed out');
+    }catch(error){await retire();throw error;}
+  };
+  const control=(method,path,body)=>enqueue(async()=>{check();return requestFor(current,method,path,body);});
+  const world={
+    get generation(){return generation;},
+    get endpoints(){check();return current.endpoints;},
+    get environment(){check();return current.environment;},
+    get directory(){return directory;},
+    control,
+    clock:Object.freeze({
+      get:()=>control('GET','/v1/sessions/default'),
+      set:(instant,{allowBackwards=false}={})=>control('POST','/v1/sessions/default/clock:set',{instant,allowBackwards}),
+      advance:duration=>control('POST','/v1/sessions/default/clock:advance',typeof duration==='number'?{millis:duration}:duration),
+      advanceTo:instant=>control('POST','/v1/sessions/default/clock:advanceTo',{instant}),
+      runDue:(budget=1000)=>control('POST','/v1/sessions/default/clock:runDue',{budget}),
+    }),
+    reset:()=>enqueue(async()=>{check();await retire();await start();return world;}),
+    dispose:()=>{closing=true;return enqueue(async()=>{if(disposed)return;await retire();await rm(directory,{recursive:true,force:true});disposed=true;});},
+    async run(command,args=[],runOptions={}){
+      await tail;check();
+      const active=current;
+      const windows=process.platform==='win32';
+      const stdio=runOptions.stdio==='inherit'?['pipe','inherit','inherit']:['pipe','pipe','pipe'];
+      if(!windows)stdio.push('ipc');
+      const client=supervise(windows?binary.path:process.execPath,windows?['__test-world-command',command,...args]:[fileURLToPath(new URL('./testing-process.mjs',import.meta.url)),command,...args],{cwd:runOptions.cwd??options.cwd??process.cwd(),env:{...emptyEnvironment(process.env),...emptyEnvironment(runOptions.env??{}),...active.environment},stdio,commandOwner:!windows});
+      clients.add(client);
+      const aborted=()=>{void stop(client).catch(()=>{});};
+      runOptions.signal?.addEventListener('abort',aborted,{once:true});
+      if(runOptions.signal?.aborted)aborted();
+      try{
+        const result=await client.exited;
+        if(current!==active||closing)throw Error('test world command was retired with its generation');
+        runOptions.signal?.throwIfAborted();
+        if(result.error)throw result.error;
+        if(result.code!==0)throw Error(`test world command exited ${result.code??result.signal}: ${client.errorOutput()}`);
+        return {...result,stdout:client.output(),stderr:client.errorOutput()};
+      }finally{clients.delete(client);runOptions.signal?.removeEventListener('abort',aborted);}
+    },
+  };
+  Object.defineProperty(world,'id',{value:id,enumerable:true});
+  Object.defineProperty(world,'projectId',{get:()=>snapshot?.config.daemon.authProject,enumerable:true});
+  try{snapshot=await snapshotInputs(options,directory);services??=['auth','firestore','storage',...(snapshot.functionsConfigured?['functions']:[])];await start();return Object.freeze(world);}
+  catch(error){await retire();await rm(directory,{recursive:true,force:true});throw error;}
+}
+
+/** Always join disposal, including when the test callback rejects. */
+export async function withTestWorld(options,callback){
+  const world=await createTestWorld(options);
+  try{return await callback(world);}finally{await world.dispose();}
+}