{
  "schema": "fak-concept-disambiguation-scorecard.data/1",
  "meta": {
    "as_of": "2026-06-29",
    "fak_version": "v0.34.0",
    "title": "fak concept-disambiguation scorecard - crystal clarity across similar-sounding names",
    "_doc": "Each row is one DISTINCT confusable fak concept, scored on whether it is crystal-clear: one canonical name, a written definition, an explicit line drawn against its siblings, and that line anchored in a doc that exists. The scorecard DISCOVERS the confusable universe from the tree (per family, a token counts only when it spans >= min_files production files, or is a package/dir name, or a doc heading) so coverage cannot be gamed by editing data. The grounding token must appear in the production corpus; the glossary anchor must exist. Regenerate the doc: python tools/concept_disambiguation_scorecard.py --markdown-dir docs/concept-disambiguation-scorecard"
  },
  "families": [
    {
      "id": "cache",
      "name": "Cache family",
      "roots": ["cache"],
      "ignore": ["cached", "caches", "cacheable", "cacheless", "uncached", "caching",
                 "cachedir", "cachelen", "cachettl", "flushcache", "defaultcachesize",
                 "cachecreation", "cacheentry", "cacheevent", "cachedecay", "cachestream", "cacherevoke",
                 "usercachedir"],
      "min_files": 3,
      "note": "The headline confusable space: raw KV tensor storage vs the page-table virtualization (vCache) vs the provider prompt-cache vs the metadata sidecar (cachemeta)."
    },
    {
      "id": "attention",
      "name": "Attention family",
      "roots": ["attention", "attn"],
      "ignore": ["attentions", "attentive", "tattn"],
      "min_files": 3,
      "note": "Attention compute vs the attention-witness accumulation (Attended/EMA/Cumulative) vs the DSA AttentionIndex metadata."
    },
    {
      "id": "guard-gate",
      "name": "Guard / gate family",
      "roots": ["guard", "gate"],
      "exclude": ["gateway", "aggregat", "delegat", "propagat", "navigat", "investigat"],
      "ignore": ["gated", "gates", "guarded", "guards", "gating", "ungated",
                 "unguarded", "guarding", "guardrails", "gatew"],
      "min_files": 3,
      "note": "The kernel (guard) vs the many decision points (gate): adjudicators pre-call, result admitters post-call, git-hook gates, promotion gates."
    },
    {
      "id": "session-runtime",
      "name": "Session / scheduling family",
      "roots": ["session", "slot", "scheduler"],
      "ignore": ["sessions", "scheduling", "scheduled", "slots"],
      "min_files": 3,
      "note": "Session (the drive record) vs Turn (one round-trip) vs Slot (the free/busy signal) vs Scheduler (the policy that picks the next winner)."
    },
    {
      "id": "witness-proof",
      "name": "Witness / evidence family",
      "roots": ["witness", "refut", "revoc", "trustepoch"],
      "ignore": ["witnessing", "witnessable", "witnessed", "witnesses", "refuted", "refutes", "revocations", "refutations"],
      "min_files": 3,
      "note": "A world-state witness (a cache's external binding) vs a measurement witness (RSI proof) vs a Claim (self-report) vs the WitnessResolver that corroborates claims."
    },
    {
      "id": "gateway-engine",
      "name": "Gateway / engine family",
      "roots": ["gateway", "engine", "vdso", "kernel"],
      "ignore": ["engineering", "engineer", "gateways", "kernels", "kernel32"],
      "min_files": 3,
      "note": "Kernel (coordinator) vs gateway (the wire) vs engine (the dispatch seam) vs vDSO (the local fast path) vs model (the in-kernel forward pass)."
    },
    {
      "id": "policy-capability",
      "name": "Policy / authorization family",
      "roots": ["policy", "capability", "posture", "adjudicat", "preflight"],
      "ignore": ["policies", "adjudicators", "capabilities", "postures", "adjudication", "adjudicate", "adjudicated", "adjudicates", "policyblocks"],
      "min_files": 3,
      "note": "Capability floor (intent) vs policy manifest (on-disk JSON) vs loaded Policy (compiled table) vs the adjudicator (enforcer) vs verdict/reason-code (its output)."
    },
    {
      "id": "context-ctx",
      "name": "Context-management family",
      "roots": ["ctx", "context", "recall", "compaction"],
      "ignore": ["contexts", "recalling", "recalled",
                 "context", "ctx", "cctx", "compactions", "recalls"],
      "min_files": 3,
      "note": "context-MMU (gates result bytes) vs KV-MMU (evicts K/V spans) vs recall (the persisted core dump) vs compaction (provider prefix reuse) vs the ctx* planners."
    },
    {
      "id": "score-debt",
      "name": "Scorecard / debt family",
      "roots": ["scorecard", "debt"],
      "ignore": ["scorecards"],
      "min_files": 3,
      "note": "The meta-family: the scorecard machine vs each *_debt integer vs the control pane that folds them - this very scorecard is one member."
    },
    {
      "id": "support-maturity",
      "name": "Support / coverage / correctness / parity / maturity family",
      "roots": ["support", "coverage", "correctness", "parity", "maturity"],
      "ignore": ["supported", "unsupported", "supports", "supporting", "errmmapunsupported",
                 "errstreamingunsupported", "streamingsupported", "recurrentevictunsupportederror",
                 "sourcecoverage", "targetcoverage", "correctnessclass", "correctnessdependson",
                 "paritybench", "parityreport", "supportmaturityscore", "supportmaturitydebt",
                 "immaturity"],
      "min_files": 3,
      "note": "The support-maturity ladder vocabulary: support says a path exists, coverage says how much of the declared/discovered space is exercised or positioned, correctness says the behavior is right, parity compares to a named peer/baseline, and maturity summarizes production readiness."
    },
    {
      "id": "cross-cluster",
      "name": "Cross-cluster canonical collisions",
      "roots": [],
      "ignore": [],
      "min_files": 99,
      "note": "Curated registry of same-token, two-meaning collisions across UNRELATED packages (Manifest, Verdict, Backend, Observer, Index, Store, Refusal). Each is positioned as TWO distinct rows that draw the line against each other and anchor it in the glossary. roots is empty BY DESIGN: these tokens (manifest/verdict/backend/observer/index/store/refusal) over-match hundreds of unrelated identifiers in their own packages, so this family is hand-curated, never discovered - a discovering root would flood coverage with non-confusable tokens (verdictAllow, indexByte, storeInt32)."
    },
    {
      "id": "evict",
      "name": "Eviction family",
      "roots": ["evict", "evicted", "eviction"],
      "ignore": ["evictable", "evictSupported", "eviction", "evicts", "evicting"],
      "min_files": 3,
      "note": "Three disjoint eviction planes: physical KV tensor span removal, logical playbook pruning under token budget, and model instance LRU eviction from a session pool."
    },
    {
      "id": "decision",
      "name": "Decision family",
      "roots": ["decision"],
      "ignore": [],
      "min_files": 3,
      "note": "Four disjoint Decision types: witness adjudication verdict, kernel tool-call explanation trace, scheduler loop admission advisory, and shared-task execution state tracking."
    },
    {
      "id": "render-materialize",
      "name": "Render / materialize family",
      "roots": ["render", "RenderPlan", "RenderItem", "Rendered", "materialize"],
      "ignore": ["rendered", "rendering", "renders", "materializes", "materialized", "materializers"],
      "min_files": 2,
      "note": "Three disjoint render/materialize concepts: prompt-assembly layout (RenderPlan), memq cell materialization (RenderItem), and ctxplan span paging (Rendered)."
    },
    {
      "id": "plan",
      "name": "Plan family",
      "roots": ["plan", "Plan", "Candidate"],
      "exclude": ["plane", "plank", "explanat"],
      "ignore": ["planner", "plans", "planning", "Candidates", "candidates",
                 "planned", "notplanned", "planted", "planners",
                 "plannedcumtok", "plannedcumtokens"],
      "min_files": 2,
      "note": "Two disjoint Plan types: ctxplanner's chosen resident view selection vs memq's static pre-execution explain output. Candidate is scored span input to ctxplanner."
    },
    {
      "id": "pool",
      "name": "Pool family",
      "roots": ["pool", "Pool", "PoolProfile"],
      "exclude": ["spool"],
      "ignore": [],
      "min_files": 2,
      "note": "Two disjoint pool concepts: session bounded-LRU container vs cachemeta pooling character profile describing a tier's host/coherence/share properties."
    },
    {
      "id": "layout",
      "name": "Layout family",
      "roots": ["layout", "Layout", "kvLayout"],
      "ignore": ["layouts"],
      "min_files": 2,
      "note": "Three disjoint layout concepts: tensor element physical arrangement (RowMajor/ColMajor), ctxplan region profile for layout-aware planning, and attention cache variant seam (standardKVLayout vs mlaKVLayout)."
    }
  ]
}
