@erclx/canon 5.26.0 → 5.28.0

package/src/gate/suite-lock.ts

@@ -0,0 +1,214 @@
+import {
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
+import { liveness, type LivenessProbes, SYSTEM_PROBES } from '@/sessions/live'
+import { stateDir } from '@/targets/registry'
+
+/**
+ * Who holds a machine lock, as the file records it.
+ *
+ * The start time is what separates the holder from whatever inherits its pid
+ * after a crash, so a takeover never waits on a recycled number.
+ */
+export interface LockHolder {
+  readonly pid: number
+  readonly procStart: string | undefined
+  /** The worktree whose gate holds the lock, which the wait line names. */
+  readonly root: string
+}
+
+export interface SuiteLockOptions {
+  readonly path: string
+  readonly root: string
+  readonly pid?: number
+  readonly probes?: LivenessProbes
+  readonly pollMs?: number
+  readonly sleep?: (ms: number) => Promise<void>
+  /** Called once, when the first poll finds a live holder, so a wait is never silent. */
+  readonly onWait?: (holder: LockHolder) => void
+}
+
+export interface HeldLock {
+  readonly release: () => void
+  /** The holder this acquirer queued behind, absent when it never waited. */
+  readonly waitedOn?: LockHolder
+  readonly waitedMs: number
+}
+
+export type AcquireOutcome =
+  | { readonly acquired: true; readonly release: () => void }
+  | { readonly acquired: false; readonly holder: LockHolder | undefined }
+
+/**
+ * The file a named machine lock lives at, resolved at call time so a test run
+ * that redirects the state folder never touches the real one.
+ */
+export function machineLockPath(name: string): string {
+  return join(stateDir(), 'locks', `${name}.lock`)
+}
+
+function isHolder(value: unknown): value is LockHolder {
+  if (typeof value !== 'object' || value === null) return false
+  const fields = value as Record<string, unknown>
+  return typeof fields.pid === 'number' && typeof fields.root === 'string'
+}
+
+function readText(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+function parseHolder(text: string): LockHolder | undefined {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isHolder(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function isCode(error: unknown, code: string): boolean {
+  return (error as NodeJS.ErrnoException).code === code
+}
+
+/**
+ * Publishes the holder's file whole or not at all.
+ *
+ * `link` refuses an existing name the way an exclusive open does, and the
+ * linked file is already written, so no reader meets an empty lock and mistakes
+ * a holder mid-write for a corrupt file it may take over.
+ */
+function publish(path: string, text: string, pid: number): boolean {
+  const staged = `${path}.${pid}.tmp`
+  writeFileSync(staged, text)
+  try {
+    linkSync(staged, path)
+    return true
+  } catch (error) {
+    if (isCode(error, 'EEXIST')) return false
+    throw error
+  } finally {
+    unlinkSync(staged)
+  }
+}
+
+/**
+ * Moves a dead holder's file aside, or puts back one that changed under it.
+ *
+ * Unlink then create is two calls, and two acquirers judging one stale file
+ * would both get through. A rename moves the file to a name only this acquirer
+ * uses, so only one of them gets it, and comparing what moved against what was
+ * judged catches the case where another acquirer already replaced it.
+ *
+ * One interleaving still gets through. A third acquirer publishing between the
+ * rename and the restore leaves the moved holder's file with nowhere to go, so
+ * two suites run at once. That costs one oversubscribed run and never a hang,
+ * and closing it needs a lock the kernel releases, which `node:fs` does not
+ * offer.
+ */
+function displace(path: string, judged: string, pid: number): void {
+  const aside = `${path}.${pid}.stale`
+  try {
+    renameSync(path, aside)
+  } catch (error) {
+    if (isCode(error, 'ENOENT')) return
+    throw error
+  }
+
+  if (readText(aside) !== judged) {
+    try {
+      linkSync(aside, path)
+    } catch (error) {
+      if (!isCode(error, 'EEXIST')) throw error
+    }
+  }
+  unlinkSync(aside)
+}
+
+/**
+ * One attempt at the lock: take it free, take it over from a dead holder, or
+ * report who holds it.
+ */
+export function tryAcquire(options: SuiteLockOptions): AcquireOutcome {
+  const pid = options.pid ?? process.pid
+  const probes = options.probes ?? SYSTEM_PROBES
+  const own: LockHolder = {
+    pid,
+    procStart: probes.procStartOf(pid) ?? undefined,
+    root: options.root,
+  }
+  const text = JSON.stringify(own)
+
+  mkdirSync(dirname(options.path), { recursive: true })
+
+  if (publish(options.path, text, pid)) {
+    return { acquired: true, release: () => release(options.path, text) }
+  }
+
+  const judged = readText(options.path)
+  if (judged === undefined) return { acquired: false, holder: undefined }
+
+  const holder = parseHolder(judged)
+  if (holder !== undefined && liveness(holder, probes).alive) {
+    return { acquired: false, holder }
+  }
+
+  displace(options.path, judged, pid)
+
+  if (publish(options.path, text, pid)) {
+    return { acquired: true, release: () => release(options.path, text) }
+  }
+  return { acquired: false, holder: parseHolder(readText(options.path) ?? '') }
+}
+
+/** Removes the file only while it is still this holder's own. */
+function release(path: string, text: string): void {
+  if (readText(path) !== text) return
+  try {
+    unlinkSync(path)
+  } catch (error) {
+    if (!isCode(error, 'ENOENT')) throw error
+  }
+}
+
+const wait = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+/**
+ * Waits for the lock with no deadline while its holder lives. A deadline would
+ * turn a long queue back into the intermittent failure the lock removes, and a
+ * dead holder is taken over on the next poll rather than waited out.
+ */
+export async function acquireSuiteLock(
+  options: SuiteLockOptions,
+): Promise<HeldLock> {
+  const sleep = options.sleep ?? wait
+  const pollMs = options.pollMs ?? 500
+  const startedAt = performance.now()
+  let waitedOn: LockHolder | undefined
+
+  for (;;) {
+    const outcome = tryAcquire(options)
+    if (outcome.acquired) {
+      return {
+        release: outcome.release,
+        waitedOn,
+        waitedMs: waitedOn === undefined ? 0 : performance.now() - startedAt,
+      }
+    }
+    if (waitedOn === undefined && outcome.holder !== undefined) {
+      options.onWait?.(outcome.holder)
+    }
+    waitedOn = outcome.holder ?? waitedOn
+    await sleep(pollMs)
+  }
+}

package/src/{git-files.ts → git/files.ts}

@@ -1,6 +1,6 @@
 import { $ } from 'bun'
-import { baseCandidates, isMergeBase } from '@/git-base'
-import { gitEnv } from '@/git-env'
+import { baseCandidates, isMergeBase } from '@/git/base'
+import { gitEnv } from '@/git/env'
 
 /** Runs git under `root` with the resolution variables a hook exports stripped. */
 async function git(

package/src/{git-ignore.ts → git/ignore.ts}

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path'
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /**
  * Reports which of `candidates` git ignores under `root`.

package/src/{worktree.ts → git/worktree.ts}

@@ -1,5 +1,5 @@
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /**
  * Resolves the root of the checkout the caller is standing in, which is the

package/src/gov/citations.ts

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { $ } from 'bun'
 import { isMarked } from '@/sweep/exempt-marker'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { listRuleFiles } from '@/gov/payload'
 import { parseFrontmatter } from '@/indexes/frontmatter'
 import { findBacktickSpans } from '@/markdown/backticks'

package/src/gov/install.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
-import { copyPreservingMode } from '@/copy'
+import { copyPreservingMode } from '@/sync/copy'
 
 export interface RuleSource {
   readonly rule: string

package/src/gov/superseded.ts

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { isBinary } from '@/sweep/binary'
 import { isMarked } from '@/sweep/exempt-marker'
-import { listRepositoryFiles } from '@/git-files'
+import { listRepositoryFiles } from '@/git/files'
 
 /**
  * The inline token exempting one line from this sweep, shaped on the

package/src/gov/test-order.ts

@@ -1,6 +1,6 @@
 import { execaSync } from 'execa'
-import { baseCandidates, isMergeBase } from '@/git-base'
-import { gitEnv } from '@/git-env'
+import { baseCandidates, isMergeBase } from '@/git/base'
+import { gitEnv } from '@/git/env'
 
 /**
  * The extensions this check can pair. A test sits beside its subject under one

package/src/help.ts

@@ -105,7 +105,7 @@ const EXAMPLES = [
   'canon canvas list --json',
   'canon slides render',
   'canon slides list --json',
-  'canon capture assets/captures/install.html --selector .window --out assets/evidence',
+  'canon capture assets/captures/install.html --selector .window --out assets/frames',
   'canon serve .canon/teach',
   'canon inventory focus --json',
   'canon drive http://localhost:4173 run.json --json',

package/src/hooks/post-merge.ts

@@ -1,5 +1,5 @@
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /**
  * One child `canon` call. Each step runs as its own process rather than

package/src/indexes/walk.ts

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
-import { listIgnored } from '@/git-ignore'
+import { listIgnored } from '@/git/ignore'
 
 const INDEX_FILE = 'index.md'
 

package/src/intake/folder.ts

@@ -9,7 +9,7 @@ import {
   readItems,
   writeAnswerLine,
 } from '@/intake/items'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 
 export const INTAKE_REFUSALS = [
   'no-intake',

package/src/labels/audit.ts

@@ -1,4 +1,4 @@
-import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { listChangedFiles, resolveBaseRef } from '@/git/files'
 import { type Coverage, resolveCoverage } from '@/labels/coverage'
 import { type MapRefusal, readLabelMap } from '@/labels/map'
 

package/src/labels/map.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { resolveExisting } from '@/legacy-path'
+import { resolveExisting } from '@/roots/legacy'
 
 /**
  * Where a project declares its pull request label map.

package/src/labels/phase.ts

@@ -1,6 +1,6 @@
 import { linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
-import { RECORD_ENTRIES, RECORD_ROOTS } from '@/record-root'
-import type { RecordRoot } from '@/record-root'
+import { RECORD_ENTRIES, RECORD_ROOTS } from '@/roots/record'
+import type { RecordRoot } from '@/roots/record'
 
 /**
  * The two version namespaces `standards/versioning.md` keeps apart, and why a
@@ -114,7 +114,7 @@ const ROOT_READING: Record<RecordRoot, 'whole' | 'entries'> = {
  * `.claude/` is tracked and holds `rules`, `skills`, `hooks`, and `context`,
  * so a rule path resolves in any clone and is not a board reference, and only
  * the entries the record move relocated are unreadable there. Reading the
- * roots and the relocated entries from `src/record-root.ts` is what makes a
+ * roots and the relocated entries from `src/roots/record.ts` is what makes a
  * folder added there matched here without an edit, and the list above is what
  * covers the one thing that module deliberately does not carry.
  *

package/src/markdown/files.ts

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
-import { listRepositoryFiles } from '@/git-files'
+import { listRepositoryFiles } from '@/git/files'
 
 const MARKDOWN = /\.md$/
 

package/src/migrate/apply.ts

@@ -1,7 +1,7 @@
 import { $ } from 'bun'
 import { readFile, mkdir, rename, rmdir, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import type { RenamePlan, RenameSource } from '@/migrate/plan'
 import { FROM_ROOT as OLD_ROOT, type RecordsPlan } from '@/migrate/records'
 

package/src/migrate/record-layout.ts

@@ -40,7 +40,7 @@ import {
   slugOf,
 } from '@/migrate/evidence-ordinal'
 import { presentFolders } from '@/records/backup'
-import { recordDir, SCRATCH, spell, type RecordRoot } from '@/record-root'
+import { recordDir, SCRATCH, spell, type RecordRoot } from '@/roots/record'
 
 const CANON: RecordRoot = '.canon'
 const CLAUDE: RecordRoot = '.claude'

package/src/migrate/records.ts

@@ -15,7 +15,7 @@ import {
   RECORD_ENTRIES,
   RECORD_ROOTS,
   spell,
-} from '@/record-root'
+} from '@/roots/record'
 
 /** The root the entries below leave, exported so the writer can prune it. */
 export const FROM_ROOT: RecordRoot = '.claude'
@@ -26,7 +26,7 @@ const TO_ROOT: RecordRoot = '.canon'
 /**
  * Every entry the move relocates, at the name `.claude/` gave it.
  *
- * The list is `RECORD_ENTRIES`, which `record-root.ts` owns because a seed
+ * The list is `RECORD_ENTRIES`, which `roots/record.ts` owns because a seed
  * destination and a superseded-layout report ask the same question. Restating
  * it here would let the sweep and the resolver disagree about what moved.
  */
@@ -76,12 +76,12 @@ function escape(value: string): string {
  * paths a session actually opened. Rewriting either makes it testify to
  * something that never happened.
  *
- * This module and `src/record-root.ts` are two of the sources that state the old
- * root on purpose. Sweeping them turns every citation this expression is built
- * from into its own replacement, leaving a rewriter that maps `.canon/` to
- * `.canon/` and matches nothing. `src/surface-root.ts` joins the list a release
- * early, for the same reason: it spells `.claude` as data the moment it
- * exists, and excluding it later would leave one release where a records
+ * This module and `src/roots/record.ts` are two of the sources that state the
+ * old root on purpose. Sweeping them turns every citation this expression is
+ * built from into its own replacement, leaving a rewriter that maps `.canon/`
+ * to `.canon/` and matches nothing. `src/roots/surface.ts` joins the list a
+ * release early, for the same reason: it spells `.claude` as data the moment
+ * it exists, and excluding it later would leave one release where a records
  * migration in a target could rewrite the resolver that migration itself
  * depends on.
  *
@@ -112,8 +112,8 @@ const EXCLUDED_PREFIXES: readonly string[] = [
 
 const EXCLUDED_PATHS: readonly string[] = [
   'CHANGELOG.md',
-  'src/record-root.ts',
-  'src/surface-root.ts',
+  'src/roots/record.ts',
+  'src/roots/surface.ts',
 ]
 
 const EXCLUDED_SUFFIXES: readonly string[] = ['.test.ts']
@@ -171,7 +171,7 @@ export const RECORD_ONLY_ROOTS: readonly RecordRoot[] = RECORD_ROOTS.filter(
  * under `.claude/`, and a target's installed `.claude/rules/canon/core/035-tasks.md`
  * is the file the sweep exists to repoint, so a bare `.claude/` prefix strands
  * it silently. The old root is therefore entry-scoped, through `spell` so the
- * one naming variant stays decided in `record-root.ts`.
+ * one naming variant stays decided in `roots/record.ts`.
  *
  * Joined with a literal separator rather than through `join`, the way
  * `EXCLUDED_PREFIXES` already is. These are matched against what `git ls-files`

package/src/migrate/scratch-evidence.ts

@@ -34,7 +34,7 @@ import {
   slugOf,
 } from '@/migrate/evidence-ordinal'
 import { presentFolders } from '@/records/backup'
-import { recordDir, SCRATCH } from '@/record-root'
+import { recordDir, SCRATCH } from '@/roots/record'
 
 /**
  * Every folder this promotion moves, at the name it carries under scratch.

package/src/migrate/surface-roots.ts

@@ -9,7 +9,7 @@
  */
 
 import { join } from 'node:path'
-import { SURFACE_ENTRIES, spell, type SurfaceRoot } from '@/surface-root'
+import { SURFACE_ENTRIES, spell, type SurfaceRoot } from '@/roots/surface'
 
 /** The root the entries below leave. */
 export const FROM_ROOT: SurfaceRoot = '.claude'
@@ -80,8 +80,8 @@ function escape(value: string): string {
  *
  * The changelog is release history, and an eval result is a transcript of
  * paths a session actually opened; rewriting either makes it testify to
- * something that never happened. `src/surface-root.ts` and
- * `src/record-root.ts` are the two sources that spell the old root as data on
+ * something that never happened. `src/roots/surface.ts` and
+ * `src/roots/record.ts` are the two sources that spell the old root as data on
  * purpose, so sweeping either would turn the very literals this verb reads
  * into their own replacement. A hook is the third such source, guarding on a
  * `case` carrying an arm per root, so `.claude/hooks/` and the seed's copy of
@@ -102,8 +102,8 @@ const EXCLUDED_PREFIXES: readonly string[] = [
 
 const EXCLUDED_PATHS: readonly string[] = [
   'CHANGELOG.md',
-  'src/surface-root.ts',
-  'src/record-root.ts',
+  'src/roots/surface.ts',
+  'src/roots/record.ts',
 ]
 
 export function isExcludedPath(path: string): boolean {
@@ -380,7 +380,7 @@ export interface SurfaceRootsPlan {
  * moved entry, and whether its content cites one. Either alone is enough to
  * produce an entry, and a file excluded from the citation rewrite still moves
  * when its path itself is inside a moved entry, since the two entries excluded
- * today, `src/surface-root.ts` and `src/record-root.ts`, both sit outside
+ * today, `src/roots/surface.ts` and `src/roots/record.ts`, both sit outside
  * every moved entry and never take that branch in practice.
  */
 export function planSurfaceRootsMove(

package/src/pr/bijection.ts

@@ -1,4 +1,4 @@
-import type { RenamePair } from '@/git-files'
+import type { RenamePair } from '@/git/files'
 import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
 
 /**