docs: document v1 single-instance constraint in architecture.md (#64)#66
Merged
Conversation
Adds a Single-instance constraint section to docs/architecture.md covering why the relay ships single-instance (in-memory registry, disjoint replicas → silent 4404), what multi-instance would require (shared registry or sticky-on-header LB), and the PYRYCODE_RELAY_SINGLE_INSTANCE=1 bypass shared with #65. Doc-only. Closes #64.
Contributor
Author
Code Review: #64Decision: PASS FindingsNone. SummaryDoc-only XS ticket. All five acceptance criteria are literally satisfied: heading contains "single-instance"; the Why subsection names the in-memory registry, the two-disjoint-registries failure mode, and the |
…64) Adds docs/knowledge/codebase/64.md (implementation summary, AC-literal canary set, cross-ticket contract with #65, patterns + lessons) and refreshes the INDEX.md System overview entry to name the new architecture-doc section, the two multi-instance future-work paths, and the PYRYCODE_RELAY_SINGLE_INSTANCE bypass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a Single-instance constraint (v1) section to
docs/architecture.md, between What this binary does NOT do and Threat model. Covers:4404when phone and binary land on different replicas.PYRYCODE_RELAY_SINGLE_INSTANCE=1bypass shared with sibling relay: startup self-check refuses to run as multi-instance deploy #65 — emergency / migration use only, not recommended for production.Issue
Closes #64. Doc (stochastic) half of the belt-and-suspenders pair; deterministic backstop ships in #65.
Testing
Doc-only — no code, no tests. Verified ACs literally:
grep -ni single-instance docs/architecture.md→ heading at line 33 matches.grep -n PYRYCODE_RELAY_SINGLE_INSTANCE docs/architecture.md→ env var named exactly, with explanation of what it skips, when it is acceptable, and the not-recommended-for-production warning.docs/architecture.mdchanged (git diff --stat: 1 file, +32).Architecture compliance
Follows the spec at
docs/specs/architecture/64-*.md:threat-model.mdcross-link (spec recommended skipping it; the constraint is operator foot-gun, not adversarial threat).