feat(knowledge): add local context service foundation

[kunaldhongade]

Summary

• add a reusable local context service in the existing knowledge package
• coalesce Chokidar file events into serialized graph generations
• include repository identity, indexed revision, tree fingerprint, freshness, and cache generation on every query
• quarantine corrupt or incompatible service state without touching source files
• support bounded query waits and cooperative cancellation
• document OSS-first choices and the remaining CLI/MCP, locking, atomic persistence, and benchmark work

Why

Issue #682 needs a long-lived local context layer without creating a competing index. This foundation wraps the existing engineering knowledge graph and makes stale-versus-current state explicit before transport and process-management surfaces are added.

Validation

• ./.codedecay/setup.local.sh
• pnpm run lint
• pnpm typecheck
• pnpm test (135 files, 754 tests)
• pnpm build
• pnpm --filter @submuxhq/codedecay pack --dry-run
• node packages/cli/dist/index.js --help
• node packages/cli/dist/index.js analyze --format markdown
• focused context service tests after cancellation fix (5 passed)

Refs #682

[github-actions]

CodeDecay PR Check

Lead catch: Config area changed — packages/knowledge/package.json:16

packages/knowledge/package.json touches a config area and should be reviewed for regression impact.

Risk: Medium · Merge 69/100 · Decay 46/100 · Security 0/100

Full CodeDecay report

CodeDecay Report

Overall risk: Medium

Score	Value
Merge risk	69/100
Decay risk	46/100
Security risk	0/100

Findings	Count
High	7
Medium	4
Low	12

Changed Files

• docs/context-service.md added (+13/-0)
• docs/service-topology.md added (+9/-0)
• judge-lab/app/globals.css modified (+3/-1)
• judge-lab/app/judge-lab.tsx modified (+18/-8)
• judge-lab/tests/judge-lab.spec.ts modified (+3/-1)
• packages/knowledge/package.json modified (+3/-1)
• packages/knowledge/src/index.ts modified (+41/-0)
• packages/knowledge/src/service.ts added (+281/-0)
• packages/knowledge/src/topology/impact.ts added (+115/-0)
• packages/knowledge/src/topology/manifest.ts added (+228/-0)
• packages/knowledge/src/topology/types.ts added (+116/-0)
• packages/knowledge/test/context-service.test.ts added (+165/-0)
• packages/knowledge/test/service-topology.test.ts added (+246/-0)
• pnpm-lock.yaml modified (+6/-0)

Likely Impacted Areas

• Medium Build and runtime configuration (config): packages/knowledge/package.json
• Medium UI route (ui): judge-lab/app/judge-lab.tsx
• Low Dependency lockfile (config): pnpm-lock.yaml
• Low Documentation (docs): docs/context-service.md, docs/service-topology.md
• Low Source code (source): packages/knowledge/src/index.ts, packages/knowledge/src/service.ts, packages/knowledge/src/topology/impact.ts, packages/knowledge/src/topology/manifest.ts, packages/knowledge/src/topology/types.ts
• Low Tests (test): judge-lab/tests/judge-lab.spec.ts, packages/knowledge/test/context-service.test.ts, packages/knowledge/test/service-topology.test.ts

Normalized Impact Graph

Graph artifact: .codedecay/local/impact-graph.json (4184 node(s), 8535 edge(s))

• Confidence: Direct: 8535, inferred: 0, heuristic: 0
• codedecay-js-babel-symbols via @babel/parser (available, adapter 1.0.0)
  • Limitation: Call expressions are not connected to target symbols in this adapter version.
  • Limitation: Only JavaScript and TypeScript files parsed by @babel/parser are represented.
  • Limitation: Static import resolution does not resolve runtime dependency injection or dynamic imports.
• codedecay-python-lezer via @lezer/python (available, adapter 1.0.0)
  • Limitation: Dynamic imports, dependency injection, decorators without literal routes, and framework route registries are not resolved.
  • Limitation: Python impact evidence uses the @lezer/python grammar and conservative module-to-file resolution.
  • Limitation: Static test imports do not prove execution or assertion quality.
• Graph limitation: A static test import does not prove the symbol executed or that assertions cover its behavior.

