canopycms 0.0.67-int.90 → 0.0.67

package/dist/types.d.ts

@@ -7,9 +7,9 @@ export type CanopyGroupId = string;
  * rule is expressed.
  *
  * There is deliberately no separate 'locked' state: 'submitted' already means
- * "locked while a reviewer looks at the PR", and request-changes/withdraw are
- * the unlocks. A future admin-freeze feature should reintroduce a status only
- * alongside real semantics (worker rebase skip list, a set/unset endpoint, UI).
+ * "locked while the PR is under review", with request-changes/withdraw as the
+ * unlocks. A future admin-freeze feature should add a status only alongside real
+ * semantics (worker rebase skip list, a set/unset endpoint, UI).
  */
 export type BranchStatus = 'editing' | 'submitted' | 'approved' | 'archived';
 export type SyncStatus = 'synced' | 'pending-sync' | 'sync-failed';
@@ -40,15 +40,14 @@ export interface BranchMetadata {
     /** ContentIds of entries where --theirs was applied during rebase; cleared on clean rebase */
     conflictFiles?: ContentId[];
     /**
-     * Lifecycle state of the branch's PR as last observed by the worker's
-     * merge-poll (or verified by markAsMerged). Absent until a PR exists and
-     * has been observed. Draft PRs read 'open'.
+     * Lifecycle state of the branch's PR as last observed by the worker's merge-poll
+     * (or verified by markAsMerged). Absent until a PR exists and has been observed.
+     * Draft PRs read 'open'.
      */
     pullRequestState?: PullRequestState;
     /**
-     * ISO timestamp stamped when the branch was archived because its PR
-     * merged (worker auto-poll or manual markAsMerged). Absent for branches
-     * archived any other way.
+     * ISO timestamp stamped when the branch was archived because its PR merged
+     * (worker auto-poll or markAsMerged). Absent for branches archived any other way.
      */
     mergedAt?: string;
     /**
@@ -62,30 +61,29 @@ export interface BranchMetadata {
         lastAt: string;
     };
     /**
-     * Set by the worker's rebase loop when it rewrote history this deployment
-     * had ALREADY published: the commit `remote.git` (and therefore GitHub)
-     * held for this branch, which the rebase replaced.
+     * Set by the worker's rebase loop when it rewrote history this deployment had
+     * ALREADY published: the commit `remote.git` (and therefore GitHub) held for
+     * this branch, which the rebase replaced.
      *
-     * Used as the `--force-with-lease` expected value on both hops, so a forced
-     * push can only ever move a ref off the exact commit our own rebase rewrote
-     * away -- never over anyone else's work.
+     * It is the `--force-with-lease` expected value on both hops, so a forced push
+     * can only move a ref off the exact commit our own rebase rewrote away, never
+     * over anyone else's work.
      *
-     * Set once per rewrite episode and never advanced while still set: across
-     * two rebases before any push lands, GitHub still holds the ORIGINAL
-     * commit, so advancing the marker would aim the lease at a commit GitHub
-     * never had. Cleared only once GitHub is confirmed to hold something else
-     * (CmsWorker.pushBranchToGitHub) -- while it is set, it is the sole trigger
-     * for the rebase loop's self-heal pass.
+     * Set once per rewrite episode and never advanced while still set: across two
+     * rebases before any push lands GitHub still holds the ORIGINAL commit, so
+     * advancing the marker would aim the lease at a commit GitHub never had.
+     * Cleared only once GitHub is confirmed to hold something else
+     * (CmsWorker.pushBranchToGitHub); while set, it is the sole trigger for the
+     * rebase loop's self-heal pass.
      */
     historyRewrittenFrom?: string;
     /**
-     * Short, sanitized reason the worker's last GitHub sync task failed
-     * permanently (set alongside `syncStatus: 'sync-failed'` by
-     * CmsWorker.updateBranchMetadataOnFailure) -- e.g. a non-fast-forward push
-     * rejection naming the branch. Absent until a task has failed permanently.
-     * Cleared on the next successful sync task (CmsWorker.updateBranchMetadata
-     * explicitly resets it to undefined) so a stale reason never survives a
-     * later successful push.
+     * Short, sanitized reason the worker's last GitHub sync task failed permanently,
+     * set alongside `syncStatus: 'sync-failed'` by
+     * CmsWorker.updateBranchMetadataOnFailure -- e.g. a non-fast-forward push
+     * rejection naming the branch. Absent until a task has failed permanently, and
+     * reset to undefined by the next successful sync task, so a stale reason never
+     * survives a later successful push.
      */
     syncFailureReason?: string;
 }
