@pyric/cli 0.1.0-alpha.25 → 0.1.0-alpha.27

package/src/assurance/validation.ts

@@ -13,13 +13,17 @@
  * `observations[0]`, `probes[2]`. A caller that validates one record on its
  * own passes nothing and gets the record's kind instead.
  */
+import { resolveDatabaseInstance } from "pyric/sandbox/internal";
+import { rtdbRulesSourceRejection } from "pyric/rules/internal/rtdb";
 import {
+  ASSURANCE_CAMPAIGN_SCHEMA,
   ASSURANCE_TARGET_SCHEMA,
   AssuranceInputError,
   type AssuranceActor,
   type AssuranceObservation,
   type AssuranceProbe,
   type FirebaseOperation,
+  type AuthorizationCampaignSpec,
   type LocalFirebaseTarget,
   type MutationDimension,
   type SecurityInvariant,
@@ -225,13 +229,56 @@ export function assertTarget(
   if (target.rules.rtdb !== undefined) {
     requiredRecord(target.rules.rtdb, `${where}.rules.rtdb`);
     requiredRecord(target.rules.rtdb.rules, `${where}.rules.rtdb.rules`);
+
+  }
+
+  const declaredRuleInstances = new Map<string, string>();
+  if (target.rules.rtdbInstances !== undefined) {
+    requiredRecord(target.rules.rtdbInstances, `${where}.rules.rtdbInstances`);
+    for (const [instance, rules] of Object.entries(target.rules.rtdbInstances)) {
+      const at = `${where}.rules.rtdbInstances[${JSON.stringify(instance)}]`;
+      requiredRecord(rules, at);
+      requiredRecord((rules as any).rules, `${at}.rules`);
+      try {
+        const resolvedName = resolveDatabaseInstance(instance)!.name;
+        if (declaredRuleInstances.has(resolvedName)) {
+           throw new AssuranceInputError(`${at} declares instance '${resolvedName}' which is already declared by key '${declaredRuleInstances.get(resolvedName)}'`);
+        }
+        declaredRuleInstances.set(resolvedName, instance);
+      } catch (e) {
+        if (e instanceof AssuranceInputError) throw e;
+        throw new AssuranceInputError(`${at} names a malformed RTDB instance: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
   }
+
   if (target.state.firestore !== undefined) {
     requiredRecord(target.state.firestore, `${where}.state.firestore`);
     for (const [docPath, docData] of Object.entries(target.state.firestore)) {
       requiredRecord(docData, `${where}.state.firestore[${docPath}]`);
     }
   }
+  if (target.state.rtdbInstances !== undefined) {
+    requiredRecord(target.state.rtdbInstances, `${where}.state.rtdbInstances`);
+    const declaredStateInstances = new Map<string, string>();
+    for (const [instance] of Object.entries(target.state.rtdbInstances)) {
+      const at = `${where}.state.rtdbInstances[${JSON.stringify(instance)}]`;
+      try {
+        const resolvedName = resolveDatabaseInstance(instance)!.name;
+        if (!declaredRuleInstances.has(resolvedName)) {
+           throw new AssuranceInputError(`${at} provides state for instance '${resolvedName}' which has no declared rules`);
+        }
+        if (declaredStateInstances.has(resolvedName)) {
+           throw new AssuranceInputError(`${at} provides state for instance '${resolvedName}' which is already provided by key '${declaredStateInstances.get(resolvedName)}'`);
+        }
+        declaredStateInstances.set(resolvedName, instance);
+      } catch (e) {
+        if (e instanceof AssuranceInputError) throw e;
+        throw new AssuranceInputError(`${at} names a malformed RTDB instance: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+  }
+
   if (target.state.storage !== undefined) {
     if (!Array.isArray(target.state.storage)) {
       throw new AssuranceInputError(
@@ -367,6 +414,9 @@ function assertOperation(
 ): asserts operation is FirebaseOperation {
   requiredRecord(operation, where);
   enumValue(operation.service, OPERATION_SERVICES, where, "service");
+  if (operation.service === "rtdb" && (operation as any).instance !== undefined) {
+    requiredString((operation as any).instance, where, "instance");
+  }
   requiredString(operation.path, where, "path");
   enumValue(
     operation.method,
@@ -507,3 +557,90 @@ export function changedDimensions(
   }
   return changed;
 }
+
+
+export function assertCampaign(spec: AuthorizationCampaignSpec): void {
+  if (spec.schema !== ASSURANCE_CAMPAIGN_SCHEMA) {
+    throw new AssuranceInputError(
+      `campaign schema must be '${ASSURANCE_CAMPAIGN_SCHEMA}'.`,
+    );
+  }
+  if (!spec.id.trim())
+    throw new AssuranceInputError("campaign id is required.");
+  assertTarget(spec.target);
+  if (!Array.isArray(spec.actors)) {
+    throw new AssuranceInputError("campaign actors must be an array.");
+  }
+  if (!Array.isArray(spec.invariants)) {
+    throw new AssuranceInputError("campaign invariants must be an array.");
+  }
+  if (!Array.isArray(spec.probes)) {
+    throw new AssuranceInputError("campaign probes must be an array.");
+  }
+  for (const actor of spec.actors) assertActor(actor);
+  for (const invariant of spec.invariants) assertInvariant(invariant);
+  for (const probe of spec.probes) assertProbe(probe);
+  uniqueIds(spec.actors, "actor");
+  uniqueIds(spec.invariants, "invariant");
+  uniqueIds(spec.probes, "probe");
+
+  const declaredRtdbInstances = spec.target.rules.rtdbInstances ? Object.keys(spec.target.rules.rtdbInstances).map(k => resolveDatabaseInstance(k)!.name) : [];
+  for (const probe of spec.probes) {
+    for (const op of [probe.control, probe.mutation.operation]) {
+      // test what happens to unknown fields (unrecognized keys)
+      const allowedKeys = new Set(["service", "method", "path", "data", "query", "dataBase64", "contentType", "customMetadata", "instance"]);
+      for (const key of Object.keys(op)) {
+        if (!allowedKeys.has(key)) {
+          throw new AssuranceInputError(`operation names unknown field '${key}'`);
+        }
+      }
+      
+      if (op.service === "rtdb" && op.instance !== undefined && op.instance !== "default") {
+        let resolvedName;
+        try {
+          resolvedName = resolveDatabaseInstance(op.instance)!.name;
+        } catch (e) {
+          throw new AssuranceInputError(`invalid RTDB instance '${op.instance}': ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!declaredRtdbInstances.includes(resolvedName)) {
+          throw new AssuranceInputError(`probe '${probe.id}' names undeclared RTDB instance '${op.instance}'. Declared instances: ${declaredRtdbInstances.length > 0 ? declaredRtdbInstances.join(", ") : "none"}.`);
+        }
+      }
+    }
+  }
+
+  for (const probe of spec.probes) {
+    const actor = spec.actors.find((item) => item.id === probe.actorId);
+    const invariant = spec.invariants.find(
+      (item) => item.id === probe.invariantId,
+    );
+    if (!actor)
+      throw new AssuranceInputError(
+        `probe '${probe.id}' references unknown actor '${probe.actorId}'.`,
+      );
+    if (!invariant) {
+      throw new AssuranceInputError(
+        `probe '${probe.id}' references unknown invariant '${probe.invariantId}'.`,
+      );
+    }
+    if (
+      invariant.service !== "cross-service" &&
+      invariant.service !== probe.control.service
+    ) {
+      throw new AssuranceInputError(
+        `probe '${probe.id}' service does not match invariant '${invariant.id}'.`,
+      );
+    }
+  }
+}
+
+function uniqueIds(items: ReadonlyArray<{ id: string }>, label: string): void {
+  const seen = new Set<string>();
+  for (const item of items) {
+    if (!item.id.trim())
+      throw new AssuranceInputError(`${label} id is required.`);
+    if (seen.has(item.id))
+      throw new AssuranceInputError(`duplicate ${label} id '${item.id}'.`);
+    seen.add(item.id);
+  }
+}

package/src/bridge/surface/arguments/assurance.ts

@@ -82,6 +82,7 @@ export const OPERATION_METHOD_VALUES: readonly string[] = [
 export const firebaseOperation = z
   .object({
     service: z.enum(OPERATION_SERVICES).describe('The service the operation runs against.'),
+    instance: z.string().optional().describe('The named RTDB instance, if the service is rtdb.'),
     method: z
       .enum(OPERATION_METHOD_VALUES as [string, ...string[]])
       .describe('The request method, from the set the named service evaluates.'),

package/src/cli/database-rules.ts

@@ -236,6 +236,6 @@ export async function runDatabaseRulesGenerate(
   await mkdirFn(dirname(resolvedOut), { recursive: true });
   await writeFileFn(resolvedOut, `${JSON.stringify(rulesJson, null, 2)}\n`, 'utf-8');
 
-  out.write(`pyric database rules generate: wrote ${resolvedOut}\n`);
+  out.write(`pyric database rules generate: wrote ${resolvedOut}\n  Test before deploy: pyric verify --service rtdb --rules rtdb=${outPath}\n`);
   return 0;
 }

package/src/cli/index.ts

@@ -63,9 +63,11 @@ USAGE
   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>]
@@ -110,9 +112,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 +128,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.

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/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 ?? ''}`;
 }