canopycms 0.0.67-int.90 → 0.0.67

package/dist/branch-registry.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-// The leaf, NOT './branch-metadata' — that module imports this one back, and
-// the pair was the package's only runtime import cycle. See branch-metadata-file.ts.
+// The leaf, NOT './branch-metadata': that module imports this one back, so the
+// pair would be a runtime import cycle. See branch-metadata-file.ts.
 import { readBranchMetadataFile } from './branch-metadata-file.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
@@ -13,10 +13,8 @@ import { bumpResourceGeneration, readResourceGeneration, isGenerationCurrent, }
 const log = createDebugLogger({ prefix: 'BranchRegistry' });
 // Registry files are stored directly in the branches root (not in a subdirectory)
 const REGISTRY_FILE = 'branches.json';
-// Legacy rename-based invalidation scheme's stale marker file. No longer written -
-// invalidate() now bumps the cross-process generation marker instead - but a
-// process upgraded mid-flight may find one left over from before the deploy, so
-// regenerate() opportunistically deletes it. Keep this name only for that cleanup.
+// Retired stale-marker file, never written. Named only so regenerate() can
+// delete one a mid-flight deploy left behind.
 const REGISTRY_STALE_FILE = 'branches.stale.json';
 const REGISTRY_TEMP_FILE = 'branches.tmp.json';
 const REGISTRY_VERSION = 2;
