Capability Model Migration Notes

This note records the schema inventory behind:

1. Scope

This note records the schema inventory behind:

20260623-capability-model-breaking-migration.mysql.sql

The migration is breaking and targets the new model:

Node + CapabilityBinding + RuntimeBinding + Endpoint + Subscription

2. Current Source Tables

Current Ent schema still uses these legacy source tables:

Source table	Current meaning	Target
`gateways`	generic host plus ingress/egress type	`nodes`
`gateway_runtime_bindings`	runtime binding scoped to gateway	`runtime_bindings`
`ingress_endpoints`	traffic entry endpoint	`endpoints`
`client_configurations`	client-facing access profile	`subscriptions`
`client_configuration_gateways`	client config to ingress gateway link	`subscription_endpoints`
`client_protocol_credentials`	protocol credential for client config	`subscription_protocol_credentials`

3. Dependent Tables

These tables keep their identity but need target columns:

Table	Old field	Target field
`edge_runtimes`	`gateway_id`	`node_id`
`desired_states`	`gateway_id`	`node_id`
`compiled_configurations`	`gateway_id`, `binding_id`	`node_id`, `runtime_binding_id`
`health_checks`	`gateway_id`	`node_id`, optional binding IDs
`traffic_usage_samples`	`gateway_id`, `client_configuration_id`, `gateway_role`	`node_id`, `subscription_id`, `capability_binding_id`, `role`
`traffic_usage_rollups`	`gateway_id`, `client_configuration_id`	`node_id`, `subscription_id`
`quota_policies`	`scope_type = client_configuration/gateway`	`scope_type = subscription/node`
`quota_enforcements`	`scope_type = client_configuration/gateway`	`scope_type = subscription/node`

4. Role Mapping

gateways.type = ingress -> capability_bindings.role = traffic.entry
gateways.type = egress  -> capability_bindings.role = traffic.exit
gateways.type = mixed   -> creates both traffic.entry and traffic.exit

Runtime binding role mapping:

gateway_runtime_bindings.role = ingress -> runtime_bindings.role = traffic.entry
gateway_runtime_bindings.role = egress  -> runtime_bindings.role = traffic.exit

5. Decisions

Node IDs reuse existing gateway IDs to minimize downstream remapping.
Subscription IDs reuse existing client configuration IDs.
Endpoint IDs reuse existing ingress endpoint IDs.
Runtime binding IDs reuse existing gateway runtime binding IDs.
Capability binding IDs are new UUIDs because there is no existing equivalent row.
Rollups only backfill node_id and subscription_id; role-level rollups should be rebuilt after the new collector writes role-aware samples.

6. Validation

Before cutover, validation queries in the SQL draft must return zero failed rows for:

gateway to node mapping.
runtime binding to capability binding mapping.
ingress endpoint to endpoint mapping.
client configuration to subscription mapping.
subscription endpoint mapping.
usage sample node mapping.
usage sample subscription mapping.
legacy quota scope values.

7. Follow-Up Code Work

After SQL validation:

Replace Ent schema names and fields.
Regenerate Ent code.
Replace proto contracts and regenerate OpenAPI.
Update Control Plane services.
Update Edge Runtime request signing and desired-state protocol.
Update Console routes and labels.
Run Traffic MVP smoke test.