canopycms 0.0.67-int.90 → 0.0.67

package/dist/branch-metadata.d.ts

@@ -1,7 +1,8 @@
 import type { BranchContext, BranchMetadata } from './types.js';
-import { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, type BranchMetadataFile } from './branch-metadata-file.js';
+import { BranchMetadataCorruptError, type BranchMetadataFile } from './branch-metadata-file.js';
 import { type OperatingMode } from './operating-mode/index.js';
-export { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, type BranchMetadataFile, };
+export { BranchMetadataCorruptError, type BranchMetadataFile };
+/** @internal Exported for tests. */
 export declare class BranchMetadataConflictError extends Error {
     constructor(message?: string);
 }
@@ -9,28 +10,17 @@ export declare class BranchMetadataConflictError extends Error {
  * Manages branch.json — branch status and access ACLs, both security-adjacent
  * state — under `.canopy-meta/` in a branch workspace.
  *
- * save() is protected by three layers, outermost to innermost (identical
- * structure to {@link CommentStore}'s withMutation, see comment-store.ts):
+ * save() runs under the same three-layer stack as {@link CommentStore}'s
+ * withMutation — see comment-store.ts, and `utils/occ-json-write.ts` for the
+ * guarantees of layers 2-3.
  *
- * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
- *    path. Serializes concurrent mutators on the SAME process/host
- *    deterministically.
- * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
- *    lock (proper-lockfile, mkdir-based). This is the actual fix for lost
- *    branch-status/ACL updates across two warm Lambda containers (or a
- *    Lambda + the EC2 worker) on EFS: rename-based OCC verification alone
- *    relies on a read-back that can be served from the writer's own local
- *    NFS dentry/attribute cache, so a foreign writer's rename can stay
- *    invisible for that cache's window (commonly 3-60s) and both writers
- *    conclude they won. A settle delay does not help — the cache window
- *    dwarfs any sleep worth paying — only server-enforced mutual exclusion
- *    does. Given branch.json carries status + ACLs, silently losing an
- *    update here is a correctness/security issue, not just a UX glitch.
- * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
- *    based optimistic concurrency control. With layers 1-2 in place this is
- *    now a defense-in-depth backstop only, not the primary safety mechanism.
- *
- * See `utils/occ-json-write.ts` for full guarantee documentation of layers 2-3.
+ * Layer 2's server-enforced lock is the load-bearing one here. Rename-based OCC
+ * alone verifies by a read-back that can come from the writer's own NFS
+ * attribute cache, so for that cache's window (docs/concurrency.md) a foreign
+ * writer's rename stays invisible and both writers conclude they won; no settle
+ * delay closes it, since the window dwarfs any sleep worth paying. And because
+ * branch.json carries status and ACLs, a silently lost update is a
+ * correctness/security issue, not a UX glitch.
  */
 export declare class BranchMetadataFileManager {
     private readonly branchRoot;
@@ -38,94 +28,73 @@ export declare class BranchMetadataFileManager {
     private readonly baseRoot;
     private readonly settleMs;
     private constructor();
-    /**
-     * Load branch metadata without requiring baseRoot.
-     * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
-     */
+    /** Read-only load, needing no baseRoot: registry scanning, loadBranchContext. */
     static loadOnly(branchRoot: string): Promise<BranchMetadataFile | null>;
     /**
-     * Get a BranchMetadataFileManager instance configured for registry invalidation.
-     * Use this in API handlers to ensure registry cache is invalidated on updates.
+     * An instance wired for registry invalidation. API handlers use this, so the
+     * registry cache is invalidated on update.
      */
     static get(branchRoot: string, baseRoot: string, options?: {
         settleMs?: number;
     }): BranchMetadataFileManager;
     private load;
     /**
-     * Write branch.json via the shared OCC helper, with the schemaVersion
-     * default applied here (payload shaping stays branch-metadata's concern).
+     * Write branch.json via the shared OCC helper, applying the schemaVersion
+     * default here since payload shaping is branch-metadata's concern.
      *
-     * Throws the helper's raw {@link OccWriteConflictError} so the surrounding
-     * {@link withOccRetry} in save() recognizes and retries it; translation to
-     * the public `BranchMetadataConflictError` contract happens at the save()
-     * boundary, after retries are exhausted (translating earlier would make
-     * withOccRetry's default predicate miss it, since it only recognizes the
-     * raw error type).
+     * Throws the helper's raw {@link OccWriteConflictError}, which is what the
+     * surrounding {@link withOccRetry} in save() recognizes and retries;
+     * translating to the public `BranchMetadataConflictError` earlier than the
+     * save() boundary would make withOccRetry's predicate miss it.
      *
-     * branch-metadata historically writes WITH a trailing newline, unlike
-     * comment-store; `trailingNewline: true` preserves that.
+     * branch.json is written WITH a trailing newline (`trailingNewline: true`),
+     * unlike comments.json.
      */
     private write;
     /**
-     * Run a save cycle under the full lock + OCC-retry stack described in the
-     * class doc comment. A conflict that survives every retry surfaces as the
-     * public `BranchMetadataConflictError`.
+     * Run a save cycle under the full lock + OCC-retry stack (class doc). A
+     * conflict surviving every retry surfaces as `BranchMetadataConflictError`.
      *
-     * Guards against a phantom-resurrection race with branch deletion: a
-     * caller's branchContext can be resolved BEFORE a concurrent
-     * deleteBranchHandler removes the branch directory, but this save() call
-     * only reaches here (and its own mkdir({recursive:true}) inside write())
-     * AFTER the removal. Without this check, that mkdir would silently
-     * recreate `.canopy-meta/` (and this save would recreate branch.json from
-     * defaults) inside a directory tree that no longer exists anywhere else --
-     * a registry entry with no clone behind it. Checking BEFORE the lock stack
-     * (rather than after) fails fast without paying for a lock acquisition on
-     * a doomed save.
+     * The stat guards a phantom-resurrection race with branch deletion: a
+     * caller's branchContext can resolve BEFORE a concurrent deleteBranchHandler
+     * removes the branch directory, while the save reaches here after it, and
+     * write()'s `mkdir({recursive:true})` would then recreate `.canopy-meta/` and
+     * branch.json from defaults inside a tree nothing else refers to — a registry
+     * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
+     * save fails fast instead of paying for a lock.
      *
-     * Residual window (accepted): a save that passes this check can still
-     * race a `rm` that starts moments later and is still mid-flight when this
-     * save's write lands, resurrecting the tree. Closing that fully would
-     * need a tombstone OUTSIDE the tree being removed -- the lockfile
-     * (`withOccFileLock`) this save takes next lives INSIDE `branchRoot`, so
-     * it cannot itself provide a wider guarantee than "the directory existed
-     * a moment ago."
+     * Accepted residual window: a save that passes the check can still race a
+     * `rm` that starts moments later and is mid-flight when the write lands.
+     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
+     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
+     * than "the directory existed a moment ago".
      */
     save(incoming: BranchMetadataUpdate): Promise<BranchMetadataFile>;
-    /**
-     * Invalidates the registry cache so next list() call regenerates from branch.json files.
-     */
+    /** Invalidate the registry cache so the next list() regenerates. */
     private invalidateRegistry;
 }
 /**
- * Fields that can be set via save().
- * - createdBy: Only used on initial creation; ignored if metadata already exists
- * - createdAt/updatedAt: Managed automatically
+ * Fields save() accepts. `createdBy` applies on creation only and is ignored
+ * once metadata exists; createdAt/updatedAt are managed here, not by callers.
  */
 export interface BranchMetadataUpdate {
     branch?: Partial<Omit<BranchMetadata, 'createdAt' | 'updatedAt'>>;
 }
 /**
- * Build the metadata update for archiving a branch because its PR merged.
- * Shared by the worker's merge-poll (CmsWorker.pollMergeState) and the
- * manual markAsMerged API (api/branch-merge.ts) so both paths produce
- * identical archived-branch metadata.
+ * The metadata update for archiving a branch whose PR merged. Shared by the
+ * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
+ * API (api/branch-merge.ts), so both produce identical metadata.
  *
- * Deliberately omits pullRequestNumber/pullRequestUrl: save()'s merge keeps
- * whatever the existing metadata already has for fields not present in the
- * incoming update, so the PR number/URL recorded earlier survive untouched.
+ * Deliberately omits pullRequestNumber/pullRequestUrl: save() keeps existing
+ * values for fields the incoming update omits, so the recorded PR number and
+ * URL survive untouched.
  */
 export declare function buildMergedBranchUpdate(branchName: string, now?: Date): NonNullable<BranchMetadataUpdate['branch']>;
-/**
- * Get a BranchMetadataFileManager instance configured for registry invalidation.
- * Use this in API handlers to ensure registry cache is invalidated on updates.
- */
+/** {@link BranchMetadataFileManager.get} as a function. */
 export declare const getBranchMetadataFileManager: (branchRoot: string, baseRoot: string, options?: {
     settleMs?: number;
 }) => BranchMetadataFileManager;
-/**
- * Load branch context from metadata file (source of truth).
- * Returns null if the branch doesn't exist.
- */
+/** Branch context from the metadata file, the source of truth. Null if absent. */
 export declare const loadBranchContext: (options: {
     branchName: string;
     mode: OperatingMode;

package/dist/branch-metadata.js

@@ -6,11 +6,12 @@ import { resolveBranchPath } from './paths/index.js';
 import { isNotFoundError } from './utils/error.js';
 import { withLock } from './utils/async-mutex.js';
 import { writeOccJsonFile, withOccRetry, withOccFileLock, OccWriteConflictError, } from './utils/occ-json-write.js';
-// The file format itself lives in the leaf so branch-registry.ts can read
-// branch.json without importing this module (which imports it back). Re-exported
-// here so the existing importers of these names do not have to move.
-export { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, };
+// The file format lives in the leaf so branch-registry.ts can read branch.json
+// without importing this module, which imports it back. Re-exported here so
+// importers of these names do not have to move.
+export { BranchMetadataCorruptError };
 const CURRENT_SCHEMA_VERSION = 1;
+/** @internal Exported for tests. */
 export class BranchMetadataConflictError extends Error {
     constructor(message = 'Concurrent modification detected in branch metadata') {
         super(message);
@@ -21,28 +22,17 @@ export class BranchMetadataConflictError extends Error {
  * Manages branch.json — branch status and access ACLs, both security-adjacent
  * state — under `.canopy-meta/` in a branch workspace.
  *
- * save() is protected by three layers, outermost to innermost (identical
- * structure to {@link CommentStore}'s withMutation, see comment-store.ts):
+ * save() runs under the same three-layer stack as {@link CommentStore}'s
+ * withMutation — see comment-store.ts, and `utils/occ-json-write.ts` for the
+ * guarantees of layers 2-3.
  *
- * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
- *    path. Serializes concurrent mutators on the SAME process/host
- *    deterministically.
- * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
- *    lock (proper-lockfile, mkdir-based). This is the actual fix for lost
- *    branch-status/ACL updates across two warm Lambda containers (or a
- *    Lambda + the EC2 worker) on EFS: rename-based OCC verification alone
- *    relies on a read-back that can be served from the writer's own local
- *    NFS dentry/attribute cache, so a foreign writer's rename can stay
- *    invisible for that cache's window (commonly 3-60s) and both writers
- *    conclude they won. A settle delay does not help — the cache window
- *    dwarfs any sleep worth paying — only server-enforced mutual exclusion
- *    does. Given branch.json carries status + ACLs, silently losing an
- *    update here is a correctness/security issue, not just a UX glitch.
- * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
- *    based optimistic concurrency control. With layers 1-2 in place this is
- *    now a defense-in-depth backstop only, not the primary safety mechanism.
- *
- * See `utils/occ-json-write.ts` for full guarantee documentation of layers 2-3.
+ * Layer 2's server-enforced lock is the load-bearing one here. Rename-based OCC
+ * alone verifies by a read-back that can come from the writer's own NFS
+ * attribute cache, so for that cache's window (docs/concurrency.md) a foreign
+ * writer's rename stays invisible and both writers conclude they won; no settle
+ * delay closes it, since the window dwarfs any sleep worth paying. And because
+ * branch.json carries status and ACLs, a silently lost update is a
+ * correctness/security issue, not a UX glitch.
  */
 export class BranchMetadataFileManager {
     constructor(branchRoot, baseRoot, options) {
@@ -51,16 +41,13 @@ export class BranchMetadataFileManager {
         this.baseRoot = baseRoot;
         this.settleMs = options?.settleMs;
     }
-    /**
-     * Load branch metadata without requiring baseRoot.
-     * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
-     */
+    /** Read-only load, needing no baseRoot: registry scanning, loadBranchContext. */
     static async loadOnly(branchRoot) {
         return readBranchMetadataFile(branchRoot);
     }
     /**
-     * Get a BranchMetadataFileManager instance configured for registry invalidation.
-     * Use this in API handlers to ensure registry cache is invalidated on updates.
+     * An instance wired for registry invalidation. API handlers use this, so the
+     * registry cache is invalidated on update.
      */
     static get(branchRoot, baseRoot, options) {
         return new BranchMetadataFileManager(branchRoot, baseRoot, options);
@@ -80,18 +67,16 @@ export class BranchMetadataFileManager {
         }
     }
     /**
-     * Write branch.json via the shared OCC helper, with the schemaVersion
-     * default applied here (payload shaping stays branch-metadata's concern).
+     * Write branch.json via the shared OCC helper, applying the schemaVersion
+     * default here since payload shaping is branch-metadata's concern.
      *
-     * Throws the helper's raw {@link OccWriteConflictError} so the surrounding
-     * {@link withOccRetry} in save() recognizes and retries it; translation to
-     * the public `BranchMetadataConflictError` contract happens at the save()
-     * boundary, after retries are exhausted (translating earlier would make
-     * withOccRetry's default predicate miss it, since it only recognizes the
-     * raw error type).
+     * Throws the helper's raw {@link OccWriteConflictError}, which is what the
+     * surrounding {@link withOccRetry} in save() recognizes and retries;
+     * translating to the public `BranchMetadataConflictError` earlier than the
+     * save() boundary would make withOccRetry's predicate miss it.
      *
-     * branch-metadata historically writes WITH a trailing newline, unlike
-     * comment-store; `trailingNewline: true` preserves that.
+     * branch.json is written WITH a trailing newline (`trailingNewline: true`),
+     * unlike comments.json.
      */
     async write(meta, expectedVersion) {
         const payload = {
@@ -105,28 +90,22 @@ export class BranchMetadataFileManager {
         });
     }
     /**
-     * Run a save cycle under the full lock + OCC-retry stack described in the
-     * class doc comment. A conflict that survives every retry surfaces as the
-     * public `BranchMetadataConflictError`.
+     * Run a save cycle under the full lock + OCC-retry stack (class doc). A
+     * conflict surviving every retry surfaces as `BranchMetadataConflictError`.
      *
-     * Guards against a phantom-resurrection race with branch deletion: a
-     * caller's branchContext can be resolved BEFORE a concurrent
-     * deleteBranchHandler removes the branch directory, but this save() call
-     * only reaches here (and its own mkdir({recursive:true}) inside write())
-     * AFTER the removal. Without this check, that mkdir would silently
-     * recreate `.canopy-meta/` (and this save would recreate branch.json from
-     * defaults) inside a directory tree that no longer exists anywhere else --
-     * a registry entry with no clone behind it. Checking BEFORE the lock stack
-     * (rather than after) fails fast without paying for a lock acquisition on
-     * a doomed save.
+     * The stat guards a phantom-resurrection race with branch deletion: a
+     * caller's branchContext can resolve BEFORE a concurrent deleteBranchHandler
+     * removes the branch directory, while the save reaches here after it, and
+     * write()'s `mkdir({recursive:true})` would then recreate `.canopy-meta/` and
+     * branch.json from defaults inside a tree nothing else refers to — a registry
+     * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
+     * save fails fast instead of paying for a lock.
      *
-     * Residual window (accepted): a save that passes this check can still
-     * race a `rm` that starts moments later and is still mid-flight when this
-     * save's write lands, resurrecting the tree. Closing that fully would
-     * need a tombstone OUTSIDE the tree being removed -- the lockfile
-     * (`withOccFileLock`) this save takes next lives INSIDE `branchRoot`, so
-     * it cannot itself provide a wider guarantee than "the directory existed
-     * a moment ago."
+     * Accepted residual window: a save that passes the check can still race a
+     * `rm` that starts moments later and is mid-flight when the write lands.
+     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
+     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
+     * than "the directory existed a moment ago".
      */
     async save(incoming) {
         try {
@@ -167,9 +146,9 @@ export class BranchMetadataFileManager {
                         createdAt: existing?.branch.createdAt ?? defaults.createdAt,
                         // Fork point is recorded once at creation; later saves must not move it
                         baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
-                        // Always stamped fresh — the spreads above would otherwise let
-                        // the existing (creation-time) value win forever, freezing the
-                        // timestamp the editor's Branches panel sorts and displays by
+                        // Always stamped fresh; the spreads above would otherwise let
+                        // the creation-time value win forever, freezing the timestamp
+                        // the editor's Branches panel sorts and displays by
                         updatedAt: now,
                     },
                 };
@@ -185,31 +164,28 @@ export class BranchMetadataFileManager {
             }
             throw err;
         }
-        // Registry invalidation AFTER releasing the lockfile: the protocol only
-        // requires the bump to land strictly after the branch.json write (it
-        // does), and the registry's eager regeneration is O(branch count) fs
-        // reads on EFS — holding the server-enforced lock through it would
-        // extend every save's critical section for no correctness gain.
+        // Registry invalidation AFTER releasing the lockfile. The protocol only
+        // requires the bump to land strictly after the branch.json write, which it
+        // does, and the registry's eager regeneration is O(branch count) fs reads
+        // on EFS — holding the lock through it would stretch every save's critical
+        // section for no correctness gain.
         await this.invalidateRegistry();
         return saved;
     }
-    /**
-     * Invalidates the registry cache so next list() call regenerates from branch.json files.
-     */
+    /** Invalidate the registry cache so the next list() regenerates. */
     async invalidateRegistry() {
         const registry = new BranchRegistry(this.baseRoot);
         await registry.invalidate();
     }
 }
 /**
- * Build the metadata update for archiving a branch because its PR merged.
- * Shared by the worker's merge-poll (CmsWorker.pollMergeState) and the
- * manual markAsMerged API (api/branch-merge.ts) so both paths produce
- * identical archived-branch metadata.
+ * The metadata update for archiving a branch whose PR merged. Shared by the
+ * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
+ * API (api/branch-merge.ts), so both produce identical metadata.
  *
- * Deliberately omits pullRequestNumber/pullRequestUrl: save()'s merge keeps
- * whatever the existing metadata already has for fields not present in the
- * incoming update, so the PR number/URL recorded earlier survive untouched.
+ * Deliberately omits pullRequestNumber/pullRequestUrl: save() keeps existing
+ * values for fields the incoming update omits, so the recorded PR number and
+ * URL survive untouched.
  */
 export function buildMergedBranchUpdate(branchName, now = new Date()) {
     return {
@@ -219,17 +195,11 @@ export function buildMergedBranchUpdate(branchName, now = new Date()) {
         mergedAt: now.toISOString(),
     };
 }
-/**
- * Get a BranchMetadataFileManager instance configured for registry invalidation.
- * Use this in API handlers to ensure registry cache is invalidated on updates.
- */
+/** {@link BranchMetadataFileManager.get} as a function. */
 export const getBranchMetadataFileManager = (branchRoot, baseRoot, options) => {
     return BranchMetadataFileManager.get(branchRoot, baseRoot, options);
 };
-/**
- * Load branch context from metadata file (source of truth).
- * Returns null if the branch doesn't exist.
- */
+/** Branch context from the metadata file, the source of truth. Null if absent. */
 export const loadBranchContext = async (options) => {
     const { branchRoot, baseRoot } = resolveBranchPath({
         branchName: options.branchName,

package/dist/branch-registry.d.ts

@@ -1,59 +1,28 @@
 import type { BranchContext } from './types.js';
+/** @internal Exported for tests. */
 export interface BranchRegistrySnapshot {
     version: number;
     branches: BranchContext[];
     /**
-     * The resource-generation.ts marker token this snapshot was built against, or
-     * null if it was built before any bump ever occurred on this root. Compared
-     * against the live marker (via isGenerationCurrent) to decide freshness.
+     * The marker token this snapshot was built against, or null when it was built
+     * before any bump on this root. Compared against the live marker (via
+     * isGenerationCurrent) to decide freshness.
      */
     generation: string | null;
 }
 /**
- * BranchRegistry is a read-only cache for fast branch listing.
- * Individual branch.json files are the source of truth.
+ * A read-only `branches.json` cache for fast branch listing; the individual
+ * branch.json files are the source of truth.
  *
- * ## Cross-process freshness (resource-generation.ts marker protocol)
+ * Freshness follows the generation-marker protocol owned by
+ * resource-generation.ts. This is that protocol's durable-snapshot consumer, so
+ * it carries both mitigations: invalidate() eager-regenerates on the mutating
+ * host right after its own bump, and get() has a throttled suspicious-miss
+ * backstop bounding how long a bad snapshot can hide a real branch.
  *
- * Several warm Lambda containers plus the EC2 worker can share one branch-clone
- * root over EFS, each with its own in-process cache of `branches.json`. There is
- * no shared memory and no cross-host file watching, so freshness is coordinated
- * via the generic on-disk generation marker in resource-generation.ts: every
- * snapshot embeds the marker token it was built against, and every read
- * cheaply re-checks the live marker before trusting the cached snapshot. See
- * that module's doc comment for the full protocol and residual staleness
- * windows (A/B/C/E).
- *
- * BranchRegistry is exactly the "durable snapshot consumer" case called out
- * there: a regeneration whose scan is served from stale NFS dentry/attribute
- * caches can record a FRESH token over STALE data (window E), and because the
- * result is written to `branches.json`, that staleness becomes durable and
- * shared with every other host that reads the marker - not just one process's
- * memory. Two mitigations close the practical gap:
- *
- * - invalidate() eager-regenerates immediately after its own bump. The
- *   mutating host's own scan is necessarily coherent with the mutation it just
- *   made (no NFS round trip was needed to observe its own write), so this
- *   closes window (E) for the common case without waiting for some other host
- *   to lazily pull the change.
- * - get() implements a suspicious-miss backstop: a branch that "should" exist
- *   but is absent from the cached snapshot forces one fresh regeneration
- *   (throttled), bounding how long a bad snapshot can hide a real branch.
- *
- * regenerate() also skips persisting a snapshot when the marker read itself
- * fails (`{ ok: false }`, e.g. unreadable for a non-ENOENT reason): a snapshot
- * embedding a token we cannot attribute to "matches this scan" would be
- * indistinguishable from a correctly-attributed one to every future reader, so
- * the safer behavior is to serve the fresh scan without writing it durably and
- * let the next read retry the marker.
- *
- * Design:
- * - list() returns the cached snapshot if its embedded generation token still
- *   matches the live marker, regenerates from branch.json files otherwise
- * - invalidate() bumps the marker (durable, cross-process) and eager-regenerates
- * - Concurrent regeneration within one process is deduped to a single scan
- *   (regenInFlight); across processes, regeneration is still safe since all
- *   processes produce identical output from the same branch.json files
+ * Concurrent regeneration within one process is deduped to a single scan
+ * (regenInFlight); across processes it needs no coordination, since every
+ * process produces identical output from the same branch.json files.
  */
 export declare class BranchRegistry {
     private readonly root;
@@ -71,35 +40,28 @@ export declare class BranchRegistry {
      */
     list(): Promise<BranchContext[]>;
     /**
-     * Returns a single branch by name. Uses cache if available.
+     * Returns a single branch by name, from the cached snapshot when it is fresh.
      *
-     * Suspicious-miss backstop: if `name` isn't in the (possibly cached) list,
-     * that's a signal the snapshot may be stale in the specific direction where
-     * a branch that now exists is missing from it - force one fresh
-     * regeneration and re-search before giving up, throttled per instance so a
-     * genuinely-absent branch costs at most one extra scan per throttle window.
-     * This bounds durable window-E staleness for the "branch exists but
-     * snapshot predates it" direction; see the class doc comment.
+     * Suspicious-miss backstop: a `name` missing from the list is the signal that
+     * the snapshot may predate a branch that now exists, so force one fresh
+     * regeneration and re-search before giving up. Throttled per instance, so a
+     * genuinely-absent branch costs at most one extra scan per window.
      */
     get(name: string): Promise<BranchContext | undefined>;
     private shouldForceRefresh;
     /**
-     * Marks the cache as stale for every process sharing this root by bumping
-     * the cross-process generation marker, then eager-regenerates on this host
-     * (see class doc comment for why). The bump must succeed: a swallowed
-     * failure here would leave the registry stale indefinitely with no
-     * bounding backstop, unlike a failed eager regen below, which only forgoes
-     * closing window (E) early - the bump alone already restored correctness
-     * for every future reader. A failed eager regen therefore must not fail the
-     * caller's save/delete.
+     * Marks the cache stale for every process sharing this root by bumping the
+     * marker, then eager-regenerates on this host. The bump must succeed —
+     * swallowing that failure leaves the registry stale indefinitely with no
+     * backstop. A failed eager regen must NOT fail the caller's save/delete: the
+     * bump alone already restored correctness for every future reader.
      */
     invalidate(): Promise<void>;
     /**
      * Scans branch directories and rebuilds the cache, deduping concurrent
      * callers on this instance to a single underlying scan. Never loops waiting
-     * for the snapshot's embedded token to match the marker - under a bump
-     * storm that could livelock; a caller that wants the very latest state
-     * after a concurrent bump should call list() again after this resolves.
+     * for the embedded token to match the marker — that livelocks under a bump
+     * storm; a caller wanting the very latest state calls list() again.
      */
     private regenerate;
     private performRegenerate;