Skip to content

Assumptions register

Decided

Source: doc/governance/Assumptions_Register.md — 20 active MVP assumptions with re-validation triggers

Every implicit assumption is made explicit here so hidden design constraints don't turn into production surprises. The register enforces re-validation at phase gates.

Update rule

flowchart TB
    CH[Design or implementation<br/>choice in a PR] --> ASK{Depends on an<br/>assumption not<br/>listed yet?}
    ASK -- yes --> ADD[Add it in the same PR]
    ASK -- no --> NA[No action needed]
    ASK -- assumption changes --> UPD[Update register +<br/>dependent docs/contracts<br/>in the same PR]

    classDef ok fill:#d1e7dd,stroke:#0a3622
    class ADD,UPD,NA ok

Status values:

Status Meaning
active Currently relied on
validated Confirmed in implementation / runtime
retired No longer relied on

The 20 active assumptions

ID Assumption (short) Scope Status Re-validation trigger
A-001 Public ingress / WAF / API gateway provided by deployment platform Runtime edge active Before first public env launch
A-002 Public entrypoints split: cmd/api REST + cmd/terminal-gateway WS; internal HTTP for node-agent & terminal relay; internal gRPC deferred Service topology active Phase-2 extraction decision
A-003 Identity is OIDC-first; local password is dev/bootstrap-only Auth active Auth implementation start + security review
A-004 API key auth is deferred from MVP; middleware pluggable via resolver Auth extensibility active API-key phase kickoff
A-005 Terminal WS auth via single-use token in Sec-WebSocket-Protocol (no query-token) Terminal security active Terminal phase + pen test
A-006 Notification bridge is NATS → notification-relay → Redis pub/sub → WS hub; persistent inbox deferred Notifications active Before beta reliability hardening
A-007 Financial policy values are config-driven (policy_values table), not constants Billing / policy active Every policy-related PR
A-008 Refund semantics: provider refund within window; else internal credit; outcome always explicit Payments / product active Refund implementation kickoff
A-009 Full enterprise IAM (groups, multi-tenant context switch, advanced role matrix) deferred from MVP Phase-2 readiness active Tenant ownership baseline signoff + end of MVP review
A-010 No production data migration from prototype; clean state rebuild Delivery / migration active Pre-launch Go/No-Go
A-011 Production object storage is S3-compatible; local FS is reference only Storage active Storage implementation kickoff
A-012 CI runtime is GitLab-first for MVP; gate scripts provider-agnostic DevEx / CI validated CI topology change
A-013 Service mesh (Envoy/Istio) deferred; managed edge + app middleware is the baseline Platform networking active First multi-service independent deploy
A-014 East/west security mandatory at MVP: default-deny + mTLS + cert lifecycle Platform security active Before staging → prod promotion
A-015 Full OPA/OPAL deferred; MVP uses DB-backed PolicyClient with OPA-ready decision interface Authz / policy architecture active Same as A-002 service extraction
A-016 Admin-token emergency revocation required pre-production (deny-list / token versioning) Auth security active Before first admin production login
A-017 MVP uses reset-baseline for tenant/project ownership (no legacy backfill) Delivery / migration active Before ownership baseline implementation
A-018 Service-account model is project-scoped machine identity with short-lived tokens + endpoint allowlists Auth / product active Before app-team SA implementation
A-019 service_account_credentials.private_key_enc may store encrypted key material in Postgres for MVP; KMS/Vault path required pre-production Auth security active Pre-production security hardening gate
A-020 Enterprise SSO is per-tenant federation (tenant-bound OIDC/SAML); platform-global auth stays for admin + personal bootstrap Auth / tenant architecture active Before enterprise tenant onboarding

Re-validation trigger pattern

sequenceDiagram
    autonumber
    participant DEV as Phase / release owner
    participant REG as Assumptions Register
    participant ARCH as Architecture / security owner
    participant CHK as Re-validation

    DEV->>REG: phase gate reached (e.g. Phase 7 kickoff)
    REG-->>DEV: list assumptions whose trigger matches this phase
    DEV->>CHK: walk through each assumption
    alt still true
        CHK->>REG: mark validated or keep active
    else changed
        CHK->>REG: update text + status — cross-reference dependent docs
        CHK->>ARCH: review for design-impact
    else retired
        CHK->>REG: mark retired — remove dependencies
    end

Coupling to the rest of the system

flowchart LR
    AR[Assumptions Register]
    AR -.A-001 to A-002.-> ARCH[Architecture topology decisions]
    AR -.A-003 to A-005 + A-016, A-018, A-019, A-020.-> AUTH[IAM + auth]
    AR -.A-007, A-008.-> BILL[Billing + payments]
    AR -.A-006.-> NOTIF[Notifications]
    AR -.A-009, A-017.-> TEN[Tenant + project ownership]
    AR -.A-010.-> MIG[Delivery + migration]
    AR -.A-011.-> STG[Storage]
    AR -.A-012.-> CI[CI / DevEx]
    AR -.A-013, A-014.-> SEC[East/west security + mesh]
    AR -.A-015.-> POL[Authz / policy]

    classDef src fill:#fff3cd,stroke:#332701
    classDef out fill:#d1e7dd,stroke:#0a3622
    class AR src
    class ARCH,AUTH,BILL,NOTIF,TEN,MIG,STG,CI,SEC,POL out

When an assumption breaks

flowchart TB
    EVENT[External change<br/>e.g. enterprise customer<br/>requires non-S3 storage]
    EVENT --> SEARCH[Search register<br/>for impacted assumptions]
    SEARCH --> FOUND[A-011 — production storage<br/>is S3-compatible]
    FOUND --> ASSESS[Architecture / storage owner<br/>assess impact]
    ASSESS --> Q{Adjust scope or<br/>break assumption?}
    Q -- adjust scope --> CARVEOUT[Document carve-out;<br/>keep assumption with caveat]
    Q -- break --> ROLLOVER[Update register;<br/>start dependency cascade<br/>through dependent docs]
    ROLLOVER --> CASCADE[Update:<br/>Storage_Provider_Capability_Model_v1<br/>+ storage service code<br/>+ tests<br/>+ runbooks]

    classDef warn fill:#fff3cd,stroke:#332701
    classDef act fill:#d1e7dd,stroke:#0a3622
    class EVENT,FOUND,ASSESS warn
    class CARVEOUT,ROLLOVER,CASCADE act

Why this matters for reviewers

The register answers two recurring reviewer questions:

Question Where to look
"Why doesn't the platform do X?" Register — likely a deferred-by-design assumption
"What changes if we want to add X?" Register entry's re-validation trigger names the gate

For example:

  • "Why no service mesh?" → A-013, deferred until first multi-service independent deploy milestone.
  • "Why no API keys?" → A-004, deferred; middleware is pluggable so retrofitting won't be a rewrite.
  • "Why local password login at all?" → A-003, dev-only; not in public SDK surface.

Where to look next