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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ uv run nix2cf buildfile \
`--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`);
refused. The output is **schema_version 5** (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
Expand Down
5 changes: 3 additions & 2 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,9 @@ Each of these is marked `TODO(operator)` in `nix2cf/compile.py` at the spot.
| `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. |
| Older `schema_version` | Library only (`compile_host(..., schema_version=N)`): 3 renders without the `supervisor` entry; 4 renders, for inputs valid under the current Site Model contract, the same file as the current version bar the number. That is not a migration claim for arbitrary historical v4 output: v4 permitted `dpkg` unit-writer claims, which v5 rejects. 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; schema-v5 spec §4 items 1 and 11. |
| Unit-writer keys (schema v5) | Only launchd prefixes are emitted (from `launchd-writers.yml`, `^[a-z][a-z0-9]*(\.[A-Za-z0-9][A-Za-z0-9_-]*)+\.\*$`, the v4 language launchd and runit keep). No exact/template key, no `unit-package`, no `tendcf-install`. Schema-validated v5 output carries no `dpkg` writer (retired in v5: the writers schema and the goal-file schema both refuse it); the renderer copies declared writers unchanged, so an old Site Model with one still renders at v4 (unvalidated) and is refused at v5. A systemd host gets no `supervision` domain (its renderer is not built), so the "systemd prefix must be cfengine" rule has nothing to apply to. | Schema-v5 spec §2.1, §7 item 12: the Site Model has no systemd writer registry. |
| Tombstones | Cannot be rendered: the Site Model has no way to say "absent". So the v5 rules that a tombstone sit under a same-domain `cfengine` claim and that no unit be present in one domain and absent in another cannot fire on nix2cf output. | Goal file supports them; the Site Model does not yet. |

## Conflict check (stage 2)

Expand Down
22 changes: 15 additions & 7 deletions nix2cf/compile.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,18 +39,26 @@

# Must equal the `const` of `tendcf/schema/goal-file.schema.json`
# `schema_version`; CI fails when it does not (.github/workflows/check.yml).
GOAL_FILE_SCHEMA_VERSION = 4
GOAL_FILE_SCHEMA_VERSION = 5
# `supervisor` entered the device-trust domain at v4 (schema-v4 spec §2.1).
# The `nixos` host exists only from v4 on (spec §6.2 item 6): the one v3
# spelling, a `nixos` unit-writer, described nothing.
SUPERVISOR_SCHEMA_VERSION = 4
# Older versions this compiler can still state. The launchd shape did not
# change between v1 and v4; only v3 and v4 are claimed, because v3 is the one
# the spec names ("Non-nixos hosts may render at 3 by dropping the entry").
# Older versions this compiler can still state: 3 and 4. For inputs valid
# under the current Site Model contract, rendering at v4 and v5 differs only
# in `schema_version` (v5 changed the unit-writer key language, which is a
# superset of every launchd prefix nix2cf emits, retired the `dpkg` writer and
# added `tendcf-install` and `unit-package`), and v3 differs by lacking the
# `supervisor` entry. This does not establish migration compatibility for
# arbitrary historical v4 output: v4 permitted `dpkg` unit-writer claims,
# which v5 rejects. Older-version output is never schema-validated. The spec
# names no downgrade path at v5 and no device holds a baseline (spec §4 item
# 1); 3 and 4 stay as the shapes a not-yet-migrated device could still hold.
# The current version is derived, so a bump of GOAL_FILE_SCHEMA_VERSION cannot
# leave the renderer refusing its own version. The literal 3 is NOT derived:
# re-justify it (is v3 still a shape a device may hold?) at every bump.
SUPPORTED_SCHEMA_VERSIONS = (3, GOAL_FILE_SCHEMA_VERSION)
# leave the renderer refusing its own version. The literals 3 and 4 are NOT
# derived: re-justify them (is that still a shape a device may hold?) at every
# bump.
SUPPORTED_SCHEMA_VERSIONS = (3, 4, GOAL_FILE_SCHEMA_VERSION)

# The one state domain the reference projector reads
# (`tendcf/bin/projector.py:PROJECTING_DOMAIN`). The Site Model's own domain
Expand Down
2 changes: 1 addition & 1 deletion tests/golden/example-site_mac.goal-file.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"interlock":{"tailscale-authenticated-before-lockdown":{"blocks":"enclosing-bundle","bundle":"fleet-vpn","defines_class":"tailscale_authenticated","pre_action":{"command":["tailscale","status","--json"],"expect_exit":0,"timeout_seconds":15},"report":true,"state":"present"}},"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"},"org.tendcf.tailscaled":{"bundle":"fleet-vpn","command":["/usr/local/bin/tailscaled"],"run_as":"root","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":4}
{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"interlock":{"tailscale-authenticated-before-lockdown":{"blocks":"enclosing-bundle","bundle":"fleet-vpn","defines_class":"tailscale_authenticated","pre_action":{"command":["tailscale","status","--json"],"expect_exit":0,"timeout_seconds":15},"report":true,"state":"present"}},"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"},"org.tendcf.tailscaled":{"bundle":"fleet-vpn","command":["/usr/local/bin/tailscaled"],"run_as":"root","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":5}
2 changes: 1 addition & 1 deletion tests/golden/nixos-get.goal-file.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"nixos","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"deliberately-unmanaged"}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":4}
{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"nixos","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"deliberately-unmanaged"}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":5}
2 changes: 1 addition & 1 deletion tests/golden/tendcf-examples_mac.goal-file.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":4}
{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":5}
49 changes: 46 additions & 3 deletions tests/test_compile.py
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ def test_site_model_inputs_validate(schemas: Schemas) -> None:
def test_example_site_mac_golden(schemas: Schemas) -> None:
result = compile_host(_model(SITE), _host(SITE), schemas)
doc = result.goal_file
assert doc["schema_version"] == 4
assert doc["schema_version"] == GOAL_FILE_SCHEMA_VERSION == 5
assert doc["host"] == HOST_KEY
assert doc["domains"]["device-trust"]["entries"]["supervisor"] == {"host": {"name": "launchd", "state": "present"}}
sup = doc["domains"]["supervision"]
Expand Down Expand Up @@ -302,7 +302,7 @@ def test_nixos_host_without_services_is_deliberately_unmanaged(tendcf: Path, sch
# no-op on a file with no entries): drift in either repo shows up here.
assert result.canonical == (tendcf / "deploy" / "linux" / "passthrough" / "goal-file.json").read_bytes()
doc = result.goal_file
assert doc["schema_version"] == 4
assert doc["schema_version"] == GOAL_FILE_SCHEMA_VERSION == 5
assert doc["domains"]["supervision"] == {"coverage": "deliberately-unmanaged"}
assert doc["domains"]["device-trust"]["entries"]["supervisor"] == {"host": {"name": "nixos", "state": "present"}}
assert set(doc["domains"]) == {"device-trust", "supervision"} # no unit-writer registry travels
Expand Down Expand Up @@ -358,6 +358,49 @@ def test_schema_v3_with_schema_is_noted_not_validated(schemas: Schemas) -> None:
assert any("NOT validated" in d for d in result.diagnostics)


def _host_shapes() -> dict[str, HostSpec]:
"""Every host shape nix2cf renders: a launchd host with services, a nixos
host, and service-free systemd and runit hosts (their unit renderers are not
built, so a selected service is refused; none selected renders the supervisor
entry alone)."""
return {
"launchd": _host(SITE),
"nixos": _nixos_host(),
"systemd": _host(SITE, name="get", platform="linux", supervisor="systemd", trust=_trust(SITE, None)),
"runit": _host(SITE, name="get", platform="linux", supervisor="runit", trust=_trust(SITE, None)),
}


@pytest.mark.parametrize("shape", ["launchd", "nixos", "systemd", "runit"])
def test_schema_v4_and_v5_differ_only_in_the_version_for_current_inputs(schemas: Schemas, shape: str) -> None:
"""For inputs valid under the current Site Model contract, the v4 file is the
current file with the old version number, for every host shape. The v5 file is
validated against tendcf's schemas (the v4 file cannot be: the schema is a
const). Not a claim about arbitrary historical v4 output: see
test_dpkg_writer_renders_at_v4_but_is_refused_at_v5."""
host = _host_shapes()[shape]
old = compile_host(_model(SITE), host, None, schema_version=4).goal_file
new = compile_host(_model(SITE), host, schemas).goal_file # validates against the v5 schema
assert old["schema_version"] == 4 and new["schema_version"] == 5
assert new["domains"]["device-trust"]["entries"]["supervisor"]["host"]["name"] == host.supervisor
assert {**old, "schema_version": 5} == new
assert schemas.errors("goal-file.schema.json", new) == []


def test_dpkg_writer_renders_at_v4_but_is_refused_at_v5(schemas: Schemas) -> None:
"""`dpkg` left the unit-writer enum in v5 (a package claim is its only spelling).
v4 permitted it, so an unused `dpkg` writer in an old Site Model still renders
at v4 (unvalidated, as every older version is) and is refused at v5."""
model = _model(SITE)
writer = next(w for w in model.launchd_writers.data["writers"] if w["prefix"] == "dev.mise.*")
writer["writer"] = "dpkg"
assert validate_site_model(model, schemas) != [] # launchd-writers.schema.json dropped it too
old = compile_host(model, _host(SITE), None, schema_version=4).goal_file
assert old["domains"]["supervision"]["entries"]["unit-writer"]["dev.mise.*"]["writer"] == "dpkg"
with pytest.raises(CompileError, match="dpkg"):
compile_host(model, _host(SITE), schemas)


def test_render_goal_file_alone_refuses_nixos_below_v4() -> None:
from nix2cf.compile import render_goal_file

Expand Down Expand Up @@ -388,7 +431,7 @@ def test_cli_platform_is_required_and_android_not_offered(tendcf: Path) -> None:

def test_unsupported_schema_version_refused() -> None:
with pytest.raises(CompileError, match="not one this compiler renders"):
compile_host(_model(SITE), _host(SITE), None, schema_version=5)
compile_host(_model(SITE), _host(SITE), None, schema_version=GOAL_FILE_SCHEMA_VERSION + 1)


# --- conflict check -------------------------------------------------------------
Expand Down
Loading