# Service Architecture Migration Cutover

> Canonical path: `specs/architecture/service-architecture-migration-cutover.md`
> Status: terminal canonical-only cutover
> Scope: Service Actor, Service Event, Schedule, and Automation runtime boundaries.

## 1. Purpose

The destructive schema cutover is complete. Current binaries use canonical
Service Actor, Service Event, Schedule, and Automation stores as their only
runtime facts. The historical legacy tables remain migration history only and
are not read, written, replayed, aliased, or projected by product runtime code.

## 2. Runtime ownership

```text
App identity/installations/connections/grants -> Service Actor tables
Provider subscriptions/deliveries/webhooks  -> Service Event tables
Time-based schedules/runs                    -> Schedule/Automation tables
Message provenance                           -> typed ledger contribution source
```

Stable App, provider-watch, and Trigger-shaped routes are product facades. They
translate request/response shapes to canonical methods and never resurrect an
old storage projection.

## 3. Canonical contracts

- App runtime reads and writes `service_*` stores, including service target
  bindings, webhook receipts, and notification state.
- Provider create/list/pause/resume/remove operations use
  `service_event_subscriptions`; delivery matching and lifecycle state use
  `service_event_deliveries` and the canonical subscription row.
- Provider webhook ingress reserves `service_webhook_receipts` and persists
  provider contribution provenance as `service_event_delivery`.
- Schedule management and execution use `schedule_definitions` and
  `automation_runs`; the stable `/triggers` facade returns canonical schedule
  ids.
- Message source validation accepts only `service_event_delivery`,
  `automation_run`, `workflow_run`, or ordinary message references according to
  the typed contribution-source contract.

## 4. Safety and verification

The terminal migration is immutable and drops the reviewed legacy schema in
FK-safe order. Historical fixtures remain available to migration tests, but no
runtime compatibility resolver may query those tables. Guardrails reject legacy
Trigger-table SQL in production App, Schedule, Message, and Service Event code.

Required focused verification covers:

```text
historical schema fixture -> terminal migration
fresh canonical bootstrap
provider create/list/pause/resume/remove
provider connection block/unblock and recovery
webhook receipt/delivery idempotency and retention
schedule create/list/pause/resume/delete and automation run history
message contribution-source validation and read resolution
```

A full repository test run is intentionally outside this scoped integration
workflow; release review uses the targeted results and `scripts/harness-fast.sh`.