[shipmill-romamo]

Summary

The engine side of spec 004 (docs/specs/004-domains-apply.md):

• domains.yml takes cloudfall_domains_domain_id and renders only that Domain; without it the loop is the same as before. The playbook edit is the loop: expression only
• The converge_domains MCP tool gains an optional domain. Given, the SDK looks the Domain up in the validated config, runs domains.yml with --limit <proxy.server> and the domain id, so no other host is contacted; an unknown id exits PRECONDITION (lifecycle_domain_missing) before the inventory render. Omitted, the argv and extra vars are exactly today's. The tool's handling moved into cloudfall.lifecycle.converge_domains (DomainsRun), and run_engine_playbook takes an optional limit
• cloudfall_nginx_site hashes the file at proxy.configurationPath once, before its first render, and the receipt records it as previousConfigurationSha256 (null when no file was there). The receipt schema gains the optional field (sha256 or null), so receipts without it still load

The cloudfall domains apply command is #117; the criteria here are proven at the engine and MCP layer.

Fixes #116

Test plan

• engine/tests/test_domains_one_domain.py: the real domains.yml loop evaluated with Ansible's templating (S-004-2, S-004-17); the role's own receipt tasks run for real by ansible-playbook on localhost against a hand-written vhost and against no file, receipt validated against the schema (S-004-11)
• sdk/tests/test_domains_converge.py: argv of the run for one Domain (--limit h2, the domain id) and without one (unchanged), unknown id refused before any step, a failing playbook (a rejected nginx -t) surfaces as lifecycle_execution_failed, which the tool answers as ENGINE_STEP_FAILED (S-004-2, S-004-13, S-004-17); converge_domains over the real mcp serve stdio transport with an unknown domain (S-004-17); services status loads a receipt without the field, with null, and with a hash, and refuses a malformed one (S-004-12)
• uv run ruff check ., uv run mypy, ansible-playbook --syntax-check on domains.yml, and the tests of the touched files pass locally. ansible-lint engine/ansible reported only role-not-found syntax errors on playbooks this PR doesn't touch, because ANSIBLE_CONFIG could not be set in this session; CI sets it
• Not run: a live domains.yml on a Debian host with Nginx. The full suite is left to CI

Plan

• Serves: quality bar
• Files: engine/ansible/playbooks/domains.yml, engine/ansible/roles/cloudfall_nginx_site/tasks/main.yml, config/schemas/v1/deployment-receipt.schema.json, sdk/src/cloudfall/lifecycle.py, sdk/src/cloudfall/app.py, engine/tests/test_domains_one_domain.py, sdk/tests/test_domains_converge.py, changelog.d/116-converge-one-domain.md
• Order: schema field first, then the role's hash and receipt field, then the playbook's domain filter, then the SDK limit and the MCP tool's domain, each with its test
• Proof: S-004-2, S-004-11, S-004-12, S-004-13, S-004-17 (specs.py coverage --spec 004)

🤖 Generated with Claude Code

[shipmill-romamo]

@romamo Decided without waiting: converge_domains gains an optional domain input, every domain receipt gains previousConfigurationSha256, and a one-Domain run is limited with ansible-playbook --limit <proxy server>.

Why: S-004-2, S-004-11 and S-004-17 ask for exactly this; the receipt field is optional, so older receipts still load. Without domain, the tool runs exactly as today. Review made the hash follow a symlinked vhost (the usual sites-enabled layout), which otherwise failed after the new vhost was live.
Not taken: filtering only inside the playbook, which would still connect to every server.

Reply with a comment starting with veto before 2026-10-28 08:45 UTC to reverse it, adding what you want instead if you like. A later veto still counts and gets a follow-up.