@pyric/cli 0.1.0-alpha.26 → 0.1.0-alpha.28

package/src/cli/index.ts

@@ -5,6 +5,7 @@
  * Subcommands:
  *   pyric bridge [--port N] [--project ID]
  *   pyric sandbox [flags] [--] [command...]
+ *   pyric run [--sandbox URL] [--wait[=SECONDS]] -- <command...>
  *   pyric init [dir] [--template web|node] [--name N] [--force] [--json]
  *   pyric vendor [dir] [--json]
  *   pyric snapshot [--out DIR] [--port N] [--force] [--json] [--include-passwords]
@@ -60,12 +61,15 @@ clients (Claude Code, Cursor, ...).
 USAGE
   pyric bridge [flags]
   pyric sandbox [flags] [--] [command...]
+  pyric run [--sandbox URL] [--wait[=SECONDS]] -- <command...>
   pyric init [dir] [--template=web|node]
   pyric sandbox salvage --source=DIR --out=NEW_DIR
   pyric snapshot [--out=DIR]
-  pyric verify [fixture|dir] [--engine sandbox|rules-test-api|both]
+  pyric verify [fixture|dir] [--engine sandbox|rules-test-api|staging|both]
   pyric can-i-use <feature> [--json]
   pyric verify cases [fixture] [--service firestore] [--out FILE]
+  pyric verify staging init
+  pyric verify staging restore [--force]
   pyric firestore rules validate <path>
   pyric firestore rules resolve <path> [--out <path>]
   pyric firestore indexes generate <path...> [--out <path>]
@@ -89,6 +93,15 @@ COMMANDS
                              configured in pyric.json; if none is configured, runs the sandbox host only.
                              A firebase.json Functions source is discovered automatically;
                              supported RTDB onValueCreated exports run in isolated Node.
