@knolo/cli 6.1.0 → 6.2.0

package/README.md

@@ -12,13 +12,18 @@ the format is still draft and compressed object/event images require a VQF-aware
 reader.
 
 `knolo compose`, `knolo attest`, and `knolo verify-attestation` cite local
-Knowledge Images and write an attestation sidecar. `@knolo/cli` `6.1.0`
-depends on `@knolo/core` `^6.1.0`. They do not fetch Hub. Verification
+Knowledge Images and write an attestation sidecar. `@knolo/cli` `6.2.0`
+depends on `@knolo/core` `^6.2.0`. They do not fetch Hub. Verification
 recomputes `compositionRoot` and checks bundled excerpt bytes. A keyring key
 must fall inside `notBefore`, `notAfter`, and `revokedAt`. `used` means a
 query or evaluation ran. It does not mean `SATISFIED`, and it does not mean a
 claim is true or false. Hub `attested: true` is a listing flag.
 
+`knolo cortex find`, `knolo cortex ask`, `knolo cortex explain`, and
+`knolo cortex verify` run bounded evidence retrieval. The CLI does not call a
+model and does not take an API key. A verified trace matches the image. It
+does not mean the answer is true.
+
 The official CLI for building `.knolo` knowledge packs.
 
 It indexes structured content and produces a deterministic, local-first knowledge bundle for use with `@knolo/core`.
@@ -275,9 +280,10 @@ This ensures:
 ## 🗺 Roadmap
 
 The active roadmap is maintained in [`../../docs/ROADMAP.md`](../../docs/ROADMAP.md).
-The current release is `6.1.0`. It preserves the V4 CLI, keeps V5 verification,
+The current release is `6.2.0`. It preserves the V4 CLI, keeps V5 verification,
 migration, diagnostics, and read-only Studio management, and adds offline
-composition and attestation.
+composition, attestation, and `knolo cortex`. Cortex verification does not
+mean an answer is true.
 
 ---
 

package/bin/cortex.mjs

