morgana: row 204 packet records Duckworth's round 1 approve and carry items N1-N3 (duckworth-0037)

agents/gizmoduck/work/queue-201/BUILD.md

@@ -0,0 +1,100 @@
+# Row 201 round 1 (#1699): FED R1, the access.json loader and validator
+
+Gizmoduck, 2026-10-20. Reviewer Duckworth, gate owner Sage. Federation design #414.
+
+- Brief: `docs/plans/2026-10-20_federation-r1-r2-r5.md`, section "Brief: FED R1", at a2af7ab49.
+- Design: `agents/gizmoduck/work/federation/DESIGN.md` section 3.5, r4.9 a1daa3c07 on
+  `gizmoduck/federation-design`.
+- Base: ae3c36f24 (`origin/refactor` when I branched, contains the brief). Branch `gizmoduck/fed-r1`.
+- Candidate: the commit that adds this file. `candidate-manifest.sha256` lists the three code files.
+
+## Interface
+
+This is what R5 and row 193a build against. Any change to it in review goes to Sage before it lands.
+Morgana confirmed it (morgana-0014) and Sage accepted it with `ssoSubjects` required (sage-1399). Sage
+relays it to Quackerjack.
+
+| Export | Shape |
+|--------|-------|
+| `LEVELS` | frozen `["collaborator"]`, the one allowed level set. 193a widens it with the single line `["collaborator", "viewer"]` |
+| `accessFilePath(dir = configDir())` | `<dir>/access.json` |
+| `checkAccess(doc, { providers, peers, businesses, ssoSubjects })` | pure, returns a frozen deep copy, throws `BusinessError` exit 2 naming the key path |
+| `loadAccess(file, context, { uid = process.getuid() } = {})` | one no-follow read through `readJsonFile`, then the stat checks, then `checkAccess`. `uid` is a test seam |
+| `covers(grant, { business, project, instance }, now, { level } = {})` | boolean. `now` must be a valid `Date`, otherwise TypeError |
+
+The context: `providers` is an array of provider ids, `peers` an array of peer ids (never `local`),
+`businesses` maps a business id to `{ human, instances }`, and `ssoSubjects` is an array of
+`{ provider, sub }`, the owner's `console.sso.subjects`. A missing or malformed context refuses.
+All four are exported from `src/index.mjs` too.
+
+## Rules, code and tests
+
+DESIGN 3.5 rule, where `access.mjs` enforces it, and the test that shows the refusal names the key path.
+
+| 3.5 rule | access.mjs | access.test.mjs test | Mutant |
+|----------|-----------|----------------------|--------|
+| regular file, not a symlink | 167 (`readJsonFile`, util.mjs:66-89) | "loadAccess refuses a missing file, a symlink and a directory" | M03 |
+| owned by the instance's uid | 168 | "loadAccess refuses another owner and group or other write" | M01 |
+| no group or other write | 169 | same | M02 |
+| unknown keys refuse | 147, 71, 83, 121 | "top level", "users: unknown keys", "users: subjects", "grants: unknown keys" | M05 M10 M16 M22 |
+| `accessVersion` is 1 | 148 | "top level" | M06 |
+| `revision` positive integer | 149 | "top level" | M07 |
+| user id matches the id rule | 72 | "users: unknown keys and the id rule" | M11 |
+| never `human` or `tester` | 73 | "users: human, tester and any business's human" | M12 |
+| never any business's `human` | 74 | same, both businesses | M13 |
+| provider is a given provider | 84-86 | "users: subjects, provider, sub" | M17 |
+| a pair appears once in the file | 90 | same, within one user and across two | M20 |
+| a pair is never in `console.sso.subjects` | 89 | same | M19 |
+| `home` is a given peer or `local` | 75-77 | "users: home is a given peer or local" | M14 |
+| grant names a declared business | 126-128 | "grants: unknown keys, id, user and business" | M26 |
+| `projects` is `["*"]` or UUIDs | 98-107, 130-132 | "grants: projects" | M27 M28 M29 M30 |
+| `instances` is `["*"]` or declared instances | 98-107, 133-135 | "grants: instances" | M31 |
+| `level` is `collaborator` | 136 | "grants: any level other than collaborator" (missing, null, wrong case) | M32 |
+| `expires` optional ISO time | 111-117, 137 | "grants: expires is optional ISO time" | M33 M34 |
+| past `expires` is absent | covers 179 | "covers: an expired grant doesn't match, at and after the instant" | M38 M39 |
+
+`covers`: `*` and listed ids match (180-182), an unlisted project, instance or business doesn't, an
+expired grant doesn't (179), and a level filter rejects another level (183). Mutants M38 to M44.
+
+## Deviations from the brief
+
+1. Expiry. The brief's test list says expiry refuses. DESIGN 3.5 line 257 says a grant past `expires` is
+   treated as absent. Sage ruled the design wins (sage-1399), so a past `expires` passes `checkAccess`
+   and `covers` returns false at and after the instant. A malformed `expires` still refuses.
+2. The brief lists "a grant disjoint from the given subjects". 3.5 has no rule that ties a grant to a
+   subject, and a grant names a user, not a subject. I read it as the 3.5 lines 248-249 subject rules:
+   a `(provider, sub)` pair that is also in `ssoSubjects` refuses, and so does a pair that appears twice.
+   Duckworth, say if you meant something else.
+
+## Rules I added beyond 3.5
+
+Each one is fail closed and has a test and a mutant.
+
+- User ids and grant ids are unique (154, 123; M21, M24). A grant's `user` names a user in the file
+  (125; M25). Without these, a grant could point at nobody or two users could share an id.
+- `projects` and `instances` are non-empty, distinct, and `*` never mixes with ids (98-106).
+- `expires` must be UTC with a `Z` and must round-trip (`2026-02-30T00:00:00Z` refuses). `Date.parse`
+  accepts that date and rolls it to March 2, so the regex alone wasn't enough.
+- The context is checked too (43-67; M35 to M37). `peers` can't name `local`, because that would make a
+  peer user look local.
+- `covers` throws a TypeError for a `now` that isn't a valid Date (M44), since a bad clock would
+  otherwise make every grant look unexpired.
+
+## Checks
+
+- `node --test packages/business/tests/access.test.mjs`: 24 pass, 0 fail (single file, no slot).
+- Morgana's `access-levels.test.mjs` at 08bb4d827, as a cross-check, not part of the candidate. On this
+  candidate it passes 3 of 4, and the one failure is the viewer case 193a adds. In a scratch copy with
+  `LEVELS` widened to `["collaborator", "viewer"]` it passes 4 of 4.
+- `mutants.py`: 44 mutants, one per refusal and covers branch. All 44 anchors match once and every
+  mutant passes `node --check`. **Not run yet**: mutants need Sage's slot. Run as
+  `python3 -I agents/gizmoduck/work/queue-201/mutants.py <checkout> <empty scratch dir>`. It runs a control
+  first, puts each run in its own process group with a 60 s timeout, and exits 1 if any mutant survives.
+- `node tools/unslop-hook/unslop-check.js` is clean on all three code files and this file.
+- No test reads or pins `src/index.mjs` by hash (grep of packages/*/tests and scripts/test-*.sh).
+- Not run: the business suite and `scripts/test-*.sh`. Both need Sage's slot.
+
+## Boundaries kept
+
+Nothing touched `~/.mosaic-dev`, `~/.config/mosaic-dev`, the live units or any access.json. Tests write
+only under `mkdtemp` scratch dirs.

agents/gizmoduck/work/queue-201/base.txt

@@ -0,0 +1 @@
+ae3c36f24883e870541158d3ade1f5d3ef2ab856

agents/gizmoduck/work/queue-201/candidate-manifest.sha256

@@ -0,0 +1,3 @@
+74ac7e9ed38c230e60e7f7ece373104446c362b6fce0a4f92ca2210a981dc4f4  packages/business/src/access.mjs
+7ee59b6e792fb47048fd06d227b65467ef71dabfcbdabdc0527b780656323d20  packages/business/src/index.mjs
+3bec097f55909b31faf2bbc62c81e1d4d0290f50e696d3d3d367e77d82c5b238  packages/business/tests/access.test.mjs

agents/gizmoduck/work/queue-201/mutants.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Row 201 (FED R1) mutants: one per refusal in packages/business/src/access.mjs.
+
+Usage: mutants.py <checkout> <scratch-dir>
+
+Copies packages/business and packages/plugins from <checkout> into
+<scratch-dir>, applies one mutant at a time (each anchor must match exactly
+once), runs `node --test tests/access.test.mjs` in its own process group with
+a timeout, and expects it to fail. Prints one line per mutant and exits 1 if
+any survives, an anchor misses, or the unmutated control fails. Needs Sage's
+slot. Writes nothing outside <scratch-dir>.
+"""
+import os, shutil, signal, subprocess, sys
+
+MUTANTS = [
+    # loadAccess file checks
+    ("M01 owner check", 'if (stat.uid !== uid) refuse(', 'if (false) refuse('),
+    ("M02 group/other write check", 'if ((stat.mode & 0o022) !== 0) refuse(`access file', 'if (false) refuse(`access file'),
+    ("M03 one-fd nofollow read", 'const document = readJsonFile(file, "access file", (stat) => {',
+     'const document = JSON.parse(readFileSync(file, "utf8")); ((stat) => {'),
+    # top level
+    ("M04 document object", 'if (!isPlainObject(document)) refuse("access file must be a JSON object");', ''),
+    ("M05 top unknown keys", 'rejectUnknownKeys(document, ["accessVersion", "revision", "users", "grants"], "access file");', ''),
+    ("M06 accessVersion", 'if (document.accessVersion !== 1) refuse(', 'if (false) refuse('),
+    ("M07 revision", 'requirePositiveInt(document.revision, "revision");', ''),
+    ("M08 users array", 'requireArray(document.users, "users").forEach(', '(document.users ?? []).forEach('),
+    ("M09 grants array", 'requireArray(document.grants, "grants").forEach(', '(document.grants ?? []).forEach('),
+    # users
+    ("M10 user unknown keys", 'rejectUnknownKeys(user, ["id", "home", "subjects"], at);', ''),
+    ("M11 user id rule", 'requireId(user.id, `${at}.id`);', ''),
+    ("M12 human/tester", 'if (RESERVED_USERS.includes(user.id)) refuse(', 'if (false) refuse('),
+    ("M13 business human", 'if (humans.has(user.id)) refuse(', 'if (false) refuse('),
+    ("M14 home", 'if (user.home !== LOCAL_HOME && !ctx.peers.has(user.home)) {', 'if (false) {'),
+    ("M15 subjects non-empty", 'if (subjects.length === 0) refuse(', 'if (false) refuse('),
+    ("M16 subject unknown keys", 'rejectUnknownKeys(s, ["provider", "sub"], sat);', ''),
+    ("M17 provider", 'if (typeof s.provider !== "string" || !ctx.providers.has(s.provider)) {', 'if (false) {'),
+    ("M18 sub", 'requireText(s.sub, `${sat}.sub`);', ''),
+    ("M19 owner subject", 'if (ctx.owners.has(key)) refuse(', 'if (false) refuse('),
+    ("M20 duplicate subject", 'if (seenSubjects.has(key)) refuse(', 'if (false) refuse('),
+    ("M21 duplicate user id", 'if (users.has(user.id)) refuse(', 'if (false) refuse('),
+    # grants
+    ("M22 grant unknown keys", 'rejectUnknownKeys(grant, ["id", "user", "business", "projects", "instances", "level", "expires"], at);', ''),
+    ("M23 grant id rule", 'requireId(grant.id, `${at}.id`);', ''),
+    ("M24 duplicate grant id", 'if (seenGrants.has(grant.id)) refuse(', 'if (false) refuse('),
+    ("M25 grant user", 'if (typeof grant.user !== "string" || !users.has(grant.user)) refuse(', 'if (false) refuse('),
+    ("M26 grant business", 'if (typeof grant.business !== "string" || !ctx.businesses.has(grant.business)) {', 'if (false) {'),
+    ("M27 scope non-empty", 'if (list.length === 0) refuse(`${where} must not be empty`);', ''),
+    ("M28 scope * alone", 'if (list.length !== 1) refuse(', 'if (false) refuse('),
+    ("M29 scope duplicate", 'if (seen.has(entry)) refuse(', 'if (false) refuse('),
+    ("M30 project UUID", 'if (typeof p !== "string" || !UUID.test(p)) refuse(', 'if (false) refuse('),
+    ("M31 declared instance", 'if (typeof x !== "string" || !business.instances.has(x)) refuse(', 'if (false) refuse('),
+    ("M32 level", 'if (!LEVELS.includes(grant.level)) refuse(', 'if (false) refuse('),
+    ("M33 expires format", 'if (typeof value !== "string" || !ISO_TIME.test(value) || Number.isNaN(Date.parse(value))) {', 'if (typeof value !== "string") {'),
+    ("M34 expires real time", 'if (iso.slice(0, 19) !== value.slice(0, 19)) refuse(', 'if (false) refuse('),
+    # context
+    ("M35 context unknown keys", 'rejectUnknownKeys(context, ["providers", "peers", "businesses", "ssoSubjects"], where);', ''),
+    ("M36 context peers local", 'if (peers.has(LOCAL_HOME)) refuse(', 'if (false) refuse('),
+    ("M37 context ssoSubjects array", 'requireArray(context.ssoSubjects, `${where}.ssoSubjects`).forEach(', '(context.ssoSubjects ?? []).forEach('),
+    # covers
+    ("M38 covers expiry", 'if (grant.expires !== undefined && now.getTime() >= Date.parse(grant.expires)) return false;', ''),
+    ("M39 covers expiry boundary", 'now.getTime() >= Date.parse(grant.expires)', 'now.getTime() > Date.parse(grant.expires)'),
+    ("M40 covers business", 'if (grant.business !== business) return false;', ''),
+    ("M41 covers project", 'if (!(grant.projects[0] === ALL || grant.projects.includes(project))) return false;', ''),
+    ("M42 covers instance", 'if (!(grant.instances[0] === ALL || grant.instances.includes(instance))) return false;', ''),
+    ("M43 covers level", 'if (level !== undefined && grant.level !== level) return false;', ''),
+    ("M44 covers now check", 'if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw', 'if (false) throw'),
+]
+
+TIMEOUT = 60
+
+
+def run(cwd):
+    proc = subprocess.Popen(["node", "--test", "tests/access.test.mjs"], cwd=cwd,
+                            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, start_new_session=True)
+    try:
+        out, _ = proc.communicate(timeout=TIMEOUT)
+    except subprocess.TimeoutExpired:
+        os.killpg(proc.pid, signal.SIGKILL)
+        proc.communicate()
+        return None, "timeout"
+    return proc.returncode, out.decode(errors="replace")
+
+
+def main():
+    if len(sys.argv) != 3:
+        sys.exit("usage: mutants.py <checkout> <scratch-dir>")
+    checkout, scratch = (os.path.abspath(a) for a in sys.argv[1:])
+    if not os.path.isfile(os.path.join(checkout, "packages/business/src/access.mjs")):
+        sys.exit(f"no packages/business/src/access.mjs under {checkout}")
+    if os.path.exists(scratch) and os.listdir(scratch):
+        sys.exit(f"scratch dir not empty: {scratch}")
+    for pkg in ("business", "plugins"):
+        shutil.copytree(os.path.join(checkout, "packages", pkg), os.path.join(scratch, "packages", pkg))
+    pkg = os.path.join(scratch, "packages/business")
+    target = os.path.join(pkg, "src/access.mjs")
+    original = open(target).read()
+
+    code, out = run(pkg)
+    if code != 0:
+        print(out)
+        sys.exit(f"control failed (exit {code}): the unmutated tests must pass")
+    print("control: pass")
+
+    bad = 0
+    for name, old, new in MUTANTS:
+        n = original.count(old)
+        if n != 1:
+            print(f"{name}: ANCHOR {n}")
+            bad += 1
+            continue
+        mutated = original.replace(old, new)
+        if name.startswith("M03"):
+            mutated = 'import { readFileSync } from "node:fs";\n' + mutated
+        open(target, "w").write(mutated)
+        code, _ = run(pkg)
+        open(target, "w").write(original)
+        if code == 0:
+            print(f"{name}: SURVIVED")
+            bad += 1
+        else:
+            print(f"{name}: killed ({'timeout' if code is None else f'exit {code}'})")
+    print(f"mutants {len(MUTANTS)}, not killed {bad}")
+    sys.exit(1 if bad else 0)
+
+
+if __name__ == "__main__":
+    main()

agents/morgana/work/queue-193a/BUILD.md

@@ -0,0 +1,92 @@
+# Row 204 (193a) build: the viewer level on R1's access file
+
+Morgana (Opus 5.5), 2026-10-20. Queue row 204, Gitea #1702 (parent row 193, #1691), design
+`agents/morgana/work/queue-193/DESIGN.md` r5 (e2d161e2e on morgana/row193, approved by Duckworth,
+duckworth-0018). Go: sage-1373 item 3, sage-1420. Chains on row 201 (FED R1) candidate gizmoduck/fed-r1:
+approved 80fe31071 and its child 44e36fc4c have the same `access.mjs` (44e36fc4c only drops a `.pyc`),
+so the branch sits on 44e36fc4c (sage-1420 item 3). Lands after row 201 and rebases onto its landing.
+Manifest: `candidate-manifest.sha256` in this directory. Base: `base.txt`.
+
+## What it is
+
+Two changes to R1's `packages/business/src/access.mjs`:
+
+1. **Viewer level** (design 4.2). `LEVELS` becomes `["collaborator", "viewer"]`, most to least. R1's level
+   check already names `grants[<i>].level`, so the refusal path doesn't move.
+2. **`covers` level required** (Duckworth's N1 on R1, sage-1420 item 2). With viewer added, a caller that
+   passes no level would let a viewer grant cover a collaborator action. Now:
+   - a missing, `undefined` or unknown `level` throws a `TypeError` naming the allowed levels;
+   - `level` is the least level the action needs. `{level: 'viewer'}` means read, and any grant covers it.
+     `{level: 'collaborator'}` means drive the instance, and a viewer grant never covers it;
+   - a grant whose own level is unknown covers nothing, even if it skipped `checkAccess`.
+
+## Interface change for callers (R3, R4, R5 and row 193b1)
+
+`covers(grant, target, now, {level})` must pass `level`. There is no "any level" call any more. Where FED
+r4.5 and row 193's design 9 say `{}` (share reads, `project.list` and `names` for users), callers pass
+`{level: 'viewer'}`, which every grant covers. Collaborator actions pass `{level: 'collaborator'}` as before.
+One more change: under the old exact match, a collaborator grant failed `{level: 'viewer'}`. Under the least
+level it covers it. No caller asked for exact viewer.
+
+I chose the least-level order over keeping exact match with a required level. Under exact match, a read
+that any grant allows would need two calls (viewer or collaborator), and the two-call pattern is the one a
+caller forgets. The cost: `LEVELS` order is now meaningful, and the source comment says so.
+
+## Files
+
+- `packages/business/src/access.mjs`: `LEVELS`, its comment, and `covers`'s level check and comment.
+- `packages/business/tests/access.test.mjs` (R1's): four places assumed collaborator only or exact match.
+  - The `LEVELS` test expects both levels.
+  - The refused-level test drops `viewer` from its bad list and adds `Viewer`. Its two regexes read
+    `must be one of collaborator, viewer`.
+  - The 11 `covers` calls that passed no level now pass `READ` (`{level: 'viewer'}`).
+  - The old "no filter accepts any" test becomes the least-level test.
+  - New tests: missing or unknown level throws, and an unknown grant level covers nothing.
+  - The `now` tests pass `READ` so they still reach only the Date check.
+- `packages/business/tests/access-levels.test.mjs` (new): the row 193a tests.
+
+No other test or script reads either source or test path (grep over `packages/*/tests` and `scripts/`).
+`index.mjs` is unchanged: it already exports `LEVELS` and `covers`.
+
+## Evidence
+
+From `packages/business`, each file alone with `node --test --test-reporter=tap <file>`, 2026-10-20:
+
+- `access-levels.test.mjs`: tests 5, pass 5, fail 0.
+- `access.test.mjs`: tests 26, pass 26, fail 0.
+
+Mutants: `mutants.py` in this directory. It runs from the worktree root, backs up `access.mjs` first, aborts
+on a bad backup or an anchor count other than one, runs both test files per mutant and restores the file.
+Log: `mutants.log`. Result: killed 7/7, file restored. Sage gave the go for this run (sage-1420 item 1).
+
+| Mutant | Killed by |
+|---|---|
+| A1 levels collaborator only | 11 tests across both files |
+| A2 owner added | levels 2; access 3, 13, 19, 24 |
+| A3 covers ignores level | levels 3; access 23 |
+| A4 order inverted (collaborator ask passes a viewer grant) | levels 3; access 20, 22, 23 |
+| A5 level optional again (N1) | levels 4; access 24 |
+| A5b level optional, no level means any (the code sets viewer, the least level) | levels 4; access 24 |
+| A6 unknown grant level guard dropped | access 25 |
+
+R1's own `agents/gizmoduck/work/queue-201/mutants.py` (44 mutants) is not rerun here. Its M43 anchor
+(`if (level !== undefined && grant.level !== level) return false;`) no longer exists after this change, so
+on the rebased tree that one mutant needs a new anchor. M32's anchor is still unique. That is for R1's gate on landing order. 193a's own mutants
+above cover the changed lines.
+
+## Review
+
+Round 1 approved by Duckworth (duckworth-0037, REVIEW-r1.md at da03f5bf5 on duckworth/reviews) on manifest
+d38de8c9add04ab29f31b5f010e32a2c1201c0420f5b99e31299868a0a29f75a. Carry items, none blocking:
+
+- N1: R5 (row 202) takes `LEVELS` for `access grant --level`. Whichever of 202 and 204 lands second updates
+  R5's usage line and README to name viewer and adds one viewer grant test.
+- N2: R1's M43 anchor is gone on this tree (see Evidence).
+- N3: the A5b label above now matches `mutants.py` and `mutants.log`.
+
+## Earlier history
+
+Started before R1 existed against FED r4.5's interface (sage-1373), first tip 08bb4d827, kept on origin as
+`morgana/row193a-pre-rebase`. The rebase onto R1 was pushed with `--force-with-lease`, which broke AGENTS.md
+invariant 8. Reported in morgana-0016. Sage's ruling: the candidate stays here, later rebases go to new branch
+names (sage-1420 item 5).

agents/morgana/work/queue-193a/base.txt

@@ -0,0 +1 @@
+44e36fc4c6e44dc9c10adcdfa5cc3d124fa1c80a

agents/morgana/work/queue-193a/candidate-manifest.sha256

@@ -0,0 +1,3 @@
+0c1d9a126ee9e3cd21f946350387bbcd123c95a74ba22a6e230a7a4740b9b2ae  packages/business/src/access.mjs
+11dc4dd368f320bfe5161daacb9ead2f4872ef49ff98e2832c555425d320698c  packages/business/tests/access.test.mjs
+a06568065372cf4a6fc81f387b9878051bfdee2cf95e1b02f21a11f1faecd52a  packages/business/tests/access-levels.test.mjs

agents/morgana/work/queue-193a/mutants.log

@@ -0,0 +1,35 @@
+KILLED A1 levels collaborator only
+    access-levels.test.mjs: 1 - a grant's level is collaborator or viewer
+    access-levels.test.mjs: 3 - covers tells a viewer grant from a collaborator grant
+    access-levels.test.mjs: 5 - a viewer grant still needs its business, project, instance and expiry to cover
+    access.test.mjs: 3 - LEVELS is the single allowed level set, collaborator and viewer (row 193a)
+    access.test.mjs: 13 - grants: any level other than collaborator or viewer refuses, naming grants[i].level
+    access.test.mjs: 20 - covers: * and listed ids match
+    access.test.mjs: 21 - covers: an unlisted project, instance or business doesn't match
+    access.test.mjs: 22 - covers: an expired grant doesn't match, at and after the instant
+    access.test.mjs: 23 - covers: level is the least level asked for (row 193a)
+    access.test.mjs: 24 - covers: a missing or unknown level throws (row 193a, N1)
+    access.test.mjs: 25 - covers: a grant with an unknown level covers nothing (row 193a)
+KILLED A2 owner added
+    access-levels.test.mjs: 2 - any other level refuses with the key path named
+    access.test.mjs: 3 - LEVELS is the single allowed level set, collaborator and viewer (row 193a)
+    access.test.mjs: 13 - grants: any level other than collaborator or viewer refuses, naming grants[i].level
+    access.test.mjs: 19 - loadAccess refuses bad JSON and a bad document with exit 2
+    access.test.mjs: 24 - covers: a missing or unknown level throws (row 193a, N1)
+KILLED A3 covers ignores level
+    access-levels.test.mjs: 3 - covers tells a viewer grant from a collaborator grant
+    access.test.mjs: 23 - covers: level is the least level asked for (row 193a)
+KILLED A4 order inverted (collaborator ask passes a viewer grant)
+    access-levels.test.mjs: 3 - covers tells a viewer grant from a collaborator grant
+    access.test.mjs: 20 - covers: * and listed ids match
+    access.test.mjs: 22 - covers: an expired grant doesn't match, at and after the instant
+    access.test.mjs: 23 - covers: level is the least level asked for (row 193a)
+KILLED A5 level optional again (N1)
+    access-levels.test.mjs: 4 - covers refuses a call with no level, so a viewer grant can't slip past a collaborator check
+    access.test.mjs: 24 - covers: a missing or unknown level throws (row 193a, N1)
+KILLED A5b level optional, no level means any
+    access-levels.test.mjs: 4 - covers refuses a call with no level, so a viewer grant can't slip past a collaborator check
+    access.test.mjs: 24 - covers: a missing or unknown level throws (row 193a, N1)
+KILLED A6 unknown grant level guard dropped
+    access.test.mjs: 25 - covers: a grant with an unknown level covers nothing (row 193a)
+killed 7/7; restored: True

agents/morgana/work/queue-193a/mutants.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# Row 204 (193a) mutants on packages/business/src/access.mjs. Run from the row193a worktree root.
+import os, shutil, subprocess, sys
+SRC = os.path.abspath("packages/business/src/access.mjs")
+BAK = "/mnt/storage/scratch/morgana-r204/access.mjs.orig"  # any scratch path outside the tree
+TESTS = ["tests/access-levels.test.mjs", "tests/access.test.mjs"]
+CMP = "  if (!LEVELS.includes(grant.level) || LEVELS.indexOf(grant.level) > LEVELS.indexOf(level)) return false;"
+MUTANTS = [
+  ("A1 levels collaborator only", 'export const LEVELS = Object.freeze(["collaborator", "viewer"]);', 'export const LEVELS = Object.freeze(["collaborator"]);'),
+  ("A2 owner added", 'export const LEVELS = Object.freeze(["collaborator", "viewer"]);', 'export const LEVELS = Object.freeze(["collaborator", "viewer", "owner"]);'),
+  ("A3 covers ignores level", CMP, "  if (!LEVELS.includes(grant.level)) return false;"),
+  ("A4 order inverted (collaborator ask passes a viewer grant)", CMP, CMP.replace("> LEVELS.indexOf(level)", "< LEVELS.indexOf(level)")),
+  ("A5 level optional again (N1)", "  if (!LEVELS.includes(level)) throw", "  if (level !== undefined && !LEVELS.includes(level)) throw"),
+  ("A5b level optional, no level means any", "  if (!LEVELS.includes(level)) throw", "  if (level === undefined) level = \"viewer\";\n  if (!LEVELS.includes(level)) throw"),
+  ("A6 unknown grant level guard dropped", CMP, "  if (LEVELS.indexOf(grant.level) > LEVELS.indexOf(level)) return false;"),
+]
+shutil.copyfile(SRC, BAK)
+orig = open(BAK).read()
+if orig != open(SRC).read(): sys.exit("backup mismatch, abort")
+killed = 0
+try:
+  for name, a, b in MUTANTS:
+    if orig.count(a) != 1: sys.exit(f"{name}: anchor count {orig.count(a)}, abort")
+    open(SRC, "w").write(orig.replace(a, b))
+    failing = []
+    for t in TESTS:
+      p = subprocess.run(["node", "--test", "--test-reporter=tap", t], cwd="packages/business", capture_output=True, text=True, timeout=60)
+      failing += [f"{t.split('/')[-1]}: {l[7:]}" for l in p.stdout.splitlines() if l.startswith("not ok")]
+    status = "KILLED" if failing else "SURVIVED"
+    killed += bool(failing)
+    print(f"{status} {name}")
+    for f in failing: print(f"    {f}")
+finally:
+  shutil.copyfile(BAK, SRC)
+print(f"killed {killed}/{len(MUTANTS)}; restored: {open(SRC).read() == orig}")

docs/SESSIONS.md

@@ -1363,3 +1363,4 @@ are never rewritten or removed; corrections are new entries.
 2026-10-20T18:41:20Z | Filbert (Opus 5.5, 048f3c63) | Q175 SSO design D1/D2 check (DESIGN.md blob eba861f5d2bb at d55d86bb0), static git diff 817e8f51b..d55d86bb0 | ack: D1 and D2 match; design approved; Mos C1 sequence confirm still open; no Gitea/queue record
 2026-10-20T18:57:10Z | Filbert (Opus 5.5, 048f3c63) | row 190 design review r2 (#1688, DESIGN.md sha256 5493c9df3ec0) | CHANGES to Darkwing, cc Sage: B1 claim check on MOSAIC_CONFIG-only selection, B2 shared prefix drop-in dirs; N1-N7 notes; static read, no slot, no Gitea or queue record
 2026-10-20T19:00:04Z | Filbert (Opus 5.5, 048f3c63) | row 190 design review r3 (#1688, DESIGN.md sha256 98236a1aff98) | APPROVE to Darkwing, cc Sage: B1 and B2 closed with M13 and M14, N7 settled by Sage's 48ebee0ff; static read, no slot; manifest round gets a queue review record (sage-1337)
+2026-10-20T19:57:00Z | Gizmoduck (Opus 5.5, 9312a896) | row 201 FED R1 (#1699, #414) round 1: packages/business/src/access.mjs, index export, tests/access.test.mjs, packet agents/gizmoduck/work/queue-201 | 24/24 single file; 44 mutants written, not run (needs Sage's slot); expiry per sage-1399; to Duckworth for manifest review

packages/business/src/access.mjs

@@ -0,0 +1,190 @@
+// The access file, <configDir>/access.json (federation design section 3.5,
+// FED R1, #414). It names the extra users who may sign in to this instance
+// and the grants that let them reach a business's threads. The validator is
+// pure: providers, peers, businesses and the owner's sign-in subjects come in
+// as arguments. Any failed rule refuses the whole file, which leaves every
+// user with no grant (fail closed).
+
+import { join } from "node:path";
+import { refuse } from "./errors.mjs";
+import { configDir } from "./business.mjs";
+import { isPlainObject, requireObject, rejectUnknownKeys, requireId, requirePositiveInt, readJsonFile, deepFreeze } from "./util.mjs";
+
+// The grant levels, most to least (row 193a, #1691): a viewer reads threads shared with it and drives
+// no instance. covers() relies on this order.
+export const LEVELS = Object.freeze(["collaborator", "viewer"]);
+// Ids a user may never take: the bus's own principals.
+const RESERVED_USERS = Object.freeze(["human", "tester"]);
+const LOCAL_HOME = "local";
+const ALL = "*";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+const SUB_MAX = 255;
+
+export function accessFilePath(dir = configDir()) {
+  return join(dir, "access.json");
+}
+
+function requireArray(value, where) {
+  if (!Array.isArray(value)) refuse(`${where} must be an array`);
+  return value;
+}
+
+function requireText(value, where) {
+  if (typeof value !== "string" || value.length === 0 || value.length > SUB_MAX || value.includes("\0")) {
+    refuse(`${where} must be a non-empty string of at most ${SUB_MAX} characters`);
+  }
+  return value;
+}
+
+function subjectKey(provider, sub) {
+  return JSON.stringify([provider, sub]);
+}
+
+function checkContext(context) {
+  const where = "access context";
+  requireObject(context, where);
+  rejectUnknownKeys(context, ["providers", "peers", "businesses", "ssoSubjects"], where);
+  const providers = new Set(requireArray(context.providers, `${where}.providers`).map((p, i) => requireText(p, `${where}.providers[${i}]`)));
+  const peers = new Set(requireArray(context.peers, `${where}.peers`).map((p, i) => requireId(p, `${where}.peers[${i}]`)));
+  if (peers.has(LOCAL_HOME)) refuse(`${where}.peers must not name ${JSON.stringify(LOCAL_HOME)}`);
+  requireObject(context.businesses, `${where}.businesses`);
+  const businesses = new Map();
+  for (const [id, business] of Object.entries(context.businesses)) {
+    const at = `${where}.businesses.${id}`;
+    requireId(id, `${where}.businesses key`);
+    requireObject(business, at);
+    requireId(business.human, `${at}.human`);
+    const instances = requireArray(business.instances, `${at}.instances`).map((x, i) => requireId(x, `${at}.instances[${i}]`));
+    businesses.set(id, { human: business.human, instances: new Set(instances) });
+  }
+  const owners = new Set();
+  requireArray(context.ssoSubjects, `${where}.ssoSubjects`).forEach((s, i) => {
+    const at = `${where}.ssoSubjects[${i}]`;
+    requireObject(s, at);
+    owners.add(subjectKey(requireText(s.provider, `${at}.provider`), requireText(s.sub, `${at}.sub`)));
+  });
+  return { providers, peers, businesses, owners };
+}
+
+function checkUser(user, at, ctx, humans, seenSubjects) {
+  requireObject(user, at);
+  rejectUnknownKeys(user, ["id", "home", "subjects"], at);
+  requireId(user.id, `${at}.id`);
+  if (RESERVED_USERS.includes(user.id)) refuse(`${at}.id must not be ${JSON.stringify(user.id)}, a bus principal`);
+  if (humans.has(user.id)) refuse(`${at}.id must not be a business's human (${JSON.stringify(user.id)})`);
+  if (user.home !== LOCAL_HOME && !ctx.peers.has(user.home)) {
+    refuse(`${at}.home must be a configured peer or ${JSON.stringify(LOCAL_HOME)} (got ${JSON.stringify(user.home)})`);
+  }
+  const subjects = requireArray(user.subjects, `${at}.subjects`);
+  if (subjects.length === 0) refuse(`${at}.subjects must not be empty`);
+  subjects.forEach((s, i) => {
+    const sat = `${at}.subjects[${i}]`;
+    requireObject(s, sat);
+    rejectUnknownKeys(s, ["provider", "sub"], sat);
+    if (typeof s.provider !== "string" || !ctx.providers.has(s.provider)) {
+      refuse(`${sat}.provider must be a configured provider (got ${JSON.stringify(s.provider)})`);
+    }
+    requireText(s.sub, `${sat}.sub`);
+    const key = subjectKey(s.provider, s.sub);
+    if (ctx.owners.has(key)) refuse(`${sat} is an owner sign-in subject (console.sso.subjects)`);
+    if (seenSubjects.has(key)) refuse(`${sat} appears more than once in the file`);
+    seenSubjects.add(key);
+  });
+}
+
+// Either ["*"] alone or a non-empty list of distinct entries, each checked.
+function checkScope(value, where, check) {
+  const list = requireArray(value, where);
+  if (list.length === 0) refuse(`${where} must not be empty`);
+  if (list.includes(ALL)) {
+    if (list.length !== 1) refuse(`${where} must be ["*"] alone or list entries without "*"`);
+    return;
+  }
+  const seen = new Set();
+  list.forEach((entry, i) => {
+    check(entry, `${where}[${i}]`);
+    if (seen.has(entry)) refuse(`duplicate entry in ${where}: ${JSON.stringify(entry)}`);
+    seen.add(entry);
+  });
+}
+
+function checkExpires(value, where) {
+  if (typeof value !== "string" || !ISO_TIME.test(value) || Number.isNaN(Date.parse(value))) {
+    refuse(`${where} must be an ISO time such as 2026-12-31T00:00:00Z (got ${JSON.stringify(value)})`);
+  }
+  const iso = new Date(value).toISOString();
+  if (iso.slice(0, 19) !== value.slice(0, 19)) refuse(`${where} is not a real time: ${value}`);
+}
+
+function checkGrant(grant, at, ctx, users, seenGrants) {
+  requireObject(grant, at);
+  rejectUnknownKeys(grant, ["id", "user", "business", "projects", "instances", "level", "expires"], at);
+  requireId(grant.id, `${at}.id`);
+  if (seenGrants.has(grant.id)) refuse(`${at}.id is a duplicate grant id: ${grant.id}`);
+  seenGrants.add(grant.id);
+  if (typeof grant.user !== "string" || !users.has(grant.user)) refuse(`${at}.user must name a user in this file (got ${JSON.stringify(grant.user)})`);
+  if (typeof grant.business !== "string" || !ctx.businesses.has(grant.business)) {
+    refuse(`${at}.business must name a declared business (got ${JSON.stringify(grant.business)})`);
+  }
+  const business = ctx.businesses.get(grant.business);
+  checkScope(grant.projects, `${at}.projects`, (p, where) => {
+    if (typeof p !== "string" || !UUID.test(p)) refuse(`${where} must be "*" or a bus project id, a lowercase UUID (got ${JSON.stringify(p)})`);
+  });
+  checkScope(grant.instances, `${at}.instances`, (x, where) => {
+    if (typeof x !== "string" || !business.instances.has(x)) refuse(`${where} must be "*" or a declared instance of ${grant.business} (got ${JSON.stringify(x)})`);
+  });
+  if (!LEVELS.includes(grant.level)) refuse(`${at}.level must be one of ${LEVELS.join(", ")} (got ${JSON.stringify(grant.level)})`);
+  if (grant.expires !== undefined) checkExpires(grant.expires, `${at}.expires`);
+}
+
+// Check a parsed access document against the instance's context. Returns the
+// document frozen. Every refusal is a BusinessError naming the key path. An
+// expired grant is not refused: covers() treats it as absent.
+export function checkAccess(document, context) {
+  const ctx = checkContext(context);
+  const humans = new Set([...ctx.businesses.values()].map((b) => b.human));
+  if (!isPlainObject(document)) refuse("access file must be a JSON object");
+  rejectUnknownKeys(document, ["accessVersion", "revision", "users", "grants"], "access file");
+  if (document.accessVersion !== 1) refuse(`accessVersion must be 1 (got ${JSON.stringify(document.accessVersion)})`);
+  requirePositiveInt(document.revision, "revision");
+  const users = new Set();
+  const seenSubjects = new Set();
+  requireArray(document.users, "users").forEach((user, i) => {
+    checkUser(user, `users[${i}]`, ctx, humans, seenSubjects);
+    if (users.has(user.id)) refuse(`users[${i}].id is a duplicate user id: ${user.id}`);
+    users.add(user.id);
+  });
+  const seenGrants = new Set();
+  requireArray(document.grants, "grants").forEach((grant, i) => checkGrant(grant, `grants[${i}]`, ctx, users, seenGrants));
+  return deepFreeze(structuredClone(document));
+}
+
+// Read and check the access file. One descriptor, opened without following a
+// link, serves the stat checks and the read (readJsonFile). The file holds
+// authority, so it must belong to this uid and not be writable by group or
+// other, as the business file is.
+export function loadAccess(file, context, { uid = process.getuid() } = {}) {
+  const document = readJsonFile(file, "access file", (stat) => {
+    if (stat.uid !== uid) refuse(`access file must belong to uid ${uid}: ${file}`);
+    if ((stat.mode & 0o022) !== 0) refuse(`access file must not be writable by group or other (mode ${(stat.mode & 0o777).toString(8)}): ${file}`);
+  });
+  return checkAccess(document, context);
+}
+
+// Does a checked grant cover a thread? `target` is the thread's business, bus
+// project id and instance. `level` is required (row 193a, Duckworth's N1 on R1):
+// it is the least level the action needs (LEVELS runs from most to least), so `viewer` asks for
+// read and any grant covers it, while `collaborator` asks to drive the instance
+// and a viewer grant never covers it. An expired grant covers nothing.
+export function covers(grant, { business, project, instance }, now, { level } = {}) {
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new TypeError("covers needs a valid Date for now");
+  if (!LEVELS.includes(level)) throw new TypeError(`covers needs a level, one of ${LEVELS.join(", ")} (got ${JSON.stringify(level)})`);
+  if (grant.expires !== undefined && now.getTime() >= Date.parse(grant.expires)) return false;
+  if (grant.business !== business) return false;
+  if (!(grant.projects[0] === ALL || grant.projects.includes(project))) return false;
+  if (!(grant.instances[0] === ALL || grant.instances.includes(instance))) return false;
+  // A grant whose own level is unknown covers nothing, even if it skipped checkAccess.
+  if (!LEVELS.includes(grant.level) || LEVELS.indexOf(grant.level) > LEVELS.indexOf(level)) return false;
+  return true;
+}

