@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.3

package/dist/commands/bkn-ops.js

@@ -4,14 +4,36 @@ import { resolve } from "node:path";
 import { loadNetwork, allObjects, allRelations, allActions, generateChecksum, validateNetwork } from "@kweaver-ai/bkn";
 import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils/bkn-encoding.js";
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
-import { createKnowledgeNetwork, createObjectTypes, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
-import { listTablesWithColumns, scanMetadata, getDatasource } from "../api/datasources.js";
+import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
+import { listTablesWithColumns, scanDatasourceMetadata } from "../api/datasources.js";
 import { createDataView, findDataView } from "../api/dataviews.js";
+import { resolveFiles } from "./ds.js";
+import { buildTableName } from "./import-csv.js";
 import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createActionSchedule, updateActionSchedule, setActionScheduleStatus, deleteActionSchedules, listJobs, getJob, getJobTasks, deleteJobs, } from "../api/bkn-backend.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
-import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, confirmYes, } from "./bkn-utils.js";
+import { pollWithBackoff, detectPrimaryKey, detectDisplayKey, formatPkDetectionError, parsePkMap, 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,
+// non-empty. Backend rejects the whole batch on first violation, so we surface
+// every offender locally before any side-effecting call.
+export const BKN_OBJECT_NAME_MAX_LENGTH = 40;
+export function assertValidBknObjectNames(names, context) {
+    const offenders = [];
+    for (const name of names) {
+        const len = [...name].length;
+        if (len === 0 || len > BKN_OBJECT_NAME_MAX_LENGTH) {
+            offenders.push({ name, length: len });
+        }
+    }
+    if (offenders.length === 0)
+        return;
+    const lines = offenders.map((o) => `  - ${o.name} (${o.length} chars)`);
+    throw new Error(`${context}: ${offenders.length} name(s) violate BKN object-name limit ` +
+        `(1..${BKN_OBJECT_NAME_MAX_LENGTH} utf-8 chars):\n${lines.join("\n")}`);
+}
 // ── Build ───────────────────────────────────────────────────────────────────
 const KN_BUILD_HELP = `kweaver bkn build <kn-id> [options]
 
@@ -458,19 +480,24 @@ Create a knowledge network from a datasource (dataviews + object types + optiona
 Options:
   --name <s>       Knowledge network name (required)
   --tables <a,b>   Comma-separated table names (default: all)
+  --pk-map <s>     Explicit primary keys: <table>:<field>[,<table>:<field>...]
+                   Required when auto-detection fails (no unique column in sample)
   --build (default)  Build after creation
   --no-build       Skip build after creation
   --timeout <n>    Build timeout in seconds (default: 300)
+  --no-rollback    Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain  Business domain (default: bd_public)
   --pretty         Pretty-print output (default)`;
 export function parseKnCreateFromDsArgs(args) {
     let dsId = "";
     let name = "";
     let tablesStr = "";
+    let pkMapStr = "";
     let build = true;
     let timeout = 300;
     let businessDomain = "";
     let pretty = true;
+    let noRollback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -483,6 +510,10 @@ export function parseKnCreateFromDsArgs(args) {
             tablesStr = args[++i];
             continue;
         }
+        if (arg === "--pk-map" && args[i + 1]) {
+            pkMapStr = args[++i];
+            continue;
+        }
         if (arg === "--build") {
             build = true;
             continue;
@@ -491,6 +522,10 @@ export function parseKnCreateFromDsArgs(args) {
             build = false;
             continue;
         }
+        if (arg === "--no-rollback") {
+            noRollback = true;
+            continue;
+        }
         if (arg === "--timeout" && args[i + 1]) {
             timeout = parseInt(args[++i], 10);
             if (Number.isNaN(timeout) || timeout < 1)
@@ -513,9 +548,10 @@ export function parseKnCreateFromDsArgs(args) {
     if (!dsId || !name) {
         throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
     }
+    const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, name, tables, build, timeout, businessDomain, pretty };
+    return { dsId, name, tables, pkMap, build, timeout, businessDomain, pretty, noRollback };
 }
 /** Sanitize a table name into a BKN-safe ID (alphanumeric + underscore). */
 function sanitizeBknId(name) {
@@ -559,6 +595,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         const tableRetryDelayMs = 4000;
         let allTables = [];
         let targetTables = [];
+        let scanAttempted = false;
         for (let attempt = 1; attempt <= maxTableListAttempts; attempt += 1) {
             const tablesBody = await listTablesWithColumns({ ...base, id: options.dsId });
             allTables = JSON.parse(tablesBody);
@@ -568,15 +605,61 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
             if (targetTables.length > 0)
                 break;
             if (attempt < maxTableListAttempts) {
-                console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); retrying in ${tableRetryDelayMs / 1000}s...`);
-                await new Promise((r) => setTimeout(r, tableRetryDelayMs));
+                // First miss: the catalog often hasn't picked up tables created
+                // out-of-band (e.g. ds import-csv from an older SDK that didn't
+                // self-scan). Trigger a scan once before falling back to plain
+                // sleep-retries.
+                if (!scanAttempted) {
+                    scanAttempted = true;
+                    console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); scanning datasource metadata before retry...`);
+                    try {
+                        await scanDatasourceMetadata({ ...base, id: options.dsId });
+                    }
+                    catch (err) {
+                        console.error(`Scan warning (continuing): ${formatHttpError(err)}`);
+                    }
+                }
+                else {
+                    console.error(`No tables available (attempt ${attempt}/${maxTableListAttempts}); retrying in ${tableRetryDelayMs / 1000}s...`);
+                    await new Promise((r) => setTimeout(r, tableRetryDelayMs));
+                }
             }
         }
         if (targetTables.length === 0) {
             console.error("No tables available");
             return 1;
         }
-        // Phase 1: Create DataViews for each table
+        // Pre-flight: catch every offending OT name before any side effect.
+        // Backend rejects the whole batch on first violation (validate.go:90),
+        // so retroactive rollback is wasted work if we can fail fast here.
+        assertValidBknObjectNames(targetTables.map((t) => t.name), "Object type names derived from table names");
+        // Pre-flight: resolve PK for every table BEFORE any side effect.
+        // Auto-detection silently picking the wrong column was the cause of
+        // issue #97 (KN built with ~5 indexed docs out of 2036 source rows).
+        // Resolve order: --pk-map override → cardinality-based detection → fail-fast.
+        const tablePks = {};
+        const unknownPkMapTables = Object.keys(options.pkMap).filter((name) => !targetTables.some((t) => t.name === name));
+        if (unknownPkMapTables.length > 0) {
+            throw new Error(`--pk-map references unknown table(s): ${unknownPkMapTables.join(", ")}`);
+        }
+        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;
+                continue;
+            }
+            const result = detectPrimaryKey(t, sampleRows?.[t.name]);
+            if (!result.pk) {
+                throw new Error(formatPkDetectionError(t.name, result));
+            }
+            tablePks[t.name] = result.pk;
+        }
+        // Phase 1: Create DataViews for each table. findDataView is idempotent;
+        // not tracked for rollback so a retry can reuse what's already there.
         console.error(`Creating data views for ${targetTables.length} table(s) ...`);
         const viewMap = {};
         for (const t of targetTables) {
@@ -597,7 +680,8 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
                 }));
             viewMap[t.name] = dvId;
         }
