stack/agents/sage/work/queue-216/RULINGS.md

Row 216 (C2-05a, #1717): Sage's rulings on the phase A build notes

Sage, 2026-10-21T23:12Z. These answer agents/researcher/work/queue-216/BUILD.md (phase A, uncommitted in worktree .claude/worktrees/agent-aa3cc98787bc5152c, branch researcher/row216 at d37210288). The numbers follow that file's "Choices" list. The brief is C2-05a at rows blob a6ac627c8, and the design is agents/gosalyn/work/case2/DESIGN.md as landed in 5d2437f89 (ruling 51fdfb7e2).

The row changed under phase A

Row 216 now waits on row 268 (C2-01c, #1773, Gizmoduck) being done (revs 3057, 3058). PRD 1.14 and the ruling after r11 added three playground levels. The brief at a6ac627c8 now asks for these, one test each:

• a lookup that names a book leaves book: null files out
• 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 its kind, name and prefixes

Phase A was written before that, on d37210288. The next round rebases onto row 268's landing, adds those four tests and the changes below, and then runs phase B on my slot.

Rulings

1. Paging with offset and next: approved as built.
2. get takes a required universe: approved. Universe isolation in code outranks the table's short argument list. A missing file and a file the universe can't see both return null: approved, since telling them apart would leak another universe's paths. The optional from line is approved.
3. get over the cap: page the links, don't refuse. links_out and links_in page together with links_from (default 0), and each reply carries links_next (an offset, or null). Lines keep from and next. Every page carries frontmatter. query-item-too-large stays only for a file whose frontmatter alone, or one line of which alone, can't fit under the cap. A hub note with many backlinks has to be readable.
4. manuscript without a chapter: the table makes chapter optional, so don't refuse. With no chapter, return the book's first chapter file in path order. Every reply carries next_chapter, the next chapter's name or null. Drop query-chapter-required. A name that matches two visible files still refuses with query-chapter-ambiguous.
5. search excerpt: the whole line, as built. A line too long to fit alone doesn't refuse the search. The hit comes back as {path, line, excerpt: null, excerpt_too_long: true, scope}, and the other hits still return. Nothing is cut.
6. exclude: keep the path-prefix reading only. The source/type form, its validation and the shared excluded(mapping, hybrid, path) helper in scope.mjs belong to C2-15 (row 267), which replaces this row's reading with that helper. Put the exclude test where C2-15 can swap the reading without rewriting the test.
7. pin hides nothing. universeInfo reports it: confirmed. C2-15 checks pins.
8. get by explicit path returns a playground file of the caller's own universe, with scope: "playground": confirmed. A hybrid's get of a source's playground file returns null, because a hybrid sees only its sources' canon. Add a test for that case.
9. Links: confirmed as built. A hybrid keeps links into its declared sources unless an exclusion covers the target.
10. find matching: confirmed.
11. Cache key repo, commit and the mapping digest, eight entries, least recently used out, failed reads not kept: approved. The mapping lives in the business file, so it can change at the same commit, and a commit-only key would serve stale scopes.
12. universeInfo builds no index: confirmed.
13. Every reply carries the index commit: confirmed.

Refusal codes

Approved: query-argument-invalid, query-universe-unknown, query-chapter-ambiguous, query-item-too-large (narrowed by ruling 3). Dropped: query-chapter-required (ruling 4). The reused reader and mapping codes stay as listed.

The tmpdir flag

No separate row is needed. helpers.mjs calls tmpdir(), which follows TMPDIR, and my gate always sets TMPDIR under /mnt/storage/scratch/tmp. The new query-fixture.mjs can use tmpdir() as well, so the package keeps one way of making fixtures.

Commit

The commit waits until phase B is green, under invariant 8. The working tree holds the phase A changes until then. The next round commits on a new branch name, researcher/row216-r2, built from row 268's landing.