Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,8 @@ release/
# Local-only: browser-based tmux session launcher (see tmux-web/README.md)
tmux-web/

assets/__pycache__/
__pycache__/
*.pyc

assets/generate-waitlist.py

Expand Down
10 changes: 1 addition & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,7 @@ Canonical project guidance for coding agents working in this repository (Codex/A

**Instruction budget:** Keep this root file below 32,768 UTF-8 bytes; `npm run check:agent-docs` enforces the limit. Put conditional procedures, evidence, and worked examples in linked documents. Codex user configuration may set `project_doc_max_bytes = 65536` as a safety margin, but the larger limit does not replace the repository guard.

**Completion and branch boundary:**

- This repository's default integration branch is `fork/consolidated`.
- A worktree or other feature branch is intermediate.
- Before committing or integrating, confirm the checkout is this repository and that its integration target is `fork/consolidated` (worktrees included). Never commit or merge this repository's work into another repository or its default branch (`main` included), and never merge another repository's work here.
- For authorized repository work, finish by committing the verified change, integrating it through any required checks or PR into `fork/consolidated`, pushing, and confirming that its remote head contains the commit.
- Stop earlier only when the user requests it or integration is blocked; report the exact blocker.
- Do not run `npm publish` without explicit authorization.
- Fork GitHub release policy is defined under Releases below.
**Branch:** this repository's default integration branch is `fork/consolidated`; fork work goes there through a pull request to the fork, never to `main`, and focused upstream contributions follow Branch roles below. Do not run `npm publish` without explicit authorization; fork release policy is under Releases below.

**Agent rules:** [House Rules](https://github.com/bompus/house-rules) is an optional, portable rule set that works well with this repository; nothing here requires it. If your agent loads it or similar always-on rules, this file adds to them and wins for this repository's commands, branches and checks.

Expand Down
Binary file removed assets/__pycache__/generate-waitlist.cpython-313.pyc
Binary file not shown.
18 changes: 9 additions & 9 deletions docs/benchmarks/explore-requested-evidence.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Measured 2026-09-10 (America/Denver). This change fixes omissions of requested s

## Controlled comparison

The 16 queries and expected source ranges come from the private reproduction fixture (private checkout at `74fcd4e`). All 13 referenced source files were checked against their recorded SHA-256 hashes at downstream commit `c570e32b22177ab59d3fa8f4c162419bac196422`.
The 16 queries and expected source ranges come from a private reproduction fixture taken from a downstream application. All 13 referenced source files were checked against the SHA-256 hashes recorded for the pinned downstream revision.

Three engines queried the same checkout-local index, with a fresh ToolHandler per query and no explicit `maxFiles` override:

Expand All @@ -30,15 +30,15 @@ Each cell counts returned / expected nonblank source lines across the fixture's
| 2 | Named normalization body | 9/9 | 9/9 | 9/9 |
| 3 | Prop wiring and table selectors | 0/24 | 0/24 | 2/24 |
| 4 | Cache key and consensus evaluation | 52/123 | 52/123 | 73/123 |
| 5 | Draft identity test | 0/31 | 0/31 | 30/31 |
| 5 | Identity-assertion test | 0/31 | 0/31 | 30/31 |
| 6 | Named interface | 0/132 | 0/132 | 132/132 |
| 7 | Priority stamping body | 0/33 | 12/33 | 33/33 |
| 8 | ADP mappers and secondary test | 97/117 | 97/117 | 97/117 |
| 9 | TTD receiver/storage, prose query | 0/78 | 0/78 | 0/78 |
| 10 | TTD receiver/storage, event query | 0/78 | 0/78 | 0/78 |
| 8 | Mapper bodies and secondary test | 97/117 | 97/117 | 97/117 |
| 9 | Receiver/storage, prose query | 0/78 | 0/78 | 0/78 |
| 10 | Receiver/storage, event query | 0/78 | 0/78 | 0/78 |
| 11 | Hover-related cache key | 0/50 | 0/50 | 0/50 |
| 12 | Vue cells and column styles | 0/22 | 0/22 | 18/22 |
| 13 | Draft identity test, broad path control | 0/31 | 0/31 | 23/31 |
| 13 | Identity-assertion test, broad path control | 0/31 | 0/31 | 23/31 |
| 14 | Focused stamping control | 33/33 | 33/33 | 33/33 |
| 15 | Exact Vue column literal and CSS | 0/4 | 0/4 | 4/4 |
| 16 | Explicit sender/receiver/storage bodies | 113/128 | 113/128 | 128/128 |
Expand All @@ -49,9 +49,9 @@ The decisive assertions are present in cases 1 and 5, including the identity che

- Cases 3, 4 and 11 still omit table selectors or the cache key. Case 4's evaluation body is now complete; losing the two formerly returned closing lines of the cache-key range does not establish that the key was previously usable.
- Cases 9 and 10 still omit the receiver file unless the query explicitly names its endpoints. Selecting that file and synthesizing the actual message boundary are separate future changes.
- Case 12 returns the survival tag and requested CSS ranges, but still omits the column declaration and ADP/FP cells in that broad query. The exact column-literal control, case 15, is complete.
- Case 12 returns the survival tag and requested CSS ranges, but still omits the column declaration and the remaining column cells in that broad query. The exact column-literal control, case 15, is complete.
- Case 13 improves selected test source but still omits the identity assertion. Its broad path-and-function query has less discriminating information than case 5. Do not score it as solved from its filename or partial line count.
- The ADP question remains helpful without the secondary test; no test-inclusion improvement is claimed for case 8.
- The mapper question remains helpful without the secondary test; no test-inclusion improvement is claimed for case 8.

## Validation and reproduction

Expand All @@ -68,7 +68,7 @@ For a source probe, build the intended engine's TypeScript and copy its assets,
```bash
fnm exec --using codegraph node scripts/agent-eval/probe-explore.mjs \
<fixture-checkout> \
'src/components/DraftTable.vue "col-w-survival"'
'<vue-component-path> "<column-class-literal>"'
```

Use the fixture's exact queries for the other cases. Match numbered lines inside each file's fenced Source section, not occurrences in the blast-radius header or omitted-symbol pointers. Recheck fixture hashes first. The direct harness binds the project through `CodeGraph.openSync`; it is not a deployed MCP or agent A/B run.
Expand Down
6 changes: 3 additions & 3 deletions docs/benchmarks/explore-selector-cache-evidence.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,17 @@ The existing guards for stale source, file admission, oversized containers, flow

## Fixed-source comparison

The exact 16 queries and 13 source-file hashes are from the private fixture (private checkout at `74fcd4e`), pinned to downstream source `c570e32b22177ab59d3fa8f4c162419bac196422`. Both engines used the same existing index and a fresh ToolHandler per call. Baseline results are the retained `22ae167837e174fa623dc77c2c4435ecadbc37d0` comparison; candidate results were rerun with each referenced source hash checked. This compares source completeness, not agent answer quality or independently rebuilt indexes.
The exact 16 queries and 13 source-file hashes are from the private fixture described in the first report, pinned to a downstream application's source revision. Both engines used the same existing index and a fresh ToolHandler per call. Baseline results are the retained `22ae167837e174fa623dc77c2c4435ecadbc37d0` comparison; candidate results were rerun with each referenced source hash checked. This compares source completeness, not agent answer quality or independently rebuilt indexes.

| Case | Evidence | 22ae1678 | Candidate |
| --- | --- | --- | --- |
| 3 | Popout prop wiring | 2/2 | 2/2 |
| 3 | DraftTable selectors | 0/22 | 22/22 |
| 3 | Table selectors | 0/22 | 22/22 |
| 4 | Cache key | 0/50 | 50/50 |
| 4 | Consensus evaluator | 73/73 | 73/73 |
| 11 | Cache key from broad hover/invalidation query | 0/50 | 50/50 |

All other fixture ranges retain their baseline completeness. The snapshot assertion, draft identity assertion, named interface, stamping body, ADP mapper bodies, exact Vue column/CSS, and explicit TTD endpoint bodies remain passing controls. Cases 9/10 still omit the broad-query receiver; case 12 still omits the column declaration and ADP/FP cells; case 13 still omits the identity assertion. No sender-to-listener edge was added.
All other fixture ranges retain their baseline completeness. The snapshot assertion, identity assertion, named interface, stamping body, mapper bodies, exact Vue column/CSS, and explicit endpoint bodies remain passing controls. Cases 9/10 still omit the broad-query receiver; case 12 still omits the column declaration and the remaining column cells; case 13 still omits the identity assertion. No sender-to-listener edge was added.

The candidate's maximum response was 24,989 characters; all 16 responses totalled 392,850 characters. Single-pass median latency was 197.5 ms, range 69–268 ms. The earlier baseline was 202 ms, range 65–258 ms. Runs were not interleaved: these timings do not establish a speedup or regression.

Expand Down
7 changes: 3 additions & 4 deletions docs/benchmarks/fork-vs-upstream-2026-09-26.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,8 @@ n8n (Vue and TypeScript) and re-measures every corpus on one newer fork build.
in their own worktrees.
- **Host.** WSL2 Ubuntu, 16 vCPUs, 47 GiB RAM, ext4. No swap in use. Each batch
started with a 1-minute load average under 2 and Windows under 5% CPU.
- **Commands.** Every run was capped with
`nice -n 10 ~/.local/bin/run-capped 16G` and timed with `/usr/bin/time -v`,
with `CODEGRAPH_DIR=.cg-bench`, `CODEGRAPH_NO_DAEMON=1` and
- **Commands.** Every run used `nice -n 10` under a 16 GiB memory cap and was
timed with `/usr/bin/time -v`, with `CODEGRAPH_DIR=.cg-bench`, `CODEGRAPH_NO_DAEMON=1` and
`CODEGRAPH_TELEMETRY=0`. The index directory started empty for every run.
- Index: `codegraph init --yes .`
- One-file sync: an untimed `init`, then a one-line edit to one source file,
Expand Down Expand Up @@ -98,7 +97,7 @@ README lists as the fork's largest.

## One-file sync: fork vs upstream (Node 24)

Re-measured later the same day on an idle host (no other session's capped jobs
Re-measured later the same day on an idle host (no other session's memory-capped jobs
running, 1-minute load 1.5–4 from the benchmark's own workers), with the fork at
`perf/incremental-sync` (the sync skip cache, [`docs/design/incremental-synthesis.md`](../design/incremental-synthesis.md)).
Each arm indexes once, then times two one-file syncs, each adding a line to the
Expand Down
8 changes: 4 additions & 4 deletions docs/benchmarks/fork-vs-upstream-2026-09-28.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ runtime comparison (Node 24, Node 26, Bun), which was not re-run.
`npm run build` in their own worktrees.
- **Host.** WSL2 Ubuntu, 16 vCPUs, 47 GiB RAM, ext4, Node 24.21.0. No swap in
use. Before each corpus's index step and again before its sync step, the
runner waited until no other session held a capped job and the 1-minute load
average was under 2.
- **Commands.** Every run was capped with `nice -n 10 ~/.local/bin/run-capped`
(16G for index, 13G for sync) and timed with `/usr/bin/time -v`, with
runner waited until no other session's memory-capped job was running and the
1-minute load average was under 2.
- **Commands.** Every run used `nice -n 10` under a memory cap (16 GiB for
index, 13 GiB for sync) and was timed with `/usr/bin/time -v`, with
`CODEGRAPH_DIR=.cg-bench`, `CODEGRAPH_NO_DAEMON=1` and
`CODEGRAPH_TELEMETRY=0`. The index directory started empty for every run.
- Index: `codegraph init --yes .`
Expand Down
6 changes: 3 additions & 3 deletions docs/benchmarks/fork-vs-upstream-node-bun-2026-09-28.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,11 @@ The scripts are in [`scripts/benchmarks/runtime/`](../../scripts/benchmarks/runt
fork needs no override.
- **Host.** WSL2 Ubuntu, 16 vCPUs, 47 GiB RAM, ext4. Swap was cycled before
the run and stayed at 0 B. Before each corpus the runner waited until no
other session held a capped job and the 1-minute load average was under 2.
Windows-side CPU was about 9%.
other session's memory-capped job was running and the 1-minute load average
was under 2. Windows-side CPU was about 9%.
- **Environment.** `CODEGRAPH_DIR=.cg-bench`, `CODEGRAPH_TELEMETRY=0`, and
`CODEGRAPH_NO_DAEMON=1` for the CLI runs. Every CLI run used
`nice -n 10 ~/.local/bin/run-capped 16G` and `/usr/bin/time -v`. Peak memory
`nice -n 10` under a 16 GiB memory cap and `/usr/bin/time -v`. Peak memory
is MaxRSS. Database size is `codegraph.db` after a WAL checkpoint.
- **Order.** Per corpus the arms ran in the order upstream Node, fork Node,
fork Bun, upstream Bun, then the reverse. Each run did a full index
Expand Down
6 changes: 3 additions & 3 deletions docs/benchmarks/fork-vs-upstream-node-bun-2026-10-03.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,12 @@ The scripts are in [`scripts/benchmarks/runtime/`](../../scripts/benchmarks/runt
Node 25 and newer, so without the override upstream exits with
`Unsupported Node.js version: 26.3.0`. The fork needs no override.
- **Host.** WSL2 Ubuntu, 16 vCPUs, 47 GiB RAM, ext4. Before each corpus the
runner waited until no other session held a capped job and the 1-minute
load average was under 2. Unlike the 2026-09-28 run, swap was not cycled
runner waited until no other session's memory-capped job was running and the
1-minute load average was under 2. Unlike the 2026-09-28 run, swap was not cycled
first: 2.1 GiB of swap was in use, with about 35 GiB of memory available.
- **Environment.** `CODEGRAPH_DIR=.cg-bench`, `CODEGRAPH_TELEMETRY=0`, and
`CODEGRAPH_NO_DAEMON=1` for the CLI runs. Every CLI run used
`nice -n 10 ~/.local/bin/run-capped 16G` and `/usr/bin/time -v`. Peak memory
`nice -n 10` under a 16 GiB memory cap and `/usr/bin/time -v`. Peak memory
is MaxRSS. Database size is `codegraph.db` after a WAL checkpoint.
- **Order.** Per corpus the arms ran in the order upstream Node, fork Node,
fork Bun, upstream Bun, then the reverse. Each run did a full index
Expand Down
17 changes: 8 additions & 9 deletions docs/benchmarks/fork-vs-upstream-node-bun-2026-10-12.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,12 @@ The scripts are in [`scripts/benchmarks/runtime/`](../../scripts/benchmarks/runt
`Unsupported Node.js version`. The fork needs no override. The previous run
used Bun 1.4.2.
- **Host.** WSL2 Ubuntu, 16 vCPUs, 62 GiB RAM, ext4. Each run waited until
the host was quiet (below), and the benchmark held the host lock while it
ran.
the host was quiet (below), and the benchmark held a lock that other sessions
on the host respect before starting heavy jobs.
- **Environment.** `CODEGRAPH_DIR=.cg-bench`, `CODEGRAPH_TELEMETRY=0`, and
`CODEGRAPH_NO_DAEMON=1` for the CLI runs. Every timed command ran at normal
priority under `~/.local/bin/run-capped 16G` (a 16 GiB memory cap) and
`/usr/bin/time -v`. Peak memory is MaxRSS. Database size is `codegraph.db`
after a WAL checkpoint.
priority under a 16 GiB memory cap and `/usr/bin/time -v`. Peak memory is
MaxRSS. Database size is `codegraph.db` after a WAL checkpoint.
- **Order.** Per corpus the arms ran in the order upstream Node, fork Node,
fork Bun, upstream Bun, then the reverse. Each run did a full index
(`codegraph init --yes .` into an empty directory) and then two one-file
Expand All @@ -60,10 +59,10 @@ corpus.
### Quiet-host rule

A run started only when swap in use was at most 64 MiB, the 1-minute load
average was under 2, no `capped-*` scope was running, and Windows CPU, read from
the Windows side, was under 20% for three samples 20 s apart. An attempt was
rejected as suspect when the command exited non-zero or a Windows CPU sample
before or after it exceeded 30%. Each corpus had one retry; the first accepted
average was under 2 and no memory-capped job (a `capped-*` systemd user scope)
was running. Windows CPU, read from the Windows side, also had to be under 20% for three
samples 20 s apart. An attempt was rejected as suspect when the command exited non-zero or
a Windows CPU sample before or after it exceeded 30%. Each corpus had one retry; the first accepted
attempt is the one reported. The two runs per arm are the spread this page
offers; no wider variation criterion was set before the run, so a difference
near the 3% reporting band is labelled no clear change.
Expand Down
Loading