canopycms 0.0.63 → 0.0.64

package/dist/task-queue/index.d.ts

@@ -1,3 +1,2 @@
-export type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types';
-export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue';
-//# sourceMappingURL=index.d.ts.map
+export type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types.js';
+export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue.js';

package/dist/task-queue/index.js

@@ -1,2 +1 @@
 export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, requeueFailedTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, listCorruptTaskFiles, } from './task-queue.js';
-//# sourceMappingURL=index.js.map

package/dist/task-queue/task-queue.d.ts

@@ -15,7 +15,7 @@
  * processes — the worker lock (acquireLock) ensures only one consumer runs at
  * a time. Do not run multiple dequeue consumers concurrently.
  */
-import type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types';
+import type { Task, TaskStatus, QueueStats, TaskQueueLogger, CorruptTaskFile } from './types.js';
 /**
  * Enqueue a task. Writes a JSON file to pending/{id}.json.
  * Returns the generated task ID.
@@ -114,4 +114,3 @@ export declare function getQueueStats(taskDir: string): Promise<QueueStats>;
  * dir (returns []). Sorted newest-mtime first, capped at `limit`.
  */
 export declare function listCorruptTaskFiles(taskDir: string, limit?: number, logger?: TaskQueueLogger): Promise<CorruptTaskFile[]>;
-//# sourceMappingURL=task-queue.d.ts.map

package/dist/task-queue/task-queue.js

@@ -531,4 +531,3 @@ async function moveToCorrupt(taskDir, sourceDir, fileName, reason, logger) {
         await fs.unlink(path.join(sourceDir, fileName)).catch(() => { });
     }
 }
-//# sourceMappingURL=task-queue.js.map

package/dist/task-queue/types.d.ts

@@ -47,4 +47,3 @@ export interface CorruptTaskFile {
     mtime: string;
     rawSnippet: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/task-queue/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ContentId } from './paths/types';
+import type { ContentId } from './paths/types.js';
 export type CanopyUserId = string;
 export type CanopyGroupId = string;
 /**
@@ -98,11 +98,11 @@ export interface BranchPaths {
 export interface BranchContext extends BranchPaths {
     branch: BranchMetadata;
     /** Per-branch flattened schema (lazy-loaded via getBranchContext with loadSchema: true) */
