Assumptions Register (MVP)¶
Purpose: - Make implicit assumptions explicit. - Prevent hidden design constraints from turning into production surprises. - Force re-validation of assumptions at phase gates.
Update rule: - If a design or implementation choice depends on an assumption not already listed here, add it in the same PR. - If an assumption changes, update dependent docs/contracts in the same PR.
Status values:
- active: currently relied on.
- validated: confirmed in implementation/runtime.
- retired: no longer relied on.
Current Assumptions¶
| ID | Assumption | Scope | Status | Risk if false | Owner | Re-validation trigger |
|---|---|---|---|---|---|---|
| A-001 | Public ingress/WAF/API gateway is provided by the deployment platform; repo does not ship a separate platform edge gateway product at MVP (application services like cmd/terminal-gateway are still expected). |
Runtime edge | active | Security controls/routing gaps in production rollout | Platform | Before first public environment launch |
| A-002 | Public entrypoints at MVP are split: cmd/api for HTTPS REST and cmd/terminal-gateway for terminal WS; internal service-to-service HTTP exists for node-agent and terminal relay paths, while internal gRPC remains deferred. |
Service topology | active | Boundary drift into undocumented distributed behavior | Architecture | Phase-2 extraction decision |
| A-003 | Identity is OIDC-first; local password login is dev/bootstrap-only and excluded from public SDK surfaces. | Auth | active | Inconsistent auth UX/security posture | Auth | Auth implementation start + security review |
| A-004 | API key auth is deferred from MVP; auth middleware remains pluggable via credential resolver interface. | Auth extensibility | active | Handler-level refactor when API keys are introduced | Auth | API-key phase kickoff |
| A-005 | Terminal WS auth uses short-lived single-use token via Sec-WebSocket-Protocol (no query-token auth). |
Terminal security | active | Credential leakage / replay risk | Security + Terminal | Terminal phase implementation + pen test |
| A-006 | Notification delivery bridge is NATS -> notification-relay -> Redis Pub/Sub -> WS hub for MVP; persistent inbox/read-state is deferred. | Notifications | active | Lost notifications on reconnect/restart | Platform + Notification | Before beta reliability hardening |
| A-007 | Financial policy values (thresholds/limits/rate limits) are config-driven via policy tables, not hardcoded constants. | Billing/policy | active | Redeploy needed for policy changes; inconsistent behavior | Billing | Every policy-related feature PR |
| A-008 | Refund semantics follow policy mode 2: attempt provider refund within policy window, otherwise internal credit; user-visible outcome is required. | Payments/product | active | Finance/support disputes and contract mismatch | Product + Billing | Refund implementation kickoff |
| A-009 | Full enterprise IAM (groups, advanced project-role matrix, multi-tenant context switching UX) remains out of MVP runtime scope; MVP includes baseline membership tables and tenant/project ownership enforcement first. | Phase-2 readiness | active | Premature IAM complexity or ownership drift if delayed | Architecture | Tenant ownership baseline signoff + end of MVP build review |
| A-010 | No production data migration from prototype is required; rebuild starts with clean state. | Delivery/migration | active | Unexpected migration workload and timeline slip | Product + Platform | Pre-launch go/no-go |
| A-011 | Production object storage is S3-compatible; local filesystem remains prototype/reference only. | Storage | active | Data loss or non-scalable storage path | Storage | Storage implementation kickoff |
| A-012 | CI runtime is GitLab-first for MVP (.gitlab-ci.yml) while gate scripts remain provider-agnostic for future portability. |
DevEx/CI | validated | Pipeline drift between local/remote execution and future provider migration friction | DevEx | CI topology change or provider migration decision |
| A-013 | Service mesh (Envoy sidecars/Istio) is deferred from MVP; managed edge gateway + app middleware is the baseline until extraction/scale triggers are met. | Platform networking | active | Premature complexity or delayed adoption beyond trigger point | Platform + Architecture | First multi-service independent deploy milestone |
| A-014 | East/west security is mandatory at MVP even without mesh: default-deny network policy, explicit allow-list flows, internal mTLS (or equivalent), and cert lifecycle controls. | Platform security | active | Tenant isolation failures and lateral movement risk | Security + Platform | Before staging->prod promotion |
| A-015 | Full OPA/OPAL policy control plane is deferred from MVP and adopted with control-plane/service extraction; MVP uses DB-backed PolicyClient evaluation with OPA-ready decision interfaces (embedded OPA pilot allowed without contract changes). |
Authz/policy architecture | active | Premature policy infra complexity or delayed distributed policy consistency | Architecture + Security | Same trigger as A-002 service extraction decision |
| A-016 | Admin-token emergency revocation is required pre-production via server-side deny-list/token-versioning check; non-admin tokens may remain expiry-based at MVP. | Auth security | active | High-impact admin compromise window | Security + Auth | Before first admin production login |
| A-017 | MVP uses reset-baseline for tenant/project ownership enforcement (no legacy data migration/backfill required in current dev stage). | Delivery/migration | active | Unnecessary migration complexity and delayed enforcement | Architecture + Platform | Before ownership baseline implementation starts |
| A-018 | Service-account support is required for app-team integrations; initial model is project-scoped machine identity with short-lived tokens and strict endpoint allowlists. | Auth/product integration | active | App integrations blocked or over-privileged machine access | Auth + Architecture | Before app-team service-account implementation kickoff |
| A-019 | service_account_credentials.private_key_enc may store encrypted private key material in Postgres for MVP; upgrade path to external KMS/Vault key references is required before production hardening. |
Auth security | active | Load-bearing DB key custody and difficult key-management cutover | Security + Auth | Pre-production security hardening gate |
| A-020 | Enterprise SSO is implemented as per-tenant federation configuration (tenant-bound OIDC/SAML mapping) while platform-global auth remains for platform-admin and personal-tenant bootstrap paths. | Auth/tenant architecture | active | Cross-tenant authz drift, issuer-mixup risk, and late-stage auth model rewrite | Auth + Architecture | Before enterprise tenant onboarding rollout |
| A-021 | MaaS-backed node onboarding remains deferred until a real MaaS environment is available for acceptance testing; mock-only paths are insufficient for closure. | Node lifecycle / inventory integration | active | Late integration surprises in provider adapter, credential handling, and lifecycle reconciliation | Platform + Inventory | Before MaaS onboarding mode is promoted beyond experimental use |
Open Questions To Convert Into Assumptions or Decisions¶
- Notification persistence SLA target is closed for MVP by A-006 (best-effort delivery via relay + pub/sub); revisit for persistent inbox in post-beta hardening.
- API key product scope date (v1.x milestone and minimum key lifecycle controls).
- Dedicated API gateway introduction timeline (if edge policy complexity increases).