pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/sandbox/branches/index.ts

@@ -1,449 +1,13 @@
 /**
- * Branches — a fork / apply / diff / promote / discard primitive built
- * **on top of** the existing `snapshot()` + `replay()` surface. Nothing
- * here re-implements those; a branch is an in-memory sandbox seeded from
- * a {@link SandboxSnapshot}, with `apply` delegating to `replay()` and
- * `diff` reusing the replay engine's structural divergence classifier.
- *
- * Mental model (the Pyric Studio "experiment" primitive — see
- * the design rationale):
- *
- *   const branch = fork(live.snapshot(), rules);   // isolated copy
- *   apply(branch, agentPlanEvents);                // re-issue writes
- *   const changes = diff(branch, live);            // what changed vs live
- *   promote(branch, live);   // land the branch's mutations on live
- *   // ...or...
- *   discard(branch);         // drop it; live is untouched
- *
- * This is the substrate for Studio's agent dry-run → accept/reject
- * (A1), rules-failure "re-run against an edited ruleset" (F4), and
- * time-travel (A2). Each of those wants: an isolated copy of current
- * state, a way to play hypothetical writes against it, a structural
- * diff, and a commit/rollback gate.
- *
- * Granularity / honesty notes:
- *   - `fork` rehydrates **Firestore** state from the snapshot (the
- *     `firestore` key) plus rules. Per-service state in
- *     `snapshot.services` (auth users, etc.) is NOT rehydrated here —
- *     a fresh fork has no registered persistable services to restore
- *     into, mirroring how persistence skips unregistered services. If a
- *     consumer needs auth-in-a-branch it can register services on the
- *     branch sandbox and restore them; that's out of scope for v1.
- *   - `diff` reuses the replay engine's doc-level + field-level walk
- *     (`Divergence`). Without captured write metadata it can't license
- *     sentinel/auto-id drift, so every field difference surfaces as
- *     `real-divergence` — which is the correct, honest classification
- *     for "branch state vs live state" (there are no replayed sentinels
- *     to reconcile). Doc add/remove surface as presence divergences.
- *   - `promote` re-issues the branch's accumulated write events onto the
- *     target via `replay`'s machinery, then copies the resulting docs
- *     onto the target through the admin plane. It applies *mutations*
- *     (added/changed/removed docs), not a blind whole-snapshot replace —
- *     docs the branch never touched are left alone on the target.
- */
-
-import {
-  initializeSandbox,
-  type Divergence,
-  type LocalSandbox,
-  type SandboxEvent,
-  type SandboxSnapshot,
-  type WriteSandboxEvent,
-} from '../index.js';
-import { getInternalEnv } from '../internal/sandbox-impl.js';
-import { Timestamp } from 'pyric/rules/internal';
-import { getOrCreateBackend } from '../../database/sandbox/backend-for.js';
-import { stripJsonComments } from '../../database/sandbox-controls.js';
-import type { JsonValue } from '../../database/sandbox/data-tree.js';
-
-type DocData = Record<string, unknown>;
-
-/**
- * An isolated, in-memory experiment seeded from a {@link SandboxSnapshot}.
- *
- * A branch owns its own {@link LocalSandbox} (fully isolated from the source —
- * separate `LocalEnvironment`, separate event history) plus the
- * accumulated {@link SandboxEvent}s applied to it via {@link apply}. The
- * applied events are what {@link promote} replays onto the target.
- */
-export interface Branch {
-  /** The branch's own sandbox. Inspect it directly (`branch.sandbox.snapshot()`)
-   *  or read docs via `branch.sandbox.admin.getDocument(path)`. */
-  readonly sandbox: LocalSandbox;
-  /** Rules the branch was forked with — carried so {@link promote} can
-   *  re-seed a replay target identically. */
-  readonly rules: string;
-  /** The snapshot this branch was forked from. Retained so {@link diff}
-   *  and {@link promote} can reason about the baseline. */
-  readonly base: SandboxSnapshot;
-  /** Write/op events applied to this branch since fork, in order. These
-   *  are replayed onto the target by {@link promote}. */
-  readonly events: SandboxEvent[];
-  /** Flipped by {@link discard}; subsequent {@link apply}/{@link promote}
-   *  calls throw. */
-  discarded: boolean;
-}
-
-/** A reference to diff a branch against: a live sandbox or a bare snapshot. */
-export type DiffTarget = LocalSandbox | SandboxSnapshot;
-
-/**
- * Fork a new branch from a snapshot.
- *
- * Seeds a fresh sandbox with `rules` and the snapshot's Firestore docs
- * (the same `seed({ rules, documents })` path replay uses to stand up a
- * clean environment). The branch is fully isolated: writes on it never
- * touch the source sandbox.
- *
- * @param snapshot Baseline state — typically `liveSandbox.snapshot()`.
- * @param rules    Rules source for the branch. Pass the live rules to
- *                 reproduce production behaviour, or an *edited* ruleset
- *                 to test a rules change in isolation (Studio F4).
- */
-export function fork(snapshot: SandboxSnapshot, rules = ''): Branch {
-  const sandbox = initializeSandbox();
-  const env = getInternalEnv(sandbox);
-
-  const hasServices = snapshot.services !== undefined;
-  let isRtdbPresent = false;
-  if (hasServices) {
-    const isServicesNotNull = snapshot.services !== null;
-    if (isServicesNotNull) {
-      const hasRtdbKey = 'rtdb' in snapshot.services;
-      if (hasRtdbKey) {
-        const rtdbState = snapshot.services.rtdb;
-        const isRtdbStateNotNull = rtdbState !== null;
-        const isRtdbStateNotUndefined = rtdbState !== undefined;
-        if (isRtdbStateNotNull) {
-          if (isRtdbStateNotUndefined) {
-            isRtdbPresent = true;
-          }
-        }
-      }
-    }
-  }
-
-  if (isRtdbPresent) {
-    const rtdbBackend = getOrCreateBackend(sandbox);
-    const rtdbData = snapshot.services.rtdb as Record<string, unknown>;
-    rtdbBackend.restoreTree(rtdbData as unknown as JsonValue);
-  }
-
-  const isRulesProvided = rules !== '';
-  let isRtdbRuleset = false;
-  if (isRulesProvided) {
-    const trimmed = rules.trim();
-    const startsWithBrace = trimmed.startsWith('{');
-    if (startsWithBrace) {
-      try {
-        const stripped = stripJsonComments(rules);
-        const parsed = JSON.parse(stripped) as Record<string, unknown>;
-        const isObject = typeof parsed === 'object';
-        const isNotNull = parsed !== null;
-        const isNotArray = !Array.isArray(parsed);
-        let isValidObject = false;
-        if (isObject) {
-          if (isNotNull) {
-            if (isNotArray) {
-              isValidObject = true;
-            }
-          }
-        }
-        if (isValidObject) {
-          const hasRulesKey = 'rules' in parsed;
-          if (hasRulesKey) {
-            isRtdbRuleset = true;
-          }
-        }
-      } catch {
-        isRtdbRuleset = false;
-      }
-    }
-  }
-
-  let firestoreRules = '';
-  if (isRtdbRuleset) {
-    const rtdbBackend = getOrCreateBackend(sandbox);
-    const stripped = stripJsonComments(rules);
-    const parsed = JSON.parse(stripped) as { rules: Record<string, unknown> };
-    rtdbBackend.setRules(parsed);
-  } else {
-    firestoreRules = rules;
-  }
-
-  // Copy-on-write fork: the branch reads `snapshot.firestore` as an immutable
-  // base (no clone, O(1)) and lands its own writes in an overlay. The snapshot
-  // is a stable, branch-owned object the live sandbox never mutates, so the
-  // branch stays isolated from later live writes.
-  env.seed({ rules: firestoreRules, baseDocuments: snapshot.firestore });
-  return {
-    sandbox,
-    rules,
-    base: snapshot,
-    events: [],
-    discarded: false,
-  };
-}
-
-/**
- * Apply a stream of events to a branch by re-issuing their writes against
- * the branch's CURRENT state.
- *
- * This is the same per-write re-issue logic `replay()` runs (filter to
- * `kind: 'write'`, honour `autoId` / pinned `requestTime`, prefer the
- * pre-resolution `request.resourceData` so sentinels re-resolve), but
- * applied *incrementally* on the branch's existing env rather than on a
- * fresh empty sandbox — so it composes over base docs (e.g. an `update`
- * lands on a doc the snapshot seeded) and accumulates across multiple
- * `apply` calls. The applied events are folded into `branch.events` so
- * {@link promote} can reproduce the same sequence on the target.
- *
- * @returns the same branch (mutated in place) for chaining.
- */
-export function apply(branch: Branch, events: readonly SandboxEvent[]): Branch {
-  assertLive(branch);
-  const env = getInternalEnv(branch.sandbox);
-  const writes = events.filter((e): e is WriteSandboxEvent => e.kind === 'write');
-
-  for (const wEv of writes) {
-    // Prefer the paired request event's pre-resolution payload (sentinels
-    // intact); fall back to the write's post-resolution `data`.
-    const data = preResolutionDataFor(wEv, events) ?? wEv.data;
-    const requestTime = new Timestamp(wEv.requestTime.seconds, wEv.requestTime.nanoseconds);
-
-    if (wEv.autoId) {
-      const collection = wEv.path.slice(0, wEv.path.lastIndexOf('/'));
-      env.createWithAutoId(collection, (data ?? {}) as DocData, wEv.auth);
-      continue;
-    }
-
-    try {
-      env.execute({
-        method: wEv.method,
-        path: wEv.path,
-        auth: wEv.auth,
-        ...(data !== undefined ? { data: data as DocData } : {}),
-        requestTime,
-      });
-    } catch {
-      // A denied/failed re-issue surfaces later as state divergence in
-      // diff(); keep going so one bad write doesn't abort the rest.
-    }
-  }
-
-  branch.events.push(...events);
-  return branch;
-}
-
-/**
- * Best-effort pre-resolution payload for a write — the `request` event at
- * or before it (same path) carries `request.resourceData` with sentinels
- * intact. Mirrors the replay engine's `preResolutionDataFor`.
- */
-function preResolutionDataFor(
-  wEv: WriteSandboxEvent,
-  allEvents: readonly SandboxEvent[],
-): DocData | undefined {
-  const wIdx = allEvents.indexOf(wEv);
-  if (wIdx < 0) return undefined;
-  for (let i = wIdx; i >= 0; i--) {
-    const e = allEvents[i];
-    if (!e || e.kind !== 'request') continue;
-    if (e.path !== wEv.path) continue;
-    return e.request?.resourceData as DocData | undefined;
-  }
-  return undefined;
-}
-
-/**
- * Structural diff of a branch's current state against a reference.
- *
- * Reuses the replay engine's `Divergence` result type and mirrors its
- * doc-level + field-level walk (see {@link diffDocSets}). With no captured
- * write metadata in play, differences surface as `real-divergence`
- * (field/doc changed) — the honest classification for "branch vs live".
- * Added/removed docs surface as presence divergences (one side
- * `undefined`).
- *
- * @param branch The experiment.
- * @param target Live sandbox or a snapshot to compare against.
- */
-export function diff(branch: Branch, target: DiffTarget): Divergence[] {
-  assertLive(branch);
-  const branchDocs = getInternalEnv(branch.sandbox).snapshot();
-  const targetDocs = firestoreSnapshotOf(target);
-  return diffDocSets(targetDocs, branchDocs);
-}
-
-/**
- * Promote a branch's mutations onto a target (live) sandbox.
- *
- * "Honest promote": it computes the doc-level delta between the branch's
- * BASE snapshot and its current state — i.e. exactly what the applied
- * events changed — and lands only those mutations on the target through
- * the admin plane:
- *   - docs added/changed on the branch → `admin.setDocument`
- *   - docs deleted on the branch       → `admin.deleteDocument`
- *   - docs the branch never touched    → left untouched on the target
- *
- * Admin-plane application fires the target's listeners (matching how
- * persistence restore lands docs), so live UI/handles see the promotion.
- *
- * The branch is marked discarded afterward — a promoted branch is spent.
- *
- * @param branch The experiment to land.
- * @param target The live sandbox to land it on.
- */
-export function promote(branch: Branch, target: LocalSandbox): void {
-  assertLive(branch);
-  const baseDocs = branch.base.firestore;
-  const finalDocs = getInternalEnv(branch.sandbox).snapshot();
-
-  const paths = new Set([...Object.keys(baseDocs), ...Object.keys(finalDocs)]);
-  for (const path of paths) {
-    const before = baseDocs[path];
-    const after = finalDocs[path];
-    if (after === undefined) {
-      // Branch deleted this doc relative to its base.
-      target.admin.deleteDocument(path);
-      continue;
-    }
-    if (before === undefined || !sandboxDocumentsEqual(before, after)) {
-      // Branch added or changed this doc.
-      target.admin.setDocument(path, after);
-    }
-    // else: unchanged on the branch — leave the target's copy alone.
-  }
-
-  branch.discarded = true;
-  branch.sandbox.dispose();
-}
-
-/**
- * Discard a branch: drop its sandbox and mark it spent. The target is
- * never touched (nothing was promoted). Idempotent.
- */
-export function discard(branch: Branch): void {
-  if (branch.discarded) return;
-  branch.discarded = true;
-  branch.sandbox.dispose();
-}
-
-// ---------------------------------------------------------------------------
-// internals
-// ---------------------------------------------------------------------------
-
-function assertLive(branch: Branch): void {
-  if (branch.discarded) {
-    throw new Error('Branch has been discarded or promoted; create a new fork.');
-  }
-}
-
-/** Resolve only Firestore documents without traversing registered services. */
-function firestoreSnapshotOf(
-  target: DiffTarget,
-): SandboxSnapshot['firestore'] {
-  if (isSandbox(target)) return getInternalEnv(target).snapshot();
-  return target.firestore;
-}
-
-function isSandbox(target: DiffTarget): target is LocalSandbox {
-  return typeof (target as LocalSandbox).snapshot === 'function';
-}
-
-/**
- * Doc-set structural diff. Mirrors the replay engine's doc-level + field-
- * level walk and reuses its `Divergence` result type. The replay engine's
- * own classifier is bound to captured write metadata (sentinels / auto-id
- * aliases) which a branch-vs-live comparison doesn't have, so this is the
- * "focused doc-level diff" the spec calls for when that machinery doesn't
- * fit: every leaf difference is `real-divergence`, and doc add/remove
- * surface as presence divergences (one side `undefined`).
- */
-function diffDocSets(
-  beforeDocs: Record<string, DocData>,
-  afterDocs: Record<string, DocData>,
-): Divergence[] {
-  const out: Divergence[] = [];
-  const allPaths = new Set([...Object.keys(beforeDocs), ...Object.keys(afterDocs)]);
-  for (const path of allPaths) {
-    const before = beforeDocs[path];
-    const after = afterDocs[path];
-    if (before === undefined && after !== undefined) {
-      out.push({ kind: 'real-divergence', path, before: undefined, after });
-      continue;
-    }
-    if (before !== undefined && after === undefined) {
-      out.push({ kind: 'real-divergence', path, before, after: undefined });
-      continue;
-    }
-    if (before === undefined || after === undefined) continue;
-    walkDoc(path, before, after, out);
-  }
-  return out;
-}
-
-/**
- * Field-level walk producing dotted/bracket leaf paths — mirrors the
- * replay engine's `diffDoc` walk (same path syntax: `profile.lastSeen`,
- * `tags[0]`). Every leaf difference is `real-divergence`; there is no
- * captured sentinel metadata in a branch-vs-live diff to license drift.
- */
-function walkDoc(path: string, before: unknown, after: unknown, out: Divergence[]): void {
-  walk(before, after, '');
-
-  function walk(a: unknown, b: unknown, fieldPath: string): void {
-    if (a === b) return;
-
-    const aIsObj = a !== null && typeof a === 'object' && !Array.isArray(a);
-    const bIsObj = b !== null && typeof b === 'object' && !Array.isArray(b);
-    if (aIsObj && bIsObj) {
-      const ao = a as Record<string, unknown>;
-      const bo = b as Record<string, unknown>;
-      const keys = new Set([...Object.keys(ao), ...Object.keys(bo)]);
-      for (const k of keys) {
-        const next = fieldPath ? `${fieldPath}.${k}` : k;
-        walk(ao[k], bo[k], next);
-      }
-      return;
-    }
-
-    if (Array.isArray(a) && Array.isArray(b)) {
-      const len = Math.max(a.length, b.length);
-      for (let i = 0; i < len; i++) {
-        walk(a[i], b[i], `${fieldPath}[${i}]`);
-      }
-      return;
-    }
-
-    if (sandboxDocumentsEqual(a, b)) return;
-    out.push({ kind: 'real-divergence', path, field: fieldPath || undefined, before: a, after: b });
-  }
-}
-
-/** Structural equality on sandbox document snapshots. */
-function sandboxDocumentsEqual(a: unknown, b: unknown): boolean {
-  if (a === b) return true;
-  if (a === null || b === null) return false;
-  if (typeof a !== 'object' || typeof b !== 'object') return false;
-  const aArr = Array.isArray(a);
-  const bArr = Array.isArray(b);
-  if (aArr !== bArr) return false;
-  if (aArr && bArr) {
-    if (a.length !== b.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!sandboxDocumentsEqual(a[i], b[i])) return false;
-    }
-    return true;
-  }
-  const ao = a as Record<string, unknown>;
-  const bo = b as Record<string, unknown>;
-  const ak = Object.keys(ao);
-  const bk = Object.keys(bo);
-  if (ak.length !== bk.length) return false;
-  for (const k of ak) {
-    if (!Object.prototype.hasOwnProperty.call(bo, k)) return false;
-    if (!sandboxDocumentsEqual(ao[k], bo[k])) return false;
-  }
-  return true;
-}
+ * `pyric/sandbox/branches` is the branch primitive's public surface.
+ *
+ * Re-exports only. The engine lives in `engine.ts`, the cross-service diff in
+ * `state-diff.ts`, and the promotion delta in `promotion.ts`. The on-disk
+ * store lives in `store.ts` and is published from its own subpath because it
+ * reads files.
+ */
+export { apply, diff, discard, fork, promote } from './engine.js';
+export type { Branch, BranchCandidateRules, DiffTarget } from './engine.js';
+export { diffFullStates } from './state-diff.js';
+export type { BranchDivergence, TreeChange } from './state-diff.js';
+export { promoteFullState } from './promotion.js';

