mdkg 0.1.10 → 0.3.0

package/dist/core/project_db_migrations.js

@@ -53,6 +53,24 @@ ON project_queue_message(queue_name, status, available_at_ms, created_at_ms, mes
 CREATE INDEX IF NOT EXISTS project_queue_message_lease_idx
 ON project_queue_message(queue_name, status, lease_deadline_ms, created_at_ms, message_id);
 `;
+const QUEUE_CONTROL_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS project_queue (
+  queue_name TEXT PRIMARY KEY,
+  status TEXT NOT NULL CHECK(status IN ('active', 'paused')),
+  paused_reason TEXT,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+) STRICT;
+
+INSERT OR IGNORE INTO project_queue (queue_name, status, paused_reason, created_at_ms, updated_at_ms)
+SELECT DISTINCT
+  queue_name,
+  'active',
+  NULL,
+  CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER),
+  CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)
+FROM project_queue_message;
+`;
 const EVENTS_RECEIPTS_MIGRATION_SQL = `
 CREATE TABLE IF NOT EXISTS project_event (
   event_id TEXT PRIMARY KEY,
@@ -162,6 +180,12 @@ const BUILTIN_MIGRATIONS = [
         filename: "004_mdkg_project_db_writer_leases.sql",
         sql: WRITER_LEASES_MIGRATION_SQL.trim(),
     },
+    {
+        ordinal: 5,
+        key: "mdkg.project_db.queue_control.v1",
+        filename: "005_mdkg_project_db_queue_control.sql",
+        sql: QUEUE_CONTROL_MIGRATION_SQL.trim(),
+    },
 ];
 function loadDatabaseCtor() {
     try {

package/dist/core/project_db_queue.js

@@ -10,6 +10,14 @@ exports.failProjectQueueMessage = failProjectQueueMessage;
 exports.deadLetterProjectQueueMessage = deadLetterProjectQueueMessage;
 exports.releaseExpiredProjectQueueLeases = releaseExpiredProjectQueueLeases;
 exports.readProjectQueueStats = readProjectQueueStats;
+exports.createProjectQueue = createProjectQueue;
+exports.pauseProjectQueue = pauseProjectQueue;
+exports.resumeProjectQueue = resumeProjectQueue;
+exports.readProjectQueue = readProjectQueue;
+exports.listProjectQueues = listProjectQueues;
+exports.readProjectQueueMessage = readProjectQueueMessage;
+exports.listProjectQueueMessages = listProjectQueueMessages;
+exports.readProjectQueueSnapshotSummary = readProjectQueueSnapshotSummary;
 const crypto_1 = __importDefault(require("crypto"));
 function loadDatabaseCtor() {
     try {
@@ -91,12 +99,44 @@ function toMessage(row) {
         last_error: row.last_error === null || row.last_error === undefined ? null : String(row.last_error),
     };
 }
+function toQueue(row) {
+    return {
+        queue_name: String(row.queue_name),
+        status: String(row.status),
+        paused_reason: row.paused_reason === null || row.paused_reason === undefined ? null : String(row.paused_reason),
+        created_at_ms: Number(row.created_at_ms),
+        updated_at_ms: Number(row.updated_at_ms),
+    };
+}
 function getMessage(db, queueName, messageId) {
     const row = db
         .prepare("SELECT * FROM project_queue_message WHERE queue_name = ? AND message_id = ?")
         .get(queueName, messageId);
     return row ? toMessage(row) : null;
 }
+function getQueue(db, queueName) {
+    const row = db.prepare("SELECT * FROM project_queue WHERE queue_name = ?").get(queueName);
+    return row ? toQueue(row) : null;
+}
+function ensureQueue(db, queueName, currentNow) {
+    const existing = getQueue(db, queueName);
+    if (existing) {
+        return existing;
+    }
+    db
+        .prepare("INSERT INTO project_queue (queue_name, status, paused_reason, created_at_ms, updated_at_ms) VALUES (?, 'active', NULL, ?, ?)")
+        .run(queueName, currentNow, currentNow);
+    const queue = getQueue(db, queueName);
+    if (!queue) {
+        throw new Error(`queue could not be loaded after create: ${queueName}`);
+    }
+    return queue;
+}
+function requireQueueActive(queue, action) {
+    if (queue.status === "paused") {
+        throw new Error(`queue ${queue.queue_name} is paused; cannot ${action}`);
+    }
+}
 function withDb(databasePath, fn) {
     const DatabaseSync = loadDatabaseCtor();
     const db = new DatabaseSync(databasePath);
@@ -139,6 +179,7 @@ function enqueueProjectQueueMessage(databasePath, input) {
     const payloadJson = stableJson(input.payload);
     const hash = payloadHash(payloadJson);
     return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        requireQueueActive(ensureQueue(db, input.queue_name, currentNow), "enqueue");
         if (input.dedupe_key) {
             const duplicate = db
                 .prepare("SELECT * FROM project_queue_message WHERE queue_name = ? AND dedupe_key = ?")
@@ -167,6 +208,7 @@ function claimProjectQueueMessage(databasePath, input) {
     assertPositiveInteger(input.lease_ms, "lease_ms");
     const currentNow = nowMs(input.now_ms);
     return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        requireQueueActive(ensureQueue(db, input.queue_name, currentNow), "claim");
         const row = db
             .prepare([
             "SELECT * FROM project_queue_message",
@@ -315,3 +357,147 @@ function readProjectQueueStats(databasePath, input = {}) {
         };
     });
 }
+function createProjectQueue(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    const currentNow = nowMs(input.now_ms);
+    if (input.reason !== undefined && input.reason !== null) {
+        assertNonEmpty(input.reason, "reason");
+    }
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        const existing = getQueue(db, input.queue_name);
+        if (existing) {
+            return { created: false, queue: existing };
+        }
+        const status = input.paused ? "paused" : "active";
+        db
+            .prepare("INSERT INTO project_queue (queue_name, status, paused_reason, created_at_ms, updated_at_ms) VALUES (?, ?, ?, ?, ?)")
+            .run(input.queue_name, status, input.paused ? input.reason ?? null : null, currentNow, currentNow);
+        const queue = getQueue(db, input.queue_name);
+        if (!queue) {
+            throw new Error(`queue could not be loaded after create: ${input.queue_name}`);
+        }
+        return { created: true, queue };
+    }));
+}
+function pauseProjectQueue(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    if (input.reason !== undefined && input.reason !== null) {
+        assertNonEmpty(input.reason, "reason");
+    }
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        ensureQueue(db, input.queue_name, currentNow);
+        db
+            .prepare("UPDATE project_queue SET status = 'paused', paused_reason = ?, updated_at_ms = ? WHERE queue_name = ?")
+            .run(input.reason ?? null, currentNow, input.queue_name);
+        const queue = getQueue(db, input.queue_name);
+        if (!queue) {
+            throw new Error(`queue could not be loaded after pause: ${input.queue_name}`);
+        }
+        return queue;
+    }));
+}
+function resumeProjectQueue(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    const currentNow = nowMs(input.now_ms);
+    return withDb(databasePath, (db) => withImmediateTransaction(db, () => {
+        ensureQueue(db, input.queue_name, currentNow);
+        db
+            .prepare("UPDATE project_queue SET status = 'active', paused_reason = NULL, updated_at_ms = ? WHERE queue_name = ?")
+            .run(currentNow, input.queue_name);
+        const queue = getQueue(db, input.queue_name);
+        if (!queue) {
+            throw new Error(`queue could not be loaded after resume: ${input.queue_name}`);
+        }
+        return queue;
+    }));
+}
+function readProjectQueue(databasePath, queueName) {
+    assertNonEmpty(queueName, "queue_name");
+    return withDb(databasePath, (db) => getQueue(db, queueName));
+}
+function listProjectQueues(databasePath) {
+    return withDb(databasePath, (db) => db.prepare("SELECT * FROM project_queue ORDER BY queue_name ASC").all().map(toQueue));
+}
+function readProjectQueueMessage(databasePath, queueName, messageId) {
+    assertNonEmpty(queueName, "queue_name");
+    assertNonEmpty(messageId, "message_id");
+    return withDb(databasePath, (db) => getMessage(db, queueName, messageId));
+}
+function listProjectQueueMessages(databasePath, input) {
+    assertNonEmpty(input.queue_name, "queue_name");
+    const limit = input.limit ?? 50;
+    assertPositiveInteger(limit, "limit");
+    if (input.status && input.status !== "all" && !["ready", "leased", "acked", "dead_letter"].includes(input.status)) {
+        throw new Error("status must be ready, leased, acked, dead_letter, or all");
+    }
+    return withDb(databasePath, (db) => {
+        const sql = input.status && input.status !== "all"
+            ? [
+                "SELECT * FROM project_queue_message",
+                "WHERE queue_name = ? AND status = ?",
+                "ORDER BY available_at_ms ASC, created_at_ms ASC, message_id ASC",
+                "LIMIT ?",
+            ].join(" ")
+            : [
+                "SELECT * FROM project_queue_message",
+                "WHERE queue_name = ?",
+                "ORDER BY available_at_ms ASC, created_at_ms ASC, message_id ASC",
+                "LIMIT ?",
+            ].join(" ");
+        const params = input.status && input.status !== "all" ? [input.queue_name, input.status, limit] : [input.queue_name, limit];
+        return db.prepare(sql).all(...params).map(toMessage);
+    });
+}
+function readProjectQueueSnapshotSummary(databasePath) {
+    return withDb(databasePath, (db) => {
+        const rows = db
+            .prepare([
+            "SELECT q.queue_name, q.status, q.paused_reason,",
+            "COUNT(m.message_id) AS total,",
+            "SUM(CASE WHEN m.status = 'ready' THEN 1 ELSE 0 END) AS ready,",
+            "SUM(CASE WHEN m.status = 'leased' THEN 1 ELSE 0 END) AS leased,",
+            "SUM(CASE WHEN m.status = 'acked' THEN 1 ELSE 0 END) AS acked,",
+            "SUM(CASE WHEN m.status = 'dead_letter' THEN 1 ELSE 0 END) AS dead_letter",
+            "FROM project_queue q",
+            "LEFT JOIN project_queue_message m ON m.queue_name = q.queue_name",
+            "GROUP BY q.queue_name, q.status, q.paused_reason",
+            "ORDER BY q.queue_name ASC",
+        ].join(" "))
+            .all();
+        const queues = rows.map((row) => ({
+            queue_name: String(row.queue_name),
+            status: String(row.status),
+            paused_reason: row.paused_reason === null || row.paused_reason === undefined ? null : String(row.paused_reason),
+            total: Number(row.total ?? 0),
+            ready: Number(row.ready ?? 0),
+            leased: Number(row.leased ?? 0),
+            acked: Number(row.acked ?? 0),
+            dead_letter: Number(row.dead_letter ?? 0),
+        }));
+        const summary = {
+            queues,
+            total: 0,
+            ready: 0,
+            leased: 0,
+            acked: 0,
+            dead_letter: 0,
+            paused_ready: 0,
+            active_ready: 0,
+        };
+        for (const queue of queues) {
+            summary.total += queue.total;
+            summary.ready += queue.ready;
+            summary.leased += queue.leased;
+            summary.acked += queue.acked;
+            summary.dead_letter += queue.dead_letter;
+            if (queue.status === "paused") {
+                summary.paused_ready += queue.ready;
+            }
+            else {
+                summary.active_ready += queue.ready;
+            }
+        }
+        return summary;
+    });
+}

package/dist/core/project_db_snapshot.js

@@ -18,6 +18,7 @@ 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");
+const project_db_queue_1 = require("./project_db_queue");
 function loadDatabaseCtor() {
     try {
         const loaded = require("node:sqlite");
@@ -170,7 +171,7 @@ function readManifest(filePath) {
     }
     return manifest;
 }
-function buildManifest(root, config, snapshotFile, runtimeHash) {
+function buildManifest(root, config, snapshotFile, runtimeHash, queuePolicy, queueSummary) {
     const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(root, config.db);
     const metadata = collectSnapshotMetadata(snapshotFile, config.db.migration_table);
     return {
@@ -188,17 +189,39 @@ function buildManifest(root, config, snapshotFile, runtimeHash) {
         byte_size: fs_1.default.statSync(snapshotFile).size,
         table_counts: metadata.table_counts,
         migrations: metadata.migrations,
+        queue_policy: queuePolicy,
+        queue_summary: queueSummary,
     };
 }
+function assertQueueSnapshotPolicy(policy, summary) {
+    if (policy === "drain") {
+        if (summary.ready > 0 || summary.leased > 0) {
+            throw new errors_1.ValidationError(`db snapshot seal requires drained queues; found ready=${summary.ready}, leased=${summary.leased}`);
+        }
+        return;
+    }
+    if (policy === "paused") {
+        if (summary.leased > 0) {
+            throw new errors_1.ValidationError(`db snapshot seal --queue-policy paused requires no leased messages; found leased=${summary.leased}`);
+        }
+        if (summary.active_ready > 0) {
+            throw new errors_1.ValidationError(`db snapshot seal --queue-policy paused requires ready messages to be in paused queues; found active_ready=${summary.active_ready}`);
+        }
+        return;
+    }
+    throw new errors_1.ValidationError(`unsupported queue snapshot policy: ${policy}`);
+}
 function warningListFromVerify(root, config) {
     return (0, project_db_migrations_1.verifyProjectDb)(root, config).warnings;
 }
-function sealProjectDbSnapshot(root, config) {
+function sealProjectDbSnapshot(root, config, queuePolicy = "drain") {
     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 queueSummary = (0, project_db_queue_1.readProjectQueueSnapshotSummary)(layout.runtimeFile);
+    assertQueueSnapshotPolicy(queuePolicy, queueSummary);
     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`);
