kibi-cli 2.4.0 → 2.5.0

package/dist/relationships/shards.js

@@ -51,7 +51,14 @@ export function readShard(shardPath) {
     if (!fs.existsSync(shardPath)) {
         return [];
     }
-    const content = fs.readFileSync(shardPath, "utf8");
+    return parseShardText(fs.readFileSync(shardPath, "utf8"), shardPath);
+}
+/**
+ * Parses relationship shard text read from `shardPath`.
+ * Returns an empty array for blank text. Throws on parse errors.
+ */
+// implements REQ-kibi-operation-interface-parity
+export function parseShardText(content, shardPath) {
     if (!content.trim()) {
         return [];
     }
@@ -121,7 +128,10 @@ export function writeShard(shardPath, records) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    // Sort and dedupe records
+    atomicWriteText(shardPath, renderShardRecords(records));
+}
+/** Canonical shard text for `records`: sorted and deduplicated. */
+function renderShardRecords(records) {
     const sorted = sortRecords(records);
     const seen = new Set();
     const unique = [];
@@ -132,8 +142,7 @@ export function writeShard(shardPath, records) {
         seen.add(key);
         unique.push(record);
     }
-    const yamlContent = serializeToYAML(unique);
-    atomicWriteText(shardPath, yamlContent);
+    return serializeToYAML(unique);
 }
 /**
  * Publish one canonical shard replacement atomically. Relationship shards are
@@ -254,32 +263,49 @@ function sortRecords(records) {
  */
 export function appendRelationship(kbRoot, relationship) {
     const shardPath = computeShardPath(kbRoot, relationship.from);
-    const existing = readShard(shardPath);
-    // Generate deterministic ID
-    const recordId = relationshipIdFor(relationship.type, relationship.from, relationship.to);
-    // Check if relationship already exists
-    const exists = existing.some((r) => r.type === relationship.type &&
-        r.from === relationship.from &&
-        r.to === relationship.to);
-    if (!exists) {
-        const newRecord = {
-            ...relationship,
-            id: recordId,
-        };
-        if (fs.existsSync(shardPath)) {
-            const document = parseDocument(fs.readFileSync(shardPath, "utf8"));
-            const sequence = document.get("relationships", true);
-            if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
-                throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
-            }
-            sequence.items.push(newRecord);
-            atomicWriteText(shardPath, document.toString());
-        }
-        else {
-            writeShard(shardPath, [newRecord]);
+    const existing = fs.existsSync(shardPath)
+        ? fs.readFileSync(shardPath, "utf8")
+        : null;
+    const next = renderShardWithRelationship(shardPath, existing, relationship);
+    if (next !== null) {
+        if (existing === null) {
+            fs.mkdirSync(path.dirname(shardPath), { recursive: true });
         }
+        atomicWriteText(shardPath, next);
     }
-    return { shardPath, recordId };
+    return {
+        shardPath,
+        recordId: relationshipIdFor(relationship.type, relationship.from, relationship.to),
+    };
+}
+/**
+ * The shard text appendRelationship would publish for `relationship`, without
+ * writing it: `existing` is the current shard text, or null when the shard
+ * file does not exist. Returns null when the shard already records the
+ * relationship. Callers that must journal exact after-bytes before any write
+ * (atomic plan application) render a shard through this function.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-core-atomic-upsert-persistence
+export function renderShardWithRelationship(shardPath, existing, relationship) {
+    const records = existing === null ? [] : parseShardText(existing, shardPath);
+    if (records.some((r) => r.type === relationship.type &&
+        r.from === relationship.from &&
+        r.to === relationship.to)) {
+        return null;
+    }
+    const newRecord = {
+        ...relationship,
+        id: relationshipIdFor(relationship.type, relationship.from, relationship.to),
+    };
+    if (existing === null)
+        return renderShardRecords([newRecord]);
+    const document = parseDocument(existing);
+    const sequence = document.get("relationships", true);
+    if (!sequence || typeof sequence !== "object" || !("items" in sequence)) {
+        throw new Error(`Invalid shard file: missing 'relationships' array at ${shardPath}`);
+    }
+    sequence.items.push(newRecord);
+    return document.toString();
 }
 /**
  * Lists all shard files in the relationships directory.

package/dist/runtime/cli-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAKV,gBAAgB,EAEhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAErC,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAOR;AAkFD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CAwHlB"}
+{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAKV,gBAAgB,EAEhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAOrC,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAOR;AA2GD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CA4IlB"}

package/dist/runtime/cli-runtime.js

@@ -3,7 +3,8 @@ import { retryAttachAfterBreakingStaleLock } from "../prolog/store-lock.js";
 import { EngineClient } from "../engine.js";
 import { CapabilityRegistryCache, ensureCapabilityRegistry, } from "../plugins/registry.js";
 import { nodeFilesystem, nodeGit, nodeNetwork, } from "../public/operations/node-ports.js";
-import { resolveBranchAttachment, } from "../utils/branch-resolver.js";
+import { resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
+import { declaresWriteEffect, refreshDetachedSnapshot, resolveOperationAttachment, } from "./detached-snapshot.js";
 export function attachmentFailureMessage(attachment) {
     const isNonGitContext = attachment.code === "NOT_A_GIT_REPO" ||
         attachment.code === "GIT_NOT_AVAILABLE";
@@ -65,6 +66,27 @@ function resolvePluginsOption(plugins) {
         return plugins;
     return async () => plugins;
 }
+/**
+ * The detached-HEAD snapshot attachment for a KB read that may run without
+ * Prolog (status), or undefined when the checkout resolves normally (that
+ * path keeps its lazy, non-mutating behavior). A failed snapshot compile is
+ * reported but not fatal, so status can still diagnose the snapshot store.
+ */
+// implements REQ-branch-store-recovery-v4
+async function resolveDetachedReadAttachment(root) {
+    const attachment = resolveReadBranchAttachment(root);
+    if ("error" in attachment || attachment.readOnly === undefined) {
+        return undefined;
+    }
+    console.warn(`[KIBI] ${attachment.readOnly.notice}`);
+    try {
+        await refreshDetachedSnapshot(root, attachment);
+    }
+    catch (error) {
+        console.warn(`[KIBI] ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return attachment;
+}
 // implements REQ-kibi-operation-interface-parity
 export function createCliRuntime(options = {}) {
     const ownedPrologs = new WeakMap();
@@ -102,10 +124,16 @@ export function createCliRuntime(options = {}) {
                 // That keeps pre-init and damaged-store diagnostics non-mutating.
                 let lazyProlog = merged.prolog;
                 const lazyContext = {};
+                // A KB read on a detached HEAD answers from the checkout's snapshot;
+                // resolve it up front so the operation reports which store it read.
+                const detachedAttachment = !declaresWriteEffect(spec.effects) && spec.effects.includes("kb-read")
+                    ? await resolveDetachedReadAttachment(root)
+                    : undefined;
                 const ensureProlog = async () => {
                     if (lazyProlog !== undefined)
                         return bindSignal(lazyProlog, signal);
-                    const attachment = resolveBranchAttachment(root);
+                    const attachment = detachedAttachment ??
+                        (await resolveOperationAttachment(root, spec));
                     if ("error" in attachment) {
                         throw new Error(`Failed to resolve active branch: ${attachment.error}`);
                     }
@@ -125,16 +153,29 @@ export function createCliRuntime(options = {}) {
                         ? { prolog: bindSignal(merged.prolog, signal) }
                         : {}),
                     ...(lazyEngine ? { engine: lazyEngine } : {}),
+                    ...(detachedAttachment
+                        ? { branchAttachment: detachedAttachment }
+                        : {}),
                     ensureProlog,
                 };
                 lazyContext.current = context;
                 return context;
             }
-            const attachment = resolveBranchAttachment(root);
+            let attachment;
+            try {
+                attachment = await resolveOperationAttachment(root, spec);
+            }
+            catch (error) {
+                await merged.prolog?.terminate?.();
+                throw error;
+            }
             if ("error" in attachment) {
                 await merged.prolog?.terminate?.();
                 throw new Error(attachmentFailureMessage(attachment));
             }
+            if (attachment.readOnly !== undefined) {
+                console.warn(`[KIBI] ${attachment.readOnly.notice}`);
+            }
             if (attachment.migrationRequired) {
                 console.warn(`[KIBI] Legacy branch attachment: Git '${attachment.gitBranch}' is reading KB '${attachment.kbBranch}'. Migrate with 'kibi branch migrate --from ${attachment.kbBranch} --to ${attachment.gitBranch} --apply'; writes are blocked until then.`);
             }

package/dist/runtime/detached-snapshot.d.ts

@@ -0,0 +1,38 @@
+import type { OperationEffect } from "../public/operations/types.js";
+import { type BranchAttachment, type BranchResolutionError } from "../utils/branch-resolver.js";
+/** Envelope diagnostic code reported while a detached snapshot is attached. */
+export declare const DETACHED_HEAD_READ_ONLY_CODE = "detached_head_read_only";
+export type DetachedReadOnlyDiagnostic = {
+    readonly code: typeof DETACHED_HEAD_READ_ONLY_CODE;
+    readonly severity: "warning";
+    readonly message: string;
+    readonly detail: {
+        readonly head: string;
+        readonly branchesAtHead: readonly string[];
+        readonly kbBranch: string;
+        readonly storePath: string;
+        readonly writes: "refused";
+    };
+};
+/** True when an operation declares a KB or workspace write. */
+export declare function declaresWriteEffect(effects: readonly OperationEffect[] | readonly string[]): boolean;
+/**
+ * Compile (or incrementally refresh) the read-only snapshot of a detached
+ * checkout. The snapshot store is a cache of the checkout's tracked sources:
+ * refreshing it never touches a branch KB or an authored file.
+ */
+export declare function refreshDetachedSnapshot(workspaceRoot: string, attachment: BranchAttachment): Promise<void>;
+/**
+ * Resolve the branch attachment an operation may use.
+ *
+ * Writes keep the exact-branch contract and receive an actionable refusal on
+ * a detached HEAD. Reads on a detached HEAD that no single branch points at
+ * attach a freshly compiled read-only snapshot of the checkout.
+ */
+export declare function resolveOperationAttachment(workspaceRoot: string, spec: {
+    readonly name: string;
+    readonly effects: readonly OperationEffect[];
+}): Promise<BranchAttachment | BranchResolutionError>;
+/** The envelope diagnostic for an operation answered from a snapshot. */
+export declare function detachedReadOnlyDiagnostic(attachment: BranchAttachment | undefined): DetachedReadOnlyDiagnostic | undefined;
+//# sourceMappingURL=detached-snapshot.d.ts.map

package/dist/runtime/detached-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detached-snapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/detached-snapshot.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAI3B,MAAM,6BAA6B,CAAC;AAErC,+EAA+E;AAE/E,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAGtE,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,OAAO,4BAA4B,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;KAC5B,CAAC;CACH,CAAC;AAEF,+DAA+D;AAE/D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAAE,GACtD,OAAO,CAIT;AAED;;;;GAIG;AAEH,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;GAMG;AAEH,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GAC5E,OAAO,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,CAoBnD;AAED,yEAAyE;AAEzE,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,0BAA0B,GAAG,SAAS,CAexC"}

package/dist/runtime/detached-snapshot.js

@@ -0,0 +1,92 @@
+/*
+ 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 { detachedHeadWriteRefusal, resolveBranchAttachment, resolveReadBranchAttachment, } from "../utils/branch-resolver.js";
+/** Envelope diagnostic code reported while a detached snapshot is attached. */
+// implements REQ-branch-store-recovery-v4
+export const DETACHED_HEAD_READ_ONLY_CODE = "detached_head_read_only";
+/** True when an operation declares a KB or workspace write. */
+// implements REQ-branch-store-recovery-v4
+export function declaresWriteEffect(effects) {
+    return effects.some((effect) => effect === "kb-write" || effect === "workspace-write");
+}
+/**
+ * Compile (or incrementally refresh) the read-only snapshot of a detached
+ * checkout. The snapshot store is a cache of the checkout's tracked sources:
+ * refreshing it never touches a branch KB or an authored file.
+ */
+// implements REQ-branch-store-recovery-v4
+export async function refreshDetachedSnapshot(workspaceRoot, attachment) {
+    const { syncCommand } = await import("../commands/sync.js");
+    try {
+        await syncCommand({
+            workspaceRoot,
+            detachedSnapshot: attachment,
+            quiet: true,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to compile the read-only snapshot for this detached HEAD: ${message}`);
+    }
+}
+/**
+ * Resolve the branch attachment an operation may use.
+ *
+ * Writes keep the exact-branch contract and receive an actionable refusal on
+ * a detached HEAD. Reads on a detached HEAD that no single branch points at
+ * attach a freshly compiled read-only snapshot of the checkout.
+ */
+// implements REQ-branch-store-recovery-v4
+export async function resolveOperationAttachment(workspaceRoot, spec) {
+    if (declaresWriteEffect(spec.effects)) {
+        const attachment = resolveBranchAttachment(workspaceRoot);
+        if ("error" in attachment && attachment.code === "DETACHED_HEAD") {
+            return {
+                error: detachedHeadWriteRefusal(spec.name, workspaceRoot),
+                code: "DETACHED_HEAD",
+            };
+        }
+        return attachment;
+    }
+    const attachment = resolveReadBranchAttachment(workspaceRoot);
+    if (!("error" in attachment) &&
+        attachment.readOnly !== undefined &&
+        spec.effects.includes("kb-read")) {
+        await refreshDetachedSnapshot(workspaceRoot, attachment);
+    }
+    return attachment;
+}
+/** The envelope diagnostic for an operation answered from a snapshot. */
+// implements REQ-branch-store-recovery-v4
+export function detachedReadOnlyDiagnostic(attachment) {
+    const readOnly = attachment?.readOnly;
+    if (attachment === undefined || readOnly === undefined)
+        return undefined;
+    return {
+        code: DETACHED_HEAD_READ_ONLY_CODE,
+        severity: "warning",
+        message: readOnly.notice,
+        detail: {
+            head: readOnly.head,
+            branchesAtHead: readOnly.branchesAtHead,
+            kbBranch: attachment.kbBranch,
+            storePath: attachment.storePath,
+            writes: "refused",
+        },
+    };
+}

package/dist/schemas/entity.schema.json

@@ -478,6 +478,51 @@
         "text_ref": {
             "type": "string"
         },
+        "origin": {
+            "type": "object",
+            "required": [
+                "kind"
+            ],
+            "properties": {
+                "kind": {
+                    "type": "string",
+                    "enum": [
+                        "human",
+                        "agent",
+                        "migration",
+                        "import"
+                    ],
+                    "description": "Who authored the entity: human, agent, migration (backfilled by kibi migrate) or import."
+                },
+                "ref": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "Source reference for the authored content: URL, document path, ticket, commit or conversation id."
+                },
+                "approved_by": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "The person who reviewed and approved this entity's content. Distinct from the requirement-level approved_by of an exception."
+                },
+                "recorded_at": {
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
+                    "description": "ISO-8601 time the provenance was recorded."
+                }
+            },
+            "additionalProperties": false
+        },
+        "expects": {
+            "type": "string",
+            "enum": [
+                "success",
+                "rejection",
+                "error"
+            ],
+            "description": "Scenario-only. The scenario's intended outcome. A scenario that expects success and assumes (via `assumes` facts) a value a current requirement forbids fails the scenario-feasibility check."
+        },
         "proof_exempt": {
             "type": "boolean",
             "description": "Requirement-only. Marks a current requirement as intentionally outside E2E-proof scope; requires proof_exempt_reason."
@@ -487,6 +532,33 @@
             "minLength": 1,
             "description": "Requirement-only. Required when proof_exempt is true; surfaces as the applicability reason in coverage rows."
         },
