Skip to content

[AI:zf-builder] docs(openwiki): sync architecture documentation for hotcode-dev-zerohub - #181

Merged
ntsd merged 1 commit into
mainfrom
task/zf-z-ce759582
Nov 20, 2026
Merged

ntsd merged 1 commit into
mainfrom
task/zf-z-ce759582

Conversation

@ntsd

@ntsd ntsd commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

[AI:zf-builder] Task: zf-z-ce759582

Automated PR for task zf-z-ce759582

Completed by: @zf-builder

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying zerohub with  Cloudflare Pages  Cloudflare Pages

Latest commit: e4a078f
Status: ✅  Deploy successful!
Preview URL: https://87db8fb7.zerohub.pages.dev
Branch Preview URL: https://task-zf-z-ce759582.zerohub.pages.dev

View logs

@ntsd ntsd left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[AI:zf-reviewer] [Reviewer Feedback] Round 1: Approved for human review.

Docs-only OpenWiki sync (14 files, all under openwiki/: 5 content pages, 6 .claims JSON, .page-manifest.json, .last-update.json). +791/-531. No source, test, dependency, or config changes.

Ponytail gatekeeping

  • Rung 7 (diff scope/hygiene): CLEAN. Diff is confined to openwiki/; no drive-by churn, no leftover .github/workflows/openwiki-update.yml or CLAUDE.md (verified absent). AGENTS.md untouched (unchanged, correctly not in diff).
  • Rungs 1/3/5/6: N/A — no code, no new dependencies, no abstractions.
  • No test-suite run is warranted for a docs-only diff; nothing executable changed (precommit gate already ran at PR creation).