@@ -228,7 +251,7 @@ function sealProjectDbSnapshot(root, config) {
     }
     try {
         const runtimeHash = sha256File(layout.runtimeFile);
-        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash);
+        const manifest = buildManifest(root, config, tempSnapshot, runtimeHash, queuePolicy, queueSummary);
         (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);
@@ -243,6 +266,8 @@ function sealProjectDbSnapshot(root, config) {
             byte_size: manifest.byte_size,
             table_counts: manifest.table_counts,
             migrations: manifest.migrations,
+            queue_policy: queuePolicy,
+            queue_summary: queueSummary,
             warnings: warningListFromVerify(root, config),
         };
     }

package/dist/graph/agent_file_types.js

@@ -32,6 +32,7 @@ exports.AGENT_FILE_BASENAMES = {
 exports.AGENT_ATTRIBUTE_KEY_ORDER = {
     spec: [
         "version",
+        "spec_kind",
         "role",
         "runtime_mode",
         "work_contracts",
@@ -68,7 +69,10 @@ exports.AGENT_ATTRIBUTE_KEY_ORDER = {
         "requester",
         "order_status",
         "request_ref",
+        "trigger_ref",
+        "payload_hash",
         "input_refs",
+        "queue_refs",
         "requested_outputs",
         "constraint_refs",
         "artifact_policy",
@@ -79,8 +83,10 @@ exports.AGENT_ATTRIBUTE_KEY_ORDER = {
         "receipt_status",
         "outcome",
         "cost_ref",
+        "redaction_policy",
         "proof_refs",
         "attestation_refs",
+        "evidence_hashes",
         "input_hashes",
         "output_hashes",
     ],
@@ -128,6 +134,27 @@ const UPDATE_POLICY_VALUES = new Set([
     "automatic",
     "disabled",
 ]);
+const SPEC_KIND_VALUES = new Set([
+    "cli_tool",
+    "api",
+    "agent",
+    "runtime_agent",
+    "capability",
+    "tool",
+    "model",
+    "runtime_image",
+    "integration",
+    "project_service",
+]);
+const DOCUMENTATION_ONLY_SPEC_KIND_ROUTES = {
+    gap_register: "use an EDD, task, checkpoint, or goal for gap registers",
+    checkpoint: "use a checkpoint node for checkpoint evidence",
+    roadmap: "use an epic, goal, EDD, or PRD for roadmaps",
+    audit: "use a task, checkpoint, or EDD for audits",
+    go_no_go: "use a DEC, task, or checkpoint for go/no-go notes",
+    planning_note: "use an EDD, task, or checkpoint for planning notes",
+    launch_checklist: "use a task, test, checkpoint, or DEC for launch checklists",
+};
 const PRICING_MODEL_VALUES = new Set([
     "free",
     "included",
@@ -146,6 +173,11 @@ const ORDER_STATUS_VALUES = new Set([
 ]);
 const RECEIPT_STATUS_VALUES = new Set(["recorded", "verified", "rejected", "superseded"]);
 const OUTCOME_VALUES = new Set(["success", "partial", "failure"]);
+const REDACTION_POLICY_VALUES = new Set([
+    "refs_and_hashes_only",
+    "redacted_summary",
+    "external_private",
+]);
 const ARTIFACT_POLICY_VALUES = new Set([
     "commit_sidecar_and_zip",
     "external_only",
@@ -265,6 +297,16 @@ function requireEnum(value, key, allowed, filePath) {
         throw formatError(filePath, `${key} must be one of ${Array.from(allowed).join(", ")}`);
     }
 }
+function validateSpecKind(value, filePath) {
+    if (SPEC_KIND_VALUES.has(value)) {
+        return;
+    }
+    const route = DOCUMENTATION_ONLY_SPEC_KIND_ROUTES[value];
+    if (route) {
+        throw formatError(filePath, `spec_kind ${value} is documentation-only; ${route}. SPEC.md must define a reusable invocable capability surface.`);
+    }
+    throw formatError(filePath, `spec_kind must be one of ${Array.from(SPEC_KIND_VALUES).join(", ")}; documentation-only records belong in normal mdkg nodes such as task, test, epic, goal, checkpoint, EDD, PRD, DEC, bug, feedback, dispute, or proposal.`);
+}
 function requireLowerToken(value, key, filePath) {
     if (!LOWER_TOKEN_RE.test(value)) {
         throw formatError(filePath, `${key} must be lowercase snake/kebab style`);
@@ -290,6 +332,14 @@ function validatePortableRefs(values, key, filePath) {
         }
     }
 }
+function validateWorkInvocationAnchor(requiredCapabilities, refsByKey, filePath) {
+    const hasRequiredCapability = requiredCapabilities.length > 0;
+    const hasDependencyRef = Object.values(refsByKey).some((values) => values.length > 0);
+    if (hasRequiredCapability || hasDependencyRef) {
+        return;
+    }
+    throw formatError(filePath, "WORK.md must include at least one required_capabilities entry or dependency ref in skill_refs, tool_refs, model_refs, wasm_component_refs, runtime_image_refs, or subagent_refs");
+}
 function validatePortableOrUriRefs(values, key, filePath) {
     for (const [index, value] of values.entries()) {
         if (!(0, refs_1.validatePortableOrUriRef)(value)) {
@@ -315,6 +365,11 @@ function validateHashRefs(values, key, filePath) {
         }
     }
 }
+function validateHashRef(value, key, filePath) {
+    if (!(0, refs_1.isSha256Ref)(value)) {
+        throw formatError(filePath, `${key} must be sha256:<64 lowercase hex chars>`);
+    }
+}
 function validateRelativeMarkdownPaths(values, key, basename, filePath) {
     for (const [index, value] of values.entries()) {
         if (path_1.default.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
@@ -344,6 +399,10 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
     requireSemver(version, "version", filePath);
     switch (type) {
         case "spec": {
+            const specKind = optionalString(frontmatter, "spec_kind", filePath);
+            if (specKind) {
+                validateSpecKind(specKind, filePath);
+            }
             const role = expectString(frontmatter, "role", filePath);
             requireEnum(role, "role", ROLE_VALUES, filePath);
             const runtimeMode = expectString(frontmatter, "runtime_mode", filePath);
@@ -371,13 +430,28 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             requireLowerToken(kind, "kind", filePath);
             const pricingModel = expectString(frontmatter, "pricing_model", filePath);
             requireEnum(pricingModel, "pricing_model", PRICING_MODEL_VALUES, filePath);
-            validateCapabilities(expectList(frontmatter, "required_capabilities", filePath), "required_capabilities", filePath);
-            validatePortableRefs(optionalList(frontmatter, "skill_refs", filePath), "skill_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "tool_refs", filePath), "tool_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "model_refs", filePath), "model_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "wasm_component_refs", filePath), "wasm_component_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "runtime_image_refs", filePath), "runtime_image_refs", filePath);
-            validatePortableRefs(optionalList(frontmatter, "subagent_refs", filePath), "subagent_refs", filePath);
+            const requiredCapabilities = expectList(frontmatter, "required_capabilities", filePath);
+            validateCapabilities(requiredCapabilities, "required_capabilities", filePath);
+            const skillRefs = optionalList(frontmatter, "skill_refs", filePath);
+            validatePortableRefs(skillRefs, "skill_refs", filePath);
+            const toolRefs = optionalList(frontmatter, "tool_refs", filePath);
+            validatePortableRefs(toolRefs, "tool_refs", filePath);
+            const modelRefs = optionalList(frontmatter, "model_refs", filePath);
+            validatePortableRefs(modelRefs, "model_refs", filePath);
+            const wasmComponentRefs = optionalList(frontmatter, "wasm_component_refs", filePath);
+            validatePortableRefs(wasmComponentRefs, "wasm_component_refs", filePath);
+            const runtimeImageRefs = optionalList(frontmatter, "runtime_image_refs", filePath);
+            validatePortableRefs(runtimeImageRefs, "runtime_image_refs", filePath);
+            const subagentRefs = optionalList(frontmatter, "subagent_refs", filePath);
+            validatePortableRefs(subagentRefs, "subagent_refs", filePath);
+            validateWorkInvocationAnchor(requiredCapabilities, {
+                skill_refs: skillRefs,
+                tool_refs: toolRefs,
+                model_refs: modelRefs,
+                wasm_component_refs: wasmComponentRefs,
+                runtime_image_refs: runtimeImageRefs,
+                subagent_refs: subagentRefs,
+            }, filePath);
             validateFieldDescriptors(expectList(frontmatter, "inputs", filePath), "inputs", filePath);
             validateFieldDescriptors(expectList(frontmatter, "outputs", filePath), "outputs", filePath);
             expectBoolean(frontmatter, "receipt_required", filePath);
@@ -396,7 +470,16 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             if (requestRef) {
                 validatePortableOrUriScalar(requestRef, "request_ref", filePath);
             }
+            const triggerRef = optionalRefString(frontmatter, "trigger_ref", filePath);
+            if (triggerRef) {
+                validatePortableOrUriScalar(triggerRef, "trigger_ref", filePath);
+            }
+            const payloadHash = optionalString(frontmatter, "payload_hash", filePath);
+            if (payloadHash) {
+                validateHashRef(payloadHash, "payload_hash", filePath);
+            }
             validatePortableOrUriRefs(optionalList(frontmatter, "input_refs", filePath), "input_refs", filePath);
+            validatePortableOrUriRefs(optionalList(frontmatter, "queue_refs", filePath), "queue_refs", filePath);
             validateOptionalFieldDescriptors(optionalList(frontmatter, "requested_outputs", filePath), "requested_outputs", filePath);
             validatePortableOrUriRefs(optionalList(frontmatter, "constraint_refs", filePath), "constraint_refs", filePath);
             const artifactPolicy = optionalString(frontmatter, "artifact_policy", filePath);
@@ -416,8 +499,13 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
             if (costRef) {
                 validatePortableOrUriScalar(costRef, "cost_ref", filePath);
             }
+            const redactionPolicy = optionalString(frontmatter, "redaction_policy", filePath);
+            if (redactionPolicy) {
+                requireEnum(redactionPolicy, "redaction_policy", REDACTION_POLICY_VALUES, filePath);
+            }
             validatePortableOrUriRefs(optionalList(frontmatter, "proof_refs", filePath), "proof_refs", filePath);
             validatePortableOrUriRefs(optionalList(frontmatter, "attestation_refs", filePath), "attestation_refs", filePath);
+            validateHashRefs(optionalList(frontmatter, "evidence_hashes", filePath), "evidence_hashes", filePath);
             validateHashRefs(optionalList(frontmatter, "input_hashes", filePath), "input_hashes", filePath);
             validateHashRefs(optionalList(frontmatter, "output_hashes", filePath), "output_hashes", filePath);
             break;

package/dist/graph/capabilities_indexer.js

@@ -74,7 +74,92 @@ function pickAttributes(attributes, keys) {
     }
     return picked;
 }
-function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
+function toStringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function nodeRefSet(node) {
+    return new Set([node.id, node.qid, `${node.ws}:${node.id}`]);
+}
+function sortedNodes(nodes) {
+    return [...nodes].sort((a, b) => a.qid.localeCompare(b.qid));
+}
+function resolveSpecWorkContracts(index, specNode) {
+    const candidates = new Map();
+    const specDir = path_1.default.posix.dirname(specNode.path);
+    for (const contractPath of toStringList(specNode.attributes.work_contracts)) {
+        const normalizedPath = path_1.default.posix.normalize(path_1.default.posix.join(specDir, contractPath));
+        for (const node of Object.values(index.nodes)) {
+            if (node.type === "work" && node.ws === specNode.ws && node.path === normalizedPath) {
+                candidates.set(node.qid, node);
+            }
+        }
+    }
+    for (const qid of specNode.edges.relates) {
+        const node = index.nodes[qid];
+        if (node?.type === "work") {
+            candidates.set(node.qid, node);
+        }
+    }
+    for (const qid of index.reverse_edges.relates?.[specNode.qid] ?? []) {
+        const node = index.nodes[qid];
+        if (node?.type === "work") {
+            candidates.set(node.qid, node);
+        }
+    }
+    return sortedNodes(candidates.values());
+}
+function resolveWorkSpecs(index, workNode) {
+    const candidates = new Map();
+    const workRefs = nodeRefSet(workNode);
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "spec" || node.ws !== workNode.ws) {
+            continue;
+        }
+        const agentId = typeof workNode.attributes.agent_id === "string" ? workNode.attributes.agent_id : undefined;
+        if (agentId && nodeRefSet(node).has(agentId)) {
+            candidates.set(node.qid, node);
+        }
+        if (resolveSpecWorkContracts(index, node).some((contract) => contract.qid === workNode.qid)) {
+            candidates.set(node.qid, node);
+        }
+        if (node.edges.relates.some((qid) => workRefs.has(qid))) {
+            candidates.set(node.qid, node);
+        }
+    }
+    return sortedNodes(candidates.values());
+}
+function resolveWorkOrders(index, workNode) {
+    const workRefs = nodeRefSet(workNode);
+    return sortedNodes(Object.values(index.nodes).filter((node) => node.type === "work_order" && workRefs.has(String(node.attributes.work_id ?? ""))));
+}
+function resolveReceiptsForOrders(index, orderNodes) {
+    const orderRefs = new Set();
+    for (const order of orderNodes) {
+        for (const ref of nodeRefSet(order)) {
+            orderRefs.add(ref);
+        }
+    }
+    return sortedNodes(Object.values(index.nodes).filter((node) => node.type === "receipt" && orderRefs.has(String(node.attributes.work_order_id ?? ""))));
+}
+function buildCapabilityLinkage(index, node, kind) {
+    if (kind !== "spec" && kind !== "work") {
+        return undefined;
+    }
+    const workContracts = kind === "spec" ? resolveSpecWorkContracts(index, node) : [node];
+    const specNodes = kind === "work" ? resolveWorkSpecs(index, node) : [];
+    const workOrders = workContracts.flatMap((workNode) => resolveWorkOrders(index, workNode));
+    const receipts = resolveReceiptsForOrders(index, workOrders);
+    return {
+        spec_qids: specNodes.map((specNode) => specNode.qid),
+        work_contract_qids: workContracts.map((workNode) => workNode.qid),
+        work_order_qids: workOrders.map((orderNode) => orderNode.qid),
+        receipt_qids: receipts.map((receiptNode) => receiptNode.qid),
+    };
+}
+function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
     const absolutePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(absolutePath, "utf8");
     const record = {
@@ -99,6 +184,7 @@ function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
     if (kind === "spec") {
         record.spec = pickAttributes(node.attributes, [
             "version",
+            "spec_kind",
             "role",
             "runtime_mode",
             "work_contracts",
@@ -131,6 +217,7 @@ function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
             "receipt_required",
         ]);
     }
+    record.linkage = buildCapabilityLinkage(index, node, kind);
     return record;
 }
 function skillCapabilityRecord(root, config, skill, indexedAt) {
@@ -210,7 +297,7 @@ function buildCapabilitiesIndex(root, config, nodeIndex) {
         if (!kind) {
             continue;
         }
-        records.push(nodeCapabilityRecord(root, config, node, kind, generatedAt));
+        records.push(nodeCapabilityRecord(root, config, index, node, kind, generatedAt));
     }
     records.push(...buildWorkspaceSkillCapabilities(root, config, generatedAt));
     const sortedRecords = sortRecords(records);

package/dist/graph/frontmatter.js

@@ -24,6 +24,7 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "next",
     "supersedes",
     "version",
+    "spec_kind",
     "role",
     "runtime_mode",
     "work_contracts",
@@ -42,10 +43,14 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "requester",
     "order_status",
     "request_ref",
+    "trigger_ref",
+    "payload_hash",
+    "queue_refs",
     "work_order_id",
     "receipt_status",
     "outcome",
     "cost_ref",
+    "redaction_policy",
     "target_id",
     "sentiment",
     "feedback_status",
@@ -73,6 +78,7 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "artifact_policy",
     "proof_refs",
     "attestation_refs",
+    "evidence_hashes",
     "input_hashes",
     "output_hashes",
     "tags",