kibi-cli 0.14.0 → 0.16.1

package/dist/operations/mutation/serialization.d.ts

@@ -0,0 +1,5 @@
+import type { RelationshipInput } from "./types.js";
+export declare function buildPropertyList(entity: Readonly<Record<string, unknown>>): string;
+export declare function buildRelationshipMetadata(rel: RelationshipInput): string;
+export declare function parsePrologList(list: string): string[];
+//# sourceMappingURL=serialization.d.ts.map

package/dist/operations/mutation/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA0CpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}

package/dist/operations/mutation/serialization.js

@@ -0,0 +1,85 @@
+import { toPrologAtom, toPrologString } from "../../prolog/codec.js";
+const ATOM_FIELDS = [
+    "status",
+    "owner",
+    "priority",
+    "severity",
+    "symbol_role",
+    "granularity_reason",
+    "verification_scope",
+    "verification_perspective",
+    "fact_kind",
+    "operator",
+    "value_type",
+    "polarity",
+];
+const STRING_FIELDS = [
+    "id",
+    "title",
+    "created_at",
+    "updated_at",
+    "source",
+    "text_ref",
+];
+function serializeValue(key, value) {
+    if (key === "id" && typeof value === "string") {
+        return `'${value.replaceAll("'", "''")}'`;
+    }
+    if (Array.isArray(value))
+        return JSON.stringify(value);
+    if (typeof value === "string") {
+        return ATOM_FIELDS.includes(key)
+            ? toPrologAtom(value)
+            : toPrologString(value);
+    }
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return toPrologString(String(value));
+}
+// implements REQ-kibi-operation-interface-parity
+export function buildPropertyList(entity) {
+    const pairs = Object.entries(entity).flatMap(([key, value]) => {
+        if (key === "type" || value === undefined || value === null)
+            return [];
+        return [`${key}=${serializeValue(key, value)}`];
+    });
+    return `[${pairs.join(", ")}]`;
+}
+// implements REQ-kibi-operation-interface-parity
+export function buildRelationshipMetadata(rel) {
+    const pairs = Object.entries(rel).flatMap(([key, value]) => {
+        if (key === "type" || key === "from" || key === "to")
+            return [];
+        if (typeof value === "number")
+            return [`${key}=${String(value)}`];
+        return [`${key}=${toPrologString(String(value))}`];
+    });
+    return `[${pairs.join(", ")}]`;
+}
+// implements REQ-kibi-operation-interface-parity
+export function parsePrologList(list) {
+    const match = list.trim().match(/^\[(.*)\]$/s);
+    if (!match?.[1])
+        return [];
+    const items = [];
+    let depth = 0;
+    let current = "";
+    for (const char of match[1]) {
+        if (char === "[")
+            depth += 1;
+        if (char === "]")
+            depth -= 1;
+        if (char === "," && depth === 0) {
+            items.push(current.trim().replace(/^'|'$/g, ""));
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim())
+        items.push(current.trim().replace(/^'|'$/g, ""));
+    return items;
+}

package/dist/operations/mutation/strict-fact.d.ts

@@ -0,0 +1,4 @@
+export declare function valueFieldHint(value: unknown): string;
+export declare function factKindShapeHints(entity: Readonly<Record<string, unknown>>): string[];
+export declare function validateFactModelingShape(entity: Readonly<Record<string, unknown>>): void;
+//# sourceMappingURL=strict-fact.d.ts.map

package/dist/operations/mutation/strict-fact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-fact.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/strict-fact.ts"],"names":[],"mappings":"AAQA,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAarD;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CAyCV;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,IAAI,CAKN"}

package/dist/operations/mutation/strict-fact.js

@@ -0,0 +1,67 @@
+const PROPERTY_VALUE_FIELDS = [
+    "value_string",
+    "value_int",
+    "value_number",
+    "value_bool",
+];
+// implements REQ-kibi-operation-interface-parity
+export function valueFieldHint(value) {
+    if (typeof value === "boolean") {
+        return `Use value_type: "bool" plus value_bool: ${String(value)}.`;
+    }
+    if (typeof value === "number") {
+        return Number.isInteger(value)
+            ? `Use value_type: "int" plus value_int: ${String(value)}.`
+            : `Use value_type: "number" plus value_number: ${String(value)}.`;
+    }
+    if (typeof value === "string") {
+        return `Use value_type: "string" plus value_string: ${JSON.stringify(value)}.`;
+    }
+    return "Use value_type plus exactly one of value_string, value_int, value_number, or value_bool.";
+}
+// implements REQ-kibi-operation-interface-parity
+export function factKindShapeHints(entity) {
+    if (entity.type !== "fact")
+        return [];
+    if (entity.fact_kind === "property_value") {
+        const missing = [
+            "subject_key",
+            "property_key",
+            "operator",
+            "value_type",
+        ].filter((field) => entity[field] === undefined);
+        const present = PROPERTY_VALUE_FIELDS.filter((field) => entity[field] !== undefined);
+        const hints = [];
+        if (missing.length > 0) {
+            hints.push(`fact_kind 'property_value' requires ${missing.join(", ")}.`);
+        }
+        if (present.length !== 1) {
+            hints.push("fact_kind 'property_value' requires exactly one typed value field: value_string, value_int, value_number, or value_bool.");
+        }
+        if (hints.length > 0) {
+            hints.push("Next action: use kb_model_requirement for prose claims, or provide subject_key, property_key, operator, value_type, and one value_* field in kb_upsert.properties.");
+        }
+        return hints;
+    }
+    if (entity.fact_kind !== "predicate")
+        return [];
+    const args = entity.predicate_args;
+    const missing = [
+        ...(entity.predicate_name === undefined ? ["predicate_name"] : []),
+        ...(!Array.isArray(args) || args.length === 0 ? ["predicate_args"] : []),
+        ...(entity.canonical_key === undefined ? ["canonical_key"] : []),
+    ];
+    return missing.length === 0
+        ? []
+        : [
+            `fact_kind 'predicate' requires ${missing.join(", ")}.`,
+            "Next action: call kb_suggest_predicates before hand-writing ontology predicate facts.",
+        ];
+}
+// implements REQ-kibi-operation-interface-parity
+export function validateFactModelingShape(entity) {
+    const hints = factKindShapeHints(entity);
+    if (hints.length > 0) {
+        throw new Error(`Entity validation failed: ${hints.join("; ")}`);
+    }
+}

package/dist/operations/mutation/symbol-granularity.d.ts

@@ -0,0 +1,4 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import type { RelationshipInput } from "./types.js";
+export declare function validateSymbolGranularity(entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext): Promise<void>;
+//# sourceMappingURL=symbol-granularity.d.ts.map

package/dist/operations/mutation/symbol-granularity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-granularity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiEpD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/operations/mutation/symbol-granularity.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { Project, ScriptKind } from "ts-morph";
+import { getBehavioralSymbolNames, getNonBehavioralSymbolNames, inferSymbolRole, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../../public/symbol-granularity.js";
+function scriptKind(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension === ".tsx")
+        return ScriptKind.TSX;
+    if ([".ts", ".mts", ".cts"].includes(extension))
+        return ScriptKind.TS;
+    if (extension === ".jsx")
+        return ScriptKind.JSX;
+    return ScriptKind.JS;
+}
+function candidate(name, kind) {
+    return { name, kind, role: inferSymbolRole(kind) };
+}
+function candidates(filePath, content) {
+    const source = new Project({
+        skipAddingFilesFromTsConfig: true,
+    }).createSourceFile(`${filePath}::granularity`, content, {
+        overwrite: true,
+        scriptKind: scriptKind(filePath),
+    });
+    const found = [];
+    const methodCounts = new Map();
+    const bareMethods = new Map();
+    for (const fn of source.getFunctions()) {
+        const name = fn.getName();
+        if (fn.isExported() && name)
+            found.push(candidate(name, "function"));
+    }
+    for (const cls of source.getClasses()) {
+        if (!cls.isExported())
+            continue;
+        const className = cls.getName();
+        if (className)
+            found.push(candidate(className, "class"));
+        for (const method of cls.getMethods()) {
+            const name = method.getName();
+            if (className)
+                found.push(candidate(`${className}.${name}`, "method"));
+            bareMethods.set(name, candidate(name, "method"));
+            methodCounts.set(name, (methodCounts.get(name) ?? 0) + 1);
+        }
+    }
+    for (const [name, count] of methodCounts) {
+        const method = bareMethods.get(name);
+        if (count === 1 && method)
+            found.push(method);
+    }
+    for (const item of source.getInterfaces()) {
+        if (item.isExported())
+            found.push(candidate(item.getName(), "interface"));
+    }
+    for (const item of source.getTypeAliases()) {
+        if (item.isExported())
+            found.push(candidate(item.getName(), "type"));
+    }
+    for (const item of source.getEnums()) {
+        if (item.isExported())
+            found.push(candidate(item.getName(), "enum"));
+    }
+    return found.sort((left, right) => left.name.localeCompare(right.name));
+}
+function summarized(names) {
+    const shown = names.slice(0, 10);
+    const hidden = names.length - shown.length;
+    return `${shown.join(", ")}${hidden > 0 ? `, and ${hidden} more` : ""}`;
+}
+// implements REQ-kibi-operation-interface-parity
+export async function validateSymbolGranularity(entity, relationships, context) {
+    if (entity.type !== "symbol")
+        return;
+    if (!relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type)))
+        return;
+    if (isAllowedGranularityReason(entity.granularity_reason))
+        return;
+    if (typeof entity.sourceFile !== "string" || typeof entity.title !== "string")
+        return;
+    const fs = context.fs;
+    if (fs === undefined)
+        return;
+    const sourcePath = path.isAbsolute(entity.sourceFile)
+        ? entity.sourceFile
+        : path.resolve(context.workspaceRoot, entity.sourceFile);
+    let content;
+    try {
+        const stat = await fs.stat(sourcePath);
+        if (!stat.isFile())
+            return;
+        content = await fs.readFile(sourcePath);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return;
+        throw error;
+    }
+    const available = candidates(entity.sourceFile, content);
+    if (available.some(({ name }) => name === entity.title))
+        return;
+    const behavioral = getBehavioralSymbolNames(available);
+    if (behavioral.length === 0)
+        return;
+    const nonBehavioral = getNonBehavioralSymbolNames(available);
+    const ignored = nonBehavioral.length > 0
+        ? ` Non-behavioral symbols in the file were ignored for this decision: ${summarized(nonBehavioral)}.`
+        : "";
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${summarized(behavioral)}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.${ignored}`);
+}

package/dist/operations/mutation/symbol-refresh.d.ts

@@ -0,0 +1,10 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+type RefreshResult = {
+    readonly refreshed: boolean;
+    readonly found: boolean;
+};
+type RefreshImplementation = (symbolId: string, context: OperationContext) => Promise<RefreshResult>;
+export declare function refreshSymbolCoordinates(symbolId: string, context: OperationContext): Promise<RefreshResult>;
+export declare function setSymbolRefreshForTests(refresh: RefreshImplementation | undefined): void;
+export {};
+//# sourceMappingURL=symbol-refresh.d.ts.map

package/dist/operations/mutation/symbol-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAC9E,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAsH5B,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAExB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}

package/dist/operations/mutation/symbol-refresh.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { dump as dumpYaml, load as parseYaml } from "js-yaml";
+import { enrichSymbolCoordinates } from "../../public/extractors/symbols-coordinator.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function coordinate(value) {
+    if (!record(value))
+        return null;
+    const { sourceFile, sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, } = value;
+    return typeof sourceFile === "string" &&
+        typeof sourceLine === "number" &&
+        typeof sourceColumn === "number" &&
+        typeof sourceEndLine === "number" &&
+        typeof sourceEndColumn === "number"
+        ? { sourceFile, sourceLine, sourceColumn, sourceEndLine, sourceEndColumn }
+        : null;
+}
+async function exists(context, filePath) {
+    try {
+        return context.fs?.stat(filePath).then((stat) => stat.isFile()) ?? false;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+async function manifestPath(context) {
+    const fs = context.fs;
+    if (fs === undefined)
+        return path.join(context.workspaceRoot, "symbols.yaml");
+    const configPath = path.join(context.workspaceRoot, ".kb", "config.json");
+    try {
+        const config = JSON.parse(await fs.readFile(configPath));
+        if (record(config)) {
+            const paths = config.paths;
+            const configured = record(paths) && typeof paths.symbols === "string"
+                ? paths.symbols
+                : typeof config.symbolsManifest === "string"
+                    ? config.symbolsManifest
+                    : null;
+            if (configured)
+                return path.resolve(context.workspaceRoot, configured);
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+    }
+    for (const name of ["symbols.yaml", "symbols.yml"]) {
+        const candidate = path.join(context.workspaceRoot, name);
+        if (await exists(context, candidate))
+            return candidate;
+    }
+    return path.join(context.workspaceRoot, "symbols.yaml");
+}
+async function defaultRefresh(symbolId, context) {
+    const fs = context.fs;
+    if (fs === undefined)
+        return { refreshed: false, found: false };
+    const manifest = await manifestPath(context);
+    const parsed = parseYaml(await fs.readFile(manifest));
+    if (!record(parsed) || !Array.isArray(parsed.symbols)) {
+        return { refreshed: false, found: false };
+    }
+    const entry = parsed.symbols.find((value) => record(value) && value.id === symbolId);
+    if (!record(entry))
+        return { refreshed: false, found: false };
+    const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : "";
+    const title = typeof entry.title === "string" ? entry.title : "";
+    const [enriched] = await enrichSymbolCoordinates([{ ...entry, id: symbolId, title, sourceFile }], context.workspaceRoot);
+    const next = coordinate(enriched);
+    if (next === null)
+        return { refreshed: false, found: true };
+    const artifactPath = path.join(path.dirname(manifest), "symbol-coordinates.yaml");
+    let coordinates = {};
+    try {
+        const artifact = parseYaml(await fs.readFile(artifactPath));
+        if (record(artifact) && record(artifact.coordinates)) {
+            coordinates = Object.fromEntries(Object.entries(artifact.coordinates).flatMap(([id, value]) => {
+                const normalized = coordinate(value);
+                return normalized === null ? [] : [[id, normalized]];
+            }));
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+    }
+    coordinates[symbolId] = next;
+    const sorted = Object.fromEntries(Object.entries(coordinates).sort(([left], [right]) => left.localeCompare(right)));
+    const content = `# symbol-coordinates.yaml\n# GENERATED coordinate artifact — do not edit manually.\n# Run \`kibi sync --refresh-symbol-coordinates\` to refresh.\n${dumpYaml({ coordinates: sorted }, { lineWidth: -1, noRefs: true, sortKeys: true })}`;
+    await fs.writeFile(artifactPath, content);
+    return { refreshed: true, found: true };
+}
+let implementation = defaultRefresh;
+// implements REQ-kibi-operation-interface-parity
+export async function refreshSymbolCoordinates(symbolId, context) {
+    return implementation(symbolId, context);
+}
+// implements REQ-kibi-operation-interface-parity
+export function setSymbolRefreshForTests(refresh) {
+    implementation = refresh ?? defaultRefresh;
+}

