NNO Documentation

Status: Phase 1 (core transitions) + Phase 2 (KV enforcement at Gateway) Date: 2026-03-30

1. Overview

Every platform in the Neutrino system has a lifecycle status that governs what operations are allowed, what resources are accessible, and how the Gateway routes requests. The Registry service is the authoritative source for platform status.

2. States

Status	Description
`pending`	Platform record created — awaiting provisioning bootstrap
`provisioning`	Infrastructure bootstrap in progress (CF resources, repo, DNS)
`active`	Normal operation — all services accessible
`suspended`	Temporarily disabled — operator or automated action
`pending_cancellation`	Cancellation requested — active until billing period ends
`cancelled`	Fully cancelled — resources scheduled for cleanup
`deleted`	Soft-deleted — resources deprovisioned, data retained per policy

3. Valid Transitions [Phase 1]

   ┌─────────┐   (bootstrap)   ┌──────────────┐   (complete)   ┌──────────┐
   │ pending │────────────────►│ provisioning │───────────────►│  active  │
   └─────────┘                 └──────────────┘                └────┬──┬──┘
                                                          suspend │  │ cancel
                                                                  ▼  │
                                                           ┌──────────┐
                                                           │ suspended│◄─ restore ─┐
                                                           └────┬──┬──┘            │
                                                        cancel  │  └───────────────┘
                                                                ▼
                    ┌──────────┐                    ┌─────────────────────┐
                    │ deleted  │◄── delete ─────────│ pending_cancellation│
                    └──────────┘         │          └─────────┬───────────┘
                          ▲              │                    │ (period ends)
                          └─── delete ───┴─── ◄──────────────┘
                                     cancelled

Transition Rules (from VALID_TRANSITIONS in Registry):

Action	Allowed From	Target Status
`provision`	`pending`	`provisioning`
`activate`	`provisioning`	`active`
`suspend`	`active`	`suspended`
`restore`	`suspended`	`active`
`cancel`	`active`, `suspended`	`pending_cancellation`
`delete`	`cancelled`, `pending_cancellation`, `active`, `suspended`	`deleted`

Invalid transitions return 422 Unprocessable Entity with error code INVALID_STATE_TRANSITION.

4. API Endpoints [Phase 1]

All endpoints are on the Registry service, proxied via Gateway at /api/v1/platforms/*.

Method	Path	Description
`POST`	`/platforms/:id/suspend`	Suspend platform — sets `suspendedAt`, records reason
`POST`	`/platforms/:id/restore`	Restore platform — clears `suspendedAt`/`suspensionReason`
`POST`	`/platforms/:id/cancel`	Cancel platform — sets `pending_cancellation`, cancels Stripe subscription
`POST`	`/platforms/:id/delete`	Soft-delete — sets `deleted`, triggers `DEPROVISION_PLATFORM` job
`GET`	`/platforms/:id/lifecycle`	Lifecycle event history (cursor-paginated)

Request body (suspend/restore/cancel/delete): \{ "reason": "optional explanation" \}

5. Side Effects

Transition	Side Effect
`suspend`	KV write-through: `platform:\{id\}:status = suspended` (Phase 2)
`restore`	KV write-through: `platform:\{id\}:status = active` (Phase 2)
`cancel`	Stripe subscription cancellation (`DELETE /subscriptions/\{customerId\}`) at period end
`delete`	Enqueue `DEPROVISION_PLATFORM` job via Provisioning service binding

All transitions record a platform_lifecycle_events row with fromStatus, toStatus, triggeredBy, triggerType (operator_action or user_action), and optional reason/metadata.

6. Gateway Suspension Enforcement [Phase 2]

The Gateway enforces platform suspension at the edge:

Read platform:\{platformId\}:status from NNO_PLATFORM_STATUS_KV
If suspended or cancelled → return 403 PLATFORM_SUSPENDED
Operator-role users bypass suspension checks

Phase 1: No Gateway-level enforcement — status is checked by downstream services only.

See services/gateway.md for Gateway implementation details.

7. Trigger Types

Type	Description
`operator_action`	NNO operator manually triggers via console or API
`user_action`	Platform owner requests cancellation
`automated`	System-triggered (e.g., billing failure, trial expiry) (Phase 2)
`billing_event`	Stripe webhook triggers status change (Phase 2)

Platform Lifecycle