kibi-cli 2.4.0 → 2.5.1

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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"}