Repository navigation
docs(rendering): evergreen architecture reference + TDD design principles - #500
Merged
Merged
Conversation
…ples Two durable docs describing the CURRENT rendering pipeline (post the 2026-07 ownership-ledger rewrite and #491/#492 block-level un-collapse), to complement the migration-era plans already in docs/rendering/ (rewrite-plan, residue, knowledge-dump), whose Stage-progress preambles are partly stale. - rendering-system.md — how the system works end to end: the three stages (INGEST channels→SessionRuntime, DECIDE ownership-ledger, RENDER feed painter), the one invariant, the data model, ownership decisions, the ordering law, ghosts, unknowns, identity-stability, and a where-to-look index. Grounded in a 4-agent deep read with file:line refs. - rendering-design-principles.md — how we WORK the pipeline: test-first, because the distributed-ownership bug class (two owners / suppress-before- replace / present-but-buried) is one focused patches provably can't hold. Codifies P1 reproduce-as-fixture-first, P2 every reason proves itself with a fixture (rule 15 — honestly noted as review-enforced, not mechanized), P3 assert order+ownership not existence, P4 decision-record IS the debug schema, P5 reference stability is correctness, P6 bias to survive; the three-layer test net (unit / bundle corpus / recording+invariant replay); the change workflow; and the hard do-not list distilled from the shipped scars. Both flag stale tokens (SemanticStreamingTurn, AGENT_CODE_RENDER_SHADOW/ PIPELINE, deriveFeedRenderModel — all deleted) for cleanup. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…eview of #500 Co-Authored-By: Claude Fable 5 <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.
What
Two evergreen documents under
docs/rendering/, written from a full read of the shipped pipeline (post-#491/#492 ledger world):rendering-system.md— the architecture reference: the three-stage model (INGEST → DECIDE → RENDER), the one invariant (exactly-once ownership of every block), the data model (SessionRuntime, observations,RenderRow), how ownership decisions are made, the ordering law, ghosts, unknown-block handling, identity stability, and a where-to-look index mapping symptoms to files.rendering-design-principles.md— how to work on the pipeline: the TDD principles (P1–P6) motivated by why live rendering bugs are commonly un-diagnosable at runtime (multi-channel races, timing-dependent paths), the three-layer test net (unit / bundle corpus / recording + invariant replay), fixture-gated reason codes (review-enforced, not mechanized), and a failure taxonomy.Why
The rendering rewrite (#442 → #483 → #491/#492) retired the old semantic-streaming turn model; the tribal knowledge of how the ledger actually works existed only across PR descriptions and session context. These docs are the durable version — written to stay true at the architecture grain (stages, invariants, contracts) rather than the line-number grain.
Companion to #493 (layer isolation): the three stages these docs describe are exactly the three folders #493 proposes to physically isolate.
Docs only — no code changes.
🤖 Generated with Claude Code