# Candidate Production Service Graph

These files are a design/validation candidate, not installed runtime units. Promotion requires the
Gate 2 evidence below and explicit implementation authorization.

## Dependency graph

`ollama.service` and `chromadb.service` are required upstream components for the current Workstation
profile. `cezen-api.service` requires and orders after both. The nginx drop-in only *wants* and orders
after the API so static local recovery/help remains reachable during API failure. The transactional
`nexus-one-activation-health.service` requires the complete model/vector/API/nginx graph; any failed
window triggers `nexus-one-activation-rollback.service`.

`activation-health-window.py` accepts only literal loopback HTTP URLs and exact semantic JSON responses
containing `service` and `status`. It does not resolve hostnames or contact LAN/Internet addresses.
Required components must report `ready`. An optional component may report `degraded` only when both the
signed profile marks it optional and the activation invocation explicitly enables degraded acceptance;
the default rejects degradation. Timeout, non-200 response, wrong content type/shape/identity/status,
oversized response, malformed JSON and unreachable endpoint reject immediately.

Exit `0` means the requested consecutive window completed as `ready`, or explicitly policy-accepted
`degraded`. Exit `23` means a semantic health rejection and is the contract used by systemd
`OnFailure`. Exit `2` means invalid configuration/evidence I/O and also fails the unit. Evidence is
canonical JSON, mode `0600`, fsynced and atomically published without wall-clock-dependent fields.

The per-request timeout is capped by the remaining monotonic total-window deadline. The validator
rejects with `WINDOW_TIMEOUT` when the deadline has expired or when the configured interval makes the
next required sample impossible. It never extends the deadline because a component responds slowly.

Each health-profile component also declares `systemd_unit` (a literal `.service` name or `null`) and
`max_restarts`. Before HTTP evaluation, the validator reads `NRestarts`, `ActiveState` and `SubState`
using a fixed `systemctl show` argv. A count above the signed profile limit rejects as `RESTART_STORM`;
an unavailable/malformed unit state or a non-active unit also rejects. `null` is permitted only for a
profile component whose lifecycle is demonstrably outside systemd. Restart checks occur before HTTP so
a stale or separately served healthy endpoint cannot conceal an unstable unit.

Category/profile resolution may replace Ollama with another signed model-runtime unit or omit an
unsupported optional component, but it must generate a closed graph before activation. A missing
required unit fails the transaction; it is not silently downgraded.

## Active-operation environment contract

`/var/lib/nexus-one/installer/active-operation.env` is root-owned mode `0600`, atomically published and
contains only these validated, systemd-safe assignments:

```text
OPERATION_ID=<restricted identifier>
HEALTH_PROFILE_CONFIG=/usr/share/nexus-one/health-profiles/<signed profile>.json
HEALTH_SAMPLES=3
HEALTH_INTERVAL_SECONDS=<approved integer>
HEALTH_TIMEOUT_SECONDS=<approved integer>
HEALTH_WINDOW_TIMEOUT_SECONDS=<approved integer>
HEALTH_EVIDENCE_PATH=/var/lib/nexus-one/installer/evidence/<operation>.json
JOURNAL_PATH=/var/lib/nexus-one/installer/operations/<operation>/journal.json
CHECKPOINT_PATH=/var/lib/nexus-one/installer/operations/<operation>/checkpoint
TARGET_PATH=/opt/cezen/<selected target>
```

Values must not contain whitespace, quotes, `%`, `$`, shell syntax or path traversal. All paths are
canonicalized and checked against their allowed roots before publication. The file contains no secret.
It remains until the health unit commits success or rollback reaches terminal state, then is archived
with the evidence record and removed atomically.

## Promotion gates

- Lock and sign the health profile, health-window/recovery executables and unit/drop-in bytes.
- Define semantic probes for Ollama/model availability, Chroma heartbeat, API `/api/health`, and nginx
  portal/API proxy behavior, including category-aware degraded states.
- Approve sample interval, total timeout, restart policy and consecutive-success count.
- Prove clean boot, activation, dependency failure, restart storm, timeout, rollback and recovery-portal
  access on the real services with zero network access.
- Verify ownership, modes, ACLs, xattrs, SELinux/AppArmor implications and least-privilege write paths.
- Resolve whether CPU-only installations still require Ollama; generate a different graph if not.
- Replace the current Ansible-created unit content only after the candidate passes these gates.