+        "approved_by": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Requirement-only. The human who approved this exception requirement. An exception (a requirement that exempts another and is specified_by a scenario) makes that success scenario feasible only when approved_by is set."
+        },
+        "approval_ref": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Requirement-only. Optional reference to the approval decision record (ticket, ADR or review link) for an exception requirement."
+        },
+        "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "description": "Requirement-only. Why the requirement exists, in one or two sentences from whoever stated the intent. Explanation only: it is not part of the checked meaning."
+        },
+        "exempts_claims": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+                "type": "string",
+                "pattern": "^CLAIM-[A-F0-9]{16}$"
+            },
+            "description": "Requirement-only. Narrows an exception requirement to individual clauses: the claim keys (from logic_claims) of the requirement it exempts whose constraints it waives. Without it the exception waives the whole exempted requirement."
+        },
         "semantic_text": {
             "type": "string",
             "description": "Requirement-only authored prose whose exact UTF-8 bytes anchor the semantic inventory without replacing text_ref evidence."
@@ -1155,6 +1227,15 @@
                 "type": "string"
             }
         },
+        "key_arguments": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+                "type": "string",
+                "minLength": 1
+            }
+        },
         "aliases": {
             "type": "array",
             "items": {
@@ -1380,6 +1461,11 @@
                                 "argument_descriptions"
                             ]
                         },