Accuracy spot-checks (all verified against source on this branch)

  • server/cmd/server.go:25-29 — exactly three ZeroHub instances (static/random/IP) via newZeroHubOrPanic; overview.md's "former 'permanent' mode merged into never-expiring static" matches.
  • handler.go:58-60 — Handler interface is Serve() only (post-#164); server-signaling.md routing table matches.
  • join_or_create_hub_ip.go — IP-hub ID is FNV-1a via stdlib hash/fnv (post-#178, no xxh3), matching the docs' "FNV-1a hash of the client IP".
  • hub.go:181-249 — RemovePeerIfLast/removePeer with empty = !h.IsPermanent && ...; doc's "the hub is not permanent" faithfully mirrors the still-present internal IsPermanent flag.
  • hub.go:263-299 — shared sendToPeer relay helper; cross-mode guard (hubIdCrossModeMu, claimHubForCreate, claimGetOrCreateHub in validation.go) as documented.
  • zeroHub.ts — armSendOnIceReady single-send guard, per-peer iceTimeouts cleared on disconnect/removePeer, reconnectBackoffDelayMs = reconnectBaseBackoffMs * 2^(n-1) with reconnectBaseBackoffMs: 250 default; all consistent with const.ts:39-51 (tls: true, Warning, maxReconnectAttempts: 10, maxReconnectRounds: 2, Google STUN, bundlePolicy: "balanced").
  • Makefile — every target the Development & Testing page documents exists with the documented behavior (test-all = 3 parallel jobs under -j3; server-mock generates the zerohub mock only; e2e-test kills/spawns/kills servers and exits with Playwright status).
  • test/package.json — pretest chain = typecheck + build:harness + build-unit-harness, matching the page's "don't invoke npx playwright test directly" warning.
  • Spec inventory exact: 7 E2E specs (connect, data-channel, concurrent, disconnect, multihosts, static-hub, zz-migrate) + 23 unit-*.spec.ts — as documented.
  • No stale wording: no "Svelte", no removed client-build/server-bench targets, no permanent-hubs URL paths; createPermanentHub/joinPermanentHub appear only as "no longer exist".

Hygiene & metadata

  • All 8 touched JSON files parse. .page-manifest.json lists exactly the 6 updated pages; gitHead = 6e8eced = current main tip (branch is up to date, merge-base verified). Per-page pageVersion hashes match the corresponding .claims JSON. Index pages (openwiki/index.md, architecture/index.md) still match the updated page titles/descriptions.
  • Mergeability: MERGEABLE / CLEAN against main.

CONVENTION: OpenWiki sync PRs touch only openwiki/ (pages + .claims + .page-manifest.json + .last-update.json); review = JSON validity, manifest gitHead == merge-base, spot-check claims against source; no test-suite run needed since nothing executable changes.
GOTCHA: In openwiki docs, "static hubs" is the public URL/API term while "permanent"/IsPermanent is the still-existing internal flag; mixed usage (e.g. server-signaling.md "the hub is not permanent") mirrors source code and is intentional, not stale wording.

@ntsd ntsd left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[AI:zf-reviewer] [Reviewer Feedback] Round 1: Approved for human review.

Docs-only OpenWiki sync: 14 files, all under openwiki/ (5 content pages, 6 .claims JSON, .page-manifest.json, .last-update.json), +791/−531. No source, test, dependency, or config changes.

Ponytail gatekeeping

  • Rung 7 (diff scope/hygiene): CLEAN. Diff confined to openwiki/; no drive-by churn, no leftover .github/workflows/openwiki-update.yml or CLAUDE.md (verified absent from the tree).
  • Rungs 1/3/5/6: N/A — no code, no new dependencies, no abstractions.
  • Test coverage: not applicable — no executable code changed; nothing to test.

Accuracy spot-checks (verified against source on this branch)

  • server/cmd/server.go:25-29 — exactly three ZeroHub instances (static/random/IP) via newZeroHubOrPanic; matches the updated "former 'permanent' mode merged into never-expiring static" wording.
  • handler.go:58-60 — Handler interface is just Serve() (post-#164); routing table in server-signaling.md matches Serve() dispatch (static/random/IP routes, errAdminUnauthorized → 401 passthrough, unknown path → 404, other errors → 503).
  • join_or_create_hub_ip.go — IP-hub ID is FNV-1a via stdlib hash/fnv (post-#178, no xxh3), matching "FNV-1a hash of the client IP".
  • hub.go:181-249 — RemovePeerIfLast/removePeer with empty = !h.IsPermanent && ...; doc's "the hub is not permanent" faithfully mirrors the still-present internal IsPermanent flag.
  • hub.go:271 — shared sendToPeer lookup-and-send helper used by all three relay methods; cross-mode guard (hubIdCrossModeMu, claimHubForCreate, claimGetOrCreateHub in validation.go) as documented.
  • websocket.go:247 — finishUpgradeFailure shared epilogue with per-call rollback, as documented.
  • ratelimit.go — in-package token-bucket at 60 req/min, matches "60 requests/minute".
  • config/consts.go — WSIdleTimeout 60s, WSMaxFrameSize 1 MiB, MaxMetadataSize 4 KiB, HTTPMaxRequestBodySize 4 KiB — all match the docs.
  • auth.go:32 — crypto/subtle.ConstantTimeCompare for admin secret, as documented.
  • const.ts:39-51 — DEFAULT_CONFIG (tls: true, Warning, waitIceCandidatesTimeout: 2000, maxReconnectAttempts: 10, maxReconnectRounds: 2, reconnectBaseBackoffMs: 250, Google STUN, bundlePolicy: "balanced") matches the client-sdk page exactly.
  • zeroHub.ts — armSendOnIceReady single-send guard, per-peer iceTimeouts cleared on disconnect()/removePeer(), reconnectBackoffDelayMs exponential doubling — all match.
  • Makefile — every target the Development & Testing page documents exists with the documented behavior (test-all = server-test + e2e-test + client-test under -j3; server-mock now zerohub-only; e2e-test kills/spawns two servers and exits with Playwright status).
  • test/package.json — pretest = typecheck + build:harness + build-unit-harness, matching the "don't invoke npx playwright test directly" warning. Spec inventory exact: 7 E2E specs + 23 unit-*.spec.ts, as documented.
  • No stale wording: no "Svelte", no removed client-build/server-bench targets, no permanent-hubs URL paths; createPermanentHub/joinPermanentHub appear only in the "no longer exist" context.

Hygiene & metadata

  • All 8 touched JSON files parse.
  • .page-manifest.json lists exactly the 6 updated pages; gitHead = 6e8eceda... = current main tip (branch is up to date, merge-base verified). Per-page pageVersion hashes match the corresponding .claims JSON; manifest diff is metadata-only (no pages added/removed).
  • Unchanged index pages (openwiki/index.md, architecture/index.md, etc.) still match the updated page titles/descriptions.
  • Mergeability: MERGEABLE / CLEAN against main.

CONVENTION: OpenWiki sync PRs touch only openwiki/ (pages + .claims + .page-manifest.json + .last-update.json); review = JSON validity, manifest gitHead/pageVersion consistency against the merge base, and spot-checking claims against source; no test-suite run needed since nothing executable changes.
GOTCHA: In openwiki docs, "static hubs" is the public URL/API term while "permanent"/IsPermanent is the still-existing internal flag; mixed usage (e.g. server-signaling.md "the hub is not permanent") mirrors source code and is intentional, not stale wording.

@ntsd

ntsd commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

[AI:zf-reviewer] Note: two copies of the Round 1 review were posted above by tooling retry (submitted 20:29 and 20:35 UTC); they are identical in content and conclusion. The later one (review id 5999001537) is canonical.

@ntsd

ntsd commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

[AI:zf-builder] All review comments reviewed — no code changes required.

  • Comments 1/2: dispatcher retry notices from the previous run (worker timeout / exit), not code feedback.
  • Comment 3: state transition (approved).
  • Comments 4/5: Round-1 approval with no changes requested; comment 6's dedup note is acknowledged, treating review 5999001537 as canonical.

Re-verified in this worktree against the approved diff:

  • Working tree clean; diff vs main is exactly 14 files, all under openwiki/ (+791/-531) — matches the approved diff.
  • All 8 touched JSON files parse; .page-manifest.json lists the 6 updated pages, each with gitHead 6e8eced (current main tip).
  • No leftover .github/workflows/openwiki-update.yml or CLAUDE.md; AGENTS.md untouched.
  • .zerofactory/precommit.sh (all) passes (exit 0): gofmt clean, client eslint+prettier with zero changes, go build+vet, client tsc, go tests green (e2e skipped by design).

@ntsd ntsd left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[AI:zf-reviewer] [Reviewer Feedback] Round 1: Approved for human review.

Scope

Docs-only sync of openwiki/ against ~90 recently-merged commits on main. All 14 changed files live under openwiki/ (6 pages + 6 .claims/*.json + .page-manifest.json + .last-update.json); no source, dependency, or test files touched. No CLAUDE.md / .github/workflows/openwiki-update.yml artifacts were introduced. Mergeability: MERGEABLE vs main.

Verification (all pass)

  • JSON validity: all 8 JSON files parse.
  • Manifest consistency: .page-manifest.json gitHead = 6e8eced == git merge-base origin/main HEAD; every page pageVersion matches the corresponding .claims/*.json pageVersion (6/6).
  • Frontmatter: all 6 .md pages carry valid type/title/description/tags/sources + verified/generated stamps.
  • Evidence: all 94 repo:// resource paths referenced across the six claims files exist in the repo (0 missing).
  • Spot-checked claims against source (representative, all accurate):
    • Three hub modes (static/random/IP) via newZeroHubOrPanic; zeroHubPermanent removed, "permanent" folded into never-expiring static — matches server/cmd/server.go + NewHandler(cfg, static, random, ip).
    • IP-hub key is now stdlib hash/fnv FNV-1a (not xxh3) — join_or_create_hub_ip.go.
    • Cross-mode collision guard (claimHubForCreate/claimGetOrCreateHub under hubIdCrossModeMu), shared finishUpgradeFailure epilogue, migrateHTTPResponse 301, RemovePeerIfLast + shared sendToPeer — all present.
    • Client: connectToZeroHub returns Promise<void>; close codes 1006/1011/1012/1013 reconnect without settling; negotiateWithPeer shared by sendOffer/sendAnswer; WEBRTC_RECOVERY_DELAY_MS=500/scheduleWebrtcRecovery; DEFAULT_CONFIG maxReconnectAttempts:10 / maxReconnectRounds:2 / reconnectBaseBackoffMs:250; removePeer clears both ICE + P2P-drop timers; SFU reElectSfu + lastElectingSfuId dedup — all match zeroHub.ts / sfuTopology.ts.
    • update_peer_metadata_message oneof correctly dropped (absent from client_message.proto); entry points now createRandomHub/joinRandomHub/joinStaticHub/joinOrCreateIPHub (permanent/createHub/joinHub removed) — matches zeroHub.ts docblock.
    • Test-infra claims verified: 7 E2E specs + 23 unit-*.spec.ts; connect.spec.ts rename; unit-static-hub-endpoints.spec.ts (perm-hub-endpoints removed); playwright.config.ts pins workers:1/fullyParallel:false/10s/Chrome/retries=CI?2:0; test pretest = tsc && build:harness && build-unit-harness; Makefile server-mock now zerohub-only, server-serve sets APP_ALLOWED_ORIGINS=null, e2e-test exits with Playwright status, test-all = server-test + e2e-test + client-test.
    • Stale wording corrected: "Svelte" harness → plain-TS/esbuild; ulule/limiter → in-package token-bucket; CheckOrigin accepts all → sameOriginOrAllowed + documented wildcard.

Tests

No code or test files changed, so no new unit/integration tests are required or expected for this docs sync; "test coverage" for a docs PR is the JSON-validity + evidence-path + claim-accuracy checks above. As a green-branch gate I ran the self-contained server suite at the branch tip: go test ./... → all packages ok.

Ponytail Anti-Overengineering

  • Rung 7 (diff scope/hygiene): clean — all edits confined to openwiki/, no drive-by reformat or unrelated churn.
  • Rungs 3 & 5 (dependency veto): N/A — no dependencies added.
  • Rungs 1 & 6 (simplicity/YAGNI): N/A for docs; content stays flat and factual.

CONVENTION: OpenWiki sync PRs touch only openwiki/ (pages + .claims + .page-manifest.json + .last-update.json); review = JSON validity, manifest gitHead==merge-base + pageVersion==claims, and evidence repo:// paths all exist.
GOTCHA: OpenWiki docs must use "static hubs" (public term) while isPermanent remains the internal flag — this sync correctly keeps "never-expiring static" wording and does not reintroduce "Svelte"/xxh3/ulule/perm-hub staleness.

@ntsd
ntsd merged commit 975c142 into main Nov 20, 2026
1 check passed
@ntsd
ntsd deleted the task/zf-z-ce759582 branch November 20, 2026 22:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant