canopycms 0.0.64 → 0.0.66-int.81

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/dev-content-watcher.d.ts

@@ -15,6 +15,14 @@
  *
  * All logic lives here in the core package; framework adapters just call startDevContentWatcher() once
  * at dev startup. See packages/canopycms-next/src/context-wrapper.ts for the Next wiring.
+ *
+ * ## Divergence is a CONDITION, not an event
+ *
+ * It stays true until someone runs `sync push`, so the two things this module has to get right are
+ * (a) not re-printing the same condition into a scrolling request log, and (b) making the one printing
+ * of it hard to scroll past. Both are handled below by `reportOnce` + the gutter formatting; see
+ * `.claude/future-tasks/dev-divergence-in-app-surface.md` for the in-app surface that would replace
+ * the terminal as the primary home for this.
  */
 import type { CanopyServices } from './services.js';
 import type { DevContentSyncMode } from './config/types.js';
@@ -28,6 +36,8 @@ export interface StartDevContentWatcherOptions {
     /** Warning sink. Defaults to console.warn. */
     warn?: (message: string) => void;
 }
+/** Test-only: dispose every armed watcher and drop all cross-module dedupe state. */
+export declare function resetDevContentWatchersForTests(): void;
 /**
  * Start watching the working-tree content directory for divergence from the served dev branch clone.
  * Returns a disposer that stops the watcher. A no-op (returns immediately) when mode is 'off', when

package/dist/dev-content-watcher.js

@@ -15,35 +15,98 @@
  *
  * All logic lives here in the core package; framework adapters just call startDevContentWatcher() once
  * at dev startup. See packages/canopycms-next/src/context-wrapper.ts for the Next wiring.
+ *
+ * ## Divergence is a CONDITION, not an event
+ *
+ * It stays true until someone runs `sync push`, so the two things this module has to get right are
+ * (a) not re-printing the same condition into a scrolling request log, and (b) making the one printing
+ * of it hard to scroll past. Both are handled below by `reportOnce` + the gutter formatting; see
+ * `.claude/future-tasks/dev-divergence-in-app-surface.md` for the in-app surface that would replace
+ * the terminal as the primary home for this.
  */
 import fsSync from 'node:fs';
 import path from 'node:path';
 import chokidar from 'chokidar';
+import pc from 'picocolors';
 import { operatingStrategy } from './operating-mode/index.js';
 import { getErrorMessage } from './utils/error.js';
 import { diffContentTrees, isContentTreeDiffEmpty } from './sync-core.js';