+  run [--sandbox URL]        Run a command against a sandbox host that is already
+                             running (a Vite dev server with the pyric plugin, or
+                             \`pyric sandbox\`), with the environment \`pyric sandbox\`
+                             gives its child. --sandbox URL names the host; without
+                             it, PYRIC_SANDBOX=remote:<url>, then .pyric/serve.json.
+                             The register module is passed by absolute file URL, so
+                             the command can run outside pyric's install tree.
+                             --wait[=SECONDS] polls the host's health until it
+                             answers (default 30s) before starting the command.
   init [dir]                 Scaffold a pyric project. --template=web (default; Vite app
                              on \`@pyric/cli/vite\`), static (\`pyric sandbox\`), or node.
                              --name=NAME --force (overwrite scaffold files) --json (machine
@@ -110,9 +123,12 @@ COMMANDS
                              for the Firestore/RTDB services present in the fixture.
                              No arg replays the latest \`pyric sandbox\` capture
                              (.pyric/last-session.json). --service filters services.
-                             --engine sandbox (default), rules-test-api, or both.
+                             --engine sandbox (default), rules-test-api, staging, or both.
                              Hosted Rules Test API verification is Firestore-only
                              and uses --project plus the configured Google credentials.
+                             --engine staging replays RTDB against your own dedicated
+                             instance (pyric.json verify.staging) so production decides
+                             each operation; repeat --engine to compare with sandbox.
                              --rules service=path overrides firebase.json resolution
                              (repeat for mixed captures). Each RTDB instance the session
                              used is checked against its own rules; --rules
@@ -123,6 +139,12 @@ COMMANDS
                              Exact and fuzzy queries use the same model as MCP. --json.
   verify cases [fixture]     Derive Firestore Rules Test API cases from a captured
                              fixture and print JSON, or write with --out FILE.
+  verify staging init        Enroll the empty RTDB instance pyric.json verify.staging
+                             names ({ project, rtdb }) for --engine staging. Refuses an
+                             instance that holds data or that firebase.json deploys to.
+  verify staging restore     Put the staging instance back after an interrupted run, from
+                             the rules kept in .pyric/staging-restore.json; --force
+                             deploys deny-all rules with the marker when none were kept.
   firestore rules validate   Validate Firestore rules structure against a file.
   firestore rules resolve    Resolve Firestore 2+modules imports to one ruleset.
   firestore indexes generate Generate firestore.indexes.json from application source.
@@ -209,7 +231,7 @@ CORE FLAGS (sandbox)
                      browser store in Studio under Settings, Reset, or use an
                      incognito window) for a full reset.
   [command...]       Run a command once the host is up, with PYRIC_SANDBOX set and
-                     NODE_OPTIONS extended with --import @pyric/cli/register
+                     NODE_OPTIONS extended with --import <register module URL>
                      so firebase-admin/firebase resolve to the sandbox. Put
                      Pyric flags before the command. A bare -- separates the
                      command and its flags. When omitted, pyric.json#command
@@ -389,6 +411,9 @@ export async function dispatch(parsed: ParsedArgs): Promise<number> {
       }
       const { runServe } = await import('./serve.js');
       return runServe(parsed);
+    case 'run':
+      const { runRun } = await import('./run.js');
+      return runRun(parsed);
     case 'snapshot':
       return await runSnapshot(parsed);
     case 'verify':

package/src/cli/pyric-config.ts

@@ -31,6 +31,11 @@ export interface PyricConfig {
   rules?: string | PyricRulesConfig;
   /** Project ID label for emulation. */
   project?: string;
+  /** `pyric verify` settings. */
+  verify?: {
+    /** The dedicated RTDB instance `pyric verify --engine staging` replays against. */
+    staging?: { project: string; rtdb: string };
+  };
 }
 
 export async function readPyricConfig(cwd: string = process.cwd()): Promise<PyricConfig> {

package/src/cli/run.ts

@@ -0,0 +1,139 @@
+/**
+ * `pyric run [--sandbox <url>] -- <command...>`: run one command against a
+ * sandbox host that is already running, such as a Vite dev server with the
+ * pyric plugin or a `pyric sandbox` in another terminal.
+ *
+ * The child gets the environment `pyric sandbox` gives its own child
+ * (`buildChildEnv`): the activator, the host's identity, and `--import` with
+ * the absolute `file:` URL of this install's register module. Nothing in the
+ * child resolves `@pyric/cli` by name, so the command works from any working
+ * directory, including one outside the tree pyric is installed in.
+ */
+import type { ParsedArgs } from './parse-args.js';
+import {
+  buildChildEnv,
+  registerModuleUrl,
+  spawnSandboxChild,
+  type SandboxChildPlan,
+} from './sandbox-runner.js';
+import { discoverServe, probeHostUrl } from '../serve/discovery.js';
+
+export interface RunInvocation {
+  /** The host URL named by `--sandbox` or `PYRIC_SANDBOX=remote:<url>`; null to discover it. */
+  readonly hostUrl: string | null;
+  readonly plan: SandboxChildPlan;
+  /** How long to wait for the host to answer before giving up; 0 probes once. */
+  readonly waitMs: number;
+}
+
+export const RUN_USAGE = 'usage: pyric run [--sandbox <url>] [--wait[=<seconds>]] -- <command> [args...]\n';
+
+/** `--wait` without a value: the bound `pyric sandbox` gives its first-run race guard. */
+export const DEFAULT_WAIT_SECONDS = 30;
+
+/** Strip the optional `remote:` prefix the activator uses. Null when nothing names a URL. */
+function hostUrlOf(value: string | undefined): string | null {
+  if (value === undefined) return null;
+  const url = value.startsWith('remote:') ? value.slice('remote:'.length) : value;
+  const namesUrl = /^https?:\/\//.test(url);
+  return namesUrl ? url : null;
+}
+
+/**
+ * Read a `pyric run` invocation. The host comes from `--sandbox`, then from an
+ * inherited `PYRIC_SANDBOX=remote:<url>`; with neither, the caller discovers
+ * the project's running host. Returns a usage error string when the command or
+ * the flag is missing or malformed.
+ */
+export function parseRunInvocation(parsed: ParsedArgs, env: NodeJS.ProcessEnv): RunInvocation | string {
+  const passthrough = parsed.passthrough ?? [];
+  const argv = passthrough.length > 0 ? passthrough : parsed.positional;
+  if (argv.length === 0) return `pyric run: no command to run.\n${RUN_USAGE}`;
+  const flag = parsed.flags.get('sandbox');
+  let hostUrl: string | null;
+  if (flag === undefined) {
+    hostUrl = hostUrlOf(env.PYRIC_SANDBOX);
+  } else {
+    hostUrl = typeof flag === 'string' ? hostUrlOf(flag) : null;
+    if (hostUrl === null) {
+      return `pyric run: --sandbox needs a host URL, such as http://localhost:5173.\n${RUN_USAGE}`;
+    }
+  }
+  const wait = parsed.flags.get('wait');
+  let waitMs = 0;
+  if (wait === true) {
+    waitMs = DEFAULT_WAIT_SECONDS * 1000;
+  } else if (wait !== undefined) {
+    const seconds = typeof wait === 'string' ? Number(wait) : Number.NaN;
+    const isDuration = Number.isFinite(seconds) && seconds > 0;
+    if (!isDuration) return `pyric run: --wait takes a number of seconds, such as --wait=60.\n${RUN_USAGE}`;
+    waitMs = seconds * 1000;
+  }
+  return { hostUrl, plan: { argv: [...argv], label: argv.join(' ') }, waitMs };
+}
+
+/**
+ * Call `attempt` until it returns a value or `timeoutMs` passes, `intervalMs`
+ * apart. A zero timeout makes one attempt. Injectable sleep for the unit suite.
+ */
+export async function pollUntil<T>(
+  attempt: () => Promise<T | null>,
+  opts: { timeoutMs: number; intervalMs?: number; sleep?: (ms: number) => Promise<void>; now?: () => number },
+): Promise<T | null> {
+  const intervalMs = opts.intervalMs ?? 250;
+  const sleep = opts.sleep ?? ((ms) => new Promise<void>((r) => setTimeout(r, ms)));
+  const now = opts.now ?? Date.now;
+  const deadline = now() + opts.timeoutMs;
+  for (;;) {
+    const value = await attempt();
+    if (value !== null) return value;
+    if (now() >= deadline) return null;
+    await sleep(intervalMs);
+  }
+}
+
+export async function runRun(parsed: ParsedArgs): Promise<number> {
+  const invocation = parseRunInvocation(parsed, process.env);
+  if (typeof invocation === 'string') {
+    process.stderr.write(invocation);
+    return 1;
+  }
+  const cwd = process.cwd();
+  let serveUrl: string;
+  let instanceId: string | null;
+  if (invocation.hostUrl !== null) {
+    const hostUrl = invocation.hostUrl;
+    const host = await pollUntil(() => probeHostUrl(hostUrl), { timeoutMs: invocation.waitMs });
+    if (host === null) {
+      const waited = invocation.waitMs > 0 ? ` after waiting ${invocation.waitMs / 1000}s` : '';
+      process.stderr.write(`pyric run: no sandbox host answers at ${hostUrl}/__pyric/health${waited}.\n`);
+      return 2;
+    }
+    serveUrl = host.base;
+    instanceId = host.instanceId;
+  } else {
+    const log = (line: string): void => void process.stderr.write(`pyric run: ${line}\n`);
+    const host = await pollUntil(() => discoverServe(cwd, log), { timeoutMs: invocation.waitMs });
+    if (host === null) {
+      process.stderr.write('pyric run: no running sandbox host found; pass --sandbox <url>.\n');
+      return 2;
+    }
+    serveUrl = host.base;
+    instanceId = host.instanceId;
+  }
+  const env = buildChildEnv(process.env, {
+    serveUrl,
+    registerUrl: registerModuleUrl(),
+    instanceId: instanceId ?? undefined,
+  });
+  const child = spawnSandboxChild(invocation.plan, { cwd, env, json: false });
+  const forward = (signal: NodeJS.Signals): void => child.signal(signal);
+  process.on('SIGINT', forward);
+  process.on('SIGTERM', forward);
+  try {
+    return await child.exited;
+  } finally {
+    process.off('SIGINT', forward);
+    process.off('SIGTERM', forward);
+  }
+}