@@ -105,9 +103,9 @@ export interface BranchContextWithSchema extends BranchContext {
     flatSchema: import('./config/index.js').FlatSchemaItem[];
 }
 /**
- * Wire shape of the worker's self-reported status file (worker-status.json,
- * written under the task queue dir). Written by the CmsWorker daemon
- * (PR-W1); this type is read-only here — GET /admin/status parses it as-is.
+ * Wire shape of the worker's self-reported status file (worker-status.json, under
+ * the task queue dir), written by the CmsWorker daemon. Read-only here: GET
+ * /admin/status parses it as-is.
  */
 export interface WorkerStatusReport {
     version: 1;
@@ -126,12 +124,9 @@ export interface WorkerStatusReport {
         skippedDirty: string[];
         /**
          * [SYNC-C1] Branches skipped because a content write held the branch's
-         * cross-host content-write lock (utils/content-write-lock.ts) -- the
-         * worker yields and retries next cycle.
-         *
-         * Optional for the same reason as `tracked` below: absent from a
-         * worker-status.json written by a worker predating that lock. Readers must
-         * tolerate its absence.
+         * cross-host content-write lock (utils/content-write-lock.ts); the worker
+         * yields and retries next cycle. Optional for the same reason as `tracked`
+         * below, and readers must tolerate its absence.
          */
         skippedLocked?: string[];
         failed: {
@@ -139,15 +134,11 @@ export interface WorkerStatusReport {
             error: string;
         }[];
         /**
-         * Outcome of reconciling remote.git's `refs/heads/*` against GitHub's
-         * fetched tips (worker/git-sync.ts's `reconcileTrackedBranches`) --
-         * the non-destructive replacement for the old fetch refspec that used
-         * to write GitHub's refs directly into `refs/heads/*`.
-         */
-        /**
-         * Optional: absent from a worker-status.json written by a worker that
-         * predates the tracked-branch reconcile (PR #168). Readers must tolerate
-         * its absence rather than assume every status file has it.
+         * Outcome of reconciling remote.git's `refs/heads/*` against GitHub's fetched
+         * tips, non-destructively (worker/git-sync.ts's `reconcileTrackedBranches`).
+         * Optional: a status file written by a worker without that reconcile has no
+         * such key, and readers must tolerate its absence rather than assume every
+         * status file has it.
          */
         tracked?: {
             created: string[];
@@ -155,11 +146,9 @@ export interface WorkerStatusReport {
             ahead: string[];
             diverged: string[];
             /**
-             * Optional for the same reason as `tracked` itself: absent from a
-             * status file written before the rebase loop began publishing rewritten
-             * history. Branches here diverged from GitHub because THIS worker
-             * rebased them and the GitHub push is still queued -- expected and
-             * self-resolving, unlike `diverged`.
+             * Optional for the same reason as `tracked` itself. Branches here diverged
+             * from GitHub because THIS worker rebased them and the GitHub push is still
+             * queued -- expected and self-resolving, unlike `diverged`.
              */
             rewritten?: string[];
         };

package/dist/url-collision.d.ts

@@ -3,48 +3,36 @@
  *
  * 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.
+ * merge, PR, direct commit and retrofit of an existing repo — none of which pass this boundary —
+ * while the build guard cannot help an editor about to author the collision right now. A SCHEMA
+ * edit alone can create one with no content write at all: `updateEntryType` changing a format
+ * changes the listing's `validExts`, which can turn a `guide.index.{id}.json` the listing skipped
+ * into a published entry, and so into a contested pair.
  *
  * 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.
+ *   content/docs/page.guides.{id}.json + content/docs/guides.{id}/  (no index)  -> fine: a
+ *     landing page plus a folder of children, both reachable, nothing contested.
+ *   content/docs/page.guides.{id}.json + content/docs/guides.{id}/doc.index.{id}.md -> contested:
+ *     both compute /docs/guides, so exactly one is reachable and the other 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`).
+ * A name-collision rule would forbid the first, 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 the on-disk names carry the content IDs logical paths hide (`guides.{id}/`).
  *
  * 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.
+ * `computeEntryUrl` derives and `listEntries` publishes -- not "every URL the site serves".
+ * Hand-written adopter routes, and a sitemap `<loc>` a framework adapter rewrites after
+ * enumeration (`generateContentSitemap`'s `pathFor`), are invisible here by design: at write time
+ * there is no filesystem state to check them against.
  */
 /** 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.
+     * Which of the two shapes was found. Callers word their own message from this: 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. */
@@ -53,11 +41,10 @@ export interface UrlPathClaimant {
     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.
+ * The index entry file directly inside `dir`, or null. Slug extraction is entry-type-agnostic
+ * (each candidate's type is read out of its own filename), so an index entry of ANY type counts —
+ * like the same-slug guard, 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. */
@@ -69,11 +56,10 @@ export declare function findEntryBySlugIn(dir: string, slug: string): Promise<st
  * 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.
+ * conflict), so re-checking it would be 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.
+ * Two directory reads at worst, and only on create/rename — an ordinary save never calls this,
+ * because the entry's URL is not changing and any collision 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

package/dist/url-collision.js

@@ -8,18 +8,16 @@ 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.
+ * case-sensitively (`d.name.endsWith(ext)` against lowercase extensions). Lowercasing here makes
+ * the guard looser than the listing: a `doc.index.{id}.MD` file would count as a claimant while
+ * the listing skips 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
+ * KNOWN RESIDUAL LOOSENESS: the listing accepts only the extensions of a collection's OWN
+ * configured entry-type formats, while this accepts all four, so a hand-authored
+ * `doc.index.{id}.json` inside an md-only collection claims no URL yet still blocks a sibling
+ * write. Closing it means threading each collection's configured formats into a deliberately
+ * schema-free module; 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
@@ -55,53 +53,44 @@ async function findChildCollectionDir(dir, name) {
  *
  * 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.
+ * half checks those. Hence `parseTypedFilename` — the same `{type}.{slug}.{id}.{ext}` grammar
+ * `listCollectionEntries` uses — rather than `extractSlugFromFilename`, which answers the much
+ * looser "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.
+ * `index.md` with no content ID, an `index.md~` editor backup or a colocated `guides.png` are
+ * non-entries that claim no URL, so the build guard ignores them — but a looser scan counts them
+ * as claimants and refuses a legitimate write, telling the author to "remove that collection's
+ * index entry" about a file Canopy does not consider an entry. Worst for retrofitted repos.
  *
- * 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:
+ * The claimant set is nonetheless a strict superset of the listing's in three ways, all
+ * over-blocking and all needing the same fix — the schema this module deliberately does not have
+ * — so they are one task (.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;
+ *   2. entry TYPE — parsing is structural (no `entryTypes` list), so a file whose type is not in
+ *      the collection's config is skipped by the listing but counted here. In the editor, where
+ *      this guard runs, the listing skips such a file with a debug-gated warning and nothing
+ *      surfaces; only a BUILD reports it. Reached by renaming an entry type in `.collection.json`
+ *      without renaming the files — the accident `looksLikeMalformedEntry` names as most common;
  *   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.
+    // additionally requires a configured format extension, so this must skip those 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.
+ * The index entry file directly inside `dir`, or null. Slug extraction is entry-type-agnostic
+ * (each candidate's type is read out of its own filename), so an index entry of ANY type counts —
+ * like the same-slug guard, 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)) {
@@ -130,11 +119,10 @@ export async function findEntryBySlugIn(dir, slug) {
  * 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.
+ * conflict), so re-checking it would be 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.
+ * Two directory reads at worst, and only on create/rename — an ordinary save never calls this,
+ * because the entry's URL is not changing and any collision 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
@@ -150,16 +138,13 @@ export async function findUrlPathClaimant(opts) {
             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.
+        // A collection literally NAMED "index" collapses onto ITS OWN path (`<parentPath>/index`), not
+        // onto `<parentPath>` -- see `computeEntryUrl`. The only entry that could contest it is a
+        // parent entry whose slug is also "index", but by that same forward rule such an entry IS the
+        // parent's own landing entry, at `<parentPath>`, a different URL. Nothing in the parent can
+        // claim `<parentPath>/index`, so skip the lookup rather than let it match the parent's index
+        // entry and report a collision that does not exist -- otherwise a collection named "index"
+        // could never have a landing page under a parent that has one of its own.
         if (isIndexSlug(ownName))
             return null;
         const claimant = await findEntryBySlugIn(parentDir, ownName);
@@ -168,14 +153,13 @@ export async function findUrlPathClaimant(opts) {
     // 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.
+    // likewise looks only for a parent ENTRY. Neither considers a second collection sharing the same
+    // name, because nothing stops one being created -- `createCollectionInner` does not check
+    // sibling names (tracked in collection-sibling-name-uniqueness.md). With two `guides.{id}`
+    // directories side by side, an index entry can be written into each: both writes pass this
+    // guard, two entries claim one URL, and only the build guard catches it. Fixing sibling-name
+    // uniqueness closes this without changing anything here, so that task is a prerequisite for
+    // this guard being complete.
     const childDir = await findChildCollectionDir(collectionDir, slug);
     if (!childDir)
         return null;

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

@@ -2,22 +2,18 @@
  * 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.
+ * `readByUrlPath` as safe. The reverse direction is the looser of the two and can answer at URLs
+ * no forward surface emits, so this module asserts the whole invariant at once: 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
+ * Deliberately free of `vitest` -- 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
+ * with a type their collection declares -- 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`.
  */
@@ -26,9 +22,8 @@ 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:
+ * Every URL adjacent to the published set that the resolver would actually attempt, in three
+ * families:
  *
  * 1. `/<collection>/<entryTypeName>` -- `resolveUrlPathCandidates`' index-fallback candidate lands
  *    on a registered entry-TYPE schema item, which `ContentStore.buildPaths` delegates to the
@@ -40,16 +35,16 @@ import { type DuplicateUrlPath } from './static/index.js';
  *    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.
+ * part. That asymmetry is real: `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. */
+    /** URLs claimed by more than one entry. A precondition failure, not a resolver result. */
     duplicates: DuplicateUrlPath[];
     /** Published URLs `readByUrlPath` did NOT resolve -- the round trip broken going forward. */
     unresolved: string[];
@@ -65,12 +60,12 @@ export interface UrlExclusivityReport {
     phantoms: string[];
 }
 /**
- * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for what each field means and
+ * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for the fields 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.
+ * `/docs/Index` should resolve is a separate 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

@@ -2,22 +2,18 @@
  * 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.
+ * `readByUrlPath` as safe. The reverse direction is the looser of the two and can answer at URLs
+ * no forward surface emits, so this module asserts the whole invariant at once: 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
+ * Deliberately free of `vitest` -- 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
+ * with a type their collection declares -- 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`.
  */
@@ -27,9 +23,8 @@ 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:
+ * Every URL adjacent to the published set that the resolver would actually attempt, in three
+ * families:
  *
  * 1. `/<collection>/<entryTypeName>` -- `resolveUrlPathCandidates`' index-fallback candidate lands
  *    on a registered entry-TYPE schema item, which `ContentStore.buildPaths` delegates to the
@@ -41,10 +36,10 @@ const joinUrl = (base, ...segments) => (base === '/' ? '' : base) + segments.map
  *    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.
+ * part. That asymmetry is real: `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');
@@ -73,13 +68,13 @@ export const buildProbeUrls = (schema, items, contentRoot = 'content') => {
     return [...probes];
 };
 /**
- * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for what each field means and
+ * Enumerate, round-trip, then probe. See `UrlExclusivityReport` for the fields 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.
+ * `/docs/Index` should resolve is a separate 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();

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

@@ -1,23 +1,15 @@
 /**
- * Resolves a URL path to candidate entryPath/slug pairs for content lookup.
+ * Resolve a URL path to the candidate entryPath/slug pairs a lookup should try, in order:
  *
- * Returns an ordered list of attempts:
- * 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'
+ * 1. Direct entry: last segment is the slug, the rest is the collection path — SKIPPED when that
+ *    slug is an index slug (see below).
+ * 2. Index fallback: the whole path is a collection and the 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
+ * This is the REVERSE of the forward collection+slug -> url rule and must agree with it about how
+ * many URLs an entry answers at. The forward rule — `computeEntryUrl` (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
+ * reference, plus `defaultBuildPath` (content-tree.ts) for tree nodes — collapses an `index` slug
+ * onto its collection's path and never emits a trailing `/index`.
  */
 export declare function resolveUrlPathCandidates(urlPath: string, contentRoot: string): Array<{
     entryPath: string;