docs(shard): record the REST projection gap the Part A smoke test found #65

wtclaude · 2026-07-28T15:54:29Z

wtclaude commented

2026-07-28 15:54:29 +00:00

What & why

Docs for RunicGateway/website#110. The live five-rung smoke test of the Protocol 3.0 Part A visibility framework found that it was enforced on the SSE path and on /guilds + /governors, but not on the remaining public REST reads — so one event was projected live and served verbatim from stored history.

`link/v3.md`

New §3.6.1 — the full list of what the first implementation missed: the anonymous acct/webId leak on /feed, the flattened ownerAcct on /idoc, the dead houses field rules, /feed ignoring live config, the empty-allowlist fall-through, and the Date→{} projection bug. Each is recorded as a shape the next phase can repeat.
The rule it leaves behind, which Parts B and C inherit: a read path that returns shard data and does not call projectFeature is a bug, and every new surface (/ruleset, /points, /market, /atlas) must gate its kind set on live config rather than on PUBLIC_KINDS.
§3.5 corrected. The table is not seeded on boot — an absent row means "use the compiled default". That changed during implementation, and it's the better design: the defaults live in one place instead of being duplicated into a seeder that could drift from them.
§3.7 notes the admin PUT rejects flattened locked spellings too.

`website/BACKEND_DESIGN.md` §6.5

The same, as a security contract: rule 1 locks a field by meaning, not spelling; PUBLIC_KINDS is a module-load constant and must not answer per-caller questions (use visibleKinds); every read path must project; an empty kinds allowlist serves nothing; projectFeature walks arrays and plain objects only.

`website/SHARD_VISIBILITY.md`

The admin-facing version — that stored history answers the same way the live stream does (so raising a rung hides it from both, with no back door where yesterday's copy of an event is more revealing than today's), and that turning live updates off stops the push, not the reading.

How it was tested

Docs only — no code. Every claim was verified live against the running site during the smoke test that produced website#110; the §3.6.1 list is the set of gaps that walk actually found, and each one's fix is verified in that PR.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Docs for RunicGateway/website#110. The live five-rung smoke test of the Protocol 3.0 Part A visibility framework found that it was enforced on the SSE path and on `/guilds` + `/governors`, but **not** on the remaining public REST reads — so one event was projected live and served verbatim from stored history. ### `link/v3.md` - **New §3.6.1** — the full list of what the first implementation missed: the anonymous `acct`/`webId` leak on `/feed`, the flattened `ownerAcct` on `/idoc`, the dead `houses` field rules, `/feed` ignoring live config, the empty-allowlist fall-through, and the `Date`→`{}` projection bug. Each is recorded as a *shape the next phase can repeat*. - The rule it leaves behind, which Parts B and C inherit: **a read path that returns shard data and does not call `projectFeature` is a bug**, and every new surface (`/ruleset`, `/points`, `/market`, `/atlas`) must gate its kind set on live config rather than on `PUBLIC_KINDS`. - **§3.5 corrected.** The table is *not* seeded on boot — an absent row means "use the compiled default". That changed during implementation, and it's the better design: the defaults live in one place instead of being duplicated into a seeder that could drift from them. - §3.7 notes the admin `PUT` rejects flattened locked spellings too. ### `website/BACKEND_DESIGN.md` §6.5 The same, as a security contract: rule 1 locks a field **by meaning, not spelling**; `PUBLIC_KINDS` is a module-load constant and must not answer per-caller questions (use `visibleKinds`); every read path must project; an empty `kinds` allowlist serves nothing; `projectFeature` walks arrays and plain objects only. ### `website/SHARD_VISIBILITY.md` The admin-facing version — that **stored history answers the same way the live stream does** (so raising a rung hides it from both, with no back door where yesterday's copy of an event is more revealing than today's), and that turning **live updates** off stops the push, not the reading. ## How it was tested Docs only — no code. Every claim was verified live against the running site during the smoke test that produced website#110; the §3.6.1 list is the set of gaps that walk actually found, and each one's fix is verified in that PR. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 2 commits 2026-07-28 15:54:31 +00:00

docs(shard): record the REST projection gap the Part A smoke test found 35ad440bad

The live five-rung smoke test of the visibility framework found that Part
A enforced it on the SSE path and on /guilds + /governors, but not on the
remaining public REST reads - so one event was projected live and served
verbatim from stored history.

link/v3.md gains 3.6.1 with the full list (the anonymous acct/webId leak
on /feed, the flattened ownerAcct on /idoc, the dead `houses` field
rules, /feed ignoring live config, the empty-allowlist fall-through, and
the Date-to-{} projection bug), plus the rule it leaves behind: a read
path that returns shard data and does not project is a bug, and every new
Part B/C surface must gate its kind set on live config rather than on
PUBLIC_KINDS.

3.5 also corrected: the table is NOT seeded on boot. An absent row means
"use the compiled default", which keeps the defaults in one place instead
of duplicating them into a seeder that could drift.

BACKEND_DESIGN.md 6.5 records the same as a security contract: rule 1
locks a field by meaning rather than spelling; PUBLIC_KINDS is a
module-load constant and must not answer per-caller questions;
projectFeature walks arrays and plain objects only.

SHARD_VISIBILITY.md gets the admin-facing version - that stored history
answers the same way the live stream does, and that turning live updates
off stops the push, not the reading.

Co-Authored-By: Claude <noreply@anthropic.com>

chore(docs): drop an unrelated working-tree file committed by mistake 4c0ceb1c41

android/TRUSTED_DEVICES_APP_HANDOFF.md was untracked in the working tree
before this branch and was swept in by a `git add -A`. It is not part of
this change; untracked here and left on disk.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-28 15:56:15 +00:00

whitlocktech merged commit bd9718a859 into edge

2026-07-28 15:56:22 +00:00

whitlocktech deleted branch docs/shard-visibility-rest-projection

2026-07-28 15:56:23 +00:00

whitlocktech referenced this issue from a commit

2026-07-28 15:56:23 +00:00

Merge pull request 'docs(shard): record the REST projection gap the Part A smoke test found' (#65) from docs/shard-visibility-rest-projection into edge

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#65