docs: final design assessment — post-implementation consistency pass

[cuibonobo]

Adds docs/design-assessment-2026-07.md — a whole-system read of the spec and every package after the #45–#69 implementation batch, hunting for holes the issue-by-issue review missed and inconsistencies introduced by landing decisions one issue at a time. Nothing is filed as an issue yet; the doc is the deliverable to react to, per the "discussion first, filing second" convention.

Nothing but docs changes here — no code touched.

Verdict

The design philosophy survived implementation intact. The invariant layering (#67/#68), error-taxonomy round-trip (#53), two-relations split (#54/#68), and attachment determinism/backstop pairing (#65/#66) are all faithful. The 25 findings cluster at the seams where two separately-implemented decisions meet.

The four I'd treat as urgent

• A1 [hole] — _attachment@1 creation bypasses ScopedStack.create() passes caller options through unchecked — attachment-association escalation, parent/app spoofing #51's reference gate. Creating a metadata record is itself access-conveying (satisfies canAccessFile()'s "uploaded it themselves" clause), but nothing gates it — so an uploader can mint a record for a guessed SHA-256 and download those bytes. The exact hash-confirmation oracle ScopedStack.create() passes caller options through unchecked — attachment-association escalation, parent/app spoofing #51 was written to prevent; the mimeType-conflict error even leaks the established type. Needs a design decision (I sketch an upload-receipt approach) before anyone codes it.
• A2 [bug] — permissionEqual() never learned about Group roles are decorative: admin should mean "can manage the group" #58's role. Tightening a group ACL by adding role: 'admin' is judged a no-op and silently dropped while reporting success. A failed tightening of access; one line.
• A3 + E2 — the Core code treats one query() page as the complete result set (grants, attachment metadata, uploader checks) #50 exhaustive-pagination rule is violated inside core itself. canAccessFile() and ensureOwnerEntity() both treat one bounded query page as complete → false permission denials, and duplicate owner cards past ~50 records.
• B2 [hole] — snapshot-then-mutate isn't atomic. A crash in the gap leaves an orphan version row that permanently bricks every future mutation of that record. The review anticipated this ("One versioning rule: every record mutation bumps version and snapshots full prior state (associations and permissions included) #61's atomic snapshot+mutate lands in the adapter"); implementation kept it as a separate Stack-level call.

Plus D1 [bug] — the conformance fixtures use ids (rec-1, fileId abc123) that #55's validation rules require a conformant server to reject, so the enforcement suite and the rules it enforces can't both pass; and the newest contracts (If-Match/412, schema_drift, _config protection, 401-vs-403) have no fixtures at all.

Structure

• A — permission-model holes
• B — versioning-rule inconsistencies (One versioning rule: every record mutation bumps version and snapshots full prior state (associations and permissions included) #61)
• C — wire-honesty asymmetries (Wire protocol gaps: silently dropped query filters, DELETE-with-body, missing discovery fields, getType round trip per write #56/APIAdapter collapses the error taxonomy: Stack* errors never survive the wire round trip #53)
• D — conformance fixtures under-pinning the newest contracts (PATCH contract mismatch: spec defines content-only merge patch, APIAdapter sends record-field envelopes #52)
• E — entityId invariant leaks (Polish batch: owner entityId stamping, unused timezone, lenient date validation, silent null content filter #69/_grant records store the grantee in entityId, the authorship field — move it into GrantContent #57)
• F — eight smaller items, each with a suggested direction

Closes with a fix order grouped by shared root cause. Deliberately skips everything already tracked open (#3/#15/#16/#72/#90/#93).

🤖 Generated with Claude Code

https://claude.ai/code/session_01XS3tQxohWFqeRgDxmyBiV2

---

Generated by Claude Code