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

package/src/sandbox/branches/state-diff.ts

@@ -0,0 +1,333 @@
+/**
+ * The structural difference between two full sandbox states, service by
+ * service.
+ *
+ * One walk serves both readers. `diff` renders it as {@link BranchDivergence}
+ * records that name the service and the path or uid they concern, and
+ * `promote` applies the same records as writes. Keeping them on one walk is
+ * what makes "what the diff showed" and "what the promotion landed" the same
+ * set by construction rather than by two implementations agreeing.
+ *
+ * The divergence kinds are the replay engine's, unchanged. A branch carries no
+ * captured write metadata that could license sentinel or auto-id drift, so
+ * every difference here is a `real-divergence`, which is the honest
+ * classification for state against state.
+ */
+
+import type { JsonValue } from '../../database/sandbox/data-tree.js';
+import type {
+  AuthAccountsState,
+  FullSandboxState,
+  SandboxService,
+  StorageObjectState,
+} from '../full-state.js';
+import type { Divergence } from '../replay/index.js';
+import { decodeStateDocument } from '../internal/state-values.js';
+
+/**
+ * One divergence, tagged with the service whose state it concerns.
+ *
+ * Always a `real-divergence`. The replay engine's other kinds classify drift a
+ * captured write licenses, and a branch carries no such metadata, so state
+ * against state has only the one honest classification.
+ */
+export type BranchDivergence = Extract<Divergence, { kind: 'real-divergence' }> & {
+  service: SandboxService;
+};
+
+/**
+ * The path auth's provider configuration reports under, in place of a uid. The
+ * leading dot is the same convention {@link DATABASE_PRIORITY_FIELD} uses, and
+ * it keeps the entry outside the uid keyspace the rest of the auth records use.
+ */
+export const AUTH_PROVIDER_CONFIG_PATH = '.providers';
+
+/** The field a Realtime Database priority reports under, beside its path. */
+export const DATABASE_PRIORITY_FIELD = '.priority';
+
+/** One change to the Realtime Database tree, at the shallowest path that differs. */
+export interface TreeChange {
+  path: string;
+  before: JsonValue;
+  after: JsonValue;
+}
+
+/** Structural equality over plain JSON values. */
+export function jsonEqual(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 aIsArray = Array.isArray(a);
+  const bIsArray = Array.isArray(b);
+  if (aIsArray !== bIsArray) return false;
+  if (aIsArray && bIsArray) {
+    if (a.length !== b.length) return false;
+    for (let index = 0; index < a.length; index++) {
+      if (!jsonEqual(a[index], b[index])) return false;
+    }
+    return true;
+  }
+  const aObject = a as Record<string, unknown>;
+  const bObject = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObject);
+  if (aKeys.length !== Object.keys(bObject).length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(bObject, key)) return false;
+    if (!jsonEqual(aObject[key], bObject[key])) return false;
+  }
+  return true;
+}
+
+/** True when a JSON value is a plain object the walk should descend into. */
+function isBranchingNode(value: unknown): value is Record<string, JsonValue> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** The `data` subtree of a Realtime Database persistence envelope. */
+export function databaseTreeOf(state: FullSandboxState): JsonValue {
+  const envelope = state.database;
+  if (!isBranchingNode(envelope)) return envelope;
+  if (!('.pyricRtdbPersistence' in envelope)) return envelope;
+  const data = envelope.data;
+  if (data === undefined) return null;
+  return data;
+}
+
+/** The priorities map of a Realtime Database persistence envelope. */
+export function databasePrioritiesOf(state: FullSandboxState): Record<string, JsonValue> {
+  const envelope = state.database;
+  if (!isBranchingNode(envelope)) return {};
+  const priorities = envelope.priorities;
+  if (!isBranchingNode(priorities)) return {};
+  return priorities;
+}
+
+/**
+ * Every change between two Realtime Database trees, each at the shallowest
+ * path that differs. Two objects are walked key by key; anything else is one
+ * change at that path, which is exactly the granularity `adminSet` takes.
+ */
+export function diffTrees(before: JsonValue, after: JsonValue): TreeChange[] {
+  const changes: TreeChange[] = [];
+  walkTree(before, after, '', changes);
+  return changes;
+}
+
+function walkTree(before: JsonValue, after: JsonValue, path: string, out: TreeChange[]): void {
+  if (jsonEqual(before, after)) return;
+  const bothBranch = isBranchingNode(before) && isBranchingNode(after);
+  if (!bothBranch) {
+    out.push({ path: path === '' ? '/' : path, before, after });
+    return;
+  }
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of keys) {
+    const childPath = path === '' ? key : `${path}/${key}`;
+    walkTree(before[key] ?? null, after[key] ?? null, childPath, out);
+  }
+}
+
+/** One divergence record, built once so every service reports the same shape. */
+function divergenceAt(
+  service: SandboxService,
+  path: string,
+  field: string | undefined,
+  before: unknown,
+  after: unknown,
+): BranchDivergence {
+  if (field === undefined) {
+    return { kind: 'real-divergence', service, path, before, after };
+  }
+  return { kind: 'real-divergence', service, path, field, before, after };
+}
+
+/**
+ * Field-level walk over one document, producing dotted and bracketed leaf
+ * paths (`profile.lastSeen`, `tags[0]`), the same syntax the replay engine's
+ * own diff produces.
+ */
+function walkDocument(
+  service: SandboxService,
+  path: string,
+  before: unknown,
+  after: unknown,
+  out: BranchDivergence[],
+): void {
+  walk(before, after, '');
+
+  function walk(a: unknown, b: unknown, field: string): void {
+    if (jsonEqual(a, b)) return;
+    if (isBranchingNode(a) && isBranchingNode(b)) {
+      const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+      for (const key of keys) {
+        const next = field === '' ? key : `${field}.${key}`;
+        walk(a[key], b[key], next);
+      }
+      return;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+      const length = Math.max(a.length, b.length);
+      for (let index = 0; index < length; index++) {
+        walk(a[index], b[index], `${field}[${index}]`);
+      }
+      return;
+    }
+    let leafField: string | undefined = field;
+    if (field === '') leafField = undefined;
+    out.push(divergenceAt(service, path, leafField, a, b));
+  }
+}
+
+/** Compare user fields rather than the escaped representation stored on disk. */
+function documentForDiff(state: FullSandboxState, path: string): Record<string, unknown> | undefined {
+  const document = state.firestore[path];
+  const isMissing = document === undefined;
+  if (isMissing) return undefined;
+  return decodeStateDocument(document, state.firestoreEncoding);
+}
+
+/** Firestore documents, by full document path. */
+function diffFirestore(before: FullSandboxState, after: FullSandboxState): BranchDivergence[] {
+  const out: BranchDivergence[] = [];
+  const paths = new Set([...Object.keys(before.firestore), ...Object.keys(after.firestore)]);
+  for (const path of paths) {
+    const beforeDoc = documentForDiff(before, path);
+    const afterDoc = documentForDiff(after, path);
+    const oneSideMissing = beforeDoc === undefined || afterDoc === undefined;
+    if (oneSideMissing) {
+      const bothMissing = jsonEqual(beforeDoc ?? null, afterDoc ?? null);
+      if (bothMissing) continue;
+      out.push(divergenceAt('firestore', path, undefined, beforeDoc, afterDoc));
+      continue;
+    }
+    walkDocument('firestore', path, beforeDoc, afterDoc, out);
+  }
+  return out;
+}
+
+/** The Realtime Database tree and its priorities, by database path. */
+function diffDatabase(before: FullSandboxState, after: FullSandboxState): BranchDivergence[] {
+  const out: BranchDivergence[] = [];
+  for (const change of diffTrees(databaseTreeOf(before), databaseTreeOf(after))) {
+    out.push(divergenceAt('database', change.path, undefined, change.before, change.after));
+  }
+  const beforePriorities = databasePrioritiesOf(before);
+  const afterPriorities = databasePrioritiesOf(after);
+  const paths = new Set([...Object.keys(beforePriorities), ...Object.keys(afterPriorities)]);
+  for (const path of paths) {
+    if (jsonEqual(beforePriorities[path], afterPriorities[path])) continue;
+    out.push(
+      divergenceAt(
+        'database',
+        path,
+        DATABASE_PRIORITY_FIELD,
+        beforePriorities[path],
+        afterPriorities[path],
+      ),
+    );
+  }
+  return out;
+}
+
+/** Storage objects by path, one map so a missing object is a path-level difference. */
+function objectsByPath(
+  objects: readonly StorageObjectState[],
+): Map<string, StorageObjectState> {
+  return new Map(objects.map((object) => [object.path, object]));
+}
+
+/** Storage objects, by object path. Bytes, content type, and custom metadata. */
+function diffStorage(before: FullSandboxState, after: FullSandboxState): BranchDivergence[] {
+  const out: BranchDivergence[] = [];
+  const beforeObjects = objectsByPath(before.storage);
+  const afterObjects = objectsByPath(after.storage);
+  const paths = new Set([...beforeObjects.keys(), ...afterObjects.keys()]);
+  for (const path of [...paths].sort()) {
+    const beforeObject = beforeObjects.get(path);
+    const afterObject = afterObjects.get(path);
+    const oneSideMissing = beforeObject === undefined || afterObject === undefined;
+    if (oneSideMissing) {
+      out.push(divergenceAt('storage', path, undefined, beforeObject, afterObject));
+      continue;
+    }
+    walkDocument('storage', path, beforeObject, afterObject, out);
+  }
+  return out;
+}
+
+/** Auth accounts by uid, plus the provider configuration over them. */
+function diffAuth(before: AuthAccountsState, after: AuthAccountsState): BranchDivergence[] {
+  const out: BranchDivergence[] = [];
+  const beforeUsers = new Map(before.users.map((user) => [user.uid, user]));
+  const afterUsers = new Map(after.users.map((user) => [user.uid, user]));
+  const uids = new Set([...beforeUsers.keys(), ...afterUsers.keys()]);
+  for (const uid of [...uids].sort()) {
+    const beforeUser = beforeUsers.get(uid);
+    const afterUser = afterUsers.get(uid);
+    const oneSideMissing = beforeUser === undefined || afterUser === undefined;
+    if (oneSideMissing) {
+      out.push(divergenceAt('auth', uid, undefined, beforeUser, afterUser));
+      continue;
+    }
+    walkDocument('auth', uid, beforeUser, afterUser, out);
+  }
+  const providerIds = new Set([
+    ...Object.keys(before.providers),
+    ...Object.keys(after.providers),
+  ]);
+  for (const providerId of [...providerIds].sort()) {
+    if (before.providers[providerId] === after.providers[providerId]) continue;
+    out.push(
+      divergenceAt(
+        'auth',
+        AUTH_PROVIDER_CONFIG_PATH,
+        providerId,
+        before.providers[providerId],
+        after.providers[providerId],
+      ),
+    );
+  }
+  return out;
+}
+
+/** The three rule sources, each under its own service name as the path. */
+function diffRules(before: FullSandboxState, after: FullSandboxState): BranchDivergence[] {
+  const out: BranchDivergence[] = [];
+  if (before.rules.firestore !== after.rules.firestore) {
+    out.push(
+      divergenceAt('rules', 'firestore', undefined, before.rules.firestore, after.rules.firestore),
+    );
+  }
+  if (!jsonEqual(before.rules.database, after.rules.database)) {
+    out.push(
+      divergenceAt('rules', 'database', undefined, before.rules.database, after.rules.database),
+    );
+  }
+  if (before.rules.storage !== after.rules.storage) {
+    out.push(
+      divergenceAt('rules', 'storage', undefined, before.rules.storage, after.rules.storage),
+    );
+  }
+  return out;
+}
+
+/**
+ * Every difference between two full sandbox states, ordered service by service:
+ * Firestore, then the Realtime Database, then Storage, then auth, then rules.
+ *
+ * `before` is the reference and `after` is the state being described, so a
+ * record's `before` and `after` read the way a caller asking "what would
+ * landing this change do" expects.
+ */
+export function diffFullStates(
+  before: FullSandboxState,
+  after: FullSandboxState,
+): BranchDivergence[] {
+  return [
+    ...diffFirestore(before, after),
+    ...diffDatabase(before, after),
+    ...diffStorage(before, after),
+    ...diffAuth(before.auth, after.auth),
+    ...diffRules(before, after),
+  ];
+}

