@kweaver-ai/kweaver-sdk 0.7.3 → 0.7.4

package/dist/client.js

@@ -14,6 +14,7 @@ import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
 import { ToolboxesResource } from "./resources/toolboxes.js";
 import { VegaResource } from "./resources/vega.js";
+import { ModelsResource } from "./resources/models.js";
 // ── KWeaverClient ─────────────────────────────────────────────────────────────
 /**
  * Main entry point for the KWeaver TypeScript SDK.
@@ -67,6 +68,8 @@ export class KWeaverClient {
     skills;
     /** Toolbox / tool management plus execute & debug invocation. */
     toolboxes;
+    /** Model factory (mf-model-manager CRUD + mf-model-api chat / embedding / rerank). */
+    models;
     constructor(opts = {}) {
         const envDomain = process.env.KWEAVER_BUSINESS_DOMAIN;
         if (opts.auth === false && opts.config) {
@@ -101,6 +104,7 @@ export class KWeaverClient {
             this.vega = new VegaResource(this);
             this.skills = new SkillsResource(this);
             this.toolboxes = new ToolboxesResource(this);
+            this.models = new ModelsResource(this);
             return;
         }
         if (opts.config) {
@@ -156,6 +160,7 @@ export class KWeaverClient {
         this.vega = new VegaResource(this);
         this.skills = new SkillsResource(this);
         this.toolboxes = new ToolboxesResource(this);
+        this.models = new ModelsResource(this);
     }
     /**
      * Async factory that auto-refreshes expired or revoked tokens.

package/dist/commands/agent.d.ts

@@ -65,8 +65,14 @@ export interface AgentHistoryOptions {
 }
 export declare function parseAgentHistoryArgs(args: string[]): AgentHistoryOptions;
 export interface AgentTraceOptions {
-    agentId: string;
+    /** Optional. Retained as positional arg for backward compatibility; trace-ai keys by conversation_id only. */
+    agentId?: string;
     conversationId: string;
+    view: "tree" | "perf" | "evidence" | "reasoning" | "all";
+    /** When true, emit raw JSON of the TracesByConversationResult instead of a rendered view. */
+    json: boolean;
+    /** Disable per-message truncation in the reasoning view. */
+    full: boolean;
     pretty: boolean;
 }
 export declare function parseAgentTraceArgs(args: string[]): AgentTraceOptions;

package/dist/commands/agent.js

@@ -468,21 +468,43 @@ export function parseAgentHistoryArgs(args) {
     const finalConversationId = optionStartIndex === 2 ? args[1] : args[0];
     return { agentId: finalAgentId, conversationId: finalConversationId, businessDomain, pretty, limit };
 }
+const TRACE_VIEWS = new Set(["tree", "perf", "evidence", "reasoning", "all"]);
 export function parseAgentTraceArgs(args) {
-    const agentId = args[0];
-    if (!agentId || agentId.startsWith("-")) {
-        throw new Error("Missing agent_id");
-    }
-    const conversationId = args[1];
-    if (!conversationId || conversationId.startsWith("-")) {
-        throw new Error("Missing conversation_id");
-    }
+    const positional = [];
+    let view = "tree";
+    let json = false;
+    let full = false;
     let pretty = true;
-    for (let i = 2; i < args.length; i += 1) {
+    for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h") {
             throw new Error("help");
         }
+        if (arg === "--view") {
+            const next = args[i + 1];
+            if (!next || !TRACE_VIEWS.has(next)) {
+                throw new Error(`--view requires one of: tree, perf, evidence, reasoning, all`);
+            }
+            view = next;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--view=")) {
+            const value = arg.slice("--view=".length);
+            if (!TRACE_VIEWS.has(value)) {
+                throw new Error(`--view requires one of: tree, perf, evidence, reasoning, all`);
+            }
+            view = value;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--full") {
+            full = true;
+            continue;
+        }
         if (arg === "--pretty") {
             pretty = true;
             continue;
@@ -491,9 +513,26 @@ export function parseAgentTraceArgs(args) {
             pretty = false;
             continue;
         }
-        throw new Error(`Unsupported agent trace argument: ${arg}`);
+        if (arg.startsWith("-")) {
+            throw new Error(`Unsupported agent trace argument: ${arg}`);
+        }
+        positional.push(arg);
+    }
+    // Backward-compat: legacy form is `trace <agent_id> <conversation_id>`.
+    // New form: `trace <conversation_id>`. We disambiguate by argument count.
+    let agentId;
+    let conversationId;
+    if (positional.length === 0) {
+        throw new Error("Missing conversation_id");
+    }
+    else if (positional.length === 1) {
+        conversationId = positional[0];
     }
-    return { agentId, conversationId, pretty };
+    else {
+        agentId = positional[0];
+        conversationId = positional[1];
+    }
+    return { agentId, conversationId, view, json, full, pretty };
 }
 export async function runAgentCommand(args) {
     const [subcommand, ...rest] = args;
@@ -520,7 +559,8 @@ Subcommands:
   skill <verb> ...                   Manage skills attached to an agent (add/remove/list)
   sessions <agent_id>                List all conversations for an agent
   history <agent_id> <conversation_id> Show message history for a conversation
-  trace <agent_id> <conversation_id>  Get trace data for a conversation`);
+  trace <conversation_id> [--view tree|perf|evidence|reasoning|all] [--json]
+                                       Get trace data for a conversation`);
         return Promise.resolve(0);
     }
     const dispatch = async () => {
@@ -724,13 +764,16 @@ Options:
     }
     if (subcommand === "trace") {
         if (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) {
-            console.log(`kweaver agent trace <agent_id> <conversation_id> [options]
+            console.log(`kweaver agent trace <conversation_id> [options]
+       kweaver agent trace <agent_id> <conversation_id> [options]   (legacy)
 
 Get trace data for a conversation.
 
 Options:
-  --pretty                  Pretty-print JSON output (default)
-  --compact                 Compact JSON output`);
+  --view tree|perf|evidence|reasoning|all   Render style (default: tree)
+  --json                          Emit raw TracesByConversationResult JSON
+  --pretty                        Pretty-print JSON output (default)
+  --compact                       Compact JSON output`);
             return 0;
         }
     }
@@ -1031,13 +1074,18 @@ async function runAgentTraceCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver agent trace <agent_id> <conversation_id> [options]
+            console.log(`kweaver agent trace <conversation_id> [options]
+       kweaver agent trace <agent_id> <conversation_id> [options]   (legacy)
 
-Get trace data for a conversation.
+Get trace data for a conversation. Spans are fetched from trace-ai via a 2-jump
+lookup that recovers pipeline spans (HTTP entry, internal RPCs, prompt-build)
+which the simpler /by-conversation endpoint omits.
 
 Options:
-  --pretty                  Pretty-print JSON output (default)
-  --compact                 Compact JSON output`);
+  --view tree|perf|evidence|reasoning|all   Render style (default: tree)
+  --json                          Emit raw TracesByConversationResult JSON
+  --pretty                        Pretty-print JSON output (default)
+  --compact                       Compact JSON output`);
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1045,13 +1093,19 @@ Options:
     }
     try {
         const token = await ensureValidToken();
-        const body = await getTracesByConversation({
+        const result = await getTracesByConversation({
             baseUrl: token.baseUrl,
             accessToken: token.accessToken,
             agentId: options.agentId,
             conversationId: options.conversationId,
         });
-        console.log(formatCallOutput(body, options.pretty));
+        if (options.json) {
+            console.log(formatCallOutput(JSON.stringify(result), options.pretty));
+        }
+        else {
+            const { formatTraceResult } = await import("../utils/trace-views.js");
+            console.log(formatTraceResult(result, options.view, { full: options.full }));
+        }
         return 0;
     }
     catch (error) {

package/dist/commands/bkn-metric.d.ts

@@ -0,0 +1 @@
+export declare function runKnMetricCommand(args: string[]): Promise<number>;

package/dist/commands/bkn-metric.js

@@ -0,0 +1,406 @@
+import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
+import { listMetrics, createMetrics, searchMetrics, validateMetrics, getMetric, updateMetric, deleteMetric, getMetrics, deleteMetrics, } from "../api/bkn-metrics.js";
+import { metricQueryData, metricDryRun } from "../api/ontology-query-metrics.js";
+import { formatCallOutput } from "./call.js";
+import { resolveBusinessDomain } from "../config/store.js";
+import { parseJsonObject, parseSearchAfterArray, confirmYes } from "./bkn-utils.js";
+function parseCommaSeparatedIds(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+const METRIC_HELP = `kweaver bkn metric <action> [args] [--pretty] [-bd <domain>]
+
+Management (bkn-backend):
+  list <kn-id> [--limit <n>] [--branch <b>] [--name-pattern <p>] [--sort update_time|name] [--direction asc|desc] [--offset <n>] [--tag <t>] [--group-id <id>]
+  get <kn-id> <metric-id(s)> [--branch <b>]   (comma-separated for multiple)
+  create <kn-id> '<json>'  [--branch] [--strict-mode true|false]
+  search <kn-id> '<json>'  [--branch] [--strict-mode] [--limit <n>] [--search-after '<json>']
+  validate <kn-id> '<json>'  [--branch] [--strict-mode] [--import-mode normal|ignore|overwrite]
+  update <kn-id> <metric-id> '<json>'  [--branch] [--strict-mode]
+  delete <kn-id> <metric-id(s)> [-y]   (comma-separated for multiple)
+
+Query (ontology-query):
+  query <kn-id> <metric-id> ['<json-body>']  [--branch] [--fill-null]
+  dry-run <kn-id> '<json>'  [--branch] [--fill-null]
+
+  list: default --limit 30. search/query JSON: default limit 50 in body when not set.`;
+function parseListArgs(args) {
+    let pretty = true;
+    let businessDomain = "";
+    let limit = 30;
+    let branch;
+    let namePattern;
+    let sort;
+    let direction;
+    let offset;
+    let tag;
+    let groupId;
+    const pos = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--help" || a === "-h")
+            throw new Error("help");
+        if (a === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if ((a === "-bd" || a === "--biz-domain") && args[i + 1]) {
+            businessDomain = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--limit" && args[i + 1]) {
+            const n = parseInt(args[i + 1], 10);
+            if (Number.isNaN(n) || n < 1)
+                throw new Error("Invalid --limit");
+            limit = n;
+            i += 1;
+            continue;
+        }
+        if (a === "--branch" && args[i + 1]) {
+            branch = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--name-pattern" && args[i + 1]) {
+            namePattern = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--sort" && args[i + 1]) {
+            const s = args[i + 1];
+            if (s !== "update_time" && s !== "name")
+                throw new Error("--sort must be update_time|name");
+            sort = s;
+            i += 1;
+            continue;
+        }
+        if (a === "--direction" && args[i + 1]) {
+            const d = args[i + 1];
+            if (d !== "asc" && d !== "desc")
+                throw new Error("--direction must be asc|desc");
+            direction = d;
+            i += 1;
+            continue;
+        }
+        if (a === "--offset" && args[i + 1]) {
+            offset = parseInt(args[i + 1], 10);
+            i += 1;
+            continue;
+        }
+        if (a === "--tag" && args[i + 1]) {
+            tag = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--group-id" && args[i + 1]) {
+            groupId = args[i + 1];
+            i += 1;
+            continue;
+        }
+        pos.push(a);
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    const [knId] = pos;
+    if (!knId)
+        throw new Error("Usage: kweaver bkn metric list <kn-id> [options]");
+    return {
+        knId,
+        limit,
+        pretty,
+        businessDomain,
+        branch,
+        namePattern,
+        sort,
+        direction,
+        offset,
+        tag,
+        groupId,
+    };
+}
+function parseCommonKnFlags(rest, withYes) {
+    let pretty = true;
+    let businessDomain = "";
+    let branch;
+    let strictMode;
+    let importMode;
+    let fillNull;
+    let yes = false;
+    const out = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const a = rest[i];
+        if (a === "--help" || a === "-h")
+            throw new Error("help");
+        if (a === "--pretty") {
+            pretty = true;
+            continue;
+        }
+        if (withYes && (a === "-y" || a === "--yes")) {
+            yes = true;
+            continue;
+        }
+        if ((a === "-bd" || a === "--biz-domain") && rest[i + 1]) {
+            businessDomain = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--branch" && rest[i + 1]) {
+            branch = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (a === "--strict-mode" && rest[i + 1]) {
+            strictMode = rest[i + 1] === "true" || rest[i + 1] === "1";
+            i += 1;
+            continue;
+        }
+        if (a === "--import-mode" && rest[i + 1]) {
+            const m = rest[i + 1];
+            if (m !== "normal" && m !== "ignore" && m !== "overwrite") {
+                throw new Error("--import-mode must be normal|ignore|overwrite");
+            }
+            importMode = m;
+            i += 1;
+            continue;
+        }
+        if (a === "--fill-null") {
+            fillNull = true;
+            continue;
+        }
+        out.push(a);
+    }
+    if (!businessDomain)
+        businessDomain = resolveBusinessDomain();
+    return { filtered: out, pretty, businessDomain, branch, strictMode, importMode, fillNull, yes };
+}
+export async function runKnMetricCommand(args) {
+    const [action, ...rest] = args;
+    if (!action || action === "--help" || action === "-h") {
+        console.log(METRIC_HELP);
+        return 0;
+    }
+    try {
+        const token = await ensureValidToken();
+        const b = { baseUrl: token.baseUrl, accessToken: token.accessToken };
+        if (action === "list") {
+            const p = parseListArgs(rest);
+            const out = await listMetrics({
+                ...b,
+                knId: p.knId,
+                businessDomain: p.businessDomain,
+                limit: p.limit,
+                branch: p.branch,
+                namePattern: p.namePattern,
+                sort: p.sort,
+                direction: p.direction,
+                offset: p.offset,
+                tag: p.tag,
+                groupId: p.groupId,
+            });
+            console.log(formatCallOutput(out, p.pretty));
+            return 0;
+        }
+        if (action === "get") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, metricIdArg] = o.filtered;
+            if (!knId || !metricIdArg) {
+                console.error("Usage: kweaver bkn metric get <kn-id> <metric-id(s)> [options]");
+                return 1;
+            }
+            const ids = parseCommaSeparatedIds(metricIdArg);
+            if (ids.length === 0) {
+                console.error("metric-id(s): need at least one id");
+                return 1;
+            }
+            const out = ids.length === 1
+                ? await getMetric({ ...b, knId, businessDomain: o.businessDomain, metricId: ids[0], branch: o.branch })
+                : await getMetrics({ ...b, knId, businessDomain: o.businessDomain, metricIds: ids.join(","), branch: o.branch });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "create") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, bodyJson] = o.filtered;
+            if (!knId || !bodyJson) {
+                console.error("Usage: kweaver bkn metric create <kn-id> '<json>' [options]");
+                return 1;
+            }
+            const out = await createMetrics({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                body: bodyJson,
+                branch: o.branch,
+                strictMode: o.strictMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "search") {
+            let limit;
+            let searchAfter;
+            const r = [];
+            for (let i = 0; i < rest.length; i += 1) {
+                const a = rest[i];
+                if (a === "--limit" && rest[i + 1]) {
+                    limit = parseInt(rest[i + 1], 10);
+                    if (Number.isNaN(limit) || limit < 1)
+                        throw new Error("Invalid --limit");
+                    i += 1;
+                    continue;
+                }
+                if (a === "--search-after" && rest[i + 1]) {
+                    searchAfter = parseSearchAfterArray(rest[i + 1]);
+                    i += 1;
+                    continue;
+                }
+                r.push(a);
+            }
+            const o = parseCommonKnFlags(r, false);
+            const [knId, bodyText] = o.filtered;
+            if (!knId || !bodyText) {
+                console.error("Usage: kweaver bkn metric search <kn-id> '<json>' [options]");
+                return 1;
+            }
+            const obj = parseJsonObject(bodyText, "search body must be a JSON object.");
+            if (limit !== undefined)
+                obj.limit = limit;
+            if (searchAfter !== undefined)
+                obj.search_after = searchAfter;
+            if (typeof obj.limit !== "number" || !Number.isFinite(obj.limit)) {
+                obj.limit = 50;
+            }
+            const out = await searchMetrics({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                body: JSON.stringify(obj),
+                branch: o.branch,
+                strictMode: o.strictMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "validate") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, bodyJson] = o.filtered;
+            if (!knId || !bodyJson) {
+                console.error("Usage: kweaver bkn metric validate <kn-id> '<json>' [options]");
+                return 1;
+            }
+            const out = await validateMetrics({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                body: bodyJson,
+                branch: o.branch,
+                strictMode: o.strictMode,
+                importMode: o.importMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "update") {
+            const o = parseCommonKnFlags(rest, false);
+            const [knId, metricId, bodyJson] = o.filtered;
+            if (!knId || !metricId || !bodyJson) {
+                console.error("Usage: kweaver bkn metric update <kn-id> <metric-id> '<json>' [options]");
+                return 1;
+            }
+            const out = await updateMetric({
+                ...b,
+                knId,
+                businessDomain: o.businessDomain,
+                metricId,
+                body: bodyJson,
+                branch: o.branch,
+                strictMode: o.strictMode,
+            });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "delete") {
+            const o = parseCommonKnFlags(rest, true);
+            const [knId, metricIdArg] = o.filtered;
+            if (!knId || !metricIdArg) {
+                console.error("Usage: kweaver bkn metric delete <kn-id> <metric-id(s)> [-y]");
+                return 1;
+            }
+            const ids = parseCommaSeparatedIds(metricIdArg);
+            if (ids.length === 0) {
+                console.error("metric-id(s): need at least one id");
+                return 1;
+            }
+            if (!o.yes) {
+                const label = ids.length === 1 ? ids[0] : ids.join(",");
+                const ok = await confirmYes(`Delete metric(s) ${label}?`);
+                if (!ok) {
+                    console.log("Cancelled.");
+                    return 0;
+                }
+            }
+            const out = ids.length === 1
+                ? await deleteMetric({ ...b, knId, businessDomain: o.businessDomain, metricId: ids[0], branch: o.branch })
+                : await deleteMetrics({ ...b, knId, businessDomain: o.businessDomain, metricIds: ids.join(","), branch: o.branch });
+            console.log(formatCallOutput(out, o.pretty));
+            return 0;
+        }
+        if (action === "query") {
+            const o = parseCommonKnFlags(rest, false);
+            const { fillNull, branch, filtered, pretty, businessDomain } = o;
+            const [knId, metricId, bodyText = "{}"] = filtered;
+            if (!knId || !metricId) {
+                console.error("Usage: kweaver bkn metric query <kn-id> <metric-id> ['<json>'] [--branch] [--fill-null]");
+                return 1;
+            }
+            const body = parseJsonObject(bodyText, "metric query body must be a JSON object.");
+            if (typeof body.limit !== "number" || !Number.isFinite(body.limit)) {
+                body.limit = 50;
+            }
+            const out = await metricQueryData({
+                ...b,
+                knId,
+                businessDomain,
+                metricId,
+                body: JSON.stringify(body),
+                branch,
+                fillNull,
+            });
+            console.log(formatCallOutput(out, pretty));
+            return 0;
+        }
+        if (action === "dry-run") {
+            const o = parseCommonKnFlags(rest, false);
+            const { fillNull, branch, filtered, pretty, businessDomain } = o;
+            const [knId, bodyText] = filtered;
+            if (!knId || !bodyText) {
+                console.error("Usage: kweaver bkn metric dry-run <kn-id> '<json>' [--branch] [--fill-null]");
+                return 1;
+            }
+            parseJsonObject(bodyText, "dry-run body must be a JSON object.");
+            const out = await metricDryRun({
+                ...b,
+                knId,
+                businessDomain,
+                body: bodyText,
+                branch,
+                fillNull,
+            });
+            console.log(formatCallOutput(out, pretty));
+            return 0;
+        }
+        console.error(`Unknown bkn metric action: ${action}. Use --help.`);
+        return 1;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "help") {
+            console.log(METRIC_HELP);
+            return 0;
+        }
+        console.error(formatHttpError(error));
+        return 1;
+    }
+}

package/dist/commands/bkn-ops.js

@@ -13,7 +13,7 @@ import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createA
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
-import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, formatPkDetectionError, parsePkMap, confirmYes, } from "./bkn-utils.js";
+import { pollWithBackoff, detectDisplayKey, formatPkDetectionError, parsePkMap, resolvePrimaryKey, confirmYes, } from "./bkn-utils.js";
 // ── BKN object name validation ──────────────────────────────────────────────
 // Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
 // validateObjectName (driveradapters/validate.go:85). 40 utf-8 codepoints,
@@ -644,19 +644,25 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         }
         for (const t of targetTables) {
             const override = options.pkMap[t.name];
-            if (override) {
-                if (!t.columns.some((c) => c.name === override)) {
-                    throw new Error(`--pk-map specifies '${override}' for table '${t.name}', but no such column. ` +
-                        `Columns: ${t.columns.map((c) => c.name).join(", ")}`);
-                }
-                tablePks[t.name] = override;
+            if (override && !t.columns.some((c) => c.name === override)) {
+                throw new Error(`--pk-map specifies '${override}' for table '${t.name}', but no such column. ` +
+                    `Columns: ${t.columns.map((c) => c.name).join(", ")}`);
+            }
+            const resolution = resolvePrimaryKey(t, sampleRows?.[t.name], override);
+            if (resolution.pk) {
+                tablePks[t.name] = resolution.pk;
                 continue;
             }
-            const result = detectPrimaryKey(t, sampleRows?.[t.name]);
-            if (!result.pk) {
-                throw new Error(formatPkDetectionError(t.name, result));
+            if (resolution.source === "ambiguous") {
+                const cols = (resolution.ambiguous ?? []).join(", ");
+                throw new Error(`Table '${t.name}' has a composite PRIMARY KEY (${cols}). ` +
+                    `BKN object types take a single primary key — pick one with --pk-map ${t.name}:<column>.`);
             }
-            tablePks[t.name] = result.pk;
+            throw new Error(formatPkDetectionError(t.name, {
+                pk: null,
+                candidates: resolution.candidates ?? [],
+                sampleSize: resolution.sampleSize ?? 0,
+            }));
         }
         // Phase 1: Create DataViews for each table. findDataView is idempotent;
         // not tracked for rollback so a retry can reuse what's already there.