@@ -0,0 +1,125 @@
+/**
+ * knolo cortex
+ *
+ * Bounded evidence retrieval. The CLI does not call a model and does not
+ * take an API key. Verification recomputes roots. It does not mean the
+ * answer is true.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { KAR_CLI_MAX_IMAGE_BYTES, KAR_CLI_MAX_TEXT_BYTES, readBounded, readBoundedJson } from './kar-limits.mjs';
+
+const USAGE = `Usage:
+  knolo cortex find <image> --question "..." [--top-k 100] [--policy policy.json] --out candidates.json
+  knolo cortex ask <image> --question "..." [--graph file] [--plan plan.json] [--mode find_relevant] [--policy policy.json] [--created-at text] --out answer.cortex.json
+  knolo cortex explain <answer.cortex.json>
+  knolo cortex verify --image <image> --answer answer.cortex.json [--graph file] [--question "..."]
+
+The CLI does not load a model. Hosts inject a model through createCortexSession.
+Verification checks the trace against the image. It does not mean the answer is true.
+SATISFIED on a KAR reference means evidence requirements were met. It does not mean a claim is proven.`;
+
+export async function runCortexCli(args) {
+  const sub = args[0];
+  if (sub === 'find') return writeTrace(await runAsk(parseFlags(args.slice(1)), 'find_relevant'));
+  if (sub === 'ask') return writeTrace(await runAsk(parseFlags(args.slice(1)), undefined));
+  if (sub === 'explain') return explain(parseFlags(args.slice(1)));
+  if (sub === 'verify') return verify(parseFlags(args.slice(1)));
+  throw new Error(`Unknown cortex command.\n${USAGE}`);
+}
+
+async function runAsk(flags, forcedMode) {
+  const imagePath = flags._[0];
+  if (!imagePath) throw new Error(USAGE);
+  const question = required(flags, 'question');
+  const api = await loadCortex();
+  const policy = flags.policy ? readBoundedJson(flags.policy) : {};
+  if (flags['top-k'] !== undefined) {
+    const topK = Number(flags['top-k']);
+    if (!Number.isInteger(topK) || topK < 1) throw new Error('--top-k must be a positive integer.');
+    policy.maxCandidatesPerRound = topK;
+  }
+  const session = await api.createCortexSession({
+    image: new Uint8Array(readBounded(imagePath, KAR_CLI_MAX_IMAGE_BYTES)),
+    ...(flags.graph ? { graph: readBoundedJson(flags.graph) } : {}),
+    ...(flags.plan ? { plan: readBoundedJson(flags.plan) } : {}),
+    policy,
+  });
+  const mode = forcedMode ?? flags.mode ?? 'evidence_answer';
+  const trace = await api.askCortex(session, {
+    question,
+    mode,
+    ...(flags['created-at'] ? { createdAt: flags['created-at'] } : {}),
+  });
+  return { flags, trace };
+}
+
+async function writeTrace(result) {
+  const json = `${JSON.stringify(result.trace, null, 2)}\n`;
+  if (result.flags.out) {
+    const out = path.resolve(process.cwd(), result.flags.out);
+    if (existsSync(out)) throw new Error(`Refusing to overwrite ${out}`);
+    writeFileSync(out, json);
+    console.log(`${result.trace.answer.status} ${result.trace.receipt.traceRoot}`);
+    return;
+  }
+  console.log(json);
+}
+
+async function explain(flags) {
+  const file = flags._[0] ?? flags.answer;
+  if (!file) throw new Error(USAGE);
+  const api = await loadCortex();
+  const trace = readBoundedJson(file);
+  console.log(`${JSON.stringify(api.explainCortexAnswer(trace), null, 2)}\n`);
+}
+
+async function verify(flags) {
+  const api = await loadCortex();
+  const answer = required(flags, 'answer');
+  const image = required(flags, 'image');
+  const trace = readBoundedJson(answer, KAR_CLI_MAX_TEXT_BYTES);
+  const verified = await api.verifyCortexAnswer({
+    image: new Uint8Array(readBounded(image, KAR_CLI_MAX_IMAGE_BYTES)),
+    question: flags.question ?? trace.question,
+    result: trace,
+    ...(flags.graph ? { graph: readBoundedJson(flags.graph) } : {}),
+  });
+  if (!verified.ok) throw new Error(`${verified.code}: ${verified.message}`);
+  console.log(`ok ${verified.traceRoot}`);
+}
+
+async function loadCortex() {
+  const candidate = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../core/dist/cortex/index.js');
+  const loaded = await import(pathToFileURL(candidate).href);
+  if (!loaded.createCortexSession || !loaded.askCortex || !loaded.verifyCortexAnswer) {
+    throw new Error('Could not load @knolo/core/cortex. Build packages/core first.');
+  }
+  return loaded;
+}
+
+function required(flags, name) {
+  if (!flags[name]) throw new Error(`Missing --${name}.\n${USAGE}`);
+  return flags[name];
+}
+
+function parseFlags(args) {
+  const flags = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--question') flags.question = args[++i];
+    else if (arg === '--graph') flags.graph = args[++i];
+    else if (arg === '--plan') flags.plan = args[++i];
+    else if (arg === '--mode') flags.mode = args[++i];
+    else if (arg === '--policy') flags.policy = args[++i];
+    else if (arg === '--out') flags.out = args[++i];
+    else if (arg === '--top-k') flags['top-k'] = args[++i];
+    else if (arg === '--created-at') flags['created-at'] = args[++i];
+    else if (arg === '--image') flags.image = args[++i];
+    else if (arg === '--answer') flags.answer = args[++i];
+    else if (arg.startsWith('--')) throw new Error(`Unknown flag ${arg}.\n${USAGE}`);
+    else flags._.push(arg);
+  }
+  return flags;
+}

package/bin/knolo.mjs

@@ -76,6 +76,7 @@ const SUBCOMMANDS = new Set([
   'compose',
   'attest',
   'verify-attestation',
+  'cortex',
 ]);
 const ICP_SUBCOMMANDS = new Set([
   'init',
@@ -173,6 +174,7 @@ Commands:
   kar                     KAR evidence-set retrieval over a Committed Evidence Graph
   compose                 Compose Knowledge Images, packs, and attestations offline
   attest                  Create or verify a composition attestation
+  cortex                  Bounded evidence retrieval with a verifiable trace
   icp                     Scaffold and operate an ICP-native knowledge canister
 
 Global options:
@@ -211,6 +213,7 @@ function printCommandHelp(command) {
     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.',
     compose: 'Usage: knolo compose <create|verify|excerpt|query> [options]\n\nOffline composition of Knowledge Images, packs, KAR sidecars, Domain Packs, and bounded excerpts.\n\n  knolo compose create --members members.json --out composition/ [--host knowledge.knolo] [--availability material|digest] [--policy policy.json]\n  knolo compose verify composition/ [--require-material] [--member alias=path]\n  knolo compose excerpt --image knowledge.knolo --object <id> --out excerpt.json\n  knolo compose query --composition composition/ --eql "FROM chunk SEARCH \\"valve\\"" [--question "..."] [--json]\n\ncompositionRoot does not change a V5 state root or a KAR root. statement used means a query or evaluation ran. It does not mean SATISFIED, and it does not mean a claim is true or false. Hub attested: true is a listing flag and is not an attestation root. The CLI does not fetch Hub.',
     attest: 'Usage: knolo attest <create|verify> [options]\n\n  knolo attest create --composition composition/composition.json --subject composition --statement mount|used|cited --out attestation.json [--sign-key key.json --principal <id> --key-id <id> --issued-at <ms> --expires-at <ms>]\n  knolo attest verify attestation.json [--composition composition.json] [--public-key key.json] [--now <ms>] [--content-only]\n\nstatement used means a query or KAR evaluation ran. It does not mean the claim is true or false. Hub attested: true is unrelated. Signing uses the supplied times. The CLI does not read the clock.',
+    cortex: 'Usage: knolo cortex <find|ask|explain|verify> [options]\n\nBounded evidence retrieval. The CLI does not call a model.\n\n  knolo cortex find <image> --question "..." [--top-k 100] --out candidates.json\n  knolo cortex ask <image> --question "..." [--graph file] [--plan plan.json] [--mode find_relevant] --out answer.cortex.json\n  knolo cortex explain answer.cortex.json\n  knolo cortex verify --image <image> --answer answer.cortex.json [--graph file]\n\nVerification recomputes the trace roots. It does not mean the answer is true. A KAR status of SATISFIED means evidence requirements were met. It does not mean a claim is proven.',
     'verify-attestation': 'Usage: knolo verify-attestation <attestation.json> [--composition composition.json] [--public-key key.json] [--keyring keyring.json] [--now <ms>] [--content-only]\n\nSame check as knolo attest verify. A bad signature exits 1 even when the content root matches. --content-only checks the content root and ignores the envelope. statement used is not a truth verdict. Hub attested: true is unrelated.',
     icp: 'Usage: knolo icp <command> [options]',
     'semantic:index':
@@ -1865,6 +1868,10 @@ async function main() {
         const { runComposeCli } = await import('./compose.mjs');
         return runComposeCli(command, commandArgs);
       }
+      if (command === 'cortex') {
+        const { runCortexCli } = await import('./cortex.mjs');
+        return runCortexCli(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": "6.1.0",
+  "version": "6.2.0",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
@@ -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/kar.test.mjs test/kar-graph.test.mjs test/kar-produce.test.mjs test/hub.integration.test.mjs test/compose.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/compose.test.mjs test/cortex.test.mjs",
     "test:hub": "node --test test/hub.integration.test.mjs"
   },
   "dependencies": {
-    "@knolo/core": "^6.1.0"
+    "@knolo/core": "^6.2.0"
   },
   "private": false
 }