Tracker: tendcf architecture

[djbclark]

tendcf architecture tracker

The vetted current-state description is
docs/paper/tendcf-architecture-guide.md.
Where any other living document disagrees on the current design, the guide wins.

The implementer map (decisions, build order, protection) is
docs/architecture/architecture-DEFINITIVE-v3.md
and must agree with the guide.

This issue tracks that architecture. It is not a nix-darwin evaluation ticket. Optional Mac substrate (nix-darwin / home-manager) is Step 7 only, gated on §14.1.

Remaining Step 0

• peer_actions
• trust-policy shape
• generic unit-writers
• lookup stub
• YAML canonicalize
• transcribe reality (not-yet-migrated is the correct day-one state)

Schemas, happy-path fixtures, twelve negative fixtures, and bin/schema_lint.py already live in this repository.

Build order from here

Step	What
0	Finish the contract (list above)
1	macOS services adapter. Dry-run default. Not nix-darwin.
2	Android under the Site Model; agent owns JSONL+SQLite
3	nix2cf compiler (buildfile first, then conflict, extra-entry, inference)
4	Linux reference path on a stock distro
5	First real Linux host; prove roles are data
6	Signed releases, push-only, ChangePlan executor
7	Optional Mac substrate if §14.1 says yes
8	Pull / self-update
9	Consent surface + default prompt + advisor slot
10+	Demand-driven

Premium-token residue (§14)

Do not improvise these:

1. nix-darwin on the Mac, yes or no (gates Step 7 only)
2. ChangePlan IR + executor capability vocabulary
3. Advisor / personal-branch loop
4. TUF-subset ceremony + recovery runbook

[djbclark]

Follow-up: mise is worth evaluating as a lower-risk first boundary than system-level Nix for developer tooling. Its docs cover per-project tool versions, env vars, tasks, lockfiles, Homebrew/bootstrap integrations, macOS defaults, and launchd. Treat mise-only developer tooling as the smallest prototype, with explicit controls around auto-install, plugin/backend trust, lockfile reproducibility, secretspec boundaries, and not overlapping CFEngine service adapters or optional nix-darwin substrate.

[djbclark]

Scope: this issue tracks the tendcf architecture

Per operator direction (2026-08-08), this ticket covers the full architecture: a declarative management spine for macOS/Apple Silicon, Linux x86_64+aarch64, and Android, with future extension points (IoT, iPhone, wearables, routers).

The current tracker text is the issue body. Living current-state: docs/paper/tendcf-architecture-guide.md (wins on conflict). Implementer map: docs/architecture/architecture-DEFINITIVE-v3.md.

State as of this comment (2026-08-08)

Panel drafts were being collected under docs/architecture/ (now in docs/architecture/deprecated/):

Document	Status then
architecture-proposal-v1.md	Claude proposal
SECOND-OPINIONS-BRIEF.md	Shared brief for independent reviewers
architecture-proposal-openai-v1.md	OpenAI
architecture-proposal-gemini-v1.md	Gemini (contrarian mise-first thesis)
architecture-proposal-grok-v1.md	Grok — in progress at this comment
Final synthesis	Next step at this comment

Decisions already stated by the operator (still hold unless v3 says otherwise)

Intel Mac mini out of scope · roles-not-control-node end state · no VMs / fat containers · nix-on-droid rejected · no bare-metal Nix · Gradle stays for APK builds · push and pull deploys, evolving to consent-based deploys · secretspec remains sole secrets authority · signed releases (not a sibling-repo tag lockstep).

[djbclark]

Second-opinion panel complete — v1 synthesis delivered

Panel drafts (now archival under docs/architecture/deprecated/):

Document	State
architecture-proposal-v1.md (Claude)	archived position
architecture-proposal-openai-v1.md	delivered
architecture-proposal-gemini-v1.md	delivered; contrarian no-Nix/mise-first thesis
architecture-proposal-grok-v1.md	delivered, including critique of the Claude proposal
architecture-final-v1.md	v1 synthesis of all four + dialogue

Headline then: reject the evaluated starters as the spine; Site Model + signed manifests/ChangePlans. Service ownership was later locked as CFEngine on every platform (D13), with launchd as one supervisor adapter and unit-writers lint (one writer per prefix). Nix is not the installed OS.

Panel notes: Gemini's first draft was misplaced and rewritten; a DeepSeek seat was dropped (can be commissioned later).

Those v1 files are snapshots. Current design is the vetted guide; this issue's body is the tracker.

[djbclark]

Adversarial security review — trust layer blockers before v1 pull/consent

Archival under docs/architecture/deprecated/ (and the brief in docs/architecture/):

• REDTEAM-BRIEF.md — the adversarial brief
• redteam-trust-layer-openai-v1.md — 9 findings + systemic gaps + prioritized fixes (different vendor than the synthesis author, deliberately)
• ideas-dump-claude.md — low-effort dump, not protected

Verdict (paraphrased)

Do not ship v1 pull-deployment or consent on a one-key/one-manifest design. A valid signature proves "one key signed these bytes" — not freshness, safe target, bounded operation, independent provenance, or recoverability after compromise.

Critical findings (still load-bearing)

• RT-01 one release key = fleet-root → TUF-style threshold roots before v1 pull
• RT-03 signed plans describe but don't constrain execution → typed ChangePlan IR the executor enforces
• RT-05 builder/cache confused boundary → separate build/upload/serve/release authority

High findings

RT-02 replay/freeze/downgrade · RT-04 consent without a capability-enforcing executor · RT-06 secretspec handle-injection · RT-07 peer mesh with no real fencing · RT-08 privileged Android helper APKs with no provenance gate · RT-09 personal-branch auto-merge as an injection channel

Current design folds these into TUF-subset ceremony (D41), ChangePlan executor, per-device trust (D38), and the advisor slot (D39). See the issue body and the vetted guide.

[djbclark]

Architecture map written (then v2; current is v3)

The then-current synthesis superseded architecture-final-v1.md and folded in the panel, the red-team, the tooling reviews, the defensive pass, and the pre-mortem.

Decisions from that round that still hold (see v3 / the guide):

• No bare-metal Nix. A stock distro is the Linux reference (Ubuntu Server is the working default). Nix stays for artifact builds, dev shells, and optional Mac substrate.
• The trust/consent layer is user sovereignty: a person understands a change in ordinary language, refuses it, and may keep a personal branch, using their own AI.
• Token budget is a real constraint; premium spend is reserved for the flagged decisions.

Premium residue (now v3 §14):

1. nix-darwin on the Mac, yes or no (gates Step 7 only)
2. ChangePlan IR + executor (independent adversarial review before building)
3. Advisor / personal-branch loop + AI-in-the-loop red-team
4. TUF-subset ceremony + recovery runbook

v2 is archival (docs/architecture/deprecated/). Current implementer map is architecture-DEFINITIVE-v3.md; current-state description is the vetted guide. This issue's body is the tracker.

[djbclark]

Docs landed in this repository

The architecture research and the then-definitive map were pushed for review as documentation only (no runtime behavior change). Merging and later revisions are operator-gated.

Current pointers: vetted guide docs/paper/tendcf-architecture-guide.md; implementer map docs/architecture/architecture-DEFINITIVE-v3.md; this issue's body for remaining Step 0 and the build order.