kibi-cli 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -107,6 +107,10 @@
       "default": "./dist/public/skills.js"
     },
     "./operations": "./dist/public/operations/index.js",
+    "./logic/ir": {
+      "types": "./dist/logic/ir.d.ts",
+      "default": "./dist/logic/ir.js"
+    },
     "./operations/mutation/relationships": {
       "types": "./dist/operations/mutation/relationships.d.ts",
       "default": "./dist/operations/mutation/relationships.js"
@@ -157,7 +161,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.7.1",
+    "kibi-core": "^0.8.0",
     "ts-morph": "^23.0.0",
     "ignore": "^5.3.0"
   },

package/src/public/operations/index.ts

@@ -17,3 +17,4 @@ export * from "./types.js";
 export * from "../../operations/autopilot/generate.js";
 export * from "../../operations/autopilot/presentation.js";
 export type * from "../../operations/autopilot/types.js";
+export * from "../../logic/ir.js";

package/src/public/operations/specs/check.ts

@@ -26,11 +26,14 @@ export const checkSpec = {
             "strict-req-fact-pairing",
             "predicate-verifiability",
             "logic-coverage",
+            "rule-safety",
+            "rule-verifiability",
+            "semantic-completeness",
             "query-plan-safety",
           ],
         },
         description:
-          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
+          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, rule-safety, rule-verifiability, semantic-completeness, query-plan-safety. If omitted, server runs all rules plus the full-KB qualityDiagnostics audit scan; if supplied, server preserves scoped validation and skips the full-KB advisory scan.",
       },
       sourceFiles: {
         type: "array",

package/src/public/operations/specs/modeling.ts

@@ -75,6 +75,26 @@ export const modelRequirementSpec = {
         description:
           "Existing requirement logic_claims values. The returned requirement update merges the new atomic claim key into this manifest instead of replacing prior claims.",
       },
+      requirementId: {
+        type: "string",
+        description:
+          "Optional existing requirement ID to receive the requires_rule relationship.",
+      },
+      claimKey: {
+        type: "string",
+        description:
+          "Optional advisor-issued claim key for the exact proposition represented by logic.",
+      },
+      claimText: {
+        type: "string",
+        description:
+          "Optional exact proposition text represented by logic; defaults to text.",
+      },
+      logic: {
+        type: "object",
+        description:
+          "Optional typed kibi.logic.v1 IR. Kibi validates and canonicalizes it into a rule fact; raw Prolog is rejected.",
+      },
     },
   },
   requiresProlog: true,

package/src/public/operations/specs/mutation-schemas.ts

@@ -125,6 +125,8 @@ export const ENTITY_PROPERTIES_SCHEMA = {
         "meta",
         "predicate_schema",
         "predicate",
+        "rule_schema",
+        "rule",
       ],
       description:
         "Optional fact lane kind for fact entities. Strict lane uses 'subject' and 'property_value'; context lane uses 'observation' or 'meta'; ontology lane uses 'predicate_schema' or 'predicate'. Use kb_model_requirement or kb_suggest_predicates when starting from prose.",
@@ -246,6 +248,33 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       items: { type: "string" },
       description: "Optional ground-term examples for a predicate schema.",
     },
+    semantic_inventory: {
+      type: "array",
+      description:
+        "Requirement proposition ledger returned by kb_semantic_advisor; preserve entries while modeling each assertive span.",
+      items: { type: "object" },
+    },
+    rule_ir: {
+      type: "object",
+      description:
+        "Schema-validated kibi.logic.v1 rule IR. It is persisted as data and never executed as caller-supplied Prolog.",
+    },
+    rule_hash: {
+      type: "string",
+      description: "Deterministic hash of canonical rule_ir.",
+    },
+    rule_schema_id: {
+      type: "string",
+      description: "Rule schema fact ID used to validate this rule.",
+    },
+    rule_name: { type: "string", description: "Stable rule schema name." },
+    semantic_key: {
+      type: "string",
+      description:
+        "Canonical semantic identity of the normalized logical model.",
+    },
+    claim_span_start: { type: "integer", minimum: 0 },
+    claim_span_end: { type: "integer", minimum: 0 },
   },
   allOf: [CLAIM_PROVENANCE_CONDITIONAL],
   required: ["title", "status"],
