feat(manager): expose safe VPS edge health

2026-08-22 13:08:04 +03:00
parent 07ffb22d38
commit 6ed4414a97
14 changed files with 464 additions and 42 deletions
@@ -0,0 +1,115 @@
+# Device Infrastructure Host ontology candidate
+
+Status: **candidate, not canonical**  
+Date: 2026-08-22
+
+## Why this is a candidate
+
+The live read-only NODE.DC ontology catalog currently has no canonical generic
+compute host, deployment, service instance or health-observation entities. Its
+`integration.connection` entity models provider-account connections and must
+not be reused for a VPS merely to unblock a screen.
+
+Device Core therefore does not mint local identifiers and present them as
+official ontology. The first shipped projection is limited to the already
+canonical product relationship that exists in Device Core today:
+
+```text
+Device Project -> Route -> Edge registration -> pinned Core↔Edge channel
+                                      |
+                                      +-> opaque deploymentRef
+```
+
+The UI calls this projection `VPS / Edge host` and derives current reachability
+from the live channel supervisor. It does not expose channel endpoints, trust
+material, certificates or credentials.
+
+## Proposed canonical concepts
+
+The following names are discussion handles only. Final identifiers, scopes and
+relation direction must be published by the official ontology owner before
+Device Core persists them.
+
+| Candidate concept | Scope | Required meaning |
+| --- | --- | --- |
+| `infrastructure.host` | owner + project visibility | A physical or virtual compute host independent of provider and workload |
+| `infrastructure.endpoint` | host | A bounded management or service endpoint without credentials |
+| `infrastructure.deployment` | owner/project | An immutable desired deployment of an artifact or workload |
+| `infrastructure.service_instance` | host + deployment | A runtime instance produced by a deployment |
+| `infrastructure.health_observation` | observed entity | A time-bounded observation with source, timestamp and evidence class |
+| `infrastructure.management_session` | actor + host | An expiring, audited brokered management session |
+
+Proposed relations:
+
+```text
+device.project --uses--> infrastructure.host
+infrastructure.host --exposes--> infrastructure.endpoint
+infrastructure.deployment --targets--> infrastructure.host
+infrastructure.service_instance --runs-on--> infrastructure.host
+infrastructure.service_instance --realizes--> infrastructure.deployment
+device.edge-registration --runs-on--> infrastructure.host
+device.route --terminates-at--> device.edge-registration
+infrastructure.health-observation --observes--> host|endpoint|service-instance
+infrastructure.management-session --targets--> infrastructure.host
+```
+
+## State is faceted, not flattened
+
+A single `online` flag is insufficient and would hardcode the current VPS
+case. Each host projection needs independent facets:
+
+- lifecycle: `provisioning | active | suspended | retired`;
+- reachability: `reachable | degraded | unreachable | unobserved`;
+- management access: `available | denied | expired | unconfigured`;
+- workload health: per service instance, never inferred from host ping alone;
+- observation freshness: `observedAt`, TTL and source;
+- desired/actual configuration: immutable revision refs and reconciliation
+  state, with secrets represented only by opaque secret refs.
+
+This allows one host to be reachable while a service is unhealthy, or a
+service to be healthy while interactive management access is intentionally
+disabled.
+
+## Registration workflow after ontology publication
+
+1. Create or select an owner-scoped host identity.
+2. Grant project visibility through a canonical project-host relation.
+3. Attach a provider-neutral endpoint projection and an opaque credential ref.
+4. Run a bounded reachability probe through a server-side worker.
+5. Register deployments and discovered service instances as separate entities.
+6. Link an Edge registration to the host when that role is actually deployed.
+7. Emit health observations with TTL instead of mutating a permanent `online`
+   property.
+
+Provider fields such as Beget, Hetzner or AWS remain annotations or provider
+relations. They never change the host identity or the UI information model.
+
+## Console boundary
+
+An unrestricted WebSSH terminal is not part of the first slice. If introduced,
+it must be a server-side session broker with all of the following properties:
+
+- short-lived session and explicit target selection;
+- authorization checked at session creation and command execution;
+- no private key or password delivered to the browser;
+- bounded command catalog by default;
+- immutable actor/target/timing/exit-code audit;
+- output size limits and secret redaction;
+- explicit break-glass mode for arbitrary commands;
+- automatic expiry, revocation and concurrent-session limits.
+
+The broker must reference `infrastructure.management_session` after that
+concept becomes canonical. A browser shell iframe or direct browser-to-SSH
+connection is outside the Device Core security boundary.
+
+## Delivery sequence
+
+1. **Shipped candidate UI projection:** VPS/Edge hosts, route relationships and
+   live pinned-channel state from existing Device Core records.
+2. **Ontology gate:** publish host/deployment/service/health entities and
+   relations in the official ontology package.
+3. **Inventory:** add provider-neutral host registration and project grants.
+4. **Monitoring:** persist bounded health observations from a dedicated worker.
+5. **Configuration:** immutable desired revisions and reconciliation receipts.
+6. **Management sessions:** bounded command runner first; audited break-glass
+   console only after a separate threat-model review.