Skip to content
This repository was archived by the owner on Nov 13, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@ jobs:

- uses: astral-sh/setup-uv@v5

# A tendcf schema_version bump that nix2cf has not followed fails here
# with one clear line, not as a wall of "was expected" test failures.
- name: GOAL_FILE_SCHEMA_VERSION equals tendcf's schema const
run: uv run python scripts/check_schema_version.py "$GITHUB_WORKSPACE/tendcf"

- name: Tests
env:
TENDCF_DIR: ${{ github.workspace }}/tendcf
Expand Down
26 changes: 20 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,18 @@ touching the host.
```sh
export TENDCF_DIR=~/src/tendcf # schemas + reference projector
uv run nix2cf buildfile \
--host mac --platform macos \
--host mac --platform macos --supervisor launchd \
--host-key ed25519:a1a1…a1 \
--device-trust examples/site/device-trust.json \
--site examples/site # services.yml, roles.yml, launchd-writers.yml
```

`--platform` (`macos` or `linux`) and `--supervisor` (`launchd`, `systemd`,
`runit` or `nixos`) are both required and have no default. It is written into the goal file's `device-trust.entries.supervisor`;
a `--device-trust` document that already carries a different `supervisor` is
refused. The output is **schema_version 4** (tendcf's `goal-file.schema.json`);
CI fails when `GOAL_FILE_SCHEMA_VERSION` and tendcf's schema const differ.

That prints the host's **goal file**: the canonical (RFC 8785, no trailing
newline) JSON document of guide §7 that a release carries, that consent binds
to, and that `tendcf/schema/goal-file.schema.json` checks. Add `--project` to
Expand All @@ -60,20 +66,28 @@ What the compile does, in order:
checked, and (in the tests) projected through tendcf's reference projector
with zero findings.

A `nixos` host gets no services: selecting any is refused ("host is
nixos-supervised; its units are the Nix configuration's"), and the goal file
carries `supervision: {"coverage": "deliberately-unmanaged"}` with the
`supervisor` entry, which tendcf's projector reads as `{"vars":{}}`.

`examples/site/` is tendcf's own fixtures with one edit, so an interlock
renders. Fixture, not site data.

## Not here yet

- **Inference** (`provides`/`requires` → ordering edges): waits until real
types exist on two platforms (guide §10, §18 Step 3), and goal-file v1 has no
types exist on two platforms (guide §10, §18 Step 3), and the goal file has no
edge kind to render into.
- **Any supervisor but launchd**, and therefore any Linux or Android host
(Steps 1–2, 4). A non-macOS host is a compile error, not a guess.
- **Units for any supervisor but launchd** (Steps 1–2, 4, 6). A `systemd` or
`runit` host gets its `supervisor` entry, but a service selected for it is a
compile error, not a guess: the systemd renderer (and with it the v2
`restart`/`wanted_by` fields) is step 6 proper. `nixos` needs no renderer,
as above. Android has no supervisor decided: it is not a `--platform` choice.
- **Extra-entry reporting** (device-side, tendcf-agent) and `def.json`.
- **Inventory, trust policy, peer actions** as Site Model inputs (Step 0
remaining): the host key, platform and `device-trust` domain are passed on
the command line until those schemas exist.
remaining): the host key, platform, supervisor and `device-trust` domain are
passed on the command line until those schemas exist.
- **Tombstones** from the Site Model (it cannot yet say "absent").
- **The Nix module frontend** (D12). `nix2cf eval-nix FILE` evaluates a plain
Nix expression with `nix-instantiate --eval --strict --json`; the test for
Expand Down
21 changes: 16 additions & 5 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,21 @@ oracle for the one that exists is `tendcf/examples/host_specific.json`.