@@ -273,6 +302,7 @@ export const RELATIONSHIPS_SCHEMA = {
           "constrains",
           "requires_property",
           "requires_predicate",
+          "requires_rule",
           "guards",
           "publishes",
           "consumes",

package/src/public/operations/specs/semantic.ts

@@ -43,6 +43,9 @@ export async function executeSemanticAdvisor(
       },
     },
     ...(args.clauses !== undefined ? { clauses: args.clauses } : {}),
+    ...(args.interpretations !== undefined
+      ? { interpretations: args.interpretations }
+      : {}),
   });
   return {
     content: [
@@ -69,6 +72,15 @@ async function executeSemanticAdvisorInput(
         (value): value is string => typeof value === "string",
       )
     : undefined;
+  const interpretations = Array.isArray(input.interpretations)
+    ? input.interpretations.filter(
+        (
+          value,
+        ): value is NonNullable<
+          SemanticAdvisorArgs["interpretations"]
+        >[number] => typeof value === "object" && value !== null,
+      )
+    : undefined;
   return executeSemanticAdvisor(
     {
       text: requiredText(input.text),
@@ -78,6 +90,7 @@ async function executeSemanticAdvisorInput(
       ...(source ? { source } : {}),
       ...(status ? { status } : {}),
       ...(clauses !== undefined ? { clauses } : {}),
+      ...(interpretations !== undefined ? { interpretations } : {}),
     },
     context,
   );
@@ -103,12 +116,38 @@ export const semanticAdvisorSpec = {
         description:
           "Optional complete list of atomic requirement clauses supplied by the caller. Use this for compound prose so every normative clause receives a stable claim key and independent grounding review.",
       },
+      interpretations: {
+        type: "array",
+        maxItems: 3,
+        description:
+          "Optional host-LLM typed kibi.logic.v1 interpretations. Kibi validates and canonicalizes them; raw Prolog is not accepted.",
+        items: {
+          type: "object",
+          required: ["claim_key", "claim_text", "ir"],
+          properties: {
+            claim_key: { type: "string" },
+            claim_text: { type: "string" },
+            confidence: { type: "number", minimum: 0, maximum: 1 },
+            span: { type: "object" },
+            ir: { type: "object" },
+          },
+        },
+      },
       type: {
         type: "string",
-        enum: ["req"],
+        enum: [
+          "req",
+          "scenario",
+          "test",
+          "adr",
+          "flag",
+          "event",
+          "symbol",
+          "fact",
+        ],
         default: "req",
         description:
-          "Entity type context for analysis. Currently requirement prose is supported.",
+          "Entity type context for analysis. Requirement, domain-fact, and supporting prose all receive a proposition ledger; only requirements receive deterministic modeling suggestions.",
       },
       id: {
         type: "string",

package/src/public/schemas/entity.ts

@@ -25,7 +25,9 @@ type FactKind =
   | "observation"
   | "meta"
   | "predicate_schema"
-  | "predicate";
+  | "predicate"
+  | "rule_schema"
+  | "rule";
 type Operator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
 type ValueType = "string" | "int" | "number" | "bool";
 type Polarity = "require" | "forbid" | "assert" | "deny";
@@ -74,6 +76,30 @@ const factConditionals = JSON.parse(`[
       }
     }
   },
+  {
+    "if": {
+      "properties": {
+        "type": { "const": "fact" },
+        "fact_kind": { "const": "rule_schema" }
+      },
+      "required": ["type", "fact_kind"]
+    },
+    "then": {
+      "required": ["rule_name", "argument_names", "argument_types"]
+    }
+  },
+  {
+    "if": {
+      "properties": {
+        "type": { "const": "fact" },
+        "fact_kind": { "const": "rule" }
+      },
+      "required": ["type", "fact_kind"]
+    },
+    "then": {
+      "required": ["rule_ir", "rule_hash", "rule_schema_id", "rule_name", "semantic_key"]
+    }
+  },
   {
     "if": {
       "properties": {
@@ -90,10 +116,209 @@ const factConditionals = JSON.parse(`[
   }
 ]`) as Array<Record<string, unknown>>;
 
+// The persisted rule payload is still data, but its shape is constrained at
+// the JSON boundary as well as by validateLogicIr.  Keeping this vocabulary
+// closed prevents a raw_goal/raw Prolog field from entering an upsert payload.
+const logicTermSchema = {
+  oneOf: [
+    {
+      type: "object",
+      required: ["kind", "name", "type"],
+      properties: {
+        kind: { const: "var" },
+        name: { type: "string", pattern: "^[A-Z][A-Za-z0-9_]*$" },
+        type: { type: "string", pattern: "^[a-z][a-z0-9_:.\\/-]*$" },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "value"],
+      properties: {
+        kind: { const: "const" },
+        value: { type: "string", minLength: 1 },
+        type: { type: "string", pattern: "^[a-z][a-z0-9_:.\\/-]*$" },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "value"],
+      properties: {
+        kind: { const: "number" },
+        value: { type: "number" },
+        unit: { type: "string", pattern: "^[a-z][a-z0-9_:.\\/-]*$" },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "value", "unit"],
+      properties: {
+        kind: { const: "duration" },
+        value: { type: "number", minimum: 0 },
+        unit: { type: "string", enum: ["ms", "s", "m", "h", "d", "w"] },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "value"],
+      properties: {
+        kind: { const: "timestamp" },
+        value: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "start", "end"],
+      properties: {
+        kind: { const: "interval" },
+        start: { type: "string" },
+        end: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  ],
+};
+
+const logicAtomSchema = {
+  type: "object",
+  required: ["kind", "name", "args"],
+  properties: {
+    kind: { const: "atom" },
+    namespace: { type: "string", pattern: "^[a-z][a-z0-9_:.\\/-]*$" },
+    name: { type: "string", pattern: "^[a-z][a-z0-9_:.\\/-]*$" },
+    args: {
+      type: "array",
+      maxItems: 8,
+      items: { $ref: "#/$defs/logicTerm" },
+    },
+    polarity: { enum: ["positive", "negative"] },
+    closedWorld: { type: "boolean" },
+  },
+  additionalProperties: false,
+};
+
+const logicExpressionSchema = {
+  oneOf: [
+    { $ref: "#/$defs/logicAtom" },
+    {
+      type: "object",
+      required: ["kind", "items"],
+      properties: {
+        kind: { enum: ["all", "any"] },
+        items: {
+          type: "array",
+          minItems: 1,
+          maxItems: 32,
+          items: { $ref: "#/$defs/logicExpression" },
+        },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "item"],
+      properties: {
+        kind: { const: "not" },
+        item: { $ref: "#/$defs/logicAtom" },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "operator", "left", "right"],
+      properties: {
+        kind: { const: "compare" },
+        operator: { enum: ["eq", "neq", "lt", "lte", "gt", "gte"] },
+        left: { $ref: "#/$defs/logicTerm" },
+        right: { $ref: "#/$defs/logicTerm" },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "atom", "operator", "value"],
+      properties: {
+        kind: { const: "count" },
+        atom: { $ref: "#/$defs/logicAtom" },
+        operator: { enum: ["eq", "neq", "lt", "lte", "gt", "gte"] },
+        value: { type: "integer", minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind", "relation", "left", "right"],
+      properties: {
+        kind: { const: "temporal" },
+        relation: {
+          enum: ["before", "after", "during", "overlaps", "starts", "finishes"],
+        },
+        left: { $ref: "#/$defs/logicTerm" },
+        right: { $ref: "#/$defs/logicTerm" },
+      },
+      additionalProperties: false,
+    },
+  ],
+};
+
+const logicRuleSchema = {
+  type: "object",
+  required: ["version", "kind", "modality"],
+  properties: {
+    version: { const: "kibi.logic.v1" },
+    kind: { enum: ["atom", "rule", "constraint"] },
+    modality: { enum: ["assert", "deny", "oblige", "permit", "forbid"] },
+    head: { $ref: "#/$defs/logicAtom" },
+    body: { $ref: "#/$defs/logicExpression" },
+    variables: {
+      type: "array",
+      maxItems: 32,
+      items: {
+        type: "object",
+        required: ["name", "type"],
+        properties: {
+          name: { type: "string", pattern: "^[A-Z][A-Za-z0-9_]*$" },
+          type: { type: "string", pattern: "^[a-z][a-z0-9_:.\\/-]*$" },
+          quantifier: { enum: ["forall", "exists"] },
+        },
+        additionalProperties: false,
+      },
+    },
+    exceptions: {
+      type: "array",
+      maxItems: 16,
+      items: { $ref: "#/$defs/logicExpression" },
+    },
+    scope: {
+      type: "object",
+      properties: {
+        authority: { type: "string" },
+        name: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+      },
+      additionalProperties: false,
+    },
+    validFrom: { type: "string" },
+    validTo: { type: "string" },
+    ruleSchemaId: { type: "string", minLength: 1 },
+  },
+  additionalProperties: false,
+};
+
 const entitySchema: Record<string, unknown> = {
   $id: "entity.schema.json",
   title: "Entity",
   type: "object",
+  $defs: {
+    logicTerm: logicTermSchema,
+    logicAtom: logicAtomSchema,
+    logicExpression: logicExpressionSchema,
+    logicRule: logicRuleSchema,
+  },
   properties: {
     id: { type: "string" },
     title: { type: "string" },
@@ -136,6 +361,53 @@ const entitySchema: Record<string, unknown> = {
       uniqueItems: true,
       items: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
     },
+    semantic_inventory: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["claim_key", "claim_text", "role", "status", "span"],
+        properties: {
+          claim_key: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+          claim_text: { type: "string", minLength: 1 },
+          role: {
+            type: "string",
+            enum: [
+              "normative",
+              "definition",
+              "descriptive",
+              "condition",
+              "exception",
+              "rationale",
+              "example",
+              "subjective",
+            ],
+          },
+          status: {
+            type: "string",
+            enum: [
+              "modeled",
+              "ambiguous",
+              "ontology_gap",
+              "nonlogical",
+              "missing",
+            ],
+          },
+          span: {
+            type: "object",
+            required: ["start", "end"],
+            properties: {
+              start: { type: "integer", minimum: 0 },
+              end: { type: "integer", minimum: 0 },
+            },
+            additionalProperties: false,
+          },
+          semantic_key: { type: "string" },
+          payload_hash: { type: "string" },
+          reason: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+    },
     sourceFile: { type: "string" },
     granularity_reason: {
       type: "string",
@@ -181,6 +453,8 @@ const entitySchema: Record<string, unknown> = {
         "meta",
         "predicate_schema",
         "predicate",
+        "rule_schema",
+        "rule",
       ] satisfies FactKind[],
     },
     subject_key: { type: "string" },
@@ -212,6 +486,13 @@ const entitySchema: Record<string, unknown> = {
     aliases: { type: "array", items: { type: "string" } },
     examples: { type: "array", items: { type: "string" } },
     predicate_args: { type: "array", items: { type: "string" } },
+    rule_ir: { $ref: "#/$defs/logicRule" },
+    rule_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
+    rule_schema_id: { type: "string", minLength: 1 },
+    rule_name: { type: "string", minLength: 1 },
+    semantic_key: { type: "string", pattern: "^SEM-[A-F0-9]{24}$" },
+    claim_span_start: { type: "integer", minimum: 0 },
+    claim_span_end: { type: "integer", minimum: 0 },
   },
   required: [
     "id",
@@ -268,6 +549,13 @@ const entitySchema: Record<string, unknown> = {
             { required: ["aliases"] },
             { required: ["examples"] },
             { required: ["predicate_args"] },
+            { required: ["rule_ir"] },
+            { required: ["rule_hash"] },
+            { required: ["rule_schema_id"] },
+            { required: ["rule_name"] },
+            { required: ["semantic_key"] },
+            { required: ["claim_span_start"] },
+            { required: ["claim_span_end"] },
           ],
         },
       },
@@ -285,6 +573,14 @@ const entitySchema: Record<string, unknown> = {
         },
       },
     },
+    {
+      if: {
+        properties: { type: { const: "req" } },
+      },
+      else: {
+        not: { required: ["semantic_inventory"] },
+      },
+    },
     ...factConditionals,
   ],
   additionalProperties: false,

package/src/public/schemas/relationship.ts

@@ -35,6 +35,7 @@ const relationshipSchema = {
         "constrains",
         "requires_property",
         "requires_predicate",
+        "requires_rule",
         "guards",
         "publishes",
         "consumes",