@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/doc-owners.ts

@@ -0,0 +1,314 @@
+/**
+ * The `.vinaya/doc-owners` manifest parser and the C5 code→doc
+ * coverage evaluator (state-machine.md Section 15). Pure — I/O (reading the
+ * manifest off disk, checking pointer existence) is injected by the caller.
+ */
+
+import { isCodeFile } from './file-classify'
+import { WAIVER_LABEL } from './waiver-label'
+
+export const DOC_OWNERS_PATH = '.vinaya/doc-owners'
+
+export type DocOwnersBinding = { glob: string; pointer: string; lineNum: number }
+
+/**
+ * What a caller found where the manifest should be.
+ *
+ * `absent` — a repo that never configured doc ownership. Legitimately dormant.
+ * `empty` — a manifest that exists but has nothing in it. This is the shape a
+ *   misresolved repo root produces, and reporting it as success is how a broken
+ *   derivation passes for a real one. It is a refusal, not a dormancy.
+ * `present` — parse it.
+ *
+ * Split out of `verify-dispatch --surfaces` so the three-way decision is
+ * testable: the CLI chdirs to the repo root before reading, so the branch is
+ * unreachable from a test as long as it lives inside the command.
+ */
+export type DocOwnersManifestState = 'absent' | 'empty' | 'present'
+
+export function classifyDocOwnersManifest(content: string | null): DocOwnersManifestState {
+  if (content === null) return 'absent'
+  return content.trim() === '' ? 'empty' : 'present'
+}
+
+export type C5Result = { errors: string[]; notes: string[] }
+
+/**
+ * Parse the doc-owners file. Each non-blank, non-comment line is
+ *   `<code-glob>  <doc-pointer>`
+ *
+ * Comments start with `#`. Pointer is in-repo path, path#anchor, or URL.
+ * Returns the parsed bindings + any malformed-line errors.
+ */
+export function parseDocOwners(content: string): { bindings: DocOwnersBinding[]; errors: string[] } {
+  const bindings: DocOwnersBinding[] = []
+  const errors: string[] = []
+  const lines = content.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i] ?? ''
+    const stripped = raw.replace(/#.*$/, '').trim()
+    if (!stripped) continue
+    const parts = stripped.split(/\s+/)
+    if (parts.length < 2) {
+      errors.push(
+        `C5 doc-owners-parse: ${DOC_OWNERS_PATH}:${i + 1} — malformed binding (expected "<glob>  <pointer>", got "${raw.trim()}").`
+      )
+      continue
+    }
+    const [glob, ...pointerParts] = parts
+    bindings.push({ glob: glob ?? '', pointer: pointerParts.join(' '), lineNum: i + 1 })
+  }
+  return { bindings, errors }
+}
+
+/**
+ * Translate a doc-owners glob to a RegExp. Deliberately simple — only `*` and
+ * `**` are special; every other character is literal so Next.js dynamic-route
+ * segments like `[username]` match without escaping.
+ */
+export function globToRegex(pat: string): RegExp {
+  let re = '^'
+  let i = 0
+  while (i < pat.length) {
+    const c = pat[i]
+    if (c === '*') {
+      if (pat[i + 1] === '*') {
+        re += '.*'
+        i += 2
+      } else {
+        re += '[^/]*'
+        i += 1
+      }
+    } else if (/[.+^$|(){}[\]\\?]/.test(c as string)) {
+      re += `\\${c}`
+      i += 1
+    } else {
+      re += c
+      i += 1
+    }
+  }
+  re += '$'
+  return new RegExp(re)
+}
+
+export function isUrlPointer(p: string): boolean {
+  return /^https?:\/\//.test(p)
+}
+
+export function pointerToPath(p: string): string {
+  const idx = p.indexOf('#')
+  return idx === -1 ? p : p.slice(0, idx)
+}
+
+export type DocAck = { surface: string; note: string }
+export type DocNeutral = { surface: string; note: string }
+
+// Separator between <pointer> and <note>. Tolerates em-dash (—),
+// en-dash (–), or a plain ASCII hyphen-minus (-) with REQUIRED surrounding
+// whitespace. Required whitespace around `-` disambiguates the separator
+// from hyphens that legitimately appear inside pointers (e.g. `aeg-root`,
+// `.claude/skills/ui-components/SKILL.md`). Non-greedy `(.+?)` for the
+// pointer plus this anchored separator means the pointer naturally stops
+// at the first valid separator without literally excluding `-` from
+// the pointer character set.
+const SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source
+
+/** Shared by `Doc-ack:` and `Doc-neutral:` — both are `<field>: <pointer> <sep> <note>` PR-body lines. */
+function readPointerNoteField(body: string, field: string): { surface: string; note: string }[] {
+  const out: { surface: string; note: string }[] = []
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, 'gim')
+  for (const m of body.matchAll(re)) {
+    out.push({ surface: (m[1] ?? '').trim(), note: (m[2] ?? '').trim() })
+  }
+  return out
+}
+
+export function readDocAcks(body: string): DocAck[] {
+  return readPointerNoteField(body, 'Doc-ack')
+}
+
+/**
+ * `Doc-neutral: <pointer> — <note>` — declares that the doc a fired binding
+ * would otherwise require is not owed because the matched code change is
+ * mechanically neutral (comment/whitespace-only). Mirrors `Doc-ack:`'s
+ * grammar deliberately, so it reads as the same PR-body-field family.
+ *
+ * The declaration alone is never sufficient — see `isMechanicallyNeutralDiff`
+ * below, which `evaluateC5` requires as corroborating evidence before this
+ * declaration satisfies a fired binding. An unevidenced declaration is a
+ * distinct failure (`C5 doc-neutral-unverified`), not a silent pass — that
+ * asymmetry is what keeps this from being a self-serve exemption.
+ */
+export function readDocNeutrals(body: string): DocNeutral[] {
+  return readPointerNoteField(body, 'Doc-neutral')
+}
+
+/**
+ * Full-line comment markers, scoped per source-language file extension. A
+ * marker is listed for a language ONLY if no legitimate code construct in
+ * that language can start a trimmed line with it — that constraint is what
+ * keeps this fail-closed rather than a bare per-line prefix table (review
+ * finding, task 4 code review): a flat asterisk/hash/double-dash/block-
+ * comment-delimiter table misclassifies real code as comment — a TS/JS
+ * generator method (`*gen() {`), a TS/JS private class field
+ * (`#count = 0`), SQL's `--` also being C-style pre-decrement (`--i;`), and
+ * a block-comment-close delimiter hiding trailing code on the same line are
+ * all real collisions, not hypothetical ones. `//` is the only marker kept
+ * for TS/JS/JSX because no such language construct starts a trimmed line
+ * with `//`. An unrecognized extension gets no safe marker at all, so
+ * `isMechanicallyNeutralDiff` can never classify it neutral — fail-closed
+ * under uncertainty, not an attempt at full per-language comment/string-
+ * region parsing (out of this task's bounded "comment/whitespace-only"
+ * scope).
+ */
+const LANGUAGE_COMMENT_PREFIXES: ReadonlyArray<{ test: RegExp; prefixes: readonly string[] }> = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ['//'] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ['#'] },
+  { test: /\.(sh|bash)$/, prefixes: ['#'] },
+  { test: /\.ya?ml$/, prefixes: ['#'] },
+  { test: /\.py$/, prefixes: ['#'] }
+]
+
+function commentPrefixesForPath(path: string): readonly string[] {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path)) return prefixes
+  }
+  return []
+}
+
+function isNeutralDiffContentLine(line: string, prefixes: readonly string[]): boolean {
+  const t = line.trim()
+  if (t === '') return true
+  // A shebang is comment-shaped but changes what interpreter runs the
+  // file — real behavior, never neutral, even though it starts with `#`.
+  if (t.startsWith('#!')) return false
+  return prefixes.some((p) => t.startsWith(p))
+}
+
+/**
+ * The evidence half of the neutral-edit path: given a unified diff for one
+ * file and that file's path (for language-scoped comment-marker selection),
+ * true only if every added/removed line is comment-only or whitespace-only.
+ * Context lines and the `+++`/`---`/`@@` headers are not evidence either
+ * way. A diff with zero +/- content lines is not "a change" at all, so it
+ * returns false rather than vacuously true — there must be at least one
+ * actual edited line for a neutrality claim to mean anything. An
+ * unrecognized file extension (`commentPrefixesForPath` returns `[]`)
+ * always returns false — no fired binding on an unrecognized language can
+ * take the Doc-neutral path.
+ */
+export function isMechanicallyNeutralDiff(diffText: string, path: string): boolean {
+  const prefixes = commentPrefixesForPath(path)
+  let sawChange = false
+  for (const raw of diffText.split('\n')) {
+    if (raw.startsWith('+++ ') || raw.startsWith('--- ') || raw.startsWith('@@')) continue
+    if (raw.startsWith('+') || raw.startsWith('-')) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes)) return false
+      sawChange = true
+    }
+  }
+  return sawChange
+}
+
+/**
+ * Pure evaluator for the C5 doc-coverage check. The runtime wrapper reads
+ * `.vinaya/doc-owners` from disk and `PR_BODY` from env; this
+ * function takes both as inputs and an injectable file-exists for unit tests.
+ *
+ * Dormancy: a null `docOwnersContent` (absent file) OR no glob matching any
+ * changed code file produces an empty result — no errors, no notes.
+ *
+ * `waiverActive` is a single PR-wide boolean, not a per-binding
+ * pointer/reason lookup — it's the caller-resolved result of
+ * `isWaiverLabelActorVerified`, itself a mechanized read of a forge fact.
+ * There is no agent-emittable `Doc-waiver:` string anymore; a waiver is
+ * either verified true PR-wide, or not.
+ *
+ * `getDiff` is optional and injectable (unit tests; also absent whenever a
+ * caller has no diff-content source) — it resolves the unified diff for one
+ * matched code file, feeding the `Doc-neutral:` evidence check below. Its
+ * absence never produces a pass: a declared-but-unevidenced neutral claim
+ * fails the same as if it evidence didn't check out, preserving silence =
+ * failure (state-machine.md Section 15).
+ */
+export function evaluateC5(
+  changed: string[],
+  docOwnersContent: string | null,
+  prBody: string,
+  fileExists: (p: string) => boolean,
+  waiverActive: boolean,
+  getDiff?: (p: string) => string | null
+): C5Result {
+  const out: C5Result = { errors: [], notes: [] }
+
+  if (docOwnersContent === null) return out
+
+  const { bindings, errors: parseErrors } = parseDocOwners(docOwnersContent)
+  for (const e of parseErrors) out.errors.push(e)
+  if (bindings.length === 0) return out
+
+  const codeFiles = changed.filter(isCodeFile)
+  const fired: { binding: DocOwnersBinding; matchedFiles: string[] }[] = []
+  for (const b of bindings) {
+    const re = globToRegex(b.glob)
+    const matchedFiles = codeFiles.filter((f) => re.test(f))
+    if (matchedFiles.length > 0) fired.push({ binding: b, matchedFiles })
+  }
+  if (fired.length === 0) return out
+
+  const acks = readDocAcks(prBody)
+  const neutrals = readDocNeutrals(prBody)
+
+  for (const { binding: b, matchedFiles } of fired) {
+    if (waiverActive) {
+      out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`)
+      continue
+    }
+
+    if (isUrlPointer(b.pointer)) {
+      const acked = acks.some((a) => a.surface === b.pointer)
+      if (!acked) {
+        out.errors.push(
+          `C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}). External pointer requires \`Doc-ack: ${b.pointer} — <note>\` in the PR body, or an actor-verified \`${WAIVER_LABEL}\` label to skip.`
+        )
+      }
+      continue
+    }
+
+    const pointerPath = pointerToPath(b.pointer)
+    if (!fileExists(pointerPath)) {
+      out.errors.push(
+        `C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`
+      )
+      continue
+    }
+
+    if (changed.includes(pointerPath)) continue
+
+    const declared = neutrals.find((n) => n.surface === b.pointer)
+    if (declared) {
+      const evidenced =
+        getDiff !== undefined &&
+        matchedFiles.every((f) => {
+          const diff = getDiff(f)
+          return diff !== null && isMechanicallyNeutralDiff(diff, f)
+        })
+      if (evidenced) {
+        out.notes.push(
+          `C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(', ')} confirmed comment/whitespace-only.`
+        )
+        continue
+      }
+      out.errors.push(
+        `C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(', ')} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`
+      )
+      continue
+    }
+
+    out.errors.push(
+      `C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`
+    )
+  }
+
+  return out
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/build-doc-nav.ts

