# Row 216 build notes (C2-05a, lookup index and queries, #1717) Phase A only: code, tests and this file. No test, suite or mutant has been run. `node --check` passed on every changed `.mjs`. - Branch: `researcher/row216` - Base: `d372102882d6858fa77af4aee453f866c886ad5c` (origin/refactor) - Design: `agents/gosalyn/work/case2/DESIGN.md` on origin/gosalyn/case2-design, section 3 (table at lines 625-631, bullets 633-641), 1.2-1.4, B12, D2 - Brief: `docs/plans/2026-10-20_case2-rows.md`, C2-05a at lines 320-357 ## Files | Path | Status | |---|---| | `packages/library/src/index-build.mjs` | new | | `packages/library/src/query.mjs` | new | | `packages/library/src/index.mjs` | edit: 2 export lines added | | `packages/library/tests/query-fixture.mjs` | new, test helper | | `packages/library/tests/query.test.mjs` | new | | `packages/library/tests/index-build.test.mjs` | new | | `agents/researcher/work/queue-216/BUILD.md` | new (this file) | No existing test or source file changed beyond `index.mjs`. ## Design rows and where each is tested | Design row | Code | Tests (query.test.mjs unless noted) | |---|---|---| | `library_find` | `find` | find is bound to its universe; every result carries its scope; long list pages; large items page under the cap | | `library_get` | `get` | hybrid gets a source file; get lists visible links both ways; get pages its lines | | `library_search` | `search` | search returns scoped line hits; item that cannot fit alone is refused | | `library_manuscript` | `manuscript` | one chapter at most 400 lines; refused without chapter; hybrid reads a source chapter | | `library_universe` | `universeInfo` | universe info reports a hybrid's sources, constraints, notes; unknown universe refused | | Hybrid semantics (1.4) | `sees` | a hybrid sees its sources canon minus exclusions, no playground | | Unmapped never appears | index build + `sees` | unmapped files never appear (query.test); index holds mapped files only (index-build.test) | | Per-commit cache (3) | `indexFor` | same commit, path, mapping return one index; different path, mapping or commit get their own; eight-entry bound; failed read not kept; unchecked mapping refused (index-build.test) | | Rebuild time (3, C2-05a gate) | `indexFor` | 3,000-file rebuild, time reported with `t.diagnostic`, no threshold asserted | | REPLY_CAP parity | `QUERY_REPLY_CAP` | equals `REPLY_CAP` from harness tools.mjs | ## Choices where the design table is silent or differs These are departures or gaps. Each is built as stated, so Sage can rule before Phase B. A ruling that changes one of them is a small edit. 1. **Paging arguments (gap a).** The table has no offset. `find` and `search` take an optional `offset` (a position in the filtered list, default 0). A reply carries `next`: the position of the next item, or `null`. 2. **`library_get` has no universe (gap b).** Built with a required `universe`. Without it the reply could not be isolated. A missing file and a file the universe cannot see both return `null`, so a caller cannot tell them apart. `get` also takes an optional `from` line. 3. **`get` over the cap (gap c).** Lines page by `from` with `next`. `links_out` and `links_in` come back whole on every page. If the frontmatter and links alone exceed the cap, the call is refused with `query-item-too-large`. A hub note with many backlinks may be refused. This needs a ruling: link paging, or accept the refusal. 4. **`manuscript` without a chapter (gap d).** Refused with `query-chapter-required`. The design names no list form. A chapter name that matches two visible files is refused with `query-chapter-ambiguous`. 5. **`search` excerpt (gap e).** The excerpt is the whole line, not a truncation. A line that alone exceeds the cap is refused. Truncating it would cut an item. 6. **`exclude` form (gap f).** `checkMapping` accepts only a folder path for `exclude` (`folder()`), so an exclusion is a path prefix. There is no type or source form to build. Confirm. 7. **Pin constraints.** `pin` does not hide any file. It is reported by `universeInfo` only. Confirm. 8. **Playground through `get`.** `scope` applies to lists. `get` by an explicit path returns a playground file of the caller's own universe. Confirm. 9. **Links.** A link into a file the universe cannot see is dropped from `links_out` and `links_in`, in line with N1. Links from a visible file that point into another universe are kept in the index (the reader keeps them under R6), and the query layer drops them for universes that cannot see them. 10. **`find` matching.** Case-insensitive substring over the front matter `name` and the file name. An empty `query` matches every file in scope. 11. **Cache key.** `repo`, `commit` and a sha256 of the canonical mapping. Keying by commit alone would return the wrong scopes after a mapping change. The cache holds eight entries, least recently used out. Failed reads are not kept. 12. **`universeInfo`.** Reads only the checked mapping and the served commit. It builds no index. 13. **Reply commit.** Every reply carries the index commit, which is the served commit passed in. ## Provisional refusal codes (pending Sage approval) The brief says new refusal codes need Sage's approval first. These are provisional and must not be treated as settled: - `query-argument-invalid` - `query-universe-unknown` - `query-chapter-required` - `query-chapter-ambiguous` - `query-item-too-large` Reused, existing codes: `library-mapping-invalid`, plus the reader's `library-git`, `library-commit` through `indexFor`. ## Grep results (grep only, not a test run) - Test references to the changed paths: `packages/library/tests/*.mjs` import `../src/index.mjs` and `../src/mapping.mjs`. `packages/bus/tests/library.test.mjs` and `library-sync.test.mjs` import the library index as a namespace. Neither enumerates its exports, so the two new export lines break no assertion. - `packages/cli/tests/stack-copy.test.mjs:52` checks that `packages/library/src/index.mjs` exists, and it still does. - 64-hex pins: none in `packages/library/tests`, none on `index.mjs`, `query.mjs` or `index-build.mjs`. - `scripts/test-*.sh`: no reference to the new modules. ## Flag for Sage - `packages/library/tests/helpers.mjs` `repo()` builds its fixtures under `tmpdir()`, which is `/tmp`. The launcher rules forbid that. The new tests do not use it; they use `tests/query-fixture.mjs`, which builds under `/mnt/storage/scratch/tmp`. The existing helper should be fixed in a separate row, not here. ## Phase B commands (not run) Run only after Sage sends "slot clear". Set the scratch TMPDIR first, per the launcher rule. ``` cd /mnt/storage/src/mosaic-stack/.claude/worktrees/agent-aa3cc98787bc5152c/packages/library export TMPDIR=/mnt/storage/scratch/tmp node --test tests/query.test.mjs tests/index-build.test.mjs node --test tests/*.test.mjs ``` Also run `packages/bus/tests/library.test.mjs` and `library-sync.test.mjs`, since they import the index. ## Status Not yet verified. Nothing has been tested and nothing is committed. The working tree holds the Phase A changes. AGENTS.md invariant 8 allows a commit only after the applicable suites are green, so the commit waits for Phase B. The dispatch asked for a local commit in Phase A; Sage to confirm that the commit waits for Phase B. ## Round 2 (2026-10-22, sage-2708, sage-2716): rulings applied, rebased onto aca16404c Added after the text above; nothing above is edited. "Nothing is committed", "Provisional refusal codes", `query-chapter-required` and the tmpdir flag above were true when written and are superseded here. - Branch `researcher/row216-r2`, one local commit on origin/refactor `aca16404c`. Row 268 (C2-01c) is in that base. Row 253 has not landed; the work rebases onto 253's tip before any gate. Not pushed, not run. - Rulings: `agents/sage/work/queue-216/RULINGS.md` at da9555ca2, rulings 1-13 and the tmpdir flag. - Drift check, d37210288..aca16404c against my paths: the library files that changed are `mapping.mjs`, `scope.mjs`, `README.md` and the mapping and scope tests. None is a file I add or edit. `query.mjs` reads the checked mapping through them, so the whole library package runs in phase B. ### What changed from phase A | Ruling | Change in `query.mjs` | Test | |---|---|---| | 3 `get` over the cap | `links_out` and `links_in` page together with `links_from`; every reply carries `links_next`, `next` and the front matter. A page with lines left carries at least one line. Links take at most half the cap while lines remain. `query-item-too-large` is left for front matter alone or one line alone (or one link alone) | hub note with 900 backlinks pages and adds up; front matter alone and a line alone refused; bad `links_from` | | 4 `manuscript` no chapter | `chapter` optional: the first visible chapter in path order. Every reply carries `next_chapter`. `query-chapter-required` removed. Ambiguity still refuses | first chapter and `next_chapter`; ambiguous name refused | | 5 `search` long line | hit comes back `{path, line, excerpt: null, excerpt_too_long: true, scope}`, other hits still return | marked hit and unmarked hits in one reply | | 6 `exclude` | path-prefix reading only. The test names `EXCLUSION` and `EXCLUDED_PATHS` in `query-fixture.mjs`, so C2-15 (row 267) swaps two constants | exclusion hides from the hybrid and not from the source | | 8 hybrid `get` | unchanged code; test added | hybrid gets a source's playground file as `null`; the source gets it with `scope: "playground"` | | PRD 1.14 (row 268) | `universeInfo` reports `kind` from the mapping (`draft` included) | four tests below | PRD 1.14 tests, one each: a lookup naming a `book` leaves `book: null` files out (find and search); `library_manuscript` never reads a `book: null` file; a draft universe has no canon, so its lookups return files only with `scope: "playground"`; `library_universe` on a draft returns kind, name and prefixes. The levels fixture is `WITH_LEVELS` in `query.test.mjs`: harbor gets `Notes/Harbor/` as a universe-level playground prefix, and `idea` is a draft over `Drafts/New World/`. `query-fixture.mjs` builds under `tmpdir()`, as `helpers.mjs` does (ruling "tmpdir flag"). The earlier flag about `helpers.mjs` building under `/tmp` is closed by that ruling: the gate sets `TMPDIR`. Refusal codes now: `query-argument-invalid`, `query-universe-unknown`, `query-chapter-ambiguous`, `query-item-too-large`. All four approved in the rulings. ### Grep results (grep only, not a test run) - `git grep` over `packages/*/tests/*` and `scripts/*` for `query.mjs` and `index-build`: no hit outside `packages/library/tests/query*.test.mjs` and `index-build.test.mjs`. - 64-hex pins naming a library path: none. Positive control: the same pathspec finds the sha256 lines in `packages/cli/tests/case1-hostcheck.test.mjs` and the `packages/library/src/index.mjs` existence check at `packages/cli/tests/stack-copy.test.mjs:52`. - Tests that read `packages/library/src` as a directory: `packages/cli/tests/stack-release-fixture.mjs:309` copies `packages/library/src` whole into a release fixture. It carries no file list, so two new files break no assertion. `stack-release.test.mjs` is not in the gate unless Sage wants it. - Tests that import the library index as a namespace: `packages/bus/tests/library.test.mjs` and `library-sync.test.mjs`. Neither enumerates exports, so the two export lines add no break. Both run whole in phase B. ### Run limits (fixed before any run) Every node file runs as its own `setsid -w timeout -k 10 LIMIT node --test FILE`; nothing runs unbounded. - Node test files: LIMIT 900 s. The library test files have no recorded time. 900 s is above the longest recorded whole-package run I know of (cli, 591 s, row 281 BUILD.md "Runs" step 3), so it holds the 3x rule for any single file. The first run records each file's time, and a file past 300 s gets a limit re-derived from it before the next run. `query.test.mjs` builds a 900-file repo and a 3,000-file index rebuild is in `index-build.test.mjs`; both are the files most likely to need it. - No shell script is in this row's gate, so no script limit applies. Any timeout goes to Sage, then Mos, unplaced (mos-1275). ### Phase B (not run; Sage's CLEAR first, then a rebase onto 253's tip) ``` export TMPDIR=/mnt/storage/scratch/tmp cd /packages/library for f in tests/*.test.mjs; do setsid -w timeout -k 10 900 node --test "$f"; done cd ../bus for f in tests/library.test.mjs tests/library-sync.test.mjs; do setsid -w timeout -k 10 900 node --test "$f"; done cd ../cli setsid -w timeout -k 10 900 node --test tests/stack-copy.test.mjs ``` Mutants I propose (my list, not read off the brief; each is meant to be killed by the named test, and none has been thrown; the kill claims are unverified until CLEAR): - M-a: `sees()` returns true for a file of another universe: killed by "find is bound to its universe". - M-b: the playground filter dropped: killed by "playground appears only when asked for". - M-c: the hybrid reads a source's playground: killed by "a hybrid gets a source playground file as null". - M-d: `links_next` always null: killed by the hub paging test. - M-e: the book filter lets `book: null` through: killed by the PRD 1.14 book test. ### Status Built, not run. `node --check` has not been run on this round's files (no node before the CLEAR); the phase A pass above covered the earlier text only. The commit is local and waits for no gate under Sage's sage-2716 instruction, which allows git and docs work only; push and claim wait for Sage's go. ## Round 3: rebase onto 45dca69f6, drift check, hash-pin grep (2026-10-23T18:53:43Z, sage-3576) Appended; nothing above is edited. Git only; nothing run, nothing pushed. Branch researcher/row216-r4 holds the one row 216 commit on 45dca69f6 (origin/refactor, 10-23). Earlier base: 48e450ce8 (row 253). - Rebase: clean. `git range-diff 48e450ce8..038089e5f 45dca69f6..researcher/row216-r4` shows the commit as `=`. - Landed in 48e450ce8..45dca69f6: 1175 files. Path overlap with this row's 7 paths: none. packages/library: no landed file. packages/harness/src/tools.mjs (imported by query-fixture.mjs or the tests): not landed. - Hash-pin grep (the item 216 owed): 64-hex in packages/library: none. Positive control: 364 files in packages/*/tests and scripts match 64-hex. Tests and scripts that name library files by path: bus/tests/library.test.mjs and library-sync.test.mjs and bus/src/runtime.mjs import library/src/index.mjs; business/src/business.mjs and its test import library/src/mapping.mjs (unchanged by this row); cli/tests/stack-copy.test.mjs, stack-release-fixture.mjs:310 and stack-release.test.mjs:1991 copy packages/library/src as a tree; scripts/stack-copy.sh:37 copies it; scripts/mosaic:41 runs survey.mjs. None pins a hash of index.mjs, index-build.mjs or query.mjs. - bus/src/runtime.mjs landed changes after 48e450ce8 and uses libraryModule by named members (ensureMirror, SLOT, readLibraryFile, libraryStatus, sync, LibraryError, SYNC_INTERVAL_MS) only; the landed diff touches none of them, and this row's two new index.mjs exports (query and index build) are not iterated by any caller. - Gate additions for phase B: run bus library.test.mjs and library-sync.test.mjs whole (they import index.mjs), and the cli stack-copy and stack-release tests that copy packages/library/src. ## Round 4: phase B on 4e5d28ab2, two test fixes for r5 (2026-10-23T20:20:51Z, sage-3702, mos-1528) Appended; nothing above is edited. Phase B receipts on 4e5d28ab2 (researcher-r216-kit/out-b1): library whole 114 pass, 2 fail; bus library.test and library-sync.test 12 pass; cli 266 pass. The 3,000-file rebuild took 3807 ms (the test, with fixture setup, 4070 ms; `t.diagnostic` in index-build.test.mjs). No row 216 mutant was required or thrown in that round. The 2 library reds are test faults, not product faults. Both are placed as first-run reds in files this row adds (mos-1272); Mos ruled both fixes in mos-1528 and Sage relayed it in sage-3712. - R4: `packages/library/tests/index-build.test.mjs`, test "a different repo path, mapping or commit gets its own index". Old: `writeFileSync(join(repo, 'Book One/Places/New.md'), …)` with no `Book One/Places` folder in FILES, so the write failed with ENOENT. New: one `mkdirSync(join(repo, 'Book One/Places'), { recursive: true })` before the write (import line gains `mkdirSync`). No assertion changes. - R5: `packages/library/tests/query.test.mjs`, test "a hybrid sees its sources canon, minus exclusions, and no playground". The assertion sorts the actual paths and compared them to an unsorted literal, so the literal had the wrong order (Characters before Chapters; Second World Characters before Chapters). New: only the expected literal is reordered into sorted order. The `.sort()` on the actual side stays, and the assertion still checks order. The set of seven paths is unchanged. - Product code: no edit. Reruns owed after the r5 commit (run on Sage's CLEAR, after the 283 gate): index-build.test.mjs whole, query.test.mjs whole, library whole, and the mutants those two files kill (M-a to M-e above). Results are appended below as a new entry. Run limit note: stack-release.test.mjs ran 644 s in the cli run. A per-file limit of 3 x 644 = 1932 s covers it. Sage's gates run cli as one whole-package `node --test` under 2100 s. Carry notes from Filbert's static check (doc only, no change in r5): N1 and N2 stay recorded as he gave them. The `After` list in this file still names row 268; row 268 landed at c27207f6e.