package/src/sandbox/branches/promotion.ts

@@ -0,0 +1,207 @@
+/**
+ * Landing a branch on a target, service by service.
+ *
+ * A promotion is a delta, not a clobber: it computes what the branch changed
+ * relative to the state it forked from and writes only that. State on the
+ * target that the branch never touched survives, which is what makes promoting
+ * onto a live sandbox that moved on since the fork meaningful rather than
+ * destructive.
+ *
+ * The delta is the diff. {@link promoteFullState} calls {@link diffFullStates}
+ * and writes the records it returns, so "what the diff showed" and "what the
+ * promotion landed" are the same set by construction rather than by two
+ * comparisons agreeing. Each service reads the records tagged with its own
+ * name and turns them into that service's writes.
+ */
+
+import { getAuth, sandbox as authSandbox } from '../../auth/index.js';
+import { getOrCreateBackend } from '../../database/sandbox/backend-for.js';
+import type { JsonValue } from '../../database/sandbox/data-tree.js';
+import { deleteObject, ref, uploadBytes } from '../../storage/index.js';
+import {
+  base64ToBytes,
+  getAdminStorageSandbox,
+  replaceStorageRules,
+} from '../../storage/internal.js';
+import {
+  holdsBytesInline,
+  installsStorageRules,
+  type FullSandboxState,
+  type SandboxService,
+  type StorageObjectState,
+} from '../full-state.js';
+import { getInternalEnv } from '../internal/sandbox-impl.js';
+import { decodeStateDocument } from '../internal/state-values.js';
+import type { LocalSandbox } from '../types/service.js';
+import {
+  AUTH_PROVIDER_CONFIG_PATH,
+  DATABASE_PRIORITY_FIELD,
+  diffFullStates,
+  type BranchDivergence,
+} from './state-diff.js';
+
+/** The divergences one service reported, in the order the diff walked them. */
+function forService(
+  divergences: readonly BranchDivergence[],
+  service: SandboxService,
+): BranchDivergence[] {
+  return divergences.filter((divergence) => divergence.service === service);
+}
+
+/**
+ * The paths one service diverged at, each once. A field-level walk reports
+ * several records for one document, object, or account, and every service
+ * below writes whole values, so the paths are what it iterates.
+ */
+function divergedPaths(divergences: readonly BranchDivergence[]): string[] {
+  return [...new Set(divergences.map((divergence) => divergence.path))];
+}
+
+/** Land the documents the branch added, changed, or deleted. */
+function promoteFirestore(
+  target: LocalSandbox,
+  next: FullSandboxState,
+  divergences: readonly BranchDivergence[],
+): void {
+  for (const path of divergedPaths(divergences)) {
+    const document = next.firestore[path];
+    const wasDeleted = document === undefined;
+    if (wasDeleted) {
+      target.admin.deleteDocument(path);
+      continue;
+    }
+    target.admin.setDocument(path, decodeStateDocument(document, next.firestoreEncoding));
+  }
+}
+
+/** The priority one divergence lands, `null` where the branch carries none. */
+function priorityOf(after: unknown): string | number | null {
+  if (typeof after === 'string' || typeof after === 'number') return after;
+  return null;
+}
+
+/**
+ * Land the Realtime Database paths the branch changed, and their priorities.
+ *
+ * The diff already reports each change at the shallowest path that differs,
+ * which is exactly the granularity `adminSet` takes, so one record is one
+ * write.
+ */
+function promoteDatabase(target: LocalSandbox, divergences: readonly BranchDivergence[]): void {
+  const backend = getOrCreateBackend(target);
+  for (const divergence of divergences) {
+    if (divergence.field === DATABASE_PRIORITY_FIELD) {
+      backend.adminSetPriority(divergence.path, priorityOf(divergence.after));
+      continue;
+    }
+    backend.adminSet(divergence.path, structuredClone(divergence.after) as JsonValue);
+  }
+}
+
+/** The metadata one upload sets, assembled before the call rather than inside it. */
+function settableOf(object: StorageObjectState): {
+  contentType?: string;
+  customMetadata: Record<string, string>;
+} {
+  const settable: { contentType?: string; customMetadata: Record<string, string> } = {
+    customMetadata: { ...object.customMetadata },
+  };
+  if (object.contentType !== undefined) settable.contentType = object.contentType;
+  return settable;
+}
+
+/** Land the Storage objects the branch added, changed, or removed. */
+async function promoteStorage(
+  target: LocalSandbox,
+  next: FullSandboxState,
+  divergences: readonly BranchDivergence[],
+): Promise<void> {
+  const storage = getAdminStorageSandbox(target);
+  const objects = new Map(next.storage.map((object) => [object.path, object]));
+  for (const path of divergedPaths(divergences)) {
+    const object = objects.get(path);
+    if (object === undefined) {
+      await deleteObject(ref(storage, path));
+      continue;
+    }
+    // A branch is captured with its bytes inline; a reference names bytes only its own store holds.
+    const inline = holdsBytesInline(object);
+    if (!inline) throw new Error(`Storage object '${path}' in a branch carries no bytes to promote.`);
+    await uploadBytes(ref(storage, path), base64ToBytes(object.contentBase64), settableOf(object));
+  }
+}
+
+/** Land the accounts the branch added, changed, or deleted, and the provider config. */
+function promoteAuth(
+  target: LocalSandbox,
+  next: FullSandboxState,
+  divergences: readonly BranchDivergence[],
+): void {
+  const auth = getAuth(target);
+  const accounts = new Map(next.auth.users.map((user) => [user.uid, user]));
+  const changed: FullSandboxState['auth']['users'] = [];
+  let providersDiverged = false;
+  for (const path of divergedPaths(divergences)) {
+    if (path === AUTH_PROVIDER_CONFIG_PATH) {
+      providersDiverged = true;
+      continue;
+    }
+    const account = accounts.get(path);
+    if (account === undefined) {
+      authSandbox.deleteUser(auth, path);
+      continue;
+    }
+    changed.push(account);
+  }
+  if (changed.length > 0) authSandbox.seedUsers(auth, structuredClone(changed));
+  if (providersDiverged) authSandbox.restoreProviderConfig(auth, { ...next.auth.providers });
+}
+
+/**
+ * Land whichever of the three rule sources the branch changed. The diff names
+ * each source by its service, so one record is one installation.
+ *
+ * A branch that ran Storage without rules carries a null source, and
+ * {@link installsStorageRules} is the one place that says what that means: no
+ * change, because there is no source to install and no way to un-install one.
+ * The total replace in `applyFullState` reads the same predicate.
+ */
+async function promoteRules(
+  target: LocalSandbox,
+  next: FullSandboxState,
+  divergences: readonly BranchDivergence[],
+): Promise<void> {
+  for (const service of divergedPaths(divergences)) {
+    if (service === 'firestore') {
+      getInternalEnv(target).deployRules(next.rules.firestore);
+      continue;
+    }
+    if (service === 'database') {
+      getOrCreateBackend(target).setRules(structuredClone(next.rules.database));
+      continue;
+    }
+    if (!installsStorageRules(next.rules.storage)) continue;
+    await replaceStorageRules(target, next.rules.storage);
+  }
+}
+
+/**
+ * Write onto `target` everything that differs between the state a branch was
+ * forked from and the state it holds now.
+ *
+ * Not atomic on its own: a write that throws leaves the target part way
+ * through. The caller that owns the target's rollback is {@link promote} in
+ * `engine.ts`, which captures the target first and restores it on any throw.
+ */
+export async function promoteFullState(
+  target: LocalSandbox,
+  base: FullSandboxState,
+  next: FullSandboxState,
+): Promise<void> {
+  const divergences = diffFullStates(base, next);
+  promoteFirestore(target, next, forService(divergences, 'firestore'));
+  promoteDatabase(target, forService(divergences, 'database'));
+  promoteAuth(target, next, forService(divergences, 'auth'));
+  await promoteStorage(target, next, forService(divergences, 'storage'));
+  await promoteRules(target, next, forService(divergences, 'rules'));
+}