row 283 (#1788): design draft 2 folds webby-0169 R1 (editor refuses < and >, T3, M6b) and N1 (check 8 compares NFC and case, NFD case in T6, M4b); Q2-Q4 accepted, Q4 handoff to C2-02 in BUILD.md; doc only

agents/honker/work/queue-283/DESIGN.md

@@ -0,0 +1,191 @@
+# Row 283 (#1788) C2-01d design, draft 2 (Honker)
+
+Brief: docs/plans/2026-10-20_case2-rows.md "C2-01d" at refactor 94c33a43c. Sources: the design at
+agents/gosalyn/work/case2/DESIGN.md b68d79663, the ruling after r11 (:207), the M12 paragraph (:300),
+1.1 (:755) and 1.2 (:817). Base 94c33a43c. Reviewer Webby, gate owner Sage. Nothing is built yet. The
+build waits for 282 to land (sage-2906).
+
+## 1. Mapping (packages/library/src/mapping.mjs)
+
+`supporting`:
+- Every universe kind takes an optional `supporting` list: plain `['name','books','playground','supporting']`,
+  hybrid adds it to its seven keys, and a draft gets `['kind','name','playground','supporting']`.
+- Each value is checked as a playground prefix is: a string ending in `/` whose body passes `folder()`.
+- The output carries `supporting` on every universe, `[]` when absent, the way a draft carries
+  `books: []`. classify then needs no `?? []`. The business writer writes the raw document
+  (organization.mjs:195), not this output, so no business file changes shape.
+- The prefix rules, across every entry (ruling after r11):
+  - A supporting prefix holding another supporting prefix, or one listed twice, refuses
+    `library-mapping-invalid`.
+  - A prefix equal to one of its own entry's book folders, or holding one, refuses `library-mapping-invalid`.
+  - A prefix inside or holding another entry's book folder refuses `library-supporting-other-universe`.
+  - Level comes from where the prefix sits, as for the playground: inside one of its own entry's books
+    is book level, and outside every book is universe level. A draft's prefixes are all universe level.
+- Between the two lists (my choice, Q2):
+  - A supporting prefix may equal a playground prefix of the same entry. That folder is writable.
+  - A playground prefix may hold a supporting prefix of the same entry. The inner folder is supporting
+    and the rest stays playground.
+  - A supporting prefix that holds a playground prefix refuses `library-mapping-invalid`. classify
+    checks supporting first, so that playground prefix could never match.
+  - A supporting prefix equal to, holding or inside a playground prefix of another entry refuses
+    `library-mapping-invalid`. Otherwise one path would have two universes.
+- The book loop at mapping.mjs:128-140 becomes a helper that both lists call with their own code and
+  label. The playground's messages and codes stay byte-equal, so no existing test text moves.
+
+`editor`:
+- The entry takes an optional `editor`. When present, it is an object with exactly the keys `name` and
+  `email` (via `only()`). Each value is a string that is non-empty after trim and has no control
+  character (`[\u0000-\u001f\u007f-\u009f]`), `<` or `>` (webby-0169 R1: git drops them from an ident
+  and commits under a different name, so C2-02 would never see a failure). Anything else refuses
+  `library-mapping-invalid`.
+- The output carries `editor: { name, email }` only when present, as `user` and `vaultPrefix` do. A save
+  with no `editor` refusing is C2-02's job.
+
+## 2. Scope (scope.mjs)
+
+- `classify` gets a supporting loop before the playground loop (design 1.2). It returns `place(...)`
+  with `{ scope: 'supporting', universe, book }`. The book is the book folder holding the prefix, or
+  null at universe level and in a draft. The type and folder come from the first folder under the
+  prefix, as for the playground.
+- The `.md` check stays first, so a `.canvas` or `.base` under a supporting prefix stays unmapped.
+- The comment above `classify` names the three prefix scopes and the order.
+
+## 3. supportingPath (new supporting.mjs)
+
+`supportingPath(mapping, universe, path, tree)` returns `path` or throws
+`LibraryError('library-write-story-path', ...)`. It is pure and reads no git.
+
+- `tree` is the array `listTree` returns (reader.mjs:26, `{ mode, type, oid, size, path }`), so the
+  C2-02 broker passes its listing as it is (Q3). A non-array `tree` throws a TypeError, because that is
+  a caller bug, not a path class.
+- The checks run in this order, each with its own message naming the class:
+  1. The path must be a string of at most 1,024 UTF-8 bytes (`Buffer.byteLength`).
+  2. It must have no control character, using the same control class as `editor` (not `<` or `>`).
+  3. It must have no backslash.
+  4. It must not be absolute (a leading `/`).
+  5. It must have no empty, `.` or `..` segment. That also catches `//` and a trailing `/`.
+  6. `classify(mapping, path)` must give scope `supporting` and that same `universe`. This one check
+     covers an unknown universe, an unmapped path, a `.canvas`, `.base` or attachment, a canon or
+     story path, a playground path that isn't also supporting, and another universe's prefix. The scope
+     rule then has one source, and M1 below hits both.
+  7. Every proper prefix of the path (`a`, `a/b`, ...) and the path itself must not be in `tree` with
+     mode `120000` (symlink) or `160000` (gitlink).
+  8. No prefix of the path, and not the path itself, may equal a tree path or a tree directory
+     (derived from the entries' paths) after `normalize('NFC').toLowerCase()` on both sides, unless
+     it equals that tree path exactly. NFC as well as case, because APFS treats NFC and NFD forms of
+     a name as one file (webby-0169 N1).
+     Directories are checked too, because the folders under a supporting prefix are hers to name. A
+     path in a tree that holds both `a.md` and `A.md` refuses, which matches R7.
+- The refusal messages quote the path with JSON, except for the control-character class, whose message
+  leaves the path out.
+- The delete rule ("A delete also needs the path to exist at the tip as a 100644 blob", M12) isn't in
+  the brief's supportingPath list. It stays with C2-02's delete (Q4).
+  The C2-02 brief doesn't name it (only design :308), so BUILD.md carries it to C2-02 under Handoffs
+  (webby-0169 Q4).
+- index.mjs exports `supportingPath`.
+
+## 4. README (packages/library/README.md)
+
+- Mapping: `supporting` and its rules, the cross-list rules, and `editor`.
+- Refusals: a `library-supporting-other-universe` row, and the new cases in the
+  `library-mapping-invalid` row.
+- Scope: supporting first, then playground, then canon.
+- A new section, "Agent write paths", for supportingPath and its classes.
+
+## 5. Callers of classify outside files owned (Q1 for Sage)
+
+- survey.mjs:65 builds `{ canon: 0, playground: 0, unmapped: 0 }` and increments
+  `scopes[classify(...).scope]`. A supporting file adds `supporting: NaN`, and formatSurvey (:92) never
+  prints it. I propose a departure: add `supporting: 0` and print it, so the line becomes
+  `scopes canon 5, playground 1, supporting 0, unmapped 3; indexed 6`. That re-pins survey.test:73 and
+  adds a count test. Without it, the survey reports garbage once she marks a folder. The departure
+  covers two files, packages/library/src/survey.mjs and packages/library/tests/survey.test.mjs.
+- No change in the rest, each for a reason:
+  - reader.mjs:183 skips only unmapped, so supporting files are indexed like playground files.
+  - R5 (:207) flags only canon to playground, as design 1.3 R5 says. A canon link to a supporting file
+    raises nothing.
+  - render.mjs:23 gives supporting a null badge. The supporting badge belongs to C2-10b (design :1415).
+  - mirror.mjs:246 refuses only unmapped. Reading supporting files by scope is C2-05c's.
+  - No bus or webui source filters on scope (git grep at 94c33a43c).
+- M9 already protects the whole `projects` key from agent edits (library-projects-protected.test). No
+  test is added there.
+
+## 6. Tests
+
+- mapping.test:
+  - T1: `supporting` at book level, at universe level, in a hybrid and in a draft. The output carries
+    it, with `[]` when absent. The draft `deepEqual` at :48 gains `supporting: []`.
+  - T2: one test per prefix rule.
+    - These refuse `library-mapping-invalid`: no trailing `/`, a bad folder, one holding another, one
+      listed twice, one equal to its own book, one holding its own book, one holding a playground
+      prefix, and one overlapping another entry's playground.
+    - These refuse `library-supporting-other-universe`: one inside another universe's book, and one
+      holding another universe's book.
+    - An equal same-entry playground passes.
+  - T3: `editor` passes, and absent passes. It refuses `library-mapping-invalid` for a non-object, an
+    array, an extra key, a missing key, an empty or blank value, a non-string, and a control character,
+    `<` or `>` in either value.
+- scope.test, T4:
+  - Supporting at book level, universe level and in a draft each give their universe and book.
+  - A folder in both lists is `supporting`, and a playground-only folder is `playground`.
+  - A supporting `.canvas` or `.base` is unmapped.
+- supporting.test (new):
+  - T5 passes at book level, universe level, in a draft, in a both-lists folder, and at exactly 1,024 bytes.
+  - T6 has one refusal per class against a fixture tree with a symlink, a gitlink and a case variant.
+    The classes are:
+    - unmapped, `.canvas`, `.base`, an attachment, canon, playground-only, another universe's
+      supporting prefix, and an unknown universe;
+    - absolute, `..`, `.`, `//`, a trailing `/`, a backslash, a C0 control and DEL;
+    - a symlink folder, a gitlink folder, and a symlink at the path itself;
+    - a case-variant file, a case-variant folder, and an NFD-form variant of an NFC tree name;
+    - 1,025 bytes made with a multi-byte character, so bytes and characters differ.
+  - Each asserts the code `library-write-story-path`.
+- business.test: T7 adds one assertion that `validateBusinessDocument` refuses
+  `library-supporting-other-universe`.
+- survey.test (only if Q1 is approved): T8 counts one supporting file, and :73 is re-pinned.
+
+## 7. Mutants (exact strings go in BUILD.md)
+
+| Mutant | Change | Killed by |
+|---|---|---|
+| M1 | classify checks playground before supporting (the brief's mutant) | T4 both-lists, T5 both-lists |
+| M2 | the other-universe fail for supporting is dropped | T2 |
+| M3 | the symlink and gitlink check is dropped | T6 |
+| M4 | the case check is dropped | T6 |
+| M4b | check 8 drops `normalize('NFC')` | T6 NFD variant |
+| M5 | the byte length uses `path.length` | T6 1,025 bytes |
+| M6 | the `editor` control-character check is dropped | T3 |
+| M6b | the `editor` `<` and `>` check is dropped | T3 |
+| M7 | supportingPath skips the universe match | T6 other universe |
+| M8 | the supporting-holds-playground check is dropped | T2 |
+
+## 8. Gate
+
+- Webby approves the manifest.
+- The library and business suites and every scripts/test-*.sh are green on Sage's gate.
+- Timeouts (mos-1275): each package `timeout -k 10 1800`, each script `timeout -k 10 300`, each single
+  file and mutant `timeout -k 10 600`. These come from my row 256 gate at 10:34Z.
+- Before in-review, grep packages/*/tests for 64-hex pins on the changed files and for the changed
+  message text, then drift-check BASE..refactor.
+
+## 9. Questions
+
+- Q1 (Sage): approve the survey.mjs and survey.test.mjs departure in section 5?
+- Q2 (Webby): the cross-list rules in section 1?
+- Q3 (Webby): `tree` as the `listTree` array?
+- Q4 (Webby): the delete's 100644 check stays with C2-02?
+- Q5 (Webby): `editor` refuses only blank values and control characters, as the brief says. `<` and `>`
+  would break a git ident. I'd leave them to C2-02's commit step unless you want them refused here.
+
+## 10. Draft 2 (webby-0169)
+
+- R1 folded: `editor` refuses `<` and `>` too, with T3 cases and mutant M6b.
+- Q2 accepted. BUILD.md records the tradeoff: refusing a supporting prefix that holds a playground
+  prefix goes past the brief, but it is the fail-closed reading and uses an existing code. The cost
+  is that she can't nest a playground under a supporting folder, though she can nest the other way.
+- Q3 accepted. Q4: carried to C2-02 under Handoffs in BUILD.md, and Sage was asked to add it to C2-02's brief.
+- N1 folded into check 8 (NFC and case), with an NFD case in T6 and mutant M4b.
+- N2: the survey.test:73 pin gains only `supporting`, and the count test is the only addition
+  (mos-1330, its own commit).
+- N3: before the build, re-grep tests outside packages/library for a `deepEqual` of the mapping output
+  on the build base.