docs: publish architecture boundary ADR baseline - #32
Merged
Conversation
📝 WalkthroughWalkthroughThe PR establishes an indexed ADR baseline, clarifies contributor documentation entry points, refines existing architecture decisions with rationale and revisit triggers, and adds ADRs for trusted Runtime access and immutable revision publication. ChangesArchitecture baseline
Estimated code review effort: 3 (Moderate) | ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/decisions/0018-immutable-revision-publication.md`:
- Around line 34-37: Update the reader consistency contract in the immutable
revision publication decision: require readers to use one database
snapshot/transaction for selecting the active ContextRevision and fetching all
fragments and indexes, or require every lookup to bind explicitly to that
selected ContextRevision. Clarify that the complete old-or-new guarantee depends
on this reader-side behavior, not solely on the publication transaction.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 23e3297a-8201-49b4-ae4b-03b213d28c89
📒 Files selected for processing (12)
README.mddocs/agents/domain.mddocs/decisions/0001-adopt-doc-steward-standard.mddocs/decisions/0002-bot-gateway-outside-engine.mddocs/decisions/0006-engine-delivers-context-not-answers.mddocs/decisions/0008-modular-monolith-plus-worker.mddocs/decisions/0011-read-write-plane-separation.mddocs/decisions/0012-sealed-authorization-projection-pipeline.mddocs/decisions/0015-rls-transaction-context-and-schema-manifest.mddocs/decisions/0017-trusted-invocation-and-closed-runtime-access.mddocs/decisions/0018-immutable-revision-publication.mddocs/decisions/README.md
Comment on lines
+34
to
+37
| indexing occur before activation. Publication changes the ContextResource's | ||
| active ContextRevision pointer in one PostgreSQL transaction so a reader sees | ||
| the complete old ContextRevision or the complete new ContextRevision, never a | ||
| hybrid. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Define the reader-side consistency contract.
Updating the active pointer in one transaction does not by itself prevent hybrid reads when fragments or indexes are fetched in separate statements/transactions. Specify a single read snapshot/transaction or require every content/index lookup to bind to the selected ContextRevision; otherwise the “complete old or complete new” guarantee is not enforceable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/decisions/0018-immutable-revision-publication.md` around lines 34 - 37,
Update the reader consistency contract in the immutable revision publication
decision: require readers to use one database snapshot/transaction for selecting
the active ContextRevision and fetching all fragments and indexes, or require
every lookup to bind explicitly to that selected ContextRevision. Clarify that
the complete old-or-new guarantee depends on this reader-side behavior, not
solely on the publication transaction.
This was referenced Jul 26, 2026
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
1 participant
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.
Closes #4
Outcome
Publishes a contributor-facing architecture decision baseline for the seven implementation boundaries fixed by issue #4. Existing accepted ADRs are reused and completed with explicit rationale/revisit sections; two independently revisitable gaps receive focused ADRs:
The index documents allowed dependency direction, public interfaces, prohibited shortcuts, and links every accepted ADR. README and the agent domain guide link the index. No executable implementation, schema, or speculative provider choice is included.
Definition of Done evidence
CONTEXT.md.Verification
npx --yes markdownlint-cli2@0.18.1 README.md docs/agents/domain.md docs/decisions/README.md docs/decisions/*.mdnpx --yes markdown-link-check@3.13.7for the contributor entry points and changed ADRs.git diff --checkThere is still no runnable application or dependency manifest in D0, so issue-appropriate document, structure, contradiction, and link checks are the executable verification surface.
Summary by CodeRabbit