canopycms 0.0.67-int.90 → 0.0.67

package/dist/content-index-generation.d.ts

@@ -1,65 +1,44 @@
-/** Absolute path of the generation marker for a branch-clone root. */
+/**
+ * Absolute path of the generation marker for a branch-clone root.
+ * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ */
 export declare function contentIndexGenerationPath(root: string): string;
 /**
  * Record on disk that indexed files under `root` changed, so ContentStores in
  * OTHER processes rebuild. Must be called AFTER the filesystem mutation.
- * Returns the token written, or null if the write failed (logged and swallowed:
- * the content mutation is already durable; a lost bump degrades to the
- * pre-marker staleness behavior plus the ContentStore backstop).
+ * Returns the token written, or null if the write failed — a hint bump, since
+ * the content mutation is already durable and ContentStore has a backstop.
  */
 export declare function bumpContentIndexGeneration(root: string): Promise<string | null>;
 /**
- * Read the current generation token for `root`. Returns null if the marker
- * does not exist yet (a valid state distinct from every token). Read errors
- * other than ENOENT are logged and treated as null — the caller then rebuilds,
- * which is the safe direction.
+ * Read the current generation token for `root`. Null means the marker does not
+ * exist yet; a read error collapses to null too, so the caller rebuilds, which
+ * is the safe direction.
  */
 export declare function readContentIndexGeneration(root: string): Promise<string | null>;
 /**
- * The designated entry point for a FUTURE content-only bulk mutation site —
- * one that mutates indexed files under a branch-clone root broadly (not
- * through a single known write/delete/rename call) but never touches schema.
- * Bumps the on-disk content-index marker (cross-process), then invalidates
- * in-process registered stores.
+ * The entry point for a bulk mutation site that touches indexed files under a
+ * branch-clone root broadly but never touches schema. No production caller yet:
+ * `ContentStore`'s write/delete/renameEntry bump the marker directly via
+ * `recordOwnMutation()`, and every bulk site (git checkout/merge/rebase, sync,
+ * CLI sync, migrate) can touch `.collection.json` as a side effect, so those
+ * take `invalidateBranchContentCaches()` below.
  *
- * Currently unused in production: `ContentStore`'s own write()/delete()/
- * renameEntry() bump the marker directly via their `recordOwnMutation()` ->
- * `bumpContentIndexGeneration()` call, not through this wrapper, and every
- * existing bulk-mutation call site (git checkout/merge/rebase, sync, CLI
- * sync, migrate) can touch `.collection.json` as a side effect, so those all
- * use the combined `invalidateBranchContentCaches()` below instead. Kept as
- * the documented, ready-to-use entry point for a future call site that is
- * genuinely content-only.
- *
- * Bump-before-invalidate: the in-process invalidation triggers a rebuild on
- * next access, and that rebuild captures the marker token before scanning —
- * writing the marker first lets the rebuild pick up the new token in the same
- * pass instead of a redundant second rebuild.
+ * Bump BEFORE invalidating: the rebuild the invalidation triggers captures the
+ * marker token before scanning, so the new token lands in that same pass
+ * instead of costing a second rebuild.
  */
 export declare function invalidateContentIndexesDurable(root: string): Promise<void>;
 /**
- * The entry point for operations that mutate a branch-clone root's working
- * tree BROADLY rather than through a single known write/delete/rename call:
- * git working-tree ops (checkout/merge/rebase/abort), content sync, CLI sync,
- * and migrate. Such operations can touch `.collection.json` files as a side
- * effect (a rebase can pull in upstream schema changes; a sync can overwrite
- * the whole content directory), so both durable, cross-process caches rooted
- * at `root` need to be told: the ContentId index (content-index-registry.ts)
- * AND the resolved-schema cache (branch-schema-cache.ts).
- *
- * `invalidateContentIndexesDurable` is the designated entry point for a
- * future call site that only ever touches content files, never schema, and
- * needs the durable-invalidation shape but not the extra schema bump.
- * `ContentStore`'s own write/delete/rename paths don't call it either — they
- * bump the content-index marker directly via `recordOwnMutation()` (see
- * content-store.ts), since they already know exactly which mutation just
- * happened and don't need a generic "some indexed files changed" entry point.
+ * The entry point for operations that mutate a branch-clone root's working tree
+ * broadly: git working-tree ops (checkout/merge/rebase/abort), content sync,
+ * CLI sync, migrate. Those can touch `.collection.json` as a side effect (a
+ * rebase pulls in upstream schema changes; a sync overwrites the whole content
+ * directory), so BOTH caches rooted at `root` are bumped — the ContentId index
+ * and the resolved-schema cache.
  *
- * Both marker bumps are "hint" flavor (bumpResourceGeneration's default,
- * `mustSucceed` not set): callers of this function are typically `finally`
- * blocks in bulk operations (e.g. a git rebase cleanup) that must not start
- * throwing because a marker write failed - log-and-swallow is the existing
- * semantics at those call sites, and a lost bump only degrades to pre-marker
- * staleness behavior plus whatever backstop the consumer implements.
+ * Both bumps are hint flavor (no `mustSucceed`): these callers are typically
+ * `finally` blocks in bulk operations, which must not start throwing because a
+ * marker write failed.
  */
 export declare function invalidateBranchContentCaches(root: string): Promise<void>;

