knosky 0.6.3 → 0.7.0

package/core/config.mjs

@@ -1,189 +1,189 @@
-// KnoSky protocol config schema, loader, and validator (SAT-426 / KSV2-P1).
-// Pure Node stdlib, ESM — no third-party dependencies.
-import fs from 'node:fs';
-import path from 'node:path';
-
-// ---------------------------------------------------------------------------
-// DEFAULTS — the canonical safe config for every knosky project.
-// ---------------------------------------------------------------------------
-
-/** @type {Readonly<KnoskyConfig>} */
-export const DEFAULTS = Object.freeze({
-  knosky_protocol: '1.0',
-  telemetry: false,
-  absolute_paths: false,
-  fail_on_secret: true,
-  allow_excerpts: false,
-  max_excerpt_chars: 0,
-  categories: [],
-  ignore: [],
-});
-
-// ---------------------------------------------------------------------------
-// parseConfigYaml — minimal YAML-subset parser, no deps.
-// Supports: `key: value` lines, booleans, integers, bare/quoted strings,
-// block lists (`- item` lines following a `key:` line with no inline value).
-// Ignores blank lines and # comments.
-// Throws on any line it cannot interpret for a known key.
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a minimal YAML subset used by `.knosky/config.yml`.
- *
- * @param {string} text  Raw file contents.
- * @returns {Record<string, unknown>}  Parsed key/value map.
- */
-export function parseConfigYaml(text) {
-  const result = {};
-  const lines = text.split(/\r?\n/);
-  let i = 0;
-
-  while (i < lines.length) {
-    const raw = lines[i];
-    // Strip inline comment and trim
-    const line = raw.replace(/#.*$/, '').trimEnd();
-    i++;
-
-    if (!line.trim()) continue; // blank / comment-only
-
-    // Must be a `key: [value]` line at the top level (no leading spaces)
-    const kvMatch = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)/);
-    if (!kvMatch) {
-      throw new Error(`parseConfigYaml: unexpected line: ${JSON.stringify(raw)}`);
-    }
-    const key = kvMatch[1];
-    const rest = kvMatch[2].trim();
-
-    if (rest === '') {
-      // Possibly a block list — collect `  - item` lines that follow
-      const items = [];
-      while (i < lines.length) {
-        const next = lines[i].replace(/#.*$/, '');
-        if (/^\s*-\s/.test(next)) {
-          items.push(next.replace(/^\s*-\s*/, '').trim());
-          i++;
-        } else {
-          break;
-        }
-      }
-      result[key] = items;
-    } else {
-      result[key] = parseScalar(rest, key);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Parse a scalar YAML value: boolean, integer, or string (bare or quoted).
- *
- * @param {string} raw  The raw value string (already trimmed).
- * @param {string} key  The key name, used for error messages.
- * @returns {boolean|number|string}
- */
-function parseScalar(raw, key) {
-  if (raw === 'true') return true;
-  if (raw === 'false') return false;
-
-  // Integer
-  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
-
-  // Double-quoted string
-  if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
-
-  // Single-quoted string
-  if (raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
-
-  // Bare string — must not contain characters that signal unhandled YAML
-  if (/^[A-Za-z0-9._\-/ ]+$/.test(raw)) return raw;
-
-  throw new Error(`parseConfigYaml: cannot parse value for key "${key}": ${JSON.stringify(raw)}`);
-}
-
-// ---------------------------------------------------------------------------
-// loadConfig — read + parse `.knosky/config.yml`, merge over DEFAULTS.
-// Fail-closed: throws on parse error; returns DEFAULTS copy if file absent.
-// ---------------------------------------------------------------------------
-
-/**
- * Load `.knosky/config.yml` from `root` and merge it over {@link DEFAULTS}.
- * Returns a plain object (not frozen).  Throws if the file exists but is
- * malformed.
- *
- * @param {string} root  Absolute (or relative) project root.
- * @returns {Record<string, unknown>}  Merged config object.
- */
-export function loadConfig(root) {
-  const cfgPath = path.join(root, '.knosky', 'config.yml');
-
-  let text;
-  try {
-    text = fs.readFileSync(cfgPath, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      // File absent — return a safe copy of defaults
-      return { ...DEFAULTS, categories: [], ignore: [] };
-    }
-    throw err; // permission error, etc — still fail-closed
-  }
-
-  // File exists: parse (throws on malformed — never silently fall back)
-  const parsed = parseConfigYaml(text);
-
-  // Deep-merge: parsed wins per-key; arrays are replaced, not concatenated.
-  return { ...DEFAULTS, categories: [], ignore: [], ...parsed };
-}
-
-// ---------------------------------------------------------------------------
-// validateConfig — collect all constraint violations, return { ok, errors }.
-// ---------------------------------------------------------------------------
-
-const BOOLEAN_KEYS = ['telemetry', 'absolute_paths', 'fail_on_secret', 'allow_excerpts'];
-
-/**
- * Validate a config object against the KnoSky protocol schema.
- * Collects every violation; `ok` is true only when `errors` is empty.
- *
- * @param {Record<string, unknown>} cfg  Config object (e.g. from {@link loadConfig}).
- * @returns {{ ok: boolean, errors: string[] }}
- */
-export function validateConfig(cfg) {
-  const errors = [];
-  const knownKeys = new Set(Object.keys(DEFAULTS));
-
-  // knosky_protocol must be the string "1.0"
-  if (cfg.knosky_protocol !== '1.0') {
-    errors.push(`knosky_protocol must be "1.0", got: ${JSON.stringify(cfg.knosky_protocol)}`);
-  }
-
-  // Boolean fields
-  for (const k of BOOLEAN_KEYS) {
-    if (typeof cfg[k] !== 'boolean') {
-      errors.push(`${k} must be a boolean, got: ${JSON.stringify(cfg[k])}`);
-    }
-  }
-
-  // max_excerpt_chars must be integer >= 0
-  const mec = cfg.max_excerpt_chars;
-  if (!Number.isInteger(mec) || mec < 0) {
-    errors.push(`max_excerpt_chars must be an integer >= 0, got: ${JSON.stringify(mec)}`);
-  }
-
-  // categories and ignore must be arrays of strings
-  for (const k of ['categories', 'ignore']) {
-    const val = cfg[k];
-    if (!Array.isArray(val) || val.some(v => typeof v !== 'string')) {
-      errors.push(`${k} must be an array of strings, got: ${JSON.stringify(val)}`);
-    }
-  }
-
-  // Unknown keys
-  for (const k of Object.keys(cfg)) {
-    if (!knownKeys.has(k)) {
-      errors.push(`unknown config key: ${k}`);
-    }
-  }
-
-  return { ok: errors.length === 0, errors };
-}
+// KnoSky protocol config schema, loader, and validator (SAT-426 / KSV2-P1).
+// Pure Node stdlib, ESM — no third-party dependencies.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// DEFAULTS — the canonical safe config for every knosky project.
+// ---------------------------------------------------------------------------
+
+/** @type {Readonly<KnoskyConfig>} */
+export const DEFAULTS = Object.freeze({
+  knosky_protocol: '1.0',
+  telemetry: false,
+  absolute_paths: false,
+  fail_on_secret: true,
+  allow_excerpts: false,
+  max_excerpt_chars: 0,
+  categories: [],
+  ignore: [],
+});
+
+// ---------------------------------------------------------------------------
+// parseConfigYaml — minimal YAML-subset parser, no deps.
+// Supports: `key: value` lines, booleans, integers, bare/quoted strings,
+// block lists (`- item` lines following a `key:` line with no inline value).
+// Ignores blank lines and # comments.
+// Throws on any line it cannot interpret for a known key.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a minimal YAML subset used by `.knosky/config.yml`.
+ *
+ * @param {string} text  Raw file contents.
+ * @returns {Record<string, unknown>}  Parsed key/value map.
+ */
+export function parseConfigYaml(text) {
+  const result = {};
+  const lines = text.split(/\r?\n/);
+  let i = 0;
+
+  while (i < lines.length) {
+    const raw = lines[i];
+    // Strip inline comment and trim
+    const line = raw.replace(/#.*$/, '').trimEnd();
+    i++;
+
+    if (!line.trim()) continue; // blank / comment-only
+
+    // Must be a `key: [value]` line at the top level (no leading spaces)
+    const kvMatch = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)/);
+    if (!kvMatch) {
+      throw new Error(`parseConfigYaml: unexpected line: ${JSON.stringify(raw)}`);
+    }
+    const key = kvMatch[1];
+    const rest = kvMatch[2].trim();
+
+    if (rest === '') {
+      // Possibly a block list — collect `  - item` lines that follow
+      const items = [];
+      while (i < lines.length) {
+        const next = lines[i].replace(/#.*$/, '');
+        if (/^\s*-\s/.test(next)) {
+          items.push(next.replace(/^\s*-\s*/, '').trim());
+          i++;
+        } else {
+          break;
+        }
+      }
+      result[key] = items;
+    } else {
+      result[key] = parseScalar(rest, key);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse a scalar YAML value: boolean, integer, or string (bare or quoted).
+ *
+ * @param {string} raw  The raw value string (already trimmed).
+ * @param {string} key  The key name, used for error messages.
+ * @returns {boolean|number|string}
+ */
+function parseScalar(raw, key) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+
+  // Integer
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+
+  // Double-quoted string
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
+
+  // Single-quoted string
+  if (raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+
+  // Bare string — must not contain characters that signal unhandled YAML
+  if (/^[A-Za-z0-9._\-/ ]+$/.test(raw)) return raw;
+
+  throw new Error(`parseConfigYaml: cannot parse value for key "${key}": ${JSON.stringify(raw)}`);
+}
+
+// ---------------------------------------------------------------------------
+// loadConfig — read + parse `.knosky/config.yml`, merge over DEFAULTS.
+// Fail-closed: throws on parse error; returns DEFAULTS copy if file absent.
+// ---------------------------------------------------------------------------
+
+/**
+ * Load `.knosky/config.yml` from `root` and merge it over {@link DEFAULTS}.
+ * Returns a plain object (not frozen).  Throws if the file exists but is
+ * malformed.
+ *
+ * @param {string} root  Absolute (or relative) project root.
+ * @returns {Record<string, unknown>}  Merged config object.
+ */
+export function loadConfig(root) {
+  const cfgPath = path.join(root, '.knosky', 'config.yml');
+
+  let text;
+  try {
+    text = fs.readFileSync(cfgPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // File absent — return a safe copy of defaults
+      return { ...DEFAULTS, categories: [], ignore: [] };
+    }
+    throw err; // permission error, etc — still fail-closed
+  }
+
+  // File exists: parse (throws on malformed — never silently fall back)
+  const parsed = parseConfigYaml(text);
+
+  // Deep-merge: parsed wins per-key; arrays are replaced, not concatenated.
+  return { ...DEFAULTS, categories: [], ignore: [], ...parsed };
+}
+
+// ---------------------------------------------------------------------------
+// validateConfig — collect all constraint violations, return { ok, errors }.
+// ---------------------------------------------------------------------------
+
+const BOOLEAN_KEYS = ['telemetry', 'absolute_paths', 'fail_on_secret', 'allow_excerpts'];
+
+/**
+ * Validate a config object against the KnoSky protocol schema.
+ * Collects every violation; `ok` is true only when `errors` is empty.
+ *
+ * @param {Record<string, unknown>} cfg  Config object (e.g. from {@link loadConfig}).
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateConfig(cfg) {
+  const errors = [];
+  const knownKeys = new Set(Object.keys(DEFAULTS));
+
+  // knosky_protocol must be the string "1.0"
+  if (cfg.knosky_protocol !== '1.0') {
+    errors.push(`knosky_protocol must be "1.0", got: ${JSON.stringify(cfg.knosky_protocol)}`);
+  }
+
+  // Boolean fields
+  for (const k of BOOLEAN_KEYS) {
+    if (typeof cfg[k] !== 'boolean') {
+      errors.push(`${k} must be a boolean, got: ${JSON.stringify(cfg[k])}`);
+    }
+  }
+
+  // max_excerpt_chars must be integer >= 0
+  const mec = cfg.max_excerpt_chars;
+  if (!Number.isInteger(mec) || mec < 0) {
+    errors.push(`max_excerpt_chars must be an integer >= 0, got: ${JSON.stringify(mec)}`);
+  }
+
+  // categories and ignore must be arrays of strings
+  for (const k of ['categories', 'ignore']) {
+    const val = cfg[k];
+    if (!Array.isArray(val) || val.some(v => typeof v !== 'string')) {
+      errors.push(`${k} must be an array of strings, got: ${JSON.stringify(val)}`);
+    }
+  }
+
+  // Unknown keys
+  for (const k of Object.keys(cfg)) {
+    if (!knownKeys.has(k)) {
+      errors.push(`unknown config key: ${k}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/core/constants.mjs

@@ -1,13 +1,13 @@
-// Shared, dependency-free constants used by more than one core module.
-// Kept in its own file (no imports, no side effects) so any core/*.mjs can
-// import from it without creating a circular dependency between modules.
-
-// Upper bound for a plausible ledger sequence (git commit count). 1 billion
-// is far beyond any real repo's commit count and far below
-// Number.MAX_SAFE_INTEGER (~9e15), so it rejects implausible/attacker-
-// supplied values (e.g. 1e100) with no precision-loss risk of its own.
-// Enforced independently at two layers — core/freshness.mjs's
-// extractLedgerSeq (structural validation) and core/ledger.mjs's
-// checkAndAdvance (the persisted guard itself) — both import this single
-// source of truth so the two layers cannot silently diverge.
-export const MAX_PLAUSIBLE_LEDGER_SEQ = 1_000_000_000;
+// Shared, dependency-free constants used by more than one core module.
+// Kept in its own file (no imports, no side effects) so any core/*.mjs can
+// import from it without creating a circular dependency between modules.
+
+// Upper bound for a plausible ledger sequence (git commit count). 1 billion
+// is far beyond any real repo's commit count and far below
+// Number.MAX_SAFE_INTEGER (~9e15), so it rejects implausible/attacker-
+// supplied values (e.g. 1e100) with no precision-loss risk of its own.
+// Enforced independently at two layers — core/freshness.mjs's
+// extractLedgerSeq (structural validation) and core/ledger.mjs's
+// checkAndAdvance (the persisted guard itself) — both import this single
+// source of truth so the two layers cannot silently diverge.
+export const MAX_PLAUSIBLE_LEDGER_SEQ = 1_000_000_000;

package/core/contract.mjs

@@ -1,123 +1,123 @@
-// KC city-data CONTRACT v2 — the shared spine.
-// Generalizes the fixed-4-district v1 → N categories. Pointers + projections ONLY (D-146); never bodies.
-// Council fixes baked in: serialization ALLOWLIST at the edge + best-effort DENYLIST scrub.
-
-export const SCHEMA_VERSION = '2.0';
-
-// The ONLY node fields that may ever be serialized into the index. Anything else is dropped/flagged.
-export const NODE_FIELD_ALLOWLIST = [
-  'id', 'kind', 'title', 'summary', 'category', 'status',
-  'fact_date', 'tags', 'headings', 'links', 'churn', 'provenance', 'visibility', 'sensitive',
-];
-export const NODE_REQUIRED = ['id', 'kind', 'title', 'category', 'links', 'provenance'];
-export const PROVENANCE_REQUIRED = ['store', 'ref'];
-export const CATEGORY_REQUIRED = ['id', 'label', 'order'];
-export const SUMMARY_MAX = 200;
-
-// Detection patterns for the fail-closed safe-share audit (broader than the scrub list below).
-export const SECRET_PATTERNS = [
-  [/AKIA[0-9A-Z]{16}/g, 'aws-access-key'],
-  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'private-key'],
-  [/\bgh[posru]_[A-Za-z0-9]{20,}\b/g, 'github-token'],
-  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, 'github-pat'],
-  [/\bsk-[A-Za-z0-9]{20,}\b/g, 'openai-key'],
-  [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, 'stripe-key'],
-  [/\bAIza[0-9A-Za-z_\-]{35}\b/g, 'google-api-key'],
-  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, 'slack-token'],
-  [/\bglpat-[A-Za-z0-9_\-]{20,}\b/g, 'gitlab-pat'],
-  [/\bnpm_[A-Za-z0-9]{36}\b/g, 'npm-token'],
-  [/\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\b/g, 'jwt'],
-];
-export function findSecrets(text) {
-  const s = String(text); const hits = [];
-  for (const [re, kind] of SECRET_PATTERNS) { const m = s.match(re); if (m && m.length) hits.push([kind, m.length]); }
-  return hits;
-}
-
-// Best-effort secret/PII denylist applied to emitted text projections. Backed by the indexer's
-// fail-closed findSecrets() audit on the final artifact (defense in depth, not a single boundary).
-const DENY = [
-  /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,                 // emails
-  /\b(?:api[_-]?key|secret|token|password|passwd|bearer)\b\s*[:=]\s*\S+/gi,
-  ...SECRET_PATTERNS.map(([re]) => re),
-];
-// Optional project-specific sensitive terms (e.g. an employer/customer name) → redacted too.
-let EXTRA_TERMS = [];
-export function setRedactTerms(terms) {
-  EXTRA_TERMS = (terms || []).map(t => String(t).trim()).filter(Boolean)
-    .map(t => new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'gi'));
-}
-export function scrubText(s) {
-  if (typeof s !== 'string') return s;
-  let out = s;
-  for (const re of DENY) out = out.replace(re, '[REDACTED]');
-  for (const re of EXTRA_TERMS) out = out.replace(re, '[REDACTED]');
-  return out;
-}
-
-// Default path/dir ignores (the indexer also honors the repo's .gitignore + a user .kcignore).
-export const IGNORE_DEFAULTS = [
-  /(^|\/)\.git(\/|$)/, /(^|\/)node_modules(\/|$)/, /(^|\/)secrets?(\/|$)/i,
-  /(^|\/)keys?(\/|$)/i, /(^|\/)\.env/i, /(^|\/)dist(\/|$)/,
-];
-
-// Serialize one node: keep ONLY allowlisted fields, scrub text, clamp summary.
-export function serializeNode(n) {
-  const o = {};
-  for (const k of NODE_FIELD_ALLOWLIST) if (n[k] !== undefined) o[k] = n[k];
-  if (typeof o.title === 'string') o.title = scrubText(o.title);
-  if (typeof o.summary === 'string') o.summary = scrubText(o.summary).slice(0, SUMMARY_MAX);
-  if (Array.isArray(o.headings)) o.headings = o.headings.map(scrubText);
-  if (Array.isArray(o.tags)) o.tags = o.tags.map(scrubText);
-  return o;
-}
-
-// Validate a city envelope against the contract. Returns { ok, errors[] }.
-export function validateCity(city) {
-  const errors = [];
-  if (!city || typeof city !== 'object') return { ok: false, errors: ['city is not an object'] };
-  if (city.schema_version !== SCHEMA_VERSION) errors.push(`schema_version != ${SCHEMA_VERSION}`);
-  if (!Array.isArray(city.categories)) errors.push('missing categories[] manifest');
-  if (!Array.isArray(city.nodes)) errors.push('missing nodes[]');
-  const catIds = new Set((city.categories || []).map(c => c.id));
-  (city.categories || []).forEach((c, i) => {
-    for (const k of CATEGORY_REQUIRED) if (c[k] === undefined) errors.push(`category[${i}] missing ${k}`);
-  });
-  const ids = new Set();
-  (city.nodes || []).forEach((n, i) => {
-    for (const k of NODE_REQUIRED) if (n[k] === undefined) errors.push(`node[${i}] missing ${k}`);
-    if (n.category && !catIds.has(n.category)) errors.push(`node[${i}] category '${n.category}' not in manifest`);
-    if (n.id) { if (ids.has(n.id)) errors.push(`duplicate id ${n.id}`); ids.add(n.id); }
-    if (n.provenance) for (const k of PROVENANCE_REQUIRED) if (n.provenance[k] === undefined) errors.push(`node[${i}] provenance missing ${k}`);
-    if (typeof n.summary === 'string' && n.summary.length > SUMMARY_MAX) errors.push(`node[${i}] summary > ${SUMMARY_MAX}`);
-    for (const k of Object.keys(n)) if (!NODE_FIELD_ALLOWLIST.includes(k)) errors.push(`node[${i}] non-allowlisted field '${k}'`);
-  });
-  if (city.node_count !== undefined && city.node_count !== (city.nodes || []).length) errors.push('node_count mismatch');
-  return { ok: errors.length === 0, errors };
-}
-
-const PALETTE = ['#4f8cff', '#34c759', '#ff9f0a', '#af52de', '#ff375f', '#5ac8fa', '#ffd60a', '#bf5af2', '#30d158', '#ff6482'];
-
-// Build a categories[] manifest from a list of category ids (stable order + palette).
-export function deriveCategories(ids) {
-  return ids.map((id, i) => ({
-    id, label: String(id).charAt(0).toUpperCase() + String(id).slice(1),
-    color: PALETTE[i % PALETTE.length], order: i,
-  }));
-}
-
-// Legacy adapter: v1 (district, no categories[]) → v2 (category + categories[] manifest), via the allowlist.
-export function adaptLegacy(cityV1) {
-  const ids = [...new Set((cityV1.nodes || []).map(n => n.district).filter(Boolean))];
-  const categories = deriveCategories(ids);
-  const nodes = (cityV1.nodes || []).map(n => {
-    const { district, ...rest } = n;
-    return serializeNode({ ...rest, category: district });
-  });
-  return {
-    schema_version: SCHEMA_VERSION,
-    generated_at: cityV1.generated_at || new Date().toISOString(),
-    source: { kind: 'legacy', ref: cityV1.source_rev || 'unknown', rev: cityV1.source_rev || 'unknown' },
-    categories, node_count: nodes.length, nodes,
-  };
-}
+// KC city-data CONTRACT v2 — the shared spine.
+// Generalizes the fixed-4-district v1 → N categories. Pointers + projections ONLY (D-146); never bodies.
+// Council fixes baked in: serialization ALLOWLIST at the edge + best-effort DENYLIST scrub.
+
+export const SCHEMA_VERSION = '2.0';
+
+// The ONLY node fields that may ever be serialized into the index. Anything else is dropped/flagged.
+export const NODE_FIELD_ALLOWLIST = [
+  'id', 'kind', 'title', 'summary', 'category', 'status',
+  'fact_date', 'tags', 'headings', 'links', 'churn', 'provenance', 'visibility', 'sensitive',
+];
+export const NODE_REQUIRED = ['id', 'kind', 'title', 'category', 'links', 'provenance'];
+export const PROVENANCE_REQUIRED = ['store', 'ref'];
+export const CATEGORY_REQUIRED = ['id', 'label', 'order'];
+export const SUMMARY_MAX = 200;
+
+// Detection patterns for the fail-closed safe-share audit (broader than the scrub list below).
+export const SECRET_PATTERNS = [
+  [/AKIA[0-9A-Z]{16}/g, 'aws-access-key'],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'private-key'],
+  [/\bgh[posru]_[A-Za-z0-9]{20,}\b/g, 'github-token'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, 'github-pat'],
+  [/\bsk-[A-Za-z0-9]{20,}\b/g, 'openai-key'],
+  [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, 'stripe-key'],
+  [/\bAIza[0-9A-Za-z_\-]{35}\b/g, 'google-api-key'],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, 'slack-token'],
+  [/\bglpat-[A-Za-z0-9_\-]{20,}\b/g, 'gitlab-pat'],
+  [/\bnpm_[A-Za-z0-9]{36}\b/g, 'npm-token'],
+  [/\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\b/g, 'jwt'],
+];
+export function findSecrets(text) {
+  const s = String(text); const hits = [];
+  for (const [re, kind] of SECRET_PATTERNS) { const m = s.match(re); if (m && m.length) hits.push([kind, m.length]); }
+  return hits;
+}
+
+// Best-effort secret/PII denylist applied to emitted text projections. Backed by the indexer's
+// fail-closed findSecrets() audit on the final artifact (defense in depth, not a single boundary).
+const DENY = [
+  /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,                 // emails
+  /\b(?:api[_-]?key|secret|token|password|passwd|bearer)\b\s*[:=]\s*\S+/gi,
+  ...SECRET_PATTERNS.map(([re]) => re),
+];
+// Optional project-specific sensitive terms (e.g. an employer/customer name) → redacted too.
+let EXTRA_TERMS = [];
+export function setRedactTerms(terms) {
+  EXTRA_TERMS = (terms || []).map(t => String(t).trim()).filter(Boolean)
+    .map(t => new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'gi'));
+}
+export function scrubText(s) {
+  if (typeof s !== 'string') return s;
+  let out = s;
+  for (const re of DENY) out = out.replace(re, '[REDACTED]');
+  for (const re of EXTRA_TERMS) out = out.replace(re, '[REDACTED]');
+  return out;
+}
+
+// Default path/dir ignores (the indexer also honors the repo's .gitignore + a user .kcignore).
+export const IGNORE_DEFAULTS = [
+  /(^|\/)\.git(\/|$)/, /(^|\/)node_modules(\/|$)/, /(^|\/)secrets?(\/|$)/i,
+  /(^|\/)keys?(\/|$)/i, /(^|\/)\.env/i, /(^|\/)dist(\/|$)/,
+];
+
+// Serialize one node: keep ONLY allowlisted fields, scrub text, clamp summary.
+export function serializeNode(n) {
+  const o = {};
+  for (const k of NODE_FIELD_ALLOWLIST) if (n[k] !== undefined) o[k] = n[k];
+  if (typeof o.title === 'string') o.title = scrubText(o.title);
+  if (typeof o.summary === 'string') o.summary = scrubText(o.summary).slice(0, SUMMARY_MAX);
+  if (Array.isArray(o.headings)) o.headings = o.headings.map(scrubText);
+  if (Array.isArray(o.tags)) o.tags = o.tags.map(scrubText);
+  return o;
+}
+
+// Validate a city envelope against the contract. Returns { ok, errors[] }.
+export function validateCity(city) {
+  const errors = [];
+  if (!city || typeof city !== 'object') return { ok: false, errors: ['city is not an object'] };
+  if (city.schema_version !== SCHEMA_VERSION) errors.push(`schema_version != ${SCHEMA_VERSION}`);
+  if (!Array.isArray(city.categories)) errors.push('missing categories[] manifest');
+  if (!Array.isArray(city.nodes)) errors.push('missing nodes[]');
+  const catIds = new Set((city.categories || []).map(c => c.id));
+  (city.categories || []).forEach((c, i) => {
+    for (const k of CATEGORY_REQUIRED) if (c[k] === undefined) errors.push(`category[${i}] missing ${k}`);
+  });
+  const ids = new Set();
+  (city.nodes || []).forEach((n, i) => {
+    for (const k of NODE_REQUIRED) if (n[k] === undefined) errors.push(`node[${i}] missing ${k}`);
+    if (n.category && !catIds.has(n.category)) errors.push(`node[${i}] category '${n.category}' not in manifest`);
+    if (n.id) { if (ids.has(n.id)) errors.push(`duplicate id ${n.id}`); ids.add(n.id); }
+    if (n.provenance) for (const k of PROVENANCE_REQUIRED) if (n.provenance[k] === undefined) errors.push(`node[${i}] provenance missing ${k}`);
+    if (typeof n.summary === 'string' && n.summary.length > SUMMARY_MAX) errors.push(`node[${i}] summary > ${SUMMARY_MAX}`);
+    for (const k of Object.keys(n)) if (!NODE_FIELD_ALLOWLIST.includes(k)) errors.push(`node[${i}] non-allowlisted field '${k}'`);
+  });
+  if (city.node_count !== undefined && city.node_count !== (city.nodes || []).length) errors.push('node_count mismatch');
+  return { ok: errors.length === 0, errors };
+}
+
+const PALETTE = ['#4f8cff', '#34c759', '#ff9f0a', '#af52de', '#ff375f', '#5ac8fa', '#ffd60a', '#bf5af2', '#30d158', '#ff6482'];
+
+// Build a categories[] manifest from a list of category ids (stable order + palette).
+export function deriveCategories(ids) {
+  return ids.map((id, i) => ({
+    id, label: String(id).charAt(0).toUpperCase() + String(id).slice(1),
+    color: PALETTE[i % PALETTE.length], order: i,
+  }));
+}
+
+// Legacy adapter: v1 (district, no categories[]) → v2 (category + categories[] manifest), via the allowlist.
+export function adaptLegacy(cityV1) {
+  const ids = [...new Set((cityV1.nodes || []).map(n => n.district).filter(Boolean))];
+  const categories = deriveCategories(ids);
+  const nodes = (cityV1.nodes || []).map(n => {
+    const { district, ...rest } = n;
+    return serializeNode({ ...rest, category: district });
+  });
+  return {
+    schema_version: SCHEMA_VERSION,
+    generated_at: cityV1.generated_at || new Date().toISOString(),
+    source: { kind: 'legacy', ref: cityV1.source_rev || 'unknown', rev: cityV1.source_rev || 'unknown' },
+    categories, node_count: nodes.length, nodes,
+  };
+}