@erclx/canon 4.72.1 → 4.74.0

package/src/records/backup.ts

@@ -1,12 +1,12 @@
 import { existsSync } from 'node:fs'
-import { join, relative, resolve } from 'node:path'
+import { basename, join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 import { RECORD_ROOTS, recordRoot } from '@/record-root'
 
 /**
  * The folders a backup carries, relative to the record root `workTree` resolves
- * rather than to either root specifically, since the same nine names sit under
+ * rather than to either root specifically, since the same ten names sit under
  * whichever one a tree holds.
  *
  * Nothing bounds this list any more, and the move is what took the bound away.
@@ -18,12 +18,12 @@ import { RECORD_ROOTS, recordRoot } from '@/record-root'
  * a name is written here.
  *
  * Three counts describe this surface and each is right about a different
- * question, so they are stated apart rather than reconciled. Nine is what a
- * disk loss would take, which is this list. Eleven is what sat under `.claude/`
+ * question, so they are stated apart rather than reconciled. Ten is what a
+ * disk loss would take, which is this list. Twelve is what sat under `.claude/`
  * as an ignored folder before the move, which adds the scratch folder that is
  * deletable without loss and `worktrees/`, whose contents belong to the
- * enclosing repository already. Twelve is what the move relocated, which counts
- * ignore entries rather than folders: the eleven less `worktrees/`, which stayed,
+ * enclosing repository already. Thirteen is what the move relocated, which counts
+ * ignore entries rather than folders: the twelve less `worktrees/`, which stayed,
  * plus `.records.git/` and the `README.md` a records pull writes back.
  *
  * Each entry is a top-level record folder and every archive sits inside the one
@@ -46,6 +46,7 @@ export const BACKED_FOLDERS = [
   'review',
   'tasks',
   'teach',
+  'transcripts',
 ] as const
 
 /**
@@ -88,8 +89,46 @@ function recordsGitDir(root: string): string {
   return join(workTree(root), RECORDS_GIT_NAME)
 }
 
-/** Both directions name the branch, so a machine whose `init.defaultBranch` differs still lands on it. */
-const RECORDS_BRANCH = 'main'
+/**
+ * A run of characters outside what git accepts in a ref segment, replaced
+ * with a single dash, with a leading or trailing `/` or `.` trimmed after.
+ */
+function sanitizeRefSegment(segment: string): string {
+  return segment
+    .replace(/[^a-z0-9_./-]+/g, '-')
+    .replace(/^[/.]+/, '')
+    .replace(/[/.]+$/, '')
+}
+
+/**
+ * The branch a records push or pull targets for the project at `root`,
+ * one branch per project on the shared records repository.
+ *
+ * Reduces the project's own `origin` through the same `remoteIdentity`
+ * reduction the shared-origin gate already applies, so two clones of the
+ * same project land on the same branch regardless of transport. Falls back
+ * to the project directory's own basename for a project with no `origin`,
+ * such as a fresh scaffold, which is no worse than the single shared branch
+ * this replaces: nothing else here distinguishes two such clones either.
+ *
+ * `enclosing` is `pushRecords`/`pullRecords`'s own already-fetched remote
+ * read, reused here rather than shelled out for a second time. A caller with
+ * none, such as a test reading this in isolation, gets one read of its own.
+ *
+ * A project's `origin` can change (rename, fork, transfer) between one push
+ * and the next, which silently starts writing to a new branch and orphans
+ * whatever was left on the old one. No migration handles that today.
+ */
+export async function projectBranch(
+  root: string,
+  enclosing?: EnclosingRemotes,
+): Promise<string> {
+  const remotes = enclosing ?? (await enclosingRemotes(root))
+  const raw = remotes?.originUrl
+    ? remoteIdentity(remotes.originUrl)
+    : basename(resolve(root)).toLowerCase()
+  return sanitizeRefSegment(raw)
+}
 
 /**
  * The records history is machine-written and nobody reads its authorship, so a
@@ -145,6 +184,7 @@ export type PullOutcome = PullReport | BackupRefused
 
 interface GitResult {
   readonly ok: boolean
+  readonly code: number
   readonly text: string
   readonly stderr: string
 }
@@ -180,6 +220,7 @@ async function records(root: string, args: string[]): Promise<GitResult> {
 
   return {
     ok: result.exitCode === 0,
+    code: result.exitCode,
     text: result.stdout.toString().trim(),
     stderr: result.stderr.toString().trim(),
   }
@@ -217,9 +258,18 @@ function remoteIdentity(url: string): string {
     .replace(/\/+$/, '')
 }
 
+interface EnclosingRemotes {
+  readonly identities: readonly string[]
+  readonly originUrl: string | undefined
+}
+
 /**
- * Lists every remote of the enclosing project, or undefined when git cannot
- * answer.
+ * Reads every remote of the enclosing project in one call, or undefined when
+ * git cannot answer.
+ *
+ * `resolveRemote`'s shared-origin gate needs every remote's identity and
+ * `projectBranch` needs specifically `origin`'s raw URL, so both read from
+ * this one call rather than each shelling out to git on its own.
  *
  * The caller refuses on undefined rather than smoothing it into an empty list.
  * An empty list clears the gate below for every URL, so a git that failed for
@@ -227,22 +277,27 @@ function remoteIdentity(url: string): string {
  * happens to name. A project with no remotes answers `0` with an exit of zero,
  * so the two states stay distinguishable.
  */
-async function enclosingRemoteUrls(
+async function enclosingRemotes(
   root: string,
-): Promise<string[] | undefined> {
+): Promise<EnclosingRemotes | undefined> {
   const result = await $`git -C ${root} remote -v`
     .env(gitEnv())
     .quiet()
     .nothrow()
   if (result.exitCode !== 0) return undefined
 
-  return result.stdout
-    .toString()
-    .split('\n')
-    .filter(Boolean)
-    .map((line) => line.split(/\s+/)[1] ?? '')
-    .filter(Boolean)
-    .map(remoteIdentity)
+  const identities: string[] = []
+  let originUrl: string | undefined
+
+  for (const line of result.stdout.toString().split('\n')) {
+    if (!line) continue
+    const [name, url] = line.split(/\s+/)
+    if (!url) continue
+    identities.push(remoteIdentity(url))
+    if (name === 'origin' && originUrl === undefined) originUrl = url
+  }
+
+  return { identities, originUrl }
 }
 
 /**
@@ -255,16 +310,20 @@ async function enclosingRemoteUrls(
  * misconfigured `origin` from publishing them, and refusing when that list
  * cannot be read is what keeps a failed comparison from reading as a pass.
  */
-async function resolveRemote(root: string): Promise<string | BackupRefused> {
+async function resolveRemote(
+  root: string,
+  enclosing: EnclosingRemotes | undefined,
+): Promise<string | BackupRefused> {
   const gitDir = recordsGitDir(root)
 
   if (!existsSync(gitDir)) {
     return refuse(
       'no-repository',
       [
-        `No records history at ${relative(root, gitDir)}. Create it once, against a private repository:`,
+        `No records history at ${relative(root, gitDir)}. One private repository backs every project on this machine, each on its own branch, so create it once, against whichever project sets it up first:`,
         `  git --git-dir=${gitDir} init`,
         `  git --git-dir=${gitDir} remote add origin <private-repo-url>`,
+        `A person commits a README to that repository's main branch once. It is never machine-written.`,
       ].join('\n'),
     )
   }
@@ -280,7 +339,6 @@ async function resolveRemote(root: string): Promise<string | BackupRefused> {
     )
   }
 
-  const enclosing = await enclosingRemoteUrls(root)
   if (!enclosing) {
     return refuse(
       'remote-unreadable',
@@ -289,7 +347,7 @@ async function resolveRemote(root: string): Promise<string | BackupRefused> {
   }
 
   const url = remoteIdentity(remote.text)
-  if (enclosing.includes(url)) {
+  if (enclosing.identities.includes(url)) {
     return refuse(
       'remote-shared',
       `The records origin ${remote.text} is a remote of this project. Records carry the memory pen and the groundwork trails, so they need a repository of their own.`,
@@ -396,7 +454,8 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   const split = refuseSplitRoots(root)
   if (split) return split
 
-  const remote = await resolveRemote(root)
+  const enclosing = await enclosingRemotes(root)
+  const remote = await resolveRemote(root, enclosing)
   if (typeof remote !== 'string') return remote
 
   const scope = await scopedFolders(root)
@@ -438,10 +497,11 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
     return { ok: true, root, folders, changed, pushed: false }
   }
 
+  const branch = await projectBranch(root, enclosing)
   const pushed = await records(root, [
     'push',
     'origin',
-    `HEAD:refs/heads/${RECORDS_BRANCH}`,
+    `HEAD:refs/heads/${branch}`,
   ])
   if (!pushed.ok) return failed('push', pushed)
 
@@ -460,26 +520,38 @@ export async function pullRecords(root: string): Promise<PullOutcome> {
   const split = refuseSplitRoots(root)
   if (split) return split
 
-  const remote = await resolveRemote(root)
+  const enclosing = await enclosingRemotes(root)
+  const remote = await resolveRemote(root, enclosing)
   if (typeof remote !== 'string') return remote
 
+  const branch = await projectBranch(root, enclosing)
+
+  // Checked ahead of the fetch rather than parsed out of a failed fetch's
+  // stderr, which is git's own message and translates on a localized
+  // machine. `--exit-code` answers through a code no locale changes: 2 for
+  // no matching ref, 0 for found, anything else for a remote git could not
+  // reach at all.
+  const remoteBranch = await records(root, [
+    'ls-remote',
+    '--exit-code',
+    'origin',
+    `refs/heads/${branch}`,
+  ])
+  if (remoteBranch.code === 2) {
+    return refuse(
+      'no-remote-records',
+      `The records origin carries no ${branch} branch yet. Run canon records push from the machine holding the records.`,
+    )
+  }
+  if (!remoteBranch.ok) return failed('ls-remote', remoteBranch)
+
   const fetched = await records(root, [
     'fetch',
     '--quiet',
     'origin',
-    `refs/heads/${RECORDS_BRANCH}`,
+    `refs/heads/${branch}`,
   ])
-  if (!fetched.ok) {
-    // A missing branch and an unreachable remote both fail the fetch, and only
-    // the first is an ordinary state a person resolves by pushing once.
-    if (fetched.stderr.includes("couldn't find remote ref")) {
-      return refuse(
-        'no-remote-records',
-        `The records origin carries no ${RECORDS_BRANCH} branch yet. Run canon records push from the machine holding the records.`,
-      )
-    }
-    return failed('fetch', fetched)
-  }
+  if (!fetched.ok) return failed('fetch', fetched)
 
   const target = await records(root, ['rev-parse', 'FETCH_HEAD'])
   if (!target.ok) return failed('rev-parse', target)

package/src/records/ordinal.ts

@@ -0,0 +1,243 @@
+import { mkdir, readdir, rm, stat } from 'node:fs/promises'
+import { extractOrdinal } from '@/intake/folder'
+import { recordDir } from '@/record-root'
+
+/**
+ * The two record folders that share one ordinal sequence, per
+ * `standards/intake.md` and `standards/groundwork.md`. A folder opened as
+ * either kind blocks the same number for the other, so the two read together
+ * rather than each keeping a count of its own.
+ */
+export const ORDINAL_KINDS = ['intake', 'groundwork'] as const
+
+export type OrdinalKind = (typeof ORDINAL_KINDS)[number]
+
+export function isOrdinalKind(value: string): value is OrdinalKind {
+  return (ORDINAL_KINDS as readonly string[]).includes(value)
+}
+
+const ORDINAL_WIDTH = 2
+
+/** Bounds the retry loop below. A fifth collision in a row is not a race. */
+const MAX_ATTEMPTS = 5
+
+/**
+ * How long a reservation with no leaf folder behind it stays live before
+ * `reserve` will clear it.
+ *
+ * An ordinary claim reserves the number and creates its leaf folder with
+ * nothing awaited in between, so it finishes in milliseconds. The threshold
+ * only has to clear that by a wide margin, not bound it tightly: reading a
+ * genuinely abandoned lock as live costs one retry, while reading one still
+ * in flight as abandoned reopens the exact duplicate this recovery exists to
+ * close, so the cost of guessing too short is the one that matters here.
+ */
+const STALE_LOCK_MS = 5 * 60 * 1000
+
+function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error
+}
+
+async function listNames(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+  } catch (error) {
+    if (isErrnoException(error) && error.code === 'ENOENT') return []
+    throw error
+  }
+}
+
+/**
+ * The highest ordinal already claimed across both `.canon/intake/` and
+ * `.canon/groundwork/`, or `0` with neither folder holding an entry.
+ */
+export async function highestOrdinal(root: string): Promise<number> {
+  const names = (
+    await Promise.all(
+      ORDINAL_KINDS.map((kind) => listNames(recordDir(root, kind))),
+    )
+  ).flat()
+
+  return names
+    .map((name) => extractOrdinal(name))
+    .filter((ordinal) => ordinal !== '')
+    .map(Number)
+    .reduce((carry, ordinal) => Math.max(carry, ordinal), 0)
+}
+
+function pad(ordinal: number): string {
+  return String(ordinal).padStart(ORDINAL_WIDTH, '0')
+}
+
+/**
+ * Where a number is reserved ahead of creating either kind's own folder.
+ *
+ * The two kinds share one sequence but not one directory, so a leaf `mkdir`
+ * under `intake/` and one under `groundwork/` never collide with each other
+ * even when both land on the same number in the same instant, which is the
+ * race this verb exists to close. Reserving the number itself, at a path both
+ * calls resolve to regardless of kind, is what makes the two contend on the
+ * same `mkdir`.
+ */
+function lockPath(root: string, ordinal: string): string {
+  return recordDir(root, 'ordinal-locks', ordinal)
+}
+
+async function isBacked(root: string, ordinal: string): Promise<boolean> {
+  const names = (
+    await Promise.all(
+      ORDINAL_KINDS.map((kind) => listNames(recordDir(root, kind))),
+    )
+  ).flat()
+
+  return names.some((name) => extractOrdinal(name) === ordinal)
+}
+
+/**
+ * `undefined` when the lock is already gone, otherwise how long ago it was
+ * created. The lock directory is never written to after its `mkdir`, so its
+ * `mtime` is its creation time.
+ */
+async function lockAgeMs(dir: string): Promise<number | undefined> {
+  try {
+    const info = await stat(dir)
+    return Date.now() - info.mtimeMs
+  } catch (error) {
+    if (isErrnoException(error) && error.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+/**
+ * `true` when a lock carries no leaf folder in either kind and is old enough
+ * that an ordinary claim could not still be in flight.
+ *
+ * No backing folder alone is not enough: `claimOrdinal` awaits the leaf
+ * `mkdir` after `reserve` returns, so a second process can observe another's
+ * lock in that exact gap, with no folder behind it yet even though the first
+ * process is seconds from creating one. Reading that gap as abandoned lets
+ * both processes land a leaf folder at the same ordinal under their own
+ * kind, which never collide with each other, reopening the race this verb
+ * exists to close. Requiring the lock to also be older than `STALE_LOCK_MS`
+ * is what keeps that window from being read as abandoned.
+ */
+async function isStale(root: string, ordinal: string): Promise<boolean> {
+  if (await isBacked(root, ordinal)) return false
+
+  const age = await lockAgeMs(lockPath(root, ordinal))
+  return age !== undefined && age >= STALE_LOCK_MS
+}
+
+/**
+ * `true` when this call won the reservation, `false` when another call holds
+ * a live one.
+ *
+ * A lock already held is read against the kind folders before it is read as
+ * contention. Reserving and creating the leaf folder are two acts rather than
+ * one, so a process killed in between leaves a lock with nothing behind it,
+ * and a caller walking that lock as ordinary contention would refuse every
+ * later claim as `ordinal-contended` on a cause that was never contention.
+ * Clearing a stale lock and retrying the same number is what keeps that dead
+ * reservation from costing every claim that follows it.
+ */
+async function reserve(root: string, ordinal: string): Promise<boolean> {
+  const locks = recordDir(root, 'ordinal-locks')
+  await mkdir(locks, { recursive: true })
+
+  const dir = lockPath(root, ordinal)
+
+  try {
+    await mkdir(dir, { recursive: false })
+    return true
+  } catch (error) {
+    if (!isErrnoException(error) || error.code !== 'EEXIST') throw error
+    if (!(await isStale(root, ordinal))) return false
+
+    await rm(dir, { recursive: true, force: true })
+
+    try {
+      await mkdir(dir, { recursive: false })
+      return true
+    } catch (retryError) {
+      if (isErrnoException(retryError) && retryError.code === 'EEXIST') {
+        return false
+      }
+      throw retryError
+    }
+  }
+}
+
+export const ORDINAL_REFUSALS = ['ordinal-contended'] as const
+
+export type OrdinalRefusal = (typeof ORDINAL_REFUSALS)[number]
+
+export interface Claimed {
+  readonly ok: true
+  readonly kind: OrdinalKind
+  readonly slug: string
+  readonly ordinal: string
+  readonly name: string
+  readonly path: string
+}
+
+export interface ClaimRefused {
+  readonly ok: false
+  readonly reason: OrdinalRefusal
+  readonly message: string
+  readonly lastOrdinal: string
+}
+
+export type ClaimOutcome = Claimed | ClaimRefused
+
+/**
+ * Computes the next ordinal and creates `.canon/<kind>/<nn>-<slug>/` in one
+ * act, so no window sits between the read and the create for a second session
+ * to land in, whichever kind that session is claiming.
+ *
+ * The reservation is what does the serializing: it is the one `mkdir` both an
+ * `intake` claim and a `groundwork` claim resolve to the same path for when
+ * they land on the same number, where the two kinds' own leaf folders never
+ * share a path and so never collide with each other directly. A losing
+ * reservation surfaces as `EEXIST`, `reserve` tells a live one from a stale
+ * one left by a process that died before its own leaf create ran, and the
+ * loser on a live one re-reads the highest ordinal and retries, bounded so a
+ * run of contention past what an ordinary race produces surfaces as a refusal
+ * instead of a longer silent retry.
+ *
+ * The kind's own leaf `mkdir` still runs with `recursive: false` once the
+ * reservation is won, since a recursive `mkdir` succeeds silently against a
+ * directory that already exists, and this call's own reservation ending up
+ * stale is exactly the case the staleness check above exists to recover.
+ */
+export async function claimOrdinal(
+  root: string,
+  kind: OrdinalKind,
+  slug: string,
+): Promise<ClaimOutcome> {
+  const parent = recordDir(root, kind)
+  await mkdir(parent, { recursive: true })
+
+  let lastOrdinal = ''
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const ordinal = pad((await highestOrdinal(root)) + 1)
+    lastOrdinal = ordinal
+
+    if (!(await reserve(root, ordinal))) continue
+
+    const name = `${ordinal}-${slug}`
+    const dir = recordDir(root, kind, name)
+    await mkdir(dir, { recursive: false })
+    return { ok: true, kind, slug, ordinal, name, path: dir }
+  }
+
+  return {
+    ok: false,
+    reason: 'ordinal-contended',
+    message: `${MAX_ATTEMPTS} claims collided in a row, last at ${lastOrdinal}. That is more than an ordinary race, so this stops rather than retrying further.`,
+    lastOrdinal,
+  }
+}

package/src/records/validate.ts

@@ -73,6 +73,7 @@ export const FINDING_KINDS = [
   'item-incomplete',
   'category-mismatch',
   'operator-call-phrasing',
+  'batch-unsplit',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -235,6 +236,18 @@ async function listFolders(dir: string): Promise<string[]> {
 
 const PLAN_NAME = /^feature-[a-z0-9]+(-[a-z0-9]+)*\.md$/
 const PLAN_TITLE = /^#[ \t]+Feature:[ \t]+\S/
+const BATCH_LABEL = /^\*\*Batch\s+\d+\b.*\*\*/i
+
+/**
+ * Reads the raw text rather than `splitPlanSections`'s output, since a
+ * colon-bearing `**Batch 1: ...**` line is itself a `MARKER_LINE` and is
+ * already dropped from the split `Files to touch` section before any check
+ * sees it.
+ */
+export function hasStagedBatches(text: string): boolean {
+  return linesOutsideFences(text).some((line) => BATCH_LABEL.test(line.trim()))
+}
+
 /**
  * An entry names a file and says something about it. Both halves are tested as
  * facts rather than as a syntax: a backticked span anywhere, and prose left over
@@ -463,6 +476,21 @@ export function checkPlan(name: string, text: string): Finding[] {
 
   findings.push(...checkQuestionContract(name, sections.get('Questions') ?? []))
 
+  if (hasStagedBatches(text)) {
+    const staged = linesOutsideFences(text).find((line) =>
+      BATCH_LABEL.test(line.trim()),
+    )
+
+    findings.push(
+      finding(
+        'batch-unsplit',
+        name,
+        shorten((staged ?? '').trim()),
+        "stages a batch inside one file, so the batch sharing this plan's branch has nothing left to open a pull request against once an earlier one merges. Split it into one plan file per batch.",
+      ),
+    )
+  }
+
   return findings
 }
 

package/src/surface-root.ts

@@ -0,0 +1,101 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The roots a tracked toolkit surface is read at, in precedence order.
+ *
+ * These are not `RECORD_ROOTS`, and the difference is what each root is for
+ * rather than an oversight. A record folder moves into `.canon/` because it is
+ * gitignored, so nothing tracked ever lands there. A surface here is committed,
+ * so a single shared list would put a record folder under a root a tracked
+ * file also resolves against, which is a collision this list never has to
+ * consider on its own.
+ *
+ * `canon` wins because a tree that carries it has moved, and reading `.claude/`
+ * there would answer from the copy the move left behind. Read precedence
+ * agreeing with the eventual creation default means the flip a later batch
+ * takes changes one line rather than two.
+ */
+export const SURFACE_ROOTS = ['canon', '.claude'] as const
+
+export type SurfaceRoot = (typeof SURFACE_ROOTS)[number]
+
+/**
+ * The root a surface is created at when neither root carries it yet.
+ *
+ * Disagreeing with the head of the read order for exactly one release: read
+ * precedence is new-first so a tree that has moved is never answered from the
+ * copy left behind, while creation stays at the old root so nothing writes a
+ * fresh tracked file under a root a target's installed binary may not resolve
+ * yet. A later batch flips this once a release carries the read side.
+ */
+export const CREATION_ROOT: SurfaceRoot = '.claude'
+
+/**
+ * Every tracked surface this module resolves, at the name `.claude/` gives it.
+ *
+ * `canon` names the stamp folder rather than the CLI itself, which is the one
+ * entry `spell` respells per root.
+ */
+export const SURFACE_ENTRIES: readonly string[] = [
+  'ARCHITECTURE.md',
+  'REQUIREMENTS.md',
+  'DESIGN.md',
+  'context',
+  'wireframes',
+  'canon',
+]
+
+/**
+ * How a root spells an entry name. Only the stamp folder differs, since a
+ * project under `canon/` reserves the bare name for the CLI's own install
+ * rather than for its config.
+ */
+export function spell(root: SurfaceRoot, entry: string): string {
+  return root === 'canon' && entry === 'canon' ? 'config' : entry
+}
+
+/**
+ * The root a surface resolves at: the first that carries it, and the creation
+ * default when neither does.
+ */
+function rootOf(root: string, entry: string): SurfaceRoot {
+  return (
+    SURFACE_ROOTS.find((candidate) =>
+      existsSync(join(root, candidate, spell(candidate, entry))),
+    ) ?? CREATION_ROOT
+  )
+}
+
+/**
+ * Where a tracked surface is read.
+ *
+ * `entry` is the surface itself and `rest` is whatever sits inside it, so a
+ * caller spells no root and no per-root naming variant of its own.
+ */
+export function surfaceDir(
+  root: string,
+  entry: string,
+  ...rest: string[]
+): string {
+  const at = rootOf(root, entry)
+  return join(root, at, spell(at, entry), ...rest)
+}
+
+/**
+ * Every root a surface would be read at, in precedence order, whether or not
+ * it is on disk.
+ *
+ * Containment tests take this rather than `surfaceDir`, since a path written
+ * against the root a tree no longer uses is still a path into that surface,
+ * and reading it as outside would report a live reference as stale.
+ */
+export function surfaceDirs(
+  root: string,
+  entry: string,
+  ...rest: string[]
+): string[] {
+  return SURFACE_ROOTS.map((candidate) =>
+    join(root, candidate, spell(candidate, entry), ...rest),
+  )
+}