stack/agents/morgana/work/queue-267/BUILD.md

Row 267 (C2-15, #1772): hybrid universes, exclusions, pins and the crossover. Build notes

Morgana, 2026-10-25. Brief: docs/plans/2026-10-20_case2-rows.md "C2-15 hybrid universes: exclusions, pins and the end-to-end crossover" (blob 85e6fe2e). Reviewer Filbert, gate owner Sage. Claimed at rev 4087. Branch morgana/row267 from refactor 78b69e1e6. Design 1.4 is agents/gosalyn/work/case2/DESIGN.md.

Status: build committed under sage-4389 and sage-4407. Mos approved the survey.test.mjs:75 change (mos-1667, read against 5b2da2203). Nothing is run. No runs before Sage's CLEAR.

1. What the code does today (78b69e1e6)

• mapping.mjs:119-134 checks only the shape of a constraint. exclude is any folder path, and pin.entity is any folder path with a scalar value. Nothing checks either against the sources.
• query.mjs:52-57 sees() reads exclude as a path prefix only (inside(c.exclude, file.path)). The type form second/Characters (mapping.test.mjs:203) passes the validator but hides nothing, because no file path starts with second/.
• reader.mjs:206-210 gives R6 only for a canon link into a universe that is neither the file's own nor one of its sources. A hybrid canon file that links into an excluded source path gets no problem.
• guard.mjs:91-97 lets any mix of one hybrid and its sources pass. It doesn't check exclusions.
• problems.mjs has R1-R7 and no R8.

2. Design

2.1 Validator (mapping.mjs)

The validator runs after every universe is read, alongside the existing sources check at :141-146, because it needs each source's books, playground and supporting lists. For each constraint of a hybrid:

• Type form: the first segment is one of the hybrid's sources, and the rest is exactly one key of types.
• Path form: the path equals, or lies inside, a book folder of one of the sources.
• Both forms fit: refuse library-mapping-invalid ("... reads as both a source/type and a source path").
• Neither form fits: refuse library-mapping-invalid ("... lies inside no book of the hybrid's sources"). This covers a path in the hybrid's own books, in a non-source universe, or unmapped.
• Path form under a playground: a path equal to or inside one of a source's playground prefixes refuses ("... lies under a playground of universes.X, which the hybrid never reads"). "Under" means the path equals the prefix without its trailing /, or starts with the prefix.
• pin.entity: the same path-form rules apply, with no type form. An entity is one file.

The stored shape stays { exclude } / { pin }. I don't add a form field. library_universe returns constraints as they are now, and the index cache digest doesn't change for existing mappings. excluded() works out the form again each time. It's pure and cheap.

2.2 excluded(mapping, hybrid, path) (scope.mjs)

This returns true when any exclude of universe hybrid covers path:

• Type form S/T: path starts with ${book}/${T}/ for some book of source S.
• Path form P: path === P or path starts with ${P}/.

It returns false when hybrid isn't a hybrid. It reads only the path (D2). It has three callers:

• query.mjs sees() replaces its own inside(c.exclude, ...) reading with this helper.
• reader.mjs uses it for the excluded-link R6.
• guard.mjs uses it for the excluded cite.

query-fixture.mjs EXCLUSION (Book One/Research) is path form and still fits, so the existing C2-05a query tests keep their constants.

2.3 Reader: excluded-link R6 and R8

• Excluded-link R6: in the canon branch at :206, a hybrid file's link to a target where excluded(mapping, file.universe, to.path) is true gives problem('R6', file.path, link.line), with the default message. A custom message isn't possible: mirror.mjs:196-201 validProblem accepts a sync-state problem only when message === RULES[code], so a new message would make every later sync state read refuse library-state-invalid. The link stays in file.links, as the other R-rules leave it. sees() already drops it from the hybrid's links_out. A link that is both foreign and excluded can't occur, because an excluded path always lies in a source, so each link gets at most one R6.
• R8: a new RULES.R8 entry reads "pinned value changed". The check runs once per commit, after the link pass, for each pin of each hybrid:
  • Entity missing from byPath: R8 at entity, with no line. This covers a file that is absent, R1, R2 or R7.
  • Entity present: R8 at entity, on the field key's line where there is one, unless the parsed front matter holds field as a scalar (string, number or boolean) and String(parsed) === String(value). A list, null, a missing key and unparsed (R3) front matter all count as changed. Under a plain String() comparison, ['grey'] would equal 'grey', so this rule closes that hole.
  • Hybrid versions: each canon file of the hybrid whose type (from classify) equals the entity's type, and whose name matches the entity's, is a version of it. Names are the trimmed front matter name on both sides. When either file has no text name, the file names (stems) compare instead. A version that holds field with another value gets R8 at its own path, on that key's line. A version without field gets nothing, and neither does any other file that only links to the entity.
• The entity's type and name come from classify(mapping, entity) and the entity's parsed file. When the entity is missing, its stem stands in for the name.
• An entity outside any type folder (a book root file, a manuscript file, or a folder that isn't a type) has type null or manuscript. Its versions are then the hybrid canon files with that same type and a matching name or stem. The brief doesn't cover this case, and no special rule is added for it (Filbert N2).
• R8 entries are deduplicated by path and line, so two pins or two hybrids on one missing or changed entity give one entry (Filbert N1). Survey counts and the sync state count each path and line once.

2.4 Guard (guard.mjs)

After the existing span check at :91-97, the guard looks for a hybrid among the cited universes. If there is one, and some cite lies in one of its sources while excluded(mapping, hybrid, c.path) is true, the guard refuses citation-cross-universe ("citation N (path) is excluded from hybrid H"). A reply that cites only source paths, excluded ones included, has no hybrid among its universes, so it's unchanged.

2.5 Setup sheet

docs/case2/SETUP-SHEET.md gets one section after "Supporting folders", headed "Making a crossover (hybrid) universe". It covers kind, name, sources, books, playground, constraints (exclude in both forms, pin) and notes, and says that the continuity role reads and cites the notes. It also says that Jason edits this entry by hand and agents can't change it (C2-04 rule M9), as the sheet already says for the rest of the entry.

3. Tests and mutants

New files and cases, all on scratch repos under TMPDIR (never /tmp):

• packages/library/tests/hybrid.test.mjs (new):
  • A business-file-shaped mapping (fixture mapping.json plus a cross hybrid) on a repo in her layout's shape.
  • find and search in cross return its own files plus the sources' canon, each carrying its source universe. They never return a source playground or an excluded path, and this runs once for each exclude form.
  • get keeps links_out into the sources and drops excluded targets.
  • A source universe's lookups never return a cross file.
  • universeInfo returns the sources, constraints and notes.
  • excluded() gets unit cases for both forms and for a non-hybrid.
• mapping.test.mjs: one case per new refusal: both forms fit, neither fits, the hybrid's own book, an exclude under a source playground, a pin under a source playground, and a pin.entity that doesn't end in .md (Q5). second/Characters at :203 still checks.
• reader.test.mjs:
  • R8 cases: entity missing, two pins on a missing entity give one entry (N1), entity changed, a same-name hybrid version with no link, and a list value.
  • Non-R8 cases: a hybrid place file with age: 300 that links the entity, and a different hybrid character that links it.
  • The excluded-link R6, once for each exclude form.
• guard.test.mjs: a hybrid cite with source canon passes, and a hybrid cite beside an excluded path refuses in both forms. A cite of only an excluded source path passes as that universe's item.
• packages/bus/tests/citation-guard.test.mjs: through citationWorld with mapChange adding the hybrid, the excluded-beside-hybrid send refuses and the messages count stays the same.
• Sync state after an excluded-link R6 (sage-4389 finding a): one case that syncs a commit holding a hybrid file's excluded link, then reads the sync state back with readSyncState and finds the R6 with the default message. This shows validProblem (mirror.mjs:196-201) still accepts the state.
• packages/bus/tests/library-lookups.test.mjs: one broker case, where library.find and library.universe in the hybrid return what the library tests above assert.
• C2-04 M9 rule (agents can't write projects), not a mutant: a case in packages/business/tests/library-projects-protected.test.mjs where an organization write that adds a new hybrid universe refuses organization-projects-protected. This is outside the brief's "tests in library and bus" list. Sage ruled it in (Q1), so the business suite is on the run list.
• docs/case2/SURVEY-RUN.md:98 names the problems line as R1 .., ..., R8 ... No test reads that file.
• One existing assertion changes: survey.test.mjs:75 gains , R8 0. The before and after lines are in assertion-diff.md, which goes to Mos before the commit (mos-1272).

Mutants. Each runs only its own named tests, and the tree is restored after each one.

#	Mutation	Killed by
X1	excluded() ignores the type form	hybrid.test "C2-15 excluded(): ..." and "C2-15 type form: find and search ..."
X2	excluded() ignores the path form	hybrid.test "C2-15 excluded(): ..." and "C2-15 path form: find and search ..."
X3	sees() keeps its old inside() reading	hybrid.test "C2-15 type form: find and search ..."
X4	the validator accepts "both forms fit"	mapping.test "C2-15: each exclude and pin is checked against the hybrid's sources"
X5	the validator skips the playground check	mapping.test "C2-15: each exclude and pin is checked against the hybrid's sources"
X6	R8 compares with plain String() (list equals scalar)	reader.test "C2-15 R8: the pinned entity reads clean ..." (list case)
X7	a version is matched by link instead of name	reader.test "C2-15 R8: a hybrid version of the entity ..."
X8	the reader drops the excluded-link R6	reader.test "C2-15 R6: a hybrid file that links into an excluded source path ..."; sync.test "C2-15 sage-4389 (a) ..." also fails
X9	the guard skips the excluded check	guard.test "C2-15 a hybrid cite beside an excluded source path refuses citation-cross-universe, both forms" (the mutant run); bus citation-guard "C2-15 excluded cite beside a hybrid refuses and inserts nothing" also fails

4. Rulings (sage-4389)

• Q1 yes. The C2-04 M9 case is new and goes only in packages/business/tests/library-projects-protected.test.mjs. No existing assertion there changes. The business suite is on the run list.
• Q2 dropped. The condition was a file:line showing that the hybrid's index, reader and guard never read a source's supporting prefix. Two of the three do read it:
  • Index: query.mjs:55 sees() returns false for a source file whose scope isn't canon, so the hybrid's lookups never show a source's supporting file. This one holds.
  • Reader: reader.mjs:206-209 checks R5 for playground targets only, and R6 skips any target in a source universe. A hybrid canon file that links into a source's supporting file gets no problem and keeps the link (:211).
  • Guard: guard.mjs:91-97 checks the cited universes and never their scope. A reply that cites a hybrid file beside a source's supporting file passes, and so does one beside a source's playground file (guard.mjs:87-90 only stops a playground cite marked as: 'canon'). Sage's ranges in sage-4399 (reader.mjs:206-211, guard.mjs:87-97) cover the same lines. Sage files a DEFERRED entry for the guard and reader gap at landing. So the validator does not refuse an exclude under a source's supporting prefix. The guard observation is outside this row's guard scope ("the excluded-path cite only"); I report it to Sage as a possible follow-up and don't change it here.
• Q3: R8 reaches the survey and the sync state as described. survey.test.mjs:75 goes through assertion-diff.md. Finding (a) adds the sync-state readback test in §3. packages/library/README.md lists R1-R7 in its problems table, so it gains an R8 row; no test reads that file.
• Q4 as written: versions count only in the hybrid's canon.
• Q5 yes: a pin.entity that doesn't end in .md refuses library-mapping-invalid, with its own test.
• Finding (a): R6 keeps the default message, with the readback test above.

5. Gate

Filbert approves the manifest. The library and bus suites, plus business if Q1 stands, run green on Sage's gate along with every scripts/test-*.sh. Hash pins on the changed files are grepped before in-review.

6. R2 (reviewer finding F1, written 2026-11-02T19:27:10Z)

Finding. The GPT reviewer's F1 (batch1-b-gpt.md, P2, blocks approval): search() in packages/library/src/query.mjs built its hits without universe, in both shapes (the normal hit and the excerpt_too_long hit). The row brief (docs/plans/2026-10-20_case2-rows.md, C2-15 Tests paragraph) says library_find and library_search in the hybrid return its own files and its sources' canon, each with its source universe. find already returned universe; search did not, and the tests reduced search hits to paths, so they passed without checking it. The broker forwards the query result unchanged, so the broker reply lacked it too. F2 (the hybrid's source exception ignoring source scope in the reader and guard) is out of scope for this round; the lead files it as a follow-up.

Fix. visible() filters index.files entries, and find returns file.universe from those same entries, so file.universe in search() is the file's source universe (index-build.mjs:31). Both hit shapes now carry universe: file.universe, placed after scope as in find. Nothing else in query.mjs changed. The reply-cap check in search() measures the hit with universe included, so a line within about 20 bytes of the cap now comes back marked excerpt_too_long where it used to return its excerpt. No test sits on that edge.

Pins found by the step 4 grep. query.test.mjs:178 deep-equals the exact excerpt_too_long hit for harbor; it gains universe: 'harbor'. No other test pins the hit shape. packages/library/README.md does not list search hit fields, so it is unchanged. The harness tool text for library_search (packages/harness/src/tools.mjs:245) names no hit fields, so it is unchanged, and no harness test reads search hits. No 64-hex pin names query.mjs, hybrid.test.mjs, library-lookups.test.mjs or query.test.mjs.

Tests.

• hybrid.test.mjs, both exclude forms: the search hits keep the existing path checks and now also assert that the hybrid's own hit (Crossover/Places/Bridge.md) is cross, a source-canon hit is its source (harbor for Ferry Logs in the type form, second for Ilse in the path form), and every hit equals the owner of its path. The helper owner() is shared with the existing find check.
• hybrid.test.mjs, new: an oversized line in a source's canon, searched through the hybrid, comes back as the excerpt_too_long hit carrying universe: 'harbor'. No test reached that branch with a hybrid before.
• library-lookups.test.mjs, the C2-15 broker case: library.search in the hybrid returns [path, universe] pairs for Elsewhere (harbor's Tomas, the hybrid's chapter) and ferry (harbor's two files), with the excluded second-world file absent.

RED. The new assertions failed on the unfixed code: 4 of 21 tests failed (the broker case, both forms of the hybrid case, the oversized case), all on a missing universe.

Mutants. Removing universe from the normal hit only: 3 fail (library-lookups.test.mjs:267, hybrid.test.mjs:71 in both forms). Removing it from the excerpt_too_long hit only: 2 fail (hybrid.test.mjs:92, query.test.mjs:178). Both restored byte for byte.