package/dist/content-index-generation.js

@@ -2,43 +2,15 @@ import { resourceGenerationPath, bumpResourceGeneration, readResourceGeneration,
 import { invalidateContentIndexesForRoot } from './content-index-registry.js';
 import { SCHEMA_GENERATION_RESOURCE } from './branch-schema-cache.js';
 /**
- * Cross-process ContentId index generation marker.
+ * The ContentIdIndex instance of the generation-marker protocol owned by
+ * resource-generation.ts; the marker lives at
+ * {root}/.canopy-meta/content-index.generation. In-process invalidation of the
+ * same indexes is content-index-registry.ts's job.
  *
- * This is the ContentIdIndex-specific instance of the generic on-disk
- * generation-marker protocol in resource-generation.ts — see that module's
- * doc comment for the full protocol (random-token rationale, bump/read
- * ordering, and the general residual staleness windows A/B/C/E). This file
- * documents only what is specific to the in-memory ContentIdIndex.
- *
- * The ContentIdIndex is an in-memory map per ContentStore instance. Within one
- * process, content-index-registry.ts invalidates stale indexes directly. Across
- * processes (several warm Lambda containers + the EC2 worker sharing branch
- * clones on EFS) there is no shared memory and no cross-host file watching, so
- * the shared filesystem itself is the coordination medium: every operation that
- * mutates indexed files under a branch-clone root also rewrites a small marker
- * file with a fresh random token, and every ContentStore cheaply re-reads that
- * marker (throttled) to decide whether its in-memory index is still current.
- *
- * The marker lives at {root}/.canopy-meta/content-index.generation.
- *
- * ## Residual staleness windows, as they apply here
- *
- * All bounded in practice by per-request ContentStore lifetimes and self-healed
- * by the suspicious-lookup backstop in ContentStore:
- *
- * - (A) NFS attribute caching: another host may not see a new marker for up to
- *   the attribute-cache timeout (~3-60s on default EFS mounts). The reader acts
- *   on a stale token and keeps a stale index until the cache expires.
- * - (B) Probe throttle: up to ContentStore's indexFreshnessIntervalMs (1s).
- * - (C) Self-adoption: after its own mutation a store adopts the token it
- *   wrote; if a concurrent foreign bump landed just before ours, we miss that
- *   one notification (window: from our last token observation to our rename).
- * - (E) Fresh-token/stale-scan (cross-host only): a rebuild's readdir calls may
- *   be served from stale dentry/attribute caches, recording a NEW token against
- *   PRE-mutation directory listings. Unlike a durable-snapshot consumer (see
- *   resource-generation.ts), this only mis-serves ONE process's in-memory
- *   index for the remainder of its lifetime — it is not written back to disk,
- *   so it cannot become a shared stale state visible to other hosts.
+ * Local to this consumer: the index is per-ContentStore memory, never persisted,
+ * so a scan that records a fresh token over stale NFS-cached readdir results
+ * mis-serves only that one process for the rest of its lifetime — it cannot
+ * become shared stale state the way a durable snapshot can.
  *
  * Wrong-file WRITE corruption (recreating a concurrently renamed entry →
  * duplicate IDs) is prevented independently of this marker by the existence
@@ -46,79 +18,58 @@ import { SCHEMA_GENERATION_RESOURCE } from './branch-schema-cache.js';
  * before recreating a missing expected file.
  */
 const RESOURCE = 'content-index';
-/** Absolute path of the generation marker for a branch-clone root. */
+/**
+ * Absolute path of the generation marker for a branch-clone root.
+ * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ */
 export function contentIndexGenerationPath(root) {
     return resourceGenerationPath(root, RESOURCE);
 }
 /**
  * Record on disk that indexed files under `root` changed, so ContentStores in
  * OTHER processes rebuild. Must be called AFTER the filesystem mutation.
- * Returns the token written, or null if the write failed (logged and swallowed:
- * the content mutation is already durable; a lost bump degrades to the
- * pre-marker staleness behavior plus the ContentStore backstop).
+ * Returns the token written, or null if the write failed — a hint bump, since
+ * the content mutation is already durable and ContentStore has a backstop.
  */
 export async function bumpContentIndexGeneration(root) {
     return bumpResourceGeneration(root, RESOURCE);
 }
 /**
- * Read the current generation token for `root`. Returns null if the marker
- * does not exist yet (a valid state distinct from every token). Read errors
- * other than ENOENT are logged and treated as null — the caller then rebuilds,
- * which is the safe direction.
+ * Read the current generation token for `root`. Null means the marker does not
+ * exist yet; a read error collapses to null too, so the caller rebuilds, which
+ * is the safe direction.
  */
 export async function readContentIndexGeneration(root) {
     const result = await readResourceGeneration(root, RESOURCE);
     return result.ok ? result.token : null;
 }
 /**
- * The designated entry point for a FUTURE content-only bulk mutation site —
- * one that mutates indexed files under a branch-clone root broadly (not
- * through a single known write/delete/rename call) but never touches schema.
- * Bumps the on-disk content-index marker (cross-process), then invalidates
- * in-process registered stores.
+ * The entry point for a bulk mutation site that touches indexed files under a
+ * branch-clone root broadly but never touches schema. No production caller yet:
+ * `ContentStore`'s write/delete/renameEntry bump the marker directly via
+ * `recordOwnMutation()`, and every bulk site (git checkout/merge/rebase, sync,
+ * CLI sync, migrate) can touch `.collection.json` as a side effect, so those
+ * take `invalidateBranchContentCaches()` below.
  *
- * Currently unused in production: `ContentStore`'s own write()/delete()/
- * renameEntry() bump the marker directly via their `recordOwnMutation()` ->
- * `bumpContentIndexGeneration()` call, not through this wrapper, and every
- * existing bulk-mutation call site (git checkout/merge/rebase, sync, CLI
- * sync, migrate) can touch `.collection.json` as a side effect, so those all
- * use the combined `invalidateBranchContentCaches()` below instead. Kept as
- * the documented, ready-to-use entry point for a future call site that is
- * genuinely content-only.
- *
- * Bump-before-invalidate: the in-process invalidation triggers a rebuild on
- * next access, and that rebuild captures the marker token before scanning —
- * writing the marker first lets the rebuild pick up the new token in the same
- * pass instead of a redundant second rebuild.
+ * Bump BEFORE invalidating: the rebuild the invalidation triggers captures the
+ * marker token before scanning, so the new token lands in that same pass
+ * instead of costing a second rebuild.
  */
 export async function invalidateContentIndexesDurable(root) {
     await bumpContentIndexGeneration(root);
     invalidateContentIndexesForRoot(root);
 }
 /**
- * The entry point for operations that mutate a branch-clone root's working
- * tree BROADLY rather than through a single known write/delete/rename call:
- * git working-tree ops (checkout/merge/rebase/abort), content sync, CLI sync,
- * and migrate. Such operations can touch `.collection.json` files as a side
- * effect (a rebase can pull in upstream schema changes; a sync can overwrite
- * the whole content directory), so both durable, cross-process caches rooted
- * at `root` need to be told: the ContentId index (content-index-registry.ts)
- * AND the resolved-schema cache (branch-schema-cache.ts).
- *
- * `invalidateContentIndexesDurable` is the designated entry point for a
- * future call site that only ever touches content files, never schema, and
- * needs the durable-invalidation shape but not the extra schema bump.
- * `ContentStore`'s own write/delete/rename paths don't call it either — they
- * bump the content-index marker directly via `recordOwnMutation()` (see
- * content-store.ts), since they already know exactly which mutation just
- * happened and don't need a generic "some indexed files changed" entry point.
+ * The entry point for operations that mutate a branch-clone root's working tree
+ * broadly: git working-tree ops (checkout/merge/rebase/abort), content sync,
+ * CLI sync, migrate. Those can touch `.collection.json` as a side effect (a
+ * rebase pulls in upstream schema changes; a sync overwrites the whole content
+ * directory), so BOTH caches rooted at `root` are bumped — the ContentId index
+ * and the resolved-schema cache.
  *
- * Both marker bumps are "hint" flavor (bumpResourceGeneration's default,
- * `mustSucceed` not set): callers of this function are typically `finally`
- * blocks in bulk operations (e.g. a git rebase cleanup) that must not start
- * throwing because a marker write failed - log-and-swallow is the existing
- * semantics at those call sites, and a lost bump only degrades to pre-marker
- * staleness behavior plus whatever backstop the consumer implements.
+ * Both bumps are hint flavor (no `mustSucceed`): these callers are typically
+ * `finally` blocks in bulk operations, which must not start throwing because a
+ * marker write failed.
  */
 export async function invalidateBranchContentCaches(root) {
     await bumpContentIndexGeneration(root);

package/dist/content-index-registry.d.ts

@@ -1,37 +1,28 @@
 /**
- * In-process registry connecting branch-mutating operations (git checkout/merge/rebase,
- * content sync) to the ContentStore instances whose ContentId indexes those operations
- * make stale.
+ * In-process registry connecting branch-mutating operations to the ContentStore
+ * instances whose ContentId indexes they make stale. ContentStore registers
+ * itself on construction, keyed by its resolved root; a mutation site calls
+ * invalidateContentIndexesForRoot() so the next index access rebuilds from disk
+ * instead of serving stale ID→path mappings.
  *
- * ContentStore registers itself (keyed by its resolved root) on construction. Operations
- * that change files under a root — GitManager working-tree mutations, the worker's rebase
- * loop, sync-core's content replacement — call invalidateContentIndexesForRoot() so the
- * next index access rebuilds from disk instead of serving stale ID→path mappings.
+ * SCOPE: in-process only, the zero-latency half. Cross-process divergence is the
+ * generation marker's job (content-index-generation.ts), and mutation sites
+ * should call invalidateContentIndexesDurable() there, which does both.
  *
- * SCOPE: in-process only — the zero-latency path for stores in the same process.
- * Cross-process divergence (e.g. Lambda + worker on shared EFS, each with its own
- * registry) is handled by the on-disk generation marker in
- * content-index-generation.ts; invalidateContentIndexesDurable() there combines
- * both scopes and is what mutation sites should call.
- *
- * Stores are held via WeakRef so short-lived (per-request) instances can be garbage
- * collected; a FinalizationRegistry prunes dead entries.
+ * Stores are held via WeakRef so per-request instances can be collected; a
+ * FinalizationRegistry prunes dead entries.
  */
 /** Anything holding a rebuildable content index (in practice: ContentStore). */
 export interface InvalidatableContentIndex {
     invalidateIndex(): void;
 }
-/**
- * Register a content-index holder for invalidation when files under `root` change.
- * Called by the ContentStore constructor.
- */
+/** Register a holder for invalidation when files under `root` change. */
 export declare function registerContentIndexForInvalidation(root: string, target: InvalidatableContentIndex): void;
 /**
- * Invalidate every registered content index rooted at `root` or below it.
- * Prefix matching covers stores rooted at a subdirectory of the mutated repo
- * (e.g. a store rooted at a branch clone inside a mutated workspace tree).
+ * Invalidate every registered index rooted at `root` or below it; the prefix
+ * match covers a store rooted at a subdirectory of the mutated repo.
  *
- * Invalidation only marks indexes stale; the rebuild happens lazily on the next
- * index access, so calling this for a root with no live stores is free.
+ * This only marks indexes stale — the rebuild is lazy, on next access — so a
+ * root with no live stores costs nothing.
  */
 export declare function invalidateContentIndexesForRoot(root: string): void;

package/dist/content-index-registry.js

@@ -8,10 +8,7 @@ const finalization = new FinalizationRegistry(({ rootKey, ref }) => {
     if (refs.size === 0)
         registry.delete(rootKey);
 });
-/**
- * Register a content-index holder for invalidation when files under `root` change.
- * Called by the ContentStore constructor.
- */
+/** Register a holder for invalidation when files under `root` change. */
 export function registerContentIndexForInvalidation(root, target) {
     const rootKey = path.resolve(root);
     let refs = registry.get(rootKey);
@@ -24,12 +21,11 @@ export function registerContentIndexForInvalidation(root, target) {
     finalization.register(target, { rootKey, ref });
 }
 /**
- * Invalidate every registered content index rooted at `root` or below it.
- * Prefix matching covers stores rooted at a subdirectory of the mutated repo
- * (e.g. a store rooted at a branch clone inside a mutated workspace tree).
+ * Invalidate every registered index rooted at `root` or below it; the prefix
+ * match covers a store rooted at a subdirectory of the mutated repo.
  *
- * Invalidation only marks indexes stale; the rebuild happens lazily on the next
- * index access, so calling this for a root with no live stores is free.
+ * This only marks indexes stale — the rebuild is lazy, on next access — so a
+ * root with no live stores costs nothing.
  */
 export function invalidateContentIndexesForRoot(root) {
     const rootKey = path.resolve(root);

package/dist/content-listing.d.ts

@@ -1,15 +1,10 @@
 /**
  * Shared content-listing utilities used by both the entries API and the content tree builder.
- *
- * Extracted from api/entries.ts to avoid duplication.
  */
 import type { ContentFormat, FlatSchemaItem, EntrySchema } from './config/index.js';
 import type { LogicalPath, PhysicalPath, Slug, ContentId } from './paths/types.js';
 import { ContentStore, type ReferenceResolveCache } from './content-store.js';
-/**
- * An entry listing item with raw data from the filesystem.
- * Does not include API-specific fields like canEdit.
- */
+/** An entry listing item with raw filesystem data; no API-specific fields like canEdit. */
 export interface CollectionListItem {
     logicalPath: LogicalPath;
     contentId: ContentId;
@@ -23,14 +18,6 @@ export interface CollectionListItem {
     data: Record<string, unknown>;
     updatedAt?: string;
 }
-/**
- * Read entry data from a file.
- * For md/mdx: returns frontmatter fields plus the body content (mapped to the
- * field name specified by `bodyFieldName`, which defaults to `'body'`).
- * For json: returns the parsed JSON object.
- * Returns an empty object on read/parse failure.
- */
-export declare const readEntryData: (filePath: string, format: ContentFormat, bodyFieldName?: string) => Promise<Record<string, unknown>>;
 export { parseTypedFilename } from './utils/typed-filename.js';
 /**
  * A flat entry item from listEntries.
@@ -40,17 +27,15 @@ export interface ListEntriesItem<T = Record<string, unknown>> {
     /** URL path segments, e.g., ['researchers', 'guides', 'glossary-of-terms'] */
     pathSegments: string[];
     /**
-     * URL-ready path with index entries collapsed to their parent collection path.
-     * For index entries: '/guides' instead of '/guides/index'.
-     * For regular entries: '/guides/glossary-of-terms'.
-     * For a root index entry: '/'.
+     * URL-ready path with index entries collapsed to their parent collection path: '/guides'
+     * for the index entry of guides, '/guides/glossary-of-terms' for a regular entry, '/' for a
+     * root index entry.
      *
-     * Round-trip safe: `readByUrlPath(item.urlPath)` resolves to the same entry. That guarantee
-     * depends on `slug` passing `parseSlug` — the filename grammar (`utils/typed-filename.ts`)
-     * allows a slug to contain characters `parseSlug` rejects (a dot, most commonly), and an entry
-     * whose slug does is listed here same as any other but can never be read back by URL.
-     * `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this outside
-     * this doc comment's promise.
+     * Round-trip safe: `readByUrlPath(item.urlPath)` resolves to the same entry -- but only
+     * while `slug` passes `parseSlug`. The filename grammar (`utils/typed-filename.ts`) allows
+     * slugs `parseSlug` rejects (a dot, most commonly), and such an entry is listed here like
+     * any other yet can never be read back by URL. `static/index.ts`'s `assertRoutableSlugs` is
+     * the build-time guard that catches it.
      */
     urlPath: string;
     /** Entry slug within its collection */
@@ -75,20 +60,17 @@ export interface ListEntriesItem<T = Record<string, unknown>> {
     /** Field definitions for this entry's type, when resolvable. */
     schema?: EntrySchema;
     /**
-     * Filesystem mtime (ISO 8601) of the entry file, from an unconditional `fs.stat`
-     * done while listing. Caveat: this is a checkout-time timestamp, not an editorial
-     * one — a fresh CI clone resets every file's mtime to checkout time, so treat this
-     * as "changed since last build" at best, not an authoritative last-edited date for
-     * a public-facing `<lastmod>`. Sourcing mtime from git commit history is a
-     * separate, not-yet-built improvement.
+     * Filesystem mtime (ISO 8601) of the entry file, from an unconditional `fs.stat` done while
+     * listing. Caveat: a checkout-time timestamp, not an editorial one — a fresh CI clone resets
+     * every file's mtime — so treat it as "changed since last build" at best, never as an
+     * authoritative last-edited date for a public-facing `<lastmod>`.
      */
     updatedAt?: string;
 }
 export interface ListEntriesOptions<T = Record<string, unknown>> {
     /**
-     * Transform raw entry data. Controls what ends up in `data` on each result.
-     * Raw data includes all frontmatter fields; for md/mdx, raw.body is the markdown content.
-     * Without extract, data is the full raw object.
+     * Transform raw entry data; controls what ends up in `data` on each result. Raw data
+     * includes all frontmatter fields, and for md/mdx `raw.body` is the markdown content.
      */
     extract?: (raw: Record<string, unknown>, meta: {
         entryPath: LogicalPath;
@@ -107,44 +89,38 @@ export interface ListEntriesOptions<T = Record<string, unknown>> {
     sort?: (a: ListEntriesItem<T>, b: ListEntriesItem<T>) => number;
     /**
      * Resolve `reference` fields to the referenced entry's data, the way
-     * `read()`/`readByUrlPath()` do — including references nested inside `object` fields,
-     * inline `group`s and block templates (so a shared/referenced block finally carries its
-     * snippet's content here). Off leaves them as the bare id string, or `null`.
+     * `read()`/`readByUrlPath()` do — including references nested inside `object` fields, inline
+     * `group`s and block templates. Off leaves them as the bare id string, or `null`.
      *
-     * **Defaults to `false`, unlike `read()`, which defaults to `true`.** The asymmetry is
-     * deliberate rather than an oversight. `data` is `T` and `extract` receives an untyped
-     * `Record<string, unknown>`, so turning this on changes a reference from `'a1b2c3d4e5f6'`
-     * to `{ ...data, id, slug, collection, urlPath }` with no compile error anywhere to catch it — an
-     * `/authors/${data.author}` template silently becomes `/authors/[object Object]`. Opting
-     * in is a decision you make per call site, next to the code that reads the field. It also
-     * keeps the common batch uses free: `collectStaticPaths` discards `data` outright, and
-     * `build/generate-ai-content.ts` lists purely to validate entry shapes.
+     * **Defaults to `false`, unlike `read()`, which defaults to `true`.** Deliberate: `data` is
+     * `T` and `extract` receives an untyped `Record<string, unknown>`, so turning this on
+     * changes a reference from `'a1b2c3d4e5f6'` to `{ ...data, id, slug, collection, urlPath }`
+     * with no compile error anywhere to catch it — an `/authors/${data.author}` template
+     * silently becomes `/authors/[object Object]`. Opting in is a decision per call site, next
+     * to the code that reads the field. It also keeps the common batch uses free:
+     * `collectStaticPaths` discards `data` outright.
      *
      * **Cost, and why it is bounded.** Resolution needs a `ContentStore` and its ContentId
-     * index, so turning it on adds one index scan per call plus one read per DISTINCT
-     * referenced entry — not per referencing entry. A single {@link ReferenceResolveCache}
-     * spans the whole call, so a shared block referenced by 40 pages is read once, not 40
-     * times. Nothing is constructed and nothing is scanned when this is off.
+     * index, so this adds one index scan per call plus one read per DISTINCT referenced entry —
+     * not per referencing entry, since a single {@link ReferenceResolveCache} spans the whole
+     * call. Nothing is constructed and nothing is scanned when this is off.
      *
      * **Path ACLs are not applied to the resolved targets**, matching `read()` exactly: a
-     * reference can resolve to an entry the user could not `read()` directly. The entries
-     * being LISTED are still ACL-filtered as always, and a filtered-out entry is never
-     * resolved at all.
+     * reference can resolve to an entry the user could not `read()` directly. The entries being
+     * LISTED are still ACL-filtered, and a filtered-out entry is never resolved at all.
      */
     resolveReferences?: boolean;
 }
 /**
- * Server-only path-ACL predicate, applied to raw entries before any of their data
- * reaches a caller.
+ * Server-only path-ACL predicate, applied to raw entries before any of their data reaches a
+ * caller.
  *
  * Deliberately NOT part of `ListEntriesOptions`/`BuildContentTreeOptions`: those are
- * adopter-facing, and adopter code must not be able to supply, widen, or override the
- * access check. `context.ts` is the only intended producer — it builds the predicate
- * from `services.createContentAccessChecker` for the request-scoped user, and omits it
- * entirely at build time / on static deployments (synthetic admin, no ACLs).
- *
- * Omitting it preserves the pre-existing unfiltered behavior exactly, which is what
- * build-time callers want.
+ * adopter-facing, and adopter code must not be able to supply, widen or override the access
+ * check. `context.ts` is the only intended producer — it builds the predicate from
+ * `services.createContentAccessChecker` for the request-scoped user, and omits it entirely at
+ * build time / on static deployments (synthetic admin, no ACLs), leaving the listing
+ * unfiltered exactly as build-time callers want.
  */
 export interface ContentVisibilityOptions {
     /** Return false to drop an entry. Receives the entry's branch-root-relative physical path. */
@@ -158,18 +134,16 @@ export type CollectionSchemaItem = Extract<FlatSchemaItem, {
  * Build the `ContentStore` + shared cache that a batch listing resolves references through.
  *
  * Unrelated to the `ReferenceResolver` class in reference-resolver.ts despite the adjacent
- * name — that one resolves an id to a human-readable *display label* for the editor UI. This
- * resolves a reference to the referenced entry's *data* for server-side listings.
+ * name — that one resolves an id to a human-readable display label for the editor UI.
  *
- * Constructed lazily by each listing surface, and ONLY when the caller opted in — a store
+ * Constructed lazily by each listing surface, and ONLY when the caller opted in: a store
  * builds a ContentId index on first use, which is a full scan of the content tree, and the
  * default (`resolveReferences` off) must stay a pure filesystem walk with no index at all.
  *
- * One store and one cache per listing call, not per collection: the cache is the reason a
+ * One store and one cache per listing CALL, not per collection: the cache is the reason a
  * shared block referenced from 40 pages costs one read instead of 40, so it has to span the
- * whole batch. Per-call construction is the established shape here — content-reader.ts's
- * `resolveStore` builds a store per read, and content-index-registry.ts holds stores through
- * `WeakRef` + a `FinalizationRegistry` precisely so short-lived instances stay collectable.
+ * whole batch. content-index-registry.ts holds stores through `WeakRef` + a
+ * `FinalizationRegistry`, so these short-lived instances stay collectable.
  */
 export declare const createReferenceResolver: (branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string) => {
     store: ContentStore;
@@ -188,41 +162,27 @@ export declare const resolveCollectionItemReferences: (items: CollectionListItem
     cache: ReferenceResolveCache;
 }) => Promise<CollectionListItem[]>;
 /**
- * List all content entries as a flat array.
- *
- * Walks the schema to discover collections, reads entries from each,
- * and returns a flat list suitable for generateStaticParams, search indexing, sitemaps, etc.
+ * List all content entries as a flat array: walks the schema to discover collections, reads
+ * entries from each, and returns a flat list suitable for generateStaticParams, search
+ * indexing, sitemaps, etc.
  *
- * Build-time-only failure: a file with a recognized content extension (`.md`/`.mdx`/`.json`/
- * `.yaml`) sitting in a collection directory that *looks like an attempted entry* (see
- * `looksLikeMalformedEntry` below) but doesn't match `{type}.{slug}.{id}.{ext}` is, by default,
- * silently dropped (see `listCollectionEntries`'s debug-gated warning). That is exactly the
- * silent-page-loss failure mode static generation must not have — a schema rename without a
- * matching file rename, or an entry type declared in one collection but not another, would
- * otherwise vanish a page with zero build output. So when `isBuildMode()` is true, any such file
- * turns the listing into a thrown error instead (see `findInvalidEntries`/`assertBuildEntriesValid`
- * in `static/index.ts` for the sibling schema-validity guard this mirrors). Outside build mode
- * (admin UI, content tree, `next dev`) the file is still just skipped, since a fresh scaffold or
- * mid-rename file legitimately exists there.
+ * Build-time-only failure: a file with a recognized content extension sitting in a collection
+ * directory that *looks like an attempted entry* (see `looksLikeMalformedEntry`) but does not
+ * match `{type}.{slug}.{id}.{ext}` is silently dropped by default. That is exactly the
+ * silent-page-loss static generation must not have -- a schema rename without a matching file
+ * rename, or an entry type declared in one collection but not another, would vanish a page with
+ * zero build output -- so when `isBuildMode()` is true any such file throws instead
+ * (`static/index.ts`'s `assertBuildEntriesValid` is the sibling schema-validity guard).
+ * Outside build mode (admin UI, content tree, `next dev`) it is still skipped, since a fresh
+ * scaffold or mid-rename file legitimately exists there.
  *
- * A file that was never entry-shaped to begin with — a `README.md`, or a colocated sibling
- * artifact named `{contentId}.suffix.ext` per the `entryTransforms`/`readSibling` convention
- * documented in the README — is not this guard's failure mode and never throws, in or out of
- * build mode. See `looksLikeMalformedEntry` for the exact shape test.
- *
- * @param branchRoot - Absolute path to the branch workspace root
- * @param flatSchema - Flattened schema items (from flattenSchema)
- * @param contentRootName - The content root name (e.g. "content")
- * @param options - Listing options (extract, filter, rootPath, sort, resolveReferences)
- * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
+ * A file that was never entry-shaped -- a `README.md`, or a colocated sibling artifact named
+ * `{contentId}.suffix.ext` per the `entryTransforms`/`readSibling` convention -- never throws.
  */
 export declare function listEntries<T = Record<string, unknown>>(branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, options?: ListEntriesOptions<T>, visibility?: ContentVisibilityOptions): Promise<ListEntriesItem<T>[]>;
 /**
- * Sort items by a content ID order array.
- * Items in the order array come first (in order), items not in the array come at the end
- * sorted by the provided fallback key.
- *
- * Note: sorts the array in-place and returns it.
+ * Sort items by a content ID order array: items in `order` come first, in that order, then
+ * the rest sorted by `fallbackKey`. Sorts the array in place and returns it.
  */
 export declare const sortByOrder: <T extends {
     contentId?: ContentId;
@@ -235,16 +195,13 @@ export interface SkippedListingFile {
     collectionPath: LogicalPath;
 }
 /**
- * List all entries in a collection directory.
- * Reads each entry's data (frontmatter or JSON).
+ * List all entries in a collection directory, reading each entry's data.
  *
- * @param onSkip - Called for every file that has a recognized content extension, doesn't match
- *   the `{type}.{slug}.{id}.{ext}` grammar (see `parseTypedFilename`), AND structurally looks
- *   like an attempted entry (see `looksLikeMalformedEntry`). A file that was never entry-shaped
- *   (too few dot-separated segments to ever be a valid entry — a `README.md`, a colocated
- *   sibling artifact) is always silently dropped with a debug-gated `log.warn`, never passed to
- *   `onSkip`. Optional and purely a diagnostic hook — existing callers that omit it keep the
- *   exact prior behavior. `listEntries` below uses this to turn the skip into a hard build-time
- *   failure instead of a silent one.
+ * `onSkip` is called for every file that has a recognized content extension, does NOT match
+ * the `{type}.{slug}.{id}.{ext}` grammar (see `parseTypedFilename`), AND structurally looks
+ * like an attempted entry (see `looksLikeMalformedEntry`). A file that was never entry-shaped
+ * -- a `README.md`, a colocated sibling artifact -- is always dropped with a debug-gated
+ * `log.warn` and never passed to `onSkip`. Optional and purely diagnostic: `listEntries` uses
+ * it to turn the skip into a hard build-time failure instead of a silent one.
  */
 export declare const listCollectionEntries: (root: string, collection: FlatSchemaItem, onSkip?: (file: SkippedListingFile) => void) => Promise<CollectionListItem[]>;