Skip to main content

Migration Plan

:::info Source Sourced from services/ai-gateway-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Core Rules​

  • AIClient port (F09) frozen M0 end; additive methods only.
  • AIProvenance VO (F04) frozen M0 end; additive optional fields only.
  • Prompt registry format (F10) frozen M0 end.
  • Safety verdict schema (F18) frozen M1 start.
  • Model routing policy (F32) frozen M3 start.

2. AIClient Port Evolution​

  • Adding new method: safe (consumers ignore unknown until they opt in).
  • Changing existing signature: never — would break all consumers. Create new method.
  • Method deprecation: mark + sunset ≥ 2 milestones.

3. Prompt Evolution​

  • Prompts versioned (SemVer); append-only per tenant.
  • New version auto-activated after eval pass.
  • Deprecated version callable ≥ 1 milestone.
  • Per-tenant pin honored.
  • Bias or accuracy regression → rollback automatic if canary fails.

4. Model Registry Evolution​

  • New model: additive.
  • Model deprecation: deprecation event; consumers switch; old completable until all active prompts migrate.
  • Model pricing change: additive (new entry supersedes old).

5. Safety Policy Evolution​

  • Policy fields additive.
  • New categories (e.g., "manipulation") additive.
  • Thresholds tuned quarterly.

6. Provenance Evolution​

  • Fields additive only.
  • Consumers tolerant of unknown fields.

7. Event Evolution​

All v1 additive. Safety verdict schema pinned.

8. Budget Model Evolution​

  • New budget periods (e.g., "weekly") additive.
  • Hard-cap boolean additive.
  • Provider-specific budgets: additive per tenant.

9. On-Device Model Evolution​

  • Local model versions bundled with PlayPackage.
  • Devices receive update via bundle re-download.
  • Backward-compatible API so older bundles work.

10. Data Residency​

  • Provider allowlist per region.
  • Tenant residency migration: update allowed providers; re-route new completions.

11. GDPR​

  • Erase embeddings + audit entries for user.
  • Legal hold (e.g., EU AI Act investigation) overrides.

12. HIPAA BAA Evolution​

  • BAA-signed provider roster maintained.
  • Additions require legal review.
  • Removal: tenants migrate to alternate.

13. Changelog​

Per-release: new prompts, model additions, safety category additions, port method additions, pricing changes, bias monitoring cadence.