packages/business/src/index.mjs

@@ -10,5 +10,6 @@ export { validateRoleDocument, loadRoleFile, loadRole } from "./role.mjs";
 export { LAYERS, REGISTRY, THINKING, FALLBACK_VARS, checkVars, mergeVars } from "./vars.mjs";
 export { parseCredentialRef, checkCredentialRef } from "./credentials.mjs";
 export { configDir, businessFilePath, validateBusinessDocument, loadBusiness } from "./business.mjs";
+export { LEVELS, accessFilePath, checkAccess, loadAccess, covers } from "./access.mjs";
 export { projectFilePath, validateProjectDocument, loadProject } from "./project.mjs";
 export { systemVars, resolveInstance, classify } from "./resolve.mjs";

packages/business/tests/access-levels.test.mjs

@@ -0,0 +1,81 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { BusinessError } from "../src/errors.mjs";
+import * as access from "../src/access.mjs";
+
+// Row 193a (#1691): the viewer level. R1 (federation design r4.5, section 7) owns access.mjs and its
+// tests; this file pins only what row 193 adds: a grant's level is collaborator or viewer, and covers()
+// tells the two apart with a required least level. Every call into R1 goes through check() below, so a change to R1's loader
+// interface edits one place.
+const CONTEXT = {
+  providers: ["authentik"],
+  peers: ["factory"],
+  businesses: { "creative-hub": { human: "melanie", instances: ["researcher", "writer"] } },
+  ssoSubjects: [],
+};
+const check = (doc) => access.checkAccess(doc, CONTEXT);
+
+const PROJECT = "0b6f4a52-6f1e-4c7a-9a0e-3f1d2c4b5a69";
+const NOW = new Date("2026-10-20T19:30:00Z");
+
+function file(level) {
+  const grant = { id: "g-1", user: "jason", business: "creative-hub", projects: ["*"], instances: ["researcher"] };
+  if (level !== undefined) grant.level = level;
+  return {
+    accessVersion: 1,
+    revision: 1,
+    users: [{ id: "jason", home: "local", subjects: [{ provider: "authentik", sub: "s-1" }] }],
+    grants: [grant],
+  };
+}
+
+function refuses(fn, pattern) {
+  assert.throws(fn, (error) => {
+    assert.ok(error instanceof BusinessError, `expected BusinessError, got ${error}`);
+    assert.equal(error.exitCode, 2);
+    assert.match(error.message, pattern);
+    return true;
+  });
+}
+
+test("a grant's level is collaborator or viewer", () => {
+  for (const level of ["collaborator", "viewer"]) {
+    assert.doesNotThrow(() => check(file(level)), level);
+  }
+});
+
+test("any other level refuses with the key path named", () => {
+  for (const level of ["owner", "admin", "member", "Viewer", "viewer ", "", null, 1, ["viewer"], undefined]) {
+    refuses(() => check(file(level)), /grants\[0\]\.level/);
+  }
+});
+
+test("covers tells a viewer grant from a collaborator grant", () => {
+  const target = { business: "creative-hub", project: PROJECT, instance: "researcher" };
+  const viewer = file("viewer").grants[0];
+  const collaborator = file("collaborator").grants[0];
+  // The level is the least one the action needs: share reads ask viewer; create, open, send and share ask
+  // collaborator (design 9).
+  assert.equal(access.covers(viewer, target, NOW, { level: "viewer" }), true);
+  assert.equal(access.covers(viewer, target, NOW, { level: "collaborator" }), false);
+  assert.equal(access.covers(collaborator, target, NOW, { level: "viewer" }), true);
+  assert.equal(access.covers(collaborator, target, NOW, { level: "collaborator" }), true);
+});
+
+test("covers refuses a call with no level, so a viewer grant can't slip past a collaborator check", () => {
+  const target = { business: "creative-hub", project: PROJECT, instance: "researcher" };
+  const viewer = file("viewer").grants[0];
+  assert.throws(() => access.covers(viewer, target, NOW), TypeError);
+  assert.throws(() => access.covers(viewer, target, NOW, {}), TypeError);
+});
+
+test("a viewer grant still needs its business, project, instance and expiry to cover", () => {
+  const viewer = { ...file("viewer").grants[0], projects: [PROJECT], expires: "2026-10-21T00:00:00Z" };
+  const target = { business: "creative-hub", project: PROJECT, instance: "researcher" };
+  const read = { level: "viewer" };
+  assert.equal(access.covers(viewer, target, NOW, read), true);
+  assert.equal(access.covers(viewer, { ...target, business: "other" }, NOW, read), false);
+  assert.equal(access.covers(viewer, { ...target, project: "7c1e2d3f-0a9b-4c8d-8e7f-6a5b4c3d2e1f" }, NOW, read), false);
+  assert.equal(access.covers(viewer, { ...target, instance: "writer" }, NOW, read), false);
+  assert.equal(access.covers(viewer, target, new Date("2026-10-21T00:00:01Z"), read), false);
+});