package/src/cli/serve.ts

@@ -71,6 +71,7 @@ import {
   type SandboxSession,
 } from '../serve/sandbox-session.js';
 import { resolveAvatarsConfig } from '../serve/avatars-config.js';
+import { createVerifyHint } from '../serve/verify-hint.js';
 
 interface HostingConfig {
   public?: string;
@@ -552,6 +553,8 @@ async function startServeRuntime(opts: {
   // a failed reload asked for, so fixing or creating one reloads. The source
   // is the path the rules load from, watched whether or not it exists at
   // startup, so a rules file created later loads.
+  const getVerifyHint = createVerifyHint();
+
   const isWatchEnabled = opts.watch ?? true;
   if (isWatchEnabled) {
     let debounce: ReturnType<typeof setTimeout> | null = null;
@@ -567,7 +570,7 @@ async function startServeRuntime(opts: {
             const isReloaded = result.kind === 'reloaded';
             const isRejected = result.kind === 'rejected';
             if (isReloaded) {
-              logger.note(`  ↻ rules reloaded (hash ${result.rulesHash}) → ${result.clients} page(s)`);
+              logger.note(`  ↻ rules reloaded (hash ${result.rulesHash}) → ${result.clients} page(s)${getVerifyHint()}`);
               if (result.fixtureCheck && result.fixtureCheck.ran > 0) {
                 for (const line of result.fixtureCheck.lines) logger.note(line);
               }
@@ -610,7 +613,7 @@ async function startServeRuntime(opts: {
             void session.reloadDatabaseRules(changed).then((results) => {
               for (const { instance, file: source, result } of results) {
                 if (result.kind === 'reloaded') {
-                  logger.note(`  ↻ rtdb rules reloaded for ${instance} (hash ${result.rulesHash}) → ${result.clients} page(s)`);
+                  logger.note(`  ↻ rtdb rules reloaded for ${instance} (hash ${result.rulesHash}) → ${result.clients} page(s)${getVerifyHint()}`);
                   if (result.fixtureCheck && result.fixtureCheck.ran > 0) {
                     for (const line of result.fixtureCheck.lines) logger.note(line);
                   }
@@ -650,7 +653,7 @@ async function startServeRuntime(opts: {
         debounceStorage = setTimeout(() => {
           void session.reloadStorageRules().then((result) => {
             if (result.kind === 'reloaded') {
-              logger.note(`  ↻ storage rules reloaded (hash ${result.rulesHash}) → ${result.clients} page(s)`);
+              logger.note(`  ↻ storage rules reloaded (hash ${result.rulesHash}) → ${result.clients} page(s)${getVerifyHint()}`);
             } else if (result.kind === 'rejected') {
               logger.note(`  ⚠ storage rules NOT reloaded (last-good stays live): ${result.error.message}`);
             } else if (result.kind === 'removed') {

package/src/cli/verify.ts

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import {
   deriveRulesTestCases,
   fixtureVerifiableServices,
@@ -15,7 +15,12 @@ import {
   type VerifyRulesInput,
   type VerifyServiceResult,
 } from '../verify/index.js';
-import { readFirebaseJson, type FirebaseJson } from './firebase-json.js';
+import { readFirebaseJson, readFirebaseRcSync, type FirebaseJson } from './firebase-json.js';
+import { resolveFirebaseProject } from './firebase-project.js';
+import { readPyricConfig } from './pyric-config.js';
+import { markedProject, restoreStagingInstance, StagingSafetyError, stagingMarker } from '../verify/staging/engine.js';
+import { RtdbRestClient } from '../verify/staging/rest.js';
+import { assertNotAppInstance, stagingTargetFrom, stagingToken, type StagingTarget } from '../verify/staging/target.js';
 import type { FlagValue, ParsedArgs } from './parse-args.js';
 import { resolveScope } from '../credentials/node/scope.js';
 import { CAPTURE_RELATIVE_PATH } from '../serve/capture-store.js';
@@ -37,6 +42,8 @@ export interface FixtureResult {
 
 export interface VerifyCliDeps {
   resolveScope?: typeof resolveScope;
+  /** The staging instance's REST client; tests pass one backed by a local sandbox. */
+  stagingClient?: (target: StagingTarget, token: () => Promise<string>) => RtdbRestClient;
 }
 
 export function loadFixture(path: string): Fixture {
@@ -88,9 +95,16 @@ export function formatResults(results: FixtureResult[]): string {
     lines.push(`${marker} ${result.name}${desc} - ${serviceSummary}`);
     for (const service of Object.values(result.result.services)) {
       if (!service) continue;
-      for (const divergence of failingDivergences(service.divergences)) {
-        const where = divergence.instance === undefined ? service.service : `${service.service} ${divergence.instance}`;
-        lines.push(`    [${where}] ${formatDivergence(divergence)}`);
+      const engines = Object.values(service.engines ?? {}).filter((engine) => engine !== undefined);
+      // With more than one engine, each line names the engine that reported it.
+      const groups = engines.length > 1
+        ? engines.map((engine) => ({ label: ` ${engine.engine}`, divergences: engine.divergences }))
+        : [{ label: '', divergences: service.divergences }];
+      for (const group of groups) {
+        for (const divergence of failingDivergences(group.divergences)) {
+          const instance = divergence.instance === undefined ? '' : ` ${divergence.instance}`;
+          lines.push(`    [${service.service}${instance}${group.label}] ${formatDivergence(divergence)}`);
+        }
       }
     }
   }
@@ -104,6 +118,9 @@ export async function runVerify(parsed: ParsedArgs, deps: VerifyCliDeps = {}): P
   if (parsed.positional[0] === 'cases') {
     return runVerifyCases(parsed, cwd);
   }
+  if (parsed.positional[0] === 'staging') {
+    return runVerifyStaging(parsed, cwd, deps);
+  }
 
   const target = parsed.positional[0];
   const inputPath = resolve(cwd, target ?? CAPTURE_RELATIVE_PATH);
@@ -149,6 +166,23 @@ export async function runVerify(parsed: ParsedArgs, deps: VerifyCliDeps = {}): P
     return 2;
   }
 
+  // The staging target is checked before anything else reads the project: an
+  // instance the app uses is refused before a request is made.
+  let staging: VerifyFixtureOptions['staging'];
+  let stopStaging: (() => void) | undefined;
+  if (engines.includes('staging')) {
+    try {
+      const opened = await openStagingInstance(cwd, stringFlag(parsed.flags.get('project')), deps);
+      process.stderr.write(`pyric verify: staging instance ${opened.target.databaseUrl} (project ${opened.projectId}, credentials: ${opened.source})\n`);
+      const guard = stagingRunGuard(cwd, opened.target);
+      stopStaging = guard.stop;
+      staging = { client: opened.client, projectId: opened.projectId, ...guard.hooks };
+    } catch (e) {
+      process.stderr.write(`pyric verify: ${messageOf(e)}\n`);
+      return 2;
+    }
+  }
+
   let rulesResolution: { rules: VerifyRulesInput; paths: Record<string, string> };
   try {
     rulesResolution = await resolveCandidateRules({
@@ -177,19 +211,24 @@ export async function runVerify(parsed: ParsedArgs, deps: VerifyCliDeps = {}): P
   }
 
   let results: FixtureResult[];
+  const options = {
+    services,
+    engines,
+    ...(rulesTestApi ? { rulesTestApi } : {}),
+    ...(staging ? { staging } : {}),
+  };
   try {
-    results = await Promise.all(
-      loaded.map((item) =>
-        runFixture(item.name, item.fixture, rulesResolution.rules, {
-          services,
-          engines,
-          ...(rulesTestApi ? { rulesTestApi } : {}),
-        })),
-    );
+    // The staging engine holds one instance, so its fixtures run one at a time.
+    results = staging
+      ? await pipelineFixtures(loaded, (item) => runFixture(item.name, item.fixture, rulesResolution.rules, options))
+      : await Promise.all(loaded.map((item) => runFixture(item.name, item.fixture, rulesResolution.rules, options)));
   } catch (e) {
-    const prefix = e instanceof VerifyInputError ? 'invalid input' : 'failed to replay';
+    const prefix = e instanceof VerifyInputError ? 'invalid input' : e instanceof StagingSafetyError ? 'staging instance' : 'failed to replay';
     process.stderr.write(`pyric verify: ${prefix}: ${messageOf(e)}\n`);
-    return 2;
+    stopStaging?.();
+    return e instanceof StagingAbortedError || (e as { name?: string }).name === 'AbortError' ? 130 : 2;
+  } finally {
+    stopStaging?.();
   }
   const allOk = results.every((result) => result.ok);
 
@@ -259,6 +298,190 @@ function runVerifyCases(parsed: ParsedArgs, cwd: string): number {
   return result.ok ? 0 : 1;
 }
 
+/** The staging instance from `pyric.json`, refused when the app uses it, with credentials for its project. */
+async function openStagingInstance(
+  cwd: string,
+  appProjectOption: string | undefined,
+  deps: VerifyCliDeps,
+): Promise<{ client: RtdbRestClient; projectId: string; target: StagingTarget; source: string }> {
+  const target = stagingTargetFrom(await readPyricConfig(cwd));
+  const firebaseJson = await readFirebaseJsonOrNull(cwd);
+  const appProject = resolveFirebaseProject({ projectDir: cwd, ...(appProjectOption ? { option: appProjectOption } : {}) });
+  assertNotAppInstance(target, {
+    firebaseJson,
+    ...(appProject.projectId ? { appProjectId: appProject.projectId } : {}),
+    targetInstances: databaseTargetInstances(cwd, appProject.projectId),
+  });
+  const credentials = await stagingToken(target.projectId, deps.resolveScope ? { resolve: deps.resolveScope } : {});
+  const client = deps.stagingClient?.(target, credentials.token) ?? new RtdbRestClient(target.databaseUrl, credentials.token);
+  return { client, projectId: target.projectId, target, source: credentials.source };
+}
+
+/** Every instance a `.firebaserc` database target maps for the app's project. */
+function databaseTargetInstances(cwd: string, projectId: string | undefined): string[] {
+  if (!projectId) return [];
+  try {
+    const rc = readFirebaseRcSync(cwd) as { targets?: Record<string, { database?: Record<string, string[]> }> } | null;
+    return Object.values(rc?.targets?.[projectId]?.database ?? {}).flat();
+  } catch {
+    return [];
+  }
+}
+
+async function pipelineFixtures<T>(items: T[], run: (item: T) => Promise<FixtureResult>): Promise<FixtureResult[]> {
+  const out: FixtureResult[] = [];
+  for (const item of items) out.push(await run(item));
+  return out;
+}
+
+class StagingAbortedError extends Error {}
+
+/** Where a staging run keeps the prior rules while it runs, for `pyric verify staging restore`. */
+export const STAGING_RESTORE_RELATIVE_PATH = join('.pyric', 'staging-restore.json');
+
+/**
+ * While a staging run is active: keep the prior rules on disk, and turn
+ * SIGINT/SIGTERM into an abort between steps so the run still cleans up. A
+ * second signal exits at once, naming the recovery command.
+ */
+function stagingRunGuard(cwd: string, target: StagingTarget): { hooks: Pick<NonNullable<VerifyFixtureOptions['staging']>, 'onBeforeChange' | 'onRestored' | 'signal'>; stop: () => void } {
+  const controller = new AbortController();
+  const restorePath = join(cwd, STAGING_RESTORE_RELATIVE_PATH);
+  let signals = 0;
+  const onSignal = (signal: NodeJS.Signals) => {
+    signals += 1;
+    if (signals === 1) {
+      process.stderr.write(`\npyric verify: ${signal}: stopping after the current step and restoring ${target.databaseUrl}. Press again to quit without restoring.\n`);
+      controller.abort(new StagingAbortedError(`interrupted by ${signal}`));
+      return;
+    }
+    process.stderr.write(`pyric verify: quitting without restoring ${target.databaseUrl}. Run \`pyric verify staging restore\` to put it back.\n`);
+    process.exit(130);
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  let stopped = false;
+  return {
+    hooks: {
+      signal: controller.signal,
+      onBeforeChange: (priorRules) => {
+        mkdirSync(dirname(restorePath), { recursive: true });
+        writeFileSync(restorePath, `${JSON.stringify({ databaseUrl: target.databaseUrl, projectId: target.projectId, rules: priorRules, startedAt: new Date().toISOString() }, null, 2)}\n`);
+      },
+      onRestored: () => rmSync(restorePath, { force: true }),
+    },
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      process.off('SIGINT', onSignal);
+      process.off('SIGTERM', onSignal);
+    },
+  };
+}
+
+/**
+ * `pyric verify staging restore`: put the configured instance back after a run
+ * that could not, from the prior rules the run kept in
+ * `.pyric/staging-restore.json`; with `--force` and no such file, enroll it
+ * afresh with deny-all rules. Its data is deleted either way.
+ */
+async function runVerifyStagingRestore(parsed: ParsedArgs, cwd: string, deps: VerifyCliDeps): Promise<number> {
+  let opened: Awaited<ReturnType<typeof openStagingInstance>>;
+  try {
+    opened = await openStagingInstance(cwd, stringFlag(parsed.flags.get('project')), deps);
+  } catch (e) {
+    process.stderr.write(`pyric verify staging restore: ${messageOf(e)}\n`);
+    return 2;
+  }
+  const { client, target } = opened;
+  const restorePath = join(cwd, STAGING_RESTORE_RELATIVE_PATH);
+  let rules: string | undefined;
+  if (existsSync(restorePath)) {
+    const kept = JSON.parse(readFileSync(restorePath, 'utf8')) as { databaseUrl?: string; rules?: string };
+    if (kept.databaseUrl !== target.databaseUrl) {
+      process.stderr.write(`pyric verify staging restore: ${STAGING_RESTORE_RELATIVE_PATH} is for ${kept.databaseUrl}, not ${target.databaseUrl}.\n`);
+      return 2;
+    }
+    rules = kept.rules;
+  } else if (parsed.flags.get('force') === true) {
+    rules = `${stagingMarker(target.projectId)}\n{\n  "rules": {\n    ".read": false,\n    ".write": false\n  }\n}`;
+  } else {
+    const current = await client.getRulesText().catch(() => '');
+    if (markedProject(current) === target.projectId && (await client.get('/', { shallow: true })).body === null) {
+      process.stdout.write(`✓ ${target.databaseUrl} is enrolled and empty; nothing to restore.\n`);
+      return 0;
+    }
+    process.stderr.write(
+      `pyric verify staging restore: no ${STAGING_RESTORE_RELATIVE_PATH} holds the rules ${target.databaseUrl} had. ` +
+        'Pass --force to deploy deny-all rules with the enrollment marker and delete its data.\n',
+    );
+    return 2;
+  }
+  if (typeof rules !== 'string' || markedProject(rules) !== target.projectId) {
+    process.stderr.write(`pyric verify staging restore: the kept rules do not carry the enrollment marker for ${target.projectId}; refusing to deploy them.\n`);
+    return 2;
+  }
+  const result = await restoreStagingInstance(client, rules);
+  if (!result.rulesRestored || !result.dataRemoved) {
+    process.stderr.write(`pyric verify staging restore: ${target.databaseUrl} is not restored (${result.errors.join('; ')}).\n`);
+    return 1;
+  }
+  rmSync(restorePath, { force: true });
+  process.stdout.write(`✓ restored ${target.databaseUrl}: enrolled rules deployed, data deleted.\n`);
+  return 0;
+}
+
+/** `pyric verify staging init`: enroll the configured instance, once. */
+async function runVerifyStaging(parsed: ParsedArgs, cwd: string, deps: VerifyCliDeps): Promise<number> {
+  if (parsed.positional[1] === 'restore') return runVerifyStagingRestore(parsed, cwd, deps);
+  if (parsed.positional[1] !== 'init') {
+    process.stderr.write('pyric verify staging: use `init` to enroll the instance pyric.json names, or `restore` to put it back after an interrupted run.\n');
+    return 2;
+  }
+  let opened: Awaited<ReturnType<typeof openStagingInstance>>;
+  try {
+    opened = await openStagingInstance(cwd, stringFlag(parsed.flags.get('project')), deps);
+  } catch (e) {
+    process.stderr.write(`pyric verify staging init: ${messageOf(e)}\n`);
+    return 2;
+  }
+  const { client, target } = opened;
+  try {
+    const rules = await client.getRulesText();
+    const marked = markedProject(rules);
+    if (marked === target.projectId) {
+      process.stdout.write(`✓ ${target.databaseUrl} is already enrolled for project ${target.projectId}.\n`);
+      return 0;
+    }
+    if (marked !== undefined) {
+      process.stderr.write(`pyric verify staging init: ${target.databaseUrl} is enrolled for project ${marked}, not ${target.projectId}.\n`);
+      return 2;
+    }
+    const root = await client.get('/', { shallow: true });
+    if (root.status !== 200 || root.body !== null) {
+      process.stderr.write(
+        `pyric verify staging init: refusing to enroll ${target.databaseUrl}: it holds data (or could not be read, HTTP ${root.status}). ` +
+          'The staging engine replaces an instance\'s rules and data, so enroll an empty instance created for it.\n',
+      );
+      return 2;
+    }
+    const enrolled = `${stagingMarker(target.projectId)}\n${rules.trimStart()}`;
+    const dry = await client.putRules(enrolled, { dryRun: true });
+    if (dry.status !== 200) throw new Error(`production refused the marked rules: HTTP ${dry.status} ${dry.text.slice(0, 200)}`);
+    const put = await client.putRules(enrolled);
+    if (put.status !== 200) throw new Error(`deploying the marked rules failed: HTTP ${put.status} ${put.text.slice(0, 200)}`);
+    if (markedProject(await client.getRulesText()) !== target.projectId) throw new Error('the marker did not read back.');
+  } catch (e) {
+    process.stderr.write(`pyric verify staging init: ${messageOf(e)}\n`);
+    return 1;
+  }
+  process.stdout.write(
+    `✓ enrolled ${target.databaseUrl} (project ${target.projectId}, credentials: ${opened.source}).\n` +
+      '  Run `pyric verify --engine staging` to replay a captured session against it; add `--engine sandbox` to compare engines.\n',
+  );
+  return 0;
+}
+
 function loadFixturesFromDirectory(dir: string): Array<{ name: string; fixture: Fixture }> {
   return readdirSync(dir)
     .filter((f) => f.endsWith('.json'))
@@ -296,8 +519,10 @@ function parseEngines(flag: FlagValue | undefined): VerifyEngine[] {
       pushUnique(out, 'sandbox');
     } else if (item === 'rules-test-api' || item === 'rulesTestApi') {
       pushUnique(out, 'rulesTestApi');
+    } else if (item === 'staging') {
+      pushUnique(out, 'staging');
     } else {
-      throw new Error(`unsupported verify engine '${item}'. Supported engines: sandbox, rules-test-api, both.`);
+      throw new Error(`unsupported verify engine '${item}'. Supported engines: sandbox, rules-test-api, staging, both.`);
     }
   }
   return out;
@@ -447,7 +672,8 @@ function formatDivergence(divergence: VerifyDivergence): string {
   }
   if (divergence.kind === 'engine-drift') {
     const method = divergence.method ? `${divergence.method} ` : '';
-    return `engine-drift: ${method}${divergence.path ?? ''}: sandbox=${divergence.sandbox}, rulesTestApi=${divergence.rulesTestApi}`;
+    const other = divergence.staging !== undefined ? `staging=${divergence.staging}` : `rulesTestApi=${divergence.rulesTestApi}`;
+    return `engine-drift: ${method}${divergence.path ?? ''}: sandbox=${divergence.sandbox}, ${other}`;
   }
   return `${divergence.drift}: ${divergence.path ?? ''}`;
 }