@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/src/basis/bm51-tables.ts

@@ -0,0 +1,65 @@
+/**
+ * Read the BM-51 screen-spec tables that carry item ids (company standard, DOS-12.0).
+ *
+ * `reports/mng/specs/_templates/BM-2-901-51-screen-specification-template.md`:
+ *   §4.1 Item          `| ID | Item Name | Item Type | Required | Note |`  — bold section row `A`, then `1.0`, `2.0` …
+ *   §4.2 Validation    `| ID | Type | Min | Max | Default | … |`          — rows keyed by the composed id `A-2`
+ *   §4.3 Data Mapping  `| ID | Data Source | API ID | … |`                — same key
+ *   §5   Event         `| ID | Given (Pre-condition) | … |`               — same key, or `-`
+ *
+ * Tables are recognised by their header (first column `ID` plus the second column's name), not by
+ * heading numbers, so a translated heading still reads. Rows keep their 1-based source line.
+ */
+import { composeItemId } from './anchor-grammar';
+
+export type Bm51TableKind = 'item' | 'validation' | 'mapping' | 'event';
+
+export interface Bm51Row { table: Bm51TableKind; cells: string[]; id: string; line: number }
+export interface Bm51ItemRow extends Bm51Row { section: string | null; itemId: string | null }
+export interface Bm51Tables { items: Bm51ItemRow[]; validations: Bm51Row[]; mappings: Bm51Row[]; events: Bm51Row[] }
+
+const SEPARATOR = /^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+const COMPOSED_ID = /^[A-Z]+-\d+(?:\.\d+)?$/;
+
+function splitRow(line: string): string[] {
+  const body = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return body.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}
+const bare = (cell: string): string => cell.replace(/\*\*|__|`/g, '').trim();
+
+function kindOf(header: string[]): Bm51TableKind | null {
+  if (bare(header[0] ?? '').toUpperCase() !== 'ID') return null;
+  const second = bare(header[1] ?? '').toLowerCase();
+  if (second === 'item name') return 'item';
+  if (second === 'type') return 'validation';
+  if (second === 'data source') return 'mapping';
+  if (second.startsWith('given')) return 'event';
+  return null;
+}
+
+/** `lines` are the spec's lines; `firstLine` is the 1-based number of `lines[0]`. */
+export function readBm51Tables(lines: string[], firstLine = 1): Bm51Tables {
+  const out: Bm51Tables = { items: [], validations: [], mappings: [], events: [] };
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (!lines[i].trim().startsWith('|') || !SEPARATOR.test(lines[i + 1].trim())) continue;
+    const kind = kindOf(splitRow(lines[i]));
+    let j = i + 2;
+    let section: string | null = null;
+    for (; j < lines.length && lines[j].trim().startsWith('|'); j++) {
+      if (!kind) continue;
+      const cells = splitRow(lines[j]);
+      const id = bare(cells[0] ?? '');
+      const line = firstLine + j;
+      if (kind === 'item') {
+        if (/^[A-Z]+$/.test(id)) { section = id; continue; }
+        if (!/^\d+(?:\.\d+)?$/.test(id)) continue;
+        out.items.push({ table: kind, cells, id, line, section, itemId: composeItemId(section, id) });
+      } else if (COMPOSED_ID.test(id)) {
+        const row: Bm51Row = { table: kind, cells, id, line };
+        (kind === 'validation' ? out.validations : kind === 'mapping' ? out.mappings : out.events).push(row);
+      }
+    }
+    i = j - 1;
+  }
+  return out;
+}

package/src/basis/extract-spec-anchors.ts

@@ -0,0 +1,95 @@
+/**
+ * Every anchor a `spec.md` offers, with its hash, confidence label and citation (DOS-12.1 – 12.3).
+ *
+ *   section  `sec-<slug>`             sha1-12 of the section body (the manifest's hash)   INFERRED
+ *   item     `<docId>#<itemId>`       sha256-12 of the normalized §4.1 row                EXTRACTED
+ *   val      `<docId>#<itemId>/val`   sha256-12 of the normalized §4.2 row                EXTRACTED
+ *   a duplicate id, or a §4.2 row naming no §4.1 item                                    AMBIGUOUS
+ *
+ * A §4.3 / §5 row naming no §4.1 item is reported in `orphans` (AMBIGUOUS, not an error). Item
+ * anchors need a docId (frontmatter `id`); without one only section anchors exist. Pointers and
+ * hashes only — no spec text leaves this function (red-team #14).
+ */
+import { AnchorConfidence, AnchorKind, CitationBase, formatCitation, itemAnchorId, sectionAnchorId } from './anchor-grammar';
+import { HashAlgo, itemRowHash, sectionHash } from './anchor-hash';
+import { readBm51Tables } from './bm51-tables';
+import { normalizeSectionName, readSpecSectionBlocks } from './spec-sections';
+import { readSpecFrontmatter, SpecFrontmatter } from './spec-frontmatter';
+
+export interface SourceAnchor {
+  id: string;
+  kind: AnchorKind;
+  confidence: AnchorConfidence;
+  hash: string;
+  hashAlgo: HashAlgo;
+  location: string;
+  /** Why the label is AMBIGUOUS. */
+  note?: string;
+}
+
+export interface OrphanReference { table: 'mapping' | 'event'; itemId: string; location: string; confidence: 'AMBIGUOUS' }
+
+export interface SpecAnchors {
+  frontmatter: SpecFrontmatter;
+  anchors: SourceAnchor[];
+  orphans: OrphanReference[];
+  problems: string[];
+}
+
+/** Mark every anchor whose id occurs more than once as AMBIGUOUS — a human must pick. */
+function flagDuplicates(anchors: SourceAnchor[]): void {
+  const count = new Map<string, number>();
+  for (const a of anchors) count.set(a.id, (count.get(a.id) ?? 0) + 1);
+  for (const a of anchors) {
+    if ((count.get(a.id) ?? 0) > 1) { a.confidence = 'AMBIGUOUS'; a.note = 'duplicate id'; }
+  }
+}
+
+export function extractSpecAnchors(text: string, citation: CitationBase): SpecAnchors {
+  const lines = text.replace(/^/, '').replace(/\r\n?/g, '\n').split('\n');
+  const fm = readSpecFrontmatter(text, citation.path);
+  const problems = [...fm.problems];
+  const cite = (start: number, end: number): string => formatCitation(citation, start, end);
+
+  const sections: SourceAnchor[] = readSpecSectionBlocks(lines).map((s) => ({
+    id: sectionAnchorId(normalizeSectionName(s.name)),
+    kind: 'section',
+    confidence: 'INFERRED',
+    hash: sectionHash(s.body),
+    hashAlgo: 'sha1-12',
+    location: cite(s.headingIndex + 1, s.headingIndex + 1 + s.body.length),
+  }));
+  flagDuplicates(sections);
+
+  const docId = fm.frontmatter.id;
+  const tables = readBm51Tables(lines);
+  const items: SourceAnchor[] = [];
+  const orphans: OrphanReference[] = [];
+  if (!docId) {
+    if (tables.items.length) problems.push(`${citation.path}: a BM-51 item table is present but the frontmatter has no id; no item anchors`);
+    return { frontmatter: fm.frontmatter, anchors: sections, orphans, problems };
+  }
+
+  for (const row of tables.items) {
+    if (!row.itemId) { problems.push(`${citation.path}:${row.line}: item ${row.id} has no section row above it; skipped`); continue; }
+    items.push({ id: itemAnchorId(docId, row.itemId), kind: 'item', confidence: 'EXTRACTED', hash: itemRowHash(row.cells), hashAlgo: 'sha256-12', location: cite(row.line, row.line) });
+  }
+  flagDuplicates(items);
+  const known = new Set(tables.items.map((r) => r.itemId).filter(Boolean));
+
+  const vals: SourceAnchor[] = tables.validations.map((row) => ({
+    id: itemAnchorId(docId, row.id, true),
+    kind: 'validation',
+    confidence: known.has(row.id) ? 'EXTRACTED' : 'AMBIGUOUS',
+    hash: itemRowHash(row.cells),
+    hashAlgo: 'sha256-12',
+    location: cite(row.line, row.line),
+    ...(known.has(row.id) ? {} : { note: 'no §4.1 item with this id' }),
+  }));
+  flagDuplicates(vals);
+
+  for (const row of [...tables.mappings, ...tables.events]) {
+    if (!known.has(row.id)) orphans.push({ table: row.table as 'mapping' | 'event', itemId: row.id, location: cite(row.line, row.line), confidence: 'AMBIGUOUS' });
+  }
+  return { frontmatter: fm.frontmatter, anchors: [...items, ...vals, ...sections], orphans, problems };
+}

package/src/basis/migration-sentinel.ts

@@ -0,0 +1,175 @@
+/**
+ * Write-ahead sentinel for migrations and re-baselines (takumi T6, DOS-13.6).
+ *
+ * Before a migration writes anything it records `.sungen/migrations/<slug>.pending.json`: every
+ * file it will touch plus a copy of each one's current bytes (or "did not exist"). The sentinel is
+ * deleted when the migration completes. An error inside the migration rolls the copies back at
+ * once; only a process that DIES mid-migration leaves the sentinel behind — and then the next run
+ * stops and asks a human for REVERT (restore every copy byte for byte) or KEEP (keep the new
+ * files). It never continues silently. (Reference: reports/takumi/docs/system-architecture.md:656-677.)
+ *
+ * A sentinel carries pid, host and startedAt. While its writer is alive on this host and it is under a
+ * minute old, another run is simply migrating: the answer is "retry", not a REVERT/KEEP prompt. Only a
+ * dead writer or an old sentinel is an interrupted migration. One slug per unit covers both writers:
+ * the waiver import (DOS-13.5) and the manifest upgrade to schema 2 on save (DOS-12.3).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createFileExclusive } from '../decisions/exclusive-file-create';
+
+export interface SentinelFile { path: string; existed: boolean; contentBase64?: string }
+export interface PendingMigration {
+  schema: 1; unit: string; slug: string; reason: string; startedAt: string; pid?: number; host?: string; files: SentinelFile[];
+}
+export type MigrationChoice = 'REVERT' | 'KEEP';
+export const IN_PROGRESS_WINDOW_MS = 60_000;
+
+export function sentinelPath(projectRoot: string, slug: string): string {
+  return path.join(projectRoot, '.sungen', 'migrations', `${slug}.pending.json`);
+}
+
+export class PendingMigrationError extends Error {
+  constructor(public readonly unit: string, public readonly slug: string, public readonly file: string, detail: string) {
+    super(
+      `An interrupted migration left ${file} (${detail}).\n`
+      + '  Nothing continues until a human chooses: REVERT restores every file it lists byte for byte;\n'
+      + `  KEEP keeps the new files. Run in a terminal and answer the prompt:  sungen journey --screen ${unit}`,
+    );
+    this.name = 'PendingMigrationError';
+  }
+}
+
+/** The sentinel, or null when there is none. An unreadable sentinel still exists: `files` is then empty. */
+export function readPendingMigration(projectRoot: string, slug: string): (PendingMigration & { readable: boolean }) | null {
+  const p = sentinelPath(projectRoot, slug);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as PendingMigration;
+    if (raw && raw.schema === 1 && Array.isArray(raw.files)) return { ...raw, readable: true };
+  } catch { /* fall through: a sentinel that cannot be read is still a stop sign */ }
+  return { schema: 1, unit: slug, slug, reason: 'unreadable sentinel', startedAt: '?', files: [], readable: false };
+}
+
+export class MigrationInProgressError extends Error {
+  constructor(public readonly unit: string, detail: string) {
+    super(`Another sungen run is migrating ${unit} right now (${detail}). Retry in a moment — nothing was changed.`);
+    this.name = 'MigrationInProgressError';
+  }
+}
+
+function pidAlive(pid: unknown): boolean {
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+/** in-progress: under a minute old and written by a process alive on this host (another host cannot be checked). */
+export function pendingMigrationState(p: PendingMigration & { readable: boolean }): 'in-progress' | 'interrupted' {
+  if (!p.readable) return 'interrupted';
+  const age = Date.now() - Date.parse(p.startedAt);
+  if (!(age >= 0 && age < IN_PROGRESS_WINDOW_MS)) return 'interrupted';
+  if (p.host !== os.hostname()) return 'in-progress';
+  return pidAlive(p.pid) ? 'in-progress' : 'interrupted';
+}
+
+function pendingError(projectRoot: string, slug: string, pending: PendingMigration & { readable: boolean }): Error {
+  if (pendingMigrationState(pending) === 'in-progress') {
+    const age = Math.round((Date.now() - Date.parse(pending.startedAt)) / 1000);
+    return new MigrationInProgressError(pending.unit, `pid ${pending.pid} on ${pending.host}, started ${age}s ago: ${pending.reason}`);
+  }
+  const rel = path.relative(projectRoot, sentinelPath(projectRoot, slug));
+  return new PendingMigrationError(pending.unit, slug, rel, `started ${pending.startedAt}: ${pending.reason}`);
+}
+
+/** Throws MigrationInProgressError (retry) or PendingMigrationError (REVERT/KEEP) when a sentinel exists. */
+export function assertNoPendingMigration(projectRoot: string, slug: string): void {
+  const pending = readPendingMigration(projectRoot, slug);
+  if (pending) throw pendingError(projectRoot, slug, pending);
+}
+
+/** A sentinel path must stay inside the project — it is data read back from disk. */
+function inside(projectRoot: string, rel: string): string {
+  const abs = path.resolve(projectRoot, rel);
+  const back = path.relative(path.resolve(projectRoot), abs);
+  if (path.isAbsolute(rel) || back === '' || back.startsWith('..') || path.isAbsolute(back)) {
+    throw new Error(`refusing to restore "${rel}": outside the project`);
+  }
+  return abs;
+}
+
+/** Bytes, not text: REVERT must restore a file exactly, whatever its encoding. Tmp + rename = atomic. */
+function writeBytesAtomic(abs: string, bytes: Buffer): void {
+  const tmp = `${abs}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, bytes);
+    fs.renameSync(tmp, abs);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+function restore(projectRoot: string, files: SentinelFile[]): string[] {
+  const done: string[] = [];
+  for (const f of files) {
+    const abs = inside(projectRoot, f.path);
+    if (f.existed) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      writeBytesAtomic(abs, Buffer.from(f.contentBase64 ?? '', 'base64'));
+    } else {
+      fs.rmSync(abs, { force: true });
+    }
+    done.push(f.path);
+  }
+  return done;
+}
+
+/**
+ * Run `write` under a sentinel covering `files` (absolute paths). The sentinel is written atomically
+ * before `write` starts and removed after it returns. If `write` throws, the copies are restored and
+ * the sentinel removed before the error is rethrown; a failed rollback leaves the sentinel in place.
+ */
+export function withMigrationSentinel<T>(
+  projectRoot: string, unit: string, slug: string, reason: string, files: string[], write: () => T,
+): T {
+  assertNoPendingMigration(projectRoot, slug);
+  const snapshot: SentinelFile[] = files.map((abs) => {
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    inside(projectRoot, rel);
+    return fs.existsSync(abs)
+      ? { path: rel, existed: true, contentBase64: fs.readFileSync(abs).toString('base64') }
+      : { path: rel, existed: false };
+  });
+  const p = sentinelPath(projectRoot, slug);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const pending: PendingMigration = {
+    schema: 1, unit, slug, reason, startedAt: new Date().toISOString(), pid: process.pid, host: os.hostname(), files: snapshot,
+  };
+  // Exclusive: a second migration of the same unit racing this one cannot also believe it holds it.
+  if (!createFileExclusive(p, `${JSON.stringify(pending, null, 2)}\n`)) {
+    const holder = readPendingMigration(projectRoot, slug);
+    throw holder ? pendingError(projectRoot, slug, holder) : new MigrationInProgressError(unit, 'it just finished');
+  }
+  let result: T;
+  try {
+    result = write();
+  } catch (err) {
+    restore(projectRoot, snapshot);   // throws → the sentinel stays: the next run asks REVERT/KEEP
+    fs.rmSync(p, { force: true });
+    throw err;
+  }
+  fs.rmSync(p, { force: true });
+  return result;
+}
+
+/** Answer a leftover sentinel. REVERT restores every listed file exactly; KEEP only removes the sentinel. */
+export function resolvePendingMigration(projectRoot: string, slug: string, choice: MigrationChoice): string[] {
+  const pending = readPendingMigration(projectRoot, slug);
+  if (!pending) return [];
+  if (choice === 'REVERT' && !pending.readable) {
+    throw new Error(`${sentinelPath(projectRoot, slug)} cannot be read, so there is nothing to restore from — choose KEEP.`);
+  }
+  const restored = choice === 'REVERT' ? restore(projectRoot, pending.files) : [];
+  fs.rmSync(sentinelPath(projectRoot, slug), { force: true });
+  return restored;
+}

package/src/basis/spec-frontmatter.ts

@@ -0,0 +1,68 @@
+/**
+ * Optional `spec.md` frontmatter (DOS-12.2).
+ *
+ * `source_mode: linked|authored` (default `authored`), `id` and `version` (both in the BM-51
+ * template), and `status`, `superseded_by` when present. `screen_id` is kept as metadata only — it
+ * never enters an anchor. No frontmatter = the old behavior, so this never throws: a malformed
+ * block is reported as a problem and read as absent.
+ */
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { isDocId } from './anchor-grammar';
+
+export type SourceMode = 'linked' | 'authored';
+
+export interface SpecFrontmatter {
+  source_mode: SourceMode;
+  id?: string;
+  version?: string;
+  status?: string;
+  superseded_by?: string;
+  screen_id?: string;
+}
+
+export interface FrontmatterRead {
+  present: boolean;
+  frontmatter: SpecFrontmatter;
+  /** 0-based index of the first line after the closing fence (0 when there is no frontmatter). */
+  bodyStartIndex: number;
+  problems: string[];
+}
+
+const scalar = (v: unknown): string | undefined =>
+  typeof v === 'string' ? v.trim() || undefined : typeof v === 'number' ? String(v) : undefined;
+
+export function readSpecFrontmatter(text: string, source = 'spec.md'): FrontmatterRead {
+  const absent: FrontmatterRead = { present: false, frontmatter: { source_mode: 'authored' }, bodyStartIndex: 0, problems: [] };
+  const lines = text.replace(/^/, '').replace(/\r\n?/g, '\n').split('\n');
+  if (lines[0]?.trim() !== '---') return absent;
+  const close = lines.findIndex((l, i) => i > 0 && (l.trim() === '---' || l.trim() === '...'));
+  if (close < 0) return { ...absent, problems: [`${source}: frontmatter opened with --- but never closed; read as absent`] };
+
+  const problems: string[] = [];
+  let raw: unknown;
+  try {
+    raw = safeYamlParse(lines.slice(1, close).join('\n'), `${source} frontmatter`);
+  } catch (err) {
+    return { ...absent, bodyStartIndex: close + 1, problems: [err instanceof Error ? err.message : String(err)] };
+  }
+  if (raw === null || raw === undefined) raw = {};
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...absent, bodyStartIndex: close + 1, problems: [`${source}: frontmatter is not a mapping; read as absent`] };
+  }
+  const fm = raw as Record<string, unknown>;
+  const out: SpecFrontmatter = { source_mode: 'authored' };
+
+  const mode = scalar(fm.source_mode);
+  if (mode === 'linked' || mode === 'authored') out.source_mode = mode;
+  else if (mode !== undefined) problems.push(`${source}: source_mode "${mode}" is not linked|authored; using authored`);
+
+  const id = scalar(fm.id);
+  if (id && isDocId(id)) out.id = id;
+  else if (id) problems.push(`${source}: id "${id}" is not a document id like SPEC-AUTH-001; item anchors are not derived`);
+
+  for (const key of ['version', 'status', 'superseded_by', 'screen_id'] as const) {
+    const v = scalar(fm[key]);
+    if (v) out[key] = v;
+  }
+  return { present: true, frontmatter: out, bodyStartIndex: close + 1, problems };
+}

package/src/basis/spec-sections.ts

@@ -0,0 +1,35 @@
+/**
+ * The `##` / `###` section split of `spec.md`, shared by the manifest and the anchor reader so a
+ * `sec-<slug>` anchor and a manifest section can never disagree about where a section starts or
+ * what it hashes. The rules are the manifest's original ones, moved here unchanged (red-team #1):
+ * every line is scanned, a `Section:` prefix is stripped, the body is everything up to the next
+ * `##`/`###` heading.
+ */
+export interface SpecSectionBlock {
+  /** Heading text with any `Section:` prefix stripped (not yet normalized). */
+  name: string;
+  /** 0-based index of the heading line. */
+  headingIndex: number;
+  body: string[];
+}
+
+export function readSpecSectionBlocks(lines: string[]): SpecSectionBlock[] {
+  const out: SpecSectionBlock[] = [];
+  let cur: SpecSectionBlock | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const h = lines[i].match(/^#{2,3}\s+(.*)$/);
+    if (h) {
+      if (cur) out.push(cur);
+      cur = { name: h[1].replace(/^Section:\s*/i, '').trim(), headingIndex: i, body: [] };
+    } else if (cur) {
+      cur.body.push(lines[i]);
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/** The manifest's section-name key: tier suffix and markdown marks dropped, lower-case, spaces collapsed. */
+export function normalizeSectionName(s: string): string {
+  return s.replace(/\(Tier[^)]*\)/i, '').replace(/[#*-]/g, '').trim().toLowerCase().replace(/\s+/g, ' ');
+}

package/src/basis/test-basis-schema.ts

@@ -0,0 +1,81 @@
+/**
+ * Test-basis schema, validator and reader (DOS-12.4). P0 ships only these; the generator and a
+ * `BasisProvider` are P1, and there is no `basis.hand-edited` rule.
+ *
+ *   { schema, source_mode, sources:[{docId, uri, version, hash}], anchors:[{id, kind, hash, location}] }
+ *
+ * It stores pointers and hashes, NEVER spec text (red-team #14). The validator enforces that
+ * structurally rather than by promise: unknown keys, multi-line values and long strings are refused,
+ * and every id, hash and citation must parse.
+ */
+import * as fs from 'fs';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { AnchorKind, isDocId, parseAnchorId, parseCitation } from './anchor-grammar';
+import { SourceMode } from './spec-frontmatter';
+
+export const TEST_BASIS_SCHEMA = 1;
+
+export interface TestBasisSource { docId: string; uri: string; version: string; hash: string }
+export interface TestBasisAnchor { id: string; kind: AnchorKind; hash: string; location: string }
+export interface TestBasis { schema: 1; source_mode: SourceMode; sources: TestBasisSource[]; anchors: TestBasisAnchor[] }
+
+const MAX_LEN: Record<string, number> = { docId: 64, uri: 2048, version: 64, hash: 64, id: 256, kind: 16, location: 2048 };
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** A pointer field: a short single-line string. Anything longer or multi-line is text, not a pointer. */
+function pointerErrors(where: string, obj: Record<string, unknown>, keys: string[]): string[] {
+  const e: string[] = [];
+  for (const k of Object.keys(obj)) if (!keys.includes(k)) e.push(`${where}: unknown key "${k}" (a test-basis holds pointers and hashes, never spec text)`);
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v !== 'string' || !v.trim()) e.push(`${where}.${k} must be a non-empty string`);
+    else if (/[\r\n]/.test(v) || v.length > MAX_LEN[k]) e.push(`${where}.${k} must be a single line of at most ${MAX_LEN[k]} characters`);
+  }
+  return e;
+}
+
+export function validateTestBasis(raw: unknown): string[] {
+  if (!isObject(raw)) return ['test-basis must be a mapping'];
+  const e: string[] = [];
+  for (const k of Object.keys(raw)) if (!['schema', 'source_mode', 'sources', 'anchors'].includes(k)) e.push(`unknown top-level key "${k}"`);
+  if (raw.schema !== TEST_BASIS_SCHEMA) e.push(`schema must be ${TEST_BASIS_SCHEMA}`);
+  if (raw.source_mode !== 'linked' && raw.source_mode !== 'authored') e.push('source_mode must be linked|authored');
+
+  const docIds = new Set<string>();
+  if (!Array.isArray(raw.sources)) e.push('sources must be a list');
+  else raw.sources.forEach((s, i) => {
+    if (!isObject(s)) { e.push(`sources[${i}] must be a mapping`); return; }
+    e.push(...pointerErrors(`sources[${i}]`, s, ['docId', 'uri', 'version', 'hash']));
+    if (typeof s.docId === 'string' && !isDocId(s.docId)) e.push(`sources[${i}].docId "${s.docId}" is not a document id like SPEC-AUTH-001`);
+    if (typeof s.hash === 'string' && !/^[0-9a-f]{12,64}$/.test(s.hash)) e.push(`sources[${i}].hash must be 12-64 lowercase hex`);
+    if (typeof s.docId === 'string') docIds.add(s.docId);
+  });
+
+  const seen = new Set<string>();
+  if (!Array.isArray(raw.anchors)) e.push('anchors must be a list');
+  else raw.anchors.forEach((a, i) => {
+    if (!isObject(a)) { e.push(`anchors[${i}] must be a mapping`); return; }
+    e.push(...pointerErrors(`anchors[${i}]`, a, ['id', 'kind', 'hash', 'location']));
+    const parsed = typeof a.id === 'string' ? parseAnchorId(a.id) : null;
+    if (!parsed) e.push(`anchors[${i}].id "${a.id}" is not an anchor (SPEC-ID#A-2, SPEC-ID#A-2/val, sec-<slug>)`);
+    else if (parsed.kind !== a.kind) e.push(`anchors[${i}].kind "${a.kind}" disagrees with its id (${parsed.kind})`);
+    if (parsed?.docId && !docIds.has(parsed.docId)) e.push(`anchors[${i}] points into ${parsed.docId}, which is not a listed source`);
+    if (typeof a.hash === 'string' && !/^[0-9a-f]{12}$/.test(a.hash)) e.push(`anchors[${i}].hash must be 12 lowercase hex (sha1-12 or sha256-12)`);
+    if (typeof a.location === 'string' && !parseCitation(a.location)) e.push(`anchors[${i}].location must be repo@SHA:path#Lx-Ly`);
+    if (typeof a.id === 'string') { if (seen.has(a.id)) e.push(`anchors[${i}].id "${a.id}" is listed twice`); seen.add(a.id); }
+  });
+  return e;
+}
+
+/** Best-effort reader: no file → no basis (an authored spec); a bad file → problems, never a throw. */
+export function readTestBasis(file: string): { basis?: TestBasis; problems: string[] } {
+  if (!fs.existsSync(file)) return { problems: [] };
+  let raw: unknown;
+  try {
+    raw = safeYamlParse(fs.readFileSync(file, 'utf8'), file);
+  } catch (err) {
+    return { problems: [err instanceof Error ? err.message : String(err)] };
+  }
+  const problems = validateTestBasis(raw);
+  return problems.length ? { problems } : { basis: raw as TestBasis, problems };
+}

package/src/capabilities/discover.ts

@@ -123,8 +123,11 @@ function versionSkewWarning(name: string, loaded: string | undefined, core: stri
   );
 }
 
-function loadExternalDriver(name: string): void {
-  const bundled = BUNDLED_DRIVERS.has(name);
+/** The bundled drivers, by package name (sorted). */
+export const bundledDriverNames = (): string[] => [...BUNDLED_DRIVERS].sort();
+
+/** Every installed copy of a driver, from the project and from core, with the requires that found them. */
+function driverCopies(name: string): { copies: DriverCopy[]; requires: Map<string, NodeRequire> } {
   // Look from the user's PROJECT and from core's own location. Opt-in drivers (`sungen capability add
   // db|api`) install into the PROJECT's node_modules — a globally-installed core (`npm i -g`) wouldn't
   // see them via a core-anchored `require`. The bundled @sungen/driver-ui is a core dependency
@@ -144,7 +147,17 @@ function loadExternalDriver(name: string): void {
     requires.set(resolved, req);
     copies.push({ anchor, resolved, version: readDriverVersion(req, name, resolved) });
   }
+  return { copies, requires };
+}
 
+/** The copy of a driver discovery would load (the same anchors and pick), or undefined when none resolves. */
+export function resolveDriverCopy(name: string): DriverCopy | undefined {
+  return pickDriverCopy(driverCopies(name).copies, coreVersion(), BUNDLED_DRIVERS.has(name));
+}
+
+function loadExternalDriver(name: string): void {
+  const bundled = BUNDLED_DRIVERS.has(name);
+  const { copies, requires } = driverCopies(name);
   const core = coreVersion();
   const chosen = pickDriverCopy(copies, core, bundled);
   if (chosen) {

package/src/capabilities/registry.ts

@@ -14,6 +14,7 @@
 import type { StepPattern } from '../generators/test-generator/patterns/types';
 import type { Sensor } from './sensor';
 import type { DiscoveryProvider, ContextMapper, RepairProvider } from './context';
+import type { TraceIdentityResolver } from '../contract/trace/target-identity';
 
 export interface CapabilityDescriptor {
   /** Stable id: 'ui' | 'db' | 'api' | 'core' | … */
@@ -70,6 +71,21 @@ export interface CapabilityDescriptor {
    */
   appProfilePresets?: Record<string, unknown>;
 
+  /**
+   * Target-identity resolver for trace-derived contracts: maps a replayed page snapshot + a
+   * recorded action to `{role, name, identityConfidence}` using the runtime's own accessibility
+   * engine (UI → Playwright `getByRole` / `ariaSnapshot`). Spec: `sungen_capability_spi_spec.md`
+   * §4.5, `sungen_durable_orchestration_spec.md` DOS-14.5.
+   *
+   * Pinned in phase 08 (the phase 07 spike gate passed): core renders each snapshot as inert HTML
+   * and asks the resolver for role + name + optional scope per target; a result that is not
+   * well-formed is rejected, and anything core already knows forces `low` (missing CSS…). Called
+   * only by `sungen contract check --trace` / `contract derive`; the verdict reads the cached
+   * answers. There is deliberately no `nodes?` slot: the graph node API is internal to core in P0
+   * (OES-10).
+   */
+  traceIdentity?: TraceIdentityResolver;
+
   // --- Declared for later R-steps; not consumed yet (kept here so the SPI shape is visible). ---
   // adapter?: string;                  // codegen adapter id (existing adapterRegistry)
 }

package/src/cli/commands/audit.ts

@@ -30,7 +30,7 @@ function render(r: AuditReport): void {
   L('');
   L(`  Quality score (business-weighted): ${r.score.overall}/10   [Viewpoint Gate: ${r.gateStatus}]`);
   L(`  Intent: focus=${r.intent.focus} · depth threshold ${r.depth.threshold.toFixed(2)} (${r.intent.source})`);
-  L(`  Provenance: sungen ${r.provenance.sungenVersion} · catalog ${r.provenance.catalogHash}  (same here on every machine → same score)`);
+  L(`  Provenance: sungen ${r.provenance.sungenVersion} · catalog ${r.provenance.catalogHash} · rules ${r.provenance.rulesHash}  (same rules on every machine → same score)`);
   // Print the axes the score was ACTUALLY built from — a fixed five-line block omitted a flow's
   // `flowCoverage`, `specFR` and `atomicLedger` while showing `balance`, which a contract flow
   // does not score on.
@@ -180,7 +180,7 @@ export function registerAuditCommand(program: Command): void {
         const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
-        const report = runAudit(dir, name);
+        let report = runAudit(dir, name);
 
         // The baseline is only ever written HERE, never by the measurement itself:
         // a first sighting has nothing to compare against, and any later change is
@@ -201,9 +201,14 @@ export function registerAuditCommand(program: Command): void {
         if (vb.reparsed) acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
         if ((vb.status === 'new' && !postHoc) || (options.acceptViewpoint && (vb.status === 'changed' || postHoc))) {
           acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
-          if (options.acceptViewpoint && !options.json) {
-            console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
-            console.log('    Re-run the audit to score atomicLedger + traceability against it.\n');
+          if (options.acceptViewpoint) {
+            // Measure again against what was just accepted: the report printed and saved below (the
+            // one `sungen next` reads) must not be the pre-accept one, still holding the axes (#867).
+            report = runAudit(dir, name);
+            if (!options.json) {
+              console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
+              console.log('    The report below is measured against it.\n');
+            }
           }
         } else if (options.acceptViewpoint && !options.json) {
           // `absent` covers a file with no readable viewpoint id too — say which (#832).

package/src/cli/commands/capability.ts

@@ -209,7 +209,7 @@ export function registerCapabilityCommand(program: Command): void {
           // beta channel can lag (e.g. a prerelease first-published-as-latest), pulling a driver
           // whose core dep resolves to the wrong @sun-asterisk/sungen and fails to load.
           const core = coreVersion();
-          const target = resolveDriverVersion(meta.package, core); // exact core, else same-line beta, else 'beta' tag
+          const target = resolveDriverVersion(meta.package, core); // exact core, else same-line build of core's channel, else that channel's tag
           const spec = `${meta.package}@${target}`;
           if (target !== core) {
             console.log(`ℹ ${meta.package}@${core} is not published yet — installing ${spec} (closest on the ${core} line).`);
@@ -265,7 +265,9 @@ export function registerCapabilityCommand(program: Command): void {
           else console.log('  – skipped  appium-environment/ (already exists)');
 
           // Best-effort driver install — non-fatal so capability add still succeeds offline.
-          installMobileDriver(cwd);
+          // --skip-install promises no npm install; the driver + wdio/appium runtime is ~290 MB.
+          if (o.skipInstall) console.log('  – skipped  mobile driver install (--skip-install) — later: sungen capability add mobile');
+          else installMobileDriver(cwd);
 
           // --skip-install means "record only" — then provisioning the machine is not wanted either.
           runAppiumEnvironmentSetup(cwd, { skip: !!(o.skipEnvSetup || o.skipInstall) });