-    flatSchema?: import('./config').FlatSchemaItem[];
+    flatSchema?: import('./config/index.js').FlatSchemaItem[];
 }
 /** BranchContext with guaranteed flatSchema (loaded via schema guard or loadSchema: true) */
 export interface BranchContextWithSchema extends BranchContext {
-    flatSchema: import('./config').FlatSchemaItem[];
+    flatSchema: import('./config/index.js').FlatSchemaItem[];
 }
 /**
  * Wire shape of the worker's self-reported status file (worker-status.json,
@@ -170,4 +170,3 @@ export interface WorkerStatusReport {
         phase: 'startup' | 'run';
     };
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/url-collision.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The WRITE-BOUNDARY half of the invariant "no two entries may claim the same `urlPath`".
+ *
+ * The build-time half (`assertNoDuplicateUrlPaths`, static/index.ts) detects the state; this
+ * refuses to create it. Neither replaces the other: content is git-backed, so it also arrives by
+ * merge, by PR, by direct commit and by adopters retrofitting an existing repo — none of which
+ * pass through this boundary — while the build guard cannot help an editor who is about to author
+ * the collision right now.
+ *
+ * A SCHEMA edit alone can also create one, with no content write at all: `updateEntryType`
+ * changing a format changes the listing's `validExts`, which can flip a previously-unlisted
+ * `guide.index.{id}.json` into a published entry and so into a contested pair. Another reason
+ * neither half of this invariant subsumes the other.
+ *
+ * Deliberately formulated on `urlPath`, not on names. An entry whose slug matches a sibling
+ * collection is only a problem when that collection ALSO has an index entry:
+ *
+ *   content/docs/page.guides.{id}.json + content/docs/guides.{id}/  (no index)  -> fine.
+ *     A landing page plus a folder of children. Both are reachable; nothing is contested.
+ *
+ *   content/docs/page.guides.{id}.json + content/docs/guides.{id}/doc.index.{id}.md
+ *     -> contested. Both compute /docs/guides, so exactly one of them is reachable and the
+ *        other silently has no route.
+ *
+ * A name-collision rule would forbid the first, which is a shape adopters legitimately build.
+ *
+ * Everything here works on PHYSICAL directories, because that is what the write path holds when
+ * it needs the answer, and because the on-disk names carry the content IDs that logical paths
+ * hide (`guides.{id}/`, `doc.index.{id}.md`).
+ *
+ * SCOPE, and do not widen it by accident: this guards the URL an ENTRY claims -- the `urlPath`
+ * that `computeEntryUrl` derives and `listEntries` publishes. It is NOT "every URL the site
+ * serves", and the two are not the same set. A framework adapter can route an entry somewhere
+ * else — adopters add hand-written routes Canopy knows nothing about, and a framework adapter can
+ * rewrite a sitemap `<loc>` after enumeration (`generateContentSitemap`'s `pathFor` option, in
+ * `canopycms-next/src/static.ts`, does exactly that). Those URLs are
+ * invisible here by design -- there is no filesystem state to check them against at write time.
+ * A future change that tries to make this the authority on "the set of URLs this site claims"
+ * would be reaching past what the write boundary can actually see.
+ */
+/** One entry that already claims the `urlPath` a pending write would produce. */
+export interface UrlPathClaimant {
+    /**
+     * Which of the two shapes was found. Callers word their own message from this, because the
+     * actionable advice differs: for `sibling-collection-index` the author should rename their new
+     * entry, for `parent-entry` they are adding the index entry that makes an existing pair
+     * contested.
+     */
+    kind: 'sibling-collection-index' | 'parent-entry';
+    /** Absolute path of the file already claiming that URL. */
+    physicalPath: string;
+    /** The contested logical name — the sibling collection's name, or the parent entry's slug. */
+    name: string;
+}
+/**
+ * The index entry file directly inside `dir`, or null.
+ *
+ * Slug extraction is entry-type-agnostic (each candidate's own type is read out of its filename),
+ * so an index entry of ANY entry type counts — same reasoning as the existing same-slug guard,
+ * which is deliberately cross-type because the URL does not care what type serves it.
+ */
+export declare function findIndexEntryIn(dir: string): Promise<string | null>;
+/** The entry file directly inside `dir` whose slug is `slug`, or null. */
+export declare function findEntryBySlugIn(dir: string, slug: string): Promise<string | null>;
+/**
+ * Would an entry at `collectionDir` with slug `slug` land on a `urlPath` some OTHER entry already
+ * claims? Returns the offender, or null when the write is clear.
+ *
+ * Only the cross-collection shapes are checked here. An entry colliding with another entry in the
+ * SAME collection is already refused upstream (`ContentStore.buildPaths` resolves a write by a
+ * type-agnostic slug scan, and the `expectedVersion: null` create-intent guard turns that into a
+ * conflict), so re-checking it would be duplicate work and a second source of truth.
+ *
+ * Two directory reads at worst, and only on create/rename — an ordinary save of an existing entry
+ * never calls this, because the entry's URL is not changing and the collision (if any) predates
+ * the write.
+ *
+ * @param contentRoot Absolute path of the content root. A root-level index entry claims `/`, which
+ *   nothing above it can contest, so the `parent-entry` check stops here rather than walking out
+ *   of the content tree.
+ */
+export declare function findUrlPathClaimant(opts: {
+    collectionDir: string;
+    slug: string;
+    contentRoot: string;
+}): Promise<UrlPathClaimant | null>;

package/dist/url-collision.js