-const MAX_LISTED_FILES = 10;
-// Dedupe watchers by working-tree content dir so HMR re-evaluating the adapter module (which discards
-// the disposer) doesn't accumulate watchers. This module lives in canopycms/server, so its state
-// survives app-side HMR. Each new start disposes any prior watcher for the same dir.
-const activeWatchers = new Map();
+/**
+ * Per-category cap on listed files. Deliberately small: the block is a prompt to run `sync push`,
+ * not a diff viewer, and a 30-line wall of paths is exactly as easy to scroll past as a 1-line
+ * warning. Each list carries its true count, so nothing is hidden -- only elided.
+ */
+const MAX_LISTED_FILES = 5;
+/**
+ * The registry lives on `globalThis`, NOT in module scope.
+ *
+ * Next's dev server compiles the server graph per route bundle and evaluates each copy in its own
+ * module scope, so a module-level `Map` is re-created empty per bundle -- every copy then believes it
+ * is the first watcher, arms its own, and re-prints the startup warning. (The duplicated
+ * "CanopyCMS dev-auth: Auto-configured ..." line in a dev log is the same effect on a different
+ * module-level latch.) A `globalThis` property is the one thing shared across those evaluations.
+ */
+const REGISTRY_KEY = '__canopycmsDevContentWatchers__';
+function watcherRegistry() {
+    const host = globalThis;
+    const existing = host[REGISTRY_KEY];
+    if (existing)
+        return existing;
+    const created = new Map();
+    host[REGISTRY_KEY] = created;
+    return created;
+}
+/** Test-only: dispose every armed watcher and drop all cross-module dedupe state. */
+export function resetDevContentWatchersForTests() {
+    const registry = watcherRegistry();
+    for (const state of registry.values())
+        state.dispose?.();
+    registry.clear();
+}
+/**
+ * One body line of the notice block. The left gutter (rather than a full box) is deliberate: content
+ * paths are long and unpredictable, and a right border would force either wrapping math or truncation
+ * of the very filenames the block exists to name.
+ */
+function body(line) {
+    const gutter = pc.yellow('|');
+    return line ? `${gutter} ${line}` : gutter;
+}
 function formatList(label, files) {
     if (files.length === 0)
-        return null;
-    const shown = files.slice(0, MAX_LISTED_FILES).join(', ');
-    const extra = files.length > MAX_LISTED_FILES ? `, …(+${files.length - MAX_LISTED_FILES} more)` : '';
-    return `  ${label}: ${shown}${extra}`;
+        return [];
+    const shown = files.slice(0, MAX_LISTED_FILES);
+    const lines = [body(pc.bold(`${label} (${files.length})`)), ...shown.map((f) => body(`  ${f}`))];
+    if (files.length > shown.length) {
+        lines.push(body(pc.dim(`  +${files.length - shown.length} more`)));
+    }
+    return lines;
 }
 function formatDivergenceWarning(branch, diff) {
-    const lines = [
-        `CanopyCMS: working-tree content has diverged from the dev branch clone "${branch}" — the dev ` +
-            'server is serving stale content. Run `npx canopycms sync push` to update it ' +
-            "(set dev.contentSync: 'off' to silence this).",
-        formatList('changed', diff.changed),
-        formatList('only in working tree', diff.added),
-        formatList('only in branch clone', diff.removed),
-    ].filter((line) => line !== null);
-    return lines.join('\n');
+    const total = diff.changed.length + diff.added.length + diff.removed.length;
+    // Blank lines top and bottom: the block's job is to be findable in a scrolling request log, and
+    // whitespace separation does more for that than any amount of in-block decoration.
+    return [
+        '',
+        `${pc.bgYellow(pc.black(' CanopyCMS '))} ${pc.bold(pc.yellow('working-tree content has diverged'))}`,
+        body(`The dev server is serving ${pc.bold('stale content')}: ${total} file(s) differ from the`),
+        body(`dev branch clone "${branch}".`),
+        body(''),
+        ...formatList('changed', diff.changed),
+        ...formatList('only in working tree', diff.added),
+        ...formatList('only in branch clone', diff.removed),
+        body(''),
+        body(`Fix:     ${pc.bold('npx canopycms sync push')}`),
+        body(pc.dim("Silence: set dev.contentSync: 'off' in your Canopy config")),
+        '',
+    ].join('\n');
+}
+function formatResolvedNotice(branch) {
+    return [
+        '',
+        `${pc.bgGreen(pc.black(' CanopyCMS '))} ${pc.green(`working-tree content is back in sync with "${branch}"`)}`,
+        '',
+    ].join('\n');
 }
 /**
  * Start watching the working-tree content directory for divergence from the served dev branch clone.
@@ -73,6 +136,27 @@ export function startDevContentWatcher(services, options = {}) {
         services.config.defaultActiveBranch ??
         services.config.defaultBaseBranch ??
         'main';
+    const registry = watcherRegistry();
+    let state = registry.get(workingTreeContentDir);
+    if (!state) {
+        state = { dispose: null, lastMessage: null, reportedDivergence: false };
+        registry.set(workingTreeContentDir, state);
+    }
+    const watcherState = state;
+    // Dispose any prior watcher for this dir (HMR re-start) before creating a new one. The registry
+    // ENTRY deliberately survives, carrying lastMessage/reportedDivergence into the new watcher.
+    watcherState.dispose?.();
+    /**
+     * Emit `message` unless it is verbatim what was emitted last for this directory. Covers the
+     * divergence block, the resolved notice and the error paths alike: in every case a repeat means
+     * "the condition is unchanged", which the reader already knows.
+     */
+    const reportOnce = (message) => {
+        if (watcherState.lastMessage === message)
+            return;
+        watcherState.lastMessage = message;
+        warn(message);
+    };
     let running = false;
     let pending = false;
     const check = async () => {
@@ -84,16 +168,26 @@ export function startDevContentWatcher(services, options = {}) {
         try {
             const branch = resolveBranch();
             const branchContentDir = path.join(strategy.getContentBranchRoot(branch, sourceRoot), contentRoot);
-            // No branch clone yet (e.g. before the first editor/dev request created it) → nothing to compare.
+            // No branch clone yet (e.g. before the first editor/dev request created it) -> nothing to
+            // compare. Deliberately leaves reportedDivergence alone: "cannot tell" is not "resolved".
             if (!fsSync.existsSync(branchContentDir))
                 return;
             const diff = await diffContentTrees(workingTreeContentDir, branchContentDir);
-            if (isContentTreeDiffEmpty(diff))
+            if (isContentTreeDiffEmpty(diff)) {
+                // Close the loop: a condition that was announced needs its retraction announced too, or the
+                // reader is left believing the dev server is still serving stale content.
+                if (watcherState.reportedDivergence) {
+                    watcherState.reportedDivergence = false;
+                    reportOnce(formatResolvedNotice(branch));
+                }
                 return;
-            warn(formatDivergenceWarning(branch, diff));
+            }
+            // Set BEFORE reporting so a deduped repeat still leaves the condition marked as outstanding.
+            watcherState.reportedDivergence = true;
+            reportOnce(formatDivergenceWarning(branch, diff));
         }
         catch (err) {
-            warn(`CanopyCMS: dev content-sync check failed: ${getErrorMessage(err)}`);
+            reportOnce(`CanopyCMS: dev content-sync check failed: ${getErrorMessage(err)}`);
         }
         finally {
             running = false;
@@ -103,22 +197,19 @@ export function startDevContentWatcher(services, options = {}) {
             }
         }
     };
-    // Dispose any prior watcher for this dir (HMR re-start) before creating a new one.
-    activeWatchers.get(workingTreeContentDir)?.();
     const watcher = chokidar.watch(workingTreeContentDir, { ignoreInitial: true });
     watcher.on('add', () => void check());
     watcher.on('change', () => void check());
     watcher.on('unlink', () => void check());
     // Handle watcher errors (e.g. inotify ENOSPC/EMFILE) so an unhandled 'error' event can't crash dev.
-    watcher.on('error', (err) => warn(`CanopyCMS: dev content-sync watcher error: ${getErrorMessage(err)}`));
+    watcher.on('error', (err) => reportOnce(`CanopyCMS: dev content-sync watcher error: ${getErrorMessage(err)}`));
     // Initial divergence check at startup.
     void check();
     const dispose = () => {
         void watcher.close();
-        if (activeWatchers.get(workingTreeContentDir) === dispose) {
-            activeWatchers.delete(workingTreeContentDir);
-        }
+        if (watcherState.dispose === dispose)
+            watcherState.dispose = null;
     };
-    activeWatchers.set(workingTreeContentDir, dispose);
+    watcherState.dispose = dispose;
     return dispose;
 }

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

@@ -339,7 +339,16 @@ export async function recoverOrphanedTasks(taskDir, maxAgeMs = 5 * 60_000, logge
 export async function cleanupOldTasks(taskDir, maxAgeMs = 30 * 24 * 60 * 60_000, logger = nullLogger) {
     const now = Date.now();
     let cleaned = 0;
-    for (const subdir of ['completed', 'failed']) {
+    // `corrupt` included: unparseable task files are quarantined there by
+    // dequeue and orphan recovery and surfaced in admin listing, but the
+    // retention sweep never covered the directory, so it grew forever with
+    // deletion available only as a manual per-file admin action. Any recurring
+    // producer of malformed task JSON -- a partial write surviving a crash, a
+    // bad deploy writing schema-drifted tasks for a week -- accumulated files no
+    // automated path removed. Same stamp-based retention as the other two: a
+    // quarantined file older than the window has long since been triaged or
+    // forgotten.
+    for (const subdir of ['completed', 'failed', 'corrupt']) {
         const dir = path.join(taskDir, subdir);
         let files;
         try {

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(),
+    };
+};