Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
docs(incremental): define symbol evidence rules and verification matrix
Lum110484ae3b878d5d
diff --git a/docs/incremental/symbol-loss-validation.md b/docs/incremental/symbol-loss-validation.mdnew file mode 100644index 00000000..9a0956ac--- /dev/null+++ b/docs/incremental/symbol-loss-validation.md@@ -0,0 +1,37 @@+# Incremental symbol-loss validation contract++This gate protects functions, classes and methods already present in the published graph. It does not reconstruct historical omissions, change significance filtering for new symbols, or evaluate arbitrary program execution.++## Audit++The publication boundary is already centralized: prepare snapshots the original graph before pruning; merge validates its candidate; finalize independently validates before writing graph/fingerprints/meta; repair replaces only affected current contributions and is limited to one attempt per base/head. These boundaries and current-edge ownership reconciliation remain required regression coverage.++The source-evidence layer mixed structural declarations, runtime-installed names and arbitrary AST text in a file-wide set/boolean. This caused both false absence (computed names have no matching literal token) and false preservation (another class's accessor or a quoted setter argument). Adding API tokens could only alternate between these failure modes.++## Decision rules++1. A preserved graph descriptor must keep its symbol kind/name and explicit class ownership. Unowned callables require source identity verification across commits.+2. Source identities are `(path, kind, owner, name)`. Locations disambiguate within a revision; they are not cross-revision identity. Duplicate source identities and competing graph mappings remain unknown.+3. A unique current declaration plus a unique current graph binding preserves the old symbol. A declaration without a matching graph node reports `still-present`.+4. Missing identities become `unknown` if parsing, baseline identity, evidence version, or current ID ownership cannot be verified. Empty extraction never proves deletion.+5. Supplemental evidence describes possible declarations using `kind`, `owner`, `name`, optional name suffix, location and reason. A null field is explicitly unknown, never an empty/free scope. Only evidence compatible with the missing identity prevents deletion. Ordinary reads, strings and parameter names are not declarations.+6. Static installers preserve exact names and owners (including Ruby readers versus writers). Dynamic keys have unknown names; unresolved receivers have unknown owners; arbitrary evaluation/installer aliases may require file-wide uncertainty. The gate does not execute code or restore old semantic data.+7. If the uniquely mapped old identity is absent and no compatible uncertainty remains, report `deleted`. A different class's same-name declaration is not that identity. Reusing the old graph ID for a different owner remains an identity conflict until the analyzer supplies distinct descriptors.+8. Any unresolved entry blocks publication. One targeted repair may regenerate complete affected files. Failed repair leaves all three durable baseline files unchanged.++## Verification matrix++Each source transition is checked independently from publication mechanics.++| Axis | Required cases |+| --- | --- |+| Result | preserved, still-present but omitted, genuinely deleted, unknown |+| Identity | stable ID; alternate ID; reused ID; same name across owners; free function versus method; duplicate/overloaded source identities; moved lines |+| Supplemental names | exact same/different name; unknown name; reader/writer suffix; quoted/symbol spelling; escapes/interpolation |+| Scope | same class; another class; free scope; unresolved receiver; bound installer alias; arbitrary evaluation |+| Syntax | JS/TS/JSX/TSX methods/properties/assignments/property APIs; Ruby accessors/method installers; Python attributes/installers; Go/Rust/C++ receiver extraction |+| Negative evidence | unrelated string, parameter, normal read/call; static installer for another symbol; another owner's accessor |+| Invalid evidence | unsupported parser, parse recovery/error, empty extraction, missing evidence version, ambiguous old mapping |+| Publication | 20-to-1 omission; equal counts; merge/direct-finalize refusal; retry success/failure; stable prepare baseline; stale shards; deleted/excluded files; both data directories; current edge endpoint reuse |++Tests must assert positive and negative outcomes for each recognizer rather than only adding the latest reported failure. Existing publication tests continue to verify actual persisted bytes and fresh edge identities. Full Linux/Windows CI and one overall Codex review follow the integrated local matrix.