kibi-cli 0.14.0 → 0.17.0

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

@@ -0,0 +1,149 @@
+import type { OperationContext } from "../runtime-types.js";
+import type { OperationResult, OperationSpec } from "../types.js";
+
+// implements REQ-kibi-operation-interface-parity
+export type SparqlRemoteInput = {
+  readonly endpoint: string;
+  readonly query: string;
+  readonly timeoutMs?: number;
+};
+
+// implements REQ-kibi-operation-interface-parity
+export type SparqlRemoteOutput = {
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+};
+
+function validateInput(input: SparqlRemoteInput): URL {
+  if (typeof input.endpoint !== "string" || input.endpoint.trim() === "") {
+    throw new Error("SPARQL endpoint is required");
+  }
+  if (typeof input.query !== "string" || input.query.trim() === "") {
+    throw new Error("SPARQL query is required");
+  }
+  let endpoint: URL;
+  try {
+    endpoint = new URL(input.endpoint);
+  } catch {
+    throw new Error("SPARQL endpoint must be an http:// or https:// URL");
+  }
+  if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+    throw new Error("SPARQL endpoint must be an http:// or https:// URL");
+  }
+  if (!/^\s*select\b/i.test(input.query)) {
+    throw new Error("SPARQL query must be a SELECT query");
+  }
+  if (
+    input.timeoutMs !== undefined &&
+    (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
+  ) {
+    throw new Error("SPARQL timeoutMs must be a positive number when provided");
+  }
+  return endpoint;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function decodeRows(payload: unknown): SparqlRemoteOutput {
+  if (!isRecord(payload) || !isRecord(payload.results)) {
+    throw new Error("SPARQL endpoint returned an invalid result document");
+  }
+  const bindings = payload.results.bindings;
+  if (!Array.isArray(bindings)) {
+    throw new Error("SPARQL endpoint returned an invalid bindings array");
+  }
+  const rows = bindings.map((binding) => {
+    if (!isRecord(binding)) {
+      throw new Error("SPARQL endpoint returned an invalid binding");
+    }
+    const row: Record<string, unknown> = {};
+    for (const [variable, term] of Object.entries(binding)) {
+      if (!isRecord(term) || typeof term.value !== "string") {
+        throw new Error(`SPARQL endpoint returned an invalid ${variable} term`);
+      }
+      row[variable] = term.value;
+    }
+    return row;
+  });
+  return { rows };
+}
+
+// implements REQ-kibi-operation-interface-parity, REQ-002, REQ-013
+async function executeSparqlRemote(
+  input: SparqlRemoteInput,
+  context: OperationContext,
+): Promise<OperationResult<SparqlRemoteOutput>> {
+  const endpoint = validateInput(input);
+  if (context.net === undefined) {
+    throw new Error("SPARQL remote query requires a network port");
+  }
+  const signal =
+    input.timeoutMs === undefined
+      ? context.signal
+      : AbortSignal.any([
+          context.signal,
+          AbortSignal.timeout(
+            Math.max(1, Math.ceil(input.timeoutMs / 1_000)) * 1_000,
+          ),
+        ]);
+  try {
+    const response = await context.net.fetch(endpoint, {
+      method: "POST",
+      headers: {
+        accept: "application/sparql-results+json",
+        "content-type": "application/x-www-form-urlencoded;charset=UTF-8",
+      },
+      body: new URLSearchParams({ query: input.query }),
+      signal,
+    });
+    if (!response.ok) {
+      throw new Error(`SPARQL endpoint returned HTTP ${response.status}`);
+    }
+    const payload: unknown = await response.json();
+    const structuredContent = decodeRows(payload);
+    const rowCount = structuredContent.rows.length;
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Remote SPARQL query returned ${rowCount} row${rowCount === 1 ? "" : "s"}.`,
+        },
+      ],
+      structuredContent,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`SPARQL remote query failed: ${message}`);
+  }
+}
+
+export const sparqlRemoteSpec = {
+  name: "kb_sparql_remote",
+  cliName: "sparql-remote",
+  description:
+    "Opt-in remote SPARQL query tool for external HTTP(S) RDF endpoints. This does not query Kibi's local RDF store directly, stores no credentials, and depends on network availability.",
+  businessInputSchema: {
+    type: "object",
+    required: ["endpoint", "query"],
+    properties: {
+      endpoint: {
+        type: "string",
+        description:
+          "Remote SPARQL endpoint URL. Must start with http:// or https://.",
+      },
+      query: {
+        type: "string",
+        description: "SPARQL SELECT query to send to the remote endpoint.",
+      },
+      timeoutMs: {
+        type: "number",
+        description:
+          "Optional positive timeout in milliseconds for the remote query.",
+      },
+    },
+  },
+  requiresProlog: false,
+  effects: ["network-read"],
+  execute: executeSparqlRemote,
+} as const satisfies OperationSpec<SparqlRemoteInput, SparqlRemoteOutput>;

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

@@ -0,0 +1,40 @@
+import type {
+  UpsertInput,
+  UpsertPayload,
+} from "../../../operations/mutation/types.js";
+import { executeUpsert } from "../../../operations/mutation/upsert.js";
+import type { OperationSpec } from "../types.js";
+import {
+  ENTITY_PROPERTIES_SCHEMA,
+  ENTITY_TYPES,
+  RELATIONSHIPS_SCHEMA,
+} from "./mutation-schemas.js";
+
+export const upsertSpec = {
+  name: "kb_upsert",
+  cliName: "upsert",
+  description:
+    "Create or update one entity and optional relationships. Use for KB mutations after validating intent; prefer kb_validate_upsert first because it returns semantic advisor receipts for prose-heavy requirements. Use kb_model_requirement before hand-writing strict property facts from prose, and kb_suggest_predicates before hand-writing ontology predicate facts. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`, or `requires_predicate`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. For requirements, the write will be rejected if it contradicts existing current requirements that constrain the same subject with incompatible properties. To replace a conflicting requirement, include a `supersedes` relationship from the new requirement to the old one in the same request. Successful writes may return non-blocking semantic advisor warnings; inspect and repair those warnings before treating prose as contradiction-checkable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+  businessInputSchema: {
+    type: "object",
+    required: ["type", "id", "properties"],
+    properties: {
+      type: {
+        type: "string",
+        enum: ENTITY_TYPES,
+        description:
+          "Entity type to create/update. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'.",
+      },
+      id: {
+        type: "string",
+        description:
+          "Unique entity ID (string). Example: 'REQ-123'. Existing ID updates the entity; new ID creates it.",
+      },
+      properties: ENTITY_PROPERTIES_SCHEMA,
+      relationships: RELATIONSHIPS_SCHEMA,
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-write", "workspace-write"],
+  execute: executeUpsert,
+} as const satisfies OperationSpec<UpsertInput, UpsertPayload>;

package/src/public/operations/types.ts

@@ -0,0 +1,57 @@
+import type { OperationContext } from "./runtime-types.js";
+export type { OperationContext };
+export type OperationName =
+  | "kb_query"
+  | "kb_search"
+  | "kb_status"
+  | "kb_skills_list"
+  | "kb_skills_load"
+  | "kb_skills_read"
+  | "kb_find_gaps"
+  | "kb_coverage"
+  | "kb_graph"
+  | "kb_sparql_remote"
+  | "kb_semantic_advisor"
+  | "kb_upsert"
+  | "kb_validate_upsert"
+  | "kb_delete"
+  | "kb_check"
+  | "kb_model_requirement"
+  | "kb_suggest_predicates"
+  | "kb_autopilot_generate";
+
+export type OperationEffect =
+  | "local-read"
+  | "kb-read"
+  | "workspace-read"
+  | "network-read"
+  | "kb-write"
+  | "workspace-write";
+
+export interface OperationContent {
+  readonly type: string;
+  readonly text?: string;
+}
+
+export interface OperationResult<O = unknown> {
+  readonly content: readonly OperationContent[];
+  readonly structuredContent?: O;
+}
+
+export interface OperationSpec<
+  I = Readonly<Record<string, unknown>>,
+  O = unknown,
+> {
+  readonly name: OperationName;
+  readonly cliName: string;
+  readonly description: string;
+  readonly businessInputSchema: Readonly<Record<string, unknown>>;
+  readonly requiresProlog: boolean;
+  readonly effects: readonly OperationEffect[];
+  readonly execute: {
+    bivarianceHack(
+      input: I,
+      context: OperationContext,
+    ): Promise<OperationResult<O>>;
+  }["bivarianceHack"];
+}

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";
@@ -33,6 +35,15 @@ type VerificationScope = "unit" | "integration" | "end_to_end";
 type VerificationPerspective = "internal" | "consumer";
 
 const factConditionals = JSON.parse(`[
+  {
+    "if": {
+      "anyOf": [
+        { "required": ["claim_key"] },
+        { "required": ["claim_text"] }
+      ]
+    },
+    "then": { "required": ["claim_key", "claim_text"] }
+  },
   {
     "if": {
       "properties": {
@@ -65,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": {
@@ -81,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" },
@@ -121,6 +355,59 @@ const entitySchema: Record<string, unknown> = {
     severity: { type: "string" },
     links: { type: "array", items: { type: "string" } },
     text_ref: { type: "string" },
+    logic_claims: {
+      type: "array",
+      minItems: 1,
+      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",
@@ -166,6 +453,8 @@ const entitySchema: Record<string, unknown> = {
         "meta",
         "predicate_schema",
         "predicate",
+        "rule_schema",
+        "rule",
       ] satisfies FactKind[],
     },
     subject_key: { type: "string" },
@@ -186,6 +475,8 @@ const entitySchema: Record<string, unknown> = {
     valid_from: { type: "string" },
     valid_to: { type: "string" },
     canonical_key: { type: "string" },
+    claim_key: { type: "string", pattern: "^CLAIM-[A-F0-9]{16}$" },
+    claim_text: { type: "string" },
     predicate_name: { type: "string" },
     predicate_namespace: { type: "string" },
     predicate_arity: { type: "integer", minimum: 1 },
@@ -195,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",
@@ -206,6 +504,14 @@ const entitySchema: Record<string, unknown> = {
     "type",
   ],
   allOf: [
+    {
+      if: {
+        properties: { type: { const: "req" } },
+      },
+      else: {
+        not: { required: ["logic_claims"] },
+      },
+    },
     // Forbid fact-only fields on non-fact entities
     {
       if: {
@@ -232,6 +538,8 @@ const entitySchema: Record<string, unknown> = {
             { required: ["valid_from"] },
             { required: ["valid_to"] },
             { required: ["canonical_key"] },
+            { required: ["claim_key"] },
+            { required: ["claim_text"] },
             { required: ["predicate_name"] },
             { required: ["predicate_namespace"] },
             { required: ["predicate_arity"] },
@@ -241,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"] },
           ],
         },
       },
@@ -258,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",