kibi-cli 2.36.0 → 2.39.0

package/src/public/operations/discovery-executors.ts

@@ -10,6 +10,7 @@ import {
   type IntentSearchAnalysis,
   type IntentSearchFacets,
   type IntentSearchMatch,
+  type MarkdownBodyCache,
   type SourceLocation,
   executeIntentSearch,
   questionPaths,
@@ -18,6 +19,12 @@ import {
 import { classifyActivation } from "../../operations/bootstrap/activation.js";
 import { SwiplResolutionError } from "../../prolog/swipl-resolver.js";
 import { type SearchAnswer, buildSearchAnswer } from "../../search-answer.js";
+import {
+  type SearchHintsAnalysis,
+  buildSearchHints,
+  searchHintsNote,
+  searchHintsTrigger,
+} from "../../search-hints.js";
 import { rankEntities } from "../../search-ranking.js";
 import type { SearchMatch } from "../../search-ranking.js";
 import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
@@ -51,7 +58,11 @@ import {
   runOperationJsonQuery,
   toPrologAtom,
 } from "./prolog-json.js";
-import type { OperationContext, PrologPort } from "./runtime-types.js";
+import type {
+  CapabilityRegistry,
+  OperationContext,
+  PrologPort,
+} from "./runtime-types.js";
 import type { OperationResult } from "./types.js";
 import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
 
@@ -176,6 +187,7 @@ export type SearchInput = {
   readonly minScore?: number;
   readonly fields?: "summary" | "full";
   readonly answer?: boolean;
+  readonly hints?: boolean;
 };
 
 export type SearchPayload = {
@@ -185,7 +197,9 @@ export type SearchPayload = {
   /** Rows in `results`: the page this call returned. */
   readonly returned: number;
   readonly truncated?: boolean;
-  readonly queryAnalysis?: IntentSearchAnalysis;
+  readonly queryAnalysis?: IntentSearchAnalysis & {
+    readonly hints?: SearchHintsAnalysis;
+  };
   readonly answer?: SearchAnswer;
   /** The Kibi branch whose store was searched, when the runtime attached one. */
   readonly branch?: string | null;
@@ -912,6 +926,51 @@ function questionPathHint(
     : ` The question names ${list}; their words were left out of the topic. Pass them as sourceLocations to also see the requirements linked to those files.`;
 }
 
+/**
+ * Hints from the workspace's kibi.search-hints.v1 provider. A host without a
+ * plugin runtime, or a registry that fails to load, gives no hints rather than
+ * failing the search.
+ */
+// implements REQ-kibi-search-hints-host
+async function searchHintsFor(
+  context: OperationContext,
+  options: Omit<
+    Parameters<typeof buildSearchHints>[0],
+    "resolution" | "workspaceRoot"
+  >,
+): Promise<SearchHintsAnalysis | undefined> {
+  if (!context.ensurePlugins) return undefined;
+  let resolution: Awaited<ReturnType<CapabilityRegistry["resolveSearchHints"]>>;
+  try {
+    resolution = await (await context.ensurePlugins()).resolveSearchHints();
+  } catch (error) {
+    // A configured provider that cannot load is reported, not thrown: the
+    // lexical answer stands on its own.
+    const trigger = searchHintsTrigger(options.analysis);
+    return trigger === null
+      ? undefined
+      : {
+          trigger,
+          provider: null,
+          items: [],
+          diagnostics: [
+            {
+              pluginId: "unresolved",
+              packageName: null,
+              mode: "replace",
+              code: "provider_unavailable",
+              message: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        };
+  }
+  return buildSearchHints({
+    ...options,
+    resolution,
+    workspaceRoot: context.workspaceRoot,
+  });
+}
+
 export async function executeSearch(
   input: SearchInput,
   context: OperationContext,
@@ -928,6 +987,7 @@ export async function executeSearch(
     minScore,
     fields = "summary",
     answer,
+    hints: hintsWanted = true,
   } = input;
   const trimmedQuery = query.trim();
   if (!trimmedQuery) {
@@ -960,10 +1020,19 @@ export async function executeSearch(
         ...(minScore !== undefined ? { minScore } : {}),
       } as const;
       validateIntentSearchInput(intentInput);
+      let corpus:
+        | {
+            entities: readonly Record<string, unknown>[];
+            bodies: MarkdownBodyCache;
+          }
+        | undefined;
       const intentResult = await executeIntentSearch(
         intentInput,
         prolog,
         context.workspaceRoot,
+        (entities, bodies) => {
+          corpus = { entities, bodies };
+        },
       );
       const paginated = paginateResults(intentResult.matches, limit, offset);
       // The answer layer summarizes the whole ranking, so it belongs to the
@@ -982,6 +1051,22 @@ export async function executeSearch(
       const topUngoverned = answerLayer?.ungoverned.find(
         (entry) => entry.rank === 1,
       );
+      // Hints come after the lexical answer and never change it; a strong
+      // answer never reaches a provider.
+      const hints =
+        hintsWanted &&
+        offset === 0 &&
+        corpus !== undefined &&
+        searchHintsTrigger(intentResult.analysis) !== null
+          ? await searchHintsFor(context, {
+              query: trimmedQuery,
+              analysis: intentResult.analysis,
+              entities: corpus.entities,
+              bodies: corpus.bodies,
+              governingIds: (answerLayer?.governing ?? []).map((req) => req.id),
+              prolog,
+            })
+          : undefined;
       const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained). No entity shares enough of the question's words: ask again in the words and language the KB is written in, or pass sourceLocations.`
@@ -991,7 +1076,7 @@ export async function executeSearch(
               .join(
                 ", ",
               )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}${topUngoverned ? ` (the top match ${topUngoverned.id} is linked to no requirement)` : ""}.`
-      }${questionPathHint(trimmedQuery, sourceLocations)}${CONTRADICTION_QUESTION.test(trimmedQuery) ? CONTRADICTION_HINT : ""}${storeNote}`;
+      }${searchHintsNote(hints)}${questionPathHint(trimmedQuery, sourceLocations)}${CONTRADICTION_QUESTION.test(trimmedQuery) ? CONTRADICTION_HINT : ""}${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
@@ -999,7 +1084,10 @@ export async function executeSearch(
           count: intentResult.matches.length,
           returned: paginated.length,
           truncated: offset + paginated.length < intentResult.matches.length,
-          queryAnalysis: intentResult.analysis,
+          queryAnalysis:
+            hints !== undefined
+              ? { ...intentResult.analysis, hints }
+              : intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
           ...branchFields,
         },

package/src/public/operations/evidence-floor.ts

@@ -60,6 +60,13 @@ export type EvidenceFloorOptions = Readonly<{
    * `kibi prove --all`.
    */
   freshEvidence?: boolean;
+  /**
+   * The instant and workspace snapshot the whole check judges receipts at,
+   * so the floor reads the same requirement proofs the coverage evidence
+   * read instead of computing them again.
+   */
+  checkedAt?: string;
+  snapshotEvidence?: Awaited<ReturnType<typeof readWorkspaceSnapshot>>;
 }>;
 
 function floorSource(row: EvidenceFloorRow): string {
@@ -145,6 +152,7 @@ export function evidenceFloorViolations(
 export async function readEvidenceFloorRows(
   context: OperationContext,
   snapshotEvidence?: Awaited<ReturnType<typeof readWorkspaceSnapshot>>,
+  checkedAt: string = context.clock().toISOString(),
 ): Promise<readonly EvidenceFloorRow[]> {
   const prolog = context.prolog ?? (await context.ensureProlog?.());
   if (prolog === undefined) return [];
@@ -152,7 +160,6 @@ export async function readEvidenceFloorRows(
   const snapshot = evidence.available ? evidence.snapshot.hash : "unknown";
   const { perContractTestBindings } = await import("./specs/reporting.js");
   const bindings = await perContractTestBindings({ ...context, prolog });
-  const checkedAt = context.clock().toISOString();
   const goal = `discovery:evidence_floor_json(${bindings === null ? "strict_snapshot, _{}" : `per_contract, ${bindings}`}, ${toPrologAtom(snapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
   const payload = await runOperationJsonQuery<EvidenceFloorPayload>(
     prolog,
@@ -182,8 +189,13 @@ export async function collectEvidenceFloorViolations(
     schemaVersion < EVIDENCE_FLOOR_SCHEMA_VERSION
   )
     return [];
-  const snapshotEvidence = await readWorkspaceSnapshot(context);
-  const rows = await readEvidenceFloorRows(context, snapshotEvidence);
+  const snapshotEvidence =
+    options.snapshotEvidence ?? (await readWorkspaceSnapshot(context));
+  const rows = await readEvidenceFloorRows(
+    context,
+    snapshotEvidence,
+    options.checkedAt,
+  );
   const violations = evidenceFloorViolations(rows, options);
   if (options.freshEvidence === true) {
     const clean =

package/src/public/operations/migration-plan.ts

@@ -169,20 +169,46 @@ function dependencyOrder(
       new Set(action.dependsOn.filter((dependency) => byId.has(dependency))),
     ]),
   );
+  // Dependents of each action in action order, so an emitted action frees
+  // its dependents in the order a scan over every action would.
+  const dependents = new Map<string, string[]>();
+  for (const action of actions) {
+    for (const dependency of remaining.get(action.id) as Set<string>) {
+      const list = dependents.get(dependency);
+      if (list === undefined) dependents.set(dependency, [action.id]);
+      else list.push(action.id);
+    }
+  }
   const ordered: MigrationAction[] = [];
   const ready = actions
     .filter((action) => (remaining.get(action.id)?.size ?? 0) === 0)
     .sort(actionSort)
     .map((action) => action.id);
   const queued = new Set(ready);
-  while (ready.length > 0) {
-    const id = ready.shift();
-    if (id === undefined) break;
+  const compareReady = (left: string, right: string): number =>
+    compareReadyActionIds(left, right, byId);
+  // `ready` stays sorted; a freed action is inserted after its equals, where
+  // a stable sort of the pushed list would have put it.
+  const enqueue = (id: string, head: number): void => {
+    let low = head;
+    let high = ready.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if (compareReady(ready[middle] as string, id) <= 0) low = middle + 1;
+      else high = middle;
+    }
+    ready.splice(low, 0, id);
+  };
+  let head = 0;
+  while (head < ready.length) {
+    const id = ready[head] as string;
+    head += 1;
     queued.delete(id);
-    const action = byId.get(id);
-    if (action === undefined) continue;
+    // Only ids of `actions` are ever queued or listed as dependents.
+    const action = byId.get(id) as MigrationAction;
     ordered.push(action);
-    for (const [candidateId, dependencies] of remaining) {
+    for (const candidateId of dependents.get(id) ?? []) {
+      const dependencies = remaining.get(candidateId) as Set<string>;
       if (
         !dependencies.delete(id) ||
         dependencies.size !== 0 ||
@@ -190,9 +216,8 @@ function dependencyOrder(
       ) {
         continue;
       }
-      ready.push(candidateId);
       queued.add(candidateId);
-      ready.sort((left, right) => compareReadyActionIds(left, right, byId));
+      enqueue(candidateId, head);
     }
   }
   // Preserve cyclic/missing-dependency actions in canonical order; validation will block them.
@@ -228,7 +253,14 @@ function summarize(actions: readonly MigrationAction[]) {
 
 // implements REQ-agent-guided-migration-orchestration
 export function buildMigrationPlan(input: PlanInput = {}): MigrationPlan {
-  const actions = dependencyOrder([...(input.actions ?? [])].sort(actionSort));
+  // An id names one action, as in a merged plan: a later definition of the
+  // same id replaces the earlier one instead of being ordered twice.
+  const uniqueActions = [
+    ...new Map(
+      (input.actions ?? []).map((action) => [action.id, action]),
+    ).values(),
+  ];
+  const actions = dependencyOrder(uniqueActions.sort(actionSort));
   const evaluatedDomains = uniqueSorted(input.evaluatedDomains);
   const incompleteDomains = uniqueSorted(input.incompleteDomains);
   const expected = {

package/src/public/operations/node-ports.ts

@@ -118,11 +118,13 @@ async function workspaceSnapshot(workspaceRoot: string) {
     );
   const digest = createHash("sha256");
   digest.update("kibi.workspace-snapshot.v2\0");
+  // Synchronous reads: one awaited read per file paid a file-handle round
+  // trip each, about eight times the time of reading the same files directly.
   for (const { raw, key: relativePath } of paths) {
     digest.update(relativePath);
     digest.update("\0");
     try {
-      const content = await fs.readFile(path.join(workspaceRoot, raw));
+      const content = fsSync.readFileSync(path.join(workspaceRoot, raw));
       digest.update(snapshotFileContent(relativePath, content));
     } catch (error) {
       const code =

package/src/public/operations/repair-plan.ts

@@ -110,6 +110,40 @@ const REPAIR_PHASES = {
     validationRules: ["must-priority-coverage", "no-dangling-refs"],
     writePolicy: "sequential_upsert",
   },
+  dimension_grounding: {
+    order: 64,
+    objective:
+      "Ground each quantified claim (each, every, all, or a cardinality bound) on what varies: an integer count or bound, a set of members, a rule over a variable, or a state machine. If the quantifier ranges over nothing, record a dimension_waiver on the grounding fact for a person to approve, and record their approval in the same pull request.",
+    workflowSteps: [
+      "kb_model_requirement",
+      "kb_validate_upsert",
+      "kb_upsert",
+      "kb_check",
+    ],
+    validationRules: ["no-dangling-refs"],
+    writePolicy: "sequential_upsert",
+  },
+  case_scenarios: {
+    order: 66,
+    objective:
+      "Cover each uncovered rejection case: add a scenario whose assumes fact states the case's assumption (a value past the bound, a value outside the set), expects rejection or error, is linked with specified_by and is verified by a passing end-to-end test. Each repair lists caseSkeletons, upsert-ready draft scenarios and their assumed facts: fill in the placeholders, verify the scenario by a test, then set its status to active (a draft never covers a case). If a person accepts the cases as covered another way, record a case_waiver on the grounding fact for them to approve, and record their approval in the same pull request.",
+    workflowSteps: [
+      "kb_coverage",
+      "kb_validate_upsert",
+      "kb_upsert",
+      "kb_check",
+    ],
+    validationRules: ["scenario-outcome-mismatch", "no-dangling-refs"],
+    writePolicy: "sequential_upsert",
+  },
+  negative_scenarios: {
+    order: 65,
+    objective:
+      "Add a scenario that expects rejection or error and assumes a value the requirement forbids (see suggestedNegatives), link it with specified_by and verify it with a passing end-to-end test.",
+    workflowSteps: ["kb_query", "kb_validate_upsert", "kb_upsert", "kb_check"],
+    validationRules: ["scenario-outcome-mismatch", "no-dangling-refs"],
+    writePolicy: "sequential_upsert",
+  },
   scenario_tests: {
     order: 70,
     objective:
@@ -206,6 +240,9 @@ const GAP_PHASE: Readonly<Record<string, RepairPhase>> = {
   missing_scenario: "scenario_endpoints",
   infeasible_scenario: "scenario_endpoints",
   unknown_scenario_feasibility: "scenario_endpoints",
+  dimension_unrepresented: "dimension_grounding",
+  happy_path_only: "negative_scenarios",
+  uncovered_case: "case_scenarios",
   missing_scenario_test: "scenario_tests",
   proof_snapshot_unavailable: "snapshot_runtime",
   missing_passing_e2e: "proof_evidence",
@@ -235,6 +272,9 @@ const GAP_STAGE: Readonly<Record<string, string>> = {
   missing_scenario: "scenarios",
   infeasible_scenario: "scenarios",
   unknown_scenario_feasibility: "scenarios",
+  dimension_unrepresented: "dimension",
+  happy_path_only: "negative_path",
+  uncovered_case: "cases",
   missing_scenario_test: "scenario_tests",
   missing_passing_e2e: "passing_e2e",
   missing_proof_receipt: "passing_e2e",
@@ -255,6 +295,9 @@ const PROOF_STAGE_KEY: Readonly<Record<string, string>> = {
   contradictions: "contradictions",
   scenarios: "scenarios",
   scenario_tests: "scenarioTests",
+  negative_path: "negativePath",
+  dimension: "dimension",
+  cases: "cases",
   passing_e2e: "passingE2e",
   executable_symbols: "executableSymbols",
   production_symbols: "productionSymbols",
@@ -268,6 +311,34 @@ export type RepairPlanRepair = {
   readonly proofStage: string;
   readonly action: string;
   readonly evidence: Readonly<Record<string, unknown>>;
+  /** Draft scenarios for an uncovered_case repair, one per uncovered case. */
+  readonly caseSkeletons?: readonly CaseSkeleton[];
+};
+
+type SkeletonEntity = {
+  readonly type: "fact" | "scenario";
+  readonly id: string;
+  readonly properties: Readonly<Record<string, unknown>>;
+  readonly relationships: readonly {
+    readonly type: string;
+    readonly from: string;
+    readonly to: string;
+  }[];
+};
+
+// implements REQ-kibi-case-coverage
+/**
+ * An upsert-ready draft scenario for one uncovered case: the fact it assumes
+ * (the case's value class) and the scenario that expects the predicted
+ * outcome. Drafts never count as coverage, so writing one changes no gap
+ * until it is verified and made active. placeholder is true when the value
+ * must be chosen by the author (a value outside a set).
+ */
+export type CaseSkeleton = {
+  readonly caseId: string;
+  readonly constraint: string;
+  readonly placeholder: boolean;
+  readonly entities: readonly [SkeletonEntity, SkeletonEntity];
 };
 
 export type RepairPlanBatch = {
@@ -379,6 +450,82 @@ function stageEvidence(
   return isRecord(stable) ? stable : {};
 }
 
+const VALUE_FIELD: Readonly<Record<string, string>> = {
+  int: "value_int",
+  number: "value_number",
+  set: "value_set",
+  string: "value_string",
+};
+
+function caseSkeleton(
+  requirementId: string,
+  row: Readonly<Record<string, unknown>>,
+): CaseSkeleton | undefined {
+  const caseId = typeof row.caseId === "string" ? row.caseId : undefined;
+  const assumption = isRecord(row.assumption) ? row.assumption : undefined;
+  const valueType =
+    typeof assumption?.value_type === "string" ? assumption.value_type : "";
+  const valueField = VALUE_FIELD[valueType];
+  if (caseId === undefined || assumption === undefined || !valueField)
+    return undefined;
+  const constraint = typeof row.constraint === "string" ? row.constraint : "";
+  const property =
+    typeof assumption.property_key === "string" ? assumption.property_key : "";
+  const expects = row.predicted === "rejection" ? "rejection" : "success";
+  const placeholder = JSON.stringify(assumption.value).includes("<");
+  const suffix = caseId.replace(/^CASE-/, "");
+  const factId = `FACT-CASE-${suffix}`;
+  const scenarioId = `SCEN-CASE-${suffix}`;
+  return {
+    caseId,
+    constraint,
+    placeholder,
+    entities: [
+      {
+        type: "fact",
+        id: factId,
+        properties: {
+          title: `${property} ${constraint}`,
+          status: "active",
+          fact_kind: "property_value",
+          subject_key: assumption.subject_key,
+          property_key: property,
+          operator: assumption.operator,
+          value_type: valueType,
+          [valueField]: assumption.value,
+        },
+        relationships: [],
+      },
+      {
+        type: "scenario",
+        id: scenarioId,
+        properties: {
+          title: `${property} ${constraint} is ${expects === "rejection" ? "refused" : "accepted"}`,
+          status: "draft",
+          expects,
+        },
+        relationships: [
+          { type: "assumes", from: scenarioId, to: factId },
+          { type: "specified_by", from: requirementId, to: scenarioId },
+        ],
+      },
+    ],
+  };
+}
+
+function caseSkeletons(
+  requirementId: string,
+  evidence: Readonly<Record<string, unknown>>,
+): CaseSkeleton[] {
+  const rows = Array.isArray(evidence.uncoveredCases)
+    ? evidence.uncoveredCases.filter(isRecord)
+    : [];
+  return rows.flatMap((row) => {
+    const skeleton = caseSkeleton(requirementId, row);
+    return skeleton === undefined ? [] : [skeleton];
+  });
+}
+
 function batchId(requirementId: string, phase: RepairPhase): string {
   const order = String(REPAIR_PHASES[phase].order).padStart(3, "0");
   const safeRequirementId = requirementId.replace(/[^A-Za-z0-9_-]/g, "-");
@@ -408,6 +555,7 @@ function buildRequirementBatches(
       typeof sourceRepair?.stage === "string"
         ? sourceRepair.stage
         : (GAP_STAGE[gap] ?? "manual_review");
+    const evidence = stageEvidence(row, proofStage);
     const repair: RepairPlanRepair = {
       requirementId,
       gap,
@@ -417,7 +565,10 @@ function buildRequirementBatches(
       ),
       proofStage,
       action: actionForRepair(sourceRepair, phase),
-      evidence: stageEvidence(row, proofStage),
+      evidence,
+      ...(gap === "uncovered_case"
+        ? { caseSkeletons: caseSkeletons(requirementId, evidence) }
+        : {}),
     };
     const phaseRepairs = byPhase.get(phase) ?? [];
     phaseRepairs.push(repair);

package/src/public/operations/schema6-check-actions.ts

@@ -728,7 +728,7 @@ export function schema6ReviewActionsFromCheck(
       safety: "review",
       invocation: {
         kind: "review",
-        instruction: `${total} agent-authored requirement(s) have no human approval${total > listed.length ? `; these ${listed.length} come first` : ""}: ${listed.join(", ")}. Have a person read each one; when it states the intended behavior, kb_upsert it with origin.approved_by set to the reviewer (keep kind: agent and the rest of origin). Rerun kb_check for the next page.`,
+        instruction: `${total} agent-authored requirement(s) have no human approval${total > listed.length ? `; these ${listed.length} come first` : ""}: ${listed.join(", ")}. Have a person read each one; when it states the intended behavior, kb_upsert it with origin.approved_by set to the reviewer (keep kind: agent and the rest of origin), in the same change and pull request as the requirement, not a separate one. Rerun kb_check for the next page.`,
       },
       affectedEntityIds: listed,
       affectedFiles: [...new Set(agentRequirementFiles)].sort(),