Symbol Impact Evidence

Graph artifact: .codedecay/local/symbol-impact-graph.json (895 file(s), 5321 edge(s))

• judge-lab/app/judge-lab.tsx#JudgeLab -> judge-lab/app/page.tsx
• packages/knowledge/src/index.ts#analyzeServiceTopologyImpact -> packages/knowledge/test/service-topology.test.ts
  • Likely tests: packages/knowledge/test/service-topology.test.ts
• packages/knowledge/src/index.ts#CONTEXT_SERVICE_STATE_PATH -> packages/knowledge/test/context-service.test.ts
  • Likely tests: packages/knowledge/test/context-service.test.ts
• packages/knowledge/src/index.ts#ContextServiceBuildInput -> packages/knowledge/test/context-service.test.ts
  • Likely tests: packages/knowledge/test/context-service.test.ts
• packages/knowledge/src/index.ts#loadServiceTopologyManifest -> packages/knowledge/test/service-topology.test.ts
  • Likely tests: packages/knowledge/test/service-topology.test.ts
• packages/knowledge/src/index.ts#LocalContextService -> packages/knowledge/test/context-service.test.ts
  • Likely tests: packages/knowledge/test/context-service.test.ts
• packages/knowledge/src/index.ts#normalizeServiceTopologyGraph -> packages/knowledge/test/service-topology.test.ts
  • Likely tests: packages/knowledge/test/service-topology.test.ts
• packages/knowledge/src/index.ts#persistServiceTopologyArtifact -> packages/knowledge/test/service-topology.test.ts
  • Likely tests: packages/knowledge/test/service-topology.test.ts
• packages/knowledge/src/index.ts#renderServiceTopologyImpactMarkdown -> packages/knowledge/test/service-topology.test.ts
  • Likely tests: packages/knowledge/test/service-topology.test.ts
• packages/knowledge/src/index.ts#ServiceTopologyGraph -> packages/knowledge/test/service-topology.test.ts
  • Likely tests: packages/knowledge/test/service-topology.test.ts
• packages/knowledge/src/service.ts#CONTEXT_SERVICE_SCHEMA_VERSION -> packages/knowledge/src/index.ts
• packages/knowledge/src/service.ts#CONTEXT_SERVICE_STATE_PATH -> packages/knowledge/src/index.ts, packages/knowledge/test/context-service.test.ts
  • Likely tests: packages/knowledge/test/context-service.test.ts
• ...and 30 more symbol impact(s)

Language And Parser Coverage

• Source files classified: 9
• Fully supported parser files: 9
• Limited files: 0
• Unsupported files: 0

Merge Risk Breakdown

• Score: 69/100
• Raw score before dampeners: 100/100
• Adjusted score before severity cap: 100/100
• Highest contributing severity: Medium

Top contributors:

• +18 Change size (structural): Changed lines amplify review cost across 14 file(s).
• +16 Config area changed (direct): packages/knowledge/package.json touches a config area and should be reviewed for regression impact.
• +12 File spread (structural): Change breadth spans 14 file(s).
• +10 Ui area changed (heuristic): judge-lab/app/judge-lab.tsx touches a ui area and should be reviewed for regression impact.
• +6 Config area changed (direct): pnpm-lock.yaml touches a config area and should be reviewed for regression impact.

Notes:

• Untrusted memory context is visible but contributes 0 score until trusted evidence corroborates it.

Decay Risk Breakdown

• Score: 46/100
• Raw score before dampeners: 61/100
• Adjusted score before severity cap: 46/100
• Highest contributing severity: High
• Evidence mode: heuristic-only

Top contributors:

• +18 High complexity in changed function (heuristic): JudgeLab has estimated cyclomatic complexity 23.
• +18 Large changed function (heuristic): JudgeLab spans 488 lines, which increases review and regression risk.
• +10 Duplicated added logic (heuristic): A similar block of added logic appears 2 times across 2 file(s).
• +9 Change size (structural): Changed lines amplify review cost across 14 file(s).
• +6 File spread (structural): Change breadth spans 14 file(s).

Dampeners:

