kibi-cli 2.0.0 → 2.2.0

package/dist/env/bootstrap.js

@@ -0,0 +1,310 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const WORKSPACE_ENV_KEYS = [
+    "KIBI_WORKSPACE",
+    "KIBI_PROJECT_ROOT",
+    "KIBI_ROOT",
+];
+/** Preferred project-local Kibi env file (harness-independent). */
+// implements REQ-kibi-env-bootstrap
+export const KIBI_PROJECT_ENV_FILE = ".env.kibi";
+/** Legacy generic dotenv still loaded for compatibility only. */
+// implements REQ-kibi-env-bootstrap
+export const KIBI_LEGACY_ENV_FILE = ".env";
+/** Remembered pre-bootstrap non-empty process keys for default `process.env`. */
+let rememberedInitialNonEmptyKeys = null;
+/** Last bootstrap result for default `process.env` (doctor attribution). */
+let lastDefaultBootstrap = null;
+/**
+ * Test-only: clear remembered process-key snapshot and last bootstrap result.
+ */
+// implements REQ-kibi-env-bootstrap
+export function resetKibiEnvironmentBootstrapStateForTests() {
+    rememberedInitialNonEmptyKeys = null;
+    lastDefaultBootstrap = null;
+}
+/**
+ * Last bootstrap against the real `process.env`, if any.
+ */
+// implements REQ-kibi-env-bootstrap
+export function getLastBootstrapResult() {
+    return lastDefaultBootstrap;
+}
+function readFirstEnv(env, keys) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    return null;
+}
+function nextAncestorDirectory(current) {
+    const parent = path.dirname(current);
+    return parent === current ? undefined : parent;
+}
+function findUpwards(startDir, marker) {
+    let current = path.resolve(startDir);
+    while (current !== undefined) {
+        if (fs.existsSync(path.join(current, marker))) {
+            return current;
+        }
+        current = nextAncestorDirectory(current);
+    }
+    return null;
+}
+/**
+ * Canonical workspace root for Kibi env files and KB attachment.
+ * Uses KIBI_WORKSPACE / KIBI_PROJECT_ROOT / KIBI_ROOT, then .kb / .git discovery.
+ */
+// implements REQ-kibi-env-bootstrap
+export function resolveKibiWorkspaceRoot(startDir = process.cwd(), env = process.env) {
+    const envRoot = readFirstEnv(env, WORKSPACE_ENV_KEYS);
+    if (envRoot)
+        return path.resolve(envRoot);
+    const kbRoot = findUpwards(startDir, ".kb");
+    if (kbRoot)
+        return kbRoot;
+    const gitRoot = findUpwards(startDir, ".git");
+    if (gitRoot)
+        return gitRoot;
+    return path.resolve(startDir);
+}
+// implements REQ-kibi-env-bootstrap
+export function resolveEnvFilePath(envFileName, workspaceRoot) {
+    if (path.isAbsolute(envFileName))
+        return envFileName;
+    return path.resolve(workspaceRoot, envFileName);
+}
+/** User-wide Kibi env file: $XDG_CONFIG_HOME/kibi/env or ~/.config/kibi/env. */
+// implements REQ-kibi-env-bootstrap
+export function resolveKibiUserEnvPath(options = {}) {
+    const env = options.env ?? process.env;
+    const xdg = options.xdgConfigHome?.trim() ||
+        env.XDG_CONFIG_HOME?.trim() ||
+        path.join(options.homedir ?? os.homedir(), ".config");
+    return path.join(xdg, "kibi", "env");
+}
+// implements REQ-kibi-env-bootstrap
+export function resolveKibiProjectEnvPath(workspaceRoot, env = process.env) {
+    const override = env.KIBI_ENV_FILE?.trim();
+    if (override)
+        return resolveEnvFilePath(override, workspaceRoot);
+    return resolveEnvFilePath(KIBI_PROJECT_ENV_FILE, workspaceRoot);
+}
+// implements REQ-kibi-env-bootstrap
+export function parseEnvContent(content) {
+    const entries = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eqIndex = line.indexOf("=");
+        if (eqIndex <= 0)
+            continue;
+        const key = line.slice(0, eqIndex).trim();
+        let value = line.slice(eqIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (!key)
+            continue;
+        entries.push({ key, value });
+    }
+    return entries;
+}
+function readEnvFileEntries(filePath) {
+    const map = new Map();
+    if (!fs.existsSync(filePath))
+        return map;
+    try {
+        for (const { key, value } of parseEnvContent(fs.readFileSync(filePath, "utf8"))) {
+            map.set(key, value);
+        }
+    }
+    catch {
+        // Unreadable files are treated as absent for bootstrap/inspect.
+    }
+    return map;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function snapshotNonEmptyKeys(env) {
+    return new Set(Object.keys(env).filter((key) => nonEmpty(env[key])));
+}
+function resolveInitialNonEmptyKeys(env, options, isDefaultEnv) {
+    if (options.initialNonEmptyProcessKeys) {
+        return new Set([...options.initialNonEmptyProcessKeys].filter((key) => nonEmpty(env[key])));
+    }
+    if (isDefaultEnv && rememberedInitialNonEmptyKeys) {
+        // Only keys that remain non-empty stay process-owned across re-entry.
+        return new Set([...rememberedInitialNonEmptyKeys].filter((key) => nonEmpty(env[key])));
+    }
+    const snapshot = snapshotNonEmptyKeys(env);
+    if (isDefaultEnv) {
+        rememberedInitialNonEmptyKeys = new Set(snapshot);
+    }
+    return snapshot;
+}
+/**
+ * Load Kibi-owned env files into `process.env` (or an injectable env object).
+ * Blank values are treated as unset (never applied, never overwrite).
+ * Existing non-empty process keys are never overwritten. Project overrides user.
+ * Legacy `.env` only gap-fills and is attributed as `legacy_env`.
+ * Call only from CLI/MCP entrypoints — not on library import.
+ */
+// implements REQ-kibi-env-bootstrap
+export function bootstrapKibiEnvironment(options = {}) {
+    const env = options.env ?? process.env;
+    const isDefaultEnv = options.env === undefined;
+    const workspaceRoot = resolveKibiWorkspaceRoot(options.startDir, env);
+    if (isDefaultEnv &&
+        lastDefaultBootstrap &&
+        lastDefaultBootstrap.workspaceRoot !== workspaceRoot) {
+        // New workspace (e.g. doctor under KIBI_WORKSPACE): re-snapshot process keys.
+        rememberedInitialNonEmptyKeys = null;
+    }
+    const userEnvPath = resolveKibiUserEnvPath({
+        ...(options.homedir !== undefined ? { homedir: options.homedir } : {}),
+        ...(options.xdgConfigHome !== undefined
+            ? { xdgConfigHome: options.xdgConfigHome }
+            : {}),
+        env,
+    });
+    const projectEnvPath = resolveKibiProjectEnvPath(workspaceRoot, env);
+    const legacyEnvPath = resolveEnvFilePath(KIBI_LEGACY_ENV_FILE, workspaceRoot);
+    const initialNonEmpty = resolveInitialNonEmptyKeys(env, options, isDefaultEnv);
+    const sources = {};
+    for (const key of initialNonEmpty) {
+        sources[key] = "process";
+    }
+    const keysLoadedFromUser = [];
+    const keysLoadedFromProject = [];
+    const keysLoadedFromLegacy = [];
+    const userEntries = readEnvFileEntries(userEnvPath);
+    const projectEntries = readEnvFileEntries(projectEnvPath);
+    const legacyEntries = readEnvFileEntries(legacyEnvPath);
+    // User first, then project (project may overwrite user-sourced keys).
+    // Blank file values are unset — never applied, never overwrite.
+    for (const [key, value] of userEntries) {
+        if (!nonEmpty(value))
+            continue;
+        if (initialNonEmpty.has(key))
+            continue;
+        if (!nonEmpty(env[key])) {
+            env[key] = value;
+            keysLoadedFromUser.push(key);
+        }
+        sources[key] = "user_env";
+    }
+    for (const [key, value] of projectEntries) {
+        if (!nonEmpty(value))
+            continue;
+        if (initialNonEmpty.has(key))
+            continue;
+        const previousSource = sources[key];
+        env[key] = value;
+        if (previousSource !== "project_env" &&
+            !keysLoadedFromProject.includes(key)) {
+            keysLoadedFromProject.push(key);
+        }
+        sources[key] = "project_env";
+    }
+    // Legacy .env fills only keys still unset (compatibility; not preferred).
+    for (const [key, value] of legacyEntries) {
+        if (!nonEmpty(value))
+            continue;
+        if (initialNonEmpty.has(key))
+            continue;
+        if (sources[key] === "user_env" || sources[key] === "project_env") {
+            continue;
+        }
+        if (!nonEmpty(env[key])) {
+            env[key] = value;
+            keysLoadedFromLegacy.push(key);
+        }
+        sources[key] = "legacy_env";
+    }
+    const result = {
+        workspaceRoot,
+        userEnvPath,
+        projectEnvPath,
+        legacyEnvPath,
+        sources,
+        keysLoadedFromUser,
+        keysLoadedFromProject,
+        keysLoadedFromLegacy,
+    };
+    if (isDefaultEnv) {
+        lastDefaultBootstrap = result;
+    }
+    return result;
+}
+/**
+ * Resolve a secret source label from an actual bootstrap result.
+ * Never reconstructs attribution by re-reading files alone.
+ */
+// implements REQ-kibi-env-bootstrap
+export function secretSourceFromBootstrap(key, bootstrap, env = process.env) {
+    const attributed = bootstrap.sources[key];
+    if (attributed) {
+        return nonEmpty(env[key]) ? attributed : "missing";
+    }
+    return nonEmpty(env[key]) ? "process" : "missing";
+}
+/**
+ * Read-only secret attribution via a dry bootstrap on an env snapshot.
+ * Prefer `secretSourceFromBootstrap` with the real entrypoint bootstrap result.
+ * Never returns secret values.
+ */
+// implements REQ-kibi-env-bootstrap
+export function inspectSecretSource(key, options = {}) {
+    if (options.env === undefined &&
+        lastDefaultBootstrap &&
+        !options.startDir &&
+        !options.xdgConfigHome &&
+        !options.homedir &&
+        !options.initialNonEmptyProcessKeys &&
+        !options.initialProcessKeys) {
+        return secretSourceFromBootstrap(key, lastDefaultBootstrap);
+    }
+    const envCopy = { ...(options.env ?? process.env) };
+    const initial = options.initialNonEmptyProcessKeys ??
+        options.initialProcessKeys ??
+        (options.env === undefined && rememberedInitialNonEmptyKeys
+            ? new Set([...rememberedInitialNonEmptyKeys].filter((key) => nonEmpty(envCopy[key])))
+            : snapshotNonEmptyKeys(envCopy));
+    const result = bootstrapKibiEnvironment({
+        ...options,
+        env: envCopy,
+        initialNonEmptyProcessKeys: initial,
+    });
+    return secretSourceFromBootstrap(key, result, envCopy);
+}
+/**
+ * Whether a secret is available for provider use (non-empty after resolution).
+ * Blank values are unset.
+ */
+// implements REQ-kibi-env-bootstrap
+export function isSecretAvailable(key, options = {}) {
+    return inspectSecretSource(key, options) !== "missing";
+}

package/dist/extractors/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extractors/manifest.ts"],"names":[],"mappings":"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"}

package/dist/extractors/manifest.js

@@ -37,6 +37,7 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "publishes",
     "consumes",
     "supersedes",
+    "restates",
     "relates_to",
 ]);
 const VALID_RELATIONSHIP_DIRECTIONS = [
@@ -60,6 +61,7 @@ const VALID_RELATIONSHIP_DIRECTIONS = [
     { type: "consumes", from: "symbol", to: "event" },
     { type: "supersedes", from: "adr", to: "adr" },
     { type: "supersedes", from: "req", to: "req" },
+    { type: "restates", from: "req", to: "req" },
 ];
 const RELATIONSHIP_TYPE_DISPLAY_LIST = Array.from(VALID_RELATIONSHIP_TYPES)
     .sort()
@@ -325,46 +327,82 @@ export function readManifestWithCoordinateOverlay(manifestPath, coordinatesPath)
     });
 }
 /**
- * Resolve the code scope of a receipt binding: for each proof-bound symbol,
- * its coordinate-recorded source hash. A receipt's binding covers these, so
- * editing the production code behind a test stales only that test's receipts
- * (per-contract binding mode).
+ * Resolve the code scope of a receipt binding: for each scoped symbol, the
+ * content hash of its current source file. A receipt's binding covers these,
+ * so editing code a test depends on stales only that test's receipts
+ * (per-contract binding mode). Hashes come from the live file, not the
+ * coordinate artifact: an edit must stale the receipt whether or not
+ * coordinates were refreshed. A scoped symbol whose file is gone hashes as
+ * "missing", so deleting it stales the receipt too; symbols without a
+ * source file cannot be hashed and are left out.
  */
