kibi-cli 0.19.0 → 2.0.0

package/dist/prolog/codec.js

@@ -13,11 +13,21 @@
  */
 /**
  * Escape a string for use as a Prolog atom.
- * Doubles single-quote characters per ISO Prolog standard.
+ * Escapes backslashes/control characters and doubles single quotes per ISO
+ * Prolog syntax.
  */
 export function escapeAtom(value) {
     // implements REQ-009
-    return value.replace(/'/g, "''");
+    return value
+        .replaceAll("\\", "\\\\")
+        .replaceAll("\u0007", "\\a")
+        .replaceAll("\u0008", "\\b")
+        .replaceAll("\u000c", "\\f")
+        .replaceAll("\n", "\\n")
+        .replaceAll("\r", "\\r")
+        .replaceAll("\t", "\\t")
+        .replaceAll("\u000b", "\\v")
+        .replaceAll("'", "''");
 }
 /**
  * Convert a string to a Prolog atom, quoting if necessary.
@@ -26,9 +36,7 @@ export function escapeAtom(value) {
 export function toPrologAtom(value) {
     // implements REQ-009
     const simplePrologAtom = /^[a-z][a-zA-Z0-9_]*$/;
-    return simplePrologAtom.test(value)
-        ? value
-        : `'${value.replace(/'/g, "''")}'`;
+    return simplePrologAtom.test(value) ? value : `'${escapeAtom(value)}'`;
 }
 /**
  * Escape a string value for use inside a Prolog double-quoted string literal.
@@ -51,75 +59,99 @@ export function toPrologString(value) {
  */
 export function escapeAtomContent(value) {
     // implements REQ-009
-    return value.replace(/'/g, "''");
+    return escapeAtom(value);
 }
+/**
+ * Parse a Prolog list of list rows without decoding or normalizing columns.
+ * Malformed outer collections fail closed rather than returning a partial
+ * projection.
+ */
 export function parseListOfLists(listStr) {
     // implements REQ-009
-    const cleaned = listStr.trim().replace(/^\[/, "").replace(/\]$/, "");
-    if (cleaned === "") {
-        return [];
+    return parseListRows(listStr).flatMap((row) => {
+        const scanned = scanTopLevelGeneral(row, ",");
+        if (!scanned.balanced)
+            return [];
+        const columns = scanned.parts.map((column) => column.trim());
+        return columns.length === 0 || (columns.length === 1 && columns[0] === "")
+            ? []
+            : [columns];
+    });
+}
+export function firstTwoDefinedParts(parts) {
+    const first = parts[0];
+    const second = parts[1];
+    if (first === undefined || second === undefined) {
+        return undefined;
     }
-    const results = [];
-    let depth = 0;
-    let current = "";
-    let currentList = [];
-    for (let i = 0; i < cleaned.length; i++) {
-        const char = cleaned[i];
-        if (char === "[") {
-            depth++;
-            if (depth > 1)
-                current += char;
-        }
-        else if (char === "]") {
-            depth--;
-            if (depth === 0) {
-                if (current) {
-                    currentList.push(current.trim());
-                    current = "";
-                }
-                if (currentList.length > 0) {
-                    results.push(currentList);
-                    currentList = [];
-                }
-            }
-            else {
-                current += char;
-            }
-        }
-        else if (char === "," && depth === 1) {
-            if (current) {
-                currentList.push(current.trim());
-                current = "";
-            }
-        }
-        else if (char === "," && depth === 0) {
-            // Skip comma between lists
-        }
-        else {
-            current += char;
+    return [first, second];
+}
+export function fallbackWhenPairMissing(pair, fallback) {
+    return pair === undefined ? fallback : null;
+}
+// implements REQ-core-persistence
+// covered_by TEST-cli-prolog-codec
+export function typedLiteralFromParts(parts, original) {
+    const pair = firstTwoDefinedParts(parts);
+    if (!pair) {
+        return original;
+    }
+    const [literalPart, datatypePart] = pair;
+    let literalValue = literalPart.trim();
+    const datatype = datatypePart.trim();
+    const decodedLiteral = decodePrologQuotedLiteral(literalValue, '"');
+    if (decodedLiteral !== undefined) {
+        literalValue = decodedLiteral;
+    }
+    else if (literalValue.startsWith('"') && literalValue.endsWith('"')) {
+        literalValue = literalValue.substring(1, literalValue.length - 1);
+    }
+    if (datatype.includes("#integer")) {
+        return Number.parseInt(literalValue, 10);
+    }
+    if (datatype.includes("#decimal") || datatype.includes("#double")) {
+        return Number.parseFloat(literalValue);
+    }
+    if (datatype.includes("#boolean")) {
+        return literalValue === "true";
+    }
+    if (literalValue.startsWith("[") && literalValue.endsWith("]")) {
+        const listContent = literalValue.substring(1, literalValue.length - 1);
+        if (listContent === "") {
+            return [];
         }
+        return splitTopLevelGeneral(listContent, ",").map((item) => item.trim());
     }
-    return results;
+    return literalValue;
 }
-export function parseEntityFromBinding(
-// implements REQ-009
-bindingStr) {
-    const cleaned = bindingStr.trim().replace(/^\[/, "").replace(/\]$/, "");
-    const parts = splitTopLevelGeneral(cleaned, ",");
+export function fileUriLeaf(value) {
+    const lastSlash = value.lastIndexOf("/");
+    if (lastSlash !== -1) {
+        return value.substring(lastSlash + 1);
+    }
+    return value;
+}
+export function entityFromBindingParts(parts) {
     if (parts.length < 3) {
         return {};
     }
-    const idPart = parts[0];
-    const typePart = parts[1];
-    if (idPart === undefined || typePart === undefined) {
+    const pair = firstTwoDefinedParts(parts);
+    if (!pair) {
         return {};
     }
+    const [idPart, typePart] = pair;
     const id = idPart.trim();
     const type = typePart.trim();
     const propsStr = parts.slice(2).join(",").trim();
     const props = parsePropertyList(propsStr);
     return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
 }
+export function parseEntityFromBinding(
+// implements REQ-009
+bindingStr) {
+    const cleaned = bindingStr.trim().replace(/^\[/, "").replace(/\]$/, "");
+    return entityFromBindingParts(splitTopLevelGeneral(cleaned, ","));
+}
 export function parseEntityFromList(data) {
     // implements REQ-009
     if (data.length < 3) {
@@ -160,7 +192,9 @@ export function parsePropertyList(propsStr) {
         let parsed = parsePrologValue(value);
         if ((key === "rule_ir" ||
             key === "semantic_inventory" ||
-            key === "verification_receipts") &&
+            key === "proof_receipts" ||
+            key === "proof_contract" ||
+            key === "proof_bindings") &&
             typeof parsed === "string") {
             try {
                 parsed = JSON.parse(parsed);
@@ -203,57 +237,22 @@ export function parsePrologValue(valueInput) {
         const innerContent = value.substring(innerStart, innerEnd);
         const parts = splitTopLevelGeneral(innerContent, ",");
         if (parts.length >= 2) {
-            const literalPart = parts[0];
-            const datatypePart = parts[1];
-            if (literalPart === undefined || datatypePart === undefined) {
-                return value;
-            }
-            let literalValue = literalPart.trim();
-            const datatype = datatypePart.trim();
-            if (literalValue.startsWith('"') && literalValue.endsWith('"')) {
-                literalValue = literalValue.substring(1, literalValue.length - 1);
-            }
-            // Parse typed literals based on datatype
-            if (datatype.includes("#integer")) {
-                return Number.parseInt(literalValue, 10);
-            }
-            if (datatype.includes("#decimal") || datatype.includes("#double")) {
-                return Number.parseFloat(literalValue);
-            }
-            if (datatype.includes("#boolean")) {
-                return literalValue === "true";
-            }
-            // Handle array notation for string values
-            if (literalValue.startsWith("[") && literalValue.endsWith("]")) {
-                const listContent = literalValue.substring(1, literalValue.length - 1);
-                if (listContent === "") {
-                    return [];
-                }
-                return splitTopLevelGeneral(listContent, ",").map((item) => item.trim());
-            }
-            return literalValue;
+            return typedLiteralFromParts(parts, value);
         }
     }
     // Handle URI
     if (value.startsWith("file:///")) {
-        const lastSlash = value.lastIndexOf("/");
-        if (lastSlash !== -1) {
-            return value.substring(lastSlash + 1);
-        }
-        return value;
+        return fileUriLeaf(value);
     }
     // Handle quoted string
     if (value.startsWith('"') && value.endsWith('"')) {
-        try {
-            return JSON.parse(value);
-        }
-        catch {
-            return value.substring(1, value.length - 1);
-        }
+        return (decodePrologQuotedLiteral(value, '"') ??
+            value.substring(1, value.length - 1));
     }
     // Handle quoted atom
     if (value.startsWith("'") && value.endsWith("'")) {
-        return value.substring(1, value.length - 1);
+        return (decodePrologQuotedLiteral(value, "'") ??
+            value.substring(1, value.length - 1));
     }
     // Handle list
     if (value.startsWith("[") && value.endsWith("]")) {
@@ -270,42 +269,66 @@ export function parsePrologValue(valueInput) {
 }
 export function splitTopLevelGeneral(str, delimiter) {
     // implements REQ-009
+    return scanTopLevelGeneral(str, delimiter).parts;
+}
+function scanTopLevelGeneral(str, delimiter) {
     const results = [];
     let current = "";
-    let depth = 0;
-    let inDoubleQuotes = false;
-    let inSingleQuotes = false;
+    let quote = null;
+    const delimiters = [];
+    let balanced = true;
     for (let i = 0; i < str.length; i++) {
         const char = str[i];
-        const prevChar = i > 0 ? str[i - 1] : "";
-        if (char === '"' && !inSingleQuotes && prevChar !== "\\") {
-            inDoubleQuotes = !inDoubleQuotes;
+        if (quote !== null) {
             current += char;
+            if (char === "\\") {
+                const escaped = str[i + 1];
+                if (escaped !== undefined) {
+                    current += escaped;
+                    i++;
+                }
+            }
+            else if (char === quote) {
+                const doubledPrologQuote = quote === "'" && str[i + 1] === "'";
+                if (doubledPrologQuote) {
+                    current += str[i + 1] ?? "";
+                    i++;
+                }
+                else {
+                    quote = null;
+                }
+            }
+            continue;
         }
-        else if (char === "'" && !inDoubleQuotes && prevChar !== "\\") {
-            inSingleQuotes = !inSingleQuotes;
+        if (char === "'" || char === '"') {
+            quote = char;
             current += char;
+            continue;
         }
-        else if (!inDoubleQuotes &&
-            !inSingleQuotes &&
-            (char === "[" || char === "(")) {
-            depth++;
+        if (char === "[" || char === "(" || char === "{") {
+            delimiters.push(char);
             current += char;
+            continue;
         }
-        else if (!inDoubleQuotes &&
-            !inSingleQuotes &&
-            (char === "]" || char === ")")) {
-            depth--;
+        if (char === "]" || char === ")" || char === "}") {
+            const expectedOpening = char === "]" ? "[" : char === ")" ? "(" : "{";
+            if (delimiters.at(-1) !== expectedOpening) {
+                balanced = false;
+            }
+            else {
+                delimiters.pop();
+            }
             current += char;
+            continue;
         }
-        else if (!inDoubleQuotes &&
-            !inSingleQuotes &&
-            depth === 0 &&
-            char === delimiter) {
+        if (delimiters.length === 0 &&
+            delimiter.length > 0 &&
+            str.startsWith(delimiter, i)) {
             if (current) {
                 results.push(current);
                 current = "";
             }
+            i += delimiter.length - 1;
         }
         else {
             current += char;
@@ -314,7 +337,10 @@ export function splitTopLevelGeneral(str, delimiter) {
     if (current) {
         results.push(current);
     }
-    return results;
+    return {
+        parts: results,
+        balanced: balanced && quote === null && delimiters.length === 0,
+    };
 }
 export function splitTopLevel(str, delimiter) {
     // implements REQ-009
@@ -322,14 +348,17 @@ export function splitTopLevel(str, delimiter) {
 }
 function stripOuterQuotes(value) {
     if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1);
+        return decodePrologQuotedLiteral(value, "'") ?? value.slice(1, -1);
     }
     if (value.startsWith('"') && value.endsWith('"')) {
-        return value.slice(1, -1);
+        return decodePrologQuotedLiteral(value, '"') ?? value.slice(1, -1);
     }
     return value;
 }
-function normalizeEntityId(value) {
+export function normalizeEntityId(value) {
+    if (value.startsWith("kb:entity/")) {
+        return value.slice("kb:entity/".length);
+    }
     if (!value.startsWith("file:///")) {
         return value;
     }
@@ -388,37 +417,26 @@ function parseListRows(raw) {
     if (trimmed === "[]" || trimmed.length === 0) {
         return [];
     }
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+        return [];
+    }
     const content = unwrapList(trimmed);
     if (content.length === 0) {
         return [];
     }
+    const scanned = scanTopLevelGeneral(content, ",");
+    if (!scanned.balanced) {
+        return [];
+    }
     const rows = [];
-    let depth = 0;
-    let current = "";
-    for (let i = 0; i < content.length; i++) {
-        const ch = content[i];
-        if (ch === "[") {
-            depth++;
-            if (depth > 1) {
-                current += ch;
-            }
-            continue;
-        }
-        if (ch === "]") {
-            depth--;
-            if (depth === 0) {
-                rows.push(current.trim());
-                current = "";
-            }
-            else {
-                current += ch;
-            }
-            continue;
-        }
-        if (ch === "," && depth === 0) {
+    for (const term of scanned.parts) {
+        const row = term.trim();
+        if (row.length === 0)
             continue;
+        if (!row.startsWith("[") || !row.endsWith("]")) {
+            return [];
         }
-        current += ch;
+        rows.push(row.slice(1, -1).trim());
     }
     return rows;
 }
@@ -461,12 +479,12 @@ export function parseViolationRows(raw) {
             suggestionPart === undefined) {
             continue;
         }
-        const rule = rulePart.trim().replace(/^'|'$/g, "");
-        const entityId = entityIdPart.trim().replace(/^'|'$/g, "");
-        const description = descriptionPart.trim().replace(/^"|"$/g, "");
-        const suggestion = suggestionPart.trim().replace(/^"|"$/g, "");
+        const rule = stripQuotes(rulePart.trim());
+        const entityId = stripQuotes(entityIdPart.trim());
+        const description = stripQuotes(descriptionPart.trim());
+        const suggestion = stripQuotes(suggestionPart.trim());
         const source = parts.length >= 5
-            ? parts[4]?.trim().replace(/^'|'$/g, "") || undefined
+            ? stripQuotes(parts[4]?.trim() ?? "") || undefined
             : undefined;
         violations.push({
             rule,
@@ -480,10 +498,108 @@ export function parseViolationRows(raw) {
 }
 function stripQuotes(value) {
     if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1);
+        return decodePrologQuotedLiteral(value, "'") ?? value.slice(1, -1);
     }
     if (value.startsWith('"') && value.endsWith('"')) {
-        return value.slice(1, -1);
+        return decodePrologQuotedLiteral(value, '"') ?? value.slice(1, -1);
     }
     return value;
 }
+/** Decode one Prolog quoted literal without decoding an escaped value twice. */
+function decodePrologQuotedLiteral(value, quote) {
+    if (!value.startsWith(quote) || !value.endsWith(quote) || value.length < 2) {
+        return undefined;
+    }
+    const content = value.slice(1, -1);
+    let decoded = "";
+    for (let index = 0; index < content.length; index++) {
+        const char = content[index];
+        if (char === undefined)
+            continue;
+        if (quote === "'" && char === "'") {
+            if (content[index + 1] !== "'")
+                return undefined;
+            decoded += "'";
+            index++;
+            continue;
+        }
+        if (char !== "\\") {
+            decoded += char;
+            continue;
+        }
+        const escaped = content[index + 1];
+        if (escaped === undefined)
+            return undefined;
+        index++;
+        switch (escaped) {
+            case "a":
+                decoded += "\u0007";
+                break;
+            case "b":
+                decoded += "\b";
+                break;
+            case "e":
+                decoded += "\u001b";
+                break;
+            case "f":
+                decoded += "\f";
+                break;
+            case "n":
+                decoded += "\n";
+                break;
+            case "r":
+                decoded += "\r";
+                break;
+            case "t":
+                decoded += "\t";
+                break;
+            case "v":
+                decoded += "\u000b";
+                break;
+            case "\\":
+                decoded += "\\";
+                break;
+            case "'":
+                decoded += "'";
+                break;
+            case '"':
+                decoded += '"';
+                break;
+            case "u": {
+                const code = content.slice(index + 1, index + 5);
+                if (!/^[0-9A-Fa-f]{4}$/.test(code))
+                    return undefined;
+                decoded += String.fromCodePoint(Number.parseInt(code, 16));
+                index += 4;
+                break;
+            }
+            case "U": {
+                const code = content.slice(index + 1, index + 9);
+                if (!/^[0-9A-Fa-f]{8}$/.test(code))
+                    return undefined;
+                const codePoint = Number.parseInt(code, 16);
+                if (codePoint > 0x10ffff)
+                    return undefined;
+                decoded += String.fromCodePoint(codePoint);
+                index += 8;
+                break;
+            }
+            case "x": {
+                let end = index + 1;
+                while (/[0-9A-Fa-f]/.test(content[end] ?? ""))
+                    end++;
+                if (end === index + 1 || content[end] !== "\\")
+                    return undefined;
+                const codePoint = Number.parseInt(content.slice(index + 1, end), 16);
+                if (codePoint > 0x10ffff)
+                    return undefined;
+                decoded += String.fromCodePoint(codePoint);
+                index = end;
+                break;
+            }
+            default:
+                return undefined;
+        }
+    }
+    return decoded;
+}

package/dist/prolog/error-terms.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Structured transport for Prolog errors.
+ *
+ * kb.pl throws ISO-style terms (`error(permission_error(save, kb,
+ * stale_snapshot), Context)`). The query wrappers in prolog.ts write the
+ * thrown term — quoted, depth-bounded — to stderr behind this sentinel so
+ * TypeScript can classify the term structurally instead of re-parsing SWI's
+ * human-readable print_message output. Text heuristics remain only as a
+ * fallback for errors that never pass through a wrapper (startup failures,
+ * older kibi-core versions).
+ */
+export declare const PROLOG_ERROR_TERM_PREFIX = "__KIBI_ERROR__:";
+export type PrologErrorCode = "stale_snapshot" | "audit_locked" | "permission_denied" | "entity_not_found" | "invalid_relationship" | "contradiction" | "validation_error";
+export type PrologErrorRelationship = Readonly<{
+    relType: string;
+    fromType: string;
+    toType: string;
+}>;
+export type PrologErrorConflict = Readonly<{
+    reason: string;
+    otherId: string;
+}>;
+export type PrologStoreLockOwner = Readonly<{
+    pid?: number;
+    workspaceRoot?: string;
+    bootId?: string;
+    startedAt?: string;
+}>;
+export type PrologStoreLockedDetail = Readonly<{
+    owner: PrologStoreLockOwner | null;
+    lockDirectory: string;
+    originalError?: string;
+}>;
+export type PrologErrorRecord = Readonly<{
+    code: PrologErrorCode;
+    message: string;
+    entityId?: string;
+    role?: "source" | "target";
+    relationship?: PrologErrorRelationship;
+    conflicts?: readonly PrologErrorConflict[];
+    storeLocked?: PrologStoreLockedDetail;
+}>;
+/** Extract the first structured error term line from raw stderr text. */
+export declare function extractPrologErrorRecord(text: string): PrologErrorRecord | null;
+/** Parse a written error term such as `error(permission_error(...), Context)`. */
+export declare function parsePrologErrorTerm(termText: string): PrologErrorRecord | null;
+//# sourceMappingURL=error-terms.d.ts.map

package/dist/prolog/error-terms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-terms.d.ts","sourceRoot":"","sources":["../../src/prolog/error-terms.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAG1D,MAAM,MAAM,eAAe,GACvB,gBAAgB,GAChB,cAAc,GACd,mBAAmB,GACnB,kBAAkB,GAClB,sBAAsB,GACtB,eAAe,GACf,kBAAkB,CAAC;AAGvB,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,YAAY,CAAC,EAAE,uBAAuB,CAAC;IACvC,SAAS,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC3C,WAAW,CAAC,EAAE,uBAAuB,CAAC;CACvC,CAAC,CAAC;AAEH,yEAAyE;AAEzE,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,IAAI,CAK1B;AAED,kFAAkF;AAElF,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GACf,iBAAiB,GAAG,IAAI,CAsG1B"}