canopycms 0.0.63 → 0.0.65

package/dist/content-listing.js

@@ -8,13 +8,13 @@ import path from 'node:path';
 import matter from 'gray-matter';
 import { parse as yamlParse } from 'yaml';
 import { findBodyFieldName } from './utils/body-field.js';
+import { computeEntryUrl } from './utils/entry-url.js';
 import { asRecord, getFormatExtension } from './utils/format.js';
 import { resolveCollectionPath } from './content-id-index.js';
 import { validateAndNormalizePath } from './paths/index.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
-import { isValidId } from './id.js';
-import { ContentStoreError } from './content-store.js';
+import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
 import { isBuildMode } from './build-mode.js';
 const log = createDebugLogger({ prefix: 'ContentListing' });
 /**
@@ -45,7 +45,17 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
             return asRecord(yamlParse(raw));
         }
         const parsed = matter(raw);
-        const data = parsed.data ?? {};
+        // Copy before writing the body in. gray-matter keeps a PROCESS-GLOBAL cache keyed by file
+        // content and hands every caller the same `data` object instance, so mutating it in place
+        // wrote the body into a shared object that later, unrelated `matter()` calls then saw as
+        // frontmatter. Concretely, before this copy: listing a collection that contains an md entry
+        // poisoned the cache, and a subsequent reference resolution to that same entry — which goes
+        // through `ContentStore.read()`, whose md branch calls `matter()` again — returned the body
+        // as a frontmatter field. So a resolved md snippet came back WITH `body` on a whole-site
+        // listing and WITHOUT it on one scoped past its own collection: the same entry, two shapes,
+        // decided by unrelated scoping. Regression coverage lives with the reference-resolution
+        // tests in content-listing.test.ts.
+        const data = { ...(parsed.data ?? {}) };
         if (parsed.content) {
             data[bodyFieldName] = parsed.content;
         }
@@ -58,87 +68,52 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
         return {};
     }
 };
+// `parseTypedFilename` now lives in utils/typed-filename.ts so dependency-light modules can
+// use it without importing this one (which pulls in ContentStore). Re-exported here because
+// this is where callers -- and `canopycms/server` -- have always imported it from.
+export { parseTypedFilename } from './utils/typed-filename.js';
+import { parseTypedFilename } from './utils/typed-filename.js';
+// ---------------------------------------------------------------------------
+// Reference resolution for batch listings
+// ---------------------------------------------------------------------------
 /**
- * Parse a Canopy content filename into its `{type}.{slug}.{id}.{ext}` parts.
+ * Build the `ContentStore` + shared cache that a batch listing resolves references through.
  *
- * ## Filename grammar
+ * 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.
  *
- * Every entry file on disk is named `{type}.{slug}.{id}.{ext}`:
- * - `type` — the entry type name (a key in the collection's `entries` config).
- * - `slug` — the entry's URL slug. May itself contain dots (e.g. a slug of
- *   `getting.started.guide`), so the type and ID anchor the split: the ID is
- *   always the second-to-last dot-separated segment, and the slug is
- *   everything between the type and the ID. The returned `slug` is
- *   lowercased.
- * - `id` — a 12-character Base58 content ID (`generateId()`/`isValidId()`).
- *   Base58 excludes the ambiguous characters `0`, `O`, `I`, `l` so IDs are
- *   unambiguous when read aloud or hand-transcribed. A filename whose
- *   would-be ID segment doesn't pass `isValidId` is rejected — the whole
- *   parse returns `null`, even if the rest of the shape looks right.
- * - `ext` — the format extension (`.md`, `.mdx`, `.json`, `.yaml`), stripped
- *   before parsing and not part of the returned result.
+ * 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.
  *
- * @param filename - The bare filename (no directory component). **This precondition is
- *   not enforced.** The parser splits purely on `.`, so a `/` or `\` you pass in is not
- *   rejected and is not treated as special — it becomes part of whichever segment it
- *   falls in, most often the `type` segment (e.g. `'foo/bar.slug.<validId>.md'` parses
- *   to `type: 'foo/bar'`). Strip any directory component yourself (e.g.
- *   `path.basename(filePath)`) before calling this — every internal caller already does.
- * @param entryTypes - When provided, the parsed `type` segment must match one
- *   of these entry types by name, or the parse is rejected (this is how
- *   `listCollectionEntries` filters out files that don't belong to the
- *   collection's configured entry types). Omit this argument to parse
- *   structurally without validating the type against a known list — useful
- *   for adopter code that needs to recover `{type, slug, id}` from a
- *   filename without having a schema/entry-types list on hand (e.g. a
- *   filesystem walk over content for tooling or diagnostics). Even without
- *   `entryTypes`, a leading-dot filename (dotfile, editor swap/backup file)
- *   is always rejected — an empty string is never a legal type, matching the
- *   `filename.startsWith('.')` guard `extractEntryTypeFromFilename` in
- *   `content-id-index.ts` already applies.
- * @returns `{ type, slug, id }`, or `null` if `filename` doesn't match the
- *   `{type}.{slug}.{id}.{ext}` shape (too few segments, no extension, a
- *   leading dot, an invalid ID, or — when `entryTypes` is given — an
- *   unrecognized type). `id` is validated (`isValidId`) and safe to trust. **`slug` is
- *   not** — it is the raw dot-joined middle segment(s), lowercased, cast to the branded
- *   `Slug` type without running `parseSlug`'s validation. A filename with an
- *   unconventional slug segment (e.g. containing a space) still parses and still
- *   receives the `Slug` brand. Callers that need a validated slug must run the result
- *   through `parseSlug` themselves; this function's contract is "split the filename
- *   grammar apart," not "validate every part."
+ * 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.
  */