package/src/sandbox/branches/store.ts

@@ -0,0 +1,317 @@
+/**
+ * Persisted branches: the on-disk form of the in-memory branch primitive.
+ *
+ * THE FORMAT, stated once because the CLI and Studio both read it.
+ *
+ *   <project>/.pyric/state/branches/<name>/
+ *     manifest.json          { format, created, base, eventCount }
+ *     events.json            the applied event log, a JSON array of SandboxEvent
+ *     candidate-rules.json   the rule sources the fork installed in place of
+ *                            the base's, absent when the fork installed none
+ *     base/firestore.json    the forked base state, one file per service:
+ *     base/database.json       documents, the Realtime Database envelope,
+ *     base/storage.json        objects with base64 bytes and metadata,
+ *     base/auth.json           accounts and provider config, and the three
+ *     base/rules.json          rule sources
+ *     state/<service>.json   what the branch holds now, the same five files
+ *
+ * One file per service rather than one bundle, so a reader opening the
+ * directory sees which services a branch carries without decoding anything,
+ * and two changes to different services never rewrite the same file. The
+ * directory name is the branch name and is the join key, so the manifest does
+ * not repeat it: the directory is the index, exactly as the authored record
+ * convention states. `base` is `live` or the name of the checkpoint the fork
+ * was taken from.
+ *
+ * Why the branch carries two states rather than a base and a replayable log.
+ * The event log records Firestore writes, which is one of the five services a
+ * branch holds. A branch that had uploaded a Storage object or created an
+ * account could not be rebuilt from its base and its log, so the log is what
+ * was applied and `state/` is what the branch holds. `base/` stays because a
+ * promotion is a delta against it: state on the target the branch never
+ * touched has to survive landing, and only the base says which state that is.
+ *
+ * This module reads and writes files, so it is Node only and is published at
+ * the `pyric/sandbox/branches/store` subpath rather than from the browser
+ * barrel `pyric/sandbox`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DOC_VALUE_ENCODING } from '../../firestore/internal/value-codec.js';
+
+import {
+  SANDBOX_SERVICES,
+  captureFullState,
+  type FullSandboxState,
+  type SandboxService,
+} from '../full-state.js';
+import { wallClockState, type SandboxClockState } from '../clock.js';
+import type { SandboxEvent } from '../types/index.js';
+import { fork, type Branch, type BranchCandidateRules } from './engine.js';
+
+/** The tag every branch manifest carries, so an unrelated directory is not read as one. */
+export const BRANCH_FORMAT = 'pyric-branch-v2';
+
+/** Where branches live, relative to the project directory. */
+export const BRANCH_STORE_RELATIVE = join('.pyric', 'state', 'branches');
+
+const MANIFEST_FILE = 'manifest.json';
+const EVENTS_FILE = 'events.json';
+const CANDIDATE_RULES_FILE = 'candidate-rules.json';
+const CLOCK_FILE = 'clock.json';
+const FIRESTORE_ENCODING_FILE = 'firestore-encoding.json';
+const BASE_DIRECTORY = 'base';
+const STATE_DIRECTORY = 'state';
+
+/** The names a branch may take: one path segment, so a name can never escape the store. */
+export const BRANCH_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** A branch name the store refuses. Thrown rather than returned: it is a caller mistake. */
+export class BranchNameError extends Error {
+  constructor(name: string) {
+    super(
+      `'${name}' is not a branch name. A branch name is 1 to 64 characters of lowercase letters, digits, dot, dash, or underscore, starting with a letter or digit.`,
+    );
+    this.name = 'BranchNameError';
+  }
+}
+
+/** The manifest a branch directory carries, without the name its directory already states. */
+export interface BranchManifest {
+  format: typeof BRANCH_FORMAT;
+  /** When the branch was forked, as an ISO 8601 instant. */
+  created: string;
+  /** `live`, or the name of the checkpoint the fork was taken from. */
+  base: string;
+  /** How many events have been applied to the branch. */
+  eventCount: number;
+}
+
+/** One entry of a branch listing: the manifest plus the name the directory carries. */
+export interface BranchListing extends BranchManifest {
+  name: string;
+}
+
+/** A loaded branch: the rebuilt in-memory branch plus what the manifest recorded. */
+export interface LoadedBranch {
+  name: string;
+  branch: Branch;
+  manifest: BranchManifest;
+}
+
+/** What a save records beyond the branch itself. */
+export interface SaveBranchOptions {
+  /** `live`, or the name of the checkpoint the fork was taken from. */
+  base: string;
+  /** The creation instant to record. Defaults to now, which is what a fork wants. */
+  created?: string;
+}
+
+/** Reject a name that is not one path segment of the branch store. */
+function assertBranchName(name: string): void {
+  if (!BRANCH_NAME_PATTERN.test(name)) throw new BranchNameError(name);
+}
+
+/** The directory one branch occupies. */
+export function branchDirectory(projectDir: string, name: string): string {
+  assertBranchName(name);
+  return join(projectDir, BRANCH_STORE_RELATIVE, name);
+}
+
+/** The file one service's slice of a stored state occupies. */
+function stateServicePath(dir: string, stateDir: string, service: SandboxService): string {
+  return join(dir, stateDir, `${service}.json`);
+}
+
+/** Write one full state as one file per service. */
+function writeState(dir: string, stateDir: string, state: FullSandboxState): void {
+  mkdirSync(join(dir, stateDir), { recursive: true });
+  for (const service of SANDBOX_SERVICES) {
+    writeFileSync(
+      stateServicePath(dir, stateDir, service),
+      `${JSON.stringify(state[service])}\n`,
+      'utf8',
+    );
+  }
+  // The clock is not a service, so it gets its own file beside them rather than
+  // a place in the service list the diff walks. A branch reloaded from disk
+  // reaches the same `request.time` verdict the branch reached in memory.
+  writeFileSync(
+    join(dir, stateDir, CLOCK_FILE),
+    `${JSON.stringify(state.clock ?? wallClockState())}\n`,
+    'utf8',
+  );
+  writeFileSync(join(dir, stateDir, FIRESTORE_ENCODING_FILE), `${JSON.stringify(state.firestoreEncoding ?? null)}\n`, 'utf8');
+}
+
+/** Older branch directories contain unencoded maps and have no encoding file. */
+function readFirestoreEncoding(dir: string, stateDir: string): FullSandboxState['firestoreEncoding'] {
+  const path = join(dir, stateDir, FIRESTORE_ENCODING_FILE);
+  const hasNoEncoding = !existsSync(path);
+  if (hasNoEncoding) return undefined;
+  const encoding: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  const isLegacyState = encoding === null;
+  if (isLegacyState) return undefined;
+  const isSupported = encoding === DOC_VALUE_ENCODING;
+  if (isSupported) return encoding;
+  throw new Error('Unsupported Firestore value encoding in branch state.');
+}
+
+/** Read one service's slice back, or null when the branch directory has no such file. */
+function readSandboxService(dir: string, stateDir: string, service: SandboxService): unknown {
+  const path = stateServicePath(dir, stateDir, service);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** The clock one state directory carries, or the wall clock when it has none. */
+function readClock(dir: string, stateDir: string): SandboxClockState {
+  const path = join(dir, stateDir, CLOCK_FILE);
+  if (!existsSync(path)) return wallClockState();
+  return JSON.parse(readFileSync(path, 'utf8')) as SandboxClockState;
+}
+
+/** One full state a branch directory carries, under `base/` or under `state/`. */
+function readState(dir: string, stateDir: string): FullSandboxState {
+  return {
+    clock: readClock(dir, stateDir),
+    firestoreEncoding: readFirestoreEncoding(dir, stateDir),
+    firestore: (readSandboxService(dir, stateDir, 'firestore') ?? {}) as FullSandboxState['firestore'],
+    database: readSandboxService(dir, stateDir, 'database') as FullSandboxState['database'],
+    storage: (readSandboxService(dir, stateDir, 'storage') ?? []) as FullSandboxState['storage'],
+    auth: (readSandboxService(dir, stateDir, 'auth') ?? {
+      users: [],
+      providers: {},
+    }) as FullSandboxState['auth'],
+    rules: (readSandboxService(dir, stateDir, 'rules') ?? {
+      firestore: '',
+      database: null,
+      storage: null,
+    }) as FullSandboxState['rules'],
+  };
+}
+
+/**
+ * Write one branch to its own directory, replacing whatever was there. The
+ * base, the current state, and the event log are all written from the branch
+ * itself, so a save after an `apply` or after a write on any service records
+ * exactly what the engine holds.
+ */
+export async function saveBranch(
+  projectDir: string,
+  name: string,
+  branch: Branch,
+  options: SaveBranchOptions,
+): Promise<BranchManifest> {
+  const dir = branchDirectory(projectDir, name);
+  const manifest: BranchManifest = {
+    format: BRANCH_FORMAT,
+    created: options.created ?? new Date().toISOString(),
+    base: options.base,
+    eventCount: branch.events.length,
+  };
+  const current = await captureFullState(branch.sandbox);
+  mkdirSync(dir, { recursive: true });
+  writeState(dir, BASE_DIRECTORY, branch.base);
+  writeState(dir, STATE_DIRECTORY, current);
+  writeFileSync(join(dir, EVENTS_FILE), `${JSON.stringify(branch.events)}\n`, 'utf8');
+  const candidateRulesPath = join(dir, CANDIDATE_RULES_FILE);
+  const hasCandidateRules = Object.keys(branch.candidateRules).length > 0;
+  if (hasCandidateRules) {
+    writeFileSync(candidateRulesPath, `${JSON.stringify(branch.candidateRules)}\n`, 'utf8');
+  } else {
+    rmSync(candidateRulesPath, { force: true });
+  }
+  writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  return manifest;
+}
+
+/** The manifest one directory holds, or null when it holds none this store wrote. */
+function readManifest(dir: string): BranchManifest | null {
+  const path = join(dir, MANIFEST_FILE);
+  if (!existsSync(path)) return null;
+  let parsed: Partial<BranchManifest>;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<BranchManifest>;
+  } catch {
+    return null;
+  }
+  if (parsed.format !== BRANCH_FORMAT) return null;
+  if (typeof parsed.created !== 'string') return null;
+  if (typeof parsed.base !== 'string') return null;
+  if (typeof parsed.eventCount !== 'number') return null;
+  return {
+    format: BRANCH_FORMAT,
+    created: parsed.created,
+    base: parsed.base,
+    eventCount: parsed.eventCount,
+  };
+}
+
+/** The candidate rules one branch directory carries, empty when it carries none. */
+function readCandidateRules(dir: string): BranchCandidateRules {
+  const path = join(dir, CANDIDATE_RULES_FILE);
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, 'utf8')) as BranchCandidateRules;
+}
+
+/** The event log one branch directory carries. */
+function readEvents(dir: string): SandboxEvent[] {
+  const path = join(dir, EVENTS_FILE);
+  if (!existsSync(path)) return [];
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  if (!Array.isArray(parsed)) return [];
+  return parsed as SandboxEvent[];
+}
+
+/**
+ * Rebuild one branch from its directory, or null when the project has no
+ * branch by that name. The branch's sandbox is forked onto the stored current
+ * state, and the stored base and event log are restored beside it, so a loaded
+ * branch and a branch that never left memory are the same value in every
+ * service rather than only in the one the event log records.
+ */
+export async function loadBranch(
+  projectDir: string,
+  name: string,
+): Promise<LoadedBranch | null> {
+  const dir = branchDirectory(projectDir, name);
+  const manifest = readManifest(dir);
+  if (manifest === null) return null;
+  const forked = await fork(readState(dir, STATE_DIRECTORY), readCandidateRules(dir));
+  const branch: Branch = {
+    sandbox: forked.sandbox,
+    candidateRules: forked.candidateRules,
+    base: readState(dir, BASE_DIRECTORY),
+    events: readEvents(dir),
+    discarded: false,
+  };
+  return { name, branch, manifest };
+}
+
+/**
+ * Every branch the project holds, ordered by name. A directory that carries no
+ * manifest this store wrote is skipped rather than failing the listing, so an
+ * unrelated file under the branch directory does not take the listing down.
+ */
+export function listBranches(projectDir: string): BranchListing[] {
+  const root = join(projectDir, BRANCH_STORE_RELATIVE);
+  if (!existsSync(root)) return [];
+  const listed: BranchListing[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!BRANCH_NAME_PATTERN.test(entry.name)) continue;
+    const manifest = readManifest(join(root, entry.name));
+    if (manifest === null) continue;
+    listed.push({ name: entry.name, ...manifest });
+  }
+  return listed.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Remove one branch directory. Returns whether there was one to remove. */
+export function removeBranch(projectDir: string, name: string): boolean {
+  const dir = branchDirectory(projectDir, name);
+  if (!existsSync(dir)) return false;
+  rmSync(dir, { recursive: true, force: true });
+  return true;
+}