@knolo/cli 5.5.0 → 6.0.0

package/bin/knolo.mjs

@@ -72,6 +72,7 @@ const SUBCOMMANDS = new Set([
   'semantic:index',
   'semantic:inspect',
   'semantic:validate',
+  'kar',
 ]);
 const ICP_SUBCOMMANDS = new Set([
   'init',
@@ -128,6 +129,18 @@ async function loadCore() {
   );
 }
 
+function printVersion() {
+  const cli = JSON.parse(readFileSync(path.join(__dirname, '../package.json'), 'utf8'));
+  let coreVersion = 'unavailable';
+  try {
+    coreVersion = JSON.parse(readFileSync(require.resolve('@knolo/core/package.json'), 'utf8')).version;
+  } catch {
+    coreVersion = 'unavailable';
+  }
+  console.log(`@knolo/cli ${cli.version}`);
+  console.log(`@knolo/core ${coreVersion}`);
+}
+
 function printRootHelp() {
   console.log(`KnoLo CLI
 
@@ -146,7 +159,7 @@ Commands:
   publish                 Publish a pack with a Hub Bearer token
   yank <pack>@<version>   Yank a released pack with a Hub Bearer token
   build                   Build a .knolo pack from configured sources
-  query <question>        Query a built pack and print top hits
+  query <question|EQL>    Query a V4 pack or a V5 image using its declared contract
   inspect <pack>          Inspect pack format, sections, and manifest
   migrate <pack>          Migrate a legacy pack to v4
   verify <pack>           Verify pack structure and cryptographic digests
@@ -154,11 +167,13 @@ Commands:
   diff <pack-a> <pack-b>  Compare pack identities and source/chunk counts
   dev                     Watch config/sources and rebuild on change
   v5                      Inspect, compress, decompress, and health-check a V5 Knowledge Image
+  kar                     KAR evidence-set retrieval over a Committed Evidence Graph
   icp                     Scaffold and operate an ICP-native knowledge canister
 
 Global options:
   --debug                 Print stack traces for errors
   -h, --help              Show help
+  -v, --version           Print the CLI and @knolo/core versions
 
 Run "knolo <command> --help" for command details.`);
 }
@@ -179,7 +194,7 @@ function printCommandHelp(command) {
     yank: 'Usage: knolo yank <publisher>/<slug>@<version> [--json] [--registry <url>]\n\nUses the stored token as Authorization: Bearer kno_…. Yank is owner-only and leaves the public Blob in place.',
     build: 'Usage: knolo build',
     query:
-      'Usage: knolo query <question> [--pack <path>] [--k <number>] [--receipt <file>] [--json]',
+      'Usage: knolo query <question|EQL> [--pack <path>] [--k <number>] [--receipt <file>] [--json]\n\nV4 packs accept natural-language queries. V5 images require bounded EQL such as: FROM chunk SEARCH "billing" LIMIT 5.',
     inspect: 'Usage: knolo inspect <pack.knolo>',
     migrate:
       'Usage: knolo migrate <pack.knolo> --out <new-pack.knolo> [--to 4]',
@@ -187,7 +202,8 @@ function printCommandHelp(command) {
     explain: 'Usage: knolo explain <receipt.json> --pack <pack.knolo>',
     diff: 'Usage: knolo diff <pack-a.knolo> <pack-b.knolo>',
     dev: 'Usage: knolo dev',
-    v5: 'Usage: knolo v5 <info|health|studio|compress|decompress> <image.v5> [--out <file>] [--mode fast|balanced|max] [--attach-index]',
+    v5: 'Usage: knolo v5 <info|health|studio|query|compress|decompress> <image.v5> [--out <file>] [--mode fast|balanced|max] [--attach-index]\n\nFor query: knolo v5 query <image.v5> <EQL> [--json] [--receipt <file>].',
+    kar: 'Usage: knolo kar <evaluate|verify|explain|inspect|graph|package|produce|domain|dossier|coverage|benchmark|demo|conformance> [options]\n\nKnolo Adversarial Retrieval. Semantics are frozen at kar-1-research-1.\n\n  knolo kar evaluate --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..."\n  knolo kar verify   --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..." --result result.json\n  knolo kar explain  --result result.json\n  knolo kar inspect  --image knowledge.knolo --graph knowledge.kar.json [--plan plan.json]\n  knolo kar graph build --image knowledge.knolo --source knowledge.ceg.yaml --out knowledge.kar.json\n  knolo kar package --image knowledge.knolo --graph knowledge.kar.json --out dist/my-knowledge-kar/\n  knolo kar produce rules --image knowledge.knolo --domain domains/contracts-v4 --out proposals.json\n  knolo kar domain validate domains/contracts-v4\n  knolo kar dossier build --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..." --out dossier/\n  knolo kar dossier verify dossier/\n  knolo kar coverage build --image knowledge.knolo --graph knowledge.kar.json --plan plan.json --query "..." --out coverage/\n  knolo kar coverage verify coverage/\n  knolo kar benchmark annotate --packet packet.json --decisions decisions.json --out labels.json --role human --reviewer-id <id>\n  knolo kar demo\n  knolo kar conformance\n\n--json prints the machine-readable result. verify exits non-zero when the certificate does not match. Abstention is a result and exits 0. graph and package author a Committed Evidence Graph without changing retrieval. produce proposes CEG Source and does not write committed bytes. dossier packages one evaluation and fails closed when committed fields change. coverage reports met requirements, gaps, and plans that did not decide. A gap is not a false claim. benchmark labels gold without showing producer output. demo and conformance run from a knolo-core checkout.',
     icp: 'Usage: knolo icp <command> [options]',
     'semantic:index':
       'Usage: knolo semantic:index --pack <path> [--out <path>] [--model <id>] [--endpoint <url>]',
@@ -288,6 +304,8 @@ function parseArgv(argv) {
   }
   if (args[0] === '--help' || args[0] === '-h')
     return { global, command: 'help', commandArgs: [] };
+  if (args[0] === '--version' || args[0] === '-v')
+    return { global, command: 'version', commandArgs: [] };
   return { global, command: args[0] || 'help', commandArgs: args.slice(1) };
 }
 
@@ -877,6 +895,13 @@ async function cmdQuery(core, args) {
 
   const packBuffer = readFileSync(packPath);
   const bytes = Uint8Array.from(packBuffer);
+  if (core.isKnowledgeImageV5?.(bytes)) {
+    if (opts.k !== undefined)
+      throw createError(
+        'V5 queries use EQL LIMIT. Put LIMIT in the query instead of --k.'
+      );
+    return await cmdQueryV5(core, bytes, packPath, question, opts);
+  }
   const kb = await mountPackFromBytes(core, bytes);
   const receiptResult =
     opts.receipt && core.queryWithReceipt
@@ -936,6 +961,66 @@ async function cmdQuery(core, args) {
   });
 }
 
+async function cmdQueryV5(core, bytes, imagePath, expression, opts) {
+  const image = core.mountKnowledgeImageV5(bytes);
+  const result = core.queryKnowledgeImageV5(image, expression);
+  if (opts.receipt) {
+    writeFileSync(
+      path.resolve(process.cwd(), opts.receipt),
+      `${JSON.stringify(result, null, 2)}\n`
+    );
+  }
+  const objects = new Map(image.objects.map((object) => [object.id, object]));
+  const hits = result.hits.map((hit) => {
+    const object = objects.get(hit.objectId);
+    const text = object
+      ? new TextDecoder()
+          .decode(object.bytes)
+          .replace(/\s+/gu, ' ')
+          .slice(0, 200)
+      : '';
+    const metadata = object?.meta ?? {};
+    const source =
+      typeof metadata.source === 'string'
+        ? metadata.source
+        : typeof metadata.docId === 'string'
+          ? metadata.docId
+          : hit.objectId;
+    return {
+      objectId: hit.objectId,
+      kind: hit.kind,
+      source,
+      snippet: text,
+      joinedObjectIds: hit.joinedObjectIds,
+    };
+  });
+  const payload = {
+    contract: 'v5-knowledge-image',
+    query: expression,
+    imagePath,
+    stateRoot: result.stateRoot,
+    planRoot: result.planRoot,
+    resultRoot: result.resultRoot,
+    plan: result.plan,
+    hits,
+    queryResult: result,
+  };
+  if (opts.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (!hits.length) {
+    console.log('No V5 hits found.');
+    return;
+  }
+  console.log(`V5 query returned ${hits.length} hit(s):`);
+  hits.forEach((hit, index) => {
+    console.log(`\n${index + 1}. ${hit.kind} ${hit.objectId}`);
+    console.log(`   source: ${hit.source}`);
+    console.log(`   snippet: ${hit.snippet}`);
+  });
+}
+
 function parsePackCommandArgs(args, command) {
   const positional = [];
   const flags = {};
@@ -961,6 +1046,24 @@ async function cmdInspect(core, args) {
       `Pack file not found at ${path.relative(process.cwd(), packPath)}.`
     );
   const bytes = Uint8Array.from(readFileSync(packPath));
+  if (core.isKnowledgeImageV5?.(bytes)) {
+    const image = core.mountKnowledgeImageV5(bytes);
+    console.log(
+      JSON.stringify(
+        {
+          format: 'v5-knowledge-image',
+          version: 5,
+          stateRoot: image.stateRoot,
+          commitDigest: image.commitDigest,
+          objects: image.objects.length,
+          events: image.events.length,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
   const pack = await mountPackFromBytes(core, bytes);
   const result = {
     format:
@@ -988,6 +1091,23 @@ async function cmdVerify(core, args) {
       `Pack file not found at ${path.relative(process.cwd(), packPath)}.`
     );
   const bytes = Uint8Array.from(readFileSync(packPath));
+  if (core.isKnowledgeImageV5?.(bytes)) {
+    const verification = core.verifyKnowledgeImageV5(bytes);
+    console.log(
+      JSON.stringify(
+        {
+          verified: verification.valid,
+          format: 'v5-knowledge-image',
+          version: 5,
+          stateRoot: verification.stateRoot,
+          commitDigest: verification.commitDigest,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
   const pack = await mountPackFromBytes(core, bytes);
   console.log(
     JSON.stringify(
@@ -1043,16 +1163,47 @@ async function cmdExplain(core, args) {
   const receiptPath = positional[0];
   if (!receiptPath || (!flags.out && !flags.pack))
     throw createError(
-      'Usage: knolo explain <receipt.json> --pack <pack.knolo>'
+      'Usage: knolo explain <receipt.json> --pack <pack.knolo|image.v5>'
     );
   const packPath = path.resolve(process.cwd(), flags.pack);
   const receipt = JSON.parse(
     readFileSync(path.resolve(process.cwd(), receiptPath), 'utf8')
   );
-  const pack = await mountPackFromBytes(
-    core,
-    Uint8Array.from(readFileSync(packPath))
-  );
+  const bytes = Uint8Array.from(readFileSync(packPath));
+  if (core.isKnowledgeImageV5?.(bytes)) {
+    core.verifyKnowledgeQueryResultV5(bytes, receipt);
+    const image = core.mountKnowledgeImageV5(bytes);
+    const objects = new Map(image.objects.map((object) => [object.id, object]));
+    console.log(
+      JSON.stringify(
+        {
+          verified: true,
+          contract: 'v5-knowledge-image',
+          query: receipt.plan,
+          stateRoot: receipt.stateRoot,
+          planRoot: receipt.planRoot,
+          resultRoot: receipt.resultRoot,
+          hits: receipt.hits.map((hit) => {
+            const object = objects.get(hit.objectId);
+            return {
+              objectId: hit.objectId,
+              kind: hit.kind,
+              source:
+                typeof object?.meta?.source === 'string'
+                  ? object.meta.source
+                  : typeof object?.meta?.docId === 'string'
+                    ? object.meta.docId
+                    : undefined,
+            };
+          }),
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const pack = await mountPackFromBytes(core, bytes);
   core.verifyReceipt(receipt, pack);
   console.log(
     JSON.stringify(
@@ -1120,6 +1271,8 @@ function parseV5Args(args) {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--attach-index') flags.attachIndex = true;
+    else if (arg === '--json') flags.json = true;
+    else if (arg === '--receipt') flags.receipt = args[++i];
     else if (
       arg === '--image' ||
       arg === '--index' ||
@@ -1139,17 +1292,40 @@ function parseV5Args(args) {
 
 async function cmdV5(core, args) {
   const subcommand = args[0] || 'info';
-  if (
-    !['info', 'health', 'studio', 'compress', 'decompress'].includes(subcommand)
-  )
+  const subcommands = [
+    'info',
+    'health',
+    'studio',
+    'query',
+    'compress',
+    'decompress',
+  ];
+  if (!subcommands.includes(subcommand))
     throw createError(`Unknown V5 command: ${subcommand}`);
   const { positional, flags } = parseV5Args(
-    args.slice(
-      ['info', 'health', 'studio', 'compress', 'decompress'].includes(args[0])
-        ? 1
-        : 0
-    )
+    args.slice(subcommands.includes(args[0]) ? 1 : 0)
   );
+  if (subcommand === 'query') {
+    const imagePath = path.resolve(
+      process.cwd(),
+      flags.image || positional[0] || 'dist/knowledge.v5'
+    );
+    if (!existsSync(imagePath))
+      throw createError(
+        `V5 image file not found at ${path.relative(process.cwd(), imagePath)}.`
+      );
+    const expression = (flags.image ? positional : positional.slice(1))
+      .join(' ')
+      .trim();
+    if (!expression)
+      throw createError(
+        'Usage: knolo v5 query <image.v5> <EQL> [--json] [--receipt <file>]'
+      );
+    const bytes = Uint8Array.from(readFileSync(imagePath));
+    if (!core.isKnowledgeImageV5?.(bytes))
+      throw createError('V5 query requires a V5 Knowledge Image input.');
+    return await cmdQueryV5(core, bytes, imagePath, expression, flags);
+  }
   const imagePath = path.resolve(
     process.cwd(),
     flags.image || positional[0] || 'dist/knowledge.v5'
@@ -1282,6 +1458,10 @@ async function cmdSemanticIndex(core, args) {
     );
 
   const bytes = Uint8Array.from(readFileSync(packPath));
+  if (core.isKnowledgeImageV5?.(bytes))
+    throw createError(
+      'semantic:index targets V4 packs. Query V5 images with bounded EQL through knolo query.'
+    );
   const pack = await mountPackFromBytes(core, bytes);
   const OllamaEmbeddingProvider = await loadOllamaProvider();
   const provider = new OllamaEmbeddingProvider({ modelId, endpoint });
@@ -1332,10 +1512,12 @@ async function cmdSemanticValidate(core, args) {
   const sidecarPath = path.resolve(process.cwd(), flags.sidecar);
   const modelId = flags.model;
   if (!modelId) throw createError('semantic:validate requires --model <id>.');
-  const pack = await mountPackFromBytes(
-    core,
-    Uint8Array.from(readFileSync(packPath))
-  );
+  const packBytes = Uint8Array.from(readFileSync(packPath));
+  if (core.isKnowledgeImageV5?.(packBytes))
+    throw createError(
+      'semantic:validate targets V4 packs. Query V5 images with bounded EQL through knolo query.'
+    );
+  const pack = await mountPackFromBytes(core, packBytes);
   const sidecar = core.parseSidecar(readFileSync(sidecarPath, 'utf8'));
   core.validateSidecarForPack({ sidecar, pack, modelId });
   if (sidecar.blocks.length !== pack.blocks.length)
@@ -1652,6 +1834,7 @@ async function main() {
   const { global, command, commandArgs } = parseArgv(process.argv.slice(2));
   try {
     if (command === 'help') return printRootHelp();
+    if (command === 'version') return printVersion();
     if (command === 'icp') {
       if (
         commandArgs.length === 0 ||
@@ -1666,6 +1849,10 @@ async function main() {
     if (SUBCOMMANDS.has(command)) {
       if (commandArgs.includes('--help') || commandArgs.includes('-h'))
         return printCommandHelp(command);
+      if (command === 'kar') {
+        const { runKarCli } = await import('./kar.mjs');
+        return runKarCli(commandArgs);
+      }
       if (command === 'init') return await cmdInit();
       if (command === 'add') return await cmdAdd(commandArgs);
       if (command === 'search') return await runHubSearch(commandArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/cli",
-  "version": "5.5.0",
+  "version": "6.0.0",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
@@ -9,7 +9,7 @@
     "bin/",
     "templates/"
   ],
-  "description": "CLI for building, inspecting, verifying, and operating Knolo V4 packs and V5 Knowledge Images.",
+  "description": "CLI for Knolo V4 packs, V5 Knowledge Images, and KAR evidence-set retrieval.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,11 +28,11 @@
   },
   "scripts": {
     "build": "node -e \"console.log('cli is executable via bin/knolo.mjs')\"",
-    "test": "npm run build --prefix ../core && node --test test/cli.test.mjs test/hub.integration.test.mjs",
+    "test": "npm run build --prefix ../core && node --test test/cli.test.mjs test/kar.test.mjs test/kar-graph.test.mjs test/kar-produce.test.mjs test/hub.integration.test.mjs",
     "test:hub": "node --test test/hub.integration.test.mjs"
   },
   "dependencies": {
-    "@knolo/core": "^5.5.0"
+    "@knolo/core": "^6.0.0"
   },
   "private": false
 }

package/templates/icp-knowledge-canister/canisters/knolo-core-rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "knolo-core-rust"
-version = "5.5.0"
+version = "5.5.1"
 edition = "2021"
 license = "Apache-2.0"
 description = "Rust runtime support for reading and querying .knolo packs"

package/templates/icp-knowledge-canister/canisters/knolo-icp-canister/Cargo.lock

@@ -245,11 +245,11 @@ dependencies = [
 
 [[package]]
 name = "knolo-core-rust"
-version = "5.5.0"
+version = "5.5.1"
 
 [[package]]
 name = "knolo-icp-canister"
-version = "5.5.0"
+version = "5.5.1"
 dependencies = [
  "candid",
  "ic-cdk",

package/templates/icp-knowledge-canister/canisters/knolo-icp-canister/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "knolo-icp-canister"
-version = "5.5.0"
+version = "5.5.1"
 edition = "2021"
 license = "Apache-2.0"
 description = "ICP canister adapter for Knolo retrieval over Candid"
@@ -16,5 +16,5 @@ path = "src/lib.rs"
 candid = "0.10"
 ic-cdk = "0.17"
 ic-cdk-macros = "0.17"
-knolo-core-rust = { path = "../knolo-core-rust", version = "5.5.0" }
+knolo-core-rust = { path = "../knolo-core-rust", version = "5.5.1" }
 serde = { version = "1", features = ["derive"] }