-export const parseTypedFilename = (filename, entryTypes) => {
-    // Reject dotfiles outright (matching extractEntryTypeFromFilename's guard in
-    // content-id-index.ts): a leading dot can never be a legal entry type, and this
-    // is exactly the shape of the files a structural (no-entryTypes) parse would
-    // otherwise misparse -- e.g. '.hidden.file.aB3cD4eF5gH6.md' -> potentialType ''.
-    if (filename.startsWith('.'))
-        return null;
-    // Remove extension
-    const lastDot = filename.lastIndexOf('.');
-    if (lastDot === -1)
-        return null;
-    const nameWithoutExt = filename.slice(0, lastDot);
-    // Parse: {type}.{slug}.{id}
-    const parts = nameWithoutExt.split('.');
-    if (parts.length < 3)
-        return null;
-    const potentialType = parts[0];
-    // When a known-types list is supplied, the first segment must match one of
-    // them. Without it, any non-empty first segment is accepted as the type.
-    if (entryTypes && !entryTypes.some((e) => e.name === potentialType)) {
-        return null;
-    }
-    const id = parts[parts.length - 1];
-    if (!isValidId(id))
-        return null;
-    const slug = parts.slice(1, -1).join('.').toLowerCase();
+export const createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
+    store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
+    cache: createReferenceResolveCache(),
+});
+/**
+ * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
+ *
+ * Shared by `listEntries` and `buildContentTree` so both opt into resolution through one
+ * implementation. Each entry resolves against its OWN entry type's field list, since that is
+ * what says which fields are references at all; an entry whose type has no resolvable schema
+ * is returned untouched rather than guessed at.
+ */
+export const resolveCollectionItemReferences = async (items, collection, resolver) => Promise.all(items.map(async (item) => {
+    const fields = collection.entries?.find((e) => e.name === item.entryType)?.schema;
+    if (!fields)
+        return item;
     return {
-        type: potentialType,
-        slug: slug,
-        id: id,
+        ...item,
+        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache),
     };
-};
+}));
 /**
  * List all content entries as a flat array.
  *
@@ -165,7 +140,7 @@ export const parseTypedFilename = (filename, entryTypes) => {
  * @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)
+ * @param options - Listing options (extract, filter, rootPath, sort, resolveReferences)
  * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
 export async function listEntries(branchRoot, flatSchema, contentRootName, options, visibility) {
@@ -182,10 +157,21 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
     // data never reaches `extract` (let alone the returned items).
     const shouldInclude = visibility?.shouldInclude;
     const skippedFiles = [];
+    // One store + cache for the whole call, or nothing at all when the caller did not opt in.
+    // See the `resolveReferences` option for the cost this buys back.
+    const resolver = options?.resolveReferences
+        ? createReferenceResolver(branchRoot, flatSchema, contentRootName)
+        : null;
     const collectionResults = await Promise.all(collections.map(async (collection) => {
         const entries = await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file));
         const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
-        return visible.map((entry) => ({ entry, collection }));
+        // Resolve AFTER the visibility filter (a denied entry is never resolved, so its
+        // references cost nothing and leak nothing) and BEFORE the mapping below, so
+        // `extract` and `filter` both see resolved data — which is the entire point.
+        const resolved = resolver
+            ? await resolveCollectionItemReferences(visible, collection, resolver)
+            : visible;
+        return resolved.map((entry) => ({ entry, collection }));
     }));
     // Build-time only: fail loudly rather than silently shipping a build with a page missing. See
     // the build-time-only-failure note in this function's own doc comment above. Only files that
@@ -214,9 +200,17 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
                 ? entry.logicalPath.slice(contentPrefix.length)
                 : entry.logicalPath;
             const pathSegments = pathWithoutRoot.split('/').filter(Boolean);
-            // Compute urlPath: collapse index entries to parent collection path
-            const urlSegments = entry.slug === 'index' ? pathSegments.slice(0, -1) : pathSegments;
-            const urlPath = urlSegments.length > 0 ? `/${urlSegments.join('/')}`.toLowerCase() : '/';
+            // Compute urlPath (collapses an `index` entry to its parent collection path) through
+            // the SHARED rule rather than a local copy of it. A resolved reference now carries a
+            // `urlPath` too, and the whole point of that field is that it addresses the same entry
+            // this listing does, so the two must not be free to drift apart.
+            //
+            // One deliberate copy of this rule remains: `content-tree.ts`'s `defaultBuildPath`,
+            // which is exported for adopters to extend and also handles the collection case
+            // `computeEntryUrl` does not model. It agrees today; folding it in is tracked in
+            // `.claude/future-tasks/default-build-path-url-rule-copy.md`.
+            // `content-listing.test.ts` pins the listing-vs-resolved-reference agreement.
+            const urlPath = computeEntryUrl(entry.collectionPath, entry.slug, contentRootName);
             const raw = entry.data;
             const meta = {
                 entryPath: entry.logicalPath,
@@ -398,4 +392,3 @@ export const listCollectionEntries = async (root, collection, onSkip) => {
     }));
     return entries.filter((e) => e !== null);
 };
-//# sourceMappingURL=content-listing.js.map

package/dist/content-reader.d.ts

@@ -1,7 +1,7 @@
-import { type ContentId, type LogicalPath, type PhysicalPath, type Slug } from './paths';
-import type { CanopyServices } from './services';
-import type { BranchContext } from './types';
-import type { CanopyUser } from './user';
+import { type ContentId, type LogicalPath, type PhysicalPath, type Slug } from './paths/index.js';
+import type { CanopyServices } from './services.js';
+import type { BranchContext } from './types.js';
+import type { CanopyUser } from './user.js';
 export interface ContentReaderOptions {
     services: CanopyServices;
     basePathOverride?: string;
@@ -73,4 +73,3 @@ export interface ContentReader {
  * Falls back to creating the branch workspace (metadata + checkout) if missing.
  */
 export declare const createContentReader: (options: ContentReaderOptions) => ContentReader;
