@erclx/canon 4.107.0 → 4.109.0

package/src/tasks/label.ts

@@ -1,5 +1,7 @@
 import { existsSync } from 'node:fs'
+import { mkdir, readdir } from 'node:fs/promises'
 import { relative } from 'node:path'
+import { recordDir } from '@/record-root'
 import {
   archiveDir,
   declinedDir,
@@ -21,6 +23,12 @@ const FIRST_LABEL: Label = { major: 1, minor: 0 }
  */
 export const LABEL_PATTERN = /^v(\d+)\.(\d+)-/
 
+/** A reservation is named by the bare label, with no slug behind it. */
+const RESERVATION_PATTERN = /^v(\d+)\.(\d+)$/
+
+/** Bounds the claim loop. A fifth loss in a row is not a race. */
+const MAX_ATTEMPTS = 5
+
 interface Label {
   readonly major: number
   readonly minor: number
@@ -31,18 +39,23 @@ export interface NextLabel {
   readonly label: string
   /** The label this run was derived from, absent when neither folder holds one. */
   readonly highest: string | undefined
+  /** Whether this label was reserved on disk rather than only read. */
+  readonly claimed: boolean
 }
 
 export interface LabelRefused {
   readonly ok: false
-  readonly reason: 'no-board'
+  readonly reason: 'no-board' | 'label-contended'
   readonly message: string
 }
 
 export type LabelOutcome = NextLabel | LabelRefused
 
-function parseLabel(stem: string): Label | undefined {
-  const match = LABEL_PATTERN.exec(stem)
+function parseLabel(
+  stem: string,
+  pattern: RegExp = LABEL_PATTERN,
+): Label | undefined {
+  const match = pattern.exec(stem)
   if (!match) return undefined
 
   return { major: Number(match[1]), minor: Number(match[2]) }
@@ -71,6 +84,54 @@ function next(label: Label): Label {
     : { major: label.major, minor: label.minor + 1 }
 }
 
+function noBoard(root: string, dir: string): LabelRefused {
+  return {
+    ok: false,
+    reason: 'no-board',
+    message: `No task board at ${relative(root, dir)}.`,
+  }
+}
+
+function reservationsDir(root: string): string {
+  return recordDir(root, 'ordinal-locks')
+}
+
+async function listReservations(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(reservationsDir(root), {
+      withFileTypes: true,
+    })
+    return entries.filter((entry) => entry.isDirectory()).map((e) => e.name)
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return []
+    }
+    throw error
+  }
+}
+
+function highestOf(
+  names: readonly string[],
+  pattern: RegExp,
+): Label | undefined {
+  return names
+    .map((name) => parseLabel(name, pattern))
+    .filter((label): label is Label => label !== undefined)
+    .reduce<Label | undefined>(
+      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
+      undefined,
+    )
+}
+
+async function readStems(root: string): Promise<string[]> {
+  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
+    existsSync(candidate),
+  )
+  const dirs = [tasksDir(root), ...settled]
+
+  return (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+}
+
 /**
  * Reports the next unused phase label, read off the true maximum across
  * `.canon/tasks/` and its `archive/` and `declined/` siblings together. A scan
@@ -78,41 +139,87 @@ function next(label: Label): Label {
  * spent, which is what let two sessions hand out the same label within
  * minutes of each other.
  *
- * It reports and never writes. Two sessions calling it in the same second can
- * still take the same answer, since the board is gitignored files rather than
- * a store with a lock, and `standards/versioning.md` permits free renumbering,
- * so a collision costs a rename rather than anything worse. A duplicate label
- * already sitting in the tree, and a gap left by a renumbering, both fold into
- * the same max scan without needing a dedicated check.
+ * It reports and never writes. `claimLabel` is the variant that reserves. A
+ * duplicate label already sitting in the tree, and a gap left by a
+ * renumbering, both fold into the same max scan without needing a dedicated
+ * check.
  */
 export async function nextLabel(root: string): Promise<LabelOutcome> {
   const dir = tasksDir(root)
+  if (!existsSync(dir)) return noBoard(root, dir)
 
-  if (!existsSync(dir)) {
-    return {
-      ok: false,
-      reason: 'no-board',
-      message: `No task board at ${relative(root, dir)}.`,
-    }
+  const highest = highestOf(await readStems(root), LABEL_PATTERN)
+
+  return {
+    ok: true,
+    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
+    highest: highest === undefined ? undefined : formatLabel(highest),
+    claimed: false,
   }
+}
 
-  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
-    existsSync(candidate),
-  )
-  const dirs = [dir, ...settled]
-  const stems = (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+interface ClaimOptions {
+  /** Takes the reservation, resolving false when another claim holds it. */
+  readonly reserve?: (root: string, label: string) => Promise<boolean>
+}
 
-  const highest = stems
-    .map(parseLabel)
-    .filter((label): label is Label => label !== undefined)
-    .reduce<Label | undefined>(
-      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
-      undefined,
+async function reserveLabel(root: string, label: string): Promise<boolean> {
+  await mkdir(reservationsDir(root), { recursive: true })
+
+  try {
+    await mkdir(recordDir(root, 'ordinal-locks', label), { recursive: false })
+    return true
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+      return false
+    }
+    throw error
+  }
+}
+
+/**
+ * Reserves the next label through an exclusive `mkdir` under
+ * `.canon/ordinal-locks/`, so a second claim lands on a different one.
+ *
+ * The scan counts every reservation beside the task stems. The skill writes
+ * the task file after this returns, so a reservation with no file behind it is
+ * the ordinary state for a few seconds, and a scan blind to it would offer the
+ * same label to every retry. Reservations are never expired: a claim that died
+ * leaves a gap, and `standards/versioning.md` permits gaps.
+ */
+export async function claimLabel(
+  root: string,
+  options: ClaimOptions = {},
+): Promise<LabelOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) return noBoard(root, dir)
+
+  const reserve = options.reserve ?? reserveLabel
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    const stems = highestOf(await readStems(root), LABEL_PATTERN)
+    const held = highestOf(await listReservations(root), RESERVATION_PATTERN)
+    const highest =
+      stems !== undefined && (held === undefined || isHigher(stems, held))
+        ? stems
+        : held
+    const label = formatLabel(
+      highest === undefined ? FIRST_LABEL : next(highest),
     )
 
+    if (await reserve(root, label)) {
+      return {
+        ok: true,
+        label,
+        highest: highest === undefined ? undefined : formatLabel(highest),
+        claimed: true,
+      }
+    }
+  }
+
   return {
-    ok: true,
-    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
-    highest: highest === undefined ? undefined : formatLabel(highest),
+    ok: false,
+    reason: 'label-contended',
+    message: `Could not reserve a label after ${MAX_ATTEMPTS} attempts. Re-run the claim.`,
   }
 }

package/standards/readme.md

@@ -63,6 +63,7 @@ The opening of a root README is a block of up to six elements in a fixed order.
 The description of 2-3 sentences follows the block and expands the claim rather than repeating it.
 
 - A project with no page omits the link and the screenshot. A library or a CLI reads as a complete block with a title, badges, and a claim.
+- A project whose own page carries the screenshot omits it here and keeps the live link, which answers the slot rather than skipping it. Say so in the pull request that drops it.
 - The order is the block's rather than the page's. The screenshot sits last inside the block, which puts it in the first row of content a reader meets below the title, badges, and claim.
 - A themed light and dark pair counts as one element in the slot rather than two. The block does not require a pair and leaves the handling of themes to the project.
 - Centering the block in an HTML wrapper is optional. Plain markdown reaches every host a README renders on, and a wrapper is styling a project can add.