• -15 Heuristic-only dampener: Decay stays conservative until direct evidence exists.

Notes:

• Heuristic-only decay is capped at 54/100 until direct evidence exists.

Security Risk Breakdown

• Score: 0/100
• Raw score before dampeners: 0/100
• Adjusted score before severity cap: 0/100

Security Matcher Coverage

• Changed source files scanned: 6
• Security candidates found: 0
• Skipped files: 0

Test Evidence

• Mode: heuristic-only
• Sources: none
• Changed source coverage:
• judge-lab/app/judge-lab.tsx: not measured (no measurable changed lines)
• packages/knowledge/src/index.ts: not measured (no measurable changed lines)
• packages/knowledge/src/service.ts: not measured (no measurable changed lines)
• packages/knowledge/src/topology/impact.ts: not measured (no measurable changed lines)
• packages/knowledge/src/topology/manifest.ts: not measured (no measurable changed lines)
• packages/knowledge/src/topology/types.ts: not measured (no measurable changed lines)
• Notes:
• No runtime coverage artifact was found. Test audit remains heuristic-only.

Changed Path Test Proof

Status	Count
Runtime-proven	0
Static-only	28
Weakened by mocks	0
Unproven	14

• Static-only judge-lab/app/judge-lab.tsx#JudgeLab (static-reference, deterministic)
  • Evidence: Referenced by judge-lab/tests/judge-lab.spec.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: judge-lab/tests/judge-lab.spec.ts
  • Repair task: Strengthen judge-lab/tests/judge-lab.spec.ts so it executes judge-lab/app/judge-lab.tsx#JudgeLab with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#analyzeServiceTopologyImpact (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/service-topology.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/service-topology.test.ts
  • Repair task: Strengthen packages/knowledge/test/service-topology.test.ts so it executes packages/knowledge/src/index.ts#analyzeServiceTopologyImpact with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#CONTEXT_SERVICE_STATE_PATH (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/context-service.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/context-service.test.ts
  • Repair task: Strengthen packages/knowledge/test/context-service.test.ts so it executes packages/knowledge/src/index.ts#CONTEXT_SERVICE_STATE_PATH with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#ContextServiceBuildInput (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/context-service.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/context-service.test.ts
  • Repair task: Strengthen packages/knowledge/test/context-service.test.ts so it executes packages/knowledge/src/index.ts#ContextServiceBuildInput with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#loadServiceTopologyManifest (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/service-topology.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/service-topology.test.ts
  • Repair task: Strengthen packages/knowledge/test/service-topology.test.ts so it executes packages/knowledge/src/index.ts#loadServiceTopologyManifest with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#LocalContextService (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/context-service.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/context-service.test.ts
  • Repair task: Strengthen packages/knowledge/test/context-service.test.ts so it executes packages/knowledge/src/index.ts#LocalContextService with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#normalizeServiceTopologyGraph (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/service-topology.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/service-topology.test.ts
  • Repair task: Strengthen packages/knowledge/test/service-topology.test.ts so it executes packages/knowledge/src/index.ts#normalizeServiceTopologyGraph with assertions; static import alone is not proof.
• Static-only packages/knowledge/src/index.ts#persistServiceTopologyArtifact (static-reference, deterministic)
  • Evidence: Referenced by packages/knowledge/test/service-topology.test.ts, but no runtime coverage artifact proves changed lines executed.
  • Static references: packages/knowledge/test/service-topology.test.ts
  • Repair task: Strengthen packages/knowledge/test/service-topology.test.ts so it executes packages/knowledge/src/index.ts#persistServiceTopologyArtifact with assertions; static import alone is not proof.
• ...and 34 more changed path proof entries

Untrusted Memory Context

