moloapp/plans/README.md

# MoloApp Detailed Plans

Index for the fifteen detailed plan files. Each file is self-contained with purpose, best practices, structure, rules, guidelines, specifications, execution steps, validation, references, open questions, and sources.

## Index

| # | File | Title | Scope (one line) |
|---|------|-------|------------------|
| 1 | 01-runtime.md | Core Runtime and HTTP Fundamentals | Event loop, lifecycle, HTTP/1.1 + HTTP/2, compression, cookies, static. |
| 2 | 02-observability.md | Observability Backbone | Logging, typed events, metrics, tracing, correlation, zero-cost gating. |
| 3 | 03-security.md | Security | TLS wolfSSL, auth, hashing/crypto, sessions, guards, upload safety. |
| 4 | 04-data.md | Data Layer | ORM dual backends, self-healing, pooling, transactions, KV, cache, pubsub. |
| 5 | 05-request-routing.md | Request/Response, Routing, Views, Templates | App, routers, views, validation/forms, negotiation, templates, middleware, DI, errors. |
| 6 | 06-realtime.md | Realtime (WebSocket, SSE, Socket.IO, Streaming, WebDAV, Client Parity) | Live protocols plus streaming plus WebDAV, every one with client parity. |
| 7 | 07-supervisor-replication.md | Supervisor, Tasks, Replication | Process supervisor, background tasks, pubsub durability, replication, multi-instance. |
| 8 | 08-clients-openapi.md | Clients, OpenAPI, Test Client | HTTP/REST client, REST standards, OpenAPI generation, test client. |
| 9 | 09-cli-ops.md | CLI Tooling, Dev Server, Operations | CLI, dev server, embedder, AI harness, health/metrics, i18n/CSP. |
| 10 | 10-workflow-example.md | Workflow, Testing Discipline, Living Example | Specs, AGENTS.md, autonomous git, integration testing, living example. |
| 11 | 11-tenancy.md | Multi-Tenancy | First-class tenants: isolation strategies, quotas, flags, per-tenant metrics. |
| 12 | 12-audit-compliance.md | Audit and Compliance | Immutable audit log, GDPR export/erasure, retention, PII marking, masking. |
| 13 | 13-operability.md | Operability at Scale | Safe deploys, drains, locks/election, breakers, deadlines, SLO, chaos, debug. |
| 14 | 14-api-governance.md | API Governance | API keys, versioning/deprecation, OpenAPI diff gate, rate tiers, surface rules. |
| 15 | 15-supply-chain.md | Supply Chain and Trust | SBOM, signed provenance, dependency policy, vuln-scan hook, release attestation. |

## How files reference each other

- References always use exact sibling filenames (`01-runtime.md` through `15-supply-chain.md`).
- Each file has a References section naming Depends on (interfaces it consumes) and Feeds (interfaces it provides).
- Dependency direction (consumes, upstream first):
  - `01-runtime.md` depends on `02-observability.md` (hooks) and `03-security.md` (TLS handle); feeds `05-request-routing.md`, `06-realtime.md`, `08-clients-openapi.md`, `09-cli-ops.md`.
  - `02-observability.md` depends on `01-runtime.md` (lifecycle hooks); feeds `04-data.md`, `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `09-cli-ops.md`, `10-workflow-example.md`.
  - `03-security.md` depends on `01-runtime.md` and `02-observability.md`; feeds `04-data.md`, `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `09-cli-ops.md`, `10-workflow-example.md`.
  - `04-data.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`; feeds `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `10-workflow-example.md`.
  - `05-request-routing.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`; feeds `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `09-cli-ops.md`; follows `10-workflow-example.md`.
  - `06-realtime.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `05-request-routing.md`; feeds `04-data.md` (pubsub bridge), `07-supervisor-replication.md`, `08-clients-openapi.md`, `10-workflow-example.md`.
  - `07-supervisor-replication.md` depends on `01-runtime.md`, `02-observability.md`, `04-data.md`, `06-realtime.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`.
  - `08-clients-openapi.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`; defers realtime clients to `06-realtime.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`.
  - `09-cli-ops.md` depends on `01-runtime.md` through `08-clients-openapi.md`; feeds `10-workflow-example.md`.
  - `10-workflow-example.md` depends on `02-observability.md`, `08-clients-openapi.md`, `09-cli-ops.md`; feeds `01-runtime.md` through `09-cli-ops.md` (spec template, test discipline, release gates).
  - `11-tenancy.md` depends on `01-runtime.md` through `09-cli-ops.md` (joint hardening milestone with `04-data.md` before either file freezes); follows `10-workflow-example.md`; feeds `12-audit-compliance.md`, `14-api-governance.md`.
  - `12-audit-compliance.md` depends on `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`, `07-supervisor-replication.md`, `11-tenancy.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`; defers exchange formats to `13-operability.md`, API policy to `14-api-governance.md`, attestation to `15-supply-chain.md`.
  - `13-operability.md` depends on `01-runtime.md`, `02-observability.md`, `04-data.md`, `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `09-cli-ops.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`, `12-audit-compliance.md`.
  - `14-api-governance.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`, `08-clients-openapi.md`, `10-workflow-example.md`, `11-tenancy.md`; feeds `09-cli-ops.md`, `12-audit-compliance.md`, `13-operability.md`; parallel with `07-supervisor-replication.md`, `15-supply-chain.md`.
  - `15-supply-chain.md` depends on `02-observability.md`, `03-security.md`, `09-cli-ops.md`, `10-workflow-example.md`; feeds `11-tenancy.md`, `12-audit-compliance.md`, `13-operability.md`, `14-api-governance.md`.

## Overall execution order

Build order follows plan.md section 10, with the file sequence matching dependency order:

1. `01-runtime.md` steps 1-10 plus `02-observability.md` steps 1-10 (plan step 1: foundation and instrumentation).
2. `03-security.md` steps 1-10 (plan step 2: TLS, auth, guards, uploads).
3. `04-data.md` steps 1-10 (plan step 3: drivers, ORM, sync/heal, KV/cache/pubsub).
4. `06-realtime.md` steps 1-5 plus `07-supervisor-replication.md` steps E7-1 through E7-4 (plan step 4: realtime base, supervisor and task runner).
5. `05-request-routing.md` steps E1-E12 plus `08-clients-openapi.md` steps 1-8 plus `09-cli-ops.md` steps 1-10 (plan step 5: app layer, clients, OpenAPI, CLI/ops).
6. `07-supervisor-replication.md` steps E7-5 through E7-8 (plan step 6: durable streams, replication, multi-instance).
7. `10-workflow-example.md` steps 1-8 throughout and finally (plan step 7: specs, AGENTS.md, pipeline, living example, autonomous end-to-end run).
8. `11-tenancy.md` steps E11-1 through E11-4 jointly with `04-data.md` (tenant context in the data Context before the data layer hardens), then E11-5 through E11-8 with the app layer (plan step 8: multi-tenancy).
9. `12-audit-compliance.md` steps 1-10 plus `13-operability.md` steps 1-8 (plan step 9: audit/compliance plus operability at scale).
10. `14-api-governance.md` steps 1-8 plus `15-supply-chain.md` steps E15-1 through E15-8 (plan step 10: API governance plus supply chain and trust).

Rule: no file is done until its validation section passes through the real stack and `10-workflow-example.md` rule 1 holds (spec updated, docs updated, living example demonstrates it, full suite green, same session).