package/dist/operations/mutation/types.d.ts

@@ -0,0 +1,43 @@
+import type { SemanticAdvisorReceipt } from "../semantic-advisor/types.js";
+export type RelationshipInput = Readonly<Record<string, unknown>>;
+export type UpsertInput = {
+    readonly type: string;
+    readonly id: string;
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly relationships?: readonly RelationshipInput[];
+    readonly _skipContradictionCheck?: boolean;
+    readonly _requestId?: string;
+};
+export type ValidatedUpsert = {
+    readonly entity: Record<string, unknown>;
+    readonly relationships: readonly RelationshipInput[];
+};
+export type UpsertPayload = {
+    readonly created: number;
+    readonly updated: number;
+    readonly relationships_created: number;
+    readonly warnings: readonly string[];
+    readonly semanticAdvisor: SemanticAdvisorReceipt;
+    readonly contradictionCheck?: {
+        readonly outcome: "no-conflict" | "skipped";
+        readonly checked_req_id: string;
+        readonly strict_readiness: string;
+    };
+};
+export type ValidateUpsertPayload = {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+    readonly semanticAdvisor: SemanticAdvisorReceipt | null;
+    readonly normalizedPreview: Readonly<Record<string, unknown>> | null;
+};
+export type DeleteInput = {
+    readonly ids: readonly string[];
+    readonly _requestId?: string;
+};
+export type DeletePayload = {
+    readonly deleted: number;
+    readonly skipped: number;
+    readonly errors: readonly string[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/operations/mutation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAG3E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAGlE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAGF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,CAAC;AAGF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;QAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;KACnC,CAAC;CACH,CAAC;AAGF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACxD,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACtE,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC"}

package/dist/operations/mutation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/mutation/upsert.d.ts

@@ -0,0 +1,5 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import type { OperationResult } from "../../public/operations/types.js";
+import type { UpsertInput, UpsertPayload } from "./types.js";
+export declare function executeUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<UpsertPayload>>;
+//# sourceMappingURL=upsert.d.ts.map

package/dist/operations/mutation/upsert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAaxE,OAAO,KAAK,EAAqB,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkChF,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA0FzC"}

package/dist/operations/mutation/upsert.js

@@ -0,0 +1,103 @@
+import { escapeAtom } from "../../prolog/codec.js";
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { recordEntityAudit, recordRelationshipAudits } from "./audit.js";
+import { buildUpsertTransaction, formatUpsertError } from "./contradictions.js";
+import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, } from "./relationships.js";
+import { saveMutation } from "./save.js";
+import { validateSymbolGranularity } from "./symbol-granularity.js";
+import { refreshSymbolCoordinates } from "./symbol-refresh.js";
+import { validateUpsertInput } from "./validation.js";
+import { scenarioCoverageWarnings } from "./warnings.js";
+function requireProlog(context) {
+    if (context.prolog === undefined) {
+        throw new Error("Upsert operation requires a Prolog runtime");
+    }
+    return context.prolog;
+}
+async function effectiveRelationships(input, entity, relationships, context) {
+    if (input.relationships !== undefined && input.relationships.length > 0) {
+        return relationships;
+    }
+    const prolog = requireProlog(context);
+    const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
+    if (!exists.success)
+        return relationships;
+    try {
+        const current = await existingRelationships(prolog, String(entity.id));
+        return current.length > 0 ? current : relationships;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return relationships;
+        throw error;
+    }
+}
+export async function executeUpsert(input, context) {
+    const prolog = requireProlog(context);
+    try {
+        const validated = validateUpsertInput(input, context.clock());
+        validateRelationshipSources(input.id, validated.relationships);
+        await validateSymbolGranularity(validated.entity, validated.relationships, context);
+        const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context);
+        await validateStrictLanePairing(prolog, relationships);
+        await validateLiveRelationshipTargets(prolog, validated.entity, relationships);
+        const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
+        const transaction = buildUpsertTransaction({
+            entity: validated.entity,
+            relationships,
+            skipContradictionCheck: input._skipContradictionCheck === true,
+        });
+        const written = await prolog.query(transaction);
+        if (!written.success) {
+            throw new Error(formatUpsertError(input.id, written.error));
+        }
+        await recordEntityAudit(prolog, exists.success ? "updated" : "created", validated.entity);
+        await recordRelationshipAudits(prolog, relationships);
+        await saveMutation(prolog);
+        if (input.type === "symbol") {
+            try {
+                await refreshSymbolCoordinates(input.id, context);
+            }
+            catch (error) {
+                if (!(error instanceof Error))
+                    throw error;
+            }
+        }
+        const semantic = analyzeSemanticAdvisorInput({ payload: { ...input } });
+        const coverage = await scenarioCoverageWarnings(prolog, validated.relationships, input.type, input.id);
+        const created = exists.success ? 0 : 1;
+        const payload = {
+            created,
+            updated: exists.success ? 1 : 0,
+            relationships_created: relationships.length,
+            warnings: [...semantic.warnings, ...coverage],
+            semanticAdvisor: semantic.receipt,
+            ...(input.type === "req"
+                ? {
+                    contradictionCheck: {
+                        outcome: input._skipContradictionCheck
+                            ? "skipped"
+                            : "no-conflict",
+                        checked_req_id: input.id,
+                        strict_readiness: semantic.receipt.logic_readiness === "modeled"
+                            ? "modeled"
+                            : semantic.receipt.candidate_lane,
+                    },
+                }
+                : {}),
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Upserted ${input.id} (${created > 0 ? "created" : "updated"}) with ${relationships.length} relationship(s).`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Upsert execution failed: ${message}`);
+    }
+}