-        // Phase 2: Create the KN record
+        // Phase 2: Create the KN. If any subsequent step fails we DELETE this
+        // KN — backend cascades to OTs (knowledge_network_service.go:917-969).
         const knBody = JSON.stringify({
             name: options.name,
             branch: "main",
@@ -611,72 +695,91 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
         const knItem = Array.isArray(knParsed) ? knParsed[0] : knParsed;
         const knId = String(knItem?.id ?? "");
         console.error(`Knowledge network created: ${knId}`);
-        // Phase 3: Create object types via REST API
-        console.error(`Creating ${targetTables.length} object type(s) ...`);
+        let createdKnId = knId;
         const otResults = [];
-        for (const t of targetTables) {
-            const pk = detectPrimaryKey(t, sampleRows?.[t.name]);
-            const dk = detectDisplayKey(t, pk);
-            const uniqueProps = [pk, dk].filter((x, i, a) => a.indexOf(x) === i);
-            const entry = {
-                branch: "main",
-                name: t.name,
-                data_source: { type: "data_view", id: viewMap[t.name] },
-                primary_keys: [pk],
-                display_key: dk,
-                data_properties: t.columns.map((c) => ({
-                    name: c.name,
-                    display_name: c.name,
-                    type: "string",
-                    mapped_field: { name: c.name, type: c.type || "varchar" },
-                })),
-            };
-            const otBody = JSON.stringify({ entries: [entry] });
+        let statusStr = "skipped";
+        try {
+            // Phase 3: Single batched POST. Backend wraps all entries in one tx
+            // (object_type_service.go:213-355) — all-or-nothing.
+            console.error(`Creating ${targetTables.length} object type(s) ...`);
+            const entries = targetTables.map((t) => {
+                const pk = tablePks[t.name];
+                const dk = detectDisplayKey(t, pk);
+                return {
+                    branch: "main",
+                    name: t.name,
+                    data_source: { type: "data_view", id: viewMap[t.name] },
+                    primary_keys: [pk],
+                    display_key: dk,
+                    data_properties: t.columns.map((c) => ({
+                        name: c.name,
+                        display_name: c.name,
+                        type: "string",
+                        mapped_field: { name: c.name, type: c.type || "varchar" },
+                    })),
+                    _meta: { pk, dk },
+                };
+            });
+            const wireEntries = entries.map(({ _meta: _, ...rest }) => rest);
+            const otBody = JSON.stringify({ entries: wireEntries });
             const otResponse = await createObjectTypes({
                 ...base,
                 knId,
                 body: otBody,
             });
             const otParsed = JSON.parse(otResponse);
-            const otItem = otParsed.entries?.[0];
-            otResults.push({
-                name: t.name,
-                id: otItem?.id ?? "",
-                field_count: t.columns.length,
-            });
-            console.error(`  Created: ${t.name} (${t.columns.length} fields, pk=${pk}, dk=${dk})`);
-        }
-        if (otResults.length === 0) {
-            const errorOutput = {
-                kn_id: knId,
-                kn_name: options.name,
-                error: "No object types were created",
-            };
-            console.log(JSON.stringify(errorOutput, null, options.pretty ? 2 : 0));
-            return 1;
-        }
-        let statusStr = "skipped";
-        if (options.build) {
-            console.error("Building ...");
-            await buildKnowledgeNetwork({ ...base, knId });
-            const TERMINAL = ["completed", "failed", "success"];
-            try {
-                statusStr = await pollWithBackoff({
-                    fn: async () => {
-                        const statusBody = await getBuildStatus({ ...base, knId });
-                        const statusParsed = JSON.parse(statusBody);
-                        const jobs = Array.isArray(statusParsed) ? statusParsed : (statusParsed.entries ?? []);
-                        const state = (jobs[0]?.state ?? "running").toLowerCase();
-                        if (TERMINAL.includes(state))
-                            return { done: true, value: state };
-                        return { done: false, value: "running" };
-                    },
-                    interval: 2000,
-                    timeout: options.timeout * 1000,
+            const otItems = Array.isArray(otParsed) ? otParsed : (otParsed.entries ?? []);
+            for (let i = 0; i < entries.length; i += 1) {
+                const t = targetTables[i];
+                const meta = entries[i]._meta;
+                otResults.push({
+                    name: t.name,
+                    id: otItems[i]?.id ?? "",
+                    field_count: t.columns.length,
                 });
+                console.error(`  Created: ${t.name} (${t.columns.length} fields, pk=${meta.pk}, dk=${meta.dk})`);
             }
-            catch {
-                // timeout — statusStr remains "skipped"
+            if (options.build) {
+                console.error("Building ...");
+                await buildKnowledgeNetwork({ ...base, knId });
+                const TERMINAL = ["completed", "failed", "success"];
+                try {
+                    statusStr = await pollWithBackoff({
+                        fn: async () => {
+                            const statusBody = await getBuildStatus({ ...base, knId });
+                            const statusParsed = JSON.parse(statusBody);
+                            const jobs = Array.isArray(statusParsed) ? statusParsed : (statusParsed.entries ?? []);
+                            const state = (jobs[0]?.state ?? "running").toLowerCase();
+                            if (TERMINAL.includes(state))
+                                return { done: true, value: state };
+                            return { done: false, value: "running" };
+                        },
+                        interval: 2000,
+                        timeout: options.timeout * 1000,
+                    });
+                }
+                catch {
+                    // build timeout — KN itself is fine, just mark skipped
+                }
+            }
+            // Reached the end without throwing — clear the rollback handle.
+            createdKnId = undefined;
+        }
+        finally {
+            if (createdKnId !== undefined) {
+                if (options.noRollback) {
+                    console.error(`Leaving partial KN ${createdKnId} in place (--no-rollback)`);
+                }
+                else {
+                    console.error(`Rolling back KN ${createdKnId} ...`);
+                    try {
+                        await deleteKnowledgeNetwork({ ...base, knId: createdKnId });
+                        console.error(`Rolled back KN ${createdKnId}`);
+                    }
+                    catch (rollbackErr) {
+                        console.error(`Rollback failed for KN ${createdKnId}: ${formatHttpError(rollbackErr)}`);
+                    }
+                }
             }
         }
         const output = {
@@ -706,8 +809,9 @@ Options:
   --tables <a,b>       Tables to include in KN (default: all imported)
   --build (default)    Build after creation
   --no-build           Skip build
-  --recreate           Use "insert" mode on first batch (only effective for new tables)
+  --pk-map <s>         Explicit primary keys: <table>:<field>[,<table>:<field>...]
   --timeout <n>        Build timeout in seconds (default: 300)
+  --no-rollback        Keep partially-created KN on failure (debug; default: rollback)
   -bd, --biz-domain    Business domain (default: bd_public)`;
 export function parseKnCreateFromCsvArgs(args) {
     let dsId = "";
@@ -716,10 +820,11 @@ export function parseKnCreateFromCsvArgs(args) {
     let tablePrefix = "";
     let batchSize = 500;
     let tablesStr = "";
+    let pkMapStr = "";
     let build = true;
-    let recreate = false;
     let timeout = 300;
     let businessDomain = "";
+    let noRollback = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h")
@@ -754,8 +859,12 @@ export function parseKnCreateFromCsvArgs(args) {
             build = false;
             continue;
         }
-        if (arg === "--recreate") {
-            recreate = true;
+        if (arg === "--pk-map" && args[i + 1]) {
+            pkMapStr = args[++i];
+            continue;
+        }
+        if (arg === "--no-rollback") {
+            noRollback = true;
             continue;
         }
         if (arg === "--timeout" && args[i + 1]) {
@@ -776,9 +885,10 @@ export function parseKnCreateFromCsvArgs(args) {
     if (!dsId || !files || !name) {
         throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
     }
+    const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
     if (!businessDomain)
         businessDomain = resolveBusinessDomain();
-    return { dsId, files, name, tablePrefix, batchSize, tables, build, recreate, timeout, businessDomain };
+    return { dsId, files, name, tablePrefix, batchSize, tables, pkMap, build, timeout, businessDomain, noRollback };
 }
 export async function runKnCreateFromCsvCommand(args) {
     let options;
@@ -793,6 +903,20 @@ export async function runKnCreateFromCsvCommand(args) {
         console.error(formatHttpError(error));
         return 1;
     }
+    // Pre-flight: predict OT names from (table-prefix + csv basename) and
+    // reject before any CSV is imported. CSV import is expensive; failing
+    // here saves the user a multi-minute round trip.
+    try {
+        const filePaths = await resolveFiles(options.files);
+        const predictedNames = options.tables.length > 0
+            ? options.tables
+            : filePaths.map((p) => buildTableName(p, options.tablePrefix));
+        assertValidBknObjectNames(predictedNames, "Object type names derived from CSV file names");
+    }
+    catch (error) {
+        console.error(formatHttpError(error));
+        return 1;
+    }
     // Phase 1: Import CSVs
     console.error("Phase 1: Importing CSVs ...");
     const importArgs = [
@@ -801,35 +925,15 @@ export async function runKnCreateFromCsvCommand(args) {
         "--table-prefix", options.tablePrefix,
         "--batch-size", String(options.batchSize),
         "-bd", options.businessDomain,
-        ...(options.recreate ? ["--recreate"] : []),
     ];
     const importResult = await runDsImportCsv(importArgs);
     if (importResult.code !== 0) {
         console.error("CSV import failed — aborting KN creation");
         return importResult.code;
     }
-    // Phase 1.5: Scan datasource metadata so platform discovers newly imported tables
-    console.error("Scanning datasource metadata ...");
-    try {
-        const token = await ensureValidToken();
-        const dsBody = await getDatasource({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            id: options.dsId,
-            businessDomain: options.businessDomain,
-        });
-        const dsParsed = JSON.parse(dsBody);
-        await scanMetadata({
-            baseUrl: token.baseUrl,
-            accessToken: token.accessToken,
-            id: options.dsId,
-            dsType: dsParsed.type ?? "mysql",
-            businessDomain: options.businessDomain,
-        });
-    }
-    catch (err) {
-        console.error(`Scan warning (continuing): ${String(err)}`);
-    }
+    // (Phase 1.5 metadata scan removed — runDsImportCsv now self-scans on
+    // success, and runKnCreateFromDsCommand's table-discovery retry triggers
+    // a scan if the catalog still lags. Two layers of fallback are enough.)
     // Phase 2: Create KN from datasource
     console.error("Phase 2: Creating knowledge network ...");
     const tableNames = options.tables.length > 0 ? options.tables : importResult.tables;
@@ -837,6 +941,7 @@ export async function runKnCreateFromCsvCommand(args) {
         console.error("No tables available for KN creation — aborting");
         return 1;
     }
+    const pkMapEntries = Object.entries(options.pkMap);
     const knArgs = [
         options.dsId,
         "--name", options.name,
@@ -844,6 +949,10 @@ export async function runKnCreateFromCsvCommand(args) {
         options.build ? "--build" : "--no-build",
         "--timeout", String(options.timeout),
         "-bd", options.businessDomain,
+        ...(pkMapEntries.length > 0
+            ? ["--pk-map", pkMapEntries.map(([t, f]) => `${t}:${f}`).join(",")]
+            : []),
+        ...(options.noRollback ? ["--no-rollback"] : []),
     ];
     return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);
 }

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

@@ -18,14 +18,38 @@ export declare function parseOntologyQueryFlags(args: string[]): {
     businessDomain: string;
 };
 export declare const DISPLAY_HINTS: string[];
-/** Detect primary key: first column (left-to-right) with all unique values in the sample. */
+export interface PkCandidate {
+    name: string;
+    cardinality: number;
+}
+export interface PkDetectionResult {
+    /** Detected PK column name, or null when detection is not confident. */
+    pk: string | null;
+    /** All columns sorted by cardinality desc. Empty when no sample. */
+    candidates: PkCandidate[];
+    /** 0 when no sample data was provided. */
+    sampleSize: number;
+}
+export declare const PK_NAME_HINTS: string[];
+/**
+ * Detect primary key from a row sample. Returns null pk when no column has
+ * unique values across the sample — caller must fail-fast and prompt for --pk-map.
+ * Among columns that ARE fully unique, prefers PK-like names (id, *_id, pk).
+ */
 export declare function detectPrimaryKey(table: {
     name: string;
     columns: Array<{
         name: string;
         type: string;
     }>;
-}, rows?: Array<Record<string, string | null>>): string;
+}, rows?: Array<Record<string, string | null>>): PkDetectionResult;
+/** Format a user-facing error message when PK auto-detection fails. */
+export declare function formatPkDetectionError(tableName: string, result: PkDetectionResult): string;
+/**
+ * Parse --pk-map string into a Record<table, field>.
+ * Format: "<table>:<field>[,<table>:<field>...]". Throws on invalid input.
+ */
+export declare function parsePkMap(input: string): Record<string, string>;
 export declare function detectDisplayKey(table: {
     name: string;
     columns: Array<{

package/dist/commands/bkn-utils.js

@@ -68,18 +68,75 @@ export function parseOntologyQueryFlags(args) {
 }
 // ── Schema detection helpers ─────────────────────────────────────────────────
 export const DISPLAY_HINTS = ["name", "title", "label", "display_name", "description"];
-/** Detect primary key: first column (left-to-right) with all unique values in the sample. */
+export const PK_NAME_HINTS = ["id", "_id", "pk"];
+/**
+ * Detect primary key from a row sample. Returns null pk when no column has
+ * unique values across the sample — caller must fail-fast and prompt for --pk-map.
+ * Among columns that ARE fully unique, prefers PK-like names (id, *_id, pk).
+ */
 export function detectPrimaryKey(table, rows) {
-    if (rows && rows.length > 0) {
-        for (const col of table.columns) {
-            const values = rows.map((r) => r[col.name]);
-            const unique = new Set(values);
-            if (unique.size === rows.length)
-                return col.name;
+    if (!rows || rows.length === 0) {
+        return { pk: null, candidates: [], sampleSize: 0 };
+    }
+    const candidates = table.columns
+        .map((col) => {
+        const unique = new Set(rows.map((r) => r[col.name]));
+        return { name: col.name, cardinality: unique.size };
+    })
+        .sort((a, b) => b.cardinality - a.cardinality);
+    const fullCardinality = candidates.filter((c) => c.cardinality === rows.length);
+    if (fullCardinality.length === 0) {
+        return { pk: null, candidates, sampleSize: rows.length };
+    }
+    const named = fullCardinality.find((c) => {
+        const lower = c.name.toLowerCase();
+        return PK_NAME_HINTS.some((h) => lower === h || lower.endsWith(`_${h}`));
+    });
+    return {
+        pk: named?.name ?? fullCardinality[0].name,
+        candidates,
+        sampleSize: rows.length,
+    };
+}
+/** Format a user-facing error message when PK auto-detection fails. */
+export function formatPkDetectionError(tableName, result) {
+    const lines = [`Cannot auto-detect primary key for table '${tableName}'.`];
+    if (result.sampleSize === 0) {
+        lines.push(`  No sample data available — chain with 'kweaver ds import-csv' or use --pk-map.`);
+    }
+    else {
+        lines.push(`  No column has unique values in the ${result.sampleSize}-row sample.`);
+        lines.push(`  Top candidates by cardinality:`);
+        const top = result.candidates.slice(0, 5);
+        const maxNameLen = Math.max(...top.map((c) => c.name.length));
+        for (const c of top) {
+            lines.push(`    ${c.name.padEnd(maxNameLen)}  ${c.cardinality} unique`);
+        }
+    }
+    lines.push(``);
+    lines.push(`  Re-run with --pk-map to specify explicitly:`);
+    lines.push(`    --pk-map ${tableName}:<column>`);
+    return lines.join("\n");
+}
+/**
+ * Parse --pk-map string into a Record<table, field>.
+ * Format: "<table>:<field>[,<table>:<field>...]". Throws on invalid input.
+ */
+export function parsePkMap(input) {
+    const result = {};
+    for (const pair of input.split(",").map((s) => s.trim()).filter(Boolean)) {
+        const idx = pair.indexOf(":");
+        if (idx <= 0 || idx >= pair.length - 1) {
+            throw new Error(`Invalid --pk-map entry '${pair}'. Expected '<table>:<field>[,<table>:<field>...]'`);
+        }
+        const table = pair.slice(0, idx).trim();
+        const field = pair.slice(idx + 1).trim();
+        if (!table || !field) {
+            throw new Error(`Invalid --pk-map entry '${pair}'. Expected '<table>:<field>[,<table>:<field>...]'`);
         }
+        result[table] = field;
     }
-    // Fallback: first column
-    return table.columns[0]?.name ?? "id";
+    return result;
 }
 export function detectDisplayKey(table, primaryKey) {
     for (const col of table.columns) {

package/dist/commands/config.js

@@ -2,6 +2,7 @@ import { listBusinessDomains } from "../api/business-domains.js";
 import { fetchEacpUserInfo, resolveActivePlatform, withTokenRetry } from "../auth/oauth.js";
 import { HttpError } from "../utils/http.js";
 import { loadPlatformBusinessDomain, resolveBusinessDomain, savePlatformBusinessDomain, } from "../config/store.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
 const HELP = `kweaver config
 
 Subcommands:
@@ -50,6 +51,13 @@ export async function runConfigCommand(args) {
             return 1;
         }
         const platform = active.url;
+        try {
+            assertNotStatelessForWrite("config set-bd");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         savePlatformBusinessDomain(platform, value);
         const provenance = active.source === "env" ? `${platform} via KWEAVER_BASE_URL` : platform;
         console.log(`Business domain set to: ${value} (${provenance})`);