Skip to content

docs: fold nix2cf into tendcf; plugin-type layout (D46) - #46

Merged
djbclark merged 9 commits into
masterfrom
monorepo-layout-docs
Nov 13, 2026
Merged

djbclark merged 9 commits into
masterfrom
monorepo-layout-docs

Conversation

@djbclark

@djbclark djbclark commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

What

Documents djbclark's 2026-11-13 decision to fold frdminc/nix2cf into tendcf and give the repo a plugin-type layout. New decision D46; D12 and D21 amended, D15 and §9.6 given D46 notes; new docs/architecture/plugin-layout.md.

  1. The compiler (nix2cf, Site Model → per-host goal file) moves into tendcf under compiler/ with history. Done: Import nix2cf under compiler/ (history preserved) #45 merged 2026-11-13 (ca4fa90), and frdminc/nix2cf was archived the same day. This branch is rebased on that master, so the docs cite compiler/ and its CI job as they exist.
  2. Target layout: tools/ (was bin/), compiler/, plugins/{frontends,supervisors,importers}/, contrib/. It becomes one Python package, import name tendcf. Public entry-point groups tendcf.frontends and tendcf.importers, so third-party frontends and importers can also live out of tree; supervisor renderers are in tree only (no public tendcf.supervisors group). Plugins are compile-time only and are trusted build-time code the operator explicitly allows (see Decisions).
  3. The compiler CLI becomes tendcf compile (every host by default, --host for one), replacing nix2cf buildfile with no alias; the name nix2cf moves to the Nix-module frontend (D12).
  4. nix2cf is no longer a separately pinned input: compiler and schema change in one commit. change-process.md loses the two-repo bump order and nix2cf's never-built tendcf.lock; site.lock loses only its nix2cf entry. One tendcf rev is now the unit a site pins, and the docs name that coupling.
  5. The guide's illustrative nix2cf_services/nix2cf_edges keys (never real wire keys; the projected keys are tendcf_service/tendcf_interlock) become preview_services/preview_edges. No schema change.
  6. Stale "the compiler is not built" text corrected: buildfile exists. Stale "only launchd adapter" text corrected: the systemd branch of the generic bundle exists. Fixture counts updated to 159 (125 schema-level, 6 byte-class, 28 projection).

Files: the guide, the paper, architecture-DEFINITIVE-v3.md, change-process.md, linux-targets.md, GLOSSARY.md, docs/architecture/README.md, new plugin-layout.md. No code, schema, fixture or path moves.