package/dist/operations/mutation/validate-upsert.d.ts

@@ -0,0 +1,5 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import type { OperationResult } from "../../public/operations/types.js";
+import type { UpsertInput, ValidateUpsertPayload } from "./types.js";
+export declare function executeValidateUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<ValidateUpsertPayload>>;
+//# sourceMappingURL=validate-upsert.d.ts.map

package/dist/operations/mutation/validate-upsert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGrE,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAoDjD"}

package/dist/operations/mutation/validate-upsert.js

@@ -0,0 +1,50 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { validateLiveRelationshipTargets, validateRelationshipSources, } from "./relationships.js";
+import { validateSymbolGranularity } from "./symbol-granularity.js";
+import { validateUpsertInput } from "./validation.js";
+export async function executeValidateUpsert(input, context) {
+    try {
+        const validated = validateUpsertInput(input, context.clock());
+        validateRelationshipSources(input.id, validated.relationships);
+        await validateSymbolGranularity(validated.entity, validated.relationships, context);
+        if (context.prolog !== undefined) {
+            await validateLiveRelationshipTargets(context.prolog, validated.entity, validated.relationships);
+        }
+        const semantic = analyzeSemanticAdvisorInput({ payload: { ...input } });
+        const payload = {
+            valid: true,
+            errors: [],
+            warnings: semantic.warnings,
+            semanticAdvisor: semantic.receipt,
+            normalizedPreview: validated.entity,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "kb_validate_upsert: payload is valid for kb_upsert preflight checks. No mutation was performed.",
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const payload = {
+            valid: false,
+            errors: [message],
+            warnings: [],
+            semanticAdvisor: null,
+            normalizedPreview: null,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `kb_validate_upsert: payload is invalid. ${message}`,
+                },
+            ],
+            structuredContent: payload,
+        };
+    }
+}

package/dist/operations/mutation/validation.d.ts

@@ -0,0 +1,5 @@
+import { isAllowedGranularityReason } from "../../public/symbol-granularity.js";
+import type { UpsertInput, ValidatedUpsert } from "./types.js";
+export declare function validateUpsertInput(input: UpsertInput, now: Date): ValidatedUpsert;
+export { isAllowedGranularityReason };
+//# sourceMappingURL=validation.d.ts.map

package/dist/operations/mutation/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA0CjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}