@@ -0,0 +1,186 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { extractSlugFromFilename } from './content-id-index.js';
+import { isIndexSlug } from './utils/entry-url.js';
+import { isNotFoundError } from './utils/error.js';
+import { parseTypedFilename } from './utils/typed-filename.js';
+/**
+ * Every extension `getFormatExtension` can return.
+ *
+ * Compared CASE-SENSITIVELY, deliberately, because `listCollectionEntries` compares
+ * case-sensitively (`d.name.endsWith(ext)` against lowercase extensions). Lowercasing here made
+ * the guard looser than the listing: a `doc.index.{id}.MD` file counted as a claimant while the
+ * listing skipped it silently — publishing no URL, tripping no build error, and blocking a write
+ * the build would have accepted.
+ *
+ * KNOWN RESIDUAL LOOSENESS, stated because the alternative is a comment that overclaims: the
+ * listing accepts only the extensions of a collection's OWN configured entry-type formats, while
+ * this accepts all four. A hand-authored `doc.index.{id}.json` inside an md-only collection
+ * therefore claims no URL yet still blocks a sibling write. Closing that means threading each
+ * collection's configured formats into a module that is deliberately schema-free, across three
+ * call sites, and going from a physical directory back to a schema item to do it — a change with
+ * more room to introduce a new defect than the narrow one it fixes. Tracked in
+ * .claude/future-tasks/url-collision-guard-superset-of-listing.md.
+ *
+ * A literal rather than derived: deriving it needs the `ContentFormat` union this module has no
+ * reason to import. `url-collision.test.ts` carries the drift tripwire — a compile-time
+ * exhaustiveness check plus a fixture per format — so adding a format fails there rather than
+ * silently under-blocking here.
+ */
+const CONTENT_EXTENSIONS = ['.md', '.mdx', '.json', '.yaml'];
+/** Read a directory, treating "missing" as empty. Anything else is a real error and propagates. */
+async function readDirSafe(dir) {
+    try {
+        return await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return [];
+        throw err;
+    }
+}
+/** The child directory of `dir` whose logical name is `name`, or null. */
+async function findChildCollectionDir(dir, name) {
+    const wanted = name.toLowerCase();
+    for (const entry of await readDirSafe(dir)) {
+        if (!entry.isDirectory())
+            continue;
+        if (extractSlugFromFilename(entry.name) === wanted)
+            return path.join(dir, entry.name);
+    }
+    return null;
+}
+/**
+ * The slug a file CLAIMS A URL AT, or null when the file claims none.
+ *
+ * This must recognise the set `listEntries` recognises, as closely as a schema-free module can,
+ * because the invariant is defined over the `urlPath`s `listEntries` publishes and the build-time
+ * half checks those. (One documented gap remains — see `CONTENT_EXTENSIONS`.) Hence
+ * `parseTypedFilename` — the same `{type}.{slug}.{id}.{ext}` grammar `listCollectionEntries` uses
+ * — rather than `extractSlugFromFilename`, which answers a different and much looser question
+ * ("what would I call this file?") and happily names a slug for things that are not entries.
+ *
+ * Getting this wrong OVER-BLOCKS, which is worse here than under-blocking: a hand-authored
+ * `index.md` with no content ID, an `index.md~` editor backup, or a colocated `guides.png` are all
+ * non-entries that claim no URL, so the build guard ignores them — but a looser scan counted them
+ * as claimants and refused a legitimate write, telling the author to "remove that collection's
+ * index entry" about a file Canopy does not consider an entry. That lands hardest on repos being
+ * retrofitted onto CanopyCMS, which is precisely the audience this guard's migration note
+ * addresses.
+ *
+ * Parsed structurally (no `entryTypes` list), which is the SECOND of three known ways this
+ * claimant set is a strict superset of the listing's — all of them over-blocks, all of them
+ * tracked together in .claude/future-tasks/url-collision-guard-superset-of-listing.md:
+ *
+ *   1. extension — see `CONTENT_EXTENSIONS` above;
+ *   2. entry TYPE — a file whose type is not in the collection's config is skipped by the
+ *      listing but counted here. An earlier version of this comment dismissed that as "already
+ *      reported by the listing's malformed-file guard". That is true only in BUILD mode; in the
+ *      editor, where this guard actually runs, `listCollectionEntries` skips such a file with a
+ *      debug-gated warning and nothing surfaces. Reached by the accident
+ *      `looksLikeMalformedEntry` itself names as most common: renaming an entry type in
+ *      `.collection.json` without renaming the files;
+ *   3. collection-hood — `findChildCollectionDir` matches any child directory by name, but a
+ *      directory with no `.collection.json` is not a collection, so nothing inside it publishes
+ *      a URL. Narrow (the file inside still needs valid entry grammar) but the same direction.
+ *
+ * All three need the same fix — the schema this module deliberately does not have — so they are
+ * one task, not three.
+ */
+function entrySlugOf(filename) {
+    // `parseTypedFilename` strips the extension without checking it, so an editor backup
+    // (`doc.index.{id}.md~`) parses exactly like the entry it shadows. `listCollectionEntries`
+    // additionally requires a CONFIGURED format extension, so it skips those -- and this must skip
+    // them too, or the guard refuses a write over a file the build guard never counted.
+    if (!CONTENT_EXTENSIONS.some((ext) => filename.endsWith(ext)))
+        return null;
+    return parseTypedFilename(filename)?.slug ?? null;
+}
+/**
+ * The index entry file directly inside `dir`, or null.
+ *
+ * Slug extraction is entry-type-agnostic (each candidate's own type is read out of its filename),
+ * so an index entry of ANY entry type counts — same reasoning as the existing same-slug guard,
+ * which is deliberately cross-type because the URL does not care what type serves it.
+ */
+export async function findIndexEntryIn(dir) {
+    for (const entry of await readDirSafe(dir)) {
+        if (entry.isDirectory())
+            continue;
+        if (isIndexSlug(entrySlugOf(entry.name) ?? undefined))
+            return path.join(dir, entry.name);
+    }
+    return null;
+}
+/** The entry file directly inside `dir` whose slug is `slug`, or null. */
+export async function findEntryBySlugIn(dir, slug) {
+    const wanted = slug.toLowerCase();
+    for (const entry of await readDirSafe(dir)) {
+        if (entry.isDirectory())
+            continue;
+        if (entrySlugOf(entry.name) === wanted)
+            return path.join(dir, entry.name);
+    }
+    return null;
+}
+/**
+ * Would an entry at `collectionDir` with slug `slug` land on a `urlPath` some OTHER entry already
+ * claims? Returns the offender, or null when the write is clear.
+ *
+ * Only the cross-collection shapes are checked here. An entry colliding with another entry in the
+ * SAME collection is already refused upstream (`ContentStore.buildPaths` resolves a write by a
+ * type-agnostic slug scan, and the `expectedVersion: null` create-intent guard turns that into a
+ * conflict), so re-checking it would be duplicate work and a second source of truth.
+ *
+ * Two directory reads at worst, and only on create/rename — an ordinary save of an existing entry
+ * never calls this, because the entry's URL is not changing and the collision (if any) predates
+ * the write.
+ *
+ * @param contentRoot Absolute path of the content root. A root-level index entry claims `/`, which
+ *   nothing above it can contest, so the `parent-entry` check stops here rather than walking out
+ *   of the content tree.
+ */
+export async function findUrlPathClaimant(opts) {
+    const { collectionDir, slug, contentRoot } = opts;
+    if (isIndexSlug(slug)) {
+        // Adding an index entry collapses this collection onto its own path, which an entry sitting
+        // beside the collection in the PARENT may already hold.
+        const resolvedRoot = path.resolve(contentRoot);
+        if (path.resolve(collectionDir) === resolvedRoot)
+            return null; // a root index claims '/', uncontestable
+        const parentDir = path.dirname(collectionDir);
+        const ownName = extractSlugFromFilename(path.basename(collectionDir));
+        // A collection literally NAMED "index" collapses onto ITS OWN path (`<parentPath>/index`),
+        // not onto `<parentPath>` -- see `computeEntryUrl`. So the only thing that could contest it
+        // is another entry in the parent whose slug is ALSO the literal string "index" -- but per
+        // that same forward rule, such an entry IS the parent's own index/landing entry, which
+        // collapses onto `<parentPath>` itself, a different URL. Nothing in the parent can ever claim
+        // `<parentPath>/index`, so skip the lookup below rather than let it match the parent's own
+        // index entry and report a collision that does not exist. Without this, a collection named
+        // "index" could never have a landing page under any parent that has one of its own --
+        // ironic, since `resolveUrlPathCandidates`' candidate 2 was deliberately engineered to keep a
+        // collection named "index" addressable in the first place.
+        if (isIndexSlug(ownName))
+            return null;
+        const claimant = await findEntryBySlugIn(parentDir, ownName);
+        return claimant ? { kind: 'parent-entry', physicalPath: claimant, name: ownName } : null;
+    }
+    // A plain entry sits at the same URL as a same-named child collection's index entry.
+    //
+    // KNOWN DEPENDENCY: this resolves ONE child collection by name, and the index direction above
+    // likewise looks only for a parent ENTRY. Neither considers a second collection sharing the
+    // same name, because nothing currently stops one being created -- `createCollectionInner` does
+    // not check sibling names at all (tracked in collection-sibling-name-uniqueness.md). With two
+    // `guides.{id}` directories side by side you can write an index entry into each, and both
+    // writes pass this guard while two entries end up claiming one URL. The build guard still
+    // catches it. Fixing sibling-name uniqueness closes this without changing anything here --
+    // which is why that task is a prerequisite for this guard being complete, not an unrelated
+    // tidy-up.
+    const childDir = await findChildCollectionDir(collectionDir, slug);
+    if (!childDir)
+        return null;
+    const indexEntry = await findIndexEntryIn(childDir);
+    return indexEntry
+        ? { kind: 'sibling-collection-index', physicalPath: indexEntry, name: slug }
+        : null;
+}

