230 lines
17 KiB
Markdown
230 lines
17 KiB
Markdown
# 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.
|