- *Dependency inference* (`provides`/`requires` → ordering edges). Guide §10:
"Inference does not start until real type definitions exist on two
platforms." Goal-file v1 also has no edge kind (reconciliation §8), so there
platforms." The goal file also has no edge kind (reconciliation §8), so there
is nothing to render an edge into yet. `provides`/`requires` are used only by
the conflict check (two providers of one token on one host) and to report
unmatched `requires` as notes.
- *Every supervisor except launchd.* The goal file's `unit` admits launchd,
systemd and runit; only the launchd adapter exists (guide §4, §18 Step 1).
A linux/android host is a compile error here, not a guess.
- *Android/Termux* (Step 2) — no Termux unit flavor exists in the goal file.
- *Every supervisor's units except launchd's.* The goal file's `unit` admits
launchd, systemd and runit; only the launchd adapter exists (guide §4, §18
Step 1). A systemd or runit host is stated (its `supervisor` entry) but any
service selected for it is a compile error here, not a guess. The systemd
renderer is linux-targets step 6 proper, so none of the v2 systemd fields
(`restart`, `wanted_by`) or the systemd argv/`working_dir` alphabet is
written by nix2cf yet. A `nixos` host is complete: it has no units to
render (see below).
- *Android/Termux* (Step 2) — deferred (linux-targets ruling 2026-10-29). `android`
is not a `--platform` choice and the platform↔supervisor table refuses it;
the `runit` flavour exists in the goal file but has no renderer here.
- *Extra-entry reporting* — device-side, needs tendcf-agent.
- *def.json* — MPF glue under the policy-tree digest, never per-host
(reconciliation §9).
Expand Down Expand Up @@ -90,6 +97,10 @@ Each of these is marked `TODO(operator)` in `nix2cf/compile.py` at the spot.
| Unit-writer registry | Every declared prefix is carried (the device runs extra-entry detection without the Site Model, reconciliation §8). | — |
| Unmatched `requires` | A note, and `path:`/`secret:` kinds only counted (their providers are site registries, not Site Model records). | Guide §15 says a compile error with near-misses once the lookup exists. |
| `device-trust`, host key, platform | Supplied by the caller (`--device-trust`, `--host-key`, `--platform`). | Inventory and trust-policy shapes are "Step 0 remaining". |
| `supervisor` | A required host input (`--supervisor launchd\|systemd\|runit\|nixos`) next to `platform`, **no default** (house rule; spec Q1/Q8). Written into `device-trust.entries.supervisor` as `{"host":{"name":X,"state":"present"}}`. A supplied `device-trust` document whose `supervisor` entry differs is refused; one that omits it is fine. | No inventory schema exists (spec Q8); the flag goes when it does. |
| Platform ↔ supervisor | `macos` has `launchd`; `linux` has `systemd`, `runit` or `nixos`; any other pairing, and `android`, is refused. | Not in the spec. Android/Termux is deferred (linux-targets ruling 2026-10-29), so `android` is refused rather than mapped to runit. |
| `nixos` host | Any selected service is refused ("host is nixos-supervised; its units are the Nix configuration's"). With none, the goal file carries `supervision: {"coverage": "deliberately-unmanaged"}` and no unit-writer registry; tendcf's projector reads it as `{"vars":{}}`. | Spec §6.2 item 3, Q3. |
| Older `schema_version` | Library only (`compile_host(..., schema_version=N)`): 3 renders without the `supervisor` entry; a `nixos` host is refused below 4; anything else is refused. The CLI always renders the current version, and an older file is not schema-validated (tendcf's schema is a const). | Spec §6.2 item 6. |
| Tombstones | Cannot be rendered: the Site Model has no way to say "absent". | Goal file supports them; the Site Model does not yet. |

## Conflict check (stage 2)
Expand Down
8 changes: 7 additions & 1 deletion examples/site/device-trust.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@
"state": "present"
}
},
"supervisor": {
"host": {
"name": "launchd",
"state": "present"
}
},
"trust-policy": {
"consent": {
"local_yes_required": true,
Expand All @@ -27,4 +33,4 @@
}
}
}
}
}
28 changes: 22 additions & 6 deletions nix2cf/cli.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
"""`nix2cf` command line.

nix2cf buildfile --host mac --host-key ed25519:… --device-trust trust.json \
--site examples/site [--tendcf ~/src/tendcf] [--project] [-o OUT]
nix2cf buildfile --host mac --platform macos --supervisor launchd \
--host-key ed25519:… --device-trust trust.json --site examples/site [--tendcf ~/src/tendcf] [--project] [-o OUT]

Renders exactly what one host would receive — the Bcfg2 `buildfile` shape the
guide (§4) and the paper (§6.2) say to build first — without touching the
Expand Down Expand Up @@ -33,7 +33,7 @@
from typing import Any

from . import __version__
from .compile import CompileError, HostSpec, compile_host
from .compile import SUPERVISORS, CompileError, HostSpec, compile_host
from .sitemodel import SITE_FILES, Schemas, SiteModel, SiteModelError, load_document, load_site_model, validate_site_model


Expand Down Expand Up @@ -88,7 +88,13 @@ def cmd_buildfile(args: argparse.Namespace) -> int:
print(f"nix2cf: {len(problems)} Site Model schema finding(s); not compiled", file=sys.stderr)
return 1

host = HostSpec(name=args.host, platform=args.platform, key=args.host_key, device_trust=trust_doc.data)
host = HostSpec(
name=args.host,
platform=args.platform,
supervisor=args.supervisor,
key=args.host_key,
device_trust=trust_doc.data,
)
try:
result = compile_host(model, host, schemas)
except CompileError as exc:
Expand Down Expand Up @@ -150,8 +156,18 @@ def build_parser() -> argparse.ArgumentParser:
b = sub.add_parser("buildfile", help="render what one host would receive")
b.add_argument("--host", required=True, help="host name as used in the Site Model (hosts:, roles)")
b.add_argument("--host-key", required=True, help="device public key, ed25519:<64 hex>")
b.add_argument("--platform", default="macos", choices=["macos", "linux", "android"])
b.add_argument("--device-trust", required=True, help="JSON/YAML file holding the goal file's device-trust domain verbatim")
b.add_argument("--platform", required=True, choices=["macos", "linux"], help="no default; android is not offered until Termux is decided")
b.add_argument(
"--supervisor",
required=True,
choices=list(SUPERVISORS),
help="what runs the host's units; no default. Written into device-trust.entries.supervisor",
)
b.add_argument(
"--device-trust",
required=True,
help="JSON/YAML file holding the goal file's device-trust domain; its supervisor entry, if any, must match --supervisor",
)
b.add_argument("--site", help="directory holding services.yml, roles.yml, launchd-writers.yml")
b.add_argument("--services")
b.add_argument("--roles")
Expand Down
Loading
Loading