package/dist/url-path-resolver.d.ts

@@ -2,9 +2,19 @@
  * Resolves a URL path to candidate entryPath/slug pairs for content lookup.
  *
  * Returns an ordered list of attempts:
- * 1. Direct entry: last segment is slug, rest is collection path
+ * 1. Direct entry: last segment is slug, rest is collection path — SKIPPED when that slug is
+ *    literally 'index' (see below)
  * 2. Index fallback: full path is collection, slug is 'index'
  *
+ * This is the REVERSE of the forward collection+slug -> url rule, and the two must agree on how
+ * many URLs an entry answers at. The forward rule (`computeEntryUrl` in utils/entry-url.ts, which
+ * `listEntries` publishes as `item.urlPath` and reference resolution stamps on every resolved
+ * reference; and `defaultBuildPath` in content-tree.ts for tree nodes) collapses an `index` slug
+ * onto its collection's path and never emits a trailing `/index`. Candidate 1 used to match it
+ * anyway, so an index entry ALSO answered at a `.../index` URL that no forward surface publishes
+ * — enumeration and resolution disagreeing about how many URLs exist. Adopters paid for that with
+ * per-route entryType gates whose only job was to reject the phantom.
+ *
  * @param urlPath - URL path like '/docs/guides/getting-started' or 'docs/guides'
  * @param contentRoot - Content root directory name (default: 'content')
  * @returns Array of { entryPath, slug } candidates to try in order
