docs: define canonical local and managed T4 architecture - #109
Merged
Conversation
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 I changed
I made
docs/T4_ARCHITECTURE.htmlthe sole detailed specification for T4 execution architecture.I defined four profiles behind one Flutter experience:
I converged every profile on one T4-owned adapter around pinned official OMP over bounded NDJSON. Local calls it directly; managed runtimes and Workstation Runners use runtime-initiated Runtime Wire connections. I specified that ambiguous post-dispatch outcomes become
indeterminateand are never automatically replayed. Local files stay local, managed files stay on CephFS, and I did not introduce a background synchronization layer between them.I also removed documentation that duplicated the same decision:
PRODUCT_BRIEF.mdback to product and UX promises.docs/OWNERSHIP.mdback to repository path governance and handoffs.Why I changed it
I reconciled two useful but conflicting directions. The official-OMP audit correctly required a shared public adapter, truthful capability reporting, no permanent broad OMP fork, and explicit handling of ambiguous dispatch. The detailed managed plan correctly selected k3s, PostgreSQL, CephFS, MinIO, Tailscale, and Grafana LGTM, but made that full stack the only long-term product path.
I kept those managed decisions while restoring a first-class native local path. A macOS or Linux user can run T4 locally without a Linux VM or managed stack, while Personal Hub and HA Hub retain the full managed architecture. Workstation Runner covers Hub-controlled native execution without pretending that runner-local files are portable.
No runtime behavior changes in this PR.
How I verified it
node --test scripts/check-host-ownership.test.mjs scripts/check-adr-numbering.test.mjsand saw 5/5 tests pass.docs/T4_ARCHITECTURE.htmlas XHTML-style XML and saw 126 IDs, 54 internal anchors, zero duplicate IDs, and zero missing targets.PRODUCT_BRIEF.mdanddocs/OWNERSHIP.mdand saw zero missing files.Checklist
pnpm checkpasses (not run; documentation-only change with focused checks above)pnpm testpasses (full suite not run; focused documentation tests pass)