Initial commit: SWOOSH bootstrap with statechart spec, OpenAPI, ADRs, and ops harnesses

docs/ARCHITECTURE.md

@@ -0,0 +1,14 @@
+# Architecture
+
+## Core Concepts
+- **Reducer**: Pure function `newState = Reduce(oldState, Transition)`.
+- **WAL**: Append-only log of proposed & accepted transitions.
+- **Checkpoint**: Periodic snapshot; on restart: `rehydrate = checkpoint + WAL.replay()`.
+- **HLC**: Hybrid Logical Clock stamped on every transition for total ordering.
+- **Guards**: Pure predicates sourced from policy, BACKBEAT window, health probes, quorum certs.
+- **Compensation**: Inverses for PROVISION, ELECT, INDEX, etc.
+
+## Statechart (overview)
+Top-level regions: BOOT, PROJECT_LIFECYCLE (parallel: Ingestion, Council, Environment), EXECUTION (PLAN → WORK → REVIEW → REVERB), CONTROL (PAUSED/DEGRADED/RECOVERY), QUARANTINED, TERMINATED.
+
+See `docs/statechart.yaml` for machine-parseable spec.

docs/STATECHART.md

@@ -0,0 +1,6 @@
+# Statechart Explainer
+
+- **Parallel region** ensures Ingestion, Council, and Environment advance independently with clear READY prerequisites for EXECUTION.
+- **REVERB** is the only phase for final submissions, aligning with BACKBEAT's reverb concept.
+- **QUARANTINED** is sticky; human or policy change required to exit.
+- Every transition is guarded by time windows (BACKBEAT) and policy engines when applicable.

docs/statechart.yaml

@@ -0,0 +1,119 @@
+machine: SWOOSH
+version: 0.1.0
+initial: UNINITIALIZED
+states:
+  UNINITIALIZED:
+    on:
+      CONFIG_OK: LICENSE_CHECK
+  LICENSE_CHECK:
+    entry:
+      - guard: kaching.valid
+    on:
+      LICENSED: PROJECT_LIFECYCLE
+      LICENSE_FAILED: TERMINATED
+
+  PROJECT_LIFECYCLE:
+    type: parallel
+    states:
+      Ingestion:
+        initial: DISCOVER
+        states:
+          DISCOVER:
+            on:
+              SOURCES_RESOLVED: FETCH
+          FETCH:
+            on:
+              BYTES_OK: VALIDATE
+          VALIDATE:
+            on:
+              SCHEMA_OK: INDEX
+              POLICY_VIOLATION: QUARANTINED
+          INDEX:
+            on:
+              CORPUS_BUILT: READY
+          READY: {}
+      Council:
+        initial: PLAN_ROLES
+        states:
+          PLAN_ROLES:
+            on:
+              PROFILES_LOADED: ELECT
+          ELECT:
+            on:
+              QUORUM_CERT: TOOLING_SYNC
+          TOOLING_SYNC:
+            on:
+              MCP_GREEN: READY
+          READY: {}
+      Environment:
+        initial: ALLOCATE
+        states:
+          ALLOCATE:
+            on:
+              CAPACITY_OK: PROVISION
+          PROVISION:
+            on:
+              INSTALLED: HEALTHCHECK
+          HEALTHCHECK:
+            on:
+              GREEN: READY
+              AMBER: DEGRADED
+          READY: {}
+          DEGRADED:
+            on:
+              GREEN: READY
+    on:
+      ALL_READY: EXECUTION
+
+  EXECUTION:
+    initial: PLAN
+    states:
+      PLAN:
+        on:
+          PLAN_LOCKED: WORK
+      WORK:
+        on:
+          BEAT_REVIEW_GATE: REVIEW
+      REVIEW:
+        on:
+          APPROVALS_THRESHOLD: REVERB
+          CHANGES_REQUESTED: WORK
+      REVERB:
+        on:
+          NEXT_WINDOW: PLAN
+
+  PAUSED: {}
+  RECOVERY:
+    on:
+      QUORUM_RESTORED: EXECUTION
+  QUARANTINED:
+    on:
+      HUMAN_RELEASE: PROJECT_LIFECYCLE
+      CONFIRMED_BLOCK: TERMINATED
+  TERMINATED: {}
+
+guards:
+  - name: kaching.valid
+    doc: License must validate before any network operations.
+
+events:
+  - CONFIG_OK
+  - LICENSED
+  - LICENSE_FAILED
+  - SOURCES_RESOLVED
+  - BYTES_OK
+  - SCHEMA_OK
+  - POLICY_VIOLATION
+  - CORPUS_BUILT
+  - PROFILES_LOADED
+  - QUORUM_CERT
+  - MCP_GREEN
+  - ALL_READY
+  - PLAN_LOCKED
+  - BEAT_REVIEW_GATE
+  - APPROVALS_THRESHOLD
+  - CHANGES_REQUESTED
+  - NEXT_WINDOW
+  - QUORUM_RESTORED
+  - HUMAN_RELEASE
+  - CONFIRMED_BLOCK