knosky 0.4.1 → 0.6.0

package/core/bundle.mjs

@@ -0,0 +1,178 @@
+// KnoSky bundle engine (KSV2-R4) — intent-manifest builder with fail-closed secret scan.
+// Pure Node stdlib + internal imports only. ESM. No new deps.
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, relative, isAbsolute, sep } from 'node:path';
+import { findSecrets } from './contract.mjs';
+import { makeIntentManifest, validateIntentManifest } from './schema.mjs';
+import { extractLedgerSeq } from './freshness.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when `ref` is a safe, repo-relative path (not absolute, no "..").
+ * @param {string|undefined} ref
+ * @returns {boolean}
+ */
+function isSafeRef(ref) {
+  if (!ref || typeof ref !== 'string') return false;
+  if (ref.startsWith('/')) return false;
+  // Windows drive: C:\ or C:/
+  if (/^[A-Za-z]:[\\\/]/.test(ref)) return false;
+  if (ref.split(/[/\\]/).some(seg => seg === '..')) return false;
+  return true;
+}
+
+/**
+ * Resolve `ref` under `root` and read it — following symlinks via realpathSync,
+ * then verifying the REAL resolved path still lands inside `root` before the
+ * file is ever opened. `isSafeRef` above only validates the path STRING; it
+ * cannot see that a same-named file on disk is actually a symlink pointing
+ * outside root. This is the actual read boundary (belt-and-suspenders on top
+ * of fs-indexer's own symlink exclusion at index time — this is a separate
+ * read path with its own live filesystem access, so it re-checks independently).
+ *
+ * Never throws. Distinguishes "nothing to scan by design" (no root given —
+ * the caller explicitly opted out of content access) from "root given but the
+ * file could not be verified safe/readable" (fail-closed: caller must treat
+ * this as unscannable, NEVER as clean).
+ *
+ * @param {string|undefined} root
+ * @param {string} ref
+ * @returns {{ buf: Buffer } | { noRoot: true } | { unsafe: true }}
+ */
+function safeRead(root, ref) {
+  if (!root) return { noRoot: true };
+  const full = join(root, ref);
+  let real, rootReal;
+  try {
+    real = realpathSync(full);
+    rootReal = realpathSync(root);
+  } catch {
+    return { unsafe: true }; // missing / broken symlink / permission error — cannot verify
+  }
+  const rel = relative(rootReal, real);
+  if (rel === sep || rel.startsWith('..' + sep) || rel === '..' || isAbsolute(rel)) {
+    return { unsafe: true }; // real path escapes root (symlink pointed outside) — refuse
+  }
+  try {
+    return { buf: readFileSync(real) };
+  } catch {
+    return { unsafe: true };
+  }
+}
+
+/**
+ * Compute the hex SHA-256 of a file. Returns "" when unreadable/unsafe/no-root.
+ * @param {string|undefined} root   Repo root directory, or undefined.
+ * @param {string}           ref    Repo-relative path.
+ * @returns {string}
+ */
+function sha256OfFile(root, ref) {
+  const r = safeRead(root, ref);
+  if (!r.buf) return '';
+  return createHash('sha256').update(r.buf).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// kcBundle — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an intent-manifest for the given node ids.
+ *
+ * @param {object}   ctx              — retrieve context {city:{nodes}, byId:Map}
+ * @param {string[]} ids              — node ids to include
+ * @param {object}   [opts]
+ * @param {string}   [opts.root]      — repo root; used to read files for sha256 + secret scan
+ * @param {string|null} [opts.expiry] — ISO-8601 expiry timestamp or null
+ * @returns {object} intent-manifest (passes validateIntentManifest)
+ */
+export function kcBundle(ctx, ids, { root, expiry = null } = {}) {
+  // Normalise ids to an array of strings
+  const idList = Array.isArray(ids) ? ids.map(String) : [];
+
+  // Build the set of included ids (only those with safe refs)
+  const includedSet = new Set();
+  const refByid = new Map(); // id -> safe ref string
+
+  for (const id of idList) {
+    const node = ctx.byId.get(id);
+    if (!node) continue; // missing node — skip
+    const ref = node.provenance && node.provenance.ref;
+    if (!isSafeRef(ref)) continue; // absolute or ".." — skip
+    includedSet.add(id);
+    refByid.set(id, ref);
+  }
+
+  // Build paths[] with sha256
+  const paths = [];
+  for (const id of idList) {
+    if (!includedSet.has(id)) continue;
+    const ref = refByid.get(id);
+    const sha256 = sha256OfFile(root, ref);
+    paths.push({ path: ref, sha256 });
+  }
+
+  // Build edges[] — out-edges within the bundled set
+  const edges = [];
+  for (const id of idList) {
+    if (!includedSet.has(id)) continue;
+    const node = ctx.byId.get(id);
+    const links = Array.isArray(node.links) ? node.links : [];
+    for (const target of links) {
+      if (includedSet.has(target)) {
+        edges.push({ from: id, to: target });
+      }
+    }
+  }
+
+  // Secret scan — FAIL-CLOSED. Three outcomes per included file:
+  //   noRoot  → caller opted out of content access entirely; nothing to scan by
+  //             design (sha256 is also "" in this mode — a deliberate no-read mode,
+  //             not a failure).
+  //   unsafe  → root WAS given but the file could not be verified safe-and-readable
+  //             (missing, permission error, or a symlink resolving outside root).
+  //             We can no longer prove it's secret-free, so we must NOT call it
+  //             clean — treat it as blocked (the previous behavior silently
+  //             skipped these and returned "clean", a fail-OPEN bug).
+  //   text    → scanned normally.
+  let totalMatches = 0;
+  let blocked = false;
+  let noRootMode = false;
+
+  for (const id of idList) {
+    if (!includedSet.has(id)) continue;
+    const ref = refByid.get(id);
+    const r = safeRead(root, ref);
+    if (r.noRoot) { noRootMode = true; continue; }
+    if (r.unsafe) { blocked = true; continue; }
+    const hits = findSecrets(r.buf.toString('utf8'));
+    if (hits.length > 0) {
+      blocked = true;
+      for (const [, count] of hits) totalMatches += count;
+    }
+  }
+  void noRootMode; // no-root is intentionally a no-op above; named for readability
+
+  const secret_scan = blocked
+    ? { status: 'blocked', count: totalMatches }
+    : { status: 'clean', count: 0 };
+
+  // Ledger-anchored freshness (SAT-444): propagate the monotone commit count
+  // from the city envelope into the manifest so consumers can apply the V13
+  // high-water-mark guard without needing the original city object.
+  const ledger_seq = extractLedgerSeq(ctx.city);
+
+  const manifest = makeIntentManifest({ paths, edges, expiry, secret_scan, ledger_seq });
+
+  // Invariant: manifest MUST pass validateIntentManifest
+  const validation = validateIntentManifest(manifest);
+  if (!validation.ok) {
+    throw new Error('kcBundle produced an invalid intent-manifest: ' + validation.errors.join('; '));
+  }
+
+  return manifest;
+}

package/core/churn.mjs

@@ -1,11 +1,15 @@
 // Git churn (D-155): per-file commit count (windowed) + last-commit timestamp ONLY.
 // No commit messages, diffs, hunks, authors, or line-level churn retained.
-import { execSync } from 'node:child_process';
+// execFileSync + an args array (not execSync + a shell string) — no argument here is
+// externally controlled today, but this matches the args-array-only discipline used by
+// every other git invocation in this codebase (ci.mjs) and removes the shell entirely,
+// so a future edit that adds a dynamic path/ref here can't reintroduce an injection class.
+import { execFileSync } from 'node:child_process';
 
 export function gitChurn(root) {
   const counts = {}, last = {};
   try {
-    const out = execSync('git log --since=90.days.ago --name-only --pretty=format:%ct -- .', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
+    const out = execFileSync('git', ['log', '--since=90.days.ago', '--name-only', '--pretty=format:%ct', '--', '.'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
     let ts = 0;
     for (const raw of out.split(/\r?\n/)) {
       const line = raw.trim();

package/core/ci.mjs

@@ -0,0 +1,268 @@
+// KnoSky CI artifact generator (KSV2-CI1) — PR-GPS advisory artifact.
+// Pure Node stdlib + node:child_process (git, args-array only) + internal imports.
+// HARD RULE: exit 0 by default. Only --fail-on-secret can cause exit 1, and only
+// when secrets are found in the emitted artifacts. Never throws, never breaks builds.
+import { execFileSync } from 'node:child_process';
+import { load } from './retrieve.mjs';
+import { kcRoute } from './route.mjs';
+import { findSecrets } from './contract.mjs';
+
+// ---------------------------------------------------------------------------
+// Path-safety guard (mirrors the one in route.mjs)
+// ---------------------------------------------------------------------------
+
+function isSafePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (p.startsWith('/')) return false;
+  if (/^[A-Za-z]:[\\\/]/.test(p)) return false;
+  if (p.split(/[/\\]/).some(seg => seg === '..')) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Git helper — returns changed file list or [] on any error (advisory, never throws)
+// ---------------------------------------------------------------------------
+
+// A conservative git-ref allowlist: SHAs, branch/tag names, and relative refs
+// (HEAD, HEAD~1, HEAD^). Must NOT start with '-' — that's the belt-and-suspenders
+// layer that stops a ref string looking like a CLI flag (e.g. "--output=...")
+// from ever being handed to git, even before --end-of-options runs.
+function isSafeGitRef(ref) {
+  if (!ref || typeof ref !== 'string') return false;
+  if (ref.length > 200) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._/\-~^:]*$/.test(ref);
+}
+
+function gitChangedFiles(root, base, head) {
+  // Refuse to shell out at all if either ref doesn't look like a ref (layer 1).
+  if (!isSafeGitRef(base) || !isSafeGitRef(head)) return [];
+  try {
+    // --end-of-options (layer 2, git >= 2.24) tells git's option parser that
+    // everything after is a revision, never an option — closes the residual
+    // "ref value that happens to start with '-'" injection even though
+    // execFileSync's args-array already rules out shell injection.
+    const output = execFileSync(
+      'git',
+      ['-C', root, 'diff', '--name-only', '--end-of-options', base + '...' + head],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+    return output.split('\n').map(l => l.trim()).filter(Boolean);
+  } catch (_) {
+    // Any git error → advisory empty set, never break the build
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// summaryMd builder
+// ---------------------------------------------------------------------------
+
+function buildSummaryMd(generatedAt, base, head, routes) {
+  const lines = [];
+  lines.push('## KnoSky PR-GPS — Advisory Navigation Report');
+  lines.push('');
+  lines.push('> **ADVISORY ONLY** — metadata pointers only, no file bodies, never blocks the build.');
+  lines.push('');
+  lines.push(`- Generated: ${generatedAt}`);
+  if (base) lines.push(`- Base: \`${base}\``);
+  if (head) lines.push(`- Head: \`${head}\``);
+  lines.push('');
+
+  if (routes.length === 0) {
+    lines.push('_No changed files detected in this PR._');
+  } else {
+    for (const { file, route: routeDoc } of routes) {
+      lines.push(`### \`${file}\``);
+      lines.push('');
+      const topWaypoints = (routeDoc.route || []).slice(0, 5);
+      if (topWaypoints.length === 0) {
+        lines.push('_No route waypoints found in the index for this file._');
+      } else {
+        lines.push('**Route waypoints:**');
+        lines.push('');
+        for (const wp of topWaypoints) {
+          const path = typeof wp === 'string' ? wp : (wp && wp.path) || '';
+          const reason = (wp && wp.reason) || '';
+          lines.push(`- \`${path}\`${reason ? ' — ' + reason : ''}`);
+        }
+      }
+      const confidence = typeof routeDoc.confidence === 'number'
+        ? Math.round(routeDoc.confidence * 100) + '%'
+        : 'n/a';
+      lines.push('');
+      lines.push(`**Confidence:** ${confidence}`);
+      const caveats = (routeDoc.caveats || []).filter(c =>
+        c.includes('recently changed') || c.includes('stale') || c.includes('coverage'),
+      );
+      if (caveats.length > 0) {
+        lines.push('');
+        lines.push('**Caveats:**');
+        for (const c of caveats) lines.push(`- ${c}`);
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('---');
+  lines.push('_This report is advisory. KnoSky reads metadata only — it does not read code meaning._');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// knoskyCi — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate the KnoSky PR-GPS advisory artifacts.
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.root='.']         Repo root for git commands.
+ * @param {string}   [opts.base]             Base ref for git diff.
+ * @param {string}   [opts.head]             Head ref for git diff.
+ * @param {string}   [opts.cityPath]         Path to city-data.json (city index).
+ * @param {boolean}  [opts.failOnSecret=false] Exit 1 only if secrets found in artifacts.
+ * @param {string[]} [opts.changedFiles]     Inject changed files directly (test seam — skips git).
+ * @returns {{ exitCode: number, summaryMd: string, routeJson: object, safetyJson: object }}
+ */
+export async function knoskyCi({
+  root = '.',
+  base,
+  head,
+  cityPath,
+  failOnSecret = false,
+  changedFiles,
+} = {}) {
+  const generatedAt = new Date().toISOString();
+
+  // 1. Resolve changed files
+  let files;
+  if (Array.isArray(changedFiles)) {
+    // Test seam — use injected list directly, no git needed
+    files = changedFiles;
+  } else {
+    // Resolve base/head from args, then environment, then fallback
+    const resolvedBase = base || process.env.GITHUB_BASE_REF || 'HEAD~1';
+    const resolvedHead = head || process.env.GITHUB_SHA || 'HEAD';
+    files = gitChangedFiles(root, resolvedBase, resolvedHead);
+  }
+
+  const resolvedBase = base || process.env.GITHUB_BASE_REF || null;
+  const resolvedHead = head || process.env.GITHUB_SHA || null;
+
+  // 2. Load the city index — if absent/unreadable, produce advisory summary and exit 0
+  let ctx;
+  if (!cityPath) {
+    const summaryMd = buildNoIndexSummary(generatedAt, resolvedBase, resolvedHead);
+    return {
+      exitCode: 0,
+      summaryMd,
+      routeJson: buildRouteJson(generatedAt, resolvedBase, resolvedHead, []),
+      safetyJson: buildSafetyJson(generatedAt, 0),
+    };
+  }
+
+  try {
+    ctx = load(cityPath);
+  } catch (_) {
+    const summaryMd = buildNoIndexSummary(generatedAt, resolvedBase, resolvedHead);
+    return {
+      exitCode: 0,
+      summaryMd,
+      routeJson: buildRouteJson(generatedAt, resolvedBase, resolvedHead, []),
+      safetyJson: buildSafetyJson(generatedAt, 0),
+    };
+  }
+
+  // 3. For each changed file, call kcRoute — metadata only, no file bodies
+  const routes = [];
+  for (const relpath of files) {
+    // Safety: skip any path that escapes the repo
+    if (!isSafePath(relpath)) continue;
+    let routeDoc;
+    try {
+      routeDoc = kcRoute(ctx, 'file:' + relpath);
+    } catch (_) {
+      // Route errors are advisory — skip this file, never break
+      continue;
+    }
+    // Drop any route entries with unsafe paths (defense in depth)
+    if (routeDoc && Array.isArray(routeDoc.route)) {
+      routeDoc.route = routeDoc.route.filter(wp => {
+        const p = typeof wp === 'string' ? wp : (wp && wp.path);
+        return !p || isSafePath(p);
+      });
+    }
+    if (routeDoc && Array.isArray(routeDoc.alternates)) {
+      routeDoc.alternates = routeDoc.alternates.filter(wp => {
+        const p = typeof wp === 'string' ? wp : (wp && wp.path);
+        return !p || isSafePath(p);
+      });
+    }
+    routes.push({ file: relpath, route: routeDoc });
+  }
+
+  // 4. Build routeJson
+  const routeJson = buildRouteJson(generatedAt, resolvedBase, resolvedHead, routes);
+
+  // 5. Build summaryMd
+  const summaryMd = buildSummaryMd(generatedAt, resolvedBase, resolvedHead, routes);
+
+  // 6. Scan ONLY the emitted artifacts for secrets (defense in depth)
+  const artifactText = summaryMd + '\n' + JSON.stringify(routeJson);
+  const secretHits = findSecrets(artifactText);
+  const secretsFound = secretHits.reduce((n, [, count]) => n + count, 0);
+
+  // 7. Build safetyJson
+  const safetyJson = buildSafetyJson(generatedAt, secretsFound);
+
+  // 8. exitCode: only failOnSecret+secrets_found > 0 can be non-zero
+  const exitCode = (failOnSecret && secretsFound > 0) ? 1 : 0;
+
+  return { exitCode, summaryMd, routeJson, safetyJson };
+}
+
+// ---------------------------------------------------------------------------
+// Artifact builders
+// ---------------------------------------------------------------------------
+
+function buildNoIndexSummary(generatedAt, base, head) {
+  const lines = [
+    '## KnoSky PR-GPS — Advisory Navigation Report',
+    '',
+    '> **ADVISORY ONLY** — metadata pointers only, no file bodies, never blocks the build.',
+    '',
+    `- Generated: ${generatedAt}`,
+  ];
+  if (base) lines.push(`- Base: \`${base}\``);
+  if (head) lines.push(`- Head: \`${head}\``);
+  lines.push('');
+  lines.push('_No index available — run `knosky <path>` to build the city index first._');
+  lines.push('');
+  lines.push('---');
+  lines.push('_This report is advisory. KnoSky reads metadata only._');
+  return lines.join('\n');
+}
+
+function buildRouteJson(generatedAt, base, head, routes) {
+  return {
+    knosky_protocol: '1.0',
+    artifact_type: 'pr-route',
+    advisory: true,
+    generated_at: generatedAt,
+    base: base || null,
+    head: head || null,
+    routes: routes.map(({ file, route }) => ({ file, route })),
+  };
+}
+
+function buildSafetyJson(generatedAt, secretsFound) {
+  return {
+    knosky_protocol: '1.0',
+    artifact_type: 'safety-report',
+    advisory: true,
+    generated_at: generatedAt,
+    absolute_paths: false,
+    secrets_found: secretsFound,
+    redaction: 'metadata-only; no file bodies; no absolute paths',
+  };
+}

package/core/comparison.mjs

@@ -0,0 +1,189 @@
+// KnoSky naive-vs-guided agent comparison protocol (SAT-458).
+// Defines the artifact schema and validators for a single comparison run:
+//   tokens (in + out), tool-calls, time-to-relevant-file, correctness
+// for both a naive agent and an identical task run with KnoSky guidance.
+// Pure Node stdlib, ESM — no new deps.
+
+import { PROTOCOL_VERSION } from './schema.mjs';
+
+// ---------------------------------------------------------------------------
+// Artifact type constant
+// ---------------------------------------------------------------------------
+
+/** @type {string} */
+export const COMPARISON_ARTIFACT_TYPE = 'comparison-run';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when `p` is a relative-safe file path:
+ *   — non-empty string
+ *   — does not start with `/` (Unix absolute) or Windows drive letter
+ *   — contains no `..` path segment
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isRelativeSafePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (p.startsWith('/')) return false;
+  if (/^[A-Za-z]:[\\\/]/.test(p)) return false;
+  if (p.split(/[/\\]/).some(s => s === '..')) return false;
+  return true;
+}
+
+/**
+ * Validate one metric side object (either `naive` or `guided`).
+ * Returns an array of violation strings; empty means valid.
+ *
+ * @param {unknown} side
+ * @param {string}  label   — "naive" or "guided"
+ * @returns {string[]}
+ */
+function validateSide(side, label) {
+  const errors = [];
+
+  if (!side || typeof side !== 'object') {
+    errors.push(`${label} must be an object`);
+    return errors; // can't go further
+  }
+
+  // tokens_in: non-negative integer
+  if (!Number.isInteger(side.tokens_in) || side.tokens_in < 0) {
+    errors.push(`${label}.tokens_in must be a non-negative integer, got: ${JSON.stringify(side.tokens_in)}`);
+  }
+
+  // tokens_out: non-negative integer
+  if (!Number.isInteger(side.tokens_out) || side.tokens_out < 0) {
+    errors.push(`${label}.tokens_out must be a non-negative integer, got: ${JSON.stringify(side.tokens_out)}`);
+  }
+
+  // tool_calls: non-negative integer
+  if (!Number.isInteger(side.tool_calls) || side.tool_calls < 0) {
+    errors.push(`${label}.tool_calls must be a non-negative integer, got: ${JSON.stringify(side.tool_calls)}`);
+  }
+
+  // time_to_relevant_file_ms: null (never found) or non-negative number
+  const ttrf = side.time_to_relevant_file_ms;
+  if (ttrf !== null && !(typeof ttrf === 'number' && ttrf >= 0)) {
+    errors.push(
+      `${label}.time_to_relevant_file_ms must be null or a non-negative number, got: ${JSON.stringify(ttrf)}`,
+    );
+  }
+
+  // correct: boolean
+  if (typeof side.correct !== 'boolean') {
+    errors.push(`${label}.correct must be a boolean, got: ${JSON.stringify(side.correct)}`);
+  }
+
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// makeComparisonRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a KnoSky `comparison-run` artifact envelope.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.task_id             Short identifier for this task.
+ * @param {string}   opts.task_description    Human-readable description of the task.
+ * @param {string[]} opts.target_files        Relative paths to the "relevant" files for this task.
+ * @param {object}   opts.naive               Metrics for the naive agent (no KnoSky guidance).
+ * @param {number}   opts.naive.tokens_in     Input tokens consumed.
+ * @param {number}   opts.naive.tokens_out    Output tokens produced.
+ * @param {number}   opts.naive.tool_calls    Total tool/function calls made.
+ * @param {number|null} opts.naive.time_to_relevant_file_ms  ms until first relevant-file hit, or null.
+ * @param {boolean}  opts.naive.correct       Whether the agent arrived at the correct answer.
+ * @param {object}   opts.guided              Same metric shape for the KnoSky-guided agent.
+ * @returns {object}
+ */
+export function makeComparisonRun({
+  task_id,
+  task_description,
+  target_files = [],
+  naive,
+  guided,
+} = {}) {
+  return {
+    knosky_protocol: PROTOCOL_VERSION,
+    artifact_type: COMPARISON_ARTIFACT_TYPE,
+    advisory: true,
+    generated_at: new Date().toISOString(),
+    task_id,
+    task_description,
+    target_files,
+    naive,
+    guided,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateComparisonRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a KnoSky `comparison-run` document.
+ * Collects every violation; `ok` is true only when `errors` is empty.
+ *
+ * @param {object} doc
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateComparisonRun(doc) {
+  const errors = [];
+
+  if (!doc || typeof doc !== 'object') {
+    return { ok: false, errors: ['doc must be an object'] };
+  }
+
+  if (doc.knosky_protocol !== PROTOCOL_VERSION) {
+    errors.push(
+      `knosky_protocol must be "${PROTOCOL_VERSION}", got: ${JSON.stringify(doc.knosky_protocol)}`,
+    );
+  }
+
+  if (doc.artifact_type !== COMPARISON_ARTIFACT_TYPE) {
+    errors.push(
+      `artifact_type must be "${COMPARISON_ARTIFACT_TYPE}", got: ${JSON.stringify(doc.artifact_type)}`,
+    );
+  }
+
+  if (doc.advisory !== true) {
+    errors.push(`advisory must be true, got: ${JSON.stringify(doc.advisory)}`);
+  }
+
+  // task_id: non-empty string
+  if (typeof doc.task_id !== 'string' || doc.task_id.length === 0) {
+    errors.push(`task_id must be a non-empty string, got: ${JSON.stringify(doc.task_id)}`);
+  }
+
+  // task_description: non-empty string
+  if (typeof doc.task_description !== 'string' || doc.task_description.length === 0) {
+    errors.push(
+      `task_description must be a non-empty string, got: ${JSON.stringify(doc.task_description)}`,
+    );
+  }
+
+  // target_files: non-empty array of relative-safe path strings
+  if (!Array.isArray(doc.target_files) || doc.target_files.length === 0) {
+    errors.push('target_files must be a non-empty array');
+  } else {
+    for (let i = 0; i < doc.target_files.length; i++) {
+      const p = doc.target_files[i];
+      if (typeof p !== 'string' || p.length === 0) {
+        errors.push(`target_files[${i}] must be a non-empty string`);
+      } else if (!isRelativeSafePath(p)) {
+        errors.push(`target_files[${i}] must be a relative path with no ".." segments: ${JSON.stringify(p)}`);
+      }
+    }
+  }
+
+  // naive and guided sides
+  for (const side of ['naive', 'guided']) {
+    errors.push(...validateSide(doc[side], side));
+  }
+
+  return { ok: errors.length === 0, errors };
+}