@erclx/canon 4.73.0 → 4.75.0

package/src/pr/evidence.ts

@@ -0,0 +1,171 @@
+/** The path segment that marks an image as evidence a pull request should compare. */
+const EVIDENCE_SEGMENT = 'evidence'
+
+/** Prefix of the trailing marker this module writes and reads back. */
+const MARKER_PREFIX = '<!-- pr-evidence:'
+
+/** A `#issuecomment-<id>` suffix, which is the REST comment id `gh pr view` never returns directly. */
+const ISSUE_COMMENT_ID = /#issuecomment-(\d+)$/
+
+/**
+ * The image extensions this module embeds. An `evidence/` folder holds
+ * whatever else a project keeps beside its captures, such as a README, a
+ * capture script, or a raw data file, and none of those render as
+ * `![](url)` without producing a broken embed.
+ */
+const IMAGE_EXTENSION = /\.(png|jpe?g|gif|webp|avif|svg)$/i
+
+export interface EvidenceItem {
+  readonly path: string
+  readonly stem: string
+  /** True when `path` did not exist at the comparison's base commit. */
+  readonly added: boolean
+}
+
+export interface EvidenceState {
+  /** The remainder of the path's directory under the `evidence/` segment. Empty when the image sits directly inside it. */
+  readonly state: string
+  readonly items: readonly EvidenceItem[]
+}
+
+export type EvidenceRefusal = 'no-evidence'
+
+export type EvidenceReading =
+  | { readonly kind: 'read'; readonly states: readonly EvidenceState[] }
+  | { readonly kind: 'refused'; readonly reason: EvidenceRefusal }
+
+/** Whether a path existed at the comparison's base commit, read however the caller resolves it. */
+export type ExistsAtBase = (path: string) => Promise<boolean>
+
+function evidencePosition(path: string): number {
+  return path.split('/').indexOf(EVIDENCE_SEGMENT)
+}
+
+export function isEvidencePath(path: string): boolean {
+  return evidencePosition(path) !== -1 && IMAGE_EXTENSION.test(path)
+}
+
+function splitEvidencePath(path: string): {
+  readonly state: string
+  readonly stem: string
+} {
+  const segments = path.split('/')
+  const rest = segments.slice(evidencePosition(path) + 1)
+  const filename = rest[rest.length - 1] ?? ''
+  return {
+    state: rest.slice(0, -1).join('/'),
+    stem: filename.replace(/\.[^./]+$/, ''),
+  }
+}
+
+/**
+ * Groups every evidence path in `changed` by its state, keying each entry
+ * inside a state by filename stem so a before/after pair sharing a name
+ * across two states can be read as one case.
+ */
+export async function groupEvidence(
+  changed: readonly string[],
+  existsAtBase: ExistsAtBase,
+): Promise<EvidenceReading> {
+  const paths = changed.filter(isEvidencePath)
+  if (paths.length === 0) return { kind: 'refused', reason: 'no-evidence' }
+
+  const resolved = await Promise.all(
+    paths.map(async (path) => {
+      const { state, stem } = splitEvidencePath(path)
+      const added = !(await existsAtBase(path))
+      return { path, state, stem, added }
+    }),
+  )
+
+  const byState = new Map<string, EvidenceItem[]>()
+  for (const { path, state, stem, added } of resolved) {
+    const item: EvidenceItem = { path, stem, added }
+    const items = byState.get(state)
+    if (items === undefined) byState.set(state, [item])
+    else items.push(item)
+  }
+
+  const states = [...byState.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([state, items]) => ({
+      state,
+      items: [...items].sort((a, b) => a.stem.localeCompare(b.stem)),
+    }))
+
+  return { kind: 'read', states }
+}
+
+function rawUrl(repo: string, sha: string, path: string): string {
+  return `https://raw.githubusercontent.com/${repo}/${sha}/${path}`
+}
+
+export function evidenceMarker(head: string): string {
+  return `${MARKER_PREFIX} head=${head} -->`
+}
+
+/**
+ * Renders the whole comment body: one collapsed `<details>` block per state,
+ * a Base/Head row per case, and the trailing marker naming the head this body
+ * describes. Every image URL is pinned to a commit sha rather than a branch,
+ * so the comment keeps showing what it claimed even after the branch moves.
+ */
+export function renderEvidenceBody(
+  states: readonly EvidenceState[],
+  repo: string,
+  base: string,
+  head: string,
+): string {
+  const sections = states.map((entry) => {
+    const rows = entry.items.map((item) => {
+      const before = item.added
+        ? '*(new)*'
+        : `![](${rawUrl(repo, base, item.path)})`
+      const after = `![](${rawUrl(repo, head, item.path)})`
+      return `| ${item.stem} | ${before} | ${after} |`
+    })
+
+    return [
+      '<details>',
+      `<summary>${entry.state === '' ? 'evidence' : entry.state} (${entry.items.length})</summary>`,
+      '',
+      '| Case | Base | Head |',
+      '| --- | --- | --- |',
+      ...rows,
+      '',
+      '</details>',
+    ].join('\n')
+  })
+
+  return ['## Evidence', '', ...sections, '', evidenceMarker(head)].join('\n')
+}
+
+export interface EvidenceComment {
+  readonly url?: string
+  readonly body: string
+}
+
+function hasEvidenceMarker(body: string): boolean {
+  const lines = body.split('\n')
+  let index = lines.length - 1
+  while (index >= 0 && (lines[index] ?? '').trim() === '') index -= 1
+  if (index < 0) return false
+  return (lines[index] ?? '').trim().startsWith(MARKER_PREFIX)
+}
+
+/**
+ * The REST id of the comment this module already posted, read off its `url`
+ * field, since `gh pr view --json comments` reports only a GraphQL id there
+ * and the REST id is what a later `PATCH` needs.
+ */
+export function findEvidenceCommentId(
+  comments: readonly EvidenceComment[],
+): number | undefined {
+  for (const comment of comments) {
+    if (!hasEvidenceMarker(comment.body)) continue
+    const match =
+      comment.url === undefined ? null : ISSUE_COMMENT_ID.exec(comment.url)
+    if (match?.[1] !== undefined) return Number(match[1])
+  }
+  return undefined
+}

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,
+  }
+}