svcforge: reference implementation

Complete working build of the system learn-python/ teaches.
164 tests, mypy --strict clean, domain coverage 99%.

migrations/001_init.sql

@@ -0,0 +1,36 @@
+-- 001_init.sql — instances and tasks.
+--
+-- Forward-only. There is no down script. If this is wrong, 002 fixes it.
+
+create table instances (
+  id           uuid primary key default gen_random_uuid(),
+  team         text        not null,
+  service_type text        not null,           -- 'elasticsearch' | 'redis' | ...
+  size         text        not null,           -- 'small' | 'medium'
+  state        text        not null,
+  namespace    text        not null,
+  release_name text        not null unique,    -- helm release; the idempotency anchor
+  chart_version text       not null,           -- what's ACTUALLY deployed. day-2 hinges on this column.
+  endpoint     text,
+  error        text,
+  expires_at   timestamptz,
+  created_at   timestamptz not null default now(),
+  updated_at   timestamptz not null default now()
+);
+
+create table tasks (
+  id            bigserial primary key,
+  instance_id   uuid        not null references instances(id) on delete cascade,
+  kind          text        not null,          -- 'provision'|'deprovision'|'upgrade'|'verify'
+  state         text        not null default 'queued',  -- queued|running|done|failed
+  attempts      int         not null default 0,
+  run_after     timestamptz not null default now(),     -- backoff lands here
+  locked_by     text,
+  locked_at     timestamptz,
+  last_error    text,
+  created_at    timestamptz not null default now()
+);
+
+-- Partial index: the claim query only ever looks at queued rows. Keeping the index
+-- to that subset means it stays small no matter how much history `tasks` accumulates.
+create index tasks_runnable on tasks (run_after) where state = 'queued';

migrations/003_day2.sql

@@ -0,0 +1,16 @@
+-- 003_day2.sql — the whole of day 2: two columns and one query.
+--
+-- Forward-only, expand/contract. Both additions are nullable / defaulted, so the old
+-- code keeps running against the new schema between the migrate and the deploy. That
+-- ordering is not optional: migrate first, deploy second, and a column the running
+-- code has never heard of must not break it.
+
+alter table instances add column maintenance_window text;   -- '0 3 * * 0|Asia/Ho_Chi_Minh', null = any time
+
+-- One row per service type, one column that matters. `halted` is what stops a bad
+-- chart after the first tenant instead of after all of them, and it is cleared by
+-- hand with SQL — an automatic un-halt would just resume breaking things.
+create table catalog_versions (
+  service_type  text primary key,
+  rollout_state text not null default 'ok'    -- 'ok' | 'halted'
+);

migrations/004_traceparent.sql

@@ -0,0 +1,15 @@
+-- 004_traceparent.sql — carry the trace across the queue.
+--
+-- A trace is a chain of span contexts. `POST /v1/instances` commits a row and returns;
+-- a worker in another pod claims that row minutes later. Nothing propagates the context
+-- across that gap, because the gap is a table. So the context rides in the table: the API
+-- writes the W3C traceparent it is currently inside, and the worker extracts it at claim
+-- and makes its span a child of the API's. Skip this and Tempo shows two unrelated traces
+-- for one provision, which is worse than no tracing — it looks like it works.
+--
+-- Nullable, no default, no backfill: expand/contract done right. Old rows have no
+-- traceparent and never will; a worker running the previous image ignores a column it has
+-- never heard of. Migrate first, deploy second, and neither step needs the other to have
+-- happened.
+
+alter table tasks add column traceparent text;   -- '00-<32 hex>-<16 hex>-01', null = untraced