Files
canina/docs/hermes-runtime-read-slice.md

6.4 KiB

Superseded wiring/provenance: see snapshot repair. Do not use literal grants or the old DNS alias below.

Runtime read vertical slice (not deployed)

Branch feature/v4-runtime-completion, base 5507fbc. No AppModule, live gateway, production database, cron, dispatch, or existing compose was changed.

Parent registration

Import RuntimeReadModule.register({ '<verified-user-id>': ['default', '<department>'] }) from backend/src/hermes-management/runtime-read.module into AppModule. This module uses the existing Passport jwt strategy (DB-resolved user identity), not the API-key fallback. Parent must retain AuthModule/JwtStrategy initialization. Missing grants deny. Never construct grants from browser body, JWT profile claims, or unreviewed environment input. Allowlist is copied/frozen. Admin/SUPER_ADMIN role AND exact subject grant required; API-key identities forbidden.

GET /admin/orchestration/runtime/{health,profiles,status,usage,sessions,schedules,model-info}. All except health/profiles require exactly one allowed profile query string. Usage accepts days 1..365 (30); sessions limit 1..100 (20), offset 0..10000 (0). Unknown parameters on profile routes rejected. Profiles is filtered to server grants. Responses use existing adapter projections, no prompts/transcripts/config/tokens. Missing/forged JWT ->401; missing grant/role/profile ->403; runtime auth/network/ contract failure ->503 Runtime unavailable; limits ->429. No browser Hermes cookie, credential, socket ticket or mutation handler is provided.

Mount backend /run/secrets/hermes_username and hermes_password as files. Only these fixed secret paths are read, after authorization. Broker login/cache stays server-side. Backend and isolated inventory runtime must receive matching credentials. Runtime additionally mounts hermes_signing_key (>=32 random chars). Do not put credentials in YAML/env, commands, logs or Git. Rotate key to invalidate sessions; rotate password and restart inventory plus backend to clear cached access. Stateless old sessions remain valid until TTL/key rotation.

Deliberately separate snapshot topology

Installed Hermes serve lifespan starts reconciliation and hosted-room recovery; GET sessions auto-archives. Sharing its writable home with existing gateway is therefore NOT a safe read-only sidecar. serve.py runs the pinned installed app with lifespan OFF and an outer exact GET allowlist, password-login only and all WebSockets denied1008. It does NOT start scheduler/gateway/MCP/rooms/provider chat. The existing gateway and external volume canina-hermes_canina_hermes_data remain unchanged, solely owned by existing gateway. Inventory mounts an independently provisioned snapshot volume canina_hermes_inventory_snapshot; it NEVER mounts original home. Its incidental session auto-archive writes affect only snapshot. This is snapshot inventory, NOT live runtime freshness/status acceptance. A copy of gateway PID state is not evidence of live gateway health. UI must not claim live readiness from this deployment. Parent should expose snapshot provenance/freshness before enabling it for business use.

Provisioning must use an approved consistent SQLite backup/checkpoint/export and redacted profile config inventory, not raw cp of changing SQLite/WAL or credentials. No automatic snapshot job is installed here. No secrets need be copied from live home. Review which configs the model/status APIs need and omit auth.json/.env. Missing store/schema -> unavailable, not fabricated empty healthy telemetry. Dedicated internal network must contain only backend and inventory; do NOT connect existing gateway with same canina-hermes DNS alias. Backend name resolves inventory. Inventory network must have no external egress. Compose refers to external network; operator must create it --internal. No host ports/socket are published.

CI ownership / apply

compose.readonly.yml is deployable ONLY after external snapshot, internal network, secret files and backend mounts/registration are provisioned. ci-apply.sh requires CI=true, exact reviewed HEAD SHA, clean checkout, snapshot-reviewed assertion, existing volume/network/files, then compose config/up. Never run alongside any other inventory instance writing same snapshot. CI job fragment is tracked under infra ownership; parent owns real workflow wiring and approval environment. No active deployment trigger added. Existing review-only compose template is unchanged.

Executed evidence

Remote /opt/services/canina/validation/v4-runtime-completion/:

  • read-red.log missing controller regression; read-green.log 6 suites/27 tests.
  • read-http-green.log 7 suites/30 tests: real Nest HTTP with signed JWT strategy, bad signature/no auth401, ungranted admin403, allowed admin200, no cookie, mutation404. This uses a mocked runtime service, not live Canina credentials.
  • pinned-http.log exact installed image FastAPI login/protected inventory: wrong password401, real login200/HttpOnly provider-verifiable token, profiles200, tampered token401. No lifespan/live home.
  • serve-http.log actual loopback TCP9119 in network-none disposable pinned image: unauth inventory401, wrong password401, login200, profiles200, health auth true, mutation/config/ws HTTP404. Generated test-only credentials. No live volume.
  • ws-red.log existing socket rejection code differed; ws-green.log explicit outer boundary denies authenticated sockets1008 independently of upstream tickets.
  • build.log private Prisma generation and full backend tsc build exit0.

Pinned local exact image ID sha256:373ddd5e6649f525b17993e1c885cdf1352127f8e98fd329140a73237125e52f; tracked registry digest sha256:9774f4f39a9bb8c2f68ce728ed5e99ddbad282163be56764afacf88ed952b784. Node22 disposable runner copied read-only source/dependency donor privately; no DB migration. broker-pinned-e2e.log proves actual compiled Node broker -> TCP pinned Hermes login -> adapter -> policy-filtered inventory (and deny zero secret reads). Nest HTTP authentication tested separately; these tests do not establish full Canina application E2E, snapshot refresh, CI deployment, live gateway truth or business workflow acceptance. Those remain explicit integration/provisioning gates, not claimed completion.

Final full non-DB regression: 106 suites / 850 tests pass; expected legacy negative SSL/payment logs. Scoped ESLint has zero errors, six type-safety warnings; full build passes. No RELEASE_AUTHORIZE integration suite run.