-//# sourceMappingURL=content-reader.d.ts.map

package/dist/content-reader.js

@@ -2,6 +2,7 @@ import { loadBranchContext, loadOrCreateBranchContext } from './branch-workspace
 import { ContentStore, ContentStoreError } from './content-store.js';
 import { resolveBranchPaths, } from './paths/index.js';
 import { trimSlashes } from './paths/normalize.js';
+import { isIndexSlug } from './utils/entry-url.js';
 import { isDeployedStatic, isBuildMode } from './build-mode.js';
 import { isNotFoundError } from './utils/error.js';
 import { resolveEntryLinksInData } from './entry-link-resolver.js';
@@ -86,7 +87,20 @@ export const createContentReader = (options) => {
         .join('/');
     // Build preview paths using simple path construction
     const contentRoot = trimSlashes(services.config.contentRoot ?? 'content');
-    const stripRoot = (val) => contentRoot && val.startsWith(`${contentRoot}/`) ? val.slice(contentRoot.length + 1) : val;
+    // The `val === contentRoot` branch matters as much as the prefix one: a root-level entry's
+    // collectionPath IS the content root, which does not start with `${contentRoot}/`, so without
+    // it the root index reported `path: '/content'` (and a root entry `/content/about`) -- paths
+    // that resolve to nothing. `computeEntryUrl` has always had both branches; this had one.
+    //
+    // Both branches stay guarded on `contentRoot` so an empty one passes the value through
+    // unchanged, exactly as `computeEntryUrl` does. Unreachable today (`contentRootSchema` is
+    // `relativePathSchema.default('content')` with `.min(1)`), but a blanket short-circuit would
+    // be the WRONG answer if it ever were reachable -- it would flatten every entry to root.
+    const stripRoot = (val) => contentRoot && val === contentRoot
+        ? ''
+        : contentRoot && val.startsWith(`${contentRoot}/`)
+            ? val.slice(contentRoot.length + 1)
+            : val;
     const buildEntryPath = (opts) => {
         // Construct preview path from collectionPath
         const stripped = stripRoot(opts.collectionPath);
@@ -95,7 +109,13 @@ export const createContentReader = (options) => {
             ? `${url}${url.includes('?') ? '&' : '?'}branch=${encodeURIComponent(opts.branch)}`
             : url;
         const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
-        const encodedSlug = encodeSlug(opts.slug);
+        // An index entry's URL is its COLLECTION's path. Without this collapse `path` handed back
+        // `/docs/index` for an entry advertised at `/docs` -- `resolveUrlPathCandidates`
+        // deliberately does not resolve the former, so a caller linking `path` linked to a 404.
+        // Same index decision as computeEntryUrl/listEntries/buildPreviewSrc, through the same
+        // predicate. NOTE this builder still keeps its own content-root strip and its own encoding
+        // rather than delegating wholesale -- see .claude/future-tasks/default-build-path-url-rule-copy.md.
+        const encodedSlug = isIndexSlug(opts.slug) ? '' : encodeSlug(opts.slug);
         const url = encodedSlug ? `${trimmed}/${encodedSlug}` : trimmed || '/';
         return appendBranch(url);
     };
@@ -196,4 +216,3 @@ export const createContentReader = (options) => {
     };
     return { read };
 };
-//# sourceMappingURL=content-reader.js.map

package/dist/content-store.d.ts

@@ -1,6 +1,6 @@
-import type { FlatSchemaItem, EntryTypeConfig } from './config';
-import { ContentIdIndex } from './content-id-index';
-import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths';
+import type { EntrySchema, FlatSchemaItem, EntryTypeConfig } from './config/index.js';
+import { ContentIdIndex } from './content-id-index.js';
+import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
 export type MarkdownDocument = {
     format: 'md' | 'mdx';
     data: Record<string, unknown>;
@@ -92,6 +92,25 @@ export declare class DuplicateContentIdError extends ContentConflictError {
     readonly paths: readonly string[];
     constructor(contentId: string, paths: readonly string[]);
 }
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
@@ -122,6 +141,46 @@ 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * ## Lifetime and invalidation
+ *
+ * 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`).
+ */
+export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown> | null>>;
+/** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
+export declare const createReferenceResolveCache: () => ReferenceResolveCache;
 export declare class ContentStore {
     private readonly root;
     /** See ContentStoreOptions.contentRootName — the ID index scan root. */
@@ -274,6 +333,15 @@ export declare class ContentStore {
      * existing entries lock on a per-slug create-key (createLockKey()).
      */
     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}
@@ -426,13 +494,72 @@ export declare class ContentStore {
         collection: LogicalPath;
         slug: Slug;
     }>>;
+    /**
+     * 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.
+     *
+     * **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.
+     */
+    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.
+     * 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.
+     */
+    private resolveSingleReference;
+    /**
      * Returns null if the reference is invalid or missing.
      * Includes id, slug, and collection fields for debugging.
      *
@@ -446,8 +573,12 @@ export declare class ContentStore {
      * 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 {@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.
      */
-    private resolveSingleReference;
+    private resolveSingleReferenceUncached;
     private resolveSingleReferenceOnce;
 }
-//# sourceMappingURL=content-store.d.ts.map