release: freeze Nexus One AI 1.0.0-rc1

2026-08-17 11:05:19 +05:30
1 parent 63acefd890
commit 4f1419ca93
@@ -0,0 +1,74 @@
+# 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.
@@ -0,0 +1,33 @@
+[Unit]
+Description=Nexus One AI Management API
+Wants=network-online.target
+Requires=ollama.service chromadb.service
+After=network-online.target ollama.service chromadb.service
+StartLimitIntervalSec=120
+StartLimitBurst=3
+
+[Service]
+Type=simple
+User=cezen
+Group=cezen
+WorkingDirectory=/opt/cezen/backend
+Environment=CEZEN_DATA=/opt/cezen/data
+Environment=OLLAMA_URL=http://127.0.0.1:11434
+Environment=CHROMA_URL=http://127.0.0.1:8100
+Environment=PATH=/opt/cezen/backend/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
+ExecStart=/opt/cezen/backend/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8080 --workers 2
+Restart=on-failure
+RestartSec=5
+TimeoutStartSec=120
+TimeoutStopSec=30
+KillSignal=SIGTERM
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/cezen/data
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,27 @@
+[Unit]
+Description=Nexus One AI ChromaDB Vector Store
+After=local-fs.target
+StartLimitIntervalSec=120
+StartLimitBurst=3
+
+[Service]
+Type=simple
+User=cezen
+Group=cezen
+WorkingDirectory=/opt/cezen/data/chromadb
+Environment=PATH=/opt/cezen/chromadb-venv/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=/opt/cezen/chromadb-venv/bin/chroma run --host 127.0.0.1 --port 8100 --path /opt/cezen/data/chromadb
+Restart=on-failure
+RestartSec=5
+TimeoutStartSec=120
+TimeoutStopSec=30
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/cezen/data/chromadb
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,19 @@
+[Unit]
+Description=Nexus One AI post-activation health window
+Requires=ollama.service chromadb.service cezen-api.service nginx.service
+After=ollama.service chromadb.service cezen-api.service nginx.service
+OnFailure=nexus-one-activation-rollback.service
+ConditionPathExists=/var/lib/nexus-one/installer/active-operation.env
+
+[Service]
+Type=oneshot
+EnvironmentFile=/var/lib/nexus-one/installer/active-operation.env
+ExecStart=/usr/bin/python3 /usr/lib/nexus-one/activation-health-window.py --operation-id ${OPERATION_ID} --profile-config ${HEALTH_PROFILE_CONFIG} --samples ${HEALTH_SAMPLES} --interval-seconds ${HEALTH_INTERVAL_SECONDS} --timeout-seconds ${HEALTH_TIMEOUT_SECONDS} --window-timeout-seconds ${HEALTH_WINDOW_TIMEOUT_SECONDS} --evidence ${HEALTH_EVIDENCE_PATH}
+TimeoutStartSec=600
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/nexus-one/installer
+StandardOutput=journal
+StandardError=journal
@@ -0,0 +1,16 @@
+[Unit]
+Description=Nexus One AI failed-activation rollback
+ConditionPathExists=/var/lib/nexus-one/installer/active-operation.env
+
+[Service]
+Type=oneshot
+EnvironmentFile=/var/lib/nexus-one/installer/active-operation.env
+ExecStart=/usr/bin/python3 /usr/lib/nexus-one/recover-python-profile-on-boot.py --journal ${JOURNAL_PATH} --checkpoint ${CHECKPOINT_PATH} --target ${TARGET_PATH}
+TimeoutStartSec=600
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/cezen /var/lib/nexus-one/installer
+StandardOutput=journal
+StandardError=journal
+
@@ -0,0 +1,5 @@
+[Unit]
+# Keep nginx available for local recovery/help even when the API fails. The activation health gate,
+# rather than nginx itself, requires the complete graph.
+Wants=cezen-api.service
+After=cezen-api.service