packages/business/tests/access.test.mjs

@@ -0,0 +1,300 @@
+// FED R1 (#414, row 201): the access file loader and validator, DESIGN.md
+// section 3.5, and covers(). Every test works in a scratch directory.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdirSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { BusinessError } from "../src/errors.mjs";
+import { LEVELS, accessFilePath, checkAccess, loadAccess, covers } from "../src/access.mjs";
+import { tmp, writeJson } from "./helpers.mjs";
+
+const P1 = "0f8b6c1e-2a3d-4e5f-8a9b-0c1d2e3f4a5b";
+const P2 = "11111111-2222-4333-8444-555555555555";
+
+function context(over = {}) {
+  return {
+    providers: ["authentik"],
+    peers: ["factory"],
+    businesses: {
+      "creative-hub": { human: "melanie", instances: ["researcher", "writer"] },
+      acme: { human: "jason", instances: ["coder"] },
+    },
+    ssoSubjects: [{ provider: "authentik", sub: "owner-sub" }],
+    ...over,
+  };
+}
+
+function doc() {
+  return {
+    accessVersion: 1,
+    revision: 3,
+    users: [
+      { id: "bean", home: "factory", subjects: [{ provider: "authentik", sub: "s-1" }] },
+      { id: "chet", home: "local", subjects: [{ provider: "authentik", sub: "s-2" }] },
+    ],
+    grants: [
+      { id: "g-1", user: "bean", business: "creative-hub", projects: ["*"], instances: ["researcher"], level: "collaborator", expires: "2026-12-31T00:00:00Z" },
+      { id: "g-2", user: "chet", business: "creative-hub", projects: [P1], instances: ["*"], level: "collaborator" },
+    ],
+  };
+}
+
+// Refuses with a BusinessError, exit 2 unless given, and a message matching `pattern`.
+function refuses(fn, pattern, exitCode = 2) {
+  assert.throws(fn, (error) => {
+    assert.ok(error instanceof BusinessError, `not a BusinessError: ${error}`);
+    assert.equal(error.exitCode, exitCode);
+    assert.match(error.message, pattern);
+    return true;
+  });
+}
+
+function mutated(change) {
+  const d = doc();
+  change(d);
+  return d;
+}
+
+test("a valid document passes and comes back frozen", () => {
+  const checked = checkAccess(doc(), context());
+  assert.deepEqual(checked, doc());
+  assert.ok(Object.isFrozen(checked));
+  assert.ok(Object.isFrozen(checked.grants[0].projects));
+});
+
+test("checkAccess does not freeze or alias the caller's document", () => {
+  const d = doc();
+  const checked = checkAccess(d, context());
+  assert.ok(!Object.isFrozen(d));
+  assert.notEqual(checked.grants, d.grants);
+});
+
+test("LEVELS is the single allowed level set, collaborator and viewer (row 193a)", () => {
+  assert.deepEqual([...LEVELS], ["collaborator", "viewer"]);
+  assert.ok(Object.isFrozen(LEVELS));
+});
+
+test("accessFilePath is access.json in the config directory", () => {
+  assert.equal(accessFilePath("/x/y"), join("/x/y", "access.json"));
+  const dir = tmp();
+  const saved = process.env.MOSAIC_CONFIG;
+  process.env.MOSAIC_CONFIG = join(dir, "config.json");
+  try {
+    assert.equal(accessFilePath(), join(dir, "access.json"));
+  } finally {
+    if (saved === undefined) delete process.env.MOSAIC_CONFIG;
+    else process.env.MOSAIC_CONFIG = saved;
+  }
+});
+
+test("top level: object, unknown keys, accessVersion, revision, arrays", () => {
+  refuses(() => checkAccess([], context()), /access file must be a JSON object/);
+  refuses(() => checkAccess(mutated((d) => { d.extra = 1; }), context()), /unsupported access file key: "extra"/);
+  refuses(() => checkAccess(mutated((d) => { d.accessVersion = 2; }), context()), /accessVersion must be 1/);
+  refuses(() => checkAccess(mutated((d) => { delete d.accessVersion; }), context()), /accessVersion must be 1/);
+  for (const bad of [0, -1, 1.5, "3", undefined]) {
+    refuses(() => checkAccess(mutated((d) => { d.revision = bad; }), context()), /revision must be a positive integer/);
+  }
+  refuses(() => checkAccess(mutated((d) => { d.users = {}; }), context()), /^users must be an array/);
+  refuses(() => checkAccess(mutated((d) => { delete d.grants; }), context()), /^grants must be an array/);
+});
+
+test("users: unknown keys and the id rule", () => {
+  refuses(() => checkAccess(mutated((d) => { d.users[1].role = "x"; }), context()), /unsupported users\[1\] key: "role"/);
+  refuses(() => checkAccess(mutated((d) => { d.users[0] = "bean"; }), context()), /users\[0\] must be a JSON object/);
+  refuses(() => checkAccess(mutated((d) => { d.users[0].id = "Bean"; }), context()), /users\[0\]\.id must match/);
+  refuses(() => checkAccess(mutated((d) => { d.users[1].id = "bean"; }), context()), /users\[1\]\.id is a duplicate user id: bean/);
+});
+
+test("users: human, tester and any business's human are refused", () => {
+  refuses(() => checkAccess(mutated((d) => { d.users[0].id = "human"; d.grants = []; }), context()), /users\[0\]\.id must not be "human"/);
+  refuses(() => checkAccess(mutated((d) => { d.users[1].id = "tester"; d.grants = []; }), context()), /users\[1\]\.id must not be "tester"/);
+  refuses(() => checkAccess(mutated((d) => { d.users[0].id = "melanie"; d.grants = []; }), context()), /users\[0\]\.id must not be a business's human \("melanie"\)/);
+  // The human of a business the grant doesn't name is refused too.
+  refuses(() => checkAccess(mutated((d) => { d.users[1].id = "jason"; d.grants = []; }), context()), /users\[1\]\.id must not be a business's human \("jason"\)/);
+});
+
+test("users: home is a given peer or local", () => {
+  refuses(() => checkAccess(mutated((d) => { d.users[0].home = "elsewhere"; }), context()), /users\[0\]\.home must be a configured peer or "local" \(got "elsewhere"\)/);
+  refuses(() => checkAccess(mutated((d) => { delete d.users[1].home; }), context()), /users\[1\]\.home must be a configured peer/);
+  refuses(() => checkAccess(doc(), context({ peers: [] })), /users\[0\]\.home must be a configured peer/);
+});
+
+test("users: subjects, provider, sub, uniqueness and owner subjects", () => {
+  refuses(() => checkAccess(mutated((d) => { d.users[0].subjects = []; }), context()), /users\[0\]\.subjects must not be empty/);
+  refuses(() => checkAccess(mutated((d) => { delete d.users[0].subjects; }), context()), /users\[0\]\.subjects must be an array/);
+  refuses(() => checkAccess(mutated((d) => { d.users[0].subjects[0].extra = 1; }), context()), /unsupported users\[0\]\.subjects\[0\] key: "extra"/);
+  refuses(() => checkAccess(mutated((d) => { d.users[1].subjects[0].provider = "google"; }), context()), /users\[1\]\.subjects\[0\]\.provider must be a configured provider \(got "google"\)/);
+  refuses(() => checkAccess(mutated((d) => { d.users[0].subjects[0].sub = ""; }), context()), /users\[0\]\.subjects\[0\]\.sub must be a non-empty string/);
+  refuses(() => checkAccess(mutated((d) => { d.users[0].subjects[0].sub = 7; }), context()), /users\[0\]\.subjects\[0\]\.sub must be a non-empty string/);
+  // A pair twice in one user, and across two users.
+  refuses(() => checkAccess(mutated((d) => { d.users[0].subjects.push({ provider: "authentik", sub: "s-1" }); }), context()), /users\[0\]\.subjects\[1\] appears more than once/);
+  refuses(() => checkAccess(mutated((d) => { d.users[1].subjects[0].sub = "s-1"; }), context()), /users\[1\]\.subjects\[0\] appears more than once/);
+  // The owner's own sign-in subject can't be an extra user.
+  refuses(() => checkAccess(mutated((d) => { d.users[1].subjects[0].sub = "owner-sub"; }), context()), /users\[1\]\.subjects\[0\] is an owner sign-in subject/);
+  // The same sub under another provider is a different pair.
+  const twoProviders = context({ providers: ["authentik", "google"] });
+  assert.ok(checkAccess(mutated((d) => { d.users[1].subjects[0] = { provider: "google", sub: "owner-sub" }; }), twoProviders));
+});
+
+test("grants: unknown keys, id, user and business", () => {
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].role = "x"; }), context()), /unsupported grants\[0\] key: "role"/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].id = "g-1"; }), context()), /grants\[1\]\.id is a duplicate grant id: g-1/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].id = "G 1"; }), context()), /grants\[0\]\.id must match/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].user = "nobody"; }), context()), /grants\[0\]\.user must name a user in this file \(got "nobody"\)/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].business = "other"; }), context()), /grants\[1\]\.business must name a declared business \(got "other"\)/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].business = "constructor"; }), context()), /grants\[1\]\.business must name a declared business/);
+});
+
+test("grants: projects is [\"*\"] or distinct lowercase UUIDs", () => {
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = ["stack"]; }), context()), /grants\[1\]\.projects\[0\] must be "\*" or a bus project id, a lowercase UUID \(got "stack"\)/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = [P1.toUpperCase()]; }), context()), /grants\[1\]\.projects\[0\] must be "\*" or a bus project id/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = [P1, 7]; }), context()), /grants\[1\]\.projects\[1\] must be "\*" or a bus project id/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = ["*", P1]; }), context()), /grants\[1\]\.projects must be \["\*"\] alone/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = [P1, "*"]; }), context()), /grants\[1\]\.projects must be \["\*"\] alone/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = ["*", "*"]; }), context()), /grants\[1\]\.projects must be \["\*"\] alone/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = [P1, P1]; }), context()), /duplicate entry in grants\[1\]\.projects/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = []; }), context()), /grants\[1\]\.projects must not be empty/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[1].projects = "*"; }), context()), /grants\[1\]\.projects must be an array/);
+  assert.ok(checkAccess(mutated((d) => { d.grants[1].projects = [P1, P2]; }), context()));
+});
+
+test("grants: instances is [\"*\"] or distinct declared instances of that business", () => {
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].instances = ["coder"]; }), context()), /grants\[0\]\.instances\[0\] must be "\*" or a declared instance of creative-hub \(got "coder"\)/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].instances = ["*", "writer"]; }), context()), /grants\[0\]\.instances must be \["\*"\] alone/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].instances = ["writer", "writer"]; }), context()), /duplicate entry in grants\[0\]\.instances/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].instances = []; }), context()), /grants\[0\]\.instances must not be empty/);
+  assert.ok(checkAccess(mutated((d) => { d.grants[0].instances = ["researcher", "writer"]; }), context()));
+});
+
+test("grants: any level other than collaborator or viewer refuses, naming grants[i].level", () => {
+  for (const bad of ["owner", "Collaborator", "COLLABORATOR", "Viewer", "", null, 1]) {
+    refuses(() => checkAccess(mutated((d) => { d.grants[1].level = bad; }), context()), /grants\[1\]\.level must be one of collaborator, viewer/);
+  }
+  refuses(() => checkAccess(mutated((d) => { delete d.grants[0].level; }), context()), /grants\[0\]\.level must be one of collaborator, viewer \(got undefined\)/);
+});
+
+test("grants: expires is optional ISO time, and a past expiry is not refused", () => {
+  for (const bad of ["2026-12-31", "2026-12-31 00:00:00Z", "2026-12-31T00:00:00+01:00", "tomorrow", 1798675200000, null]) {
+    refuses(() => checkAccess(mutated((d) => { d.grants[0].expires = bad; }), context()), /grants\[0\]\.expires must be an ISO time/);
+  }
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].expires = "2026-02-30T00:00:00Z"; }), context()), /grants\[0\]\.expires is not a real time/);
+  refuses(() => checkAccess(mutated((d) => { d.grants[0].expires = "2026-13-01T00:00:00Z"; }), context()), /grants\[0\]\.expires must be an ISO time/);
+  assert.ok(checkAccess(mutated((d) => { d.grants[0].expires = "2026-12-31T00:00:00.500Z"; }), context()));
+  // DESIGN 3.5: a grant past expires is treated as absent, not refused (sage-1399).
+  assert.ok(checkAccess(mutated((d) => { d.grants[0].expires = "2001-01-01T00:00:00Z"; }), context()));
+});
+
+test("the context is required and checked", () => {
+  refuses(() => checkAccess(doc()), /access context must be a JSON object/);
+  for (const key of ["providers", "peers", "ssoSubjects"]) {
+    const c = context();
+    delete c[key];
+    refuses(() => checkAccess(doc(), c), new RegExp(`access context\\.${key} must be an array`));
+  }
+  refuses(() => checkAccess(doc(), context({ businesses: [] })), /access context\.businesses must be a JSON object/);
+  refuses(() => checkAccess(doc(), context({ extra: 1 })), /unsupported access context key: "extra"/);
+  refuses(() => checkAccess(doc(), context({ peers: ["local"] })), /access context\.peers must not name "local"/);
+  refuses(() => checkAccess(doc(), context({ ssoSubjects: [{ provider: "authentik" }] })), /access context\.ssoSubjects\[0\]\.sub must be a non-empty string/);
+  refuses(() => checkAccess(doc(), context({ businesses: { acme: { human: "jason" } } })), /access context\.businesses\.acme\.instances must be an array/);
+});
+
+// loadAccess: the file checks, then checkAccess.
+
+test("loadAccess reads a valid file and checks it", () => {
+  const file = writeJson(join(tmp(), "access.json"), doc());
+  assert.deepEqual(loadAccess(file, context()), doc());
+});
+
+test("loadAccess refuses a missing file, a symlink and a directory with exit 4", () => {
+  const dir = tmp();
+  refuses(() => loadAccess(join(dir, "access.json"), context()), /access file not found/, 4);
+  const real = writeJson(join(dir, "real.json"), doc());
+  const link = join(dir, "access.json");
+  symlinkSync(real, link);
+  refuses(() => loadAccess(link, context()), /access file must be a regular, non-symbolic-link file/, 4);
+  const sub = join(dir, "d");
+  mkdirSync(sub);
+  refuses(() => loadAccess(sub, context()), /access file must be a regular, non-symbolic-link file/, 4);
+});
+
+test("loadAccess refuses another owner and group or other write", () => {
+  const file = writeJson(join(tmp(), "access.json"), doc());
+  refuses(() => loadAccess(file, context(), { uid: process.getuid() + 1 }), /access file must belong to uid/);
+  for (const mode of [0o620, 0o602, 0o666]) {
+    chmodSync(file, mode);
+    refuses(() => loadAccess(file, context()), /access file must not be writable by group or other/);
+  }
+  chmodSync(file, 0o644);
+  assert.ok(loadAccess(file, context()));
+});
+
+test("loadAccess refuses bad JSON and a bad document with exit 2", () => {
+  const dir = tmp();
+  refuses(() => loadAccess(writeJson(join(dir, "a.json"), "{"), context()), /access file is not valid JSON/);
+  refuses(() => loadAccess(writeJson(join(dir, "b.json"), mutated((d) => { d.grants[0].level = "owner"; })), context()), /grants\[0\]\.level/);
+});
+
+// covers.
+
+const NOW = new Date("2026-10-20T12:00:00Z");
+const target = (over = {}) => ({ business: "creative-hub", project: P1, instance: "researcher", ...over });
+// Any level reads: the least level is viewer (row 193a).
+const READ = { level: "viewer" };
+
+test("covers: * and listed ids match", () => {
+  const [g1, g2] = checkAccess(doc(), context()).grants;
+  assert.equal(covers(g1, target({ project: P2 }), NOW, READ), true);
+  assert.equal(covers(g2, target({ instance: "writer" }), NOW, READ), true);
+  assert.equal(covers(g2, target(), NOW, READ), true);
+});
+
+test("covers: an unlisted project, instance or business doesn't match", () => {
+  const [g1, g2] = checkAccess(doc(), context()).grants;
+  assert.equal(covers(g2, target({ project: P2 }), NOW, READ), false);
+  assert.equal(covers(g1, target({ instance: "writer" }), NOW, READ), false);
+  assert.equal(covers(g2, target({ business: "acme" }), NOW, READ), false);
+  assert.equal(covers(g1, target({ business: "acme" }), NOW, READ), false);
+});
+
+test("covers: an expired grant doesn't match, at and after the instant", () => {
+  const [g1, g2] = checkAccess(doc(), context()).grants;
+  assert.equal(covers(g1, target(), new Date("2026-12-30T23:59:59.999Z"), READ), true);
+  assert.equal(covers(g1, target(), new Date("2026-12-31T00:00:00Z"), READ), false);
+  assert.equal(covers(g1, target(), new Date("2027-01-01T00:00:00Z"), READ), false);
+  // No expires never expires.
+  assert.equal(covers(g2, target(), new Date("2099-01-01T00:00:00Z"), READ), true);
+});
+
+test("covers: level is the least level asked for (row 193a)", () => {
+  const g = checkAccess(doc(), context()).grants[0];
+  const v = { ...g, level: "viewer" };
+  assert.equal(covers(g, target(), NOW, { level: "collaborator" }), true);
+  assert.equal(covers(g, target(), NOW, READ), true);
+  assert.equal(covers(v, target(), NOW, READ), true);
+  assert.equal(covers(v, target(), NOW, { level: "collaborator" }), false);
+});
+
+test("covers: a missing or unknown level throws (row 193a, N1)", () => {
+  const v = { ...checkAccess(doc(), context()).grants[0], level: "viewer" };
+  assert.throws(() => covers(v, target(), NOW), TypeError);
+  assert.throws(() => covers(v, target(), NOW, {}), TypeError);
+  assert.throws(() => covers(v, target(), NOW, { level: undefined }), TypeError);
+  for (const bad of ["owner", "Viewer", "", null, 1]) {
+    assert.throws(() => covers(v, target(), NOW, { level: bad }), /covers needs a level, one of collaborator, viewer/);
+  }
+});
+
+test("covers: a grant with an unknown level covers nothing (row 193a)", () => {
+  const g = checkAccess(doc(), context()).grants[0];
+  for (const bad of ["owner", "Collaborator", undefined]) {
+    assert.equal(covers({ ...g, level: bad }, target(), NOW, READ), false);
+  }
+});
+
+test("covers: now must be a valid Date", () => {
+  const g = checkAccess(doc(), context()).grants[0];
+  assert.throws(() => covers(g, target(), Date.now(), READ), TypeError);
+  assert.throws(() => covers(g, target(), new Date("nope"), READ), TypeError);
+});