mdkg 0.1.5 → 0.1.7

package/dist/core/project_db_snapshot.js

@@ -0,0 +1,510 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveContainedProjectDbPath = resolveContainedProjectDbPath;
+exports.sealProjectDbSnapshot = sealProjectDbSnapshot;
+exports.verifyProjectDbSnapshot = verifyProjectDbSnapshot;
+exports.projectDbSnapshotStatus = projectDbSnapshotStatus;
+exports.canonicalDumpForSnapshot = canonicalDumpForSnapshot;
+exports.dumpProjectDbSnapshot = dumpProjectDbSnapshot;
+exports.diffProjectDbSnapshots = diffProjectDbSnapshots;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_db_1 = require("./project_db");
+const version_1 = require("./version");
+const atomic_1 = require("../util/atomic");
+const errors_1 = require("../util/errors");
+const project_db_migrations_1 = require("./project_db_migrations");
+function loadDatabaseCtor() {
+    try {
+        const loaded = require("node:sqlite");
+        if (!loaded.DatabaseSync) {
+            throw new Error("node:sqlite DatabaseSync is unavailable");
+        }
+        return loaded.DatabaseSync;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`node:sqlite is required for mdkg project DB snapshots: ${message}`);
+    }
+}
+function toPosix(relativePath) {
+    return relativePath.split(path_1.default.sep).join("/");
+}
+function rel(root, filePath) {
+    return toPosix(path_1.default.relative(root, filePath));
+}
+function isInside(root, filePath) {
+    const relative = path_1.default.relative(root, filePath);
+    return relative === "" || (!relative.startsWith("..") && !path_1.default.isAbsolute(relative));
+}
+function resolveContainedProjectDbPath(root, rawPath, label) {
+    if (rawPath.trim().length === 0) {
+        throw new errors_1.UsageError(`${label} requires a non-empty path`);
+    }
+    const resolved = path_1.default.resolve(root, rawPath);
+    if (!isInside(root, resolved)) {
+        throw new errors_1.UsageError(`${label} must be inside the repo`);
+    }
+    return resolved;
+}
+function sha256Buffer(data) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(data).digest("hex")}`;
+}
+function sha256File(filePath) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(fs_1.default.readFileSync(filePath)).digest("hex")}`;
+}
+function quoteIdentifier(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function quoteSqlString(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function tableNames(db) {
+    return db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name ASC")
+        .all()
+        .map((row) => String(row.name));
+}
+function tableCounts(db) {
+    return tableNames(db).map((name) => {
+        const row = db.prepare(`SELECT COUNT(*) AS count FROM ${quoteIdentifier(name)}`).get();
+        return { name, row_count: Number(row?.count ?? 0) };
+    });
+}
+function readMigrations(db, tableName) {
+    const exists = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(tableName);
+    if (!exists) {
+        return [];
+    }
+    return db
+        .prepare(`SELECT migration_key, ordinal, checksum, applied_at_ms FROM ${quoteIdentifier(tableName)} ORDER BY ordinal ASC`)
+        .all()
+        .map((row) => ({
+        migration_key: String(row.migration_key),
+        ordinal: Number(row.ordinal),
+        checksum: String(row.checksum),
+        applied_at_ms: Number(row.applied_at_ms),
+    }));
+}
+function assertSqliteIntegrity(db, label) {
+    const row = db.prepare("PRAGMA integrity_check").get();
+    const value = String(Object.values(row ?? {})[0] ?? "");
+    if (value !== "ok") {
+        throw new errors_1.ValidationError(`${label} integrity check failed: ${value}`);
+    }
+}
+function sqliteIntegrityCheck(root, filePath) {
+    const DatabaseSync = loadDatabaseCtor();
+    try {
+        const db = new DatabaseSync(filePath);
+        try {
+            assertSqliteIntegrity(db, "snapshot");
+            return {
+                name: "sqlite-integrity",
+                ok: true,
+                level: "ok",
+                path: rel(root, filePath),
+                detail: "snapshot SQLite integrity check ok",
+                errors: [],
+                warnings: [],
+            };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: "sqlite-integrity",
+            ok: false,
+            level: "fail",
+            path: rel(root, filePath),
+            detail: "failed to verify snapshot SQLite integrity",
+            errors: [`snapshot SQLite integrity failed: ${message}`],
+            warnings: [],
+        };
+    }
+}
+function collectSnapshotMetadata(filePath, migrationTable) {
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(filePath);
+    try {
+        assertSqliteIntegrity(db, "snapshot");
+        return {
+            table_counts: tableCounts(db),
+            migrations: readMigrations(db, migrationTable),
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+function readManifest(filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_1.ValidationError(`failed to read snapshot manifest: ${message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new errors_1.ValidationError("snapshot manifest must be a JSON object");
+    }
+    const manifest = parsed;
+    if (manifest.manifest_version !== 1 ||
+        manifest.tool !== "mdkg" ||
+        manifest.kind !== "project_db_snapshot" ||
+        typeof manifest.snapshot_sha256 !== "string" ||
+        typeof manifest.byte_size !== "number" ||
+        !Array.isArray(manifest.table_counts) ||
+        !Array.isArray(manifest.migrations)) {
+        throw new errors_1.ValidationError("snapshot manifest has unsupported shape");
+    }
+    return manifest;
+}
+function buildManifest(root, config, snapshotFile, runtimeHash) {
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const metadata = collectSnapshotMetadata(snapshotFile, config.db.migration_table);
+    return {
+        manifest_version: 1,
+        tool: "mdkg",
+        kind: "project_db_snapshot",
+        mdkg_version: (0, version_1.readPackageVersion)(),
+        generated_at: new Date().toISOString(),
+        schema_version: config.db.schema_version,
+        migration_table: config.db.migration_table,
+        runtime_path: rel(root, layout.runtimeFile),
+        snapshot_path: rel(root, layout.stateFile),
+        source_runtime_sha256: runtimeHash,
+        snapshot_sha256: sha256File(snapshotFile),
+        byte_size: fs_1.default.statSync(snapshotFile).size,
+        table_counts: metadata.table_counts,
+        migrations: metadata.migrations,
+    };
+}
+function warningListFromVerify(root, config) {
+    return (0, project_db_migrations_1.verifyProjectDb)(root, config).warnings;
+}
+function sealProjectDbSnapshot(root, config) {
+    const verification = (0, project_db_migrations_1.verifyProjectDb)(root, config);
+    if (!verification.ok) {
+        throw new errors_1.ValidationError(`db snapshot seal requires a valid project DB; run mdkg db verify`);
+    }
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const oldHash = fs_1.default.existsSync(layout.stateFile) ? sha256File(layout.stateFile) : null;
+    fs_1.default.mkdirSync(layout.stateDir, { recursive: true });
+    const tempSnapshot = path_1.default.join(layout.stateDir, `.project.sqlite.${process.pid}-${Date.now()}.tmp`);
+    const tempManifest = path_1.default.join(layout.stateDir, `.project.manifest.${process.pid}-${Date.now()}.tmp`);
+    fs_1.default.rmSync(tempSnapshot, { force: true });
+    fs_1.default.rmSync(tempManifest, { force: true });
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(layout.runtimeFile);
+    try {
+        db.exec("PRAGMA foreign_keys = ON;");
+        assertSqliteIntegrity(db, "runtime project DB");
+        try {
+            db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+        }
+        catch {
+            // WAL checkpoint can be a no-op or unavailable depending on journal mode.
+        }
+        db.exec(`VACUUM INTO ${quoteSqlString(tempSnapshot)}`);
+    }
+    catch (err) {
+        fs_1.default.rmSync(tempSnapshot, { force: true });
+        const message = err instanceof Error ? err.message : String(err);
+        throw err instanceof errors_1.ValidationError ? err : new errors_1.ValidationError(`db snapshot seal failed: ${message}`);
+    }
+    finally {
+        db.close();
+    }
+    try {
+        const runtimeHash = sha256File(layout.runtimeFile);
+        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash);
+        (0, atomic_1.atomicWriteFile)(tempManifest, `${JSON.stringify(manifest, null, 2)}\n`);
+        fs_1.default.renameSync(tempSnapshot, layout.stateFile);
+        fs_1.default.renameSync(tempManifest, layout.stateManifest);
+        return {
+            action: "db-snapshot-seal",
+            ok: true,
+            snapshot: rel(root, layout.stateFile),
+            manifest: rel(root, layout.stateManifest),
+            old_snapshot_sha256: oldHash,
+            new_snapshot_sha256: manifest.snapshot_sha256,
+            source_runtime_sha256: runtimeHash,
+            byte_size: manifest.byte_size,
+            table_counts: manifest.table_counts,
+            migrations: manifest.migrations,
+            warnings: warningListFromVerify(root, config),
+        };
+    }
+    catch (err) {
+        fs_1.default.rmSync(tempSnapshot, { force: true });
+        fs_1.default.rmSync(tempManifest, { force: true });
+        throw err;
+    }
+}
+function compareJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function verifyProjectDbSnapshot(root, config) {
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const checks = [];
+    const snapshotRel = rel(root, layout.stateFile);
+    const manifestRel = rel(root, layout.stateManifest);
+    checks.push({
+        name: "snapshot-file",
+        ok: fs_1.default.existsSync(layout.stateFile) && !fs_1.default.statSync(layout.stateFile).isDirectory(),
+        level: fs_1.default.existsSync(layout.stateFile) && !fs_1.default.statSync(layout.stateFile).isDirectory() ? "ok" : "fail",
+        path: snapshotRel,
+        detail: fs_1.default.existsSync(layout.stateFile) ? "snapshot file exists" : "snapshot file missing",
+        errors: fs_1.default.existsSync(layout.stateFile) ? [] : [`${snapshotRel} missing; run mdkg db snapshot seal`],
+        warnings: [],
+    });
+    checks.push({
+        name: "manifest-file",
+        ok: fs_1.default.existsSync(layout.stateManifest) && !fs_1.default.statSync(layout.stateManifest).isDirectory(),
+        level: fs_1.default.existsSync(layout.stateManifest) && !fs_1.default.statSync(layout.stateManifest).isDirectory() ? "ok" : "fail",
+        path: manifestRel,
+        detail: fs_1.default.existsSync(layout.stateManifest) ? "snapshot manifest exists" : "snapshot manifest missing",
+        errors: fs_1.default.existsSync(layout.stateManifest) ? [] : [`${manifestRel} missing; run mdkg db snapshot seal`],
+        warnings: [],
+    });
+    let manifest;
+    if (checks.every((check) => check.ok)) {
+        try {
+            manifest = readManifest(layout.stateManifest);
+            checks.push({
+                name: "manifest-shape",
+                ok: true,
+                level: "ok",
+                path: manifestRel,
+                detail: "snapshot manifest shape is supported",
+                errors: [],
+                warnings: [],
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            checks.push({
+                name: "manifest-shape",
+                ok: false,
+                level: "fail",
+                path: manifestRel,
+                detail: "snapshot manifest shape is invalid",
+                errors: [message],
+                warnings: [],
+            });
+        }
+    }
+    if (manifest) {
+        checks.push(sqliteIntegrityCheck(root, layout.stateFile));
+        const actualHash = sha256File(layout.stateFile);
+        const actualSize = fs_1.default.statSync(layout.stateFile).size;
+        checks.push({
+            name: "snapshot-hash",
+            ok: actualHash === manifest.snapshot_sha256,
+            level: actualHash === manifest.snapshot_sha256 ? "ok" : "fail",
+            path: snapshotRel,
+            detail: actualHash === manifest.snapshot_sha256 ? "snapshot hash matches manifest" : "snapshot hash mismatch",
+            errors: actualHash === manifest.snapshot_sha256 ? [] : [`snapshot hash mismatch: manifest ${manifest.snapshot_sha256}, actual ${actualHash}`],
+            warnings: [],
+        });
+        checks.push({
+            name: "snapshot-size",
+            ok: actualSize === manifest.byte_size,
+            level: actualSize === manifest.byte_size ? "ok" : "fail",
+            path: snapshotRel,
+            detail: actualSize === manifest.byte_size ? "snapshot byte size matches manifest" : "snapshot byte size mismatch",
+            errors: actualSize === manifest.byte_size ? [] : [`snapshot byte size mismatch: manifest ${manifest.byte_size}, actual ${actualSize}`],
+            warnings: [],
+        });
+        try {
+            const metadata = collectSnapshotMetadata(layout.stateFile, config.db.migration_table);
+            const tablesMatch = compareJson(metadata.table_counts, manifest.table_counts);
+            checks.push({
+                name: "table-counts",
+                ok: tablesMatch,
+                level: tablesMatch ? "ok" : "fail",
+                detail: tablesMatch ? "table counts match manifest" : "table counts mismatch",
+                errors: tablesMatch ? [] : ["table counts do not match snapshot manifest"],
+                warnings: [],
+            });
+            const migrationsMatch = compareJson(metadata.migrations, manifest.migrations);
+            checks.push({
+                name: "migrations",
+                ok: migrationsMatch,
+                level: migrationsMatch ? "ok" : "fail",
+                detail: migrationsMatch ? "migration metadata matches manifest" : "migration metadata mismatch",
+                errors: migrationsMatch ? [] : ["migration metadata does not match snapshot manifest"],
+                warnings: [],
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            checks.push({
+                name: "snapshot-metadata",
+                ok: false,
+                level: "fail",
+                detail: "failed to read snapshot metadata",
+                errors: [`failed to read snapshot metadata: ${message}`],
+                warnings: [],
+            });
+        }
+        if (manifest.source_runtime_sha256 && fs_1.default.existsSync(layout.runtimeFile)) {
+            const runtimeHash = sha256File(layout.runtimeFile);
+            checks.push({
+                name: "runtime-freshness",
+                ok: true,
+                level: runtimeHash === manifest.source_runtime_sha256 ? "ok" : "warn",
+                path: rel(root, layout.runtimeFile),
+                detail: runtimeHash === manifest.source_runtime_sha256 ? "snapshot matches current runtime hash" : "runtime changed since snapshot seal",
+                errors: [],
+                warnings: runtimeHash === manifest.source_runtime_sha256 ? [] : ["runtime database hash differs from sealed snapshot source hash"],
+            });
+        }
+    }
+    const errors = checks.flatMap((check) => check.errors.map((error) => `${check.name}: ${error}`));
+    const warnings = checks.flatMap((check) => check.warnings.map((warning) => `${check.name}: ${warning}`));
+    const hasMissing = checks.some((check) => !check.ok && /missing/.test(check.detail));
+    const stale = warnings.some((warning) => /runtime database hash differs/.test(warning));
+    return {
+        action: "db-snapshot-verify",
+        ok: errors.length === 0,
+        status: errors.length > 0 ? (hasMissing ? "missing" : "invalid") : stale ? "stale" : "valid",
+        snapshot: snapshotRel,
+        manifest: manifestRel,
+        checks,
+        warning_count: warnings.length,
+        failure_count: errors.length,
+        warnings,
+        errors,
+    };
+}
+function projectDbSnapshotStatus(root, config) {
+    const payload = verifyProjectDbSnapshot(root, config);
+    return {
+        ...payload,
+        action: "db-snapshot-status",
+    };
+}
+function schemaLines(db) {
+    return db
+        .prepare("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY type ASC, name ASC")
+        .all()
+        .map((row) => `schema ${String(row.type)} ${String(row.name)}: ${String(row.sql).replace(/\s+/g, " ").trim()}`);
+}
+function columnNames(db, tableName) {
+    return db
+        .prepare(`PRAGMA table_info(${quoteIdentifier(tableName)})`)
+        .all()
+        .map((row) => String(row.name));
+}
+function canonicalValue(value) {
+    if (value instanceof Uint8Array) {
+        const buffer = Buffer.from(value);
+        return {
+            blob_sha256: sha256Buffer(buffer),
+            byte_size: buffer.length,
+        };
+    }
+    return value;
+}
+function canonicalDumpForSnapshot(root, snapshotPath) {
+    if (!fs_1.default.existsSync(snapshotPath) || fs_1.default.statSync(snapshotPath).isDirectory()) {
+        throw new errors_1.ValidationError(`${rel(root, snapshotPath)} missing or not a file`);
+    }
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(snapshotPath);
+    try {
+        assertSqliteIntegrity(db, "snapshot");
+        const lines = [
+            "# mdkg project db canonical dump v1",
+            `snapshot: ${rel(root, snapshotPath)}`,
+            `snapshot_sha256: ${sha256File(snapshotPath)}`,
+            "",
+            "# Schema",
+            ...schemaLines(db),
+            "",
+            "# Tables",
+        ];
+        for (const table of tableNames(db)) {
+            const columns = columnNames(db, table);
+            lines.push(`table ${table}`);
+            lines.push(`columns ${JSON.stringify(columns)}`);
+            const selectColumns = columns.map((column) => quoteIdentifier(column)).join(", ");
+            const orderBy = columns.map((column) => `${quoteIdentifier(column)} ASC`).join(", ");
+            const rows = db
+                .prepare(`SELECT ${selectColumns} FROM ${quoteIdentifier(table)} ORDER BY ${orderBy}`)
+                .all();
+            for (const row of rows) {
+                const canonicalRow = {};
+                for (const column of columns) {
+                    canonicalRow[column] = canonicalValue(row[column]);
+                }
+                lines.push(`row ${JSON.stringify(canonicalRow)}`);
+            }
+            lines.push("");
+        }
+        return `${lines.join("\n").trimEnd()}\n`;
+    }
+    finally {
+        db.close();
+    }
+}
+function dumpProjectDbSnapshot(root, config, snapshotPath, outputPath) {
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
+    const resolvedSnapshot = snapshotPath
+        ? resolveContainedProjectDbPath(root, snapshotPath, "--snapshot")
+        : layout.stateFile;
+    const dump = canonicalDumpForSnapshot(root, resolvedSnapshot);
+    const dumpHash = sha256Buffer(dump);
+    let output = null;
+    if (outputPath) {
+        const resolvedOutput = resolveContainedProjectDbPath(root, outputPath, "--output");
+        (0, atomic_1.atomicWriteFile)(resolvedOutput, dump);
+        output = rel(root, resolvedOutput);
+    }
+    return {
+        action: "db-snapshot-dump",
+        ok: true,
+        snapshot: rel(root, resolvedSnapshot),
+        output,
+        line_count: dump.trimEnd().length === 0 ? 0 : dump.trimEnd().split("\n").length,
+        sha256: dumpHash,
+        dump,
+    };
+}
+function diffProjectDbSnapshots(root, leftPath, rightPath) {
+    const left = resolveContainedProjectDbPath(root, leftPath, "left snapshot");
+    const right = resolveContainedProjectDbPath(root, rightPath, "right snapshot");
+    const leftDump = canonicalDumpForSnapshot(root, left);
+    const rightDump = canonicalDumpForSnapshot(root, right);
+    const leftLines = leftDump.trimEnd().split("\n");
+    const rightLines = rightDump.trimEnd().split("\n");
+    const leftSet = new Set(leftLines);
+    const rightSet = new Set(rightLines);
+    const added = rightLines.filter((line) => !leftSet.has(line));
+    const removed = leftLines.filter((line) => !rightSet.has(line));
+    return {
+        action: "db-snapshot-diff",
+        ok: true,
+        left: rel(root, left),
+        right: rel(root, right),
+        left_sha256: sha256Buffer(leftDump),
+        right_sha256: sha256Buffer(rightDump),
+        added_count: added.length,
+        removed_count: removed.length,
+        changed_count: added.length + removed.length,
+        added,
+        removed,
+    };
+}

package/dist/graph/agent_file_types.js

@@ -250,6 +250,11 @@ function requirePortableId(value, key, filePath) {
         throw formatError(filePath, `${key} must be a lowercase portable id`);
     }
 }
+function requirePortableIdRef(value, key, filePath) {
+    if (value !== value.toLowerCase() || !(0, id_1.isPortableIdRef)(value)) {
+        throw formatError(filePath, `${key} must be a lowercase portable id or qid`);
+    }
+}
 function requireSemver(value, key, filePath) {
     if (!SEMVER_RE.test(value)) {
         throw formatError(filePath, `${key} must be a semantic version like 1.0.0`);
@@ -280,8 +285,8 @@ function validatePortableRefs(values, key, filePath) {
         if (value !== value.toLowerCase()) {
             throw formatError(filePath, `${key}[${index}] must be lowercase`);
         }
-        if (!(0, id_1.isPortableId)(value)) {
-            throw formatError(filePath, `${key}[${index}] must be a lowercase portable id`);
+        if (!(0, id_1.isPortableIdRef)(value)) {
+            throw formatError(filePath, `${key}[${index}] must be a lowercase portable id or qid`);
         }
     }
 }
@@ -361,7 +366,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
         }
         case "work": {
             const agentId = expectString(frontmatter, "agent_id", filePath);
-            requirePortableId(agentId, "agent_id", filePath);
+            requirePortableIdRef(agentId, "agent_id", filePath);
             const kind = expectString(frontmatter, "kind", filePath);
             requireLowerToken(kind, "kind", filePath);
             const pricingModel = expectString(frontmatter, "pricing_model", filePath);
@@ -380,7 +385,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
         }
         case "work_order": {
             const workId = expectString(frontmatter, "work_id", filePath);
-            requirePortableId(workId, "work_id", filePath);
+            requirePortableIdRef(workId, "work_id", filePath);
             const workVersion = expectString(frontmatter, "work_version", filePath);
             requireSemver(workVersion, "work_version", filePath);
             const requester = expectRefString(frontmatter, "requester", filePath);
@@ -402,7 +407,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
         }
         case "receipt": {
             const workOrderId = expectString(frontmatter, "work_order_id", filePath);
-            requirePortableId(workOrderId, "work_order_id", filePath);
+            requirePortableIdRef(workOrderId, "work_order_id", filePath);
             const receiptStatus = expectString(frontmatter, "receipt_status", filePath);
             requireEnum(receiptStatus, "receipt_status", RECEIPT_STATUS_VALUES, filePath);
             const outcome = expectString(frontmatter, "outcome", filePath);
@@ -419,7 +424,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
         }
         case "feedback": {
             const targetId = expectString(frontmatter, "target_id", filePath);
-            requirePortableId(targetId, "target_id", filePath);
+            requirePortableIdRef(targetId, "target_id", filePath);
             const sentiment = expectString(frontmatter, "sentiment", filePath);
             requireEnum(sentiment, "sentiment", SENTIMENT_VALUES, filePath);
             const feedbackStatus = expectString(frontmatter, "feedback_status", filePath);
@@ -429,9 +434,9 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
         }
         case "dispute": {
             const workOrderId = expectString(frontmatter, "work_order_id", filePath);
-            requirePortableId(workOrderId, "work_order_id", filePath);
+            requirePortableIdRef(workOrderId, "work_order_id", filePath);
             const receiptId = expectString(frontmatter, "receipt_id", filePath);
-            requirePortableId(receiptId, "receipt_id", filePath);
+            requirePortableIdRef(receiptId, "receipt_id", filePath);
             const disputeStatus = expectString(frontmatter, "dispute_status", filePath);
             requireEnum(disputeStatus, "dispute_status", DISPUTE_STATUS_VALUES, filePath);
             const severity = expectString(frontmatter, "severity", filePath);
@@ -440,7 +445,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
         }
         case "proposal": {
             const targetId = expectString(frontmatter, "target_id", filePath);
-            requirePortableId(targetId, "target_id", filePath);
+            requirePortableIdRef(targetId, "target_id", filePath);
             const proposalStatus = expectString(frontmatter, "proposal_status", filePath);
             requireEnum(proposalStatus, "proposal_status", PROPOSAL_STATUS_VALUES, filePath);
             const proposalKind = expectString(frontmatter, "proposal_kind", filePath);

package/dist/graph/node.js

@@ -308,7 +308,7 @@ function parseNode(content, filePath, options) {
     const owners = requireLowercaseList(optionalList(frontmatter, "owners", filePath), "owners", filePath);
     const links = optionalList(frontmatter, "links", filePath);
     const artifacts = optionalList(frontmatter, "artifacts", filePath);
-    const refs = normalizeRefsList(optionalList(frontmatter, "refs", filePath), "refs", filePath, isPortableType);
+    const refs = normalizeRefsList(optionalList(frontmatter, "refs", filePath), "refs", filePath, true);
     const aliases = requireLowercaseList(optionalList(frontmatter, "aliases", filePath), "aliases", filePath);
     const skillsRaw = optionalList(frontmatter, "skills", filePath);
     const skills = normalizeSkillList(skillsRaw, filePath);
@@ -326,7 +326,7 @@ function parseNode(content, filePath, options) {
             throw formatError(filePath, "supersedes must be a dec-# id");
         }
     }
-    const edges = (0, edges_1.extractEdges)(frontmatter, filePath, { allowPortableRefs: isPortableType });
+    const edges = (0, edges_1.extractEdges)(frontmatter, filePath, { allowPortableRefs: true });
     const attributes = {
         ...extractGoalAttributes(type, frontmatter),
         ...(0, agent_file_types_1.extractAgentAttributes)(type, frontmatter),

package/dist/graph/skills_index_cache.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSkillsIndexStale = isSkillsIndexStale;
 exports.writeSkillsIndex = writeSkillsIndex;
 exports.loadSkillsIndex = loadSkillsIndex;
 const fs_1 = __importDefault(require("fs"));

package/dist/graph/sqlite_index.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLITE_SCHEMA_VERSION = void 0;
 exports.isSqliteBackend = isSqliteBackend;
 exports.resolveSqlitePath = resolveSqlitePath;
+exports.sqliteSourceFingerprint = sqliteSourceFingerprint;
+exports.readSqliteIndexMeta = readSqliteIndexMeta;
 exports.writeSqliteIndex = writeSqliteIndex;
 exports.reserveSqliteNumericId = reserveSqliteNumericId;
 exports.sqliteHealth = sqliteHealth;
@@ -153,6 +155,29 @@ function buildSourceFingerprint(options) {
     };
     return `sha256:${crypto_1.default.createHash("sha256").update(stableCacheJson(payload)).digest("hex")}`;
 }
+function sqliteSourceFingerprint(options) {
+    const nodeHashes = new Map();
+    for (const node of Object.values(options.nodeIndex.nodes)) {
+        nodeHashes.set(node.qid, nodeSourceHash(options.root, node.path));
+    }
+    return buildSourceFingerprint({ ...options, nodeHashes });
+}
+function readSqliteIndexMeta(root, config) {
+    const sqlitePath = resolveSqlitePath(root, config);
+    const DatabaseSync = loadDatabaseCtor();
+    const db = new DatabaseSync(sqlitePath);
+    try {
+        const rows = db.prepare("SELECT key, value FROM meta").all();
+        const meta = {};
+        for (const row of rows) {
+            meta[String(row.key)] = String(row.value);
+        }
+        return meta;
+    }
+    finally {
+        db.close();
+    }
+}
 function writeSqliteIndex(options) {
     const sqlitePath = resolveSqlitePath(options.root, options.config);
     fs_1.default.mkdirSync(path_1.default.dirname(sqlitePath), { recursive: true });