-// implements REQ-kibi-proof-evidence-protocol
-// Receipt-binding scope reads run once per proof-bearing test; a campaign
-// touches dozens-to-hundreds of tests, so the parsed overlay is memoized per
-// manifest state (path + mtime + size) and invalidated when the file changes.
-const boundSymbolScopeCache = new Map();
-function boundSymbolScopeRecords(manifestPath) {
-    let stamp = "";
+// implements REQ-kibi-verification-evidence-contract
+// Scope reads run once per proof-bearing test and a campaign touches
+// dozens-to-hundreds of tests, so the manifest's symbol -> source mapping is
+// memoized per manifest state and file hashes per file state (mtime + size).
+const scopeSourceFileCache = new Map();
+const scopeFileHashCache = new Map();
+function fileStamp(filePath) {
     try {
-        const stats = statSync(manifestPath);
-        stamp = `${stats.mtimeMs}:${stats.size}`;
+        const stats = statSync(filePath);
+        return `${stats.mtimeMs}:${stats.size}`;
     }
     catch {
-        stamp = "missing";
+        return null;
+    }
+}
+function scopeSourceFiles(manifestPath) {
+    const stamp = fileStamp(manifestPath) ?? "missing";
+    const hit = scopeSourceFileCache.get(manifestPath);
+    if (hit && hit.stamp === stamp)
+        return hit.sourceFiles;
+    const sourceFiles = new Map();
+    if (stamp !== "missing") {
+        const records = extractManifestSymbolRecordsString(readFileSync(manifestPath, "utf8"), manifestPath);
+        for (const record of records) {
+            const sourceFile = typeof record.sourceFile === "string" && record.sourceFile !== ""
+                ? record.sourceFile
+                : typeof record.source === "string" && record.source !== ""
+                    ? record.source
+                    : undefined;
+            if (typeof record.id === "string" && sourceFile !== undefined) {
+                sourceFiles.set(record.id, sourceFile);
+            }
+        }
     }
-    const hit = boundSymbolScopeCache.get(manifestPath);
+    scopeSourceFileCache.set(manifestPath, { stamp, sourceFiles });
+    return sourceFiles;
+}
+function scopeFileHash(absolutePath) {
+    const stamp = fileStamp(absolutePath);
+    if (stamp === null)
+        return "missing";
+    const hit = scopeFileHashCache.get(absolutePath);
     if (hit && hit.stamp === stamp)
-        return hit.records;
-    const records = readManifestWithCoordinateOverlay(manifestPath);
-    boundSymbolScopeCache.set(manifestPath, { stamp, records });
-    return records;
+        return hit.hash;
+    const hash = createHash("sha256")
+        .update(readFileSync(absolutePath))
+        .digest("hex");
+    scopeFileHashCache.set(absolutePath, { stamp, hash });
+    return hash;
 }
 export function resolveBoundSymbolScope(manifestPath, symbolIds) {
-    const wanted = new Set(symbolIds);
-    if (wanted.size === 0)
+    const wanted = [...new Set(symbolIds)];
+    if (wanted.length === 0)
         return [];
-    const records = boundSymbolScopeRecords(manifestPath);
+    const sourceFiles = scopeSourceFiles(manifestPath);
+    // The manifest lives at <workspace>/.kb/symbols.yaml; source files are
+    // workspace-relative.
+    const workspaceRoot = path.dirname(path.dirname(path.resolve(manifestPath)));
     const scope = [];
-    for (const record of records) {
-        const symbolId = typeof record.id === "string" ? record.id : undefined;
-        if (symbolId === undefined || !wanted.has(symbolId))
+    for (const symbolId of wanted) {
+        const sourceFile = sourceFiles.get(symbolId);
+        if (sourceFile === undefined)
             continue;
-        const sourceHash = record.sourceHash;
-        if (typeof sourceHash === "string" && sourceHash !== "") {
-            scope.push({ symbolId, sourceHash });
-        }
+        const absolute = path.isAbsolute(sourceFile)
+            ? sourceFile
+            : path.resolve(workspaceRoot, sourceFile);
+        scope.push({ symbolId, sourceHash: scopeFileHash(absolute) });
     }
     scope.sort((left, right) => left.symbolId.localeCompare(right.symbolId));
     return scope;

package/dist/extractors/markdown.d.ts

@@ -28,6 +28,8 @@ export interface ExtractedEntity {
     sourceEndColumn?: number;
     verification_scope?: "unit" | "integration" | "end_to_end";
     verification_perspective?: "internal" | "consumer";
+    proof_exempt?: boolean;
+    proof_exempt_reason?: string;
     proof_contract?: ProofContract;
     proof_bindings?: readonly ProofBinding[];
     proof_receipts?: readonly ProofReceipt[];
@@ -59,6 +61,8 @@ export interface ExtractedEntity {
     examples?: string[];
     predicate_args?: string[];
     rule_ir?: Record<string, unknown>;
+    argument_constants?: Record<string, string[]>;
+    argument_aliases?: Record<string, Record<string, string>>;
     rule_hash?: string;
     rule_schema_id?: string;
     rule_name?: string;

package/dist/extractors/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAuBA,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,YAAY,EAElB,MAAM,4BAA4B,CAAC;AAsEpC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,0BAA0B,CAAC,EAAE,4BAA4B,CAAC;IAC1D,qBAAqB,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,CAAC;IAC/D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,wBAAwB,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAEzC,SAAS,CAAC,EACN,SAAS,GACT,gBAAgB,GAChB,aAAa,GACb,MAAM,GACN,kBAAkB,GAClB,WAAW,GACX,aAAa,GACb,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IACtD,UAAU,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAiMD,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IAYM,QAAQ;CAUlB;AA+CD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAkBD,wBAAgB,sBAAsB,CAEpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAkDV;AAqdD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAElB;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAatE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE;AASD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpE"}

package/dist/extractors/markdown.js

@@ -42,6 +42,8 @@ const FACT_STRING_FIELDS = [
     "predicate_name",
     "predicate_namespace",
     "rule_ir",
+    "argument_constants",
+    "argument_aliases",
     "rule_hash",
     "rule_schema_id",
     "rule_name",
@@ -77,7 +79,13 @@ const TEST_ENUM_FIELDS = [
     "proof_receipts",
 ];
 const ajv = new Ajv({ strict: false, allErrors: true });
-const validateExtractedEntity = ajv.compile(entitySchema);
+// Compiled on first extraction: every CLI command imports this module, and
+// most never extract Markdown entities.
+let extractedEntityValidator;
+function validateExtractedEntity() {
+    extractedEntityValidator ??= ajv.compile(entitySchema);
+    return extractedEntityValidator;
+}
 const DEFAULT_STATUS_BY_TYPE = {
     req: "open",
     scenario: "draft",
@@ -105,6 +113,7 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "publishes",
     "consumes",
     "supersedes",
+    "restates",
     "relates_to",
 ]);
 const VALID_RELATIONSHIP_DIRECTIONS = [
@@ -129,6 +138,7 @@ const VALID_RELATIONSHIP_DIRECTIONS = [
     { type: "consumes", from: "symbol", to: "event" },
     { type: "supersedes", from: "adr", to: "adr" },
     { type: "supersedes", from: "req", to: "req" },
+    { type: "restates", from: "req", to: "req" },
 ];
 const RELATIONSHIP_TYPE_DISPLAY_LIST = Array.from(VALID_RELATIONSHIP_TYPES)
     .sort()
@@ -411,6 +421,25 @@ function extractFromMarkdownContent(content, filePath) {
         if (type === "req" && data.semantic_source_hash !== undefined) {
             entity.semantic_source_hash = data.semantic_source_hash;
         }
+        if (type === "req" && data.proof_exempt !== undefined) {
+            if (typeof data.proof_exempt !== "boolean") {
+                throw new FrontmatterError("Invalid proof_exempt; expected true or false", filePath, {
+                    classification: "Invalid Proof Exemption Flag",
+                    hint: "Set proof_exempt: true with a non-empty proof_exempt_reason.",
+                });
+            }
+            entity.proof_exempt = data.proof_exempt;
+        }
+        if (type === "req" && data.proof_exempt_reason !== undefined) {
+            if (typeof data.proof_exempt_reason !== "string" ||
+                data.proof_exempt_reason.trim() === "") {
+                throw new FrontmatterError("Invalid proof_exempt_reason; expected a non-empty string", filePath, {
+                    classification: "Invalid Proof Exemption Reason",
+                    hint: "proof_exempt requires a non-empty proof_exempt_reason explaining why the requirement is outside E2E-proof scope.",
+                });
+            }
+            entity.proof_exempt_reason = data.proof_exempt_reason;
+        }
         if (type !== "fact") {
             const invalidFactField = FACT_ONLY_FIELDS.find((field) => data[field] !== undefined);
             if (invalidFactField) {
@@ -558,8 +587,9 @@ function extractFromMarkdownContent(content, filePath) {
         if (type === "req" && Array.isArray(data.semantic_inventory)) {
             entity.semantic_inventory = data.semantic_inventory.filter((value) => isObjectRecord(value));
         }
-        if (!validateExtractedEntity(entity)) {
-            const messages = (validateExtractedEntity.errors || [])
+        const validateEntity = validateExtractedEntity();
+        if (!validateEntity(entity)) {
+            const messages = (validateEntity.errors || [])
                 .map((e) => `${e.instancePath || "root"}: ${e.message}`)
                 .join("; ");
             throw new FrontmatterError(`Entity validation failed: ${messages}`, filePath, {

package/dist/extractors/relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/extractors/relationships.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,KAAK,kBAAkB,EAAa,MAAM,4BAA4B,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAyBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,EAAE,CAmBzB;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,GAChB,qBAAqB,CAiBvB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,GAAG,IAAI,CAyC9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAAE,GAC/B,qBAAqB,EAAE,CAEzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,qBAAqB,EAAE,EACtC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IACP,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC;CACtC,CAAC,CAgBD"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/extractors/relationships.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,KAAK,kBAAkB,EAAa,MAAM,4BAA4B,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AA0BD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,EAAE,CAmBzB;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,GAChB,qBAAqB,CAiBvB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,GAAG,IAAI,CAyC9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,EAAE,GAC/B,qBAAqB,EAAE,CAEzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,qBAAqB,EAAE,EACtC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IACP,YAAY,EAAE,qBAAqB,CAAC;IACpC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC;CACtC,CAAC,CAgBD"}

package/dist/extractors/relationships.js

@@ -38,6 +38,7 @@ const VALID_RELATIONSHIP_TYPES = new Set([
     "publishes",
     "consumes",
     "supersedes",
+    "restates",
     "relates_to",
 ]);
 /**

package/dist/extractors/symbols-coordinator.d.ts

@@ -1,3 +1,4 @@
+import type { CapabilityRegistry } from "../plugins/registry.js";
 import { type ManifestSymbolEntry, enrichSymbolCoordinatesWithTsMorph } from "./symbols-ts.js";
 export type { ManifestSymbolEntry };
 export type SourceAnalysisMode = "parser" | "fallback";
@@ -31,11 +32,18 @@ export interface SourceAnalysisProvider {
 }
 export interface AnalyzeSourceTextOptions {
     providers?: SourceAnalysisProvider[];
+    /** When set, prefer the host SourceAnalysisService over sync providers. */
+    registry?: CapabilityRegistry;
 }
 interface EnrichSymbolCoordinatesDeps {
     enrichTsCoordinates: typeof enrichSymbolCoordinatesWithTsMorph;
 }
 export declare function analyzeSourceText(entries: ManifestSymbolEntry[], workspaceRoot: string, deps?: Partial<EnrichSymbolCoordinatesDeps>): Promise<ManifestSymbolEntry[]>;
 export declare function analyzeSourceText(filePath: string, content: string, options?: AnalyzeSourceTextOptions): SourceAnalysisResult;
+/**
+ * Prefer the capability registry / SourceAnalysisService when available.
+ * Falls back to the sync builtin ts-morph provider path on registry failure.
+ */
+export declare function analyzeSourceTextWithRegistry(filePath: string, content: string, registry: CapabilityRegistry): Promise<SourceAnalysisResult>;
 export declare function enrichSymbolCoordinates(entries: ManifestSymbolEntry[], workspaceRoot: string, deps?: Partial<EnrichSymbolCoordinatesDeps>): Promise<ManifestSymbolEntry[]>;
 //# sourceMappingURL=symbols-coordinator.d.ts.map

package/dist/extractors/symbols-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,mBAAmB,EAExB,kCAAkC,EACnC,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAAC;CACtE;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,kCAAkC,CAAC;CAChE;AA+BD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAClC,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAAC;AAkCxB,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqChC"}
+{"version":3,"file":"symbols-coordinator.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-coordinator.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAKjE,OAAO,EACL,KAAK,mBAAmB,EAExB,kCAAkC,EACnC,MAAM,iBAAiB,CAAC;AAazB,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,GACX,MAAM,GACN,MAAM,GACN,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAAC;CACtE;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,kCAAkC,CAAC;CAChE;AA+BD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAClC,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAAC;AA8DxB;;;GAGG;AAEH,wBAAsB,6BAA6B,CACjD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAO/B;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAC1C,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAqChC"}