canopycms 0.0.65 → 0.0.66-int.81

package/README.md

@@ -316,9 +316,7 @@ This convention is applied consistently across the API:
 | `readByUrlPath`    | Automatically tries `slug: 'index'` as a fallback when the direct entry doesn't match. Works for all paths including `/`. A path whose last segment is an index slug (any case) skips the direct-entry attempt, so an index entry is reachable only at its collapsed path. |
 | `buildContentTree` | Default `buildPath` collapses index entries so tree node paths match the URLs consumers would use.                                                                                                                                                                         |
 
-The round-trip property holds in both directions: for every item from `listEntries`, `readByUrlPath(item.urlPath)` resolves to the same entry, and for an index entry no `.../index` spelling does. (Ordinary entries keep case-insensitive matching on the final slug segment.)
-
-One known exception, still open: an entry-type name is also resolvable as a URL segment, so an index entry additionally answers at `/<collection>/<entryTypeName>` -- e.g. a root index entry at both `/` and `/home`. Nothing advertises that URL (it is absent from `listEntries` and from static-param generation), so it only matters if you serve a catch-all route. See the `readbyurlpath-entry-type-candidate-phantom-url` task in the CanopyCMS repo.
+The round-trip property holds in both directions: for every item from `listEntries`, `readByUrlPath(item.urlPath)` resolves to the same entry, and for an index entry no `.../index` spelling does, nor does an entry-type name -- `readByUrlPath` only accepts a candidate whose collection segment is an actual collection, so `/<collection>/<entryTypeName>` (e.g. a root index entry answering at both `/` and `/home`) is not a second URL for it. (Ordinary entries keep case-insensitive matching on the final slug segment.)
 
 Two different entries can still compute the same `urlPath` — an entry whose slug matches a sibling collection that also has an `index` entry, or two slugs differing only by case. Only one of them can be served, so a production build fails and names them. `findDuplicateUrlPaths` (exported from `canopycms/server`) runs the same scan on demand.
 

package/dist/cli/cli.js

@@ -6264,6 +6264,54 @@ var init_generate_ai_content = __esm({
         }
         return item;
       }
