docs: replace plan.md with the production-readiness plan #14

Merged
sam merged 4 commits from docs/production-readiness-plan into main 2026-10-18 15:12:54 +00:00
Member

Replaces plan.md with the production-readiness plan prepared by another agent.

The mesh plan (R = N, one-hop forwarding, the internal- command log, replicated consumer state, forwarded lease arbitration, strict applyRecord, resync) is treated as the shipped premise. The new document states six guarantees (P1-P6) and lays out twelve phases from terms/fencing through quorum-durable publishes, promotion, holder sets (R < N), dynamic membership, cluster metadata replication, security, the porcupine robustness layer, ops, snapshots/batched pulls, the browser client, and release readiness.

Docs-only change: plan.md is the only file touched.

Replaces plan.md with the production-readiness plan prepared by another agent. The mesh plan (R = N, one-hop forwarding, the internal-<name> command log, replicated consumer state, forwarded lease arbitration, strict applyRecord, resync) is treated as the shipped premise. The new document states six guarantees (P1-P6) and lays out twelve phases from terms/fencing through quorum-durable publishes, promotion, holder sets (R < N), dynamic membership, cluster metadata replication, security, the porcupine robustness layer, ops, snapshots/batched pulls, the browser client, and release readiness. Docs-only change: plan.md is the only file touched.
docs: resolve the production-readiness plan review
All checks were successful
code-review / Agent review (pull_request) Successful in 15s
5b4f815495
Process the plan.md review (5 blocking, 8 important findings plus
suggestions and open questions) into the document:

- Break the Phase 3/4/6 circular dependency: holder epochs ride each
  stream's own command log from Phase 4; the cluster log carries derived
  metadata only.
- Make promotion refuse to start unless the write quorum is at least
  majority(holders), so quorum-1 plus failover cannot lose acked writes.
- Fix the ErrNoQuorum contract: an unacked publish may be durable on a
  subset; state the P1 converse in the promise table.
- Give promotion a read-quorum RPC to compute the committed prefix
  instead of naming a value nothing computes; state the above-prefix case.
- Land a versioned stream.meta and streamProtocol bump with Phase 1's term
  change; Phases 1-8 are pre-release with no rolling-upgrade obligation.
- Name the real chokepoints (relayedStreamName, clientDispatch,
  clientStreamName) and the fuzz test Phase 4 retires.
- Add R >= 3 as the write-availability minimum, replica-side group commit,
  forwarded-pull fan-in cost, command-log tailing set, bounded durable
  nonce store, on-disk scoped-name mapping, Drain/RemovePeer resolution,
  and correct determinism claims in the porcupine layer.
- Retire the stale no-C-compiler/racedetector text: the image ships gcc
  and make test / make robustness run the real -race detector.
- Record the open questions (epoch 0 seeding, above-prefix promotion,
  compaction vs highest term).
pi-reviewer left a comment

Docs-only PR (plan.md only, 632+/633-). The production-readiness plan replaces the retired mesh plan. I verified the plan's claims about shipped code against the repo at head 5b4f815 (local checkout synced to the PR head, grep/go doc/go vet/govulncheck run in-session):

  • P4 row: advanceIf (consumer_state.go:98), streamState.dedup (stream_state.go:36), forwarded frameGetConsumer (mesh_test.go:472) — all exist as claimed.
  • P5 row: Trim{base} monotonicity is shipped — streamState.applyTrim uses keep := max(s.log.base, base) (stream_state.go:456).
  • Phase 1/4/7 chokepoints: codeForwardLoop (protocol.go:202-205), relayedStreamName (server.go:1034), clientDispatch/dispatchFrom/clientStreamName (server.go:1523/1511/987), NewAllowlistGater/WithAllowedPeers (gater.go, doc.go:158-159), maxNameSize = 64 (server.go:250) — all exist.
  • The relayed-framePull-must-name-internal-stream rule is asserted in FuzzStreamNameExtractors (fuzz_test.go:503), matching the plan's "~fuzz_test.go:497"; FuzzDecodeCommand exists (fuzz_test.go:298).
  • Phase 3's "no test uses UnlinkPeers/LinkPeers today" is accurate — zero occurrences in the tree.
  • Phase 9's "prometheus/client_golang, already an indirect dependency" is accurate — go.mod lists github.com/prometheus/client_golang v1.24.1 // indirect (also client_model, common, procfs).
  • Phase 12's race-detector claims are accurate: /usr/bin/gcc present, make test runs go test -race ./..., no racedetector target remains in the Makefile, gremlins unleash --dry-run is a valid command.
  • rapid build tag (journal_property_test.go:1), mocknet + synctest in the suite, streamProtocol = "/norobo/webstream/1.0.0" (server.go:240), applyRecord (memlog.go:138), rep-<peerID> naming (replicate.go:176), README's "revisit when batched fetches" consumer-dedup note (README.md:185) — all verified.
  • go vet ./... clean. govulncheck finds no called vulnerability in the module's imports (one Windows-only stdlib os.Root issue, GO-2026-6604, untouched by a docs PR).

Two non-blocking findings below (an undefined symbol and a self-contradiction about plan preservation). Neither blocks merge.

