fix(recovery): restore source removed by production documentation merge

2026-11-10 03:42:10 +01:00
parent 585bdd4b44
commit 3d2fc6f913
957 changed files with 115754 additions and 0 deletions
@@ -0,0 +1,41 @@
+# API deprecation policy — 0pt
+
+BACKLOG P6 (API-24). There is exactly one prior breaking-ish change in this
+repo's history to learn from: `services/api/orchestrator/main.py` moved from
+`src/orchestrator` (docs/09-build-plan.md Phase 0) — internal, pre-contract,
+no external consumers yet. This policy is written before it's needed for a
+real consumer, on purpose (BACKLOG's own framing: "cheaper to write the
+policy than to clean up after breaking someone").
+
+## What counts as breaking
+
+- Removing a path, operation, or required request/response field from
+  `contracts/openapi.yaml`.
+- Narrowing an accepted value (enum shrink, type tightening) on a request field.
+- Changing a response field's meaning without changing its name/type.
+- Changing default auth/tenant behavior on an existing route (e.g. what
+  BACKLOG P0-4 fixed — the reverse of a break, but the same class of change).
+
+Not breaking: adding an optional field, adding a new path, widening an
+accepted value, adding a new enum member a client can ignore.
+
+## Process
+
+1. Mark the field/path `deprecated: true` in `contracts/openapi.yaml` with an
+   `x-siax-deprecated-since` date and a one-line replacement pointer.
+2. Keep the deprecated shape working for **at least one release cycle**
+   after the replacement ships (see `CHANGELOG.md` once real releases/tags
+   exist — BACKLOG P1-3).
+3. Announce in `CHANGELOG.md`'s `[Unreleased]` section before merge, not
+   after.
+4. Only remove once nothing in this repo's own consumers (Protosell/FiveCRM,
+   VehIQ per `CLAUDE.md`) is verified to depend on the old shape — "verified"
+   means checked against those repos, not assumed silent.
+
+## What this repo does NOT have yet
+
+No consumers are known to be live against this contract yet
+(`docs/architecture/ARCHITECTURE.md` §2 "Beroenden nedåt": "Inga sådana
+anrop finns i det här repot" — unverified downstream). This policy exists
+so the first real breaking change has a process to follow, not because one
+has happened.
@@ -0,0 +1,26 @@
+# API docs — 0pt
+
+BACKLOG P1-20 (DOC-07/08). This directory did not exist before this pass.
+
+**Source of truth:** [`contracts/openapi.yaml`](../../contracts/openapi.yaml)
+(OpenAPI 3.1, `0pt Data OS API`). Route handlers in `app/api/*` realize
+these contracts; `x-siax-status` on each path says whether it's `live` or
+contract-first (target).
+
+This directory does **not** duplicate the contract as hand-written prose —
+that would drift the moment one of them is edited and not the other (exactly
+the kind of stale-doc problem this whole compliance pass exists to fix).
+Instead:
+
+| Question | Where to look |
+|---|---|
+| What routes exist, request/response shapes | [`contracts/openapi.yaml`](../../contracts/openapi.yaml) directly, or render it with any OpenAPI viewer |
+| Which routes are live vs. target-only | `x-siax-status` field per path in the same file |
+| Risk level + auth requirement per route | `docs/architecture/ARCHITECTURE.md` §3 "API-yta" |
+| Capability → surface (API/CLI/MCP/UI) coverage | `docs/architecture/ARCHITECTURE.md` §5 "Ytor och paritet" |
+| The separate FastAPI engine contract (`services/api`) | `docs/04-api.md` |
+| The edge-native P0 capability contract (`app/api/0pt/*`) | `docs/12-edge-capability-api.md` |
+
+There are genuinely **two** API surfaces documented separately (edge Next.js
+routes vs. the FastAPI engine) — see `docs/02-architecture.md` "Two API
+surfaces" for why, before assuming a route lives in the file you expected.