canopycms 0.0.53 → 0.0.55

package/dist/content-index-generation.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomicWriteFile } from './utils/atomic-write.js';
+import { getErrorMessage, isNodeError } from './utils/error.js';
+import { invalidateContentIndexesForRoot } from './content-index-registry.js';
+import { createDebugLogger } from './utils/debug.js';
+/**
+ * Cross-process ContentId index generation marker.
+ *
+ * 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:
+ * `.canopy-meta/` is the established per-clone internal dir — dot-prefixed (so
+ * content and index scans skip it) and excluded from git via .git/info/exclude.
+ *
+ * ## Why a random token instead of a monotonic counter
+ *
+ * Readers only need "did it change since I captured it", so inequality against
+ * the captured value suffices. A counter would need read-modify-write, which
+ * silently loses concurrent bumps without a lock (two bumpers read 5, both
+ * write 6 — a reader that recorded 6 after the first bump never learns of the
+ * second mutation). A unique token per bump has no lost-update problem, needs
+ * no lock, and avoids NFS mtime-granularity / cross-host clock-skew issues.
+ * Each bump is a single atomic temp-file + rename.
+ *
+ * ## Ordering protocol (correctness)
+ *
+ * - Bumpers write the marker strictly AFTER their filesystem mutations.
+ * - Readers capture the marker token strictly BEFORE scanning the tree, and
+ *   record it only after the scan completes. A bump landing mid-scan therefore
+ *   leaves the recorded token older than the file, forcing a rebuild on the
+ *   next probe.
+ *
+ * ## Consistency guarantees and residual staleness windows (EFS/NFSv4)
+ *
+ * Guaranteed: any completed mutation that bumps the marker is observed by every
+ * store on that root at its next freshness probe. Residual windows, all bounded
+ * in practice by per-request ContentStore lifetimes and self-healed by the
+ * suspicious-lookup backstop in ContentStore:
+ *
+ * - (A) NFS attribute caching (benign direction): another host may not see a
+ *   new marker for up to the attribute-cache timeout (~3-60s on default EFS
+ *   mounts; `noac` cannot be assumed). 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 (malignant direction, cross-host only): NFS
+ *   revalidates the marker file on open, but a rebuild's readdir calls may be
+ *   served from dentry/attribute caches — a scan can record a NEW token against
+ *   PRE-mutation directory listings, leaving that store confidently stale until
+ *   the next bump. Structurally unfixable with a filesystem marker; bounded by
+ *   per-request store lifetimes and the backstop.
+ *
+ * Wrong-file WRITE corruption (recreating a concurrently renamed entry →
+ * duplicate IDs) is prevented independently of this marker by the existence
+ * guard in ContentStore.write(), which consults the actual directory listing
+ * before recreating a missing expected file.
+ */
+const log = createDebugLogger({ prefix: 'ContentIndex' });
+/** Matches BRANCH_META_DIR in branch-metadata.ts — the per-clone internal dir. */
+const META_DIR = '.canopy-meta';
+const GENERATION_FILE = 'content-index.generation';
+/** Absolute path of the generation marker for a branch-clone root. */
+export function contentIndexGenerationPath(root) {
+    return path.join(path.resolve(root), META_DIR, GENERATION_FILE);
+}
+/**
+ * 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).
+ */
+export async function bumpContentIndexGeneration(root) {
+    const token = randomUUID();
+    try {
+        await atomicWriteFile(contentIndexGenerationPath(root), token);
+        return token;
+    }
+    catch (err) {
+        log.warn('generation', `Failed to bump content index generation for ${root}`, {
+            error: getErrorMessage(err),
+        });
+        return 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.
+ */
+export async function readContentIndexGeneration(root) {
+    try {
+        return await fs.readFile(contentIndexGenerationPath(root), 'utf-8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return null;
+        log.warn('generation', `Failed to read content index generation for ${root}`, {
+            error: getErrorMessage(err),
+        });
+        return null;
+    }
+}
+/**
+ * The single entry point for operations that mutate indexed files under a
+ * branch-clone root: git working-tree mutations, content sync, collection
+ * directory operations, CLI sync. Bumps the on-disk marker (cross-process),
+ * then invalidates in-process registered stores.
+ *
+ * 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.
+ */
+export async function invalidateContentIndexesDurable(root) {
+    await bumpContentIndexGeneration(root);
+    invalidateContentIndexesForRoot(root);
+}
+//# sourceMappingURL=content-index-generation.js.map

package/dist/content-index-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-index-generation.js","sourceRoot":"","sources":["../src/content-index-generation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACjC,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAA;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,MAAM,GAAG,GAAG,iBAAiB,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;AAEzD,kFAAkF;AAClF,MAAM,QAAQ,GAAG,cAAc,CAAA;AAC/B,MAAM,eAAe,GAAG,0BAA0B,CAAA;AAElD,sEAAsE;AACtE,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAA;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAAY;IAC3D,MAAM,KAAK,GAAG,UAAU,EAAE,CAAA;IAC1B,IAAI,CAAC;QACH,MAAM,eAAe,CAAC,0BAA0B,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAA;QAC9D,OAAO,KAAK,CAAA;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,+CAA+C,IAAI,EAAE,EAAE;YAC5E,KAAK,EAAE,eAAe,CAAC,GAAG,CAAC;SAC5B,CAAC,CAAA;QACF,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAAY;IAC3D,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAA;IACrE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QAC1D,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,+CAA+C,IAAI,EAAE,EAAE;YAC5E,KAAK,EAAE,eAAe,CAAC,GAAG,CAAC;SAC5B,CAAC,CAAA;QACF,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CAAC,IAAY;IAChE,MAAM,0BAA0B,CAAC,IAAI,CAAC,CAAA;IACtC,+BAA+B,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC"}

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

@@ -0,0 +1,38 @@
+/**
+ * In-process registry connecting branch-mutating operations (git checkout/merge/rebase,
+ * content sync) to the ContentStore instances whose ContentId indexes those operations
+ * make stale.
+ *
+ * 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 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.
+ */
+/** 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.
+ */
+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).
+ *
+ * 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.
+ */
+export declare function invalidateContentIndexesForRoot(root: string): void;
+//# sourceMappingURL=content-index-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-index-registry.d.ts","sourceRoot":"","sources":["../src/content-index-registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,eAAe,IAAI,IAAI,CAAA;CACxB;AAcD;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,yBAAyB,GAChC,IAAI,CAUN;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAelE"}

package/dist/content-index-registry.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+const registry = new Map();
+const finalization = new FinalizationRegistry(({ rootKey, ref }) => {
+    const refs = registry.get(rootKey);
+    if (!refs)
+        return;
+    refs.delete(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.
+ */
+export function registerContentIndexForInvalidation(root, target) {
+    const rootKey = path.resolve(root);
+    let refs = registry.get(rootKey);
+    if (!refs) {
+        refs = new Set();
+        registry.set(rootKey, refs);
+    }
+    const ref = new WeakRef(target);
+    refs.add(ref);
+    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).
+ *
+ * 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.
+ */
+export function invalidateContentIndexesForRoot(root) {
+    const rootKey = path.resolve(root);
+    const prefix = rootKey + path.sep;
+    for (const [storeRoot, refs] of registry) {
+        if (storeRoot !== rootKey && !storeRoot.startsWith(prefix))
+            continue;
+        for (const ref of refs) {
+            const target = ref.deref();
+            if (target) {
+                target.invalidateIndex();
+            }
+            else {
+                refs.delete(ref);
+            }
+        }
+        if (refs.size === 0)
+            registry.delete(storeRoot);
+    }
+}
+//# sourceMappingURL=content-index-registry.js.map

package/dist/content-index-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-index-registry.js","sourceRoot":"","sources":["../src/content-index-registry.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AA2B5B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmD,CAAA;AAE3E,MAAM,YAAY,GAAG,IAAI,oBAAoB,CAG1C,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE;IACtB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAClC,IAAI,CAAC,IAAI;QAAE,OAAM;IACjB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAChB,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;AAC/C,CAAC,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,UAAU,mCAAmC,CACjD,IAAY,EACZ,MAAiC;IAEjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,IAAI,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAChC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,GAAG,IAAI,GAAG,EAAE,CAAA;QAChB,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC7B,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACb,YAAY,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAA;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,+BAA+B,CAAC,IAAY;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,MAAM,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,GAAG,CAAA;IACjC,KAAK,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzC,IAAI,SAAS,KAAK,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,SAAQ;QACpE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,CAAA;YAC1B,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,eAAe,EAAE,CAAA;YAC1B,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAClB,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;YAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACjD,CAAC;AACH,CAAC"}

package/dist/content-store.d.ts

@@ -1,4 +1,4 @@
-import type { FlatSchemaItem } from './config';
+import type { FlatSchemaItem, EntryTypeConfig } from './config';
 import { ContentIdIndex } from './content-id-index';
 import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths';
 export type MarkdownDocument = {
@@ -50,17 +50,95 @@ export declare class ContentStoreError extends Error {
 export declare class ContentConflictError extends Error {
     constructor();
 }
+/**
+ * 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.
+ */
+export declare function getDefaultEntryType(entries: readonly EntryTypeConfig[] | undefined): EntryTypeConfig | undefined;
+export interface ContentStoreOptions {
+    /**
+     * Minimum ms between on-disk generation-marker probes when the in-memory
+     * index is otherwise fresh (see content-index-generation.ts). The probe is
+     * one small readFile; the 1s default matches the schema-cache mtime
+     * debounce. Tests pass 0 for deterministic cross-process scenarios.
+     */
+    indexFreshnessIntervalMs?: number;
+}
 export declare class ContentStore {
     private readonly root;
     private readonly schemaIndex;
-    private readonly _idIndex;
-    private indexLoaded;
-    constructor(root: string, flatSchema: FlatSchemaItem[]);
+    /** Swapped wholesale on rebuild — in-flight callers keep their (older) snapshot. */
+    private _idIndex;
+    /** Bumped by invalidateIndex(); when it differs from loadedIndexGeneration the index is stale. */
+    private indexGeneration;
+    private loadedIndexGeneration;
     /**
-     * Get the ID index, ensuring it's loaded first.
-     * This getter automatically loads the index on first access.
+     * On-disk generation token (content-index-generation.ts) the current index
+     * was built against. undefined = never captured; null = marker absent at
+     * build time. Assigned only by the rebuild path and by guarded self-adoption
+     * after this store's own mutations.
+     */
+    private loadedDiskGeneration;
+    private lastDiskProbeMs;
+    private lastForcedRefreshMs;
+    private readonly indexFreshnessIntervalMs;
+    /** In-flight index build, shared by concurrent idIndex() callers so scans never interleave. */
+    private indexBuild;
+    constructor(root: string, flatSchema: FlatSchemaItem[], options?: ContentStoreOptions);
+    /**
+     * Mark the ID index stale so the next idIndex() access rebuilds it from disk.
+     *
+     * 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.
+     */
+    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).
      */
     idIndex(): Promise<ContentIdIndex>;
+    /**
+     * Throttle for the on-disk marker probe. Stamps the clock synchronously
+     * before the caller's readFile so concurrent idIndex() callers don't
+     * double-probe (and double-rebuild) on the same token change.
+     */
+    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.
+     */
+    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.
+     */
+    private refreshIndexForSuspiciousLookup;
+    /**
+     * Find the file in `dir` whose filename embeds `id`.
+     * Returns its root-relative path, or null if no such file (or no such dir).
+     */
+    private findEntryPathById;
     /**
      * Get all schema items for iteration.
      * Used internally by ReferenceResolver for path matching.
@@ -105,13 +183,47 @@ export declare class ContentStore {
     /**
      * Read an entry by its ID (UUID).
      * Returns null if the ID doesn't exist or points to a 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.
      */
     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>;
+    /**
+     * Check whether a document already exists on disk for this collection+slug.
+     * Used by the write boundary to distinguish creates from edits (create
+     * scaffolds and maxItems enforcement).
+     */
+    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.
+     *
+     * 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).
+     *
+     * Cheap: one buildPaths() resolution plus a stat, no file content is read —
+     * same cost class as documentExists().
+     */
+    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.
+     */
+    countEntriesOfType(collectionPath: LogicalPath, entryTypeName: string): Promise<number>;
     /**
      * Delete an entry and remove it from the index.
      */
@@ -150,7 +262,19 @@ export declare class ContentStore {
      * Resolve a single reference ID to full entry data.
      * Returns null if the reference is invalid or missing.
      * Includes id, slug, and collection fields for debugging.
+     *
+     * 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.
      */
     private resolveSingleReference;
+    private resolveSingleReferenceOnce;
 }
 //# sourceMappingURL=content-store.d.ts.map

package/dist/content-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-store.d.ts","sourceRoot":"","sources":["../src/content-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"content-store.d.ts","sourceRoot":"","sources":["../src/content-store.ts"],"names":[],"mappings":"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"}