knosky 0.5.0 → 0.6.0

package/core/protocol-spec.mjs

@@ -0,0 +1,460 @@
+// KnoSky machine-readable protocol spec (SAT-462).
+// Exports authoritative JSON Schema (Draft 2020-12) objects for every protocol artifact.
+// Pure ESM, no dependencies — the objects are plain JSON-serializable data.
+//
+// Four schemas are published:
+//   ROUTE_SCHEMA          — the `route` artifact written by kc_route / kcRoute()
+//   INTENT_MANIFEST_SCHEMA — the `intent-manifest` artifact written by kc_bundle / kcBundle()
+//   CONFIG_SCHEMA          — the `.knosky/config.yml` file (after YAML → JS object parse)
+//   CITY_SCHEMA            — the city-data v2 envelope (core/CONTRACT.md)
+//
+// These complement, and must stay consistent with, the runtime validators in:
+//   core/schema.mjs   (route + intent-manifest)
+//   core/config.mjs   (config)
+//   core/contract.mjs (city)
+//
+// Protocol version constants (mirrors runtime constants in schema.mjs / config.mjs).
+export const PROTOCOL_VERSION = '1.0';   // knosky_protocol field value
+export const CITY_SCHEMA_VERSION = '2.0'; // schema_version field value
+
+// ---------------------------------------------------------------------------
+// Reusable sub-schemas
+// ---------------------------------------------------------------------------
+
+/** A path entry inside route[] / alternates[]: either a bare string or an object with a `path` field. */
+const PATH_ENTRY = {
+  oneOf: [
+    { type: 'string', minLength: 1 },
+    {
+      type: 'object',
+      required: ['path'],
+      properties: {
+        path: { type: 'string', minLength: 1 },
+      },
+      additionalProperties: true,
+    },
+  ],
+};
+
+/** A KnoSky secret-scan result object embedded in the intent-manifest. */
+const SECRET_SCAN_RESULT = {
+  type: 'object',
+  required: ['status'],
+  properties: {
+    status: { type: 'string', enum: ['clean', 'blocked'] },
+    detail: { type: 'string' },
+  },
+  additionalProperties: true,
+};
+
+/** A provenance object embedded in every city node. */
+const PROVENANCE = {
+  type: 'object',
+  required: ['store', 'ref'],
+  properties: {
+    store: { type: 'string', minLength: 1 },
+    ref: { type: 'string', minLength: 1 },
+    source_rev: { type: 'string' },
+    fetched_at: { type: 'string' },
+  },
+  additionalProperties: true,
+};
+
+// ---------------------------------------------------------------------------
+// ROUTE_SCHEMA
+// ---------------------------------------------------------------------------
+
+/**
+ * JSON Schema (Draft 2020-12) for the KnoSky `route` artifact.
+ * Produced by kc_route / kcRoute().  Must agree with validateRouteDoc() in core/schema.mjs.
+ *
+ * @type {object}
+ */
+export const ROUTE_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://knosky.com/schemas/route.json',
+  title: 'KnoSky Route',
+  description:
+    'Advisory navigation route produced by kc_route. ' +
+    'Structural metadata only — never code analysis. ' +
+    'Always advisory: the `advisory` field is invariantly true.',
+  type: 'object',
+  required: [
+    'knosky_protocol',
+    'artifact_type',
+    'advisory',
+    'generated_at',
+    'destination',
+    'route',
+    'alternates',
+    'caveats',
+    'confidence',
+  ],
+  additionalProperties: true,
+  properties: {
+    knosky_protocol: {
+      type: 'string',
+      const: '1.0',
+      description: 'Protocol version. Always "1.0" for this schema.',
+    },
+    artifact_type: {
+      type: 'string',
+      const: 'route',
+      description: 'Discriminator field. Always "route" for this artifact.',
+    },
+    advisory: {
+      type: 'boolean',
+      const: true,
+      description: 'Invariantly true — routes are advisory, never authoritative.',
+    },
+    generated_at: {
+      type: 'string',
+      format: 'date-time',
+      description: 'ISO-8601 timestamp at which this document was generated.',
+    },
+    source_rev: {
+      type: ['string', 'null'],
+      description: 'VCS revision (e.g. git commit SHA) of the city index used. Null when unknown.',
+    },
+    destination: {
+      type: 'string',
+      description: 'The navigation target string supplied by the caller.',
+    },
+    route: {
+      type: 'array',
+      items: PATH_ENTRY,
+      description: 'Ordered primary waypoints. Each entry is a path string or { path, id, reason, score }.',
+    },
+    alternates: {
+      type: 'array',
+      items: PATH_ENTRY,
+      description: 'Alternate waypoints beyond the primary route limit.',
+    },
+    caveats: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Advisory notes. Always contains at least the mandatory advisory caveat. ' +
+        'May include churn, coverage, and staleness warnings.',
+    },
+    confidence: {
+      type: 'number',
+      minimum: 0,
+      maximum: 1,
+      description: 'Estimated confidence of the route [0..1]. 0 = no signal; ~0.95 = direct file match.',
+    },
+    tests: {
+      type: 'array',
+      items: { type: 'object' },
+      description: 'Test files in the candidate neighbourhood (informational).',
+    },
+    docs: {
+      type: 'array',
+      items: { type: 'object' },
+      description: 'Documentation files in the candidate neighbourhood (informational).',
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// INTENT_MANIFEST_SCHEMA
+// ---------------------------------------------------------------------------
+
+/**
+ * JSON Schema (Draft 2020-12) for the KnoSky `intent-manifest` artifact.
+ * Produced by kc_bundle / kcBundle().  Must agree with validateIntentManifest() in core/schema.mjs.
+ *
+ * @type {object}
+ */
+export const INTENT_MANIFEST_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://knosky.com/schemas/intent-manifest.json',
+  title: 'KnoSky Intent Manifest',
+  description:
+    'Shareable, verifiable file-set manifest produced by kc_bundle. ' +
+    'Each path entry carries a SHA-256 digest. ' +
+    'The secret_scan field signals whether the manifest was produced by a clean or blocked scan.',
+  type: 'object',
+  required: [
+    'knosky_protocol',
+    'artifact_type',
+    'advisory',
+    'generated_at',
+    'paths',
+    'edges',
+    'secret_scan',
+  ],
+  additionalProperties: true,
+  properties: {
+    knosky_protocol: {
+      type: 'string',
+      const: '1.0',
+      description: 'Protocol version. Always "1.0" for this schema.',
+    },
+    artifact_type: {
+      type: 'string',
+      const: 'intent-manifest',
+      description: 'Discriminator field. Always "intent-manifest" for this artifact.',
+    },
+    advisory: {
+      type: 'boolean',
+      const: true,
+      description: 'Invariantly true.',
+    },
+    generated_at: {
+      type: 'string',
+      format: 'date-time',
+      description: 'ISO-8601 timestamp at which this document was generated.',
+    },
+    paths: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['path', 'sha256'],
+        properties: {
+          path: {
+            type: 'string',
+            minLength: 1,
+            description: 'Repo-relative path. Must not be absolute or contain ".." segments.',
+          },
+          sha256: {
+            type: 'string',
+            description: 'Hex-encoded SHA-256 digest of the file at bundle time. Empty string when unreadable.',
+          },
+        },
+        additionalProperties: true,
+      },
+      description: 'Ordered list of files covered by this manifest.',
+    },
+    edges: {
+      type: 'array',
+      items: { type: 'object' },
+      description: 'Dependency edges among the covered files.',
+    },
+    expiry: {
+      type: ['string', 'null'],
+      description: 'ISO-8601 expiry timestamp, or null for no expiry.',
+    },
+    secret_scan: {
+      ...SECRET_SCAN_RESULT,
+      description:
+        'Result of the fail-closed secret scan run at bundle time. ' +
+        '"clean" means no secret-like values were detected; ' +
+        '"blocked" means the scan found a pattern match and the bundle should not be shared.',
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// CONFIG_SCHEMA
+// ---------------------------------------------------------------------------
+
+/**
+ * JSON Schema (Draft 2020-12) for a KnoSky project config object
+ * (`.knosky/config.yml`, parsed to a JS object by loadConfig()).
+ * Must agree with validateConfig() in core/config.mjs.
+ *
+ * @type {object}
+ */
+export const CONFIG_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://knosky.com/schemas/config.json',
+  title: 'KnoSky Project Config',
+  description:
+    'KnoSky project configuration. Read from `.knosky/config.yml`; ' +
+    'missing fields default to the values shown in `default`. ' +
+    'Unknown keys are rejected by validateConfig().',
+  type: 'object',
+  required: [
+    'knosky_protocol',
+    'telemetry',
+    'absolute_paths',
+    'fail_on_secret',
+    'allow_excerpts',
+    'max_excerpt_chars',
+    'categories',
+    'ignore',
+  ],
+  additionalProperties: false,
+  properties: {
+    knosky_protocol: {
+      type: 'string',
+      const: '1.0',
+      default: '1.0',
+      description: 'Protocol version. Must be "1.0".',
+    },
+    telemetry: {
+      type: 'boolean',
+      default: false,
+      description: 'Whether to emit telemetry. Defaults to false (never sends data out).',
+    },
+    absolute_paths: {
+      type: 'boolean',
+      default: false,
+      description: 'Embed absolute filesystem paths in the city output. Defaults to false (basename only).',
+    },
+    fail_on_secret: {
+      type: 'boolean',
+      default: true,
+      description: 'Abort the build if a secret-like value is detected. Defaults to true (fail-closed).',
+    },
+    allow_excerpts: {
+      type: 'boolean',
+      default: false,
+      description: 'Include file-content excerpts in the index. Defaults to false.',
+    },
+    max_excerpt_chars: {
+      type: 'integer',
+      minimum: 0,
+      default: 0,
+      description: 'Maximum characters per excerpt. 0 = no excerpts even when allow_excerpts is true.',
+    },
+    categories: {
+      type: 'array',
+      items: { type: 'string' },
+      default: [],
+      description: 'Explicit category (district) labels. Empty array = derived automatically.',
+    },
+    ignore: {
+      type: 'array',
+      items: { type: 'string' },
+      default: [],
+      description: 'Additional glob-style ignore patterns (appended to the built-in defaults and .gitignore).',
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// CITY_SCHEMA
+// ---------------------------------------------------------------------------
+
+/**
+ * JSON Schema (Draft 2020-12) for a KnoSky city-data v2 envelope.
+ * Produced by the fs-indexer and consumed by the renderer / MCP server.
+ * Must agree with validateCity() + NODE_FIELD_ALLOWLIST in core/contract.mjs.
+ *
+ * @type {object}
+ */
+export const CITY_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://knosky.com/schemas/city.json',
+  title: 'KnoSky City Data (v2)',
+  description:
+    'N-category city-data envelope (contract v2). ' +
+    'Contains pointers and projections only — never full file bodies (decision D-146). ' +
+    'See core/CONTRACT.md for narrative spec.',
+  type: 'object',
+  required: ['schema_version', 'generated_at', 'categories', 'nodes'],
+  additionalProperties: true,
+  properties: {
+    schema_version: {
+      type: 'string',
+      const: '2.0',
+      description: 'City contract version. Always "2.0" for this schema.',
+    },
+    generated_at: {
+      type: 'string',
+      format: 'date-time',
+      description: 'ISO-8601 timestamp at which the city was built.',
+    },
+    source: {
+      type: 'object',
+      required: ['kind', 'ref'],
+      properties: {
+        kind: { type: 'string', enum: ['fs', 'github', 'board', 'legacy'] },
+        ref: { type: 'string' },
+        rev: { type: 'string' },
+      },
+      additionalProperties: false,
+      description: 'Where the city was built from.',
+    },
+    categories: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['id', 'label', 'order'],
+        properties: {
+          id: { type: 'string', minLength: 1 },
+          label: { type: 'string', minLength: 1 },
+          color: { type: 'string' },
+          order: { type: 'integer', minimum: 0 },
+        },
+        additionalProperties: false,
+      },
+      description: 'N-category manifest. Replaces the hardcoded 4-district v1 model.',
+    },
+    node_count: {
+      type: 'integer',
+      minimum: 0,
+      description: 'Expected number of nodes. Must equal nodes.length when present.',
+    },
+    nodes: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['id', 'kind', 'title', 'category', 'links', 'provenance'],
+        // additionalProperties:false enforces the serialization allowlist from contract.mjs.
+        additionalProperties: false,
+        properties: {
+          id: {
+            type: 'string',
+            minLength: 1,
+            description: 'Stable, source-derived node identifier.',
+          },
+          kind: {
+            type: 'string',
+            description: 'Node kind: decision, spec, file, dir, doc, …',
+          },
+          title: {
+            type: 'string',
+            description: 'Short projection title (scrubbed; never a full file body).',
+          },
+          summary: {
+            type: 'string',
+            maxLength: 200,
+            description:
+              'Short excerpt projection (≤ 200 chars, scrubbed; never a full file body).',
+          },
+          category: {
+            type: 'string',
+            description: 'Category id. Must match an entry in the top-level categories[] manifest.',
+          },
+          status: { type: 'string' },
+          fact_date: { type: 'string' },
+          tags: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+          headings: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+          links: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Edges to other node ids.',
+          },
+          churn: {
+            description: 'Recent-change signal. Object with `c` (commit count) or a plain number.',
+          },
+          provenance: {
+            ...PROVENANCE,
+            description: 'Back-pointer to the live source. Fields: store (required), ref (required).',
+          },
+          visibility: {
+            type: 'string',
+            enum: ['internal', 'public'],
+          },
+          sensitive: {
+            type: 'boolean',
+            description: 'Scrub/flag marker. True when a sensitive-term match was found.',
+          },
+        },
+      },
+      description:
+        'All nodes in the city. Node fields are strictly limited to the serialization allowlist ' +
+        '(id, kind, title, summary, category, status, fact_date, tags, headings, links, churn, ' +
+        'provenance, visibility, sensitive).',
+    },
+  },
+};