Decisions (djbclark, 2026-11-13, on the reviews)

  1. Trust model. Plugins are trusted build-time code the operator explicitly allows, not sandboxed. Release gates (schema lint, projector, preview diff) and signing run in a separate environment with no plugin installed; the compile step holds no signing key. A compile-side preview diff or explain-hunk (D44) is compiler output and inherits plugin trust. The consent claim is now stated exactly in all five places: a plugin cannot make a device accept anything its own diff does not show, and cannot emit a shape the schema forbids, but it can make the goal file say something other than the Site Model says. contrib/'s lower bar waives support and maintenance promises, never the standing review rule. Out-of-tree trust establishment (OpenPGP web of trust, tendcf plugin management): Plugins: OpenPGP web of trust and paseo-style tendcf plugin management #47.
  2. Activation. A plugin loads only if site-private names it (name → distribution, version, hash); installed-but-unnamed is ignored; a duplicate name in a group is a compile error; built-in names are reserved; release builds load in-tree plugins only until out-of-tree pinning exists (Plugins: OpenPGP web of trust and paseo-style tendcf plugin management #47); the release's targets.json custom records the plugin set.
  3. Supervisor renderers are in tree only: unit is a closed oneOf, so an out-of-tree renderer could only shadow a built-in. Public groups: tendcf.frontends, tendcf.importers.
  4. No users, no backward compatibility. (a) One tendcf rev is the pinned unit; the compiler/policy coupling is named and accepted, no maintenance-branch machinery, revisit when the first non-operator device enrolls. (b) No shims: tendcf compile replaces nix2cf buildfile outright, the Python package is renamed tendcf, bin/ → tools/ leaves no symlinks or wrappers and rewrites every path reference in every file, dated records included (djbclark, 2026-11-13: a one-time exception to their append-only convention; only paths change, and prose naming nix2cf as the old repository stays as history). (c) The compiler renders only the current schema_version; older-version rendering is removed in the restructure; map §9.6's ceiling design stays and applies once the first non-operator device enrolls. (d) frdminc/nix2cf is archived as soon as Import nix2cf under compiler/ (history preserved) #45 merges: done 2026-11-13.

Not in this PR

The restructure (one PR after #41/#42): bin/ → tools/, package rename to tendcf, the plugin split, tendcf compile, removal of older-version rendering, the device-boundary import check. plugin-layout.md §5 states its rewrite scope and lists the files found. Historical records (handoffs, reviews, deprecated, dated opinions) are unchanged in this PR; the restructure rewrites their paths only.

Verification

bin/schema_lint.py: OK (8 schemas, 125 negative, 6 byte-class, 28 projection fixtures). bin/xref_lint.py: 107 live documents, 0 findings. Both run through bin/bg at the final head. git diff --check clean.

Review

Design ruling: two cross-model frontier reviews.

  • Astra (gpt-6-astra, high): "MERGE AFTER FIXES. The consolidation is sound; the plugin trust and reproducibility claims need bounded guarantees before this becomes implementation guidance."
  • Fable (claude-fable-5-2, high): "Merge after fixes." Nothing argues against the fold itself.

The two reviews do not disagree; Astra's A1/A2 and Fable's H1/H2 are the same two gaps seen from two sides. Resolution of every finding:

Finding Resolution
A1 (P1) output validation is not a boundary for third-party plugin code Fixed by decision 1: trusted build-time code, gates and signing apart, no signing key in compile (plugin-layout.md §4, D46 (4), change-process.md §6)
A2 (P2) plugin pinning leaves the reproducibility invariant incomplete Fixed by decision 2 (release builds load named in-tree plugins only until #47; targets.json records the plugin set) plus round-2 A2: the pin identifies sources; byte reproduction also needs a dependency/toolchain closure and controlled external inputs, not yet specified (plugin-layout.md §4, §7; change-process.md §3; guide §4)
A3 (P2) "reaches a device only as a diff" Fixed: the full signed canonical goal file reaches the device, which computes the diff (plugin-layout.md §4)
A4 (P2) paper drops the Nix passthrough exception Fixed: paper §2.2 matches the guide
A5 (P2) "every supervisor adapter except launchd" unbuilt Fixed in guide §4, guide §18 (built list and "Not built") and paper §8: launchd and systemd device adapters exist; compiler renderers kept distinct
A6 (P3) "one command" Fixed: buildfile is the compilation command, eval-nix a hook (plugin-layout.md §2, map Step 3, change-process.md §2)
H1 consent claim is a non sequitur Fixed by decision 1 in all five places (plugin-layout §4, map §5, D46, guide §4, paper §2.2)
H2 activation and name collision Fixed by decision 2 (plugin-layout.md §4, D46 (5), change-process gate 2)
M1 device boundary left to convention Fixed: device artifact from the validator alone, no compiler/plugins/contrib imports or entry-point discovery; schema lint and projector never import the compiler; CI import check planned (plugin-layout.md §4, D46 (4))
M2 one pin couples compiler and policy Fixed by decision 4a: named and accepted (change-process.md §8 items 2 and 5, §9 item 2; plugin-layout.md §1; D46 (8))
M3 version skew not gone Resolved by decision 4c: current schema_version only; change-process sentences qualified; map §9.6 note
M4 tendcf.supervisors not a real extension point Resolved by decision 3: no public group (plugin-layout.md §3)
M5 contrib/ lower bar Fixed via decision 1: waives support/maintenance only, never review; off unless named
M6 site.lock wording Fixed: "site.lock loses only its nix2cf entry …" (change-process top note, plugin-layout §1)
L1 two live referents of nix2cf Resolved by decision 4b (no alias); glossary says which sense holds when
L2 subcommand mapping Fixed: tendcf compile compiles every host, --host renders one; eval-nix moves to the Nix frontend; Bcfg2 buildfile lineage kept in prose only
L3 "stays one Python package" Fixed: "becomes one Python package", import name tendcf; directory mapping and schema-as-package-data listed in §7
L4 living contract files Fixed: plugin-layout.md §5 states the rewrite scope (every path in every file, dated records included; prose stays) and lists the files found (incl. all of compiler/, schema descriptions, examples, AGENTS.md and its handoff rule, README, overlay, check.yml, canary check, D45)
L5 D15 vs amended §5 Fixed: D15 pointer to the goal file
L6 = A4 Fixed (A4)
L7 = A5 Fixed (A5), plus guide §4 (adapter paragraph) and the §18 built-list bundle line, since the guide wins
L8 Guix line Fixed: Guix is an authoring frontend (Guile records → Site Model JSON); Guix System with Shepherd is a separate, undecided question
L9 cosmetic Fixed: long lines rewrapped; linux-targets.md names today's nix-instantiate hook beside the planned nix eval

Fix-round re-reviews (at f2646cd)

  • Astra (gpt-6-astra, high): "MERGE AFTER FIXES — reconcile the historical-path rewrite instructions and qualify the remaining reproducibility claim."
  • Fable (claude-fable-5-2, high): "Merge after fixes." All 17 first-round findings resolved in substance; three text fixes left by the fix round.

No disagreement between them (Astra A1 = Fable F1). All fixed in b315772 (plus fd43679, a13e892):

Finding Resolution
Astra A1 / Fable F1: rewrite scope stated two ways Fixed: every statement now matches djbclark's ruling (every path in every file, dated records included; prose stays): plugin-layout.md §5 item 5 and the AGENTS.md handoff-rule clause in item 4, §6 item 2, map D46 (6), GLOSSARY, this PR body
Astra A2: reproducibility still overclaimed Fixed: qualified in plugin-layout.md §4 activation item 4 and §7, change-process.md §3 property 1, guide §4 "pure function"
Fable F2: guide §7 still describes per-host multi-version render Fixed: guide §7 carries the decision-4c note (map §9.6)
Fable F3: #45 merged and nix2cf archived, docs said "will" Fixed: branch rebased on master; every row of F3's table updated (change-process.md top note, §2 table, §5, §6 compiler gate now "yes: compiler job"; plugin-layout.md §1, §2, §5; map §3, §5, Step 3, D46 (1), doc map; guide §2, §3, §4, §18 built list and Step 3; paper §2.1, §2.2; GLOSSARY). Remaining "move" wording names the restructure (§5 step 4)
N1 "no devices to strand" Fixed: "no device outside the operator's own hosts" (map §9.6 note)
N2 guide "Nothing described here is deployed" Fixed: "apart from a canary service on one operator host"
N3 operator-host caveat Fixed: guide §4 says the PR preview diff is the only human check on an operator host
N4 §5 list missed compiler/ files Fixed: item 1 now covers the rest of compiler/ (README, DESIGN.md, pyproject.toml, sitemodel.py, examples, tests, package name)

Lints at b315772 (plus fd43679, a13e892) (through bin/bg): bin/schema_lint.py OK (8 schemas, 125 negative, 6 byte-class, 28 projection fixtures); bin/xref_lint.py 107 live documents, 0 findings.

Final check (head fd43679, then a13e892)

  1. Astra (gpt-6-astra, high): merge. Fix-round A1 and A2 are resolved, and so are the original A1–A6. Nothing new in 64994e3..fd43679. fd43679 also qualifies the paper's §2.2 purity sentence to match the guide (A2).
  2. Fable (claude-fable-5-2, high): merge. F1–F3 and N1–N4 are resolved, nothing new, and djbclark's decisions are recorded accurately. Its four non-blocking leftovers are fixed in a13e892: X1 (the paper's "nothing deployed" now names the operator-host canary), X2 (the purity caveat no longer says "with plugins"), X3 (two sentences reworded) and X4 (this body).

Lints at a13e892: bin/xref_lint.py 0 findings; git diff --check clean.

🤖 Generated with Claude Code


Note

Low Risk
Documentation-only changes to architecture and process specs; no runtime code, schemas, or repository layout are modified in this PR.

Overview
Records operator decision D46 (2026-11-13): the compiler moves from archived frdminc/nix2cf into tendcf as compiler/, with a future plugin layout (tools/, compiler/, plugins/, contrib/) and CLI tendcf compile replacing nix2cf buildfile with no alias. nix2cf is redefined as the Nix module frontend plugin only.

Adds plugin-layout.md and threads the ruling through the implementer map, change-process (drop nix2cf from site.lock, two-repo bump order, and tendcf.lock; one tendcf pin; plugin activation/trust and release-gate separation), GLOSSARY, README, linux-targets, and the architecture guide and paper.

Also renames illustrative nix2cf_services / nix2cf_edges to preview_services / preview_edges, and updates status text (e.g. buildfile and systemd bundle exist, 159 broken fixtures, canary deployment caveat)—no code, schema, or path moves in this PR.

Reviewed by Cursor Bugbot for commit a13e892. Bugbot is set up for automated code reviews on this repo. Configure here.

djbclark and others added 6 commits November 13, 2026 06:47
…to tendcf

djbclark, 2026-11-13: frdminc/nix2cf folds into tendcf under compiler/;
the compiler becomes `tendcf compile`, the name nix2cf moves to the Nix
frontend plugin, plugins are found through the tendcf.frontends,
tendcf.supervisors and tendcf.importers entry-point groups and run at
compile time only. Docs only: no files move, no code or schema changes.

- guide §2-§4, §18: layer diagram, lockfile, compiler name and home;
  buildfile recorded as built (verified: nix2cf master 572b0b7 CI green)
- map: §1, §3, §5, Step 3, D12, D21 amended; new D46; document map
- change-process: one repo, no tendcf.lock, two-step bump; site.lock kept
- linux-targets step 6 and §5; GLOSSARY nix2cf entry; architecture README
- new docs/architecture/plugin-layout.md: tree, today vs planned,
  entry-point groups, consent rule, contrib/out of tree, move order

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…with D46

The nix2cf_services / nix2cf_edges keys only ever appeared in guide §16.A's
illustrative, non-loading preview example and its copy in the paper; no
schema, fixture, projector or bundle carried them. Rename them to
tendcf_services / tendcf_edges there now, note that the projection's real
keys are tendcf_service / tendcf_interlock (and that tendcf_services is the
real bundle's name), and drop the planned schema-v6 rename from D46 and
plugin-layout.md: no schema bump is involved.

Paper §2.1, §2.2, §2.6, §6.2, §8: compiler is tendcf compile, folded into
tendcf (decided 2026-11-13); nix2cf names the Nix frontend; one tendcf
pin covers schemas and compiler; buildfile recorded as built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Lead call on the follow-up: tendcf_services matched the real generic
bundle's name and was one letter off the projected key tendcf_service.
Rename the guide §16.A / paper §2.6 illustration keys to preview_* and
reword the note, D46 (6) and plugin-layout.md §6 item 4 accordingly. No
schema change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both frontier reviews (Astra gpt-6-astra high, Fable claude-fable-5-2
high) said merge after fixes. This records djbclark's decisions on them:
plugins are trusted build-time code the operator allows, with gates and
signing run apart from plugins; a plugin loads only if site-private names
it, in-tree only for releases until #47; supervisor renderers are in tree
only; one tendcf rev is the pinned unit; no shims (tendcf compile with no
alias, package renamed tendcf, bin/ -> tools/ with no wrappers); current
schema_version only until a non-operator device enrolls; nix2cf archived
as soon as #45 merges.

Also: device-boundary import rules (M1), site.lock wording (M6), the
compile/--host mapping (L2), the living-file list for the restructure
(L4), D15 pointer (L5), the paper's Nix passthrough exception and the
systemd adapter status (A4, A5), the device receives the full goal file
(A3), fixture counts 159 (125/6/28).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uded (djbclark 2026-11-13)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@djbclark
djbclark force-pushed the monorepo-layout-docs branch from f2646cd to 64994e3 Compare November 13, 2026 11:50
djbclark and others added 3 commits November 13, 2026 06:50
Re-reviews (Astra gpt-6-astra high, Fable claude-fable-5-2 high) both
said merge after fixes.

- Rewrite scope matches djbclark's ruling everywhere: every path in every
  file, dated records included; prose naming nix2cf stays (A1/F1).
- Reproducibility qualified: the pin identifies compiler and plugin
  source; byte reproduction also needs a fixed dependency/toolchain
  closure and controlled external inputs, not yet specified (A2).
- Guide section 7 carries the current-schema-version-only note (F2).
- PR 45 merged (ca4fa90) and frdminc/nix2cf is archived: compiler/
  exists and its tests run in tendcf CI (F3). Branch rebased on master.
- N1-N4: operator-host wording, deployment caveat, operator-host check
  in the guide, the rest of compiler/ in the restructure list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…caveat, two sentences)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@djbclark
djbclark marked this pull request as ready for review November 13, 2026 12:07
@djbclark
djbclark merged commit 40cf93a into master Nov 13, 2026
7 checks passed
@cursor

cursor Bot commented Nov 13, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 33e4a8e8-525f-4b50-afd2-732651c5a64f)

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T12:07:45.286466Z a13e892 Draft marked ready
🔒 Security Review ✅ Completed 2026-11-13T12:09:32.681306Z a13e892 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

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