ds4-context-engine 0.1.1 → 0.2.0-beta.1

package/docs/STORAGE.md

@@ -8,7 +8,9 @@ Pi's session JSONL is canonical for conversations and live project files are can
 /context rebuild-index
 ```
 
-The extension never edits or rewrites Pi JSONL or project source files. Manual memory/pin commands append versioned Pi `CustomEntry` records through Pi's official `appendEntry()` API.
+The extension never edits or rewrites Pi JSONL or project source files. Manual memory/pin commands and learned-ranking feedback append versioned classified Pi `CustomEntry` records through Pi's official `appendEntry()` API.
+
+The M19 non-Pi reference adapter owns a separate `ds4-runtime-session-v1` JSONL source selected by its host runtime. Its header binds runtime/session identity and the exact canonical project root; following records contain provenance-checked canonical messages. DS4 snapshots and capability diagnostics are disposable. `createReferenceHistory()` refuses overwrite, append uses a dedicated provenance-checked operation, files are mode `0600` where supported, and rebuild never edits this runtime-owned canonical file. Reference JSONL is not imported into Pi or `context.db`.
 
 ## Session index
 
@@ -45,19 +47,33 @@ Malformed newline-terminated records are skipped consistently and counted. A val
 
 ## Project knowledge index
 
-Schema v7 adds `project_states`, `project_files`, `project_snippets`, and `project_snippets_fts`. The state row records canonical root plus Git branch/HEAD/dirty paths. Current file rows store SHA-256, size, mtime, language, indexed Git HEAD, tracked/modified state, and lifecycle. Snippet rows store the immutable file hash, line range, source text, heuristic symbols, estimate, and stale bit.
+Schema v7 adds `project_states`, `project_files`, `project_snippets`, and `project_snippets_fts`. The state row records canonical root plus Git branch/HEAD/dirty paths. Current file rows store SHA-256, size, mtime, language, indexed Git HEAD, tracked/modified state and lifecycle. Snippet rows store the immutable file hash, line range, source text, estimate and stale bit.
+
+Schema v12 extends snippet rows with text/symbol chunk kind, parser ID, stable symbol ID, simple and qualified names, kind, signature, parent, imports and references. The exact-name indexes and all parser output are disposable. Built-in TypeScript/JavaScript/Python/Go structural parsing has no native dependency; unsupported, invalid or declaration-free files retain bounded v7 text windows.
 
-Changed hashes never overwrite old snippet rows silently: prior rows become stale and new hash-derived snippet IDs become current. Deleted, renamed, oversized, binary, symlinked, or newly sensitive files similarly invalidate prior snippets. Exact and FTS queries join current files and require `stale = 0`; stale FTS rows may remain locally for derived-history diagnostics but cannot enter context.
+Changed hashes never overwrite old snippet rows silently: only the changed path's prior rows become stale and new hash-derived snippet/symbol IDs become current. Unrelated files preserve their rows and IDs. Deleted, renamed, oversized, binary, symlinked or newly sensitive files similarly invalidate prior snippets. Exact path/symbol and FTS queries join current files and require `stale = 0`; stale FTS rows may remain locally for derived-history diagnostics but cannot enter context.
 
 Project source text is duplicated in SQLite only to provide local FTS and bounded snippet injection. Deleting the database loses no source truth. `/context rebuild-index` clears/rebuilds current projections from trusted live files. No project table is read or written while Pi reports the project untrusted.
 
+## Derived embedding index
+
+Schema v13 adds `derived_embeddings` for opt-in M16 historical/project vectors. The compound key contains source kind/scope/key/hash, chunking version, embedding provider/model and dimensions. Rows store only source grouping metadata, numeric vector JSON and indexing time; no query text, copied evidence text, provider response ID or remote handle is added.
+
+Current source keys and hashes prune obsolete vectors without touching unrelated sources. Provider/model/dimension profiles coexist, so changing one profile does not rewrite another. Query vectors live only in a bounded volatile cache. The table is ignored when semantic retrieval is disabled and can always be recreated from Pi JSONL plus trusted live project files and the configured runtime embedding port.
+
+Remote embedding text is privacy-filtered before the port is called. `local-only` values are omitted entirely and allowed values are secret-redacted. These rules govern transport; SQLite remains a local disposable projection.
+
 ## Memory and pin event projection
 
 Schema v9 adds append-only `memory_mutations` and `pin_mutations`, each keyed to the canonical scoped `entries.entry_key` for its Pi custom entry. Mutation payloads describe immutable add, explicit supersede, or lifecycle status operations. `entry_order` preserves causal order when several Pi entries share one millisecond timestamp.
 
 `memory_items`, `memory_sources`, `memory_fts`, and `pins` are materialized transactionally by replaying every known mutation. Materialized memory records retain normalized keys, origin session, source entries, optional privacy classification, active/superseded/invalid/expired status and immutable replacement links. Pins retain session/branch/project scope, creation leaf, optional classification, source entry/file and active/superseded/deleted lifecycle. Classification lives in canonical mutation JSON and derived `metadata_json`; M10 required no schema migration beyond v9.
 
-Before replay, the current session's mutation rows are replaced from its complete Pi entry tree. Other indexed sessions remain available, enabling trusted project-scope state across sessions. Deleting the database loses no canonical mutation; reopening each source session recreates its projection. Unbacked legacy pre-v9 materialized rows are inspectable immediately after migration but are not treated as canonical during a later full replay.
+Before replay, the current session's mutation rows are replaced from its complete Pi entry tree. Other indexed sessions remain available, preserving the 0.1 project-scope behavior.
+
+Schema v15 adds `project_memory_sessions`, `project_memory_source_exclusions`, and mutation creation-parent columns. When `memory.crossSession` is opted in, DS4 enumerates at most `memory.maxProjectSessions` sibling Pi JSONL files, validates each header against the exact trusted canonical project path, indexes only changed suffixes, and materializes their explicit mutations. Source rows retain header/checkpoint hashes, offsets, record/mutation counts, malformed-line counts, status and bounded error text. Exclusions are local derived policy; mutation content remains only in canonical JSONL and existing local projection tables.
+
+A missing, moved, truncated, identity-mismatched or corrupt sibling source stops contributing unverifiable project-scoped mutations without discarding its isolated session-scoped projection. The active session retains its last transactional projection if an auxiliary cross-session refresh fails. Restored files rebuild deterministically. Deleting the database loses no canonical mutation; source discovery recreates the complete project projection without opening every source session. Unbacked legacy pre-v9 materialized rows are inspectable immediately after migration but are not treated as canonical during a later full replay.
 
 Custom entries have empty lexical search text and never enter Pi context directly. The managed planner creates bounded, source-labelled synthetic pin/memory messages. Context Manifests store only metadata and hashes, never content/claims.
 
@@ -67,9 +83,21 @@ Schema v10 extends `context_manifests` and `token_calibration` with separate unc
 
 Calibration rows are derived telemetry, isolated by exact provider/model and bounded to the latest configured window at read time. The runtime recomputes median/MAD outlier filtering deterministically; no learned model or mutable provider state is stored. Deleting the database loses calibration and cache history but never session content. Ephemeral sessions and configurations that disable manifest persistence keep only a bounded in-memory window.
 
+## Context quality samples
+
+Schema v11 adds bounded `context_quality_samples` for opt-in M14 measurement. Rows contain only metric/corpus/planner/profile versions, source-kind/token/budget/decision counts, normalized outcome labels and separate planning duration. Prompt text, evidence text, paths, memory claims, provider payloads, response IDs and raw source IDs are never stored. Invalid or corrupt rows are skipped during aggregation.
+
+The table is a disposable replay projection. Deleting it loses no canonical state; replaying the versioned sanitized corpus recreates byte-stable non-timing aggregates. Runtime samples without expected-evidence labels remain explicitly unlabeled. See [`CONTEXT_QUALITY.md`](CONTEXT_QUALITY.md).
+
+## Learned-ranking labels and model artifact
+
+M18 adds no SQLite table. Classified `ds4-context-ranking-feedback-v1` Pi custom entries are canonical and contain only version/hash/label metadata plus ten bounded numeric features. Stable repository and candidate identities are SHA-256 hashes; raw prompt, evidence, claim, path and symbol text are absent. Sanitized replay labels use the same entry schema and explicitly identify their label source.
+
+The trained `ds4-context/ranking-model.json` file is a disposable private artifact containing schema/algorithm versions, bounded weights, aggregate training counts, optional promotion-gate metrics and a stable-payload checksum. Deleting or corrupting it restores static ranking; canonical labels remain available for local retraining. Shadow comparison stores only aggregate disagreement in Context Manifests. No label, feature vector or candidate ID is copied into a manifest. See [`LEARNED_RANKING.md`](LEARNED_RANKING.md).
+
 ## Native continuation state
 
-M12 adds no SQLite migration or continuation table; schema remains v10. The active process keeps only deterministic SHA-256 hashes of the previous full request items and serialized response items, a hash of non-input request options, completion time, and the minimum provider response handle needed for `previous_response_id`.
+M12 adds no continuation table. It was introduced at schema v10; M14 adds quality samples in v11, M15 adds project-symbol columns/indexes in v12, and M16 adds only disposable vectors in v13. The active process keeps only deterministic SHA-256 hashes of the previous full request items and serialized response items, a hash of non-input request options, completion time, and the minimum provider response handle needed for `previous_response_id`.
 
 The volatile state is cleared on lifecycle/model/branch/compaction boundaries and is not reconstructed on resume. The first request after a cold start is therefore always the complete managed replay. Pi may persist its normal `AssistantMessage.responseId` in canonical JSONL, but DS4 does not create a custom entry, copy that ID into SQLite/manifest/logs, or depend on it for recovery.
 
@@ -83,7 +111,7 @@ A full index rebuild replays all message entries, recreates missing qualifying o
 
 ## Context manifests
 
-For persisted sessions, each `context` hook stores a metadata-only manifest containing token counts, session/project/pin/memory source and atomic-group IDs, inclusion/exclusion reasons, classifications and scores, original/selected counts, exact-model override/calibration/adaptive budgets, model-switch/cache disposition, provider destination/allow names, privacy counters, optional continuation mode/item counts/retry reasons, project revision/hash/line references, tool names, a SHA-256 prompt hash, and planner/policy versions. Prompt text, message text, pin content, memory claims, project snippet text, tool arguments, image data, rendered provider payloads, and provider response/conversation IDs are not stored in the manifest.
+For persisted sessions, each `context` hook stores a metadata-only manifest containing token counts, session/project/pin/memory source and atomic-group IDs, inclusion/exclusion reasons, classifications and scores, original/selected counts, exact-model override/calibration/adaptive budgets, aggregate learned-ranking status/disagreement, model-switch/cache disposition, provider destination/allow names, privacy counters, optional continuation mode/item counts/retry reasons, project revision/hash/line references, tool names, a SHA-256 prompt hash, and planner/policy versions. Prompt text, message text, pin content, memory claims, project snippet text, tool arguments, image data, rendered provider payloads, and provider response/conversation IDs are not stored in the manifest.
 
 `before_provider_request` updates the pending manifest with final-check/redaction counters but never the provider payload. The following finalized assistant response updates it with uncached input, cache-read, cache-write and total provider input usage, then adds at most one exact-model calibration sample. Ephemeral sessions retain this information only in memory.
 
@@ -99,4 +127,4 @@ Schema-v2 `CompactionEntry.details.ds4ContextEngine` records the active/segment
 
 A full rebuild does not blindly delete unchanged entries. It upserts all observed entries, marks them in a temporary seen-set, and removes only stale rows. This preserves foreign-key provenance for unchanged source entries. FTS rows and checkpoint state update in the same transaction.
 
-Session reconciliation is transactional. Memory/pin mutation replacement and full materialization are one transaction. Each changed project file is also replaced transactionally with its snippets and FTS rows; artifact object/reference metadata and project deletion batches are atomic. A filesystem artifact write precedes its metadata transaction, so an interrupted metadata write may leave only an unreferenced content-addressed cache file; canonical JSONL remains sufficient for recovery. If parsing, validation, or SQLite writing fails, the prior derived state remains available. Artifact/project failures contribute no replacement/snippets; planner failures discard all synthetic evidence; Pi continues with its native context.
+Session reconciliation is transactional. Memory/pin mutation replacement, checkpoint update, source exclusion and full materialization each occur under the shared write coordinator. Each quality upsert and bounded-retention prune share one transaction; quality failures do not affect manifests or planning. Each changed project file is also replaced transactionally with its snippets and FTS rows; embedding upserts and canonical-source pruning are transactional; artifact object/reference metadata and project deletion batches are atomic. A filesystem artifact write precedes its metadata transaction, so an interrupted metadata write may leave only an unreferenced content-addressed cache file; canonical JSONL remains sufficient for recovery. If parsing, validation, or SQLite writing fails, the prior derived state remains available. Artifact/project failures contribute no replacement/snippets; planner failures discard all synthetic evidence; Pi continues with its native context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.1.1",
+  "version": "0.2.0-beta.1",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,8 @@
   "files": [
     "src",
     "docs",
+    "quality",
+    "scripts/compare-context-quality.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -37,12 +39,15 @@
   },
   "scripts": {
     "build:core": "npm run build --workspace ds4-context-core",
-    "typecheck": "npm run build:core && tsc --noEmit",
-    "test": "npm run build:core && vitest run",
-    "test:watch": "npm run build:core && vitest",
-    "check": "npm run build:core && tsc --noEmit && vitest run",
+    "build:reference-adapter": "npm run build --workspace ds4-context-reference-adapter",
+    "build:adapters": "npm run build:reference-adapter",
+    "typecheck": "npm run build:core && npm run build:adapters && tsc --noEmit",
+    "test": "npm run build:core && npm run build:adapters && vitest run",
+    "test:watch": "npm run build:core && npm run build:adapters && vitest",
+    "check": "npm run build:core && npm run build:adapters && tsc --noEmit && vitest run",
+    "quality:compare": "node scripts/compare-context-quality.mjs",
     "pack:check": "node scripts/verify-packages.mjs",
-    "prepare": "npm run build:core"
+    "prepare": "npm run build:core && npm run build:adapters"
   },
   "pi": {
     "extensions": [
@@ -50,7 +55,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.1.1"
+    "ds4-context-core": "0.2.0-beta.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",

package/quality/corpus-v1.json

@@ -0,0 +1,208 @@
+{
+  "schemaVersion": 1,
+  "corpusVersion": "ds4-quality-corpus-v1",
+  "description": "Synthetic metadata-only replay fixtures for deterministic DS4 context-quality comparisons.",
+  "fixtures": [
+    {
+      "schemaVersion": 1,
+      "corpusVersion": "ds4-quality-corpus-v1",
+      "sampleId": "fixture:retrieval-budget",
+      "plannerVersion": "managed-v1",
+      "profileKey": "fixture/model-128k",
+      "task": {
+        "taskId": "task:retrieval-budget",
+        "taskType": "debugging",
+        "queryTags": ["exact-symbol", "historical-decision"]
+      },
+      "expectedEvidenceSourceIds": ["entry:decision-a"],
+      "candidates": [
+        {
+          "id": "candidate:current-a",
+          "kind": "current",
+          "tokens": 80,
+          "groupId": "group:current-a",
+          "sourceIds": ["entry:request-a"],
+          "staticScore": 1000,
+          "candidateScore": 1000,
+          "currentRequest": true
+        },
+        {
+          "id": "candidate:recent-a",
+          "kind": "recent",
+          "tokens": 120,
+          "groupId": "group:recent-a",
+          "sourceIds": ["entry:recent-a"],
+          "staticScore": 100,
+          "candidateScore": 40
+        },
+        {
+          "id": "candidate:retrieval-a",
+          "kind": "retrieval",
+          "tokens": 100,
+          "groupId": "group:retrieval-a",
+          "sourceIds": ["entry:decision-a"],
+          "staticScore": 85,
+          "candidateScore": 180
+        }
+      ],
+      "totalBudgetTokens": 210,
+      "categoryBudgets": {
+        "recent": 160,
+        "retrieval": 120
+      },
+      "outcomeLabels": ["expected:decision-recovered"]
+    },
+    {
+      "schemaVersion": 1,
+      "corpusVersion": "ds4-quality-corpus-v1",
+      "sampleId": "fixture:atomic-tools",
+      "plannerVersion": "managed-v1",
+      "profileKey": "fixture/model-32k",
+      "task": {
+        "taskId": "task:atomic-tools",
+        "taskType": "tool-debugging",
+        "queryTags": ["atomic-tool-group"]
+      },
+      "expectedEvidenceSourceIds": ["entry:tool-call", "entry:tool-result"],
+      "candidates": [
+        {
+          "id": "candidate:current-b",
+          "kind": "current",
+          "tokens": 40,
+          "groupId": "group:current-b",
+          "sourceIds": ["entry:request-b"],
+          "staticScore": 1000,
+          "candidateScore": 1000,
+          "currentRequest": true
+        },
+        {
+          "id": "candidate:tool-call",
+          "kind": "retrieval",
+          "tokens": 60,
+          "groupId": "group:tool-exchange",
+          "sourceIds": ["entry:tool-call"],
+          "staticScore": 90,
+          "candidateScore": 120
+        },
+        {
+          "id": "candidate:tool-result",
+          "kind": "retrieval",
+          "tokens": 100,
+          "groupId": "group:tool-exchange",
+          "sourceIds": ["entry:tool-result"],
+          "staticScore": 90,
+          "candidateScore": 120
+        },
+        {
+          "id": "candidate:background-b",
+          "kind": "recent",
+          "tokens": 170,
+          "groupId": "group:background-b",
+          "sourceIds": ["entry:background-b"],
+          "staticScore": 80,
+          "candidateScore": 20
+        }
+      ],
+      "totalBudgetTokens": 220,
+      "categoryBudgets": {
+        "recent": 180,
+        "retrieval": 180
+      },
+      "outcomeLabels": ["expected:atomic-selection"]
+    },
+    {
+      "schemaVersion": 1,
+      "corpusVersion": "ds4-quality-corpus-v1",
+      "sampleId": "fixture:duplicate-evidence",
+      "plannerVersion": "managed-v1",
+      "profileKey": "fixture/model-200k",
+      "task": {
+        "taskId": "task:duplicate-evidence",
+        "taskType": "refactoring",
+        "queryTags": ["decision-recall", "duplicate-control"]
+      },
+      "expectedEvidenceSourceIds": ["entry:decision-b", "entry:decision-c"],
+      "candidates": [
+        {
+          "id": "candidate:current-c",
+          "kind": "current",
+          "tokens": 50,
+          "groupId": "group:current-c",
+          "sourceIds": ["entry:request-c"],
+          "staticScore": 1000,
+          "candidateScore": 1000,
+          "currentRequest": true
+        },
+        {
+          "id": "candidate:decision-b-primary",
+          "kind": "retrieval",
+          "tokens": 80,
+          "groupId": "group:decision-b-primary",
+          "sourceIds": ["entry:decision-b"],
+          "staticScore": 100,
+          "candidateScore": 100
+        },
+        {
+          "id": "candidate:decision-b-duplicate",
+          "kind": "retrieval",
+          "tokens": 80,
+          "groupId": "group:decision-b-duplicate",
+          "sourceIds": ["entry:decision-b"],
+          "staticScore": 99,
+          "candidateScore": 10
+        },
+        {
+          "id": "candidate:decision-c",
+          "kind": "retrieval",
+          "tokens": 80,
+          "groupId": "group:decision-c",
+          "sourceIds": ["entry:decision-c"],
+          "staticScore": 98,
+          "candidateScore": 99
+        }
+      ],
+      "totalBudgetTokens": 210,
+      "categoryBudgets": {
+        "retrieval": 160
+      },
+      "outcomeLabels": ["expected:no-duplicate"]
+    },
+    {
+      "schemaVersion": 1,
+      "corpusVersion": "ds4-quality-corpus-v1",
+      "sampleId": "fixture:mandatory-overflow",
+      "plannerVersion": "managed-v1",
+      "profileKey": "fixture/model-32k",
+      "task": {
+        "taskId": "task:mandatory-overflow",
+        "taskType": "overflow-safety",
+        "queryTags": ["fail-open", "current-request"]
+      },
+      "expectedEvidenceSourceIds": [],
+      "candidates": [
+        {
+          "id": "candidate:current-d",
+          "kind": "current",
+          "tokens": 300,
+          "groupId": "group:current-d",
+          "sourceIds": ["entry:request-d"],
+          "staticScore": 1000,
+          "candidateScore": 1000,
+          "currentRequest": true
+        },
+        {
+          "id": "candidate:history-d",
+          "kind": "history",
+          "tokens": 50,
+          "groupId": "group:history-d",
+          "sourceIds": ["entry:history-d"],
+          "staticScore": 10,
+          "candidateScore": 10
+        }
+      ],
+      "totalBudgetTokens": 200,
+      "categoryBudgets": {},
+      "outcomeLabels": ["expected:fail-open"]
+    }
+  ]
+}

package/quality/semantic-corpus-v1.json

@@ -0,0 +1,84 @@
+{
+  "schemaVersion": 1,
+  "corpusVersion": "ds4-semantic-corpus-v1",
+  "baseQualityCorpusVersion": "ds4-quality-corpus-v1",
+  "description": "Synthetic sanitized M16 retrieval fixtures evaluated with the M14 evidence recall and irrelevant-token metrics.",
+  "fixtures": [
+    {
+      "id": "semantic-auth-renewal",
+      "query": "renew authorization credentials after expiry",
+      "exactIdentifiers": [],
+      "expectedEvidenceIds": ["evidence:auth-refresh"],
+      "maxResults": 1,
+      "candidates": [
+        {
+          "id": "evidence:auth-refresh",
+          "text": "OAuth token refresh handles expired authentication secrets.",
+          "tokens": 24
+        },
+        {
+          "id": "evidence:schema",
+          "text": "SQLite migration creates a project metadata table.",
+          "tokens": 28
+        }
+      ]
+    },
+    {
+      "id": "semantic-cache-reuse",
+      "query": "reuse previously computed responses to reduce latency",
+      "exactIdentifiers": [],
+      "expectedEvidenceIds": ["evidence:cache"],
+      "maxResults": 1,
+      "candidates": [
+        {
+          "id": "evidence:cache",
+          "text": "Memoized output caching avoids repeated work and improves performance.",
+          "tokens": 30
+        },
+        {
+          "id": "evidence:logging",
+          "text": "Structured logs record request metadata for diagnostics.",
+          "tokens": 26
+        }
+      ]
+    },
+    {
+      "id": "exact-path-priority",
+      "query": "inspect src/Auth.ts before changing token renewal",
+      "exactIdentifiers": ["src/Auth.ts"],
+      "expectedEvidenceIds": ["evidence:exact-path"],
+      "maxResults": 1,
+      "candidates": [
+        {
+          "id": "evidence:exact-path",
+          "text": "src/Auth.ts exports a small compatibility wrapper.",
+          "tokens": 20
+        },
+        {
+          "id": "evidence:semantic-neighbor",
+          "text": "Authentication credential refresh renews expired OAuth tokens.",
+          "tokens": 34
+        }
+      ]
+    },
+    {
+      "id": "semantic-storage-failure",
+      "query": "debug persistence failures in the local datastore",
+      "exactIdentifiers": [],
+      "expectedEvidenceIds": ["evidence:sqlite-error"],
+      "maxResults": 1,
+      "candidates": [
+        {
+          "id": "evidence:sqlite-error",
+          "text": "SQLite database exceptions are isolated and fall back safely.",
+          "tokens": 32
+        },
+        {
+          "id": "evidence:ui",
+          "text": "Terminal colors and status labels are rendered by the UI.",
+          "tokens": 30
+        }
+      ]
+    }
+  ]
+}

package/quality/symbol-corpus-v1.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "corpusVersion": "ds4-symbol-corpus-v1",
+  "fixtures": [
+    {
+      "id": "typescript-comments-and-methods",
+      "language": "typescript",
+      "filePath": "src/service.ts",
+      "content": "import { Client } from \"./client.js\";\n// class PhantomComment {}\nconst sample = \"function PhantomString() {}\";\nexport class Service {\n  async run(client: Client): Promise<Result> {\n    return client.execute();\n  }\n}\n",
+      "expectedSymbols": ["sample", "Service", "Service.run"],
+      "forbiddenSymbols": ["PhantomComment", "PhantomString"]
+    },
+    {
+      "id": "javascript-declarations",
+      "language": "javascript",
+      "filePath": "src/worker.js",
+      "content": "const text = 'class StringOnly {}';\nexport function buildWorker(options) {\n  return createWorker(options);\n}\nexport const stopWorker = () => terminateWorker();\n",
+      "expectedSymbols": ["text", "buildWorker", "stopWorker"],
+      "forbiddenSymbols": ["StringOnly"]
+    },
+    {
+      "id": "python-indentation",
+      "language": "python",
+      "filePath": "src/processor.py",
+      "content": "from app.client import Client\n# def phantom_comment(): pass\nclass Processor:\n    def process(self, client: Client):\n        return client.execute()\n\ndef create_processor():\n    return Processor()\n",
+      "expectedSymbols": ["Processor", "Processor.process", "create_processor"],
+      "forbiddenSymbols": ["phantom_comment"]
+    },
+    {
+      "id": "go-receiver-method",
+      "language": "go",
+      "filePath": "service/service.go",
+      "content": "package service\n\nimport (\n  \"context\"\n  \"example/client\"\n)\n\n// type Phantom struct{}\ntype Service struct { client *client.Client }\n\nfunc (s *Service) Run(ctx context.Context) error {\n  return s.client.Execute(ctx)\n}\n",
+      "expectedSymbols": ["Service", "Service.Run"],
+      "forbiddenSymbols": ["Phantom"]
+    }
+  ]
+}

package/scripts/compare-context-quality.mjs

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import {
+  compareQualityStrategies,
+  staticRankingStrategy,
+  taskWeightedCandidateStrategy,
+} from "ds4-context-core/quality/context-quality";
+import { stableStringify } from "ds4-context-core/shared/stable-json";
+
+const corpusUrl = new URL("../quality/corpus-v1.json", import.meta.url);
+const corpus = JSON.parse(readFileSync(fileURLToPath(corpusUrl), "utf8"));
+const startedAt = performance.now();
+const report = compareQualityStrategies(corpus, [
+  staticRankingStrategy(),
+  taskWeightedCandidateStrategy(),
+]);
+const durationMs = performance.now() - startedAt;
+
+process.stdout.write(`${stableStringify(report)}\n`);
+if (process.argv.includes("--timing")) {
+  process.stderr.write(`quality comparison wall-clock: ${durationMs.toFixed(3)} ms\n`);
+}