package/core/route.mjs

@@ -3,6 +3,7 @@
 import { getRelated } from './retrieve.mjs';
 import { makeRouteDoc, validateRouteDoc } from './schema.mjs';
 import { parseDestination } from './destination.mjs';
+import { extractLedgerSeq } from './freshness.mjs';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -233,6 +234,9 @@ export function kcRoute(ctx, destination, { limit = 8, overlays } = {}) {
     caveats.push('route is based on rev ' + source_rev + ' and may be stale');
   }
 
+  // Ledger-anchored freshness (SAT-444): read the monotone commit count from the city.
+  const ledger_seq = extractLedgerSeq(ctx.city);
+
   // Slice into route + alternates
   const routeEntries = scored.slice(0, clampedLimit);
   const alternateEntries = scored.slice(clampedLimit, clampedLimit + 5);
@@ -283,6 +287,7 @@ export function kcRoute(ctx, destination, { limit = 8, overlays } = {}) {
     caveats,
     confidence,
     source_rev,
+    ledger_seq,
   });
 
   // Attach tests + docs (extra fields beyond the base envelope — schema.validateRouteDoc does not reject them)

package/core/schema.mjs

@@ -86,6 +86,9 @@ function checkAbsolutePaths(entries, fieldName, errors) {
  * @param {string[]}  [opts.caveats]     Advisory notes.
  * @param {number}    [opts.confidence]  Confidence score [0..1].
  * @param {string|null} [opts.source_rev] VCS revision that produced this doc.
+ * @param {number|null} [opts.ledger_seq] Ledger sequence number (SAT-444) —
+ *   monotone commit count from the city that produced this route doc.
+ *   null means the city predates ledger-anchored freshness.
  * @returns {object}
  */
 export function makeRouteDoc({
@@ -95,6 +98,7 @@ export function makeRouteDoc({
   caveats = [],
   confidence = 0,
   source_rev = null,
+  ledger_seq = null,
 } = {}) {
   return {
     knosky_protocol: PROTOCOL_VERSION,
@@ -102,6 +106,7 @@ export function makeRouteDoc({
     advisory: true,
     generated_at: new Date().toISOString(),
     source_rev,
+    ledger_seq,
     destination,
     route,
     alternates,
@@ -142,10 +147,18 @@ export function validateRouteDoc(doc) {
     }
   }
 
-  if (typeof doc.confidence !== 'number' || doc.confidence < 0 || doc.confidence > 1) {
+  // Number.isFinite rejects NaN and ±Infinity; the range check then enforces [0, 1].
+  if (!Number.isFinite(doc.confidence) || doc.confidence < 0 || doc.confidence > 1) {
     errors.push(`confidence must be a number in [0, 1], got: ${JSON.stringify(doc.confidence)}`);
   }
 
+  // ledger_seq: must be null or a non-negative integer (SAT-444)
+  if (doc.ledger_seq !== undefined && doc.ledger_seq !== null) {
+    if (typeof doc.ledger_seq !== 'number' || !Number.isInteger(doc.ledger_seq) || doc.ledger_seq < 0) {
+      errors.push(`ledger_seq must be null or a non-negative integer, got: ${JSON.stringify(doc.ledger_seq)}`);
+    }
+  }
+
   // Absolute-path invariant applies to route[] and alternates[]
   if (Array.isArray(doc.route)) {
     checkAbsolutePaths(doc.route, 'route', errors);
@@ -169,6 +182,9 @@ export function validateRouteDoc(doc) {
  * @param {unknown[]} [opts.edges]       Dependency edges.
  * @param {string|null} [opts.expiry]    ISO-8601 expiry timestamp or null.
  * @param {object}   opts.secret_scan    REQUIRED secret-scan result object.
+ * @param {number|null} [opts.ledger_seq] Ledger sequence number (SAT-444) —
+ *   monotone commit count from the city that produced this manifest.
+ *   null means the city predates ledger-anchored freshness.
  * @returns {object}
  */
 export function makeIntentManifest({
@@ -176,6 +192,7 @@ export function makeIntentManifest({
   edges = [],
   expiry = null,
   secret_scan,
+  ledger_seq = null,
 } = {}) {
   return {
     knosky_protocol: PROTOCOL_VERSION,
@@ -185,6 +202,7 @@ export function makeIntentManifest({
     paths,
     edges,
     expiry,
+    ledger_seq,
     secret_scan,
   };
 }
@@ -237,6 +255,13 @@ export function validateIntentManifest(doc) {
     checkAbsolutePaths(doc.paths, 'paths', errors);
   }
 
+  // ledger_seq: must be null or a non-negative integer (SAT-444)
+  if (doc.ledger_seq !== undefined && doc.ledger_seq !== null) {
+    if (typeof doc.ledger_seq !== 'number' || !Number.isInteger(doc.ledger_seq) || doc.ledger_seq < 0) {
+      errors.push(`ledger_seq must be null or a non-negative integer, got: ${JSON.stringify(doc.ledger_seq)}`);
+    }
+  }
+
   // secret_scan must be present and have a valid status
   if (!doc.secret_scan || typeof doc.secret_scan !== 'object') {
     errors.push('secret_scan is required and must be an object');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knosky",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Turn any repo or docs folder into an explorable city, plus a local MCP that grounds your AI in your own source with citations. Local-first, free, $0 tokens.",
   "type": "module",
   "bin": {
@@ -10,6 +10,8 @@
     "bin",
     "core",
     "renderer",
+    "action",
+    "action.yml",
     "mcp/server.mjs",
     "README.md",
     "LICENSE.md",