kibi-mcp 0.16.0 → 0.17.2

package/dist/tools/upsert.js

@@ -19,11 +19,15 @@ import path from "node:path";
 */
 import Ajv from "ajv";
 import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
+import { SYMBOL_ROLES, getBehavioralSymbolNames, getNonBehavioralSymbolNames, inferSymbolRole, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "kibi-cli/public/symbol-granularity";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { Project, ScriptKind } from "ts-morph";
 import { isMcpDebugEnabled } from "../env.js";
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
+import { attachedBranchKbPath, updateAttachedBranchStamp, } from "../server/session.js";
+import { readBranchKbStamp } from "../server/kb-freshness.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
 const entitySchemaRecord = entitySchema;
@@ -46,79 +50,164 @@ const validateEntity = ajv.compile({
                 "legacy-link",
             ],
         },
+        symbol_role: {
+            type: "string",
+            enum: [...SYMBOL_ROLES],
+        },
     },
 });
 const validateRelationship = ajv.compile(relationshipSchema);
-const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
-    "implements",
-    "covered_by",
-    "executable_for",
-]);
-const ALLOWED_GRANULARITY_REASONS = new Set([
-    "config-artifact",
-    "module-level-behavior",
-    "extractor-miss",
-    "legacy-link",
+const PROPERTY_ALIAS_HINTS = new Map([
+    ["subjectKey", "subject_key"],
+    ["propertyKey", "property_key"],
+    ["predicateName", "predicate_name"],
+    ["predicateArgs", "predicate_args"],
+    ["canonicalKey", "canonical_key"],
+    ["closedWorld", "closed_world"],
 ]);
-/**
- * Handle kb.upsert tool calls
- * Accepts { type, id, properties } — the flat format matching the tool schema.
- * Validates the assembled entity against JSON Schema before Prolog writes.
- * implements REQ-002, REQ-011
- */
-export async function handleKbUpsert(prolog, args) {
-    const { type, id, properties, relationships = [] } = args;
-    if (!type || !id) {
-        throw new Error("'type' and 'id' are required for upsert");
+const PROPERTY_VALUE_FIELDS = [
+    "value_string",
+    "value_int",
+    "value_number",
+    "value_bool",
+];
+function valueFieldHint(value) {
+    if (typeof value === "boolean") {
+        return `Use value_type: "bool" plus value_bool: ${String(value)}.`;
     }
-    // Assemble full entity from flat args + properties
-    const entity = {
-        id,
-        type,
-        ...properties,
-    };
-    // Fill in defaults for optional required fields
-    if (!entity.created_at) {
-        entity.created_at = new Date().toISOString();
+    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 (!entity.updated_at) {
-        entity.updated_at = new Date().toISOString();
+    if (typeof value === "string") {
+        return `Use value_type: "string" plus value_string: ${JSON.stringify(value)}.`;
     }
-    if (!entity.source) {
-        entity.source = "mcp://kibi/upsert";
+    return "Use value_type plus exactly one of value_string, value_int, value_number, or value_bool.";
+}
+function ajvErrorParams(error) {
+    return error.params;
+}
+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 presentValueFields = PROPERTY_VALUE_FIELDS.filter((field) => entity[field] !== undefined);
+        const hints = [];
+        if (missing.length > 0) {
+            hints.push(`fact_kind 'property_value' requires ${missing.join(", ")}.`);
+        }
+        if (presentValueFields.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;
     }
-    const entities = [entity];
-    // Validate all entities
-    for (let i = 0; i < entities.length; i++) {
-        const ent = entities[i];
-        if (!validateEntity(ent)) {
-            const errors = validateEntity.errors || [];
-            const errorMessages = errors
-                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
-                .join("; ");
-            throw new Error(`Entity validation failed: ${errorMessages}`);
+    if (entity.fact_kind === "predicate") {
+        const predicateArgs = entity.predicate_args;
+        const hasPredicateArgs = Array.isArray(predicateArgs) && predicateArgs.length > 0;
+        const missing = [
+            ...(entity.predicate_name === undefined ? ["predicate_name"] : []),
+            ...(!hasPredicateArgs ? ["predicate_args"] : []),
+            ...(entity.canonical_key === undefined ? ["canonical_key"] : []),
+        ];
+        const hints = [];
+        if (missing.length > 0) {
+            hints.push(`fact_kind 'predicate' requires ${missing.join(", ")}.`);
+        }
+        if (hints.length > 0) {
+            hints.push("Next action: call kb_suggest_predicates before hand-writing ontology predicate facts.");
         }
+        return hints;
     }
-    // Validate all relationships
-    for (let i = 0; i < relationships.length; i++) {
-        const rel = relationships[i];
-        if (!validateRelationship(rel)) {
-            const errors = validateRelationship.errors || [];
-            const errorMessages = errors
-                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
-                .join("; ");
-            throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
+    return [];
+}
+function formatEntityValidationErrors(entity, errors) {
+    const messages = errors.map((error) => {
+        const path = error.instancePath || "root";
+        const params = ajvErrorParams(error);
+        if (error.keyword === "additionalProperties" && params.additionalProperty) {
+            const property = params.additionalProperty;
+            const suggested = PROPERTY_ALIAS_HINTS.get(property);
+            if (property === "value") {
+                return `${path}: unknown property 'value'. ${valueFieldHint(entity.value)} Do not use generic value in kb_upsert.properties.`;
+            }
+            if (suggested) {
+                return `${path}: unknown property '${property}'. Did you mean '${suggested}'? kb_upsert.properties uses snake_case typed fact fields.`;
+            }
+        }
+        if (error.keyword === "enum" && params.allowedValues) {
+            return `${path}: ${error.message}. Allowed values: ${params.allowedValues.map(String).join(", ")}`;
+        }
+        return `${path}: ${error.message}`;
+    });
+    const extraHints = factKindShapeHints(entity);
+    for (const [alias, canonical] of PROPERTY_ALIAS_HINTS) {
+        if (Object.prototype.hasOwnProperty.call(entity, alias)) {
+            extraHints.push(`Unknown property '${alias}'. Use '${canonical}' in kb_upsert.properties.`);
         }
     }
-    validateRelationshipSources(id, relationships);
-    validateSymbolGranularity(entity, relationships);
-    // Validate strict-lane fact_kind pairing for constrains/requires_property
-    // implements REQ-011
-    await validateStrictLanePairing(prolog, relationships);
+    if (Object.prototype.hasOwnProperty.call(entity, "value")) {
+        extraHints.push(valueFieldHint(entity.value));
+    }
+    if (Object.keys(entity).some((key) => PROPERTY_ALIAS_HINTS.has(key)) ||
+        Object.prototype.hasOwnProperty.call(entity, "value")) {
+        extraHints.push("Next action: if starting from prose, call kb_model_requirement and apply its sequential applyPlan instead of guessing field names.");
+    }
+    return [...messages, ...extraHints].join("; ");
+}
+function validateFactModelingShape(entity) {
+    const hints = factKindShapeHints(entity);
+    if (hints.length > 0) {
+        throw new Error(`Entity validation failed: ${hints.join("; ")}`);
+    }
+}
+/**
+ * Handle kb.upsert tool calls
+ * Accepts { type, id, properties } — the flat format matching the tool schema.
+ * Validates the assembled entity against JSON Schema before Prolog writes.
+ * implements REQ-002, REQ-011
+ */
+export async function handleKbUpsert(prolog, args) {
+    const { entity, relationships } = validateKbUpsertArgs(args);
+    const semanticAdvisor = analyzeSemanticAdvisorInput({
+        payload: { ...args },
+    });
+    const type = entity.type;
+    const entities = [entity];
+    // If relationships are not explicitly provided, preserve existing ones.
+    // This prevents accidental relationship loss when updating only properties.
+    let effectiveRelationships = relationships;
     let created = 0;
     let updated = 0;
     let relationshipsCreated = 0;
     try {
+        if ((args.relationships === undefined ||
+            (Array.isArray(args.relationships) && args.relationships.length === 0)) &&
+            args.id) {
+            // Preserve relationships on updates when the request omits relationships
+            // OR provides an empty array. This avoids accidental edge deletion by
+            // clients that always serialize `relationships: []` for partial updates.
+            // For creates, this remains cheap because existence is checked first.
+            const existsResult = await prolog.query(`once(kb_entity('${escapeAtom(args.id)}', _, _))`);
+            if (existsResult.success) {
+                const existing = await fetchExistingRelationships(prolog, args.id);
+                if (existing.length > 0) {
+                    effectiveRelationships = existing;
+                }
+            }
+        }
+        // Validate strict-lane fact_kind pairing for constrains/requires_property
+        // implements REQ-011
+        await validateStrictLanePairing(prolog, effectiveRelationships);
         // Process entities
         for (const entity of entities) {
             const id = entity.id;
@@ -131,7 +220,7 @@ export async function handleKbUpsert(prolog, args) {
             const props = buildPropertyList(entity);
             // Build relationship goals
             const relationshipGoals = [];
-            for (const rel of relationships) {
+            for (const rel of effectiveRelationships) {
                 const relType = rel.type;
                 const from = rel.from;
                 const to = rel.to;
@@ -172,7 +261,7 @@ export async function handleKbUpsert(prolog, args) {
                 throw new Error(formattedError);
             }
             await recordEntityAudit(prolog, isUpdate ? "updated" : "created", type, entity);
-            for (const rel of relationships) {
+            for (const rel of effectiveRelationships) {
                 await recordRelationshipAudit(prolog, rel);
             }
             // Update counters
@@ -182,7 +271,7 @@ export async function handleKbUpsert(prolog, args) {
             else {
                 created++;
             }
-            relationshipsCreated += relationships.length;
+            relationshipsCreated += effectiveRelationships.length;
         }
         // Save KB to disk after all entities/relationships are written to ensure
         // durability across process restarts.
@@ -191,28 +280,43 @@ export async function handleKbUpsert(prolog, args) {
         if (!saveResult.success) {
             throw new Error(`Failed to save KB after upsert: ${saveResult.error || "Unknown error"}`);
         }
+        // Update session stamp so kb_check (and other tools) don't trigger a
+        // stale-detach refresh that would unload the just-saved runtime state.
+        if (attachedBranchKbPath) {
+            try {
+                const freshStamp = await readBranchKbStamp(attachedBranchKbPath);
+                updateAttachedBranchStamp(freshStamp);
+            }
+            catch {
+                // Non-fatal: stamp update is best-effort to avoid spurious refresh.
+            }
+        }
         if (type === "symbol") {
             try {
-                await refreshCoordinatesForSymbolIdImpl(id);
+                await refreshCoordinatesForSymbolIdImpl(entity.id);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 if (isMcpDebugEnabled()) {
-                    console.warn(`[KIBI-MCP] Symbol coordinate auto-refresh failed for ${id}: ${message}`);
+                    console.warn(`[KIBI-MCP] Symbol coordinate auto-refresh failed for ${String(entity.id)}: ${message}`);
                 }
             }
         }
+        // Check for scenario-coverage guidance
+        const coverageWarnings = await checkScenarioCoverageGuidance(prolog, relationships, type, entity.id);
         return {
             content: [
                 {
                     type: "text",
-                    text: `Upserted ${id} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
+                    text: `Upserted ${String(entity.id)} (${created > 0 ? "created" : "updated"}) with ${relationshipsCreated} relationship(s).`,
                 },
             ],
             structuredContent: {
                 created,
                 updated,
                 relationships_created: relationshipsCreated,
+                warnings: [...semanticAdvisor.warnings, ...coverageWarnings],
+                semanticAdvisor: semanticAdvisor.receipt,
             },
         };
     }
@@ -221,6 +325,45 @@ export async function handleKbUpsert(prolog, args) {
         throw new Error(`Upsert execution failed: ${message}`);
     }
 }
+export function validateKbUpsertArgs(args) {
+    const { type, id, properties, relationships = [] } = args;
+    if (!type || !id) {
+        throw new Error("'type' and 'id' are required for upsert");
+    }
+    const entity = {
+        id,
+        type,
+        ...properties,
+    };
+    if (!entity.created_at) {
+        entity.created_at = new Date().toISOString();
+    }
+    if (!entity.updated_at) {
+        entity.updated_at = new Date().toISOString();
+    }
+    if (!entity.source) {
+        entity.source = "mcp://kibi/upsert";
+    }
+    if (!validateEntity(entity)) {
+        const errors = validateEntity.errors || [];
+        const errorMessages = formatEntityValidationErrors(entity, errors);
+        throw new Error(`Entity validation failed: ${errorMessages}`);
+    }
+    validateFactModelingShape(entity);
+    for (let i = 0; i < relationships.length; i++) {
+        const rel = relationships[i];
+        if (!validateRelationship(rel)) {
+            const errors = validateRelationship.errors || [];
+            const errorMessages = errors
+                .map((e) => `${e.instancePath || "root"}: ${e.message}`)
+                .join("; ");
+            throw new Error(`Relationship validation failed at index ${i}: ${errorMessages}`);
+        }
+    }
+    validateRelationshipSources(id, relationships);
+    validateSymbolGranularity(entity, relationships);
+    return { entity, relationships };
+}
 function chooseScriptKind(filePath) {
     const lower = filePath.toLowerCase();
     if (lower.endsWith(".tsx"))
@@ -235,58 +378,69 @@ function chooseScriptKind(filePath) {
     return ScriptKind.JS;
 }
 function hasTraceabilityRelationship(relationships) {
-    return relationships.some((relationship) => typeof relationship.type === "string" &&
-        TRACEABILITY_RELATIONSHIP_TYPES.has(relationship.type));
+    return relationships.some((relationship) => isTraceabilityRelationshipType(relationship.type));
 }
 function hasAllowedGranularityReason(entity) {
-    const reason = entity.granularity_reason;
-    return typeof reason === "string" && ALLOWED_GRANULARITY_REASONS.has(reason);
+    return isAllowedGranularityReason(entity.granularity_reason);
 }
-function collectNarrowExportNames(filePath, content) {
+function createSymbolCandidate(name, kind) {
+    return {
+        name,
+        kind,
+        role: inferSymbolRole(kind),
+    };
+}
+function collectGranularSymbolCandidates(filePath, content) {
     const project = new Project({ skipAddingFilesFromTsConfig: true });
     const sourceFile = project.createSourceFile(`${filePath}::granularity`, content, {
         overwrite: true,
         scriptKind: chooseScriptKind(filePath),
     });
-    const names = new Set();
+    const candidates = [];
     const methodNameCounts = new Map();
+    const bareMethodCandidates = new Map();
     for (const fn of sourceFile.getFunctions()) {
         if (fn.isExported()) {
             const name = fn.getName();
             if (name)
-                names.add(name);
+                candidates.push(createSymbolCandidate(name, "function"));
         }
     }
     for (const cls of sourceFile.getClasses()) {
         if (cls.isExported()) {
             const name = cls.getName();
             if (name)
-                names.add(name);
+                candidates.push(createSymbolCandidate(name, "class"));
             for (const method of cls.getMethods()) {
                 const methodName = method.getName();
-                if (name)
-                    names.add(`${name}.${methodName}`);
+                if (name) {
+                    candidates.push(createSymbolCandidate(`${name}.${methodName}`, "method"));
+                }
+                bareMethodCandidates.set(methodName, createSymbolCandidate(methodName, "method"));
                 methodNameCounts.set(methodName, (methodNameCounts.get(methodName) ?? 0) + 1);
             }
         }
     }
     for (const [methodName, count] of methodNameCounts) {
-        if (count === 1)
-            names.add(methodName);
+        const candidate = bareMethodCandidates.get(methodName);
+        if (count === 1 && candidate)
+            candidates.push(candidate);
     }
     for (const iface of sourceFile.getInterfaces()) {
-        if (iface.isExported())
-            names.add(iface.getName());
+        if (iface.isExported()) {
+            candidates.push(createSymbolCandidate(iface.getName(), "interface"));
+        }
     }
     for (const alias of sourceFile.getTypeAliases()) {
-        if (alias.isExported())
-            names.add(alias.getName());
+        if (alias.isExported()) {
+            candidates.push(createSymbolCandidate(alias.getName(), "type"));
+        }
     }
     for (const en of sourceFile.getEnums()) {
         if (en.isExported())
-            names.add(en.getName());
+            candidates.push(createSymbolCandidate(en.getName(), "enum"));
     }
-    return [...names].sort();
+    return candidates.sort((a, b) => a.name.localeCompare(b.name));
 }
 function validateSymbolGranularity(entity, relationships) {
     if (entity.type !== "symbol")
@@ -304,12 +458,29 @@ function validateSymbolGranularity(entity, relationships) {
         : path.resolve(process.cwd(), entity.sourceFile);
     if (!existsSync(sourcePath))
         return;
-    const narrowNames = collectNarrowExportNames(entity.sourceFile, readFileSync(sourcePath, "utf8"));
-    if (narrowNames.length === 0)
+    const candidates = collectGranularSymbolCandidates(entity.sourceFile, readFileSync(sourcePath, "utf8"));
+    const candidateNames = [
+        ...new Set(candidates.map((candidate) => candidate.name)),
+    ];
+    if (candidateNames.includes(entity.title))
         return;
-    if (narrowNames.includes(entity.title))
+    const behavioralNames = getBehavioralSymbolNames(candidates);
+    if (behavioralNames.length === 0)
         return;
-    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available: ${narrowNames.join(", ")}. Move relationships to the narrow symbol or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.`);
+    const nonBehavioralNames = getNonBehavioralSymbolNames(candidates);
+    const maxNamesInMessage = 10;
+    const shownBehavioral = behavioralNames.slice(0, maxNamesInMessage);
+    const hiddenBehavioralCount = behavioralNames.length - shownBehavioral.length;
+    const behavioralList = shownBehavioral.join(", ") +
+        (hiddenBehavioralCount > 0 ? `, and ${hiddenBehavioralCount} more` : "");
+    const shownNonBehavioral = nonBehavioralNames.slice(0, maxNamesInMessage);
+    const hiddenNonBehavioralCount = nonBehavioralNames.length - shownNonBehavioral.length;
+    const nonBehavioralList = shownNonBehavioral.join(", ") +
+        (hiddenNonBehavioralCount > 0 ? `, and ${hiddenNonBehavioralCount} more` : "");
+    const ignoredSymbolsMessage = nonBehavioralNames.length > 0
+        ? ` Non-behavioral symbols in the file were ignored for this decision: ${nonBehavioralList}.`
+        : "";
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${behavioralList}. 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.${ignoredSymbolsMessage}`);
 }
 export const __test__ = {
     // implements REQ-vscode-traceability
@@ -333,6 +504,7 @@ function buildPropertyList(entity) {
         "owner",
         "priority",
         "severity",
+        "symbol_role",
         // Typed fact enum fields must be atoms for Prolog validation
         "fact_kind",
         "operator",
@@ -446,6 +618,103 @@ async function validateStrictLanePairing(prolog, relationships) {
         }
     }
 }
+/**
+ * Check for scenario-coverage guidance when verified_by is added to a
+ * requirement that already has scenarios (specified_by relationships).
+ * Returns non-blocking warnings; never throws.
+ */
+async function checkScenarioCoverageGuidance(prolog, relationships, entityType, entityId) {
+    const warnings = [];
+    if (entityType !== "req")
+        return warnings;
+    try {
+        for (const rel of relationships) {
+            const relType = rel.type;
+            if (relType !== "verified_by")
+                continue;
+            // Check if this requirement has scenarios
+            const scenarioQuery = `kb_relationship(specified_by, '${escapeAtom(entityId)}', ScenarioId)`;
+            const scenarioResult = await prolog.query(`once(${scenarioQuery})`);
+            if (scenarioResult.success) {
+                warnings.push(`Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`);
+                break; // One warning per entity is enough
+            }
+        }
+    }
+    catch {
+        // Non-blocking: never fail the upsert
+    }
+    return warnings;
+}
+/**
+ * Query existing relationships for an entity from the live KB.
+ * Used to preserve relationships when the upsert request omits the
+ * relationships field (entity-only property update).
+ */
+async function fetchExistingRelationships(prolog, entityId) {
+    const relTypes = [
+        "depends_on", "specified_by", "verified_by", "validates",
+        "implements", "covered_by", "executable_for", "constrained_by",
+        "constrains", "requires_property", "requires_predicate",
+        "guards", "publishes", "consumes", "supersedes", "relates_to",
+    ];
+    const existing = [];
+    try {
+        for (const relType of relTypes) {
+            const forwardGoal = `findall(To, kb_relationship(${relType}, '${escapeAtom(entityId)}', To), Targets)`;
+            const forwardResult = await prolog.query(forwardGoal);
+            if (forwardResult.success && forwardResult.bindings.Targets) {
+                const targetsStr = forwardResult.bindings.Targets;
+                const targets = parsePrologList(targetsStr);
+                for (const to of targets) {
+                    existing.push({ type: relType, from: entityId, to });
+                }
+            }
+            const reverseGoal = `findall(From, kb_relationship(${relType}, From, '${escapeAtom(entityId)}'), Sources)`;
+            const reverseResult = await prolog.query(reverseGoal);
+            if (reverseResult.success && reverseResult.bindings.Sources) {
+                const sourcesStr = reverseResult.bindings.Sources;
+                const sources = parsePrologList(sourcesStr);
+                for (const from of sources) {
+                    existing.push({ type: relType, from, to: entityId });
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Best-effort: if we can't read existing relationships, proceed without them.
+        // This preserves backward compatibility and avoids breaking mocked tests.
+    }
+    return existing;
+}
+function parsePrologList(listStr) {
+    const trimmed = listStr.trim();
+    if (trimmed === "[]")
+        return [];
+    const match = trimmed.match(/^\[(.*)\]$/s);
+    if (!match || !match[1])
+        return [];
+    const content = match[1];
+    const items = [];
+    let depth = 0;
+    let current = "";
+    for (const char of content) {
+        if (char === "[")
+            depth++;
+        if (char === "]")
+            depth--;
+        if (char === "," && depth === 0) {
+            items.push(current.trim().replace(/^'|'$/g, ""));
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim()) {
+        items.push(current.trim().replace(/^'|'$/g, ""));
+    }
+    return items;
+}
 /**
  * Record audit entry for a successfully committed entity mutation.
  * Called only after the RDF transaction succeeds.

package/dist/tools/validate-upsert.js

@@ -0,0 +1,43 @@
+import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
+import { validateKbUpsertArgs } from "./upsert.js";
+export async function handleKbValidateUpsert(args) {
+    try {
+        const { entity } = validateKbUpsertArgs(args);
+        const semanticAdvisor = analyzeSemanticAdvisorInput({
+            payload: { ...args },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "kb_validate_upsert: payload is valid for kb_upsert preflight checks. No mutation was performed.",
+                },
+            ],
+            structuredContent: {
+                valid: true,
+                errors: [],
+                warnings: semanticAdvisor.warnings,
+                semanticAdvisor: semanticAdvisor.receipt,
+                normalizedPreview: entity,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `kb_validate_upsert: payload is invalid. ${message}`,
+                },
+            ],
+            structuredContent: {
+                valid: false,
+                errors: [message],
+                warnings: [],
+                semanticAdvisor: null,
+                normalizedPreview: null,
+            },
+        };
+    }
+}