+      /**
+       * 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.
+       *
+       * 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.
+       *
+       * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+       * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+       */
+      isCollectionPath(collectionPath) {
+        return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === "collection";
+      }
+      /**
+       * 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.
+       *
+       * 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 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.
+       */
+      declaresEntryType(collectionPath, entryTypeName) {
+        const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
+        if (item?.type !== "collection")
+          return true;
+        if (!item.entries)
+          return false;
+        return item.entries.some((e) => e.name === entryTypeName);
+      }
       assertCollection(collectionPath) {
         const item = this.assertSchemaItem(collectionPath);
         if (item.type !== "collection") {

package/dist/cli/generate-ai-content.js

@@ -2926,6 +2926,54 @@ var ContentStore = class {
     }
     return item;
   }
+  /**
+   * 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.
+   *
+   * 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.
+   *
+   * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+   * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+   */
+  isCollectionPath(collectionPath) {
+    return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === "collection";
+  }
+  /**
+   * 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.
+   *
+   * 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 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.
+   */
+  declaresEntryType(collectionPath, entryTypeName) {
+    const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
+    if (item?.type !== "collection")
+      return true;
+    if (!item.entries)
+      return false;
+    return item.entries.some((e) => e.name === entryTypeName);
+  }
   assertCollection(collectionPath) {
     const item = this.assertSchemaItem(collectionPath);
     if (item.type !== "collection") {

package/dist/content-reader.d.ts

@@ -11,7 +11,11 @@ export interface ContentReaderOptions {
     getBranchContext?: (branch: string) => Promise<BranchContext | null>;
 }
 export interface ReadContentInput {
-    /** Resolved schema path (e.g., content/posts or content/home). */
+    /**
+     * Resolved schema path (e.g., content/posts or content/home). An entry-TYPE path like
+     * `content/home` is valid and resolves that singleton -- except under `urlAddressableOnly`
+     * below, which rejects it.
+     */
     entryPath: LogicalPath;
     slug?: Slug;
     branch?: string;
@@ -21,6 +25,26 @@ export interface ReadContentInput {
     resolveReferences?: boolean;
     /** Whether to resolve entry:ID links in body/markdown fields. Defaults to true. */
     resolveEntryLinks?: boolean;
+    /**
+     * This read is addressing an entry by its PUBLISHED URL, so accept only what enumeration
+     * publishes. Two rules, both off by default:
+     *
+     * 1. `entryPath` must be a COLLECTION. A published URL is `/<collectionSegments>/<slug>` (or
+     *    the collapsed collection path, for an index entry), so its non-slug segments are always
+     *    collection names. An `entryPath` that resolves to an entry-TYPE item instead would be
+     *    delegated by `ContentStore.buildPaths` to the parent collection -- answering at
+     *    `/<collection>/<typeName>` and `/<collection>/<typeName>/<slug>`, neither of which any
+     *    forward surface emits.
+     * 2. The resolved entry's type must be one its collection declares, matching the
+     *    `parseTypedFilename(filename, collection.entries)` check `listEntries` applies. A legacy
+     *    untyped file has no type token to fail on -- see `declaresEntryType`.
+     *
+     * Set by `readByUrlPath` and nothing else. Note what it does NOT do: `read({ entryPath:
+     * 'content/home' })` and direct `ContentStore` use keep the entry-type delegation, which is a
+     * supported API and the only way to address a singleton structurally. Misusing this flag can
+     * only make a read stricter, never looser.
+     */
+    urlAddressableOnly?: boolean;
 }
 /**
  * Structural metadata surfaced alongside a resolved content read. Shared by

package/dist/content-reader.js

@@ -122,6 +122,13 @@ export const createContentReader = (options) => {
     const readDocument = async (input) => {
         const { entryPath, slug, branchName, user } = resolveTarget(input);
         const { context, branchRoot, store } = await resolveStore(branchName);
+        // Rule 1 of urlAddressableOnly (see ReadContentInput): a published URL's non-slug segments
+        // are collection names, so a candidate landing on an entry-TYPE item can only ever produce a
+        // URL enumeration never emits. NO_SCHEMA_ITEM is what assertCollection raises for exactly
+        // this condition, and readByUrlPath treats it as a miss and tries the next candidate.
+        if (input.urlAddressableOnly && !store.isCollectionPath(entryPath)) {
+            throw new ContentStoreError(`Path is not a collection: ${entryPath}`, 'NO_SCHEMA_ITEM');
+        }
         // Get the path WITHOUT reading the file
         let relativePath;
         // Absolute filesystem path to the entry file. Surfaced on read() / readByUrlPath()
@@ -151,6 +158,14 @@ export const createContentReader = (options) => {
             const code = err instanceof ContentStoreError ? err.code : 'VALIDATION';
             throw new ContentStoreError(message, code);
         }
+        // Rule 2 of urlAddressableOnly (see ReadContentInput): buildPaths' directory scan matches on
+        // slug alone, so it happily returns a file whose type token the collection no longer (or
+        // never did) declare -- a file listEntries skips. Checked here rather than inside the scan so
+        // the write path can still find, edit and rename it; making it unfindable would make the
+        // mistake unrecoverable through the editor.
+        if (input.urlAddressableOnly && !store.declaresEntryType(entryPath, entryType)) {
+            throw new ContentStoreError(`Entry type '${entryType}' is not declared by ${entryPath}`, 'NO_SCHEMA_ITEM');
+        }
         // Check permissions BEFORE reading the file (security)
         const shouldCheckPermissions = !(isDeployedStatic(services.config) || isBuildMode());
         if (shouldCheckPermissions) {

package/dist/content-store.d.ts

@@ -289,6 +289,45 @@ export declare class ContentStore {
      */
     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.
+     *
+     * 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.
+     *
+     * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+     * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+     */
+    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.
+     *
+     * 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 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.
+     */
+    declaresEntryType(collectionPath: LogicalPath, entryTypeName: string): boolean;
     private assertCollection;
     /**
      * Lock key for an existing entry, addressed by its permanent content ID

package/dist/content-store.js

@@ -391,6 +391,54 @@ export class ContentStore {
         }
         return item;
     }
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+     * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+     */
+    isCollectionPath(collectionPath) {
+        return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === 'collection';
+    }
+    /**
+     * 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.
+     *
+     * 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 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.
+     */
+    declaresEntryType(collectionPath, entryTypeName) {
+        const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
+        if (item?.type !== 'collection')
+            return true;
+        if (!item.entries)
+            return false;
+        return item.entries.some((e) => e.name === entryTypeName);
+    }
     assertCollection(collectionPath) {
         const item = this.assertSchemaItem(collectionPath);
         if (item.type !== 'collection') {
@@ -499,9 +547,20 @@ export class ContentStore {
         const rootWithSep = this.root.endsWith(path.sep) ? this.root : `${this.root}${path.sep}`;
         // Entry-type items: delegate to their parent collection.
         // Uses the same {type}.{slug}.{id}.{ext} pattern as all entries.
-        // NOTE: The API layer always resolves paths via resolvePath(), which returns
-        // the parent collection directly, so this branch may only fire on direct
-        // ContentStore usage (e.g., store.read('content/home', '')).
+        //
+        // This branch is for DIRECT ContentStore usage -- store.read('content/home', ''), and the
+        // read({ entryPath: 'content/home' }) API built on it, where the slug defaults to the entry
+        // type's own name. The API layer resolves paths via resolvePath(), which returns the parent
+        // collection directly and so never lands here.
+        //
+        // That used to be an observation, and it was WRONG: readByUrlPath reached this branch too,
+        // because `resolveUrlPathCandidates` happily produces `content/<typeName>` for the URL
+        // `/<typeName>` and the delegation below then answered it with the parent collection's index
+        // entry -- a URL no forward surface publishes. It is now enforced rather than assumed:
+        // readByUrlPath requires every candidate's entryPath to be a collection (see
+        // `isCollectionPath` and `ReadContentInput.urlAddressableOnly`). Narrowing the delegation
+        // ITSELF was the wrong fix -- write()/renameEntry()/delete() resolve through here as well,
+        // and the by-URL rule has no business constraining them.
         if (schemaItem.type === 'entry-type') {
             const parentPath = schemaItem.parentPath || '';
             const parentCollection = this.schemaIndex.get(parentPath);

package/dist/context.d.ts

@@ -76,12 +76,22 @@ export interface CanopyBuildContext {
      * Read content by URL path, resolving the collection/entry split automatically.
      *
      * Tries direct entry match first (last segment = slug, rest = collection path),
-     * then falls back to index entry (full path = collection, slug = 'index').
+     * then falls back to index entry (full path = collection, slug = 'index'). Both attempts
+     * require the collection part to be a real collection — see below.
      * Root path '/' resolves to the content root's index entry.
      *
-     * The direct-entry attempt is SKIPPED when the last segment is an index slug (any case), so
-     * `/x/index` returns null rather than a second URL for the entry that already answers at `/x`.
-     * A collection literally named `index` is unaffected — the fallback resolves it.
+     * Resolves ONLY what `listEntries` publishes — `readByUrlPath(item.urlPath)` reaches the entry,
+     * and no other spelling does. Three shapes that used to resolve are therefore null now:
+     * `/x/index` (the literal spelling of an index entry's collapsed URL, in any case),
+     * `/<collection>/<entryTypeName>` and `/<collection>/<entryTypeName>/<slug>` (an entry-type
+     * path is not a collection, so it is not part of any published URL), and an entry whose
+     * on-disk type token its collection does not declare (`listEntries` skips those too). A
+     * collection literally named `index` is unaffected — the index fallback resolves it.
+     *
+     * `read({ entryPath: 'content/home' })` is deliberately NOT narrowed: addressing an entry
+     * structurally, by its schema path, is a different question from addressing it by its
+     * published URL, and it is the only way to reach a singleton without knowing its slug.
+     *
      * Returns null if no content matches the path — including collection URLs that have no
      * index entry (use buildContentTree for those) and non-entry/invalid paths such as
      * `/favicon.ico` or Next internals (the slug validator rejects them, treated as a miss).

package/dist/context.js

@@ -60,8 +60,12 @@ export function createCanopyContext(options) {
         const user = await getUser();
         // Create base content reader
         const baseReader = createContentReader({ services });
-        // Wrap reader to inject user automatically, validating strings → branded types at this boundary
-        const read = async (input) => {
+        // Wrap reader to inject user automatically, validating strings → branded types at this
+        // boundary. `extra` carries options that are NOT part of the public `read` surface -- today
+        // just readByUrlPath's URL-addressability gate. Kept as a separate inner function rather than
+        // an optional second parameter on the `CanopyContext['read']`-typed closure so the two call
+        // sites stay visible and nobody widens the public API by accident.
+        const readWithOptions = async (input, extra) => {
             const entryPath = createLogicalPath(input.entryPath);
             let slug;
             if (input.slug) {
@@ -77,9 +81,11 @@ export function createCanopyContext(options) {
                 branch: input.branch,
                 user,
                 resolveReferences: input.resolveReferences ?? true,
+                ...extra,
             };
             return baseReader.read(readInput);
         };
+        const read = (input) => readWithOptions(input);
         const readByUrlPath = async (urlPath, options) => {
             const contentRoot = services.config.contentRoot || 'content';
             const candidates = resolveUrlPathCandidates(urlPath, contentRoot);
@@ -93,12 +99,17 @@ export function createCanopyContext(options) {
                 if (!parseSlug(candidate.slug).ok)
                     continue;
                 try {
-                    return await read({
+                    return await readWithOptions({
                         entryPath: candidate.entryPath,
                         slug: candidate.slug,
                         branch,
                         resolveReferences,
-                    });
+                    }, 
+                    // This is a read BY PUBLISHED URL, so it must accept only what listEntries publishes.
+                    // See ReadContentInput.urlAddressableOnly for the two rules and why they live in the
+                    // reader (which holds the branch-correct schema) rather than in the candidate builder
+                    // (which is pure and schema-free by design).
+                    { urlAddressableOnly: true });
                 }
                 catch (err) {
                     // Swallow "not found" errors from trying candidate paths, and FORBIDDEN (a denied

package/dist/url-exclusivity-fixtures.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The one-URL-per-entry invariant, as a reusable probe + report.
+ *
+ * `listEntries` assigns every entry exactly one `urlPath` and documents the round trip through
+ * `readByUrlPath` as safe. The reverse direction has repeatedly been the looser of the two: it
+ * has answered at URLs no forward surface emits, and those extra URLs were found one at a time,
+ * a release apart, by adopters (see
+ * `.claude/future-tasks/resolved/url-resolver-index-entry-extra-url.md`, then
+ * `resolved/readbyurlpath-entry-type-candidate-phantom-url.md`). This module exists so the whole
+ * invariant is asserted at once instead: enumerate, then probe every ADJACENT URL the resolver
+ * would try and require it to be a miss.
+ *
+ * Deliberately free of `vitest` -- this is a plain `src` module in the shape of
+ * `operating-mode/deployment-name-fixtures.ts`, so more than one test file can import it without
+ * dragging that file's `vi.mock` calls and `describe` blocks along. It therefore ASSERTS NOTHING:
+ * it returns a report and the caller does the expecting, which also puts the offending URLs in
+ * the assertion message rather than behind a boolean.
+ *
+ * Scope of the invariant it checks: entries written in the `{type}.{slug}.{id}.{ext}` grammar
+ * with a type their collection declares -- i.e. exactly the set `listEntries` can see. A legacy
+ * untyped file (`overview.json`) is invisible to enumeration and is deliberately NOT probed here;
+ * see `.claude/future-tasks/legacy-untyped-files-url-addressable.md`.
+ */
+import { type RootCollectionConfig } from './config/index.js';
+import type { ListEntriesItem } from './content-listing.js';
+import type { CanopyContext } from './context.js';
+import { type DuplicateUrlPath } from './static/index.js';
+/**
+ * Every URL adjacent to the published set that the resolver would actually attempt.
+ *
+ * Three families, each one a shape that HAS resolved at some point in this package's history:
+ *
+ * 1. `/<collection>/<entryTypeName>` -- `resolveUrlPathCandidates`' index-fallback candidate lands
+ *    on a registered entry-TYPE schema item, which `ContentStore.buildPaths` delegates to the
+ *    parent collection with slug `index`, resolving that collection's index entry.
+ * 2. `/<collection>/<entryTypeName>/<slug>` -- the same delegation reached through the
+ *    DIRECT-entry candidate instead, resolving the collection's entry `<slug>`. Wider than family
+ *    1: it needs no index entry at all, so it applies to every listed entry.
+ * 3. `/<publishedUrl>/index`, and its case variants -- an index entry answering at the literal
+ *    spelling its collapsed URL replaced.
+ *
+ * Entry-type names are appended VERBATIM, after `computeEntryUrl` has lowercased the collection
+ * part. That asymmetry is real, not sloppiness: `flattenSchema` puts `entryType.name` into the
+ * logical path unchanged and `normalizeFilesystemPath` does not lowercase, so only the declared
+ * spelling can reach the entry-type schema item at all. A lowercased probe would miss the schema
+ * item, return null for the wrong reason, and pass vacuously.
+ */
+export declare const buildProbeUrls: (schema: RootCollectionConfig, items: readonly ListEntriesItem[], contentRoot?: string) => string[];
+export interface UrlExclusivityReport {
+    /** Every `urlPath` the listing published, sorted. */
+    published: string[];
+    /** URLs claimed by more than one entry. A precondition failure, not a resolver finding. */
+    duplicates: DuplicateUrlPath[];
+    /** Published URLs `readByUrlPath` did NOT resolve -- the round trip broken going forward. */
+    unresolved: string[];
+    /** Published URLs that resolved to some OTHER entry than the one that published them. */
+    mismatched: Array<{
+        urlPath: string;
+        expectedEntryId?: string;
+        actualEntryId?: string;
+    }>;
+    /** Every adjacent URL probed, sorted. */
+    probes: string[];
+    /** Probes that resolved despite not being published -- the phantom URLs. Must be empty. */
+    phantoms: string[];
+}
+/**
+ * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for what each field means and
+ * `buildProbeUrls` for which URLs are probed.
+ *
+ * A probe whose LOWERCASED form is published is skipped rather than asserted on: a collection
+ * literally named `index` publishes `/docs/index`, which family 3 also generates, and whether
+ * `/docs/Index` should resolve is a separate, pre-existing question about collection-path case
+ * sensitivity that this invariant does not speak to.
+ */
+export declare const collectUrlExclusivityReport: (ctx: Pick<CanopyContext, "listEntries" | "readByUrlPath">, schema: RootCollectionConfig, contentRoot?: string) => Promise<UrlExclusivityReport>;

package/dist/url-exclusivity-fixtures.js

@@ -0,0 +1,119 @@
+/**
+ * The one-URL-per-entry invariant, as a reusable probe + report.
+ *
+ * `listEntries` assigns every entry exactly one `urlPath` and documents the round trip through
+ * `readByUrlPath` as safe. The reverse direction has repeatedly been the looser of the two: it
+ * has answered at URLs no forward surface emits, and those extra URLs were found one at a time,
+ * a release apart, by adopters (see
+ * `.claude/future-tasks/resolved/url-resolver-index-entry-extra-url.md`, then
+ * `resolved/readbyurlpath-entry-type-candidate-phantom-url.md`). This module exists so the whole
+ * invariant is asserted at once instead: enumerate, then probe every ADJACENT URL the resolver
+ * would try and require it to be a miss.
+ *
+ * Deliberately free of `vitest` -- this is a plain `src` module in the shape of
+ * `operating-mode/deployment-name-fixtures.ts`, so more than one test file can import it without
+ * dragging that file's `vi.mock` calls and `describe` blocks along. It therefore ASSERTS NOTHING:
+ * it returns a report and the caller does the expecting, which also puts the offending URLs in
+ * the assertion message rather than behind a boolean.
+ *
+ * Scope of the invariant it checks: entries written in the `{type}.{slug}.{id}.{ext}` grammar
+ * with a type their collection declares -- i.e. exactly the set `listEntries` can see. A legacy
+ * untyped file (`overview.json`) is invisible to enumeration and is deliberately NOT probed here;
+ * see `.claude/future-tasks/legacy-untyped-files-url-addressable.md`.
+ */
+import { flattenSchema } from './config/index.js';
+import { findDuplicateUrlPaths } from './static/index.js';
+import { computeEntryUrl } from './utils/entry-url.js';
+/** Append raw segments to a URL base, without normalizing their case (see buildProbeUrls). */
+const joinUrl = (base, ...segments) => (base === '/' ? '' : base) + segments.map((s) => `/${s}`).join('');
+/**
+ * Every URL adjacent to the published set that the resolver would actually attempt.
+ *
+ * Three families, each one a shape that HAS resolved at some point in this package's history:
+ *
+ * 1. `/<collection>/<entryTypeName>` -- `resolveUrlPathCandidates`' index-fallback candidate lands
+ *    on a registered entry-TYPE schema item, which `ContentStore.buildPaths` delegates to the
+ *    parent collection with slug `index`, resolving that collection's index entry.
+ * 2. `/<collection>/<entryTypeName>/<slug>` -- the same delegation reached through the
+ *    DIRECT-entry candidate instead, resolving the collection's entry `<slug>`. Wider than family
+ *    1: it needs no index entry at all, so it applies to every listed entry.
+ * 3. `/<publishedUrl>/index`, and its case variants -- an index entry answering at the literal
+ *    spelling its collapsed URL replaced.
+ *
+ * Entry-type names are appended VERBATIM, after `computeEntryUrl` has lowercased the collection
+ * part. That asymmetry is real, not sloppiness: `flattenSchema` puts `entryType.name` into the
+ * logical path unchanged and `normalizeFilesystemPath` does not lowercase, so only the declared
+ * spelling can reach the entry-type schema item at all. A lowercased probe would miss the schema
+ * item, return null for the wrong reason, and pass vacuously.
+ */
+export const buildProbeUrls = (schema, items, contentRoot = 'content') => {
+    const collections = flattenSchema(schema, contentRoot).filter((i) => i.type === 'collection');
+    const probes = new Set();
+    for (const collection of collections) {
+        const base = computeEntryUrl(collection.logicalPath, '', contentRoot);
+        for (const entryType of collection.entries ?? []) {
+            // Family 1.
+            probes.add(joinUrl(base, entryType.name));
+            // Family 2 -- every listed entry of this collection, under every type name the collection
+            // declares (not just the entry's OWN type: the directory scan `buildPaths` runs matches on
+            // slug alone, so any declared name reaches any entry).
+            for (const item of items) {
+                if (String(item.collectionPath) !== String(collection.logicalPath))
+                    continue;
+                probes.add(joinUrl(base, entryType.name, item.slug));
+            }
+        }
+    }
+    // Family 3.
+    for (const item of items) {
+        for (const spelling of ['index', 'Index', 'INDEX']) {
+            probes.add(joinUrl(item.urlPath, spelling));
+        }
+    }
+    return [...probes];
+};
+/**
+ * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for what each field means and
+ * `buildProbeUrls` for which URLs are probed.
+ *
+ * A probe whose LOWERCASED form is published is skipped rather than asserted on: a collection
+ * literally named `index` publishes `/docs/index`, which family 3 also generates, and whether
+ * `/docs/Index` should resolve is a separate, pre-existing question about collection-path case
+ * sensitivity that this invariant does not speak to.
+ */
+export const collectUrlExclusivityReport = async (ctx, schema, contentRoot = 'content') => {
+    const items = await ctx.listEntries();
+    const unresolved = [];
+    const mismatched = [];
+    for (const item of items) {
+        const result = await ctx.readByUrlPath(item.urlPath);
+        if (!result) {
+            unresolved.push(item.urlPath);
+            continue;
+        }
+        if (result.meta.entryId !== item.entryId) {
+            mismatched.push({
+                urlPath: item.urlPath,
+                expectedEntryId: item.entryId,
+                actualEntryId: result.meta.entryId,
+            });
+        }
+    }
+    const publishedLower = new Set(items.map((i) => i.urlPath.toLowerCase()));
+    const probes = buildProbeUrls(schema, items, contentRoot);
+    const phantoms = [];
+    for (const probe of probes) {
+        if (publishedLower.has(probe.toLowerCase()))
+            continue;
+        if (await ctx.readByUrlPath(probe))
+            phantoms.push(probe);
+    }
+    return {
+        published: items.map((i) => i.urlPath).sort(),
+        duplicates: findDuplicateUrlPaths(items),
+        unresolved: unresolved.sort(),
+        mismatched,
+        probes: [...probes].sort(),
+        phantoms: phantoms.sort(),
+    };
+};

package/dist/url-path-resolver.js

@@ -34,10 +34,14 @@ export function resolveUrlPathCandidates(urlPath, contentRoot) {
     // `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.
+    // This closes the `.../index` spelling only. The other extra URLs an entry answered at —
+    // `/<collection>/<entryTypeName>` via candidate 2, and `/<collection>/<entryTypeName>/<slug>`
+    // via candidate 1 — are closed DOWNSTREAM instead, by `readByUrlPath` requiring every
+    // candidate's `entryPath` to be a collection (`ReadContentInput.urlAddressableOnly`). They have
+    // to be: telling those apart needs the branch's schema, and this module is deliberately pure
+    // and schema-free so that the candidate shapes stay a fact about URLs rather than about
+    // content. The consequence to keep in mind when reading this file: the candidates below are
+    // what is ATTEMPTED, not what can resolve.
     //
     // Compared case-INSENSITIVELY, through the shared `isIndexSlug`. This function is the one
     // consumer that sees a raw, un-normalized URL segment — everything downstream lowercases

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.0.65",
+  "version": "0.0.66-int.81",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {