canopycms 0.0.67-int.90 → 0.0.67

package/dist/content-store.d.ts

@@ -52,38 +52,29 @@ export declare class ContentConflictError extends Error {
 }
 /**
  * [SYNC-C1] Thrown when a mutation could not take the branch's cross-host
- * content-write lock within its bounded wait -- in practice, the worker is
- * mid-rebase on this branch's working tree (utils/content-write-lock.ts).
+ * content-write lock within its bounded wait (utils/content-write-lock.ts) --
+ * usually the worker mid-rebase on this branch's working tree, though
+ * writer-vs-writer contention raises it too (see ContentWriteLockBusyError).
  *
- * A `ContentConflictError` subclass so every existing 409 mapping keeps
- * working unchanged; the distinct type exists so the API can surface THIS
- * message ("the branch is busy, retry") instead of the generic "modified by
- * another editor", which would be actively misleading. The default wording
- * covers writer-vs-writer contention too, which this lock also produces --
- * see ContentWriteLockBusyError.
+ * A `ContentConflictError` subclass so every 409 mapping keeps working; the
+ * distinct type lets the API surface THIS message ("the branch is busy, retry")
+ * instead of the misleading generic "modified by another editor".
  */
 export declare class BranchSyncingError extends ContentConflictError {
     constructor(message: string);
 }
 /**
- * [F1] Thrown when a save's content ID is carried by MORE THAN ONE file in
- * the branch's content tree -- the duplicate-ID state `ContentIdIndex`
- * quarantines (see its "Duplicate-ID quarantine" section).
+ * [F1] Thrown when a save's content ID is carried by MORE THAN ONE file in the branch's
+ * content tree -- the duplicate-ID state `ContentIdIndex` quarantines.
  *
- * Why refuse rather than write: with two files sharing one ID, "this entry"
- * is ambiguous, and every way of proceeding is worse than stopping.
- * Following the index would mutate (and, via the slug-change cleanup, DELETE)
- * a file the caller never addressed -- the data-loss bug this class exists to
- * prevent. Writing only the addressed file would succeed silently into a file
- * that is invisible to every ID-based lookup (reads-by-id, references,
- * listings all resolve to the OTHER copy) and that the repair action later
- * archives away, so the editor's work would appear to evaporate with no error
- * anywhere. Refusing mutates nothing under any interleaving, and says what is
- * wrong and who can fix it.
+ * Refuse rather than write: with two files sharing one ID "this entry" is ambiguous and every
+ * way of proceeding is worse. Following the index would DELETE (via the slug-change cleanup) a
+ * file the caller never addressed; writing only the addressed file would succeed into a file
+ * invisible to every ID-based lookup and later archived by the repair action, so the editor's
+ * work evaporates with no error anywhere. Refusing mutates nothing under any interleaving.
  *
- * A `ContentConflictError` subclass so every existing 409 mapping keeps
- * working; the distinct type exists so the API can surface THIS message
- * rather than the generic "modified by another editor", which would send the
+ * A `ContentConflictError` subclass so every 409 mapping keeps working; the distinct type lets
+ * the API surface THIS message rather than "modified by another editor", which would send the
  * editor into a reload-and-retry loop that cannot succeed.
  */
 export declare class DuplicateContentIdError extends ContentConflictError {
@@ -94,27 +85,22 @@ export declare class DuplicateContentIdError extends ContentConflictError {
 }
 /**
  * Thrown when a create or rename would give a SECOND entry a `urlPath` another entry already
- * holds -- the write-boundary half of the invariant `assertNoDuplicateUrlPaths` enforces at build
- * time (see url-collision.ts for which shapes count and, just as importantly, which do not).
+ * holds -- the write-boundary half of the invariant `assertNoDuplicateUrlPaths` enforces at
+ * build time (url-collision.ts says which shapes count and which deliberately do not).
  *
- * Why refuse rather than write: only one of the two entries can be served at that URL, so the
- * other silently has no route anywhere. Allowing the write trades a clear error now for a page
- * that quietly does not exist later -- and, because the loser is picked by resolver precedence
- * rather than by the author, not necessarily the page they were editing.
+ * Refuse rather than write: only one of the two can be served at that URL, so the other
+ * silently has no route anywhere -- and the loser is picked by resolver precedence rather than
+ * by the author, so not necessarily the page they were editing.
  *
- * A `ContentConflictError` subclass so every existing 409 mapping keeps working; the distinct
- * type exists so the API can surface THIS message rather than the generic "modified by another
- * editor", which would send the editor into a reload-and-retry loop that cannot succeed.
+ * A `ContentConflictError` subclass so every 409 mapping keeps working; the distinct type lets
+ * the API surface THIS message rather than the generic "modified by another editor".
  */
 export declare class UrlPathConflictError extends ContentConflictError {
     /** Absolute path of the entry already holding the contested URL. */
     readonly conflictingPath: string;
     constructor(message: string, conflictingPath: string);
 }
-/**
- * Get the default entry type from a collection's entries array.
- * Returns the entry marked as default, or the first one, or undefined if no entries.
- */
+/** The entry type marked `default`, else the first, else undefined. */
 export declare function getDefaultEntryType(entries: readonly EntryTypeConfig[] | undefined): EntryTypeConfig | undefined;
 export interface ContentStoreOptions {
     /**
@@ -126,21 +112,17 @@ export interface ContentStoreOptions {
     indexFreshnessIntervalMs?: number;
     /**
      * Directory name (relative to `root`) holding the content tree — i.e.
-     * `config.contentRoot`. The ID index scans from here, so an adopter with a
-     * non-default content root would otherwise get an index built from a
-     * directory that does not exist: empty, so every ID-based lookup (reference
-     * resolution, entry links, order cleanup, rename) silently misses while
-     * path-based reads keep working.
-     *
+     * `config.contentRoot`. The ID index scans from here, so a non-default content
+     * root would otherwise build the index from a directory that does not exist:
+     * empty, so every ID-based lookup (reference resolution, entry links, order
+     * cleanup, rename) silently misses while path-based reads keep working.
      * Defaults to 'content'.
      *
-     * ENFORCED BY LINT, not by the type. Omitting it is silent and data-shaped
-     * when wrong -- nothing throws, nothing logs, and only ID-addressed lookups
-     * miss -- so every production construction must pass it. That is checked by
-     * the `no-restricted-syntax` rule on `new ContentStore(...)` in
-     * eslint.config.mjs, which is scoped to non-test sources: making the field
-     * required in the TYPE would have forced the argument on 61 test call sites
-     * that legitimately want the default, for no gain in the 11 production ones.
+     * ENFORCED BY LINT, not by the type -- the `no-restricted-syntax` rule on
+     * `new ContentStore(...)` in eslint.config.mjs, scoped to non-test sources.
+     * Omitting it is silent and data-shaped when wrong, so every production
+     * construction must pass it; making the field required in the TYPE would force
+     * the argument on dozens of test call sites that legitimately want the default.
      */
     contentRootName?: string;
     /**
@@ -152,41 +134,25 @@ export interface ContentStoreOptions {
     contentWriteLockWaitMs?: number;
 }
 /**
- * Per-batch memo for reference resolution, keyed by content ID.
- *
- * Exists because a batch surface resolves the SAME reference over and over: a shared
- * block ("call to action", "promo card") referenced by 40 pages costs 40 separate
- * `read()`s of one small file in a single `listEntries()` pass, and a search-index build
- * over thousands of entries multiplies that. Pass one cache through a whole batch and
- * each distinct target is read once.
+ * Per-batch memo for reference resolution, keyed by content ID (plus `includeBody`).
  *
- * Values are the in-flight **promise**, not the settled value, so concurrent lookups
- * inside a `Promise.all` collapse onto one read rather than each starting their own —
- * the same in-flight dedup `ContentStore.indexBuild` uses for index rebuilds.
+ * A batch surface resolves the SAME reference over and over: a shared block referenced by 40
+ * pages costs 40 separate `read()`s of one small file in a single `listEntries()` pass. One
+ * cache per batch and each distinct target is read once.
  *
- * What is cached is the READ, not the object handed out: every occurrence receives its own
- * deep copy, so a caller mutating one resolved reference cannot rewrite it for the other 39
- * entries pointing at the same target. See `resolveSingleReference` for why that matters and
- * why it does not undo the saving.
+ * Values are the in-flight **promise**, so concurrent lookups inside a `Promise.all` collapse
+ * onto one read. What is cached is the READ, not the object handed out: every occurrence gets
+ * its own deep copy (see `resolveSingleReference`).
  *
- * ## Lifetime and invalidation
+ * Lifetime is one `listEntries()` / `buildContentTree()` call, with no invalidation -- strictly
+ * shorter than the `ContentStore` whose memoized `idIndex()` it sits on, so it adds no
+ * staleness window and is out of scope for the generation-marker protocol in
+ * `docs/concurrency.md`. Never make one module-global, persist one, or reuse one across
+ * requests.
  *
- * There is no invalidation, and that is the design: a cache lives inside a single
- * `listEntries()` / `buildContentTree()` call and is dropped when it returns. That is
- * strictly shorter than the lifetime of the `ContentStore` whose memoized `idIndex()` it
- * sits on top of, so it introduces no staleness window that store did not already have,
- * and it is out of scope for the generation-marker protocol in
- * `docs/concurrency.md` (which governs caches rebuilt by scanning that OUTLIVE the
- * mutations they can miss). Never make one module-global, never persist one, and never
- * reuse one across requests.
- *
- * Misses are memoized alongside hits, deliberately: one batch should be internally
- * coherent, and a shared block resolving to data on page 1 and to `null` on page 40 of
- * the same sitemap is worse than either consistent answer. The accepted cost is that a
- * later occurrence in the same batch can no longer get incidentally lucky after a
- * sibling lookup wins the stale-index refresh throttle. Each DISTINCT id still gets its
- * full self-healing retry, because that retry happens inside the memoized promise (see
- * `resolveSingleReference`).
+ * Misses are memoized alongside hits so one batch stays internally coherent: a shared block
+ * resolving to data on page 1 and `null` on page 40 of one sitemap is worse than either
+ * consistent answer. Each DISTINCT id still gets its full self-healing retry, inside the memo.
  */
 export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown> | null>>;
 /** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
@@ -218,20 +184,16 @@ export declare class ContentStore {
     constructor(root: string, flatSchema: FlatSchemaItem[], options?: ContentStoreOptions);
     /**
      * [SYNC-C1] Run a working-tree mutation under the branch's cross-host
-     * content-write lock (utils/content-write-lock.ts), on top of the
-     * in-process locks the callee takes for itself.
-     *
-     * The in-process mutex serializes writers inside ONE process; it says
-     * nothing about the EC2 worker rebasing this same tree on shared EFS, which
-     * destroys an in-flight save (`checkout --theirs` overwrites it and the
-     * rebase then reports success; `rebase --abort` hard-resets it). This is the
-     * layer that actually excludes the two.
+     * content-write lock (utils/content-write-lock.ts), on top of the in-process
+     * locks the callee takes for itself. The in-process mutex serializes writers
+     * inside ONE process and says nothing about the EC2 worker rebasing this same
+     * tree on shared EFS, which destroys an in-flight save.
      *
-     * Reads deliberately do NOT take it -- an extra EFS round-trip per read is
-     * not an acceptable cost, and reads cannot be destroyed by a rebase.
+     * Reads deliberately do NOT take it: an extra EFS round-trip per read is not an
+     * acceptable cost, and a rebase cannot destroy a read.
      *
-     * Acquisition order is always content lock -> `withLock`, never the reverse,
-     * so the two cannot deadlock.
+     * Acquisition order is always content lock -> `withLock`, never the reverse, so
+     * the two cannot deadlock.
      */
     private withContentWriteExclusion;
     /**
@@ -239,18 +201,16 @@ export declare class ContentStore {
      *
      * Called (via content-index-registry) after in-process operations that change the
      * working tree underneath this store — git checkout/merge/rebase, the worker's
-     * rebase loop, and sync-core's content replacement. Without this, ID→path lookups
-     * keep resolving to pre-mutation paths and saves can target moved/deleted files.
-     *
-     * Cheap: only bumps a generation counter; the rebuild happens lazily.
+     * rebase loop, sync-core's content replacement. Without it, ID→path lookups keep
+     * resolving to pre-mutation paths and saves can target moved/deleted files.
+     * Cheap: bumps a generation counter, the rebuild is lazy.
      */
     invalidateIndex(): void;
     /**
-     * Get the ID index, ensuring it's loaded and current first.
-     * Loads lazily on first access and rebuilds after invalidateIndex(); repeated
-     * accesses with no intervening invalidation reuse the already-built index,
-     * except for a throttled probe of the on-disk generation marker that detects
-     * mutations made by OTHER processes sharing this root (e.g. on EFS).
+     * The ID index, rebuilt first if stale. Loads lazily, rebuilds after
+     * invalidateIndex(), and otherwise reuses the built index apart from a throttled
+     * probe of the on-disk generation marker, which detects mutations by OTHER
+     * processes sharing this root (e.g. on EFS).
      */
     idIndex(): Promise<ContentIdIndex>;
     /**
@@ -260,157 +220,126 @@ export declare class ContentStore {
      */
     private shouldProbeDiskGeneration;
     /**
-     * After one of this store's own successful mutations: publish the change to
-     * other processes (bump the on-disk marker) and adopt the written token,
-     * since the in-memory index was already updated incrementally — avoiding a
-     * pointless self-rescan on the next probe. Adoption is skipped unless the
-     * index is quiescent and `updatedIndex` is still the live instance: if a
-     * rebuild raced with the mutation, its scan may predate our file change, so
-     * we leave the recorded token older and let the next probe observe our bump
-     * and trigger the healing rebuild.
+     * After one of this store's own successful mutations: publish it to other
+     * processes (bump the on-disk marker) and adopt the written token, since the
+     * in-memory index was already updated incrementally. Adoption is skipped unless
+     * the index is quiescent and `updatedIndex` is still the live instance: a rebuild
+     * that raced the mutation may have scanned before our file change, so leaving the
+     * recorded token older lets the next probe observe our bump and heal.
      */
     private recordOwnMutation;
     /**
-     * Backstop for the residual staleness windows of the cross-process marker
-     * (NFS attribute caching, probe throttle, self-adoption — see
-     * content-index-generation.ts): force one rebuild in response to a
-     * suspicious lookup (an ID miss, or an index hit whose file is gone), but
-     * throttle how often a caller can force one. Time-boxed so genuinely
-     * dangling IDs cost at most one rescan per window. Returns true if a
-     * refresh was performed by THIS call; callers that lose the throttle race
-     * still benefit — idIndex() dedupes concurrent builds, so a caller that won
-     * the race rebuilds the index for everyone, and callers should still retry
-     * their lookup against the live index regardless of this return value.
+     * Backstop for the residual staleness windows of the cross-process marker (NFS
+     * attribute caching, probe throttle, self-adoption — see
+     * content-index-generation.ts): force one rebuild in response to a suspicious
+     * lookup (an ID miss, or an index hit whose file is gone), throttled so a
+     * genuinely dangling ID costs at most one rescan per window. Returns true only if
+     * THIS call refreshed; a caller that loses the throttle race must still retry its
+     * lookup, since idIndex() dedupes concurrent builds and the winner rebuilds for
+     * everyone.
      */
     private refreshIndexForSuspiciousLookup;
     /**
-     * Every file in `dir` whose filename embeds `id`, as root-relative paths
-     * (empty when there is no such file, or no such dir).
+     * Every file in `dir` whose filename embeds `id`, as root-relative paths (empty
+     * when there is no such file, or no such dir).
      *
-     * [F1] Returns ALL matches, not the first: more than one match is a
-     * duplicate-ID pair, and callers must be able to tell that apart from a
-     * clean single hit rather than silently picking whichever one `readdir()`
-     * happened to yield first.
+     * [F1] Returns ALL matches, not the first: more than one match is a duplicate-ID
+     * pair, and callers must be able to tell that apart from a clean single hit rather
+     * than silently picking whichever one `readdir()` happened to yield first.
      */
     private findEntryPathsById;
-    /**
-     * Get all schema items for iteration.
-     * Used internally by ReferenceResolver for path matching.
-     */
     getSchemaItems(): IterableIterator<FlatSchemaItem>;
     private assertSchemaItem;
     /**
      * Is this path a COLLECTION schema item?
      *
      * The non-throwing form of `assertCollection`, reading the same `schemaIndex` -- which is the
-     * point. A caller that gates on this cannot disagree with what `buildPaths` will then do: the
-     * Map is last-wins, so where a subcollection's path collides with a parent's entry-type name
-     * both this and `buildPaths` see the collection. A `find` over the flat schema LIST is
-     * first-wins and would not.
+     * point: a caller that gates on this cannot disagree with what `buildPaths` will then do,
+     * because the Map is last-wins where a subcollection's path collides with a parent's
+     * entry-type name. A `find` over the flat schema LIST is first-wins and would not.
      *
-     * Type-only, deliberately -- `resolvePath` additionally requires `entries`, but a collection
-     * with subcollections and no entries of its own is legal, and mirroring that stricter test here
-     * would reject something `buildPaths` accepts.
+     * Type-only, deliberately: `resolvePath` additionally requires `entries`, but a collection
+     * with subcollections and no entries of its own is legal, and testing for that here would
+     * reject something `buildPaths` accepts.
      *
      * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
-     * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+     * `urlAddressableOnly`.
      */
     isCollectionPath(collectionPath: LogicalPath): boolean;
     /**
      * Does this collection declare `entryTypeName` in its `entries` config?
      *
-     * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries` decides
-     * whether a file on disk is one of the collection's entries at all. `buildPaths`' own directory
-     * scan deliberately does NOT check this -- it matches on slug alone, so that an entry whose type
-     * was renamed out of the schema stays findable and therefore still editable, renameable and
-     * deletable. Only URL resolution consults this, so what enumeration hides is not served.
+     * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries`
+     * decides whether a file on disk is one of the collection's entries at all. `buildPaths`'
+     * own directory scan deliberately does NOT check this -- it matches on slug alone, so an
+     * entry whose type was renamed out of the schema stays findable and therefore editable,
+     * renameable and deletable. Only URL resolution consults this, so what enumeration hides is
+     * not served.
      *
-     * Returns FALSE when the collection declares no `entries` at all, which is stricter than
-     * `parseTypedFilename`'s own `if (entryTypes && ...)` guard and deliberately so: the enumerating
-     * surface is not `parseTypedFilename`, it is `listCollectionEntries`, and that returns `[]`
-     * outright for a collection with no `entries`. A collections-only container therefore publishes
-     * nothing, so a URL read that resolved a file sitting in one would be answering where nothing is
-     * advertised -- the exact disagreement this predicate exists to close. Such a file cannot have
-     * been created by the CMS (there is no entry type to create it as); it arrived by hand, by merge
-     * or by retrofit, and it is invisible to the sitemap and to static params either way.
+     * Returns FALSE when the collection declares no `entries` at all -- stricter than
+     * `parseTypedFilename`'s own guard, and deliberately so: the enumerating surface is
+     * `listCollectionEntries`, which returns `[]` outright for such a collection, so a URL read
+     * resolving a file sitting in one would answer where nothing is advertised.
      *
-     * Returns true for a path that is not a collection at all, because that is rule 1's question,
-     * not this one's -- and under `urlAddressableOnly` rule 1 has already rejected it.
+     * Returns true for a path that is not a collection at all, because that is rule 1's
+     * question, and under `urlAddressableOnly` rule 1 has already rejected it.
      */
     declaresEntryType(collectionPath: LogicalPath, entryTypeName: string): boolean;
     private assertCollection;
     /**
-     * Lock key for an existing entry, addressed by its permanent content ID
-     * (stable across renames -- the whole point of this locking scheme; see
-     * .claude/future-tasks/resolved/content-store-lock-key.md). Namespaced by store
-     * root: the same content ID exists in every clone of a branch, and one
-     * process can hold ContentStore instances on several clones (dev
-     * workspace roots, prod branch clones) at once, so the root prefix keeps
-     * the keyspace scoped per-store. It also keeps this ID keyspace disjoint
-     * from other modules' raw-path-keyed locks sharing the same withLock()
-     * map (comment-store, branch-metadata, etc).
+     * Lock key for an existing entry, addressed by its permanent content ID --
+     * stable across renames, which is the whole point of this locking scheme.
+     * Namespaced by store root: the same content ID exists in every clone of a
+     * branch and one process can hold stores on several clones at once, so the
+     * prefix scopes the keyspace per store and keeps it disjoint from other
+     * modules' raw-path-keyed locks sharing the same withLock() map.
      */
     private idLockKey;
     /**
-     * Stable collection+slug identifier for lock-key namespacing. Mirrors the
-     * schemaItem resolution buildPaths() performs for entry-type delegation:
-     * an entry-type item delegates to its parent collection with the slug
-     * defaulting to the entry type's own name (see buildPaths()'s
-     * `schemaItem.type === 'entry-type'` branch).
+     * Stable collection+slug identifier for lock-key namespacing. Mirrors
+     * buildPaths()' entry-type delegation: an entry-type item delegates to its
+     * parent collection with the slug defaulting to the entry type's own name.
      */
     private collectionSlugKey;
     /**
      * Lock key for a not-yet-existing entry (a create). Serializes concurrent
-     * same-slug creates WITHIN this process: the second call's in-lock
-     * buildPaths() re-resolution will find the first call's just-written file
-     * and fold in as an edit (see write()). A concurrent create racing from a
-     * DIFFERENT process is NOT covered by this in-process mutex -- accepted
-     * per the epic's design review: each writer mints its own fresh ID and
-     * writes its own distinct filename, so both writes succeed and the result
-     * is two same-slug files with different IDs (a slug-uniqueness violation
-     * surfaced on the next listing/lookup), never a duplicate-ID collision
-     * that would poison index rebuilds.
+     * same-slug creates WITHIN this process: the second call's in-lock buildPaths()
+     * re-resolution finds the first call's just-written file and folds in as an edit.
+     *
+     * A create racing from a DIFFERENT process is NOT covered by this in-process
+     * mutex, and that is accepted: each writer mints its own fresh ID and filename, so
+     * both writes succeed and the result is two same-slug files with different IDs (a
+     * slug-uniqueness violation surfaced on the next listing/lookup), never a
+     * duplicate-ID collision that would poison index rebuilds.
      */
     private createLockKey;
     /**
-     * Lock key for a write()/delete() pre-pass classification. Existing
-     * entries lock on their content ID (idLockKey()). Legacy entries with no
-     * embedded ID (pre-ID-era filenames -- renameEntry() already refuses to
-     * touch these, via its four-part filename check, so there is no rename
-     * race to guard against for them) fall back to the physical path, matching
-     * this store's original locking behavior for that narrow case. Not-yet-
-     * existing entries lock on a per-slug create-key (createLockKey()).
+     * Lock key for a write()/delete() pre-pass classification: an existing entry
+     * locks on its content ID (idLockKey()), a not-yet-existing one on a per-slug
+     * create-key (createLockKey()). An entry with no embedded ID falls back to its
+     * physical path -- renameEntry() refuses to touch those (its four-part filename
+     * check), so they have no rename race to guard against.
      */
     private entryLockKey;
     /**
      * Refuse a create/rename that would give a second entry a `urlPath` another entry already
      * holds. See url-collision.ts for the two shapes that count, and the legitimate
      * landing-page-beside-a-collection shape that deliberately does not.
-     *
-     * @param collectionDir Absolute physical directory the entry will live in.
-     * @param slug The entry's slug, as it will be written.
      */
     private assertUrlPathAvailable;
     /**
-     * Build absolute and relative paths with security validation.
-     * All entries use the unified filename pattern: {type}.{slug}.{id}.{ext}
-     *
-     * SECURITY BOUNDARY: This method prevents path traversal attacks by:
-     * 1. Validating that resolved paths stay within the content root
-     * 2. Checking slugs for malicious patterns (via validateSlug)
-     * 3. Using path.resolve to normalize paths before validation
+     * Build absolute and relative paths for an entry, filename pattern
+     * `{type}.{slug}.{id}.{ext}`. `options.existingId` addresses a known entry; without it a
+     * new ID is generated. `options.entryTypeName` picks among a collection's entry types,
+     * defaulting to its default one.
      *
-     * This validation is performed BEFORE file I/O in resolveDocumentPath(),
-     * ensuring permission checks happen before any file system access.
-     *
-     * @param options.existingId - Optional ID to use (for edits). If not provided, generates new ID.
-     * @param options.entryTypeName - For collections with multiple entry types, specify which one to use. Defaults to the default entry type.
+     * SECURITY BOUNDARY against path traversal: resolved paths must stay inside the content
+     * root, slugs go through `validateSlug`, and everything is `path.resolve`d before those
+     * checks. All of it runs BEFORE any file I/O in resolveDocumentPath(), so permission checks
+     * happen before filesystem access.
      */
     private buildPaths;
-    /**
-     * Path resolution: resolves a URL path to a schema item
-     * - Try as collection + slug (last segment = slug)
-     */
+    /** Resolve path segments to a collection schema item plus the trailing slug. */
     resolvePath(pathSegments: string[]): {
         schemaItem: FlatSchemaItem;
         slug: Slug;
@@ -420,21 +349,17 @@ export declare class ContentStore {
         relativePath: PhysicalPath;
         id?: string;
         /**
-         * Always populated for a valid schema item: the collection branch below
-         * always resolves a name (falling back to `'entry'` when the collection
-         * has no matching/default entry type config), and the entry-type branch
-         * delegates to it with its own name set explicitly. Only non-collection,
-         * non-entry-type schema items (impossible via the public API, which only
-         * ever resolves to one of those two) skip both branches, hitting the
-         * throw below instead of returning at all.
+         * Always populated for a valid schema item: the collection branch below resolves a name
+         * (falling back to `'entry'` when the collection has no matching/default entry type
+         * config) and the entry-type branch delegates to it with its own name. Anything else
+         * throws below rather than returning.
          */
         entryTypeName: string;
         /**
-         * True if this slug already had a file on disk (a directory-scan finding,
-         * or `options.existingId` asserting one) -- i.e. this resolution is an
-         * edit, not a create. Used by write()/delete()/renameEntry() to pick a
-         * stable lock key (see entryLockKey()); NOT the same as `id` being set,
-         * since a brand-new entry also gets an `id` (freshly generated below).
+         * True if this slug already had a file on disk (the directory scan found one, or
+         * `options.existingId` asserts one) -- i.e. this resolution is an edit, not a create.
+         * write()/delete()/renameEntry() use it to pick a stable lock key (see entryLockKey()).
+         * NOT the same as `id` being set: a brand-new entry also gets an `id`, generated below.
          */
         existed: boolean;
     }>;
@@ -453,7 +378,6 @@ export declare class ContentStore {
     readById(id: ContentId): Promise<ContentDocument | null>;
     private readByIdOnce;
     /**
-     * Get the ID for an entry given its collection and slug.
      * Returns null if no ID exists yet.
      */
     getIdForEntry(collectionPath: LogicalPath, slug: Slug): Promise<ContentId | null>;
@@ -464,80 +388,60 @@ export declare class ContentStore {
      */
     documentExists(collectionPath: LogicalPath, slug?: Slug | ''): Promise<boolean>;
     /**
-     * Resolve the actual on-disk entry type of an existing collection entry, by
-     * inspecting its filename directly. Entry filenames embed their type
-     * (`{type}.{slug}.{id}.{ext}`) and it is immutable after creation — see the
-     * existing-file lookup in buildPaths(), which this mirrors. Returns
-     * undefined if no entry exists yet at this slug.
+     * The on-disk entry type of an existing collection entry, read from its filename
+     * (`{type}.{slug}.{id}.{ext}`), which is immutable after creation -- mirroring the
+     * existing-file lookup in buildPaths(). Undefined if no entry exists yet at this slug.
      *
-     * Used at the API write boundary (api/content.ts) to validate an existing
-     * entry's payload against ITS real schema rather than a caller-supplied (or
-     * omitted/spoofed) `entryType` param — ContentStore.write() preserves the
-     * on-disk type regardless of what's requested, so validation must agree
-     * with what will actually be written (post-review M2).
+     * The API write boundary (api/content.ts) validates an existing entry's payload against ITS
+     * real schema rather than a caller-supplied (or omitted, or spoofed) `entryType` param:
+     * ContentStore.write() preserves the on-disk type regardless of what is requested, so
+     * validation must agree with what will actually be written.
      *
-     * Cheap: one buildPaths() resolution plus a stat, no file content is read —
-     * same cost class as documentExists().
+     * Cheap: one buildPaths() resolution plus a stat, no file content is read.
      */
     getExistingEntryType(collectionPath: LogicalPath, slug?: Slug | ''): Promise<string | undefined>;
     /**
-     * Count existing entries of a given entry type in a collection, by filename
-     * (entry filenames embed their type: `{type}.{slug}.{id}.{ext}`). Used to
-     * enforce `EntryTypeConfig.maxItems` server-side at the create boundary.
+     * Count existing entries of a given entry type in a collection, by filename (entry
+     * filenames embed their type: `{type}.{slug}.{id}.{ext}`). Enforces
+     * `EntryTypeConfig.maxItems` server-side at the create boundary.
      */
     countEntriesOfType(collectionPath: LogicalPath, entryTypeName: string): Promise<number>;
     /**
-     * Test-only seam: awaited right after the pre-pass buildPaths() resolves
-     * in delete() and renameEntry(), before the lock key is used to acquire
-     * anything. No-op in production. A test subclass can override this to
-     * inject a controlled pause in that exact window, letting a test
-     * deterministically run OTHER mutations (which don't hold this call's
-     * not-yet-acquired lock) to completion before this call proceeds to
-     * acquire its (possibly now-stale) lock key -- see the "Deterministic
-     * interleavings" testing pattern in docs/concurrency.md and
-     * branch-registry.test.ts's `BlockingRegistry` for the same idiom.
+     * Test-only seam: awaited right after the pre-pass buildPaths() resolves in delete() and
+     * renameEntry(), while neither has yet acquired a lock. No-op in production. A test subclass
+     * overrides it to pause in that exact window and run OTHER mutations to completion, making
+     * the stale-lock-key path deterministic -- see the "Deterministic interleavings" testing
+     * pattern in docs/concurrency.md and branch-registry.test.ts's `BlockingRegistry`.
      */
     protected afterPrePassForTesting(): Promise<void>;
-    /**
-     * Delete an entry and remove it from the index.
-     */
+    /** Delete an entry and remove it from the index. */
     delete(collectionPath: LogicalPath, slug: Slug): Promise<void>;
     /**
      * Rename an entry by changing its slug (middle segment of filename).
      * Entry filename pattern: {entryTypeName}.{slug}.{id}.{ext}
-     *
-     * @param collectionPath - Logical path to the collection
-     * @param currentSlug - Current slug of the entry
-     * @param newSlug - New slug (must be unique within collection)
-     * @returns Object with new logical path
-     * @throws ContentStoreError if entry doesn't exist, new slug conflicts, or validation fails
      */
     renameEntry(collectionPath: LogicalPath, currentSlug: Slug, newSlug: Slug): Promise<{
         newPath: LogicalPath;
     }>;
-    /**
-     * List all entries in a collection tree (including subcollections).
-     * For example, passing 'content/data-catalog' returns entries from
-     * 'content/data-catalog', 'content/data-catalog/partner-a', etc.
-     * Returns array of entry metadata (relativePath, collection, slug).
-     * Returns empty array if the collection doesn't exist.
-     */
     /**
      * Resolve a schema collection referenced by name or logical path.
      *
-     * Accepts either a full logical path ("content/authors") or a bare
-     * collection name ("authors") — the contract reference fields use for
-     * `collections: [...]` (see README). This is the single normalization
-     * point shared by reference-option loading and reference validation so
-     * the dropdown and the write boundary can never disagree.
+     * Accepts a full logical path ("content/authors") or a bare collection name ("authors") --
+     * the contract reference fields use for `collections: [...]` (see README). The single
+     * normalization point shared by reference-option loading and reference validation, so the
+     * dropdown and the write boundary can never disagree.
      *
-     * CAVEAT: the bare-name fallback matches on the LAST path segment and
-     * returns the first hit in schema order — with two collections sharing a
-     * leaf name (e.g. content/blog/posts and content/news/posts), a bare
-     * 'posts' is ambiguous. Use the full logical path in schemas that nest
-     * same-named collections.
+     * CAVEAT: the bare-name fallback matches on the LAST path segment and returns the first hit
+     * in schema order, so with two collections sharing a leaf name (content/blog/posts,
+     * content/news/posts) a bare 'posts' is ambiguous. Use the full logical path in schemas that
+     * nest same-named collections.
      */
     resolveCollectionItem(collectionPath: string): FlatSchemaItem | undefined;
+    /**
+     * Every entry in a collection tree, including subcollections: 'content/data-catalog'
+     * returns entries from it and from 'content/data-catalog/partner-a' and so on. Empty when
+     * the collection does not exist.
+     */
     getCollectionEntryPaths(collectionPath: LogicalPath): Promise<Array<{
         relativePath: PhysicalPath;
         collection: LogicalPath;
@@ -546,87 +450,57 @@ export declare class ContentStore {
     /**
      * Resolve every `reference` field in `data` against `fields`, returning a copy.
      *
-     * This is what `read()` applies automatically (unless `resolveReferences: false`), exposed
-     * so BATCH surfaces can opt into the same resolution without duplicating the walk: the
-     * listing primitives in content-listing.ts and content-tree.ts read entry files straight
-     * off disk and never touch this store, so before this existed a `reference` field reached
-     * `listEntries()`/`buildContentTree()` callers as a bare id string or `null`.
-     *
-     * Pass one {@link ReferenceResolveCache} across a whole batch so a target referenced by
-     * many entries is read once rather than once per referencing entry. Omit `cache` and the
-     * behavior is exactly what `read()` has always done, unmemoized.
+     * What `read()` applies automatically (unless `resolveReferences: false`), exposed so BATCH
+     * surfaces can opt into the same resolution without duplicating the walk: the listing
+     * primitives in content-listing.ts and content-tree.ts read entry files straight off disk
+     * and never touch this store. Pass one {@link ReferenceResolveCache} across a whole batch so
+     * a target referenced by many entries is read once; omit `cache` for exactly `read()`'s
+     * unmemoized behavior.
      *
-     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's
-     * own `read()`, below the per-entry permission check in content-reader.ts — so a resolved
-     * target may be an entry the caller could not `read()` directly. That is pre-existing
-     * `read()` behavior, matched here on purpose so one rule covers both; see the
-     * `resolveReferences` option in content-listing.ts for the note adopters see.
+     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's own
+     * `read()`, below the per-entry permission check in content-reader.ts, so a resolved target
+     * may be an entry the caller could not `read()` directly -- pre-existing `read()` behavior,
+     * matched here on purpose so one rule covers both.
      */
     resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache): Promise<Record<string, unknown>>;
-    /**
-     * Recursively resolve reference fields in data.
-     * This traverses objects, arrays, and blocks to find and resolve all reference fields.
-     */
     private resolveReferencesInData;
     /**
-     * Resolve a single reference ID to full entry data, memoized when a batch cache is
-     * supplied. Without a cache this is a straight pass-through to the uncached path, so
-     * `read()` behaves exactly as it always has.
-     *
-     * Every occurrence gets its OWN deep copy, even on a cache hit. Without that, the memo
-     * would hand one shared object to all 40 entries referencing the same block — a mutation
-     * in one caller's `extract` (truncating a body for a search index, deleting a field) would
-     * silently rewrite it for every sibling, and both `list: true` elements of `[id, id]` would
-     * be the same instance. The copy is what keeps the cache a pure performance optimization
-     * instead of a semantic change.
-     *
-     * Note the uncached path is NOT the clean baseline it looks like. For a json/yaml target it
-     * genuinely reparses fresh per occurrence, but for md/mdx gray-matter serves `data` from a
-     * process-global content-keyed cache, so `resolveSingleReferenceOnce`'s top-level spread
-     * severs exactly one level and NESTED frontmatter objects alias across occurrences, calls and
-     * requests. That is pre-existing `read()` behavior and out of scope here — deliberately, since
-     * touching it would change `read()` — but it means the cached path is the safer of the two,
-     * not a relaxation of a guarantee the uncached one provides. See
-     * `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
-     *
-     * What the copy costs, measured rather than assumed (2000 occurrences of one target, local
-     * disk, so every read hits the page cache — the friendliest possible case for NOT caching):
-     * a snippet-sized target is ~63x cheaper to clone than to re-read-and-parse, while a 265KB
-     * JSON target is ~0.8x, i.e. cloning is marginally SLOWER than reparsing it. So the win is
-     * large in the case this exists for and roughly a wash at the pathological end, never a
-     * blow-up. Two things keep the bad end narrow: an md/mdx target resolves to its FRONTMATTER
-     * only *unless the field sets `includeBody`* (`read()` puts the body on `doc.body`, which
-     * `resolveSingleReferenceOnce` spreads in only for an embedding field), so by default body
-     * size is irrelevant no matter how long the document and only a genuinely huge JSON/YAML
-     * target reaches the wash. **`includeBody: true` is the case that CAN reach it on markdown**:
-     * the body then sits inside the memoized object and is cloned once per referencing entry, so
-     * a long document embedded by many pages pays that repeatedly — the reason `includeBody`
-     * exists as an opt-in per field rather than as resolution's default. And in the deployment this
-     * targets, content lives on EFS/NFS where the syscall the memo removes dominates parse and
-     * clone alike, which the local-disk numbers above understate badly. Correctness is the
-     * reason for the copy regardless; the numbers are here so nobody has to re-derive them
-     * before touching this.
+     * Resolve a single reference ID to full entry data, memoized when a batch cache is supplied.
+     * Without a cache this is a straight pass-through, so `read()` behaves as it always has.
+     *
+     * Every occurrence gets its OWN deep copy, even on a cache hit. Without that, the memo would
+     * hand one shared object to all 40 entries referencing the same block -- a mutation in one
+     * caller's `extract` would silently rewrite it for every sibling, and both `list: true`
+     * elements of `[id, id]` would be the same instance. The copy is what keeps the cache a pure
+     * performance optimization instead of a semantic change.
+     *
+     * The uncached path is NOT the clean baseline it looks like: for md/mdx, gray-matter serves
+     * `data` from a process-global content-keyed cache, so `resolveSingleReferenceOnce`'s
+     * top-level spread severs exactly one level and NESTED frontmatter objects alias across
+     * occurrences, calls and requests. Pre-existing `read()` behavior, deliberately out of scope
+     * here; see `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
+     *
+     * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
+     * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
+     * 265KB JSON target ~0.8x -- a wash at the pathological end, never a blow-up, and on the
+     * EFS/NFS this targets the syscall the memo removes dominates both. An md/mdx target
+     * resolves to its FRONTMATTER unless the field sets `includeBody`, which is why
+     * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
+     * cloned once per referencing entry.
      */
     private resolveSingleReference;
     /**
-     * Returns null if the reference is invalid or missing.
-     * Includes id, slug, and collection fields for debugging.
+     * Returns null if the reference is invalid or missing. Includes id, slug and collection.
      *
-     * Suspicious results (ID missing from the index, or an index hit whose file
-     * is gone) trigger one forced index refresh and a retry — self-healing for
-     * mutations by other processes inside the marker's residual windows. The
-     * forced refresh itself is throttled (see refreshIndexForSuspiciousLookup),
-     * but the retry against the live index always runs regardless of whether
-     * this call won the throttle race: when a `list: true` reference array is
-     * resolved via Promise.all, every miss shares the same stale snapshot, and
-     * idIndex() dedupes concurrent builds — so a sibling call that wins the
-     * throttle and rebuilds heals every other miss in the same batch, not just
-     * the first.
+     * A suspicious result (ID missing from the index, or an index hit whose file is gone)
+     * triggers one forced index refresh and a retry — self-healing for mutations by other
+     * processes inside the marker's residual windows. The forced refresh is itself throttled
+     * (see refreshIndexForSuspiciousLookup) but the retry against the live index always runs:
+     * every miss in a `list: true` Promise.all shares one stale snapshot, and idIndex() dedupes
+     * concurrent builds, so a sibling that wins the throttle heals the whole batch.
      *
-     * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every
-     * distinct id still runs the full refresh-and-retry above. What a cache changes
-     * is only that repeats of the SAME id in one batch share that one attempt's
-     * outcome instead of each getting an independent throw of the dice.
+     * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every distinct id
+     * still runs the full refresh-and-retry; a cache only makes repeats of the SAME id share it.
      */
     private resolveSingleReferenceUncached;
     private resolveSingleReferenceOnce;