Skip to content

docs: define canonical local and managed T4 architecture - #109

Merged
iarbpairs merged 6 commits into
mainfrom
feat/t4-hub
Jul 21, 2026
Merged

docs: define canonical local and managed T4 architecture#109
iarbpairs merged 6 commits into
mainfrom
feat/t4-hub

Conversation

@iarbpairs

@iarbpairs iarbpairs commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

What I changed

I made docs/T4_ARCHITECTURE.html the sole detailed specification for T4 execution architecture.

I defined four profiles behind one Flutter experience:

  • T4 Local: native macOS/Linux Local Service, SQLite command ledger, official OMP adapter, and local files; no VM or managed stack.
  • Personal Hub: the full managed stack on one Linux machine, explicitly non-HA.
  • HA Hub: three or more tested Linux failure domains with hard writer fencing before portable recovery.
  • Workstation Runner: a Hub-registered native macOS/Linux executor whose sessions remain pinned and nonportable.

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 indeterminate and 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:

  • I deleted ADR-016 because the canonical HTML plus Git history preserves the decision and its evolution.
  • I deleted the checked-in Hub tracker because the architecture owns delivery gates and GitHub issues/PRs should own live status.
  • I trimmed PRODUCT_BRIEF.md back to product and UX promises.
  • I trimmed docs/OWNERSHIP.md back to repository path governance and handoffs.
  • I updated the ownership contract test to verify that those documents point to the canonical architecture.

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

  • I ran node --test scripts/check-host-ownership.test.mjs scripts/check-adr-numbering.test.mjs and saw 5/5 tests pass.
  • I parsed docs/T4_ARCHITECTURE.html as XHTML-style XML and saw 126 IDs, 54 internal anchors, zero duplicate IDs, and zero missing targets.
  • I resolved local links from PRODUCT_BRIEF.md and docs/OWNERSHIP.md and saw zero missing files.
  • I opened the HTML in Chromium and saw the expected title, 54 sections, four figures, and zero broken internal anchors.

Checklist

  • pnpm check passes (not run; documentation-only change with focused checks above)
  • pnpm test passes (full suite not run; focused documentation tests pass)
  • Any pasted logs or screenshots are redacted: no secrets, tokens, pairing codes, or private paths
  • No third-party source was ported in this change

@iarbpairs
iarbpairs merged commit 8a22be7 into main Jul 21, 2026
8 checks passed
@iarbpairs
iarbpairs deleted the feat/t4-hub branch July 21, 2026 02:13
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.

1 participant