Service Readiness Gates

:::info Source Sourced from docs/roadmap/service-readiness-gates.md in the documentation repo. :::

Execution-layer companion to ROADMAP.md and 03 Microservices.

Defines what "ready" means for each service at each milestone. A service cannot exit a milestone unless all applicable gates are green for its target level.

1. Level Definitions

Level	Meaning	Who may use it
L0	Not started	—
L1	Skeleton: scaffold, empty domain + ports; zero customer endpoints	Internal + dev tests only
L2	Internal MVP: a subset of use cases callable; Pact contracts for those flows; RLS + tenant isolation green	Internal staging only
L3	Customer-facing MVP: feature subset meeting target SLOs; offline hooks registered (if applicable); AI provenance enforced (if applicable); pen-test #1 closed	Customer-facing
L4	Feature-complete per 03 spec; all applicable capabilities delivered; prompt regression + safety eval green; chaos tests passing; DR drill executed	GA-grade

Escalation: no service may run at L3 without its L2 gate green; no service runs at L4 without its L3 gate green. L4 is the target steady-state.

2. Eight Canonical Gates

Every service is measured against these at each milestone.

Gate	Definition	Test artefact
G1 Domain	Aggregates + invariants implemented in pure TS; unit tests cover every invariant	/domain/**.test.ts
G2 API	OpenAPI published + versioned; idempotency + problem+json + cursor pagination; If-Match for mutations	OpenAPI diff CI job + Pact
G3 Events	Subjects + JSON Schemas registered; outbox + inbox; Pact contracts with every registered consumer	Schema registry + Pact broker
G4 Sync	Service registers replicable aggregates with sync-service; conflict policy declared (see 02 §7)	SyncRegistration row + conformance test
G5 AI	Uses AIClient port only; provenance invariant enforced; prompts registered + eval'd; budget observable	Prompt regression + safety eval + provenance CI check
G6 Observability	SLOs defined; OTel traces propagated; metrics + dashboards + runbook	Grafana dashboard link + runbook URL
G7 Performance	k6 test meeting target p95 + p99; saturation + degradation documented	k6 report attached to release
G8 Security	Two-tenant isolation green; threat model updated; pen-test findings closed; audit events emitted; KMS keys per tenant	Security-review sign-off

3. Service × Milestone × Level Matrix

Entry format: Level (gates must be green at this level). Unlisted gates are non-applicable.

identity-service

Milestone	Level	Gates
M0	L2	G1, G2 (auth endpoints), G3 (user/session events), G6, G8 (OWASP ASVS L2 baseline)
M1	L3	+ device binding; offline-after-online cert reuse
M2	L3	+ rate limits + bot signals
M3	L4	+ SAML + OIDC advanced + SCIM; WebAuthn; OWASP ASVS L3 on auth
M4	L4	+ key rotation drills
M5	L4	+ HIPAA-ready audit

tenant-service

Milestone	Level	Gates
M0	L2	G1, G2, G3, G6, G8 (RLS policies); two-tenant isolation green
M1	L3	+ org-unit hierarchy usable
M2	L3	+ feature flags + plan routing
M3	L4	+ custom roles + ABAC + DynamicGroup evaluated at scale
M4	L4	—
M5	L4	+ residency migration saga complete

ai-gateway-service

Milestone	Level	Gates
M0	L3	G1, G2, G3, G5 (prompt registry + provenance invariant), G6, G7, G8
M1	L4	+ streaming + local-inference telemetry
M2	L4	+ Co-Author prompts with eval gates
M3	L4	+ image + TTS providers + moderation v2
M4	L4	+ semantic search + recs ranker eval
M5	L4	+ HIPAA-compliant providers; multi-region caches

sync-service

Milestone	Level	Gates
M0	L3	G1, G2, G3, G4 (registrations for pilot aggregates), G6, G7, G8
M1	L4	+ PlayPackage bundle projection + statement queue
M2	L4	+ license projections
M3	L4	+ ABAC / DG propagation + AI-pre-warm distribution
M4	L4	+ Y.Doc handling + conflict UI backend
M5	L4	+ cross-device wipe + residency-scoped cursors

delivery-service

Milestone	Level	Gates
M0	—	—
M1	L3	G1, G2, G3, G4 (sessions + turns), G5 (tutor turns), G6, G7, G8
M2	L3	—
M3	L4	+ branching + quiz gating
M4	L4	+ LTI embed launches
M5	L4	+ mobile native event emission

progress-service (LRS)

Milestone	Level	Gates
M1	L3	G1, G2, G3 (statements + attempts), G4 (append-only), G6, G7 (10 k stmts/sec), G8
M2	L3	—
M3	L4	+ xAPI 1.0.3 + cmi5 conformance
M4	L4	+ learner transcripts
M5	L4	+ regulated-tenant retention

content-service

Milestone	Level	Gates
M1	L3	G1, G2, G3, G4 (bundle projection), G6, G7, G8 (signing + encryption + tamper)
M2	L3	+ SCORM 1.2 export (ADL conformance)
M3	L4	+ SCORM 2004 + xAPI + cmi5; 3rd-party SCORM import full
M4	L4	+ full export matrix incl. HTML5 standalone
M5	L4	+ multi-region bundle distribution

authoring-service

Milestone	Level	Gates
M1	L1	G1 block runtime only (learner-side)
M2	L3	G1, G2, G3, G4 (drafts), G5 (AI Co-Author MVP), G6, G8 (publish saga)
M3	L4	+ full Co-Author (PDF→course, TTS, translate, images, branching gen)
M4	L4	+ live collab (Yjs) + offline authoring + localization
M5	L4	—

catalog-service

Milestone	Level	Gates
M1	L2	G1, G2 (read-only), G3 (consume publish), G6
M2	L3	+ browse + filter + taxonomy
M3	L3	+ visibility + marketplace projection
M4	L4	+ AI metadata enrichment
M5	L4	+ multi-region

marketplace-service

Milestone	Level	Gates
M2	L3	G1, G2, G3, G4 (licenses), G5 (moderation stub), G6, G7, G8 (PCI-scope minimized)
M3	L3	+ coupons + webhooks + SCIM-assigned seats
M4	L4	+ full moderation + provider SDK
M5	L4	+ multi-currency + bundles + gift licenses

billing-service

Milestone	Level	Gates
M2	L3	G1, G2, G3, G6, G7, G8 (PCI-scoped)
M3	L3	+ multi-processor
M4	L3	+ dunning + tax depth
M5	L4	+ multi-currency payouts + FX

enrollment-service

Milestone	Level	Gates
M1	L3	G1, G2, G3, G4 (enrollments), G6, G8
M2	L3	+ purchase-sourced enrollments
M3	L3	+ assignment-sourced enrollments
M4	L3	+ version migrations
M5	L3	—

assignment-service

Milestone	Level	Gates
M2	L1	G1 (manual one-shot only)
M3	L4	G1–G8 full; RRULE engine frozen; DST + leap fixtures
M4	L4	—
M5	L4	+ AI recommender depth

assessment-service

Milestone	Level	Gates
M1	L3	G1, G2, G3, G6, G7, G8 (serve + score only)
M2	L3	+ quiz bank CRUD
M3	L4	+ branching scenarios + AI generation + AI grading
M4	L4	—
M5	L4	+ rubric marketplace

certification-service

Milestone	Level	Gates
M1	L2	G1, G2, G3 (issue + verify), G6, G8 (JWS signing)
M2	L2	+ public verify UI
M3	L3	+ templates + offline claims + recert
M4	L4	+ Open Badges v3
M5	L4	+ multi-region

notification-service

Milestone	Level	Gates
M0	L3	G1, G2 (core), G3, G6, G7, G8 (SPF/DKIM/DMARC)
M1	L3	+ multi-channel (email + in-app + push)
M2	L3	+ suppression list + bounce handling
M3	L4	+ tenant webhooks + webhook DLQ
M4	L4	+ AI tone adaptation
M5	L4	+ HIPAA-safe providers

media-service

Milestone	Level	Gates
M1	L2	G1, G2, G3, G6, G8 (virus scan + MIME)
M2	L3	+ transcoding + captions (AI) + image variants
M3	L3	+ TTS pipeline
M4	L4	+ AI image styles + 360° optional
M5	L4	+ region-local storage

search-service

Milestone	Level	Gates
M1	L1	G1 (lexical-only skeleton), G6
M2	L2	+ catalog browse search
M3	L3	+ assignment search
M4	L4	+ semantic hybrid + recommendations
M5	L4	+ personalized ranker + residency-scoped indices

analytics-service

Milestone	Level	Gates
M0	L1	G1, G3 (firehose consumer skeleton)
M1	L2	+ learner progress widget
M2	L3	+ provider sales dashboard
M3	L4	+ AI insight v1 + scheduled reports
M4	L4	+ recommendations dashboards
M5	L4	+ AI insight v2 + board summaries + raw exports

4. Gate Details

G1 Domain — acceptance criteria

• Pure TS; no framework imports.
• Every aggregate root has invariants codified in its constructor + command methods.
• Unit coverage ≥ 95 % on domain folder.
• No any types in domain.
• Value objects equal by value, compared via equals().

G2 API — acceptance criteria

• OpenAPI 3.1 published at /openapi.json.
• Problem+JSON on every error.
• Idempotency-Key required on all writes.
• If-Match required on all mutations.
• Cursor pagination everywhere; no offset.
• Error codes from registry only; no ad-hoc strings.
• Rate-limit headers on throttled routes.

G3 Events — acceptance criteria

• Every outgoing event has schema in registry.
• Every incoming event validated on consume.
• Outbox + inbox rows present.
• Pact contracts with each registered consumer.
• Envelope includes tenantId, retentionClass, dataResidency.

G4 Sync — acceptance criteria

• SyncRegistration row for every replicable aggregate.
• Conflict policy from 02 §7 declared.
• Push idempotency by clientMutationId.
• Pull supports cursor + hasMore.
• Chaos test covers drop, retry, partial push.

G5 AI — acceptance criteria

• No direct LLM SDK imports outside ai-gateway-service.
• AIClient adapter used in every AI-calling use case.
• AIProvenance required on every persisted AI artifact.
• Prompt registry entries with pinned versions per tenant.
• Prompt regression + safety eval gates before promotion.

G6 Observability — acceptance criteria

• SLOs documented: availability, latency (p50/p95/p99), error rate.
• OTel traces with traceparent flowing end-to-end.
• Metrics: RPS, latency, errors, saturation.
• Dashboard link in runbook.
• Alert thresholds + escalation.

G7 Performance — acceptance criteria

• k6 scenario matching peak-hour traffic.
• Saturation point documented.
• Degradation plan documented (what gets shed).
• Cold-start + warm-cache both measured.

G8 Security — acceptance criteria

• Two-tenant isolation test suite green.
• Threat model updated for changes in this milestone.
• Pen-test findings closed for the release scope.
• Audit events emitted for every sensitive action.
• KMS keys per tenant where applicable.
• Dependency vulnerability scan green.

5. Milestone Exit Summary (derived)

A milestone exits when every in-scope service reaches its declared level with its gates green. Non-compliant services block the milestone.

Milestone	Must-green services (level target)
M0	identity L2, tenant L2, ai-gateway L3, sync L3, notification L3, analytics L1
M1	+ delivery L3, progress L3, content L3 (bundle+HTML), authoring L1, catalog L2, enrollment L3, assessment L3, certification L2, media L2, search L1, analytics L2
M2	+ marketplace L3, billing L3, authoring L3, catalog L3, content L3 (+SCORM 1.2), certification L2, media L3, analytics L3
M3	+ identity L4, tenant L4, assignment L4, content L4, assessment L4, certification L3, notification L4, media L3, analytics L4
M4	+ authoring L4, catalog L4, marketplace L4, search L4, certification L4, media L4
M5	+ billing L4, enrollment L3 (unchanged), residency-capable services L4

6. Governance

• Change control: level upgrades require sign-off from service owner + architecture + security.
• Regression: a failing gate on any merged change blocks release until remediated.
• Exceptions: a service may ship to production at L3 with a documented delta from L4; delta tracked in the risk register and must close within one milestone.