docs: strip self-referential/audience framing from the three reference docs · burrito.space/szzt@177a658

+5 -5

docs/architecture.md

··· 1 1 # Szzt — Architecture & Technology Inventory 2 2 3 - A high-level map of the codebase for a new engineer. Szzt publishes small static 3 + Szzt publishes small static 4 4 sites and loose files to a user's own **atproto PDS**, then serves them 5 5 **content-addressed and hash-verified** at `<name>.szzt.app`. Because content lives 6 6 in the user's PDS and every byte is checked against its content ID (CID), the ··· 10 10 > **Naming note.** The product is "Szzt" and deploys at `szzt.app`, but the code is 11 11 > internally named **Mini-Site**: every workspace package is `@minisite/*`, the root 12 12 > package is `minisite`, and the normative spec is `mini-site-spec.md` at the repo 13 - > root. Treat "Szzt" and "Mini-Site" as the same system. Spec section references 13 + > root. "Szzt" and "Mini-Site" are the same system. Spec section references 14 14 > below (e.g. §9.2) point into `mini-site-spec.md`. 15 15 16 16 ## Repository layout ··· 359 359 rework — the only place code and shipped UX currently diverge. 360 360 - **Moderation on by default.** The gateway subscribes to the Bluesky mod service 361 361 labeler unless an operator explicitly opts out (`LABELER_ENDPOINT=""`). 362 - - This doc summarizes structure and intent; per-subsystem invariants (SSRF pinning, the 363 - CBOR encoder boundary, cache-poisoning defenses) are documented in load-bearing header 364 - comments in the relevant source files and in `mini-site-spec.md` / `conformance-audit.md`. 362 + - Per-subsystem invariants (SSRF pinning, the CBOR encoder boundary, cache-poisoning 363 + defenses) are documented in load-bearing header comments in the relevant source files 364 + and in `mini-site-spec.md` / `conformance-audit.md`.

+6 -16

docs/content-spec.md

View file

··· 1 1 # Szzt — Content Model & Wire Format Specification 2 2 3 - This document specifies the **on-PDS content model** and the **wire formats** of a Szzt 3 + The **on-PDS content model** and the **wire formats** of a Szzt 4 4 (a.k.a. "Mini-Site" / `@minisite`) mini-site: the three atproto records that describe a site, the 5 5 StrongRef links between them, the CID codecs, the byte encodings, and how a served request path 6 - resolves to a specific block of bytes. It is written for someone implementing a compatible 7 - **publisher** (writes these records) or **verifier** (re-derives every CID from signed state and 8 - trusts no source's assertion). 6 + resolves to a specific block of bytes. A compatible **publisher** writes these records; a compatible 7 + **verifier** re-derives every CID from signed state and trusts no source's assertion. 9 8 10 - Scope boundaries — read the siblings for these: 9 + Scope boundaries, covered in the sibling docs: 11 10 12 11 - **How a request is dispatched and served** (host demux, RASL-by-CID, tile-mode headers, SSRF 13 12 guard, caching): `docs/gateway-conformance.md`. 14 13 - **What each package is and how the system is wired together**: `docs/architecture.md`. 15 14 - **The normative source of truth**: `mini-site-spec.md`. Section numbers (`§3.2`, `§7.2`, …) below 16 - refer to it. Where the shipped code and the spec diverge, this document flags it explicitly under 17 - "Code vs. spec notes" at the end. 18 - 19 - Every concrete claim here is anchored to `file` + a symbol name (function / type / constant), never 20 - a bare line number, so the anchor survives edits. 15 + refer to it. Code/spec divergences are flagged explicitly under "Code vs. spec notes" at the end. 21 16 22 17 --- 23 18 ··· 191 186 192 187 Resolution turns any mini-site target AT-URI into a common 193 188 `{ site?, deployment?, manifest }` context. The implementation is 194 - `packages/records/src/resolve.ts` `resolveTarget()` (the task brief calls it `resolve()`; the actual 195 - exported symbol is `resolveTarget()`). It fetches raw records through the `RepoReader` seam 189 + `packages/records/src/resolve.ts` `resolveTarget()`. It fetches raw records through the `RepoReader` seam 196 190 (`packages/records/src/types.ts` `RepoReader.getRecord` / `getBlob`) and performs **no integrity 197 191 checks itself** — every referenced CID is re-derived and compared later by the caller 198 192 (`@minisite/verify` or the gateway). Shape violations throw ··· 430 424 is faithful to `mini-site-spec.md` (which uses "tile record" in §4.3 and "tile mode" in §9.6), not 431 425 a code/spec disagreement, but it is the single most likely thing to confuse a new reader, so it is 432 426 called out explicitly. 433 - 434 - - **The task brief names the resolver `resolve()`; the actual exported symbol is 435 - `resolveTarget()`** (`packages/records/src/resolve.ts`). No behavioral discrepancy — just a name to 436 - anchor correctly. 437 427 438 428 - **No UnixFS/`dag-pb` path exists in Szzt source** (§3.1). If a reader expects large files to chunk 439 429 into a UnixFS DAG (as general IPFS does), that expectation is wrong for this model: one file = one

+6 -8

docs/gateway-conformance.md

View file

··· 2 2 3 3 A **gateway** is the read-side host that answers `https://<name>.szzt.app/…` (and bound custom 4 4 domains): it resolves a request to a mini-site's signed atproto state, hash-verifies every byte it 5 - serves, and terminates the request. This document is two things at once: 5 + serves, and terminates the request. Each requirement below appears twice: 6 6 7 - 1. A **normative spec** (RFC-2119 MUST/SHOULD/MAY) an independent implementer could build a 7 + 1. As a **normative spec** clause (RFC-2119 MUST/SHOULD/MAY) an independent implementer could build a 8 8 conforming gateway against, derived from `mini-site-spec.md` §9–§17 and the §18 conformance 9 9 summary. 10 - 2. An **as-built guide** to how *this* repository satisfies each requirement, anchored to 11 - `file` + symbol name (never a bare line number). 10 + 2. As an **as-built** account of how *this* repository satisfies it. 12 11 13 - Every claim below names the symbol that carries it. Where the standing audit 12 + Where the standing audit 14 13 (`conformance-audit.md`) and the current code disagree, the divergence is flagged inline under 15 14 **AUDIT DELTA** — the audit is a dated snapshot (last full sweep 2026-07-16 at `17c2b01`) and 16 15 several of its OPEN gaps have since been wired. ··· 349 348 ## 9. Composition invariant — socket-free factory, sockets at the entry point 350 349 351 350 This is an **architectural conformance property** of this implementation (not a spec MUST), but it 352 - is what makes the security invariants above testable and is worth stating for a re-implementer. 351 + is what makes the security invariants above testable. 353 352 354 353 `apps/gateway/src/main.ts createServerFromEnv()` is **socket-free**: it constructs the whole request 355 354 pipeline but opens no socket and starts no background loop. Everything that dials the network — ··· 401 400 signature chain anyway (§3 above), so it passes §9.2 on the merits — but a *different* conforming 402 401 implementation could verify nothing and still pass §9.2 as written. `conformance-audit.md` "Spec 403 402 defects" recommends §9.2 gain an explicit serve-path signature MUST to codify what this code does. 404 - This document states the stronger requirement in §3 as the intended bar; an implementer targeting 405 - only the literal spec should know §9.2 alone is weaker. 403 + §3 above states the stronger requirement as the intended bar; §9.2 read literally alone is weaker. 406 404 407 405 ## Summary of audit-vs-code divergences 408 406

Configure Feed

Configure Feed