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

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.