+                        {
+                            "required": [
+                                "key_arguments"
+                            ]
+                        },
                         {
                             "required": [
                                 "aliases"
@@ -1546,11 +1632,47 @@
                             "required": [
                                 "proof_exempt_reason"
                             ]
+                        },
+                        {
+                            "required": [
+                                "approved_by"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "approval_ref"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "rationale"
+                            ]
+                        },
+                        {
+                            "required": [
+                                "exempts_claims"
+                            ]
                         }
                     ]
                 }
             }
         },
+        {
+            "if": {
+                "properties": {
+                    "type": {
+                        "const": "scenario"
+                    }
+                }
+            },
+            "else": {
+                "not": {
+                    "required": [
+                        "expects"
+                    ]
+                }
+            }
+        },
         {
             "if": {
                 "anyOf": [

package/dist/search-answer.d.ts

@@ -0,0 +1,157 @@
+import type { IntentSearchMatch } from "./intent-search.js";
+import type { PrologPort } from "./public/operations/runtime-types.js";
+/**
+ * The answer layer turns ranked matches into what an agent asking "what
+ * governs this?" needs: the current requirements that apply, why (ADRs, with
+ * an excerpt of their decision), what must stay true (linked facts), what
+ * verifies it (scenarios and tests), what the existing checks say about it
+ * (contradiction and scenario-feasibility witnesses, exceptions, and what is
+ * still unknown), and the KB snapshot the answer was computed from.
+ * Superseded or deprecated requirements are listed separately so they are
+ * never read as current policy, and observation facts are labelled as notes,
+ * not rules. Tests are collected through the canonical
+ * REQ -specified_by-> SCEN -verified_by-> TEST path as well as direct
+ * requirement links, and each says how it was reached. Graph links are
+ * discovery, not proof, and a verdict of `none` means no check named the
+ * requirement, not that it is proven.
+ */
+export type SearchAnswerEntity = Readonly<{
+    id: string;
+    title: string;
+    status?: string;
+}>;
+/**
+ * A test verifying a governing requirement. `via` is `"direct"` for a test
+ * linked to the requirement itself, or the id of the scenario it verifies.
+ */
+export type SearchAnswerTest = SearchAnswerEntity & Readonly<{
+    via: string;
+}>;
+/** An ADR with the opening of its decision (or rationale) section. */
+export type SearchAnswerRationale = SearchAnswerEntity & Readonly<{
+    source?: string;
+    excerpt?: string;
+}>;
+/** A blocking finding of an existing check that names the requirement. */
+export type SearchAnswerWitness = Readonly<{
+    check: "domain-contradictions" | "scenario-feasibility";
+    status: "contradiction" | "infeasible";
+    /** The other requirement in a contradiction, or the forbidding one. */
+    with?: string;
+    scenario?: string;
+    facts: readonly string[];
+    detail: string;
+}>;
+/**
+ * What the checks could not decide for the requirement: rule overlaps they
+ * could not classify, scenarios whose feasibility is unknown, propositions
+ * still ambiguous or ontology gaps, a missing clause ledger, or a verdict
+ * that could not be computed.
+ */
+export type SearchAnswerUnknown = Readonly<{
+    kind: "contradiction_unresolved" | "feasibility_unknown" | "unresolved_proposition" | "analysis_incomplete" | "verdict_unavailable";
+    detail: string;
+    entities: readonly string[];
+}>;
+export type SearchAnswerVerdict = Readonly<{
+    /**
+     * The worst finding: `contradiction` or `infeasible` when a blocking
+     * witness exists, `unknown` when only unknowns remain, `none` when no
+     * check named the requirement (absence of a witness is not proof).
+     */
+    status: "contradiction" | "infeasible" | "unknown" | "none";
+    witnesses: readonly SearchAnswerWitness[];
+}>;
+/** A requirement that `exempts` the governing one. */
+export type SearchAnswerException = SearchAnswerEntity & Readonly<{
+    approvedBy?: string;
+}>;
+export type SearchAnswerRequirement = SearchAnswerEntity & Readonly<{
+    score: number;
+    via: string;
+    facts: readonly (SearchAnswerEntity & {
+        factKind?: string;
+    })[];
+    scenarios: readonly SearchAnswerEntity[];
+    tests: readonly SearchAnswerTest[];
+    adrs: readonly SearchAnswerEntity[];
+    verdict: SearchAnswerVerdict;
+    exceptions: readonly SearchAnswerException[];
+    unknowns: readonly SearchAnswerUnknown[];
+}>;
+/** The KB the answer was computed from. */
+export type SearchAnswerScope = Readonly<{
+    branch: string | null;
+    snapshotId: string;
+    syncedAt: string | null;
+}>;
+export type SearchAnswer = Readonly<{
+    version: "kibi.search-answer.v1";
+    governing: readonly SearchAnswerRequirement[];
+    rationale: readonly SearchAnswerRationale[];
+    notGoverning: readonly (SearchAnswerEntity & {
+        supersededBy?: string;
+    })[];
+    observations: readonly SearchAnswerEntity[];
+    scope: SearchAnswerScope;
+    truncated: boolean;
+    note: string;
+}>;
+export type SearchAnswerOptions = Readonly<{
+    /** Root that ADR sources resolve against; without it no excerpts. */
+    workspaceRoot?: string;
+    /** The Git branch identity of the attached KB. */
+    branch?: string | null;
+}>;
+export declare const SEARCH_ANSWER_LIMITS: {
+    readonly seeds: 10;
+    readonly governing: 5;
+    readonly perRequirement: 4;
+    readonly rationale: 3;
+    readonly notGoverning: 5;
+    readonly observations: 3;
+    /** Entity rows loaded per answer, the matched seeds included. */
+    readonly entityLoads: 70;
+    readonly maxBytes: 16384;
+    /** Title length (characters) kept when an answer must shrink to fit. */
+    readonly titleChars: 160;
+    /** Characters of an ADR decision kept as its excerpt. */
+    readonly excerptChars: 280;
+    /** Characters of a witness or unknown detail kept. */
+    readonly detailChars: 240;
+};
+/**
+ * The opening sentences of an ADR's Decision section (falling back to
+ * Rationale, then to the first prose paragraph), as plain text of at most
+ * `maxChars` characters.
+ */
+export declare function adrExcerpt(body: string, maxChars?: number): string | undefined;
+type RawVerdict = Readonly<{
+    id?: unknown;
+    error?: unknown;
+    contradictions?: unknown;
+    scenarios?: unknown;
+    forbids?: unknown;
+    inventory?: unknown;
+}>;
+/** Project the Prolog verdict of one requirement onto the answer fields. */
+export declare function projectVerdict(raw: RawVerdict | undefined, perRequirement?: number): {
+    verdict: SearchAnswerVerdict;
+    unknowns: SearchAnswerUnknown[];
+    truncated: boolean;
+};
+export declare function buildSearchAnswer(prolog: Pick<PrologPort, "query">, matches: readonly IntentSearchMatch[], options?: SearchAnswerOptions): Promise<SearchAnswer>;
+/**
+ * Hold the whole answer under `maxBytes`, marking it truncated when anything
+ * is cut. In order: long titles, excerpts and details are clipped; ADR
+ * excerpts are dropped, last rationale entry first; the least relevant
+ * governing requirements are dropped;
+ * list items are dropped (notes and side lists before the remaining
+ * requirement's own lists, its verdict witnesses last); then the remaining
+ * requirement's title and `via` are clipped. A verdict keeps its status when
+ * its witnesses are dropped. If even that cannot fit, the requirement itself
+ * is dropped.
+ */
+export declare function fitSearchAnswer(answer: SearchAnswer, maxBytes?: number): SearchAnswer;
+export {};
+//# sourceMappingURL=search-answer.d.ts.map

package/dist/search-answer.d.ts.map

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