@@ -13,4 +23,3 @@ export declare function resolveUrlPathCandidates(urlPath: string, contentRoot: s
     entryPath: string;
     slug: string;
 }>;
-//# sourceMappingURL=url-path-resolver.d.ts.map

package/dist/url-path-resolver.js

@@ -1,11 +1,22 @@
 import { trimSlashes } from './paths/normalize.js';
+import { isIndexSlug } from './utils/entry-url.js';
 /**
  * Resolves a URL path to candidate entryPath/slug pairs for content lookup.
  *
  * Returns an ordered list of attempts:
- * 1. Direct entry: last segment is slug, rest is collection path
+ * 1. Direct entry: last segment is slug, rest is collection path — SKIPPED when that slug is
+ *    literally 'index' (see below)
  * 2. Index fallback: full path is collection, slug is 'index'
  *
+ * This is the REVERSE of the forward collection+slug -> url rule, and the two must agree on how
+ * many URLs an entry answers at. The forward rule (`computeEntryUrl` in utils/entry-url.ts, which
+ * `listEntries` publishes as `item.urlPath` and reference resolution stamps on every resolved
+ * reference; and `defaultBuildPath` in content-tree.ts for tree nodes) collapses an `index` slug
+ * onto its collection's path and never emits a trailing `/index`. Candidate 1 used to match it
+ * anyway, so an index entry ALSO answered at a `.../index` URL that no forward surface publishes
+ * — enumeration and resolution disagreeing about how many URLs exist. Adopters paid for that with
+ * per-route entryType gates whose only job was to reject the phantom.
+ *
  * @param urlPath - URL path like '/docs/guides/getting-started' or 'docs/guides'
  * @param contentRoot - Content root directory name (default: 'content')
  * @returns Array of { entryPath, slug } candidates to try in order
@@ -16,16 +27,37 @@ export function resolveUrlPathCandidates(urlPath, contentRoot) {
     if (segments.length === 0)
         return [{ entryPath: contentRoot, slug: 'index' }];
     const candidates = [];
-    // Try 1: last segment is the entry slug, rest is the collection path
+    // Try 1: last segment is the entry slug, rest is the collection path.
+    //
+    // Skipped when that slug is an index slug. An index entry's ADVERTISED URL is its collapsed
+    // collection path, so matching it here would answer at a second URL enumeration never emits.
+    // `index` is not a contrived segment either — it is the slug the index convention requires on
+    // disk, so the collision was structural rather than accidental.
+    //
+    // This closes the `.../index` spelling, NOT every extra URL: candidate 2 below still resolves an
+    // index entry at `/<collection>/<entryTypeName>`, because that path is a registered entry-TYPE
+    // schema item which `buildPaths` delegates to the parent collection. Open, and tracked in
+    // .claude/future-tasks/readbyurlpath-entry-type-candidate-phantom-url.md.
+    //
+    // Compared case-INSENSITIVELY, through the shared `isIndexSlug`. This function is the one
+    // consumer that sees a raw, un-normalized URL segment — everything downstream lowercases
+    // (`parseSlug`, and ContentStore's directory scan) — so a strict compare here closed
+    // `/x/index` while leaving `/x/Index` and `/x/INDEX` resolving the very entry it exists to hide.
     const slug = segments[segments.length - 1];
     const collectionSegments = segments.slice(0, -1);
     const entryPath = collectionSegments.length > 0 ? `${contentRoot}/${collectionSegments.join('/')}` : contentRoot;
-    candidates.push({ entryPath, slug });
-    // Try 2: full path is a collection with an index entry
+    if (!isIndexSlug(slug)) {
+        candidates.push({ entryPath, slug });
+    }
+    // Try 2: full path is a collection with an index entry.
+    //
+    // Kept unconditionally, which is what makes the skip above a skip rather than a removal: a
+    // collection literally NAMED `index` is handed the path `/x/index` by
+    // `defaultBuildPath(kind: 'collection')`, and this candidate is the only one that can answer it.
+    // (Candidate 1 used to shadow that collection entirely, returning the parent's own index entry.)
     candidates.push({
         entryPath: `${contentRoot}/${segments.join('/')}`,
         slug: 'index',
     });
     return candidates;
 }
-//# sourceMappingURL=url-path-resolver.js.map

package/dist/user.d.ts

@@ -1,6 +1,6 @@
-import type { CanopyUserId, CanopyGroupId } from './types';
-import type { AuthenticationResult } from './auth/types';
-import type { InternalGroup } from './authorization/groups/schema';
+import type { CanopyUserId, CanopyGroupId } from './types.js';
+import type { AuthenticationResult } from './auth/types.js';
+import type { InternalGroup } from './authorization/groups/schema.js';
 /**
  * Anonymous user - explicitly marked for public/unauthenticated access
  */