• Project invariant may be impacted (packages/knowledge/package.json:16): Untrusted memory context: invariant "No hidden cloud or model call" applies to this change. The OSS CLI must remain useful without telemetry, API keys, hosted services, required LLM calls, or CodeDecayCloud.
• Project invariant may be impacted (packages/knowledge/package.json:16): Untrusted memory context: invariant "Commands are explicit" applies to this change. CodeDecay must not run project commands unless they are configured and safety.allowCommands is true.
• Project invariant may be impacted (docs/context-service.md:1): Untrusted memory context: invariant "Tool evidence is separate from AI suggestions" applies to this change. Reports must not present agent/model suggestions as verified evidence unless backed by deterministic checks or command output.
• Project invariant may be impacted (packages/knowledge/package.json:16): Untrusted memory context: invariant "Package remains installable from npm" applies to this change. The published package must include README, LICENSE, package.json, dist/index.js, and dist/index.d.ts without workspace-only dependency leaks.
• Past regression area changed (packages/knowledge/package.json:16): Untrusted memory context: past regression "Published npm package leaked workspace protocol" may be relevant. Published package installation failed when workspace protocol dependencies leaked into the npm package.
• Project invariant may be impacted (docs/context-service.md:1): Untrusted memory context: invariant "Output must be actionable" applies to this change. Redteam reports and agent bundles should say what behavior to verify, which test proof is weak or missing, and what task a coding agent should perform.
• Architecture note applies (packages/knowledge/package.json:16): Untrusted architecture context: CLI is the published surface: The public npm package is @submuxhq/codedecay and the binary is codedecay. Internal workspace packages are implementation details.

High Risk Findings

• High complexity in changed function (judge-lab/app/judge-lab.tsx:21): JudgeLab has estimated cyclomatic complexity 23.
• Large changed function (judge-lab/app/judge-lab.tsx:21): JudgeLab spans 488 lines, which increases review and regression risk.

Medium Risk Findings

• Duplicated added logic (packages/knowledge/src/index.ts:51): A similar block of added logic appears 2 times across 2 file(s).
• Config area changed (packages/knowledge/package.json:16): packages/knowledge/package.json touches a config area and should be reviewed for regression impact.
• Ui area changed (judge-lab/app/judge-lab.tsx:264): judge-lab/app/judge-lab.tsx touches a ui area and should be reviewed for regression impact.

Low Risk Findings

• Config area changed (pnpm-lock.yaml:148): pnpm-lock.yaml touches a config area and should be reviewed for regression impact.
• Docs area changed (docs/context-service.md:1): docs/context-service.md touches a docs area and should be reviewed for regression impact.
• Docs area changed (docs/service-topology.md:1): docs/service-topology.md touches a docs area and should be reviewed for regression impact.
• Source area changed (packages/knowledge/src/index.ts:28): packages/knowledge/src/index.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/knowledge/src/service.ts:1): packages/knowledge/src/service.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/knowledge/src/topology/impact.ts:1): packages/knowledge/src/topology/impact.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/knowledge/src/topology/manifest.ts:1): packages/knowledge/src/topology/manifest.ts touches a source area and should be reviewed for regression impact.
• Source area changed (packages/knowledge/src/topology/types.ts:1): packages/knowledge/src/topology/types.ts touches a source area and should be reviewed for regression impact.
• Test area changed (judge-lab/tests/judge-lab.spec.ts:10): judge-lab/tests/judge-lab.spec.ts touches a test area and should be reviewed for regression impact.
• Test area changed (packages/knowledge/test/context-service.test.ts:1): packages/knowledge/test/context-service.test.ts touches a test area and should be reviewed for regression impact.
• Test area changed (packages/knowledge/test/service-topology.test.ts:1): packages/knowledge/test/service-topology.test.ts touches a test area and should be reviewed for regression impact.

Recommended Checks

• Add an integration test that reaches packages/knowledge/src/topology/types.ts#SERVICE_TOPOLOGY_EDGE_KINDS without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#SERVICE_TOPOLOGY_NODE_KINDS without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#SERVICE_TOPOLOGY_SCHEMA_VERSION without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyConfidence without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyEdge without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyEdgeKind without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyFreshness without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyGap without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyImpact without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyImpactReport without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyNode without mocking the changed boundary.
• Add an integration test that reaches packages/knowledge/src/topology/types.ts#ServiceTopologyNodeKind without mocking the changed boundary.

Notes

CodeDecay is deterministic and local-first. This report was generated without telemetry, API keys, LLMs, or model calls.

---

Found by CodeDecay - deterministic, local-first, no telemetry.