Skip to content

docs: document v1 single-instance constraint in architecture.md (#64)#66

Merged
ilmoniemi merged 3 commits into
mainfrom
feature/64
May 12, 2026
Merged

docs: document v1 single-instance constraint in architecture.md (#64)#66
ilmoniemi merged 3 commits into
mainfrom
feature/64

Conversation

@ilmoniemi
Copy link
Copy Markdown
Contributor

Summary

Adds a Single-instance constraint (v1) section to docs/architecture.md, between What this binary does NOT do and Threat model. Covers:

  • Why v1 is single-instance — in-memory registry; disjoint replicas → silent 4404 when phone and binary land on different replicas.
  • What multi-instance would require — shared registry (Redis/NATS) or sticky-session-on-server-id at the LB; both documented as future work, not a commitment.
  • The PYRYCODE_RELAY_SINGLE_INSTANCE=1 bypass 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.
  • Only docs/architecture.md changed (git diff --stat: 1 file, +32).

Architecture compliance

Follows the spec at docs/specs/architecture/64-*.md:

  • Heading contains the phrase "single-instance" (AC-1).
  • Section placed between behavioural contract and threat model.
  • Three subsections (why / what multi-instance would require / bypass env var) + no threat-model.md cross-link (spec recommended skipping it; the constraint is operator foot-gun, not adversarial threat).
  • Tone matches existing declarative present-tense style; refers to relay: startup self-check refuses to run as multi-instance deploy #65 by number for enforcement detail rather than restating it.

ilmoniemi added 2 commits May 12, 2026 19:24
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.
@ilmoniemi
Copy link
Copy Markdown
Contributor Author

Code Review: #64

Decision: PASS

Findings

None.

Summary

Doc-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 4404 symptom; the multi-instance subsection enumerates shared registry (Redis/NATS) and sticky-on-header at the LB, both framed as future work; the bypass subsection contains the exact string PYRYCODE_RELAY_SINGLE_INSTANCE, lists emergency rollback and migration windows as intended uses, and flags it as NOT recommended for production. Section placement (between "What this binary does NOT do" and "Threat model") matches the spec, and the prose matches the existing declarative register. No code touched.

…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>
@ilmoniemi ilmoniemi merged commit 748490b into main May 12, 2026
2 checks passed
@ilmoniemi ilmoniemi deleted the feature/64 branch May 12, 2026 16:30
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.

relay: document v1 single-instance constraint in architecture.md

1 participant