@@ -0,0 +1,38 @@
+import type { Doc, DocNav, DocSection } from './types'
+
+export type BuildDocNavOptions = {
+  sectionOrder?: string[]
+}
+
+function sectionIdOf(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+export function buildDocNav(docs: Doc[], opts: BuildDocNavOptions = {}): DocNav {
+  const bySection = new Map<string, Doc[]>()
+  for (const doc of docs) {
+    const list = bySection.get(doc.section) ?? []
+    list.push(doc)
+    bySection.set(doc.section, list)
+  }
+
+  const ordered: string[] = []
+  if (opts.sectionOrder) {
+    for (const label of opts.sectionOrder) if (bySection.has(label)) ordered.push(label)
+  }
+  for (const label of bySection.keys()) if (!ordered.includes(label)) ordered.push(label)
+
+  const sections: DocSection[] = ordered.map((label) => {
+    const items = (bySection.get(label) ?? []).slice().sort((a, b) => {
+      if (a.order !== b.order) return a.order - b.order
+      return a.title.localeCompare(b.title)
+    })
+    return { id: sectionIdOf(label), label, docs: items }
+  })
+
+  const flat = sections.flatMap((s) => s.docs)
+  return { sections, flat }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/docs-coherence.ts

@@ -0,0 +1,136 @@
+/**
+ * C6 — the docs-coherence check (state-machine.md Section 15c). Pure: given
+ * every parsed doc entry from `aeg-root/` and the model-backed surfaced-path
+ * allowlist (`modelBackedDocPaths`, passed in because deriving
+ * it requires reading doctrine, which this pure module never does), asserts:
+ *   (a) every surfaced doc is reachable in the doc-nav tree the docs engine
+ *       (`buildDocNav`) would build for the surfaced set;
+ *   (b) no surfaced doc's `parent:` reference points at a doc that doesn't
+ *       exist, or exists but isn't itself surfaced;
+ *   (c) every relative `.md` link between two surfaced docs resolves to
+ *       another surfaced doc.
+ *
+ * (a) and (b) mirror the real parent/child resolution
+ * `apps/vinaya/web/src/lib/docs/nest-doc-children.ts` performs when building
+ * Vinaya's live `/docs` nav (a Portal route since `vinaya-pages-v1` task 8;
+ * that file is read-only reference here, never imported): a doc whose
+ * `parent:` frontmatter points at
+ * a nonexistent (or excluded) slug is silently dropped from that nav's flat
+ * list — reachable neither at the top level nor as anyone's child. That
+ * silent-drop is the exact defect this check exists to catch.
+ */
+
+import { deriveTitle, type ParsedDoc } from './parse-doc'
+import { isSurfacedDoc } from './surfaced-manifest'
+import type { Doc, DocFrontmatter } from './types'
+
+export type DocsCoherenceEntry = {
+  /** Path relative to `aeg-root/`, e.g. `roles/developer.md`. */
+  relPath: string
+  frontmatter: DocFrontmatter
+  body: string
+  firstH1?: string
+}
+
+export type DocsCoherenceResult = { errors: string[]; notes: string[] }
+
+function slugOf(relPath: string): string {
+  return relPath.replace(/\.md$/, '')
+}
+
+function relPathOf(slug: string): string {
+  return `${slug}.md`
+}
+
+function defaultSectionFor(relPath: string): string {
+  const segments = relPath.split('/')
+  return segments.length === 1 ? 'Overview' : (segments[0] ?? 'Overview')
+}
+
+function toDoc(entry: DocsCoherenceEntry): Doc {
+  const slug = slugOf(entry.relPath)
+  const parsed: ParsedDoc = { frontmatter: entry.frontmatter, body: entry.body, firstH1: entry.firstH1 }
+  return {
+    slug,
+    title: deriveTitle(parsed, slug),
+    sidebarTitle: entry.frontmatter.sidebarTitle,
+    description: entry.frontmatter.description,
+    section: entry.frontmatter.section ?? defaultSectionFor(entry.relPath),
+    order: entry.frontmatter.order ?? 0,
+    href: `/docs/${slug}`,
+    filePath: `aeg-root/${entry.relPath}`,
+    parentSlug: entry.frontmatter.parent
+  }
+}
+
+function isReachable(doc: Doc, bySlug: Map<string, Doc>, seen: Set<string> = new Set()): boolean {
+  if (!doc.parentSlug) return true
+  if (seen.has(doc.slug)) return false // cycle guard
+  const parent = bySlug.get(doc.parentSlug)
+  if (!parent) return false
+  seen.add(doc.slug)
+  return isReachable(parent, bySlug, seen)
+}
+
+const MD_LINK_PATTERN = /\]\(([^)]+)\)/g
+
+/** Resolves `target` relative to the directory of `fromRelPath`. Returns null if it escapes `aeg-root/`. */
+function resolveRelativeMdLink(fromRelPath: string, target: string): string | null {
+  const fromDir = fromRelPath.includes('/') ? fromRelPath.slice(0, fromRelPath.lastIndexOf('/')) : ''
+  const combined = target.startsWith('/') ? target.slice(1) : fromDir ? `${fromDir}/${target}` : target
+
+  const stack: string[] = []
+  for (const part of combined.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') {
+      if (stack.length === 0) return null
+      stack.pop()
+    } else {
+      stack.push(part)
+    }
+  }
+  return stack.join('/')
+}
+
+export function evaluateDocsCoherence(
+  entries: DocsCoherenceEntry[],
+  surfacedPaths: ReadonlySet<string> = new Set()
+): DocsCoherenceResult {
+  const errors: string[] = []
+  const notes: string[] = []
+
+  const surfacedEntries = entries.filter((e) => isSurfacedDoc(e.relPath, e.frontmatter, surfacedPaths))
+  const surfacedRelPaths = new Set(surfacedEntries.map((e) => e.relPath))
+  const docs = surfacedEntries.map(toDoc)
+  const bySlug = new Map(docs.map((d) => [d.slug, d]))
+
+  for (const doc of docs) {
+    if (!isReachable(doc, bySlug)) {
+      errors.push(`C6: surfaced doc "${relPathOf(doc.slug)}" is not reachable in the doc nav`)
+    }
+    if (doc.parentSlug && !bySlug.has(doc.parentSlug)) {
+      errors.push(
+        `C6: nav entry "${relPathOf(doc.slug)}" points at a non-existent/excluded doc "${relPathOf(doc.parentSlug)}"`
+      )
+    }
+  }
+
+  for (const entry of surfacedEntries) {
+    for (const match of entry.body.matchAll(MD_LINK_PATTERN)) {
+      const raw = (match[1] ?? '').trim()
+      const target = (raw.split('#')[0] ?? '').trim()
+      if (!target) continue // pure same-doc anchor, e.g. `(#some-heading)`
+      if (/^https?:\/\//.test(target) || target.startsWith('mailto:')) continue
+      if (!target.endsWith('.md')) continue
+
+      const resolved = resolveRelativeMdLink(entry.relPath, target)
+      if (resolved === null) continue // escapes aeg-root/ — out of scope for this check
+
+      if (!surfacedRelPaths.has(resolved)) {
+        errors.push(`C6: link "${target}" in "${entry.relPath}" resolves to no surfaced doc`)
+      }
+    }
+  }
+
+  return { errors, notes }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/index.ts

@@ -0,0 +1,29 @@
+export type { Doc, DocFrontmatter, DocNav, DocSection } from './types'
+export { parseDocFrontmatter, deriveTitle, stripLeadingH1 } from './parse-doc'
+export type { ParsedDoc } from './parse-doc'
+export { buildDocNav } from './build-doc-nav'
+export type { BuildDocNavOptions } from './build-doc-nav'
+export { findDoc, getNextDoc, getPrevDoc } from './nav-helpers'
+export { isSurfacedDoc, surfacedDocs, modelBackedDocPaths } from './surfaced-manifest'
+export type { SurfacedManifestEntry } from './surfaced-manifest'
+export { nodeDocRoute, nodeDocHref } from './node-route'
+export type { NodeDocRoute } from './node-route'
+export { legacyAnchorSlugs } from './legacy-anchors'
+export { evaluateDocsCoherence } from './docs-coherence'
+export type { DocsCoherenceEntry, DocsCoherenceResult } from './docs-coherence'
+export {
+  ALLOWED_MECHANICS,
+  CONTRACT_BLOCKS,
+  countWords,
+  enforcementPublishedText,
+  evaluatePublishedProse,
+  extractShortVersion,
+  publishedDoctrineBody,
+  readabilityErrors,
+  REFERENCE_HEADING,
+  ROLE_BLOCKS,
+  SHORT_VERSION_HEADING,
+  SHORT_VERSION_MAX_WORDS,
+  SHORT_VERSION_MIN_WORDS
+} from './published-prose'
+export type { PublishedProseEntry, PublishedProseResult } from './published-prose'

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/legacy-anchors.ts

@@ -0,0 +1,48 @@
+/**
+ * The old-slug → new-slug alias derivation for `/docs` gate/check anchors.
+ * `node-route.ts`'s `nodeSlug()` computes an anchor from a node's display
+ * form (G-code stripped, over-length names cut at a clause boundary), which
+ * for a handful of nodes now differs from the slug `diagram-model.ts`
+ * originally stamped into the node id. A reader who bookmarked, or a page
+ * that still links to, the old `#g1-implementation-exists`-style fragment
+ * must keep landing on the right section — this is the input to that alias.
+ *
+ * Derived, not hand-listed: the failure mode this replaces is exactly the
+ * one `node-route.ts`'s own header comment warns against for a second slug
+ * source. Zero I/O, additive export — takes an already-derived node, returns
+ * data, never reads a file (aeg-core purity, #372/#382/#506).
+ */
+
+import type { DiagramNode } from '../diagram-model'
+import { nodeDocRoute } from './node-route'
+
+/**
+ * A doctrine cell's own text renamed outright (not a G-code strip, not an
+ * over-length cut) is the one case this file cannot derive. `node.id` is
+ * `slugify(row.action)` computed fresh from whatever `enforcement.md` says
+ * RIGHT NOW — by the time a rename lands, the old text is gone from the
+ * doctrine snapshot entirely, so there is nothing left in `node.id`/
+ * `node.label` for a derivation to diff against. This is not a second
+ * routing authority — `nodeSlug()`/`nodeDocRoute()` still compute every
+ * live anchor unconditionally; this map only remembers what one specific
+ * anchor used to be before an editor rewrote the cell it came from, and it
+ * grows by exactly one entry, once, at the moment of a rename. Keyed by the
+ * node id the rename produced. */
+const RENAMED_CELL_ALIASES: Record<string, string> = {
+  'check:coherence-check': 'coherence-oracle'
+}
+
+/**
+ * The anchor slugs this node used to publish and must continue to answer
+ * to. `[]` when the node's canonical slug is unchanged — most nodes, since
+ * `nodeSlug()`'s cleanup is a no-op on an already-clean display form.
+ */
+export function legacyAnchorSlugs(node: DiagramNode): string[] {
+  const rawSlug = node.id.slice(node.kind.length + 1)
+  const canonicalSlug = nodeDocRoute(node)?.slug
+  const aliases = new Set<string>()
+  if (canonicalSlug && canonicalSlug !== rawSlug) aliases.add(rawSlug)
+  const renamed = RENAMED_CELL_ALIASES[node.id]
+  if (renamed) aliases.add(renamed)
+  return [...aliases]
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/nav-helpers.ts

@@ -0,0 +1,17 @@
+import type { Doc, DocNav } from './types'
+
+export function findDoc(nav: DocNav, slug: string): Doc | undefined {
+  return nav.flat.find((d) => d.slug === slug)
+}
+
+export function getNextDoc(nav: DocNav, slug: string): Doc | undefined {
+  const idx = nav.flat.findIndex((d) => d.slug === slug)
+  if (idx === -1 || idx === nav.flat.length - 1) return undefined
+  return nav.flat[idx + 1]
+}
+
+export function getPrevDoc(nav: DocNav, slug: string): Doc | undefined {
+  const idx = nav.flat.findIndex((d) => d.slug === slug)
+  if (idx <= 0) return undefined
+  return nav.flat[idx - 1]
+}