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

package/dist/basis/migration-sentinel.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationInProgressError = exports.PendingMigrationError = exports.IN_PROGRESS_WINDOW_MS = void 0;
+exports.sentinelPath = sentinelPath;
+exports.readPendingMigration = readPendingMigration;
+exports.pendingMigrationState = pendingMigrationState;
+exports.assertNoPendingMigration = assertNoPendingMigration;
+exports.withMigrationSentinel = withMigrationSentinel;
+exports.resolvePendingMigration = resolvePendingMigration;
+/**
+ * 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).
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const exclusive_file_create_1 = require("../decisions/exclusive-file-create");
+exports.IN_PROGRESS_WINDOW_MS = 60000;
+function sentinelPath(projectRoot, slug) {
+    return path.join(projectRoot, '.sungen', 'migrations', `${slug}.pending.json`);
+}
+class PendingMigrationError extends Error {
+    constructor(unit, slug, file, detail) {
+        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.unit = unit;
+        this.slug = slug;
+        this.file = file;
+        this.name = 'PendingMigrationError';
+    }
+}
+exports.PendingMigrationError = PendingMigrationError;
+/** The sentinel, or null when there is none. An unreadable sentinel still exists: `files` is then empty. */
+function readPendingMigration(projectRoot, slug) {
+    const p = sentinelPath(projectRoot, slug);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+        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 };
+}
+class MigrationInProgressError extends Error {
+    constructor(unit, detail) {
+        super(`Another sungen run is migrating ${unit} right now (${detail}). Retry in a moment — nothing was changed.`);
+        this.unit = unit;
+        this.name = 'MigrationInProgressError';
+    }
+}
+exports.MigrationInProgressError = MigrationInProgressError;
+function pidAlive(pid) {
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/** in-progress: under a minute old and written by a process alive on this host (another host cannot be checked). */
+function pendingMigrationState(p) {
+    if (!p.readable)
+        return 'interrupted';
+    const age = Date.now() - Date.parse(p.startedAt);
+    if (!(age >= 0 && age < exports.IN_PROGRESS_WINDOW_MS))
+        return 'interrupted';
+    if (p.host !== os.hostname())
+        return 'in-progress';
+    return pidAlive(p.pid) ? 'in-progress' : 'interrupted';
+}
+function pendingError(projectRoot, slug, pending) {
+    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. */
+function assertNoPendingMigration(projectRoot, slug) {
+    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, rel) {
+    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, bytes) {
+    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, files) {
+    const done = [];
+    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.
+ */
+function withMigrationSentinel(projectRoot, unit, slug, reason, files, write) {
+    assertNoPendingMigration(projectRoot, slug);
+    const snapshot = 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 = {
+        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 (!(0, exclusive_file_create_1.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;
+    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. */
+function resolvePendingMigration(projectRoot, slug, choice) {
+    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;
+}
+//# sourceMappingURL=migration-sentinel.js.map

package/dist/basis/migration-sentinel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-sentinel.js","sourceRoot":"","sources":["../../src/basis/migration-sentinel.ts"],"names":[],"mappings":"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"}

package/dist/basis/spec-frontmatter.d.ts

@@ -0,0 +1,18 @@
+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[];
+}
+export declare function readSpecFrontmatter(text: string, source?: string): FrontmatterRead;
+//# sourceMappingURL=spec-frontmatter.d.ts.map

package/dist/basis/spec-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-frontmatter.d.ts","sourceRoot":"","sources":["../../src/basis/spec-frontmatter.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,UAAU,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,eAAe,CAAC;IAC7B,gGAAgG;IAChG,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAY,GAAG,eAAe,CAkCrF"}

package/dist/basis/spec-frontmatter.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSpecFrontmatter = readSpecFrontmatter;
+/**
+ * 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.
+ */
+const safe_yaml_parse_1 = require("../utils/safe-yaml-parse");
+const anchor_grammar_1 = require("./anchor-grammar");
+const scalar = (v) => typeof v === 'string' ? v.trim() || undefined : typeof v === 'number' ? String(v) : undefined;
+function readSpecFrontmatter(text, source = 'spec.md') {
+    const absent = { 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 = [];
+    let raw;
+    try {
+        raw = (0, safe_yaml_parse_1.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;
+    const out = { 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 && (0, anchor_grammar_1.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']) {
+        const v = scalar(fm[key]);
+        if (v)
+            out[key] = v;
+    }
+    return { present: true, frontmatter: out, bodyStartIndex: close + 1, problems };
+}
+//# sourceMappingURL=spec-frontmatter.js.map

package/dist/basis/spec-frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-frontmatter.js","sourceRoot":"","sources":["../../src/basis/spec-frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/basis/spec-sections.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare function readSpecSectionBlocks(lines: string[]): SpecSectionBlock[];
+/** The manifest's section-name key: tier suffix and markdown marks dropped, lower-case, spaces collapsed. */
+export declare function normalizeSectionName(s: string): string;
+//# sourceMappingURL=spec-sections.d.ts.map

package/dist/basis/spec-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-sections.d.ts","sourceRoot":"","sources":["../../src/basis/spec-sections.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAczE;AAED,6GAA6G;AAC7G,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/basis/spec-sections.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSpecSectionBlocks = readSpecSectionBlocks;
+exports.normalizeSectionName = normalizeSectionName;
+function readSpecSectionBlocks(lines) {
+    const out = [];
+    let cur = 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. */
+function normalizeSectionName(s) {
+    return s.replace(/\(Tier[^)]*\)/i, '').replace(/[#*-]/g, '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+//# sourceMappingURL=spec-sections.js.map

package/dist/basis/spec-sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-sections.js","sourceRoot":"","sources":["../../src/basis/spec-sections.ts"],"names":[],"mappings":";;AAeA,sDAcC;AAGD,oDAEC;AAnBD,SAAgB,qBAAqB,CAAC,KAAe;IACnD,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,IAAI,GAAG,GAA4B,IAAI,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAC5C,IAAI,CAAC,EAAE,CAAC;YACN,IAAI,GAAG;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACvB,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACtF,CAAC;aAAM,IAAI,GAAG,EAAE,CAAC;YACf,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,IAAI,GAAG;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,6GAA6G;AAC7G,SAAgB,oBAAoB,CAAC,CAAS;IAC5C,OAAO,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACzG,CAAC"}

package/dist/basis/test-basis-schema.d.ts

@@ -0,0 +1,28 @@
+import { AnchorKind } from './anchor-grammar';
+import { SourceMode } from './spec-frontmatter';
+export declare 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[];
+}
+export declare function validateTestBasis(raw: unknown): string[];
+/** Best-effort reader: no file → no basis (an authored spec); a bad file → problems, never a throw. */
+export declare function readTestBasis(file: string): {
+    basis?: TestBasis;
+    problems: string[];
+};
+//# sourceMappingURL=test-basis-schema.d.ts.map

package/dist/basis/test-basis-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-basis-schema.d.ts","sourceRoot":"","sources":["../../src/basis/test-basis-schema.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAyC,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,MAAM,WAAW,eAAe;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC9F,MAAM,WAAW,eAAe;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACjG,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,CAAC,CAAC;IAAC,WAAW,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE;AAiBzH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CA+BxD;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAUrF"}

package/dist/basis/test-basis-schema.js

@@ -0,0 +1,141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_BASIS_SCHEMA = void 0;
+exports.validateTestBasis = validateTestBasis;
+exports.readTestBasis = readTestBasis;
+/**
+ * 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.
+ */
+const fs = __importStar(require("fs"));
+const safe_yaml_parse_1 = require("../utils/safe-yaml-parse");
+const anchor_grammar_1 = require("./anchor-grammar");
+exports.TEST_BASIS_SCHEMA = 1;
+const MAX_LEN = { docId: 64, uri: 2048, version: 64, hash: 64, id: 256, kind: 16, location: 2048 };
+const isObject = (v) => 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, obj, keys) {
+    const e = [];
+    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;
+}
+function validateTestBasis(raw) {
+    if (!isObject(raw))
+        return ['test-basis must be a mapping'];
+    const e = [];
+    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 !== exports.TEST_BASIS_SCHEMA)
+        e.push(`schema must be ${exports.TEST_BASIS_SCHEMA}`);
+    if (raw.source_mode !== 'linked' && raw.source_mode !== 'authored')
+        e.push('source_mode must be linked|authored');
+    const docIds = new Set();
+    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' && !(0, anchor_grammar_1.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();
+    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' ? (0, anchor_grammar_1.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' && !(0, anchor_grammar_1.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. */
+function readTestBasis(file) {
+    if (!fs.existsSync(file))
+        return { problems: [] };
+    let raw;
+    try {
+        raw = (0, safe_yaml_parse_1.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, problems };
+}
+//# sourceMappingURL=test-basis-schema.js.map

package/dist/basis/test-basis-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-basis-schema.js","sourceRoot":"","sources":["../../src/basis/test-basis-schema.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/discover.d.ts

@@ -27,5 +27,9 @@ export declare function sameVersionLine(a: string | undefined, b: string | undef
  * project-first order: there is no line to match against.
  */
 export declare function pickDriverCopy(copies: readonly DriverCopy[], core: string, bundled: boolean): DriverCopy | undefined;
+/** The bundled drivers, by package name (sorted). */
+export declare const bundledDriverNames: () => string[];
+/** The copy of a driver discovery would load (the same anchors and pick), or undefined when none resolves. */
+export declare function resolveDriverCopy(name: string): DriverCopy | undefined;
 export declare function discoverAndRegisterCapabilities(): void;
 //# sourceMappingURL=discover.d.ts.map

package/dist/capabilities/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/capabilities/discover.ts"],"names":[],"mappings":"AAiDA,sGAAsG;AACtG,MAAM,WAAW,UAAU;IACzB,4FAA4F;IAC5F,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAIrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAOpH;AA+HD,wBAAgB,+BAA+B,IAAI,IAAI,CAYtD"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/capabilities/discover.ts"],"names":[],"mappings":"AAiDA,sGAAsG;AACtG,MAAM,WAAW,UAAU;IACzB,4FAA4F;IAC5F,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAIrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAOpH;AAmCD,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,QAAO,MAAM,EAAiC,CAAC;AA0B9E,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEtE;AA2ED,wBAAgB,+BAA+B,IAAI,IAAI,CAYtD"}

package/dist/capabilities/discover.js

@@ -33,8 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundledDriverNames = void 0;
 exports.sameVersionLine = sameVersionLine;
 exports.pickDriverCopy = pickDriverCopy;
+exports.resolveDriverCopy = resolveDriverCopy;
 exports.discoverAndRegisterCapabilities = discoverAndRegisterCapabilities;
 /**
  * Capability discovery (R5 packaging seam).
@@ -151,8 +153,11 @@ function versionSkewWarning(name, loaded, core, bypassed) {
         `and a driver on another version line misses metadata core requires (for the UI driver: every "is hidden"/"is disabled" ` +
         `clause fails SG-E021 on the pattern that should assert it).\n` + fix);
 }
-function loadExternalDriver(name) {
-    const bundled = BUNDLED_DRIVERS.has(name);
+/** The bundled drivers, by package name (sorted). */
+const bundledDriverNames = () => [...BUNDLED_DRIVERS].sort();
+exports.bundledDriverNames = bundledDriverNames;
+/** Every installed copy of a driver, from the project and from core, with the requires that found them. */
+function driverCopies(name) {
     // 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
@@ -183,6 +188,15 @@ function loadExternalDriver(name) {
         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. */
+function resolveDriverCopy(name) {
+    return pickDriverCopy(driverCopies(name).copies, (0, lockstep_version_1.coreVersion)(), BUNDLED_DRIVERS.has(name));
+}
+function loadExternalDriver(name) {
+    const bundled = BUNDLED_DRIVERS.has(name);
+    const { copies, requires } = driverCopies(name);
     const core = (0, lockstep_version_1.coreVersion)();
     const chosen = pickDriverCopy(copies, core, bundled);
     if (chosen) {