Docs-only PR (plan.md only, 632+/633-). The production-readiness plan replaces the retired mesh plan. I verified the plan's claims about shipped code against the repo at head 5b4f815 (local checkout synced to the PR head, `grep`/`go doc`/`go vet`/`govulncheck` run in-session): - P4 row: `advanceIf` (consumer_state.go:98), `streamState.dedup` (stream_state.go:36), forwarded `frameGetConsumer` (mesh_test.go:472) — all exist as claimed. - P5 row: `Trim{base}` monotonicity is shipped — `streamState.applyTrim` uses `keep := max(s.log.base, base)` (stream_state.go:456). - Phase 1/4/7 chokepoints: `codeForwardLoop` (protocol.go:202-205), `relayedStreamName` (server.go:1034), `clientDispatch`/`dispatchFrom`/`clientStreamName` (server.go:1523/1511/987), `NewAllowlistGater`/`WithAllowedPeers` (gater.go, doc.go:158-159), `maxNameSize = 64` (server.go:250) — all exist. - The relayed-`framePull`-must-name-internal-stream rule is asserted in `FuzzStreamNameExtractors` (fuzz_test.go:503), matching the plan's "~fuzz_test.go:497"; `FuzzDecodeCommand` exists (fuzz_test.go:298). - Phase 3's "no test uses `UnlinkPeers`/`LinkPeers` today" is accurate — zero occurrences in the tree. - Phase 9's "`prometheus/client_golang`, already an indirect dependency" is accurate — `go.mod` lists `github.com/prometheus/client_golang v1.24.1 // indirect` (also client_model, common, procfs). - Phase 12's race-detector claims are accurate: `/usr/bin/gcc` present, `make test` runs `go test -race ./...`, no `racedetector` target remains in the Makefile, `gremlins unleash --dry-run` is a valid command. - `rapid` build tag (journal_property_test.go:1), mocknet + `synctest` in the suite, `streamProtocol = "/norobo/webstream/1.0.0"` (server.go:240), `applyRecord` (memlog.go:138), `rep-<peerID>` naming (replicate.go:176), README's "revisit when batched fetches" consumer-dedup note (README.md:185) — all verified. - `go vet ./...` clean. `govulncheck` finds no called vulnerability in the module's imports (one Windows-only stdlib `os.Root` issue, GO-2026-6604, untouched by a docs PR). Two non-blocking findings below (an undefined symbol and a self-contradiction about plan preservation). Neither blocks merge.
plan.md Outdated
@ -85,0 +310,4 @@
- A config epoch mismatch is a loud error (the loop guard plus the epoch check),
and a node that refuses to adopt a config keeps serving reads but not writes.
- Leader failover, placement and membership all derive from
`(config epoch, toms)`, so there is exactly one place where "who is in the mesh"
Member

🟡 SUGGESTION — (config epoch, toms) uses an undefined symbol. toms appears exactly once in the entire document and nowhere in the codebase (grep -rn "toms" *.go → no hits); every other reference in this file is to the stream term (e.g. lines 24, 63, 67). A reader implementing Phase 5 cannot resolve what toms names. Fix: write (config epoch, term) or (config epoch, terms).

🟡 **SUGGESTION** — `(config epoch, toms)` uses an undefined symbol. `toms` appears exactly once in the entire document and nowhere in the codebase (`grep -rn "toms" *.go` → no hits); every other reference in this file is to the stream **term** (e.g. lines 24, 63, 67). A reader implementing Phase 5 cannot resolve what `toms` names. Fix: write `(config epoch, term)` or `(config epoch, terms)`.
plan.md Outdated
@ -85,0 +567,4 @@
- **Semver, changelog and docs**: README gains the guarantee section (P1–P6) and
the placement/availability trade-off table; `doc.go` gains the scoped-name
contract and the threat model; `plan.md` is this document, and retired plans
are preserved under `docs/plans/` rather than overwritten.
Member

🟡 SUGGESTION — this rule is violated by the PR that introduces it. Phase 12 promises "retired plans are preserved under docs/plans/ rather than overwritten", but this PR itself retires the mesh plan (the document says it "is fully implemented and is retired by this document") by overwriting plan.md in place: the repo has no docs/ directory at head (git ls-files | grep -c '^docs/' → 0), so the retired mesh plan survives only in git history. Fix: add the old plan.md content as docs/plans/mesh-replication.md in this PR, or reword the rule to exclude plan.md.

🟡 **SUGGESTION** — this rule is violated by the PR that introduces it. Phase 12 promises "retired plans are preserved under `docs/plans/` rather than overwritten", but this PR itself retires the mesh plan (the document says it "is fully implemented and is retired by this document") by overwriting `plan.md` in place: the repo has no `docs/` directory at head (`git ls-files | grep -c '^docs/'` → 0), so the retired mesh plan survives only in git history. Fix: add the old `plan.md` content as `docs/plans/mesh-replication.md` in this PR, or reword the rule to exclude `plan.md`.
Both findings from review 61 (pi-reviewer) were on plan.md:

- Phase 5's "(config epoch, toms)" named a symbol that exists nowhere in the
  document or the code; every other reference is to the stream term, so it now
  reads "(config epoch, term)".
- Phase 12 promises retired plans are preserved under docs/plans/, so the mesh
  plan this document retires is stored there (with a notice naming its
  successor) instead of surviving only in git history.
The preserved copy added in 4b95d05 is dropped: a superseded plan has no home
in the tree, and git history already holds it at 074350f^:plan.md. Phase 12's
release-readiness bullet is reworded accordingly, so the document no longer
promises a docs/plans/ home that this PR would have to create for itself.
sam merged commit 88cf83327e into main 2026-10-18 15:12:54 +00:00
sam deleted branch docs/production-readiness-plan 2026-10-18 15:12:54 +00:00
Sign in to join this conversation.
No reviewers
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
norobo/webstream!14
No description provided.