The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
perf(context): store routing vectors in a compact encoding
montjeffrey8df78d934e01
diff --git a/docs/design/context-profile-delivery.md b/docs/design/context-profile-delivery.mdindex e238de80b..62acd9dfd 100644--- a/docs/design/context-profile-delivery.md+++ b/docs/design/context-profile-delivery.md@@ -66,7 +66,7 @@ The task call sends the query and selected reference content on standard input tOrdinary interactive turns can receive advisory skill suggestions from a UserPromptSubmit hook. The hook prints up to three skill IDs with one-line descriptions and the `resolve` command to load one. Like implicit admission, a suggestion needs a matched term in the skill name or curated triggers, or an exact name; it never returns a skill body, changes the saved mode or selection, or grants authority. Loading still goes through `resolve`, which re-verifies canonical sources.-`ecc profile routing-index --state-root <store>` writes a metadata index for the current managed generation: the entries the resolver could suggest (not excluded, admissible without explicit selection), their curated triggers and precomputed retrieval vectors. Building refuses a store whose generation no longer matches the canonical sources. A small pointer named by the generation binds the index to the state receipt; the entries file is named by the SHA-256 of its bytes. A `set`, `mode` or `rollback` retires the index until it is rebuilt, and the hook then stays silent with a stderr diagnostic. `--dry-run` reports whether the current index exists.+`ecc profile routing-index --state-root <store>` writes a metadata index for the current managed generation: the entries the resolver could suggest (not excluded, admissible without explicit selection), their curated triggers and precomputed retrieval vectors in a compact little-endian encoding. Building refuses a store whose generation no longer matches the canonical sources. A small pointer named by the generation binds the index to the state receipt; the entries file is named by the SHA-256 of its bytes. A `set`, `mode` or `rollback` retires the index until it is rebuilt, and the hook then stays silent with a stderr diagnostic. `--dry-run` reports whether the current index exists.The hook is inert unless `ECC_CONTEXT_STATE_ROOT` names the store, and it is not registered by default. It is also silent in manual mode, for slash commands, prompts under 12 characters and malformed input, and fails open when its 150 ms budget (`ECC_CONTEXT_SUGGEST_BUDGET_MS`) is spent. An optional async SessionStart hook builds a missing index. To opt in, add to Claude settings, with `<ecc-root>` the ECC installation:diff --git a/docs/design/context-profile-delivery.tdd.md b/docs/design/context-profile-delivery.tdd.mdindex e00df0b64..87a60dd6e 100644--- a/docs/design/context-profile-delivery.tdd.md+++ b/docs/design/context-profile-delivery.tdd.md@@ -104,6 +104,7 @@ The suggest-only prompt hook from #2945 now reads a generation-bound metadata in- RED: routing-index and hook cases fail before the modules exist. GREEN adds a stored-vector key to the entry shape, a stale-source refusal and the session-start builder; all 16 cases pass, with a retrieval case proving stored vectors rank identically to computed ones.- The resolver path took 300 to 500 ms per prompt from a source checkout, almost all in rehashing 293 skills and 584 files. Loading Ajv lazily and storing vectors moved the hook's own work to about 95 to 110 ms on a Full Claude index (276 entries, 1.8 MB); wrapper invocations measured 140 to 180 ms against a 71 ms disabled baseline on Linux x64.- RED: on the full registry the function-word prompt still produced three unanchored suggestions. GREEN applies the routing policy v5 anchor to suggestions; the prompt now yields none and a React keyboard-focus prompt still leads with `skill:frontend-a11y`.+- Stored vectors moved from JSON pairs to little-endian base64 (RED: format test fails; GREEN: exact decode). The Full index shrank from 1.8 MB to 0.97 MB, its parse from 26 ms to 6 ms, and hook work to about 89 to 98 ms; wrapper invocations measured 149 to 190 ms against a 61 ms disabled baseline. The resolver's two registry reads are left intact as its source-consistency check.- Selection, retrieval, profile CLI and hook-wrapper suites pass unchanged.- No interactive Claude or Codex session loaded the hook; suggestion quality is bounded by the resolver ranking measured above.diff --git a/scripts/lib/context-routing-index.js b/scripts/lib/context-routing-index.jsindex c4742e715..851d0d1b4 100644--- a/scripts/lib/context-routing-index.js+++ b/scripts/lib/context-routing-index.js@@ -42,6 +42,30 @@ function currentBinding(stateRoot) {return { root, generationDigest: state.generationDigest, receiptDigest: state.receiptDigest };}+// Stored vectors are little-endian uint16 dimensions and float64 weights in+// base64: half the size of JSON pairs and exact on any platform.+function encodeDense(pairs) {+ const indexes = Buffer.alloc(pairs.length * 2);+ const values = Buffer.alloc(pairs.length * 8);+ pairs.forEach(([dimension, value], position) => {+ indexes.writeUInt16LE(dimension, position * 2);+ values.writeDoubleLE(value, position * 8);+ });+ return { indexes: indexes.toString('base64'), values: values.toString('base64') };+}++function decodeDense(dense) {+ if (!dense || typeof dense.indexes !== 'string' || typeof dense.values !== 'string') return null;+ const indexes = Buffer.from(dense.indexes, 'base64');+ const values = Buffer.from(dense.values, 'base64');+ if (indexes.length % 2 || values.length !== indexes.length * 4) return null;+ const pairs = new Array(indexes.length / 2);+ for (let position = 0; position < pairs.length; position++) {+ pairs[position] = [indexes.readUInt16LE(position * 2), values.readDoubleLE(position * 8)];+ }+ return pairs;+}+// routing/<generation>.json is a small pointer bound to the state receipt; the// entries live in routing/indexes/<sha256 of bytes>.json so readers verify them// by hashing raw bytes instead of re-serializing a large object.@@ -62,7 +86,7 @@ function writeRoutingIndex({ stateRoot, repoRoot = DEFAULT_REPO_ROOT } = {}) {const routing = routingEntries({ repoRoot, profileId: status.profileId, target: status.target,selectionMode: status.selectionMode, include: status.include, exclude: status.exclude });const bytes = io.jsonBytes({ schemaVersion: SCHEMA, generationDigest: binding.generationDigest, receiptDigest: binding.receiptDigest,- ...routing, entries: routing.entries.map(entry => ({ ...entry, dense: sparseDense(entry) })) });+ ...routing, entries: routing.entries.map(entry => ({ ...entry, dense: encodeDense(sparseDense(entry)) })) });const digest = io.hash(bytes);const file = entriesPath(root, digest);io.mkdir(path.join(root, 'routing')); io.mkdir(path.dirname(file));@@ -89,6 +113,10 @@ function readRoutingIndex(stateRoot) {const index = JSON.parse(bytes.toString('utf8'));if (index.schemaVersion !== SCHEMA || index.generationDigest !== binding.generationDigest|| index.receiptDigest !== binding.receiptDigest || !Array.isArray(index.entries)) throw invalid();+ for (const entry of index.entries) {+ entry.dense = decodeDense(entry.dense);+ if (!entry.dense) throw invalid();+ }return index;}