@@ -25,50 +23,18 @@ const RESOURCE = 'branch-registry';
 /** Throttle for the get() suspicious-miss backstop; mirrors content-store's FORCED_REFRESH_MIN_INTERVAL_MS. */
 const GET_MISS_REFRESH_MIN_INTERVAL_MS = 5000;
 /**
- * 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 class BranchRegistry {
     constructor(root) {
@@ -97,10 +63,9 @@ export class BranchRegistry {
             }
             throw err;
         }
-        // Strict version check: a truthy-only check would accept a persisted v1
-        // snapshot (no `generation` field) left on EFS after a rolling deploy,
-        // and `parsed.generation` would then be `undefined` rather than a real
-        // token or explicit `null`, breaking the freshness comparison below.
+        // Strict version check, not truthiness: a snapshot from an older version
+        // left on EFS by a rolling deploy has no `generation` field, and an
+        // `undefined` token breaks the freshness comparison below.
         if (parsed.version !== REGISTRY_VERSION || !Array.isArray(parsed.branches)) {
             return await this.regenerate();
         }
@@ -111,15 +76,12 @@ export class BranchRegistry {
         return await this.regenerate();
     }
     /**
-     * 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.
      */
     async get(name) {
         const branches = await this.list();
@@ -139,23 +101,19 @@ export class BranchRegistry {
         return true;
     }
     /**
-     * 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.
      */
     async invalidate() {
         await bumpResourceGeneration(this.root, RESOURCE, { mustSucceed: true });
         try {
-            // A scan already in flight (a concurrent list() on this shared
-            // instance) captured the PRE-bump token and possibly pre-mutation
-            // state; joining it via regenerate()'s dedup would skip the eager
-            // post-bump scan this method exists for. Let it drain — its snapshot
-            // self-describes as stale either way — then run a fresh scan.
+            // A scan already in flight captured the PRE-bump token and possibly
+            // pre-mutation state; joining it via regenerate()'s dedup would skip the
+            // eager post-bump scan this method exists for. Let it drain — its
+            // snapshot self-describes as stale either way — then scan fresh.
             if (this.regenInFlight)
                 await this.regenInFlight.catch(() => { });
             await this.regenerate();
@@ -169,9 +127,8 @@ export class BranchRegistry {
     /**
      * 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.
      */
     async regenerate() {
         if (this.regenInFlight)
@@ -191,16 +148,13 @@ export class BranchRegistry {
         // next probe instead of silently resurrecting stale data.
         const read = await readResourceGeneration(this.root, RESOURCE);
         const branches = await this.scanBranchDirectories();
-        // Opportunistic cleanup of a stale file left by the old rename-based
-        // invalidation scheme (e.g. a process upgraded mid-flight). Not load-bearing.
+        // Opportunistic cleanup of the retired stale-marker file. Not load-bearing.
         await fs.unlink(this.stalePath).catch(() => { });
         if (!read.ok) {
-            // The marker couldn't be read for a reason other than "never bumped" -
-            // we cannot attribute a token to this scan, and stamping the snapshot
-            // with an unattributable token would make it indistinguishable from a
-            // correctly-attributed one to every future reader on any host. Serve
-            // the fresh scan result without persisting it; the next read retries
-            // the marker read and, on success, regenerates and persists normally.
+            // The marker read failed for a reason other than "never bumped", so no
+            // token can be attributed to this scan, and a snapshot stamped with an
+            // unattributable one would look correctly attributed to every future
+            // reader on any host. Serve the fresh scan without persisting it.
             return branches;
         }
         const snapshot = {
@@ -208,8 +162,8 @@ export class BranchRegistry {
             branches,
             generation: read.token,
         };
-        // Write to unique temp file first, then atomic rename.
-        // Use random suffix to avoid conflicts between concurrent regenerations.
+        // Temp file then atomic rename; the random suffix keeps concurrent
+        // regenerations off each other's temp path.
         const uniqueTempPath = `${this.tempPath}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
         await fs.mkdir(this.root, { recursive: true });
         await fs.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + '\n', 'utf8');
@@ -217,7 +171,6 @@ export class BranchRegistry {
             await fs.rename(uniqueTempPath, this.registryPath);
         }
         catch (err) {
-            // Clean up temp file if rename fails
             await fs.unlink(uniqueTempPath).catch(() => { });
             throw err;
         }
@@ -238,11 +191,10 @@ export class BranchRegistry {
                     continue;
                 }
                 const branchRoot = path.join(this.root, entry.name);
-                // Quarantine, don't propagate: one branch's corrupt/unreadable
-                // branch.json must not take down the whole listing (a rethrow here
-                // would 500 GET /branches for every branch). The broken branch just
-                // drops out of the registry; it stays on disk for the admin
-                // branch-health surface to report and repair.
+                // Quarantine, don't propagate: one branch's corrupt or unreadable
+                // branch.json must not take down the whole listing, which a rethrow
+                // would (500 on GET /branches, for every branch). The broken branch
+                // drops out of the registry and stays on disk for branch-health.
                 let meta;
                 try {
                     meta = await readBranchMetadataFile(branchRoot);
@@ -261,7 +213,6 @@ export class BranchRegistry {
             }
         }
         catch (err) {
-            // If root doesn't exist yet, return empty list
             if (isNotFoundError(err)) {
                 return [];
             }

package/dist/branch-schema-cache.d.ts

@@ -4,92 +4,32 @@ import type { OperatingMode } from './operating-mode/index.js';
 import type { EntrySchemaRegistry, SchemaResolutionResult } from './schema/types.js';
 /** resource-generation.ts resource key for the schema cache's marker. */
 export declare const SCHEMA_GENERATION_RESOURCE = "schema";
-/**
- * Schema cache structure stored in {branchRoot}/.canopy-meta/schema-cache.json
- */
+/** @internal Exported for tests. */
 export interface BranchSchemaCacheEntry {
     version: number;
     schema: RootCollectionConfig;
     flatSchema: FlatSchemaItem[];
     cachedAt: string;
     /**
-     * The resource-generation.ts marker token this snapshot was resolved
-     * 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. See the class doc comment.
+     * The marker token this snapshot was resolved 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;
 }
 /**
- * Manages per-branch schema caching with lazy loading and automatic
- * invalidation.
- *
- * ## Cross-process freshness (resource-generation.ts marker protocol)
- *
- * Several warm Lambda containers plus the EC2 worker can share one
- * branch-clone root over EFS, each with its own copy of
- * `schema-cache.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 cached snapshot embeds the marker
- * token it was resolved against, and every read cheaply re-checks the live
- * marker before trusting the cache. See that module's doc comment for the
- * full protocol and residual staleness windows (A/B/C/E).
- *
- * BranchSchemaCache is the "durable snapshot consumer" case called out there:
- * a resolve 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 `schema-cache.json`, that staleness becomes durable and shared
- * with every other host that reads the marker - not just one process's
- * memory. `loadFromCacheOrResolve` mitigates this the same way
- * BranchRegistry does:
- *
- * - The marker is captured strictly BEFORE `resolveFresh()` runs, and the
- *   captured token (not one read after resolving) is what gets embedded in
- *   the persisted snapshot. A bump landing mid-resolve therefore leaves the
- *   embedded token older than the live marker, forcing a re-resolve on the
- *   next read instead of silently resurrecting stale schema.
- * - A snapshot is only persisted when the marker read itself succeeded
- *   (`{ ok: true }`). If the read fails for a reason other than "never
- *   bumped", we cannot attribute a token to this resolve, and stamping the
- *   snapshot with an unattributable token would make it indistinguishable
- *   from a correctly-attributed one to every future reader. The fresh result
- *   is still served to this caller; it just isn't written durably.
- * - invalidate() bumps the marker with `mustSucceed: true`: an explicit
- *   invalidation (e.g. after a schema mutation) must not silently fail and
- *   leave every reader confidently stale with no bounding backstop.
- *   invalidate() itself does NOT eager-regenerate - it isn't given the
- *   entrySchemaRegistry/contentRootName that resolveSchema needs. The
- *   eager re-resolve (window-E mitigation, mirroring BranchRegistry's
- *   eager regen) lives one level up in SchemaOps.invalidateSchemaCache()
- *   (schema/schema-store.ts), which has those arguments and calls
- *   {@link resolveAndPersist} (NOT getSchema()) right after invalidating -
- *   so every SchemaOps mutation re-resolves on the mutating host via a scan
- *   that is GUARANTEED to run, not merely likely to run. getSchema() would
- *   be the wrong call here: its cache-read fast path can short-circuit
- *   through a snapshot a DIFFERENT concurrent host just wrote (see
- *   resolveAndPersist()'s doc comment for the exact race), silently
- *   skipping the one scan this eager re-resolve exists to guarantee. (The
- *   editor's follow-up schema GET is a separate Lambda invocation with no
- *   container affinity, so it could not serve this purpose either.)
- *   Callers of invalidate() that bypass SchemaOps (api/schema.ts's explicit
- *   invalidate endpoint; the bulk-mutation bump in
- *   invalidateBranchContentCaches) accept the lazy next-read regen.
- *
- * This is also why prod needs no mtime walk: the dev-only mtime check below
- * exists solely to catch hand edits to .collection.json made outside the CMS
- * (which bypass SchemaOps and therefore never bump the marker). Every
- * mutation path that matters in prod - SchemaOps writes, git working-tree
- * rewrites (checkout/merge/rebase/sync/migrate) - bumps the marker via
- * SchemaOps.invalidateSchemaCache() or the combined
- * invalidateBranchContentCaches() helper in content-index-generation.ts, so
- * the marker alone is a sufficient prod backstop.
+ * Per-branch schema cache: a file at {branchRoot}/.canopy-meta/schema-cache.json
+ * with no in-memory layer, so it stays coherent across Lambda invocations.
  *
- * Caching Strategy:
- * - File-based cache at {branchRoot}/.canopy-meta/schema-cache.json (no
- *   in-memory layer - intentional: matches prod behavior and keeps cache
- *   coherent across Lambda invocations)
- * - Invalidation: invalidate() bumps the cross-process generation marker;
- *   every reader sharing this branchRoot re-resolves at its next access.
+ * Freshness follows the generation-marker protocol owned by
+ * resource-generation.ts, and this is one of that protocol's durable-snapshot
+ * consumers. Its eager re-resolve lives one level up, in
+ * `SchemaOps.invalidateSchemaCache()` (schema/schema-store.ts), because that is
+ * where the entrySchemaRegistry/contentRootName arguments {@link invalidate}
+ * lacks are available; it calls {@link resolveAndPersist}, never getSchema().
+ * Callers that bypass SchemaOps (api/schema.ts's invalidate endpoint, and the
+ * bulk git-op bump in invalidateBranchContentCaches) accept the lazy
+ * next-read regen instead.
  */
 export declare class BranchSchemaCache {
     /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
@@ -99,35 +39,23 @@ export declare class BranchSchemaCache {
     /**
      * Whether to skip the on-disk cache for this branchRoot.
      *
-     * branchRoot equals the project root (process.cwd()) only in the synthetic
-     * contexts used by static deployments and build phases — real branch roots are
-     * always nested under the workspace (.canopy-dev/content-branches/<name> in dev,
-     * <workspaceRoot>/content-branches/<name> in prod). Never write .canopy-meta/ at
-     * the project root, regardless of which entrypoint produced the cwd branchRoot.
+     * Never write `.canopy-meta/` at the project root, whichever entrypoint
+     * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
+     * synthetic contexts static deployments and build phases use; a real branch
+     * root is always nested under the workspace.
      */
     private skipDiskCache;
-    /**
-     * Get schema for a branch (loads from cache or resolves fresh).
-     *
-     * @param branchRoot - Root directory of the branch (e.g., .canopy-dev/content-branches/main)
-     * @param entrySchemaRegistry - Map of schema names to field definitions
-     * @param contentRootName - Name of content directory (e.g., "content") from config
-     * @returns Resolved schema tree and flattened schema
-     */
+    /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
     getSchema(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
         schema: RootCollectionConfig;
         flatSchema: FlatSchemaItem[];
     }>;
     /**
-     * Resolve the schema from disk. Wrapped in a protected method (rather than
-     * calling the imported resolveSchema directly) so tests can subclass and
-     * override with a deferred/blocking implementation to simulate cross-process
+     * Resolve the schema from disk. Protected rather than a direct resolveSchema
+     * call so tests can subclass and block it to simulate cross-process
      * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
      */
     protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry): Promise<SchemaResolutionResult>;
-    /**
-     * Load schema from cache or resolve fresh if cache is missing or stale.
-     */
     private loadFromCacheOrResolve;
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
@@ -137,43 +65,25 @@ export declare class BranchSchemaCache {
      */
     private resolveFreshAndPersist;
     /**
-     * Resolve the schema fresh from disk and persist it, SKIPPING the cache
-     * read entirely -- unlike {@link getSchema}, which can short-circuit
-     * through a cache HIT. That distinction matters for eager re-resolve after
-     * invalidation (see {@link invalidate}'s doc comment and
-     * `SchemaOps.invalidateSchemaCache()` in schema/schema-store.ts, the sole
-     * intended caller): the whole point of an eager re-resolve is to guarantee
-     * ONE scan that is coherent with the mutation this host just made. A plain
-     * `getSchema()` call right after `invalidate()` is NOT that guarantee --
-     * `getSchema()`'s cache-read fast path (`loadFromCacheOrResolve`) can still
-     * return a snapshot written by a DIFFERENT, concurrent host: if that
-     * foreign host's own eager re-resolve raced this one and embedded the
-     * (now-current) marker token over ITS OWN stale-NFS-cache scan (the
-     * window-E case this class's doc comment describes), this host's
-     * `getSchema()` would happily accept that foreign snapshot as "current"
-     * and skip the one scan this call was specifically trying to guarantee.
-     * `resolveAndPersist()` never reads the cache file at all, so it cannot be
-     * short-circuited that way.
+     * Resolve fresh from disk and persist, SKIPPING the cache read entirely.
+     * That is what makes it, and not {@link getSchema}, the right call for the
+     * eager re-resolve in `SchemaOps.invalidateSchemaCache()` (its sole intended
+     * caller): an eager re-resolve exists to guarantee ONE scan coherent with the
+     * mutation this host just made, and getSchema()'s cache-read fast path can
+     * instead return a snapshot a concurrent host wrote — possibly one embedding
+     * the now-current token over ITS own stale-NFS scan — skipping that scan.
      */
     resolveAndPersist(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
         schema: RootCollectionConfig;
         flatSchema: FlatSchemaItem[];
     }>;
     /**
-     * Invalidate cache for a branch by bumping the cross-process generation
-     * marker (resource-generation.ts). Every process sharing this branchRoot
-     * will re-resolve at its next read.
-     *
-     * The bump must succeed: a swallowed failure here would leave the schema
-     * cache stale indefinitely with no bounding backstop (unlike
-     * BranchRegistry, there is no get-miss backstop for a resolved schema).
-     *
-     * No eager regeneration here (unlike BranchRegistry.invalidate()): this
-     * method isn't given the entrySchemaRegistry/contentRootName resolveSchema
-     * needs. See the class doc comment for why the mutating request's own
-     * follow-up schema read closes the same window-E gap instead.
+     * Invalidate a branch's cache by bumping the marker; every process sharing
+     * this branchRoot re-resolves at its next read. The bump must succeed —
+     * swallowing that failure leaves the schema cache stale indefinitely, and
+     * unlike BranchRegistry there is no get-miss backstop for a resolved schema.
      *
-     * @param branchRoot - Root directory of the branch
+     * No eager re-resolve here; it lives in SchemaOps (see the class doc).
      */
     invalidate(branchRoot: string): Promise<void>;
 }