@@ -41,4 +41,3 @@ export declare const ANONYMOUS_USER: AnonymousUser;
  * @returns CanopyUser (either authenticated with groups or ANONYMOUS_USER)
  */
 export declare function authResultToCanopyUser(authResult: AuthenticationResult, bootstrapAdminIds: Set<string>, internalGroups?: InternalGroup[]): CanopyUser;
-//# sourceMappingURL=user.d.ts.map

package/dist/user.js

@@ -51,4 +51,3 @@ export function authResultToCanopyUser(authResult, bootstrapAdminIds, internalGr
         groups,
     };
 }
-//# sourceMappingURL=user.js.map

package/dist/utils/async-mutex.d.ts

@@ -1,2 +1 @@
 export declare function withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=async-mutex.d.ts.map

package/dist/utils/async-mutex.js

@@ -25,4 +25,3 @@ export async function withLock(key, fn) {
             locks.delete(key);
     }
 }
-//# sourceMappingURL=async-mutex.js.map

package/dist/utils/atomic-write.d.ts

@@ -12,4 +12,3 @@
  * @param content - String or binary content to write
  */
 export declare function atomicWriteFile(filePath: string, content: string | Buffer | Uint8Array): Promise<void>;
-//# sourceMappingURL=atomic-write.d.ts.map

package/dist/utils/atomic-write.js

@@ -26,4 +26,3 @@ export async function atomicWriteFile(filePath, content) {
         throw err;
     }
 }
-//# sourceMappingURL=atomic-write.js.map

package/dist/utils/body-field.d.ts

@@ -1,4 +1,4 @@
-import type { FieldConfig } from '../config';
+import type { FieldConfig } from '../config/index.js';
 /**
  * Count the number of top-level fields marked `isBody: true` in a schema.
  * Does NOT recurse into objects — isBody only makes sense at the top level
@@ -10,9 +10,19 @@ export declare function countBodyFields(fields: readonly FieldConfig[]): number;
  * Used at read time to map the markdown file's content to the correct data field.
  */
 export declare function findBodyFieldName(fields: readonly FieldConfig[]): string;
+/**
+ * Find an isBody field whose NAME is reserved by reference resolution.
+ *
+ * A resolved reference reserves `id`/`slug`/`collection`/`urlPath` by applying them after the
+ * target's data. The body is the one value assigned by key rather than spread, so a body field
+ * named e.g. `id` would be the single way to get around that — and since the write boundary
+ * recovers a reference's id from `value.id`, re-saving would then persist the prose as the
+ * reference. Rejected at registry-validation time instead, so the schema fails loudly rather
+ * than the body being silently dropped at resolution.
+ */
+export declare function findReservedBodyFieldName(fields: readonly FieldConfig[], reserved: readonly string[]): string | undefined;
 /**
  * Find isBody fields that have an invalid type (not 'markdown' or 'mdx').
  * Returns field names that fail validation.
  */
 export declare function findInvalidBodyFields(fields: readonly FieldConfig[]): string[];
-//# sourceMappingURL=body-field.d.ts.map

package/dist/utils/body-field.js

@@ -24,6 +24,23 @@ export function findBodyFieldName(fields) {
     }
     return 'body';
 }
+/**
+ * Find an isBody field whose NAME is reserved by reference resolution.
+ *
+ * A resolved reference reserves `id`/`slug`/`collection`/`urlPath` by applying them after the
+ * target's data. The body is the one value assigned by key rather than spread, so a body field
+ * named e.g. `id` would be the single way to get around that — and since the write boundary
+ * recovers a reference's id from `value.id`, re-saving would then persist the prose as the
+ * reference. Rejected at registry-validation time instead, so the schema fails loudly rather
+ * than the body being silently dropped at resolution.
+ */
+export function findReservedBodyFieldName(fields, reserved) {
+    for (const field of flattenGroupFields(fields)) {
+        if ('isBody' in field && field.isBody && reserved.includes(field.name))
+            return field.name;
+    }
+    return undefined;
+}
 /**
  * Find isBody fields that have an invalid type (not 'markdown' or 'mdx').
  * Returns field names that fail validation.
@@ -37,4 +54,3 @@ export function findInvalidBodyFields(fields) {
     }
     return invalid;
 }
-//# sourceMappingURL=body-field.js.map

package/dist/utils/content-serialize.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Comment-preserving serialisation for YAML content files and md/mdx frontmatter.
+ *
+ * ContentStore used to write a content file by stringifying a fresh plain object
+ * (`yamlStringify(data)` / `matter.stringify(body, data)`). Comments live in neither the object
+ * nor that round trip, so **every editor save silently deleted every comment in the file** —
+ * invisible to a dev team (`canopycms sync` copies files byte-for-byte) and certain for an
+ * editorial team. See `.claude/future-tasks/resolved/content-comment-loss-on-editor-save.md`.
+ *
+ * The fix re-serialises onto the file's OWN parsed document instead of a fresh one: nodes whose
+ * value did not change are left untouched, and an untouched node keeps its attached comments
+ * (and its original quoting/block style). Only what actually changed is rewritten.
+ *
+ * What this module does NOT do is give the file any authority over its own content. The
+ * reconciler makes the document's key set match `data` exactly — a key the caller dropped
+ * disappears, a key the caller kept survives whether or not the schema still knows about it.
+ * Data authority stays with the payload; comments are the only thing inherited from disk. That
+ * separation is deliberate: whether a surviving key SHOULD still be there is a schema question,
+ * answered one layer up by `findUnknownKeys` (validation/entry-validator.ts) at the API
+ * boundary, not by a serialiser that has no schema.
+ */
+/**
+ * Serialise entry data as a YAML file, carrying the comments of `existingRaw` through.
+ *
+ * Falls back to a plain stringify — byte-identical to the pre-fix behaviour — when there is
+ * nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk do not
+ * parse). A save must not fail because the previous content was malformed.
+ */
+export declare function serializeYaml(data: Record<string, unknown>, existingRaw?: string): string;
+/**
+ * Serialise an md/mdx entry, carrying the comments of `existingRaw`'s frontmatter through.
+ *
+ * The reconciled YAML goes back through `matter.stringify` via a custom stringify engine rather
+ * than being spliced between hand-written `---` lines, so the delimiters, blank lines and
+ * trailing newline stay exactly what gray-matter would have produced.
+ */
+export declare function serializeFrontmatter(body: string, data: Record<string, unknown>, existingRaw?: string): string;