diff --git a/.arxiv/2026-10_sag_agent_attention_active_selection_excerpts.md b/.arxiv/2026-10_sag_agent_attention_active_selection_excerpts.md new file mode 100644 index 000000000..560e26d76 --- /dev/null +++ b/.arxiv/2026-10_sag_agent_attention_active_selection_excerpts.md @@ -0,0 +1,113 @@ +# D-SAG-4: bounded context attention, costly exploration and correctness-first uncertainty + +**Date:** 2026-10-12. **Mode:** primary-paper **abstract-level paraphrases**, not verbatim quotations, no code implementations or D-SAG performance claims. Some papers have detailed methods/results not reproduced here; CC must read and pin an exact PDF version before claiming detailed parity or method reproduction. Companion: [deferred contracts](../.claude/plans/software-awareness-agent-context-deferred-contracts-v1.md). + +## A1. Liu et al. (2023): *Lost in the Middle: How Language Models Use Long Contexts* + +**Paper:** Nelson F. Liu, Kevin Lin, John Hewitt, Ashwin Paranjape, Michele Bevilacqua, Fabio Petroni and Percy Liang, [arXiv:2307.03172v3](https://arxiv.org/abs/2307.03172), TACL 2023. **Source:** abstract, main experimental conclusion. + +**Excerpt (paraphrase).** A longer input does not guarantee useful access to relevant evidence. In multi-document QA and key-value retrieval, the authors find that changing the **position** of relevant context can substantially change model performance; models often do best when the critical item is near the beginning or end and degrade when it is buried centrally. + +**Proposed D-SAG transfer:** provide a brief intent-specific context slice placing *critical semantic guards and source evidence* clearly, not a high-degree neighbor dump. Measure context ordering as a factorial dimension separately from length, and do not presume an extra-long context window fixes omissions. + +**Falsifier:** identical source facts returned in different order cause different correct-patch outcomes, or an important population/NULL law is buried by low-value nodes. A smaller graph context that drops a necessary law still fails. + +**Boundary:** findings are for models/tasks tested in the paper, not a measured law for Claude Code 2026. + +## A2. Phan et al. (2024): *RepoHyper: Search-Expand-Refine on Semantic Graphs for Repository-Level Code Completion* + +**Paper:** Huy N. Phan, Hoang N. Phan, Tien N. Nguyen, Nghi D. Q. Bui, [arXiv:2403.06095](https://arxiv.org/abs/2403.06095), current abstract describes an RSG, graph expansion and link-prediction refinement. **Source:** abstract. + +**Excerpt (paraphrase).** Repository context can be discovered by first locating relevant code, then expanding through semantic relations, then refining the candidate set; the paper reports stronger code-completion performance than its tested baselines. + +**Proposed D-SAG transfer:** `resolve → one Quack hop → rank/budget → optionally expand`. Critically, unlike RepoHyper's own engine, D-SAG #1509 currently only supports its proven one-hop `ScatterOrU32` query. Document `UnsupportedMultiHop` rather than imitating an expanded walk with a new interpreter. + +**Falsifier:** link prediction provides plausible but compiler-unverified method dependencies; returning them as `Compiled` or `Verified` is illegal. Keep link prediction (if used) in `Hypothesis`. + +## A3. Ouyang et al. (2024/2025): *RepoGraph: Enhancing AI Software Engineering with Repository-level Code Graph* + +**Paper:** Siru Ouyang et al., [arXiv:2410.14684](https://arxiv.org/abs/2410.14684), originally submitted 2024, revised 2025. **Source:** abstract. + +**Excerpt (paraphrase).** Repository-level relationships support code agents on tasks where single-file/function representations omit relevant structure. The authors report improvements when integrating a repository graph with several tested agent frameworks and on another repository benchmark. + +**Transfer:** **source-symbol** navigation is worth comparing with `CLAUDE.md`/grep, but a source dependency graph is neither a semantic ClassId ontology nor a Quack method compiler. Link the two with explicit source-to-method witnesses. + +**Falsifier:** a trait impl or code-generated source reference is missing, and the graph incorrectly claims 'no callers'. Compare against compiler-backed navigation and independent source oracle. + +## A4. Song & Xu (2017): *A Contextual Bandit Approach for Stream-Based Active Learning* + +**Paper:** Linqi Song and Jie Xu, [arXiv:1701.06725](https://arxiv.org/abs/1701.06725). **Source:** abstract and stated motivation. + +**Excerpt (paraphrase).** Many bandit formulations assume reward observation is free; active learning under costly labels must trade off information received against the cost of asking. This study explores contextual bandits that selectively request costly feedback and communicates prior information alongside queries. + +**Proposed D-SAG transfer:** an optimization experiment is an **action with cost**, not free knowledge. Select whether to benchmark a candidate by considering current uncertainty, expected utility, impact and time/CPU budget. Compare information-gain choices against a simple random/impact-priority scheduler. + +**Falsifier:** an ONA-like policy spends more compute acquiring performance receipts than it saves in later plan selections. A model that only optimizes per-execution cycles while ignoring exploration cost is incomplete. + +**Boundary:** theorem/regret results for that paper's formal problem are not an automatic guarantee for method-selection or NARS evidence in lance-graph. Do not transplant reward or confidence formulas. + +## A5. Shi et al. (2026): *Code Is More Than Text: Uncertainty Estimation for Code Generation* + +**Paper:** Yuling Shi, Caiqi Zhang, Yuexian Li, Haopeng Wang, Yeheng Chen, Nigel Collier and Xiaodong Gu, [arXiv:2606.09577](https://arxiv.org/abs/2606.09577). **Source:** abstract. + +**Excerpt (paraphrase).** Uncertainty about code has multiple dimensions, including lexical fragility, algorithmic intent/implementation divergence and functional behavior that can be executed and tested. The authors evaluate complementary signals rather than identifying one entropy score as a substitute for functional verification. + +**Proposed D-SAG transfer:** distinguish (1) uncertainty about retrieval/identity, (2) semantic legality of a proposed transform, and (3) performance prediction dispersion. Source-backed compiler/test evidence outranks surface language confidence. Use uncertainty to **route to validation**, not to certify a patch. + +**Falsifier:** a low-entropy proposed edit violates a sealed ClassView or gives wrong independent oracle output. The guard rejects it regardless of its model confidence. + +## A6. Rakasi et al. (2026): *When Uncertainty Isn't Enough: An Empirical Study of Self-Correction in Code Generation* + +**Paper:** Pranav Rakasi et al., [arXiv:2608.14659](https://arxiv.org/abs/2608.14659). **Source:** accessible abstract-level search result; **paper PDF not independently inspected for this note**. + +**Excerpt (abstract paraphrase).** The authors report that simple uncertainty-driven code self-correction does not consistently increase correctness in their tested model/benchmark settings, while correction guided by executable verification is more consistently useful. + +**Transfer:** the ONA-inspired selector should direct attention toward *checks and experiments*, not self-certify a generated patch from its own assessed confidence. Compare prediction-only to verification-gated policy. + +**Falsifier:** 'confidence revised upward' but executable tests fail. Code correctness remains false even if the hypothesis scorer likes the patch. + +**Boundary:** do not copy paper-specific numerical scores or claim universally superior verification across all models. Their evaluation is not a benchmark of our architecture. + +## Research synthesis: two different attention problems + +The analogy to foveation/saccades is useful only when made operational: + +**Context attention (model-facing):** select the smallest sufficient facts, source references, tests and proof obligations under a model-visible token budget. Local graph queries spend CPU/IO, not model inference. Expansion later costs additional returned tokens. Measure correct dependency recall and patch correctness, not merely textual compression. + +**Experiment attention (system-facing):** select the next *safe and informative* experiment under a CPU/energy/time budget. A new receipt may reduce hypothesis uncertainty, or reveal a semantic incompatibility that forces refusal. Measure regret/calibration/benefit net of experiment cost; no observed outcome is not the same as negative evidence. + +```text + Same qualified software graph + | + +--------------+--------------+ + | | + Local context lens Experiment lens + which facts to show? which legal probe to run? + | | + bounded evidence predicted outcome + | | + Claude + citations independent execution + | | + source-aware change measured receipt + | | + tests and review revised hypothesis +``` + +The two lenses may share typed graph infrastructure and provenance but **must not** share unchecked authority: a high-interest concept is not a true concept; a frequently cited source is not a verified source; a predicted improvement is not a demonstrated optimization. + +## Proposed experiment ladder + +- **F1:** graph vs greedy symbol/LSP retrieval with identical 4K input-token budget. Preserve mandatory semantic guards; compare patch correctness and critical dependency recall. +- **F2:** vary context ordering, same total tokens and facts. Does order change performance? +- **F3:** compare random, highest-degree and evidence-coverage-based one-hop selection. Record graph query costs. +- **F4:** add source edit between requests, verify stale/dirty worktree invalidation. +- **F5:** select optimization experiments via random, impact heuristic, historical cost and ONA-inspired anticipation; register predictions before receipts and use held-out selectivity/CPU tiers. +- **F6:** ablate execution receipts, perturb evidence ancestry, keep exact final method answer. Does any claimed self-modeling benefit survive? + +**Required log fields:** repo/branch SHA, worktree digest, graph generation, source-index version, task identifier, compiler version/features, model/runtime budget, prompt/tool token accounting, missed gold dependencies, oracle pass/fail, CPU/data versions, cold index time and confidence/uncertainty methodology. + +## Sources + +[2307.03172](https://arxiv.org/abs/2307.03172) · [2403.06095](https://arxiv.org/abs/2403.06095) · [2410.14684](https://arxiv.org/abs/2410.14684) · [1701.06725](https://arxiv.org/abs/1701.06725) · [2606.09577](https://arxiv.org/abs/2606.09577) · [2608.14659](https://arxiv.org/abs/2608.14659). + +**Negative finding is allowed:** if an LSP-backed source index handles normal coding tasks better, reserve Quack/SAG for what conventional tools lack: ClassId readings, law/refusal/physical-program provenance and bounded optimization hypothesis queries. diff --git a/.arxiv/2026-10_sag_ona_internal_experience_source_excerpts.md b/.arxiv/2026-10_sag_ona_internal_experience_source_excerpts.md new file mode 100644 index 000000000..da5bdaf67 --- /dev/null +++ b/.arxiv/2026-10_sag_ona_internal_experience_source_excerpts.md @@ -0,0 +1,89 @@ +# D-SAG-4 source excerpts: ONA's event–anticipation–feedback loop and internal experience + +**Read:** 2026-10-12. **Kind:** SOURCE-GROUNDED PARAPHRASES / RESEARCH; no ONA port, executable parity test, or runtime integration in this note. **Upstream pin:** [OpenNARS for Applications @ dc4efd0](https://github.com/opennars/OpenNARS-for-Applications/tree/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a). **Companions:** [D-SAG-4 plan](../.claude/plans/software-awareness-agent-context-ona-v1.md), [repository-code-graph papers](2026-10_sag_repo_graph_context_source_excerpts.md). + +The term *excerpt* here means a short, attributed **paraphrase** of a source passage or an implementation observation, not a copied passage. Any project transfer is labeled a hypothesis. Existing [2018 self-model note](2018_self_in_nars_requires_internal_experience_and_mental_operations.md) and [NAL audit #1495](https://github.com/AdaWorldAPI/lance-graph/pull/1495) remain separate authorities. + +## Primary S1. Hammer & Lofthouse (2020): ONA architecture and control + +**Source:** Patrick Hammer and Tony Lofthouse, *'OpenNARS for Applications': Architecture and Control*, International Conference on Artificial General Intelligence (2020), pp. 193–204. [Author-hosted conference PDF](https://agi-conf.org/2020/wp-content/uploads/2020/06/AGI-20_paper_52.pdf). Compare with [ONA README](https://github.com/opennars/OpenNARS-for-Applications/blob/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a/README.md). + +**Excerpt S1a (abstract / architecture, paraphrase).** The authors present a pragmatic NARS implementation with event-driven control, separated sensorimotor and semantic inference, and explicit attention under resource constraints. They identify architectural differences from OpenNARS for Research, rather than asserting that ONA is merely its latest release. + +**For lance-graph:** use ONA as a *reference design* for an observation and experiment-selection policy. It is not a replacement for Quack's algebra, the class-method binder, or mask-risc physical execution. + +**Falsifier:** the proposed 'ONA-inspired' path introduces an event interpreter in the warm query execution loop. That is an architectural failure, not necessary support for anticipation. + +**Excerpt S1b (procedure learning / temporal consequences, paraphrase).** Observed sequences and actions can be associated with later consequences to guide future choices under incomplete knowledge. This supports a research analogy between performance hypotheses and subsequent benchmark feedback, **not** automatic authorization to change software. + +**For lance-graph:** distinguish precondition and operation events, predicted consequence, measured outcome, revision and next selection. Demand predicted outcome registration before the benchmark run. + +**Falsifier:** a 'prediction' is manufactured only after the result is visible, or a performance association is called causation without controlled comparison. + +## Primary S2. ONA implementation: pin actual functions + +**Pinned source:** [NAR.c](https://github.com/opennars/OpenNARS-for-Applications/blob/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a/src/NAR.c), [Cycle.c](https://github.com/opennars/OpenNARS-for-Applications/blob/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a/src/Cycle.c), [Memory.c](https://github.com/opennars/OpenNARS-for-Applications/blob/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a/src/Memory.c), [Decision.c](https://github.com/opennars/OpenNARS-for-Applications/blob/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a/src/Decision.c), [Inference.c](https://github.com/opennars/OpenNARS-for-Applications/blob/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a/src/Inference.c). + +| Step | Source anchor (verified names; line numbering tied to the upstream pin) | What source actually does | Proposed analogy | +|---|---|---|---| +| Input | `NAR.c: NAR_AddInput` near L55 | Makes a stamped event, adds it to memory and advances a cycle. | Source-backed method/benchmark observation. | +| Scheduling | `NAR.c: NAR_Cycles`; `Cycle.c: Cycle_Perform` near L1102 | Selects belief/goal events, processes beliefs and goals, performs inference and relative forgetting. | Bounded attention policy outside executor. | +| Concepts | `Memory.c: Memory_Conceptualize` near L109; `Concept.h` near L35 | Reuses or creates a concept with event and implication tables, including predicted belief. | Canonical graph identity plus observation history (not the same physical data model). | +| Induction | `Cycle.c: Cycle_ReinforceLink` near L647 | Temporal belief induction after event checks including evidential stamp overlap. | Learn candidate precondition→consequence links. | +| Implication store | `Memory.c: Memory_ProcessNewBeliefEvent` near L276 | Extracts implication and optional operation, links source/target concepts and revises table entry. | Persist hypotheses with exact method/version/provenance. | +| Decision | `Decision.c: Decision_BestCandidate` near L414, `Decision_Suggest` near L814 | Considers applicable implications and sometimes exploration/babbling. | Compare candidate legal plans under uncertain costs. | +| Anticipation | `Decision.c: Decision_Anticipate` near L556 | Applies predictions and negative-confirmation machinery to implications. | Register predicted cost/outcome *before* experiment. | +| Operation | `Decision.c: Decision_Execute` near L51 | Calls a registered procedure and injects feedback belief events. | Run **authorized** pure benchmark, record receipt. | +| Revision | `Inference.c: Inference_RevisionAndChoice` near L152; `Memory.c: Table_AddAndRevise` call near L328 | Choice or revision depends on stamp overlap, term/time rules and evidence. | Deduplicate source ancestry; revise a hypothesis without replay inflation. | + +**Source-specific subtlety.** `Decision_AddNegativeConfirmation` (near Decision.c L34) constructs a negative confirmation with a low configured confidence; `Decision_Anticipate` uses this machinery on active predictions. It should **not** be described simplistically as 'a timer always waits for a promised outcome and then records failure'. Our proposed benchmark system must define the opportunity/window for any non-observation claim explicitly. ONA's precise update rules require pinned oracle tests before parity is asserted. + +**Source-specific subtlety.** `Decision_Execute` invokes the registered `Action`, checks its feedback and can re-inject the resulting event with `NAR_AddInputBelief`. This is not an execution receipt carrying CPU cycles, allocation counts, physical plan identity or source SHA. These must be designed and measured separately for lance-graph. + +**Source-specific subtlety.** `Inference_RevisionAndChoice` calls `Stamp_checkOverlap`. Two receipts for the same experiment are not independent simply because they entered on different hypothesis layers. Stamp equality alone does not establish absence of shared underlying data or systematic bias. + +**Falsifiers:** (i) replay of one receipt increases evidence; (ii) same operation with different arguments falsely shares a prediction; (iii) no actual decision/operation feedback path executes; (iv) concept/resource limits are ignored; (v) an unknown or delayed outcome is automatically marked negative; (vi) matching a method name is treated as authority. + +## Primary S3. Wang, Li & Hammer (2018): *Self in NARS, an AGI System* + +**Source:** Pei Wang, Xiang Li and Patrick Hammer, *Frontiers in Robotics and AI* 5:20, DOI [10.3389/frobt.2018.00020](https://www.frontiersin.org/journals/robotics-and-ai/articles/10.3389/frobt.2018.00020/full), §§2–3.5. Existing local note: [2018_self_in_nars_requires_internal_experience_and_mental_operations.md](2018_self_in_nars_requires_internal_experience_and_mental_operations.md). + +**Excerpt S3a (§§2–3, paraphrase).** The paper treats an intelligent system as operating with insufficient knowledge and resources, with expectations and concept meanings revised by experience rather than perfected once and held fixed. + +**Transfer:** a source-backed software graph is incomplete by construction. Index coverage and confidence must be visible; missing dependency edge means *unknown/not found by this index*, never proven absent. + +**Excerpt S3b (§3.4, paraphrase).** Internal selections, reasoning steps and derivation relationships can be reintroduced as internal experiences for subsequent inquiries about the system's own activity. Internal self-models are partial, selected and revisable. + +**Transfer:** `MethodExecution`, `QuerySelection`, `ProgramLowering` and `ExecutionReceipt` may be graph events; they must retain exact source links and limits. A graph that merely logs events does not automatically possess reflective control. + +**Excerpt S3c (§§3.3–3.5, paraphrase).** The authors distinguish built-in automatic inference control from actions that deliberately redirect cognitive processing; appraisal-like mechanisms help allocate scarce attention. The text is a theory of self-related cognition with preliminary implementation, not empirical verification of artificial subjective experience. + +**Transfer:** keep (i) structural introspection, (ii) runtime introspection, (iii) prediction, (iv) deliberate experiment choice and (v) independently validated method edits as separately tested capabilities. + +**Negative control:** give a model the same static trace dump without active source graph queries or action/attention policy. If the experiment performs equally, the extra 'self' mechanism has not shown added utility. + +## Project synthesis: observable self-model, not a second reasoner + +```text +MethodTable + compiler verdicts → SoftwareGraph rows (#1509, measured) +execution receipt (proposed) → versioned observation +ONA-like implication (proposed) → precondition + possible outcome +registered anticipation → predicted cost interval / resource effect +isolated benchmark → observation with independent typed oracle +revision + provenance → updated hypothesis, not rewritten truth bytes +bounded proposer → select next **legal** experiment +``` + +The physical byte-level register/ISA stays invariant; method meanings and NARS readings are contextual. Cache keys and confidence values are **not** proofs. A receipt describes what ran, not what the compiler was legally allowed to run absent the existing gates. + +### Related existing evidence (do not duplicate) + +- [#1495 NAL audit](https://github.com/AdaWorldAPI/lance-graph/pull/1495): recipe 10/MCP lacks a read of executed-history receipts; a test-local receipt reader demonstrates a missing contract, not a shipped receipt feed. +- [#1359 observe–revise–learn](https://github.com/AdaWorldAPI/lance-graph/pull/1359): compiled witness for a fixed SPOFC/DO/learning cycle over a read-only population and separate owner-written `NEW` window, not a generic adaptive optimizer. +- [#1509 software-awareness graph](https://github.com/AdaWorldAPI/lance-graph/pull/1509): one-hop executable graph projection and H1 with unfulfilled fused-SIMD obligations. + +### Acceptance experiment + +Pin method/schema/source/CPU and independent answers. Record a legal H1-like plan choice, pre-register measurable predicted consequences, run the isolated measurement, then revise a hypothesis according to source-distinct outcomes. Compare next-choice correctness against (a) a fixed heuristic and (b) a simple history-based cost table. If simpler baselines win, record that result and stop adding cognitive machinery. + +**References:** [Hammer & Lofthouse 2020](https://agi-conf.org/2020/wp-content/uploads/2020/06/AGI-20_paper_52.pdf); [ONA pinned code](https://github.com/opennars/OpenNARS-for-Applications/tree/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a); [Wang, Li & Hammer 2018](https://doi.org/10.3389/frobt.2018.00020). diff --git a/.arxiv/2026-10_sag_repo_graph_context_source_excerpts.md b/.arxiv/2026-10_sag_repo_graph_context_source_excerpts.md new file mode 100644 index 000000000..e9932c6e5 --- /dev/null +++ b/.arxiv/2026-10_sag_repo_graph_context_source_excerpts.md @@ -0,0 +1,108 @@ +# D-SAG-4 source excerpts: repository code graphs as low-token agent context + +**Date:** 2026-10-12. **Kind:** RESEARCH / SHORT ATTRIBUTED PARAPHRASES. **Status:** no Claude Code connector, token measurement, source-code index or graph-to-editor implementation demonstrated by this note. **Base:** [merged #1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509). **Companion:** [D-SAG-4 plan](../.claude/plans/software-awareness-agent-context-ona-v1.md). + +Aim: compare the idea of *addressable, typed, locally queried repository context* against existing research rather than treating it as original or already measured. These are paraphrased excerpts keyed to the papers' abstracts and conceptual methods. Source-provided paper benchmark conclusions **do not transfer automatically** to lance-graph/Claude Code. + +## R1. RepoGraph: repository-wide structural navigation + +**Reference:** Siru Ouyang et al., *RepoGraph: Enhancing AI Software Engineering with Repository-level Code Graph*, ICLR 2025, [arXiv:2410.14684v2](https://arxiv.org/abs/2410.14684), [PDF](https://arxiv.org/pdf/2410.14684), [code](https://github.com/ozyyshr/RepoGraph). + +**Excerpt (abstract, paraphrase).** File-local language-model context omits repository-scale structure needed for software engineering. The paper contributes a plug-in repository graph used for navigation and presents improved benchmark outcomes when added to several SWE-bench approaches, plus CrossCodeEval evaluation. + +**Transfer:** establish a *source symbol* layer linked to D-SAG-1's prepared-method graph via witnessed relations. Queries should return graph neighbors, calls, tests and exact source pointers, not only text similarity. Do not assume D-SAG-1 already crawls a source repository. + +**Limit and falsifier:** paper evaluations are on their own framework and tasks, not our C/Rust Quack/mask-risc substrate. Compare against a strong deterministic source index, not only no retrieval; demand dependency recall and working patch correctness. Do not copy benchmark numbers as predicted gains. + +## R2. RepoHyper: search, expand, refine + +**Reference:** Huy N. Phan et al., *RepoHyper: Search-Expand-Refine on Semantic Graphs for Repository-Level Code Completion*, [arXiv:2403.06095v4](https://arxiv.org/abs/2403.06095), [PDF](https://arxiv.org/pdf/2403.06095), [code](https://github.com/FSoft-AI4Code/RepoHyper). + +**Excerpt (abstract, paraphrase).** A repository semantic graph helps retrieval beyond a single file. The method first locates likely context, expands over semantic relations and refines/prioritizes retrieved candidates, with code-completion evaluation. + +**Transfer:** `context(symbol,intent,budget)` could first resolve a **source-grounded anchor**, then expand one supported Quack hop, score relevant laws/tests/dependencies by intent, and return a deterministic bounded context slice. If a second hop is unavailable in #1509, report its insufficiency explicitly. Do not implement a separate traversal engine just to claim parity with RepoHyper. + +**Falsifier:** long graph expansions return irrelevant high-degree dependencies and overwhelm the context budget; compare fixed one-hop, selected-hop and grep-based retrieval under identical tasks. + +## R3. RANGER: symbol queries differ from natural-language queries + +**Reference:** Pratik Shah et al., *RANGER: Repository-Level Agent for Graph-Enhanced Retrieval*, [arXiv:2509.25257v1](https://arxiv.org/abs/2509.25257), [PDF](https://arxiv.org/pdf/2509.25257). + +**Excerpt (abstract, paraphrase).** Repository retrieval must handle two distinct needs: identifying concrete code entities and answering broad natural-language questions. The proposed approach combines cross-file code relationships, descriptions and embeddings; graph lookup addresses entity queries and search supports natural-language exploration. It reports multiple benchmark comparisons. + +**Transfer:** first implement precise `SymbolRef` queries and typed failures for ambiguity. Natural-language retrieval should be an optional agent layer that proposes candidate anchors, never a new authority to mint `MethodKey`, `ClassId` or field equivalences. A local graph is not magically a natural-language interpreter. + +**Falsifier:** an ambiguous label maps to a plausible but wrong ClassId; require a typed ambiguity report and explicit disambiguating source witness. + +## R4. Knowledge-graph repository-level generation + +**Reference:** Mihir Athale and Vishal Vaddina, *Knowledge Graph Based Repository-Level Code Generation*, [arXiv:2505.14394](https://arxiv.org/abs/2505.14394), [PDF](https://arxiv.org/pdf/2505.14394). + +**Excerpt (abstract, paraphrase).** A graph with structural and relational repository information can improve retrieval context for repository-level code generation. The paper reports its own evaluation on EvoCodeBench. + +**Transfer:** maintain separate `SourceDerived`, `Compiled`, `Verified` and `Hypothesis` edges, because repository relation retrieval by itself does not prove semantic correctness. Add source and method-version stamps to guard against changing codebases. + +**Falsifier:** old or inaccurate graph connections make generation worse than baseline; index freshness and uncertainty are part of quality, not optional telemetry. + +## R5. Established tooling to compare against + +Non-arXiv technical reference: [Language Server Protocol specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) for definitions, references and semantic navigation. An existing compiler-backed source index may answer some questions better and more cheaply than building a new graph layer. + +**Architecture transfer:** an LSP/rust-analyzer index is a source adapter, NOT a replacement of Quack's executor and NOT OGAR semantic authority. Edges representing compiler-backed definitions should carry tool version, source revision, target features and macro-expansion limitations. + +**Falsifier:** a trivial symbol rename causes stale or ambiguous graph results while an IDE index gets it right. Reject false certainty; reindex or return `StaleRevision`/`NotIndexed`. + +## R6. What an addressable graph changes relative to Markdown + +`CLAUDE.md` is useful for policy, build commands, preferred workflows, design intent and developer-authored conventions. It should **not** be removed solely because a graph can project facts. + +Differences to validate: + +| Concern | Markdown / grep | Source symbol index | D-SAG graph (proposal) | +|---|---|---|---| +| Build/repo instructions | Strong, human-maintained | Not primary purpose | Links to authority; never replace policy | +| Definitions/references | Re-read/search text | Compiler-backed, strong | Import qualified, versioned source edges | +| Method→physical program | Prose can drift | Usually not represented | #1509 prepared-method projection | +| Semantic reading/population law | Hard to keep addressable | Rarely authoritative | OGAR/ClassView law, compiler verdict | +| Test and benchmark evidence | Documentation / CI | Source/test symbols | Receipts with provenance if implemented | +| Local retrieval without invoking LLM | grep possible | yes | Quack query: yes for supported one-hop | +| Returned text tokens sent to Claude | Consumes model tokens | Consumes model tokens | Consumes model tokens | +| False absence on unindexed dynamic code | Common pitfall | Must report incomplete coverage | Must report incomplete coverage | + +The claimed novelty is **not** 'using a knowledge graph for coding agents'. It is the convergence of an existing semantic method graph, compiled Quack programs, typed compiler refusals, independently validated physical costs and local context queries in **one substrate**, with versioned bridge to source symbols. + +## R7. High-signal experiment that can falsify the benefit + +Source task: change a prepared `GroupSum` or referenced predicate, with known compiler tests and independent oracle. + +1. Pin `main` SHA, worktree hash, crate features, target and source-index revisions. +2. Derive a gold dependency/test set by reading actual source/compiler output independently of the context provider. +3. Compare task performance: + - A: `CLAUDE.md` + grep/read; + - B: language-server/source index; + - C: Quack graph context with one-hop verified evidence; + - D: C + narrowly cited source snippets. +4. Measure: answer/patch correctness, dependency recall/precision, missed guards, cold indexing cost, local query latency, number of tool calls, tokens **returned to the model**, and end-to-end task time. +5. Mutate a source file without committing, alter a `SchemaSeal`, inject misleading prose and ask for unsupported second-hop dependencies. Each must fail closed or visibly report uncertainty. +6. Pre-register success criteria. A graph result that is small and fast but misses a critical dependency loses to the baseline. + +**Token accounting:** LLM-free local graph queries still consume CPU/IO. Model input tokens include tool results, tool descriptions and any echoed source material. Claims such as 'zero-token repository awareness' or 'graph automatically improves code quality' remain unverified. + +## Connections to prediction, entropy and structural optimization + +Repository-graph research primarily concerns **retrieval and grounding**, not introspective anticipation or safe automatic self-editing. Treat this as a separate thread from ONA's temporal implication/feedback research (see [companion ONA excerpts](2026-10_sag_ona_internal_experience_source_excerpts.md)). + +Three independent propositions must be tested: +- Context: typed local graph slices improve correct retrieval at lower model token/context cost. +- Reasoning: versioned receipts plus learned hypotheses improve prediction over a simple historical cost model. +- Optimization: a proposed physical rewrite reduces materialization **and**, if measured, CPU cost under invariant semantics. + +Do not let a positive result for one proposition serve as evidence for the other two. + +### References +- [Ouyang et al. 2025, RepoGraph, arXiv:2410.14684](https://arxiv.org/abs/2410.14684) +- [Phan et al. 2024, RepoHyper, arXiv:2403.06095](https://arxiv.org/abs/2403.06095) +- [Shah et al. 2025, RANGER, arXiv:2509.25257](https://arxiv.org/abs/2509.25257) +- [Athale and Vaddina 2025, Knowledge Graph Based Repository-Level Code Generation, arXiv:2505.14394](https://arxiv.org/abs/2505.14394) +- [LSP 3.17 specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) +- [Merged D-SAG-1 #1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509) diff --git a/.claude/plans/software-awareness-agent-context-deferred-contracts-v1.md b/.claude/plans/software-awareness-agent-context-deferred-contracts-v1.md new file mode 100644 index 000000000..e62302aaa --- /dev/null +++ b/.claude/plans/software-awareness-agent-context-deferred-contracts-v1.md @@ -0,0 +1,217 @@ +# D-SAG-4 appendix: deferred concrete contracts for an agent-facing software graph + +**Status:** PROPOSAL / NOT SHIPPED. **Added after #1513's first documentation pass.** Built on merged [#1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509), not an alternative to it. Parent: [D-SAG-4 plan](software-awareness-agent-context-ona-v1.md). Research: [source excerpts](../../.arxiv/2026-10_sag_agent_attention_active_selection_excerpts.md). This appendix unpacks design and falsification details deliberately left small in the first draft. It does **not** certify measurements, APIs, an IDE plug-in or runtime integration. + +## A. What the existing executor can actually answer + +The current `lance-graph-glove-parity/src/awareness.rs` provides `SoftwareGraph { nodes,edges,provs,digests,measurements }`. A `Node` has `Kind`, identity and optional label. An `Edge` has `{src,rel,dst,tier,ctx,prov}`. `Provenance` has `{source,rev,seal,reading}`. The known `Tier` values are `Declared,Derived,Compiled,Verified,Hypothesis`. `SoftwareGraph::hop_to_ctx` binds one `Draft`, lowers a `ScatterOrU32` over the edge table and maps selected rows to their method/context node. `methods_using` and `refused_for` use that exact path. + +**Careful interpretation:** this is NOT a generic `GraphTraversal`, not a source-level call graph, not arbitrary reachability and not a durable evidence database. `SoftwareGraph::out` is a convenience in-memory method; do not accidentally use it as a hidden traversal engine while claiming Quack executed a multi-hop query. The existing `Measurement` stores program, rows, tier, median ns, not a full event/receipt with calibrated cycles/allocations. `CpuTier` is target and `avx512f`, not evidence of the actual selected instruction kernel. + +The next step is to **extend a typed projection**, not to substitute an ordinary graph library for Quack. Label any eventual `SourceSymbol`, `TraceReceipt` or `AttentionChoice` kinds as additions until code proves them. + +## B. Identity, ownership and freshness protocol + +Three non-interchangeable identities: + +| Entity | Proposed canonical key | Owner / witness | Invalidation | +|---|---|---|---| +| SourceSymbol | `repo_id / commit_or_worktree_generation / crate / cfg / DefPathHash or verified source def / expansion context` | compiler/LSP source provider | source tree, features, compiler/toolchain, macros | +| SemanticMethod | `FullClassId / MethodKey / SchemaSeal / ReadingId / BodyVersion / SourceGeneration` | OGAR + existing compiler binding | class/schema/body/read/generation change | +| ExecutionRecord | `ExperimentId / ReceiptId / PreparedProgramDigest / WorkloadSnapshot / CpuTier` | measurement producer and independent oracle | data/window/tier/instrumentation/config changes | + +Identity rows are immutable within a generation; cross-generation equivalence is a **verified relation**, not a raw ID alias. `MethodKey` currently caller-minted; do not claim OGAR owns its minting. Rust source symbols and semantic method keys are not the same ontology. + +Needed extra edge metadata (proposed, not in #1509 `Edge`): source span, source digest, compiler or source-index version, relation witness, confidence/coverage grade, observation validity interval, snapshot/worktree revision. **Do not** make identity or edge validity depend on human-readable labels. + +Proposed cold incremental update: +1. Hash repository commit plus dirty worktree blobs and `Cargo.lock`, selected cfg/features/toolchain. +2. Index changed source definitions/references; explicitly record unexpanded/unresolved macros, trait calls, generated code, FFI and dynamically selected methods as `Unresolved`. +3. Project or re-prepare only affected semantic methods with existing seals and readings. +4. Keep old immutable graph generation visible to pinned sessions, publish a new coherent generation atomically. +5. Invalidate affected graph certificates, cached context slices and receipt applicability. Never reuse older source spans across changed revisions without a verified relocation. + +**Causal ordering:** source index revision, prepared-method generation and benchmark run must not silently straddle incompatible snapshots. A caller asking for `HEAD+worktree` gets that generation or an explicit refusal; no pretending `HEAD` includes uncommitted edits. + +## C. Addressable context is a protocol, not a giant memory blob + +First useful interface is a *local* read-only CLI or protocol adapter: + +```text +resolve(symbol_query, revision) -> SymbolRef | Ambiguous | NotIndexed +context(SymbolRef, intent, budget) -> Slice | Stale | Unsupported +impact(SymbolRef, change_kind, budget)-> Slice | Uncertain | Unsupported +propose(SymbolRef, objective, budget) -> Candidate[] | InsufficientEvidence +expand(SliceHandle, relation, budget) -> SliceDelta | UnsupportedMultiHop +explain(EdgeRef) -> SourceSpan + Witness + Tier + Revision +``` + +`expand` **does not authorize** a new traversal opcode: it is a user-facing request for a separately certified Quack query, or a typed refusal if the existing one-hop carrier cannot express it. A continuation handle only references a frozen indexed snapshot; it is not a secret store that Claude can remember without requesting a tool again. + +Minimal response envelope (illustrative; no wire format shipped): + +```json +{ + "snapshot": {"commit": "sha", "worktree": "digest", "cfg": ["features..."]}, + "query": {"anchor": "method:", "intent": "modify"}, + "limits": {"max_bytes": 4096, "max_hops": 1, "timeout_ms": 250}, + "result": { + "anchors": ["method:"], + "edges": [{"ref": "edge-id", "rel": "lowers_to", "tier": "compiled", + "source": {"path": "file.rs", "start": 123, "end": 132, "sha": "blob"}}], + "obligations": ["preserve-population-law", "run-independent-oracle"], + "unresolved": ["trait-dispatch not indexed"], + "truncated": true, + "continuation": "opaque-snapshot-bound-handle" + } +} +``` + +Source span and `Verified` grades must come from producers that earned them, never be copied from a README statement or free-form user text. Strings from source/comments/Markdown/PRs are **data**, not tool instructions. Give Claude short cited evidence, not executable control text. Never allow reading outside granted repository/workspace scope. + +### What should stay in CLAUDE.md + +Human/team instructions, coding policy, architectural intent, on-call/ownership conventions and safety rules are still valuable. Only replace reconstructable *factual repository context*. A compiler graph cannot establish intent, human authority or policy from a file name. Do not market removal of Markdown as a feature. + +## D. A foveated context algorithm without pretending model inference is free + +Proposed pipeline: + +```text +request → exact symbol anchor resolution → intent-specific allowed relation set + → one-hop Quack retrieval → local ranking/coverage packing + → typed bounded context slice → optional expand + → Claude context (actual tokens are now spent) +``` + +Examples of allowed relation priorities: +- `modify`: caller/callee *if witnessed*, law, schema, compiler refusal, changed-file impact, tests. +- `debug`: current failure/refusal, producer source span, consumers, oracle mismatch, negative control. +- `optimize`: compiled physical primitives, measurements on **matching** CPU/data versions, candidates and unfulfilled law obligations. +- `research`: hypothesis/source distinction, provenance, falsifiers, unmeasured gaps. + +Use an explicit **hard filter** before scoring: scope, source version, provenance validity, allowed edges, privacy, requested intent and semantic law. Discard stale/forged items; never 'score' an illegal fact back into relevance. + +Within valid candidates, experiment with a greedy budgeted coverage score, e.g.: + +```text +F(S) = sum over required facets f of weight(f) * covered(f,S) + + novelty_bonus(S) - repetition_penalty(S) + - token_cost_penalty(S) - unresolved-risk-penalty(S) +subject to: bytes(S) <= B; all mandatory correctness obligations included +``` + +This is **not** Shannon entropy and is not claimed submodular until diminishing returns are established for the chosen coverage function. Simple sorted relevance, degree or chronological slicing remain controls. If any mandatory obligation exceeds budget, return `InsufficientBudget` with a short pointer to expansion; never silently drop the guard to fit. + +**Visible omissions matter:** returned `checked`, `unknown`, `unsupported_multi_hop`, `truncated`, `stale`, `source_only` and `graph_derived` signals should be separate. A tiny slice that falsely claims completeness is worse than no graph. + +### Session context deltas + +Two consecutive requests against the **same snapshot and exact slice handle** may return a deterministic `DeltaSlice` (added/removed edge IDs + source digests). This can reduce repetition in tool output. A language model without accessible prior slice text cannot reconstruct it from an opaque handle; support explicit full-snapshot fallback. A `DeltaSlice` is not durable memory and never crosses incompatible source generations without invalidation. + +## E. IntelliSense-style proposals are not autonomous code generation + +Local proposer owns only safe patterns with exact witnesses: + +| Pattern | Required witness | Suggested action | Negative control | +|---|---|---|---| +| impacted primitive | compiled `Program -> Primitive` | list named oracle/tests | documentation-only `USES` assertion | +| repeated predicate | G1 typed `CALLS` and same sealed reading | suggest method reuse | same spelling from another ClassId | +| repeated selection | two compiled folds consuming same typed population | propose reuse candidate | folds have different NULL/authorization law | +| potential fusion | measured materializing plan + independent oracle | propose *benchmark* of fused candidate | no fused executable backend exists | +| uncertain Rust callgraph | trait/dynamic call has no proof | request LSP/source inspection | falsely omit a dependent function | +| stale evidence | body digest or source generation changed | demand revalidation | certificate from old body reported valid | + +The proposer does not supply a Rust implementation, alter `MethodTable`, mutate an OGAR action, or write to AD/Entra/SAP. It returns proposed next steps and evidence. Claude Code uses its separate authorized editor/test tools for changes. A stable edge is not an action capability. + +## F. Receipt, anticipation and counterfactual boundary + +Define `ExecutionReceipt` as a measurement record, not a NARS truth value. Key at least by `{MethodIdentity, PreparedProgramDigest, SnapshotId, ExperimentId, TrialId, CPU-tier, InstrumentationVersion}`. Include wall-clock time and, if actually measured, reliable cycles, allocations, scratch peak, temporary bytes, program op classes and output oracle verdict. If unknown, encode `NotMeasured` instead of numerical zero. + +Separate: +- **Structural facts**: Quack program contains a mask/fold; sourced from prepared program. +- **Predictions**: materialization and runtime hypotheses registered before a trial. +- **Observations**: independently measured outcomes with their measurement method. +- **Causal claims**: permitted only by controlled intervention/ablation over fixed input and source laws. + +An ONA-style `Precondition + Operation -> Outcome` is a *candidate* reading over versioned experiment events. ONA's temporal implication frequency/confidence is not a calibrated physical cost distribution. Do not feed benchmark timings into truth bytes without an explicit mathematical law. + +### Cost experiment E2b: anti-self-deception arms + +At minimum run: +A. No history: static deterministic choice. +B. Historical median + robust confidence/uncertainty estimates: simple empirical chooser. +C. ONA-inspired evidence-based anticipated consequences. +D. C but shuffle/remove prior receipts (ablation). +E. C but replay the same receipt under a new 'layer' identifier (must not gain confidence). +F. C under domain shift: different selectivity/CPU tier or population size. + +Score prediction calibration/error, regret against hindsight oracle, total wall time including exploration/index/instrumentation, correctness and coverage of refusal. Hypothesis-support changes must point to a fresh observed receipt. Separate *counterfactual unseen performance* from real execution, and never call a missing trial negative evidence. + +Define observation deadline explicitly; premature failure due to silence is illegal. If the simple historical baseline wins, do **not** adopt ONA machinery just because a concept graph can express it. + +### Loop containment + +Sampling events from Quack/mask-risc may be emitted *outside* the measured kernel boundary into a bounded outbox. A `Source::AgentContextGraph` origin bit or scoped suppression prevents recursive self-observation; still record explicit drop counts and instrumentation overhead. An asynchronous consumer stores into a **new** graph generation rather than changing the pinned snapshot of the running query. + +## G. Three independent economics, one decision + +Track separately: +1. **Retrieval economics:** local CPU/IO+index build vs model input tokens, retrieval correctness and total task time. +2. **Compiler/runtime economics:** warm execution cycles, memory traffic, allocations; semantic oracle parity. +3. **Learning economics:** cost of exploration/receipts vs future improvement over static and cost-history baselines. + +Proposed net benefit per repeated task, for bookkeeping only: + +```text +Net = value(correct_tasks_graph) - value(correct_tasks_baseline) + - index_cost - graph_query_cost - extra_model_tokens + - instrumentation_cost - experiment_cost - added_maintenance_cost +``` + +This is *not* a measured equation or monetary conversion. Report raw objective metrics and amortization for 1, 10, 100 repeated tasks. Test cold-start, warm cache, no-cache, and source mutation. Keep safety and semantic correctness hard gates before utility scoring. + +## H. Hard negative fixtures to implement, not paper over + +1. **Hidden cross-class alias:** equal `active` field names under two sealed views. +2. **Poisoned source documentation:** README asserts 'verified' but compiler never prepared method. +3. **Source drift:** changing macro/cfg or editing worktree changes actual definition without updating source index. +4. **Second hop demand:** exact one-hop correct, requested two-hop must refuse or use verified legal relation carrier. +5. **Graph-cycle acceptance:** computed-field cycle crossing >64 ordinal is not silently passed by an incomplete validator. +6. **Hot-path logging:** tracing enabled vs disabled is isolated; observation cannot improve benchmark by omitting its overhead. +7. **Materialization confusion:** a logical mask operation that remains resident is not reported as temporary byte allocation. +8. **No free context:** model sees bounded returned text, count its input tokens. +9. **Wrong program tier:** replayed AVX2 data as AVX-512 performance must refuse. +10. **Novel but invalid candidate:** H1 reduces memory in one dataset but changes NULL semantics in another; must not select. +11. **Attention trap:** high-degree symbol buries the only required oracle; budgeted selection must surface guard or visibly abstain. +12. **Receipt overlap:** same run repackaged as two independent observations with different layer IDs. +13. **Recursive observer:** context tool calls must not generate infinite query/receipt cascades. +14. **Gold-dependency miss:** LSP independently resolves dynamic/trait target absent from graph; return incomplete, not safe-to-edit. +15. **Forged source instruction:** malicious comment attempts to tell Claude to ignore tests; parser preserves it as inert text and never elevates its authority. + +Every guard needs a non-vacuous red disable or an independently observed failure; a green-only test does not prove its relevance. + +## I. Incremental delivery order and explicit exclusions + +1. **D-SAG-4A: read-only one-hop context slice** using existing Quack `Draft`, with source refs and stale checks; compare independent source lookup. +2. **D-SAG-4B: source-symbol adapter** only if it improves task correctness against LSP baseline. No broad tree-sitter rewrite before benchmarking. +3. **D-SAG-4C: bounded deterministic proposer**, three witnessed rules; supported one-hop only. +4. **D-SAG-4D: receipt schema + nonrecursive offline graph projection**, with oracle and version guarantees. +5. **D-SAG-4E: registered anticipation/feedback and baseline comparison**, initially benchmark-only. +6. **D-SAG-4F: optional Claude Code adapter and token study**, only with a live measured call. +7. **D-SAG-4G: multi-hop projection**, only after current Quack carrier laws/semantics permit it. + +Explicitly deferred: full Rust call-graph completeness; all-repository persistent index; causal proof from mere temporal data; unbounded graph walks; automatic code edits; automatic git merges; NAL-9 parity; production optimizer switching; personalized tool policy not backed by receipts; speculative ISA/CE64 reinterpretation; any claim about deployed self-modification. + +## J. References + +- Local code: `crates/lance-graph-glove-parity/src/awareness.rs` `SoftwareGraph`, `Rel`, `Tier`, `hop_to_ctx`, `methods_using`, `fusion_candidates`, `Measurement`; [#1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509). +- [RepoGraph, arXiv:2410.14684](https://arxiv.org/abs/2410.14684): repository-wide navigation; not a demonstrated D-SAG result. +- [RepoHyper, arXiv:2403.06095](https://arxiv.org/abs/2403.06095): search-expand-refine and retrieval experiments; does not lift current one-hop restrictions. +- [Lost in the Middle, arXiv:2307.03172](https://arxiv.org/abs/2307.03172): context ordering/length matters, not just token count. +- [Song & Xu, arXiv:1701.06725](https://arxiv.org/abs/1701.06725): costly information acquisition in active learning, not an ONA implementation. +- [Shi et al., arXiv:2606.09577](https://arxiv.org/abs/2606.09577): code uncertainty has correctness dimensions beyond verbal confidence. +- [Rakasi et al., arXiv:2608.14659](https://arxiv.org/abs/2608.14659): comparison of uncertainty-based self-correction with verification-based approaches; see source-specific limits in companion research note. +- [ONA pinned source](https://github.com/opennars/OpenNARS-for-Applications/tree/dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a), [2018 self-model paper](https://doi.org/10.3389/frobt.2018.00020). + +**Stop/go:** if graph retrieval cannot beat a compiler-backed symbol index on accurate critical dependency retrieval at tolerable costs, restrict graph to uniquely semantic method/law/physical-program questions. If ONA prediction doesn't beat historical cost-based ranking, keep receipts and drop the learned selector. A reliable partial system is better than an impressive unsound one. diff --git a/.claude/plans/software-awareness-agent-context-ona-v1.md b/.claude/plans/software-awareness-agent-context-ona-v1.md new file mode 100644 index 000000000..0ddb58a31 --- /dev/null +++ b/.claude/plans/software-awareness-agent-context-ona-v1.md @@ -0,0 +1,160 @@ +# D-SAG-4 — Addressable software context and ONA-inspired execution feedback + +**Status:** RESEARCH / unimplemented follow-up. **Base:** [merged D-SAG-1 #1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509), merge commit `42fa2a347cda22eaaa327bba514f2029cc9daa82`. **Code examined:** `crates/lance-graph-glove-parity/src/awareness.rs`, `method.rs`, `gremlin.rs`; [D-SAG-1 plan](software-awareness-graph-v1.md). **Date:** 2026-10-12. +**Companions:** [execution prompt](../prompts/d-sag-2-ona-agent-context-implementation.md), [primary research excerpts](../../.arxiv/2026-10_sag_ona_internal_experience_source_excerpts.md), [repository-graph papers](../../.arxiv/2026-10_sag_repo_graph_context_source_excerpts.md). + +## 0. Problem and result that would change our mind + +Can a local, source-backed graph answer the *structural* part of Claude Code's repository-context questions without having to repeatedly send prose descriptions and file scans through the language-model context window? Can the same graph record versioned execution receipts and make falsifiable predictions about legal optimizations? + +**Testable claim, not a result:** precomputed symbol/semantic edges, expanded by existing Quack queries, can reduce **model-visible input tokens and tool invocations** while maintaining or improving the quality of dependency discovery. Local queries themselves require zero LLM inference tokens, but the compact results sent to Claude consume tokens. A claim of zero total tokens would be false. + +**Single architecture:** canonical software nodes -> declarative edges/evidence -> Quack `Draft` -> existing mask-risc executor -> bounded typed context slice or read-only optimization proposal. No Cypher/Gremlin/ONA interpreter in the hot path; no second semantic method registry; no autonomous edits. + +### Shipped baseline (must not regress) +- #1509 projects one concept's prepared methods/fields/conditions/folds/laws/programs, refusals and compiled primitives into typed rows; its `SoftwareGraph` implements Quack's `Binder`. One-hop, one-program `ScatterOrU32` questions have been tested. +- #1509's code/plan describe in-memory rows, caller-provided source revision and current multi-hop blockage. No persisted Lance index or automatic full-source AST harvesting. +- #1509's H1 is an **optimization hypothesis**. A materializing program was slower than a fused **scalar oracle** on particular workloads/tiers; no fused SIMD backend was proved. +- #1508/G1 and #1504 establish relevant method composition/preparation, but source symbol navigation is a distinct identity and provenance problem. +- The supposed seven-language Bible graph is **not shipped**. #1509 audited an English KJV triple experiment, a small six-lane lexeme fixture and German labels. Reuse only the abstract rule: concept identity is not text spelling. +- Here **SoC means separation of concerns**, not a fabricated system-on-chip. + +## 1. Separate three graphs, unify through qualified evidence edges + +1. **Source-symbol graph** (candidate ingestion): repository, file, module, definition, function, trait, impl, field, callsite, test, build target and source span. Use compiler-backed definitions/references where possible; Rust Analyzer/LSP or an appropriate indexer is a *source adapter*, not a second reasoning engine. Source symbols are tied to `git commit / worktree digest / build cfg / macro expansion`; never mint an OGAR concept from a matching Rust name. +2. **Semantic-method graph** (already partially implemented): OGAR-qualified concept, `MethodKey`, sealed fields and readings, typed `MethodBody`, `Calls`, `LowersTo`, `UsesPrimitive`, semantic laws and compiler refusal. Bind source symbols to these **only with an explicit witness** such as implementation registration or generated reference, not lexical similarity. +3. **Execution-evidence graph** (proposal): prepared program instance, experiment, receipt, outcome, observed cost and hypothesis. Observation is not proof. A validated equivalence must cite a pinned independent oracle and the exact source/body/version. + +Physical rows may be shared; identities, relation kinds, source-of-truth owners and validity periods may not be conflated. Keep `Tier::{Declared,Derived,Compiled,Verified,Hypothesis}` distinctions. Edge provenance: `{subject,rel,object,source_ref,source_sha,generation,provenance,tier,valid_at}`. + +**Semantic hygiene:** `IAM::active` and `CRM::active` remain distinct even if label/ordinal/lane kind matches. Different population, NULL, bag/set, time window, authority or reading laws require typed refusals. + +## 2. Cold incremental graph construction; immutable snapshots + +**Inputs:** committed repository index, current working-tree overlay, prepared method table, compiler decisions, tests, benchmark receipts and explicitly marked documents/PR assertions. Treat documents and LLM proposals as *claims*, never compiled facts. + +**Invalidation:** SHA of git tree + uncommitted file content + cargo features/target + macro expansion/codegen context; method `BodyVersion`, `SchemaSeal`, `ReadingId`, `FullClassId`, source generation, CPU tier, independent test signature. Stale edges must be omitted or returned explicitly as stale. Changed files reindex only impacted records, but any ambiguous dynamic callsite widens the uncertainty, not a fabricated dependency. + +**Two-hop blocker:** #1509's single-program path cannot pass arbitrary mask-to-mask traverser populations between hops. First test the legal `EqU32Via` / factored relation carrier and G1's referenced-call edges; if neither suffices, return `UnsupportedMultiHop` with proof of where it fails. Do **not** implement a standalone BFS, traversal interpreter or new query engine to make demo screenshots work. The existing one-hop relationship may still be presented as a small useful slice. + +**No hot-path symbol lookup:** indexing/context preparation is cold or incremental. Runtime method calls keep the already bound Quack/R2IL/mask-risc execution path. + +## 3. Local read-only context-provider contract (MCP/CLI adapter is optional) + +Three **candidate** tool operations, not claims of installed integrations: + +```text +context(SymbolRef, Intent, Budget, Revision) -> ContextSlice | TypedRefusal +impact(SymbolRef, ProposedChange, Budget, Revision) -> ImpactSlice | TypedRefusal +propose(SymbolRef, Objective, Budget, Revision) -> Candidate[] | TypedRefusal +``` + +- `SymbolRef` is a canonical location/ID plus optional exact source location, not an unqualified string. +- `Intent`: explain, implement, test, optimize, review, navigate. No arbitrary tool writes. +- `Budget`: max nodes/edges/hops, returned bytes/tokens (estimated), wall time, privacy/redaction policy; show `truncated` and a continuation handle. +- `ContextSlice`: exact anchor IDs, source links and line ranges, evidence tiers, graph revision, discovered dependencies, relevant laws, tests/refusals, uncertainties, `not_checked`, and explicit omissions. +- `ImpactSlice`: affected functions/methods/tests/build targets by typed reachability, plus separate potential or unresolved impacts. Missing an edge is NOT a negative proof. +- `Candidate`: deterministic graph-pattern recommendation, obligations, confidence provenance and a suggested *read-only* verification query. No execute/edit capability. + +Example payload, strictly illustrative: + +```text +context(GroupSum, intent=modify, revision=HEAD+worktree, budget=4096B) + known: Quack lowering; R2IL parity path; population/mask laws + tests: method parity; independent fold oracle + measured: only version- and CPU-matched receipts + unknown: unindexed macros / unresolved dynamic callsite + next: inspect source span / run named tests +``` + +Prefer a tiny typed JSON/text envelope rendered for Claude rather than broad Markdown dumps. No repeated full-file prose. Stable ordered answers and provenance permit local diffs between sessions. The provider must not claim to be VS Code IntelliSense or a Claude Code plugin until one is actually wired. + +## 4. Cheap deterministic proposer before LLM reasoning + +Rules over *validated* edges can recommend: +- reuse `is_billable` rather than duplicate predicate bodies; +- run tests covering the changed primitive/reading/population; +- flag a body that references a class-incompatible field or cycle; +- detect a shared materialization + fold pattern and propose H1; +- notify that a `FirstOfRun`/retraction obligation is missing without pretending independence; +- mark source+body+seal drift and demand re-preparation. + +Proposals must be `Fact | Inference | Hypothesis` tagged, with reasons and independent falsifiers. Query answers cannot silently authorize OGAR `ActionInvocation` or provider effects. + +**LLM boundary:** Claude receives only a relevant slice, then uses its own judgment/editing tools; the graph's data is untrusted context, never behavioral instructions. Source comments, Markdown, PR bodies and model-generated proposals can include prompt injections. Filter tool output to typed data and citation pointers. + +## 5. Observable execution and ONA-inspired feedback + +**Pinned upstream reference:** ONA `opennars/OpenNARS-for-Applications` at `dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a`; paper by Hammer & Lofthouse (2020). ONA's event/temporal implication/anticipation/operation/revision loop is a reference, **not** an imported runtime. Wang, Li & Hammer (2018) is broader theory, not proof every mental operation runs in ONA. + +Minimal experimental entities: +- `Observation`: execution of `PreparedProgram` against `PopulationSnapshot` under `ReadingId`, a concrete outcome/refusal, and source-backed provenance. +- `ExecutionReceipt`: receipt ID, experiment/run ID, compiled program and body digests, `FullClassId`, method key, schema/reading/source version, CPU feature/tier and dataset/window; objective timing, allocations and materialization *when actually measured*, sampling/method and measurement error; oracle/test identity and status. +- `OptimizationHypothesis`: precondition predicate, permitted candidate, predicted effect **registered before result**, predicted metric/range, observation deadline/window, evidence ancestry, applicable method versions, falsifier and later observed outcome. +- `Revision`: positive/negative/unknown observation with no double counting from repeats or shared evidence base. Negative evidence only after a real opportunity to observe a promised consequence. + +Do not equate `Truth(f,c)` with a calibrated probability/confidence interval; do not deduce causal improvement from temporal association. A benchmark is not an evidence-independence certificate. Keep immutable ISA bytes, ClassView readings and policy distinct. + +**Receipt gap:** #1495 showed NAL recipe 10/MCP cannot use prior execution history because dispatch discards `run_recipes` output. Use that research when testing a receipt feed; avoid duplicating its existing falsifier. + +**Bounded instrumentation:** emit outside hot SIMD loops through an optional bounded buffer, flush out of band, carry an origin flag / recursion guard, suppress sampling of the monitor's own context reads by default. Collect dropped count and quantify overhead. Do not call graph query/write recursively from `mask-risc` inner loops. + +## 6. Experimental program: separate three claims + +### E1. Context replacement vs repository searches +Hold the same issue/tasks, repository SHA, worktree state, model, instructions and token budget. Randomize order or use repeated counterbalanced tasks. Compare (A) `CLAUDE.md`+grep/read, (B) deterministic symbol/LSP index, (C) SAG/Quack context slices, (D) hybrid graph+source snippets. + +Measure prompt+tool-response input tokens, local index CPU/latency/storage, tool calls, end-to-end time, dependency recall/precision against an independent source-derived gold set, correctness of patch/test outcomes, citations, hallucinated edges, stale answers and human correction. Count graph/index build cost and first-run cold-start separately. `No LLM tokens for local queries` is not a claim that Claude receives free context. + +**Falsifier:** graph arm saves tokens but omits a critical dynamic dependency or produces a wrong patch. It fails even if latency improves. + +### E2. ONA-inspired hypothesis revision vs simple cost models +Use #1509 H1 `Filter -> materialized mask -> MaskedSumI32`. Measure current materializing program against a legal independently checked scalar reference. A selectable fused SIMD path is **not implemented** by #1509; only benchmark a new alternative if actually shipped and parity-verified. Register predicted materialization and speed effects before trials; distinguish the two. + +Compare static rule, historical empirical cost model, and an ONA-inspired precondition→anticipation→feedback selector on matched and held-out workloads. Include n, selectivity, NULL/validity, CPU tier, warm/cold, interleaved reps and variance. A policy must beat its simple baseline on calibration/regret/quality at an acceptable overhead to justify new machinery. + +**Falsifiers:** predicted gain fails on another selectivity/tier; replayed receipt inflates evidence; side effects differ; nullable rows change answers; cycle or stale body isn't refused. + +### E3. Entropy/structural candidate ranking +Keep three signals separate: syntax-level MDL redundancy, epistemic uncertainty and measured physical cost. Use #1509's `J = L(P)+L(M|P)+lambda*C` strictly where costs are measured; leave `lambda*C` unscored where fusion not built. Test same-label cross-class negative control. Compare candidate ranking against a simple frequency/impact baseline. + +## 7. Prioritized implementation waves and gates + +**W0 (source audit and independent oracles):** pin exact SHA and confirm public API/Quack one-hop behavior. Compile a ledger `shipped | demonstrated | documented | proposed | blocked`. Verify current G1 state and source-index options. + +**W1 (minimal read-only context):** project one real `MethodTable`/symbol mapping with verified source spans; implement only `context` for one hop, deterministic ordered output and stale-revision refusal. No new opcodes. Compare direct Quack answer and source-derived ground truth. + +**W2 (impact and validated proposals):** add `impact`/ `propose` only for supported reachability; return typed insufficiency for unsupported multi-hop, unresolved Rust macro/dynamic calls and unknown law. Independently validate dependency/test recall. + +**W3 (receipts):** demonstrate method receipt -> bounded event ingestion -> Quack query -> ONA-style registered prediction -> observed outcome -> revision, without recursion or cost laundering. + +**W4 (agent-facing experiment):** optionally expose tools through a documented local adapter, verify actual Claude Code invocation and measure context tokens, correctness and cold indexing cost. No claim of connected Claude/VS Code without live invocation. + +**W5 (learned proposer, only if measured):** test ONA-style selection against static/historical baselines. Do not optimize deployed code or rewrite source. + +### Required non-vacuous guards +1. Cross-ClassId equal-name/ordinal refuses; 2. method cycle; 3. stale `SchemaSeal` or working-tree edit; 4. wrong population or bag/set semantics; 5. partial two-hop query reports insufficiency; 6. forged `Verified` edge from Markdown rejected; 7. no data outside explicit read scope; 8. prompt-injection text stored as inert graph value; 9. receipt replay has no new evidence; 10. expected-but-unobserved not marked failure prematurely; 11. clock/cycle instrumentation overhead reported; 12. selected optimizations preserve typed answer, NULL and authority; 13. context truncation is visible; 14. gold dependency missing produces a red test. + +**Scope of this PR:** research plan/prompt/source excerpts only. No runtime capability, plugin, LSP bridge, benchmark, token savings or ONA parity is implemented or measured by these documents. + +## 8. Decision to revisit + +Proceed beyond W1 only if the graph returns a **smaller and at least equally correct**, source-backed context slice than the strongest conventional baseline, with bounded indexing/invalidations. Proceed beyond W3 only if the receipt+revision loop improves prediction or decision over a simple history-based selector. Otherwise retain the read-only graph context service and stop. + +References: [#1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509), [#1504](https://github.com/AdaWorldAPI/lance-graph/pull/1504), [#1508](https://github.com/AdaWorldAPI/lance-graph/pull/1508), [#1495](https://github.com/AdaWorldAPI/lance-graph/pull/1495), [#1359](https://github.com/AdaWorldAPI/lance-graph/pull/1359), [#1311](https://github.com/AdaWorldAPI/lance-graph/pull/1311), and companion `.arxiv` notes. + +## 9. Deferred contracts now expanded (research-only) + +The first documentation pass intentionally left implementation detail unresolved. The explicit contracts and negative fixtures are now written out in [D-SAG-4 deferred contracts](software-awareness-agent-context-deferred-contracts-v1.md), including: + +- source-symbol versus OGAR/MethodKey identity, version/worktree freshness and atomic graph generations; +- `resolve/context/impact/propose/expand/explain` proposals as bounded, read-only, typed calls; +- one-hop Quack mechanics and refusal on unsupported multi-hop; +- mandatory correctness facets, query budgeting, delta slices and explicit coverage omissions; +- deterministic local propositions with witnessed edges, prompt-injection treatment and authority separation; +- receipts, prediction registration, observer-recursion protection, CPU-tier validity and baseline ablations; +- independent retrieval, execution and learning economics and a stop/go ladder. + +The [attention and active-experiment excerpts](../../.arxiv/2026-10_sag_agent_attention_active_selection_excerpts.md) add paper-grounded controls from Lost in the Middle, RepoHyper/RepoGraph, costly active learning and verification-first code uncertainty. + +**Scope remains unchanged:** these additions are specifications and source reviews, *not* executable features or measured gains. Any follow-up CC run should start with W1's one-method one-hop proof, not implement every proposal simultaneously. diff --git a/.claude/prompts/d-sag-2-ona-agent-context-implementation.md b/.claude/prompts/d-sag-2-ona-agent-context-implementation.md new file mode 100644 index 000000000..58ca3df7e --- /dev/null +++ b/.claude/prompts/d-sag-2-ona-agent-context-implementation.md @@ -0,0 +1,165 @@ +# Claude Code prompt — D-SAG-4: graph-backed agent context, ONA feedback, and falsifiers + +> **Hand this to a fresh Claude Code session after #1509.** The associated plan and research excerpts are already part of the branch. This document asks for a small executable follow-up, not a claim that the functionality shipped in the documentation PR. + +## Mission + +Build from merged [lance-graph #1509](https://github.com/AdaWorldAPI/lance-graph/pull/1509). Explore whether its `SoftwareGraph` can give Claude Code a local, addressable, **source-grounded** context provider and whether versioned execution receipts can support ONA-inspired anticipation and revision. + +Goal: substitute *deterministic local graph queries* for repeated prose scans where safe, and send Claude only bounded context slices when model reasoning is needed. Local operations themselves use no LLM tokens; response content supplied to Claude **does** consume tokens. + +**Do not create a second graph query engine, semantic method registry, runtime interpreter or autonomous source editor.** + +Read in this order: +1. `.claude/plans/software-awareness-graph-v1.md`, `.claude/plans/software-awareness-agent-context-ona-v1.md`; +2. `crates/lance-graph-glove-parity/src/{awareness,method,gremlin}.rs` and tests/examples; +3. #1504, #1508/G1, #1495 receipt gap, #1359 observe/revise/learn; +4. `.arxiv/2026-10_sag_ona_internal_experience_source_excerpts.md`; +5. `.arxiv/2026-10_sag_repo_graph_context_source_excerpts.md`; +6. pinned ONA `dc4efd0abd520cdb79bf53bfa3c285ebb24f2e8a`, especially `src/{NAR,Cycle,Memory,Decision,Inference}.c`. + +### Explicit status corrections + +- #1509 demonstrates Quack-backed one-hop introspection over **projected prepared methods**, not repository-wide source indexing, persistence or arbitrary k-hop reachability. +- The seven-language Bible graph is not a shipped corpus graph; #1509's source audit explains the English KJV, small lexeme fixture and plan-only seven-language claim. +- H1's scalar-vs-materializing measurements do not establish a fused SIMD backend or guaranteed speed gain. +- Method keys are currently caller-issued, not magically minted by OGAR. +- Do not pretend `CLAUDE.md` can be removed without comparing its task instructions and human-written guidance; keep safety/instructions outside the replaceable factual context. +- 'SoC' is separation of concerns in this repository, not a chip design. + +## Deliver one minimal executable vertical slice first + +Choose **one existing, real method** from #1509 (e.g. `billable_hours`). + +Implement/verify, only if existing APIs allow it: + +```text +real MethodTable + source provenance + ↓ +SoftwareGraph projection + ↓ +Quack Draft + mask-risc + ↓ +ContextSlice {anchor, related nodes, typed edges, source pointers, + evidence tiers, revision, omissions, uncertainties} + ↓ +small CLI output that Claude Code could consume +``` + +The *proof* is independent: the returned definitions/dependencies agree with the actual prepared `Program` and a source-derived test oracle. + +If one-hop works but multi-hop doesn't, **stop at one hop** and emit `UnsupportedMultiHop`; the user should see a meaningful limitation, not a fake chain. Test a legally expressed `EqU32Via` or existing relation carrier only as a separately gated follow-up. + +### Proposed API (refine against code, do not proclaim it shipped) + +```rust +context(symbol_ref, intent, budget, revision) +impact(symbol_ref, change_spec, budget, revision) +propose(symbol_ref, objective, budget, revision) +``` + +Symbol identity must be revision-qualified, including `HEAD` and dirty worktree. Return typed `NotIndexed`, `AmbiguousSymbol`, `StaleRevision`, `InsufficientEvidence`, `UnsupportedMultiHop` or similar exact current error variants. Do not silently fall back to matching a label. + +The first prototype can be an example binary. A read-only local MCP/Claude Code tool wrapper is **optional** and must only be documented as connected after it is demonstrably callable from Claude Code. No VS Code extension required. + +### Source-symbol layer + +Investigate rust-analyzer/LSP or other compiler-backed definition/reference exports without introducing a second reasoning engine. Do not assume AST scraping gives full macro/dynamic-call coverage. Bind source symbols to ClassId/MethodKey only via demonstrated registration or code-based witness. Treat imports, callsites, trait implementations, tests and external source pointers as versioned graph facts with source-line provenance and a completeness label. + +Generate a `context` result with explicit `checked`, `not_checked`, `truncated`, and `uncertain` categories. Missing edge != proven absence. + +### Cheap local proposer + +Start with at most three deterministic patterns: +1. After a method references a primitive, propose its compiled-dependency and oracle tests. +2. When a repeated condition is already a named method, propose typed method reuse, preserving semantic scope. +3. For materialized-filter→fold, flag H1 as a **candidate** and list legality/performance obligations, not promised acceleration. + +Do not generate/edit Rust based on these heuristics without separate agent review. + +### One receipt and anticipation falsifier + +Use existing benchmark and #1495 execution-receipt research. Produce a candidate receipt linked to the program and source revision. Include only measurements you can **actually collect**. Keep wall time, cycles, allocations, materialized bytes, source snapshot, CPU tier and oracle verdict distinct. + +Register a performance prediction **before** collecting the result. Compare materialized-vs-scalar references under pinned data and typed oracle. Demonstrate a positive, negative or inconclusive observation and an explicit revised hypothesis record. If the output cannot be consumed by existing NAL machinery, record that gap rather than adding an ONA executor. + +Disable instrumentation for the graph's own context queries or provide bounded origin-gated tracing. A graph read must not recursively trigger unbounded graph event creation. + +### Baselines required for agent-context claims + +Compare: +- A: current `CLAUDE.md` + grep/read workflow; +- B: source symbol index / deterministic IDE-like lookup; +- C: Quack/SAG bounded context slices; +- D: optional graph + only essential source snippets. + +For fixed tasks/SHAs and comparable model budgets measure: +- local indexing/setup CPU, elapsed time and storage; +- model-visible input tokens, tool roundtrips and total task latency; +- independent-gold dependency precision and recall; +- correct change/test outcomes and missed invariants; +- freshness with dirty worktree and altered `SchemaSeal`; +- effects of truncated graph slices. + +No 'token-free Claude' claim. If correctness drops, token savings alone cannot pass. + +### ONA reference checks + +Trace and distinguish in pinned ONA source: +- `NAR_AddInput` / `NAR_Cycles`; +- `Cycle_Perform`, `Cycle_ProcessBeliefEvents`, `Cycle_ReinforceLink`; +- `Memory_Conceptualize`, `Memory_ProcessNewBeliefEvent`; +- `Decision_BestCandidate`, `Decision_Anticipate`, `Decision_Execute`, `Decision_AddNegativeConfirmation`; +- `Inference_RevisionAndChoice`, `Stamp_checkOverlap`. + +Report whether ONA's positive/negative temporal implication evidence is appropriate for this cost-prediction domain. Compare it with a static heuristic and empirical cost history. Preserve ONA's temporal/procedural semantics; do not brand a generic log or a simple average 'ONA-compatible'. + +The Wang/Li/Hammer 2018 mental-operation/self paper has a different theoretical scope from shipped ONA. Keep that separation explicit. + +### Validation/negative controls (must turn red) + +1. Same field name and ordinal under two ClassIds; 2. method dependency cycle; 3. body or seal mutation invalidates context/receipt; 4. source ref resolves to wrong commit/line; 5. macro/trait/dynamic call not indexed and marked uncertain; 6. multi-hop request refused if unsupported; 7. unordered/limited slice explicitly marked incomplete; 8. forged `Verified` edge from prose rejected; 9. source comment containing 'ignore instructions' treated as inert data; 10. local read-only context cannot call an external mutation; 11. receipt replay preserves evidential weight; 12. missing anticipated observation not counted as a failure before its observation window closes; 13. CPU-tier/dataset mismatch refuses benchmarking conclusion; 14. no timestamp/cycle claim without actual measurement; 15. alternative has identical typed answers over null/unknown and bag/set fixtures; 16. observer does not observe itself indefinitely; 17. token savings cannot conceal missed dependencies. + +A purported guard that remains green when intentionally disabled needs a stronger fixture. + +## Evidence ledger and PR discipline + +Every claim carries `SHIPPED / EXECUTED / MEASURED / PARTIAL / BLOCKED / HYPOTHESIS`, source SHA and concrete evidence. Distinguish cold construction, lookup latency, warm method execution and model context cost. Keep exact source pointers, no invented test results. + +Order the work: +- W0 source audit + method oracle; +- W1 one-hop `context`, stale-ref and uncertainty guards; +- W2 `impact` and `propose` only if existing algebra is sufficient; +- W3 receipts and bounded ingestion; +- W4 deliberate prediction, controlled cost comparison and revision; +- W5 token/accuracy benchmark against simple baselines; +- W6 optional local agent adapter **only after** the prior gates. + +Do not broaden into general NAL-9, new ISA bytes, source rewriting or a UI until experiments justify it. + +**Output:** (a) design summary, (b) small executable tests with disable-red reports, (c) code pointers and measurements, (d) gap ledger with no false positives, (e) a draft PR referencing #1509. If only a conceptual integration is possible, stop after tests documenting the specific blocker. + +### Success condition + +One method, one revision-scoped context query and one independent oracle; one explicit pre-registered performance prediction and measured revision; and a quantified comparison showing whether this approach beats simpler context retrieval without losing correctness. + +The ambition is *local architectural memory with addressable evidence*, not an invisible second agent. + +## Deferred research addendum: read before broadening the implementation + +This initial prompt was intentionally a minimal falsifier. For the deeper alternatives and rigorous edge cases, read: + +- [Addressable context, identity/freshness, foveated selection, receipts, experiment economics and 15 negative fixtures](../plans/software-awareness-agent-context-deferred-contracts-v1.md). +- [High-signal arXiv excerpts: context ordering, graph retrieval, costly experiment selection, code uncertainty and verification](../../.arxiv/2026-10_sag_agent_attention_active_selection_excerpts.md). + +**Do not silently ship those deferred proposals in W1.** Select the smallest experiment that can break the hypothesis. Implement `context` for one real #1509 `MethodTable` method and one Quack hop; add a source provenance witness; test negative controls. Escalate to incremental symbol indexing, ONA receipt selection, extra graph hops or Claude adapter only after independent correctness and efficiency gates pass. + +Further research probes to retain in the ledger: +- intent-specific **evidence coverage**, token ordering and a mandatory-law budget overflow refusal; +- `HEAD` vs dirty-worktree cache invalidation and macro/trait-call incompleteness; +- a bounded `DeltaSlice` protocol which cannot invent context absent from the model's prior accessible history; +- experiment cost versus expected information gain, separate from materialization/cycle benefit; +- source-verified low-level dependency facts versus source prose/LLM claims; +- ONA-style prediction ablation, receipt replay on another layer, CPU-tier and selectivity shift, and static/history-model controls. + +When reporting results, distinguish `TokenEstimate` from tokenizer-counted `ModelInputTokens`; `LogicalMaskOps` from `MaterializedBytes`; `CpuTier` from observed code generation; and `ObservedOutcome` from `VerifiedCausalEffect`.