75 lines
4.7 KiB
Markdown
75 lines
4.7 KiB
Markdown
# 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.
|