Skip to content

Norn v3 planning package ​

For current product documentation, start with Norn 3.0.0. This page indexes the planning records and their historical proposals. The launch state and release milestones record the successful 2026-11-16 online upgrade and completed pilot retirement. Management remains separate and available. V1 and V2 documentation is retained.

Older proposals below are design history. An accepted decision does not itself establish live qualification. Use the capability reference for the current boundary and the repository split for proposed Fleet/self-hosted ownership.

An Architecture Decision Record (ADR) captures a consequential choice, its alternatives, rationale, consequences and validation. Proposed means ready for review; Accepted means the choice has been agreed, not that it is implemented. Later changes supersede records rather than erase the rationale.

Read in this order ​

  1. Architecture roadmap: release scope, milestones and dependencies.
  2. ADR 0001 — State, evidence and observability.
  3. ADR 0002 — Control stores and fencing.
  4. ADR 0003 — Profiles and database bindings.
  5. ADR 0004 — Scaling and placement.
  6. ADR 0005 — Upgrade compatibility.
  7. ADR 0006 — Migration authority.
  8. Planning contracts: state inventory, interface/resource proposals, compatibility, measurement and acceptance plan.
  9. Execution milestones: delivery sequence, parallel work, exit gates and release evidence.
  10. Implementation status: branch-specific local progress and qualification boundary.
  11. Foundation review: source-backed safety findings, bounded implementation slices and review acceptance tests.
  12. Fleet controller plan and ADR 0009 — Fleet controller: the target fence, authority epoch and resource-status work for changes 1-4, plus its lifecycle contract, review and operator runbook.
  13. Online upgrade lessons and capability proposal: Mini upgrade findings and a platform-wide path to low-interruption upgrades.
  14. Offline lane statecharts: bounded release, Mini, existing-Fleet Genesis, fresh-Fleet create/recovery, and workload models with reproduction instructions.
  15. Mini host assurance route authentication: SOPS credential handoff, the narrow retained-fence exception, and live verification requirements.

The older session and topic handoffs are available in Git history. Use the current release handoff above for next actions and the status and review documents for implementation details.

  • Require both initial release paths: existing Mini v2/PG → v3 on the same PG/runtime, and fresh DigitalOcean HA Fleet v3 on three control-node etcd members.
  • Keep three logical storage concerns: control correctness, evidence archive, diagnostics. Etcd must not retain a mandatory historical PG dependency.
  • Consolidate physical services locally while maintaining the same logical identities and explicit non-HA status.
  • Preserve PostgreSQL as the supported Mini control backend. Fleet uses etcd independently from application DBs; optional Fleet control PG is not an initial GA gate.
  • Make desired replica count durable and distinct from VM count; require explicit placement and remaining capacity before drain.
  • Qualify single-active API handoff before promising continuous API service; test ownership and schema compatibility before wider concurrency.
  • Use a writer-fenced, externally recoverable migration coordinator; never treat switching a connection string back as sufficient rollback after new writes.
  • Deploy and qualify an application directly on the independent staging Fleet, including its data binding, web/worker behavior, traffic and recovery. Mini-to-Fleet application migration and general PG↔etcd control conversion are deferred; neither blocks the Mini upgrade or the staging Fleet launch.

Remaining product choices ​

Architecture can be reviewed now. The following still need an agreed product policy or measured engineering result:

ChoiceProposed defaultHow to close
Availability and recovery budgetsSeparate app/control/database/job budgets; draft targets in planning contractsConfirm acceptable interruptions, then benchmark and qualify
LogsSeven-day local / 30-day Fleet diagnostic targets under hard disk capsConfirm retention/cost needs; collector/backend spike
Etcd supportRequired for initial HA Fleet GA; PG required for the Mini upgradeShared invariants plus isolated partition, restore and fresh-bootstrap evidence; no general backend-conversion gate
API serving modelSingle-active handoff firstDecide whether measured handoff meets the required API budget
Initial app DB scopePG plus MySQL for WordPressConfirm engine workflows included at GA; defer Cockroach

The user has separately authorized staged local implementation. See implementation status for evidence; this does not implicitly accept every proposed ADR or numerical budget. Resolve the decisions required by each slice before implementing it. The initial backward-compatible startup-safety slice does not select a new backend or qualify a release. Update milestone status based on evidence rather than the existence of these documents; live deployment remains separately scoped.