Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 18 additions & 13 deletions tools/migrate-apim/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,18 @@ Declares what the `az aigateway` CLI extension can do. Paired to one CLI release

Declares how APIM shapes map to target capabilities. Never versioned separately; versioned with the catalog it references. Contains:

- **`assets[]`** — How to map each APIM asset family (models, mcpServers, agents, modelProviders). Each rule matches on asset properties (`family`, `modelsStatus`, `surfaceStatus`, etc.) and declares:
Every rule says what it decides about in `selects`, narrows with `where` (field predicates), `derived` (predicates computed from a record rather than read off it) or `fallback` (the rule that answers when nothing above it did), and then declares the decision. A subject is a *question*, not an asset type: one model API raises six, and they are decided separately.

- **`assets[]`** — The questions asked about one asset. `modelProvider` and `modelRegistration`, `publishedSurface`, `callerDialect`, `sessionAffinity`, `modelCatalogue` and `aliasNames` for a model API, `mcpServer`, `toolExposure` and `agent` for the rest. Each declares:
- `verdict` — `native` (direct map), `partial` (decision needed), `gap` (no target), `handled` (carried elsewhere), `notApplicable` (skip it)
- `capabilityId` — Which capability in the catalog handles this
- `itemKind` — What type of plan item to raise (`reduce-surface`, `translate`, `accept-loss`, `enumerate`, `name`, `scope`, `collapse`)
- `options` — If `partial`, the choices the operator can make
- `proposal` — If `partial`, the recommended choice

- **`structural[]`** — Rules for cross-asset things (workspaces, subscriptions, telemetry, policy fragments, coverage gaps). A rule may pin a second match key where one kind resolves to several cases: `policyFragments` carries a `disposition`, because a fragment the target must dissolve is not a fragment nothing includes, and neither is an `include-fragment` naming one the inventory does not hold.
- **`structural[]`** — The questions asked about the service rather than one asset: `workspace`, `subscriptions`, `telemetry`, `certificates`, `credentialProviders`, `coverageGap`, `policyFragment`, plus `gatewayIdentity` and `backendReachability`. A rule may narrow with `where` where one subject resolves to several cases: `policyFragment` pins a `disposition`, because a fragment the target must dissolve is not a fragment nothing includes, and neither is an `include-fragment` naming one the inventory does not hold.

- **`policies[]`** — How APIM policies map to AI Gateway policies. Four passes in order: by element name, then by family, then a fallback for anything carrying a policy expression, then one terminal rule (`match: {anyElement: true}`) that answers for everything else.
- **`policies[]`** — How APIM policies map to AI Gateway policies. Every rule here `selects: policyElement`. Four passes in order: by element name (`where.name`), then by family (`where.family`), then a fallback for anything carrying a policy expression (`derived.hasExpression`), then one terminal rule (`fallback: true`) that answers for everything else.

The last pass is what makes an unmapped element impossible rather than unlikely: before it, an element matching no rule was dropped where it was classified, and the ones that vanished were those carrying *no* expression, since an expression at least reached the pass above. It is a net and not a mapping, so `compile` holds every element in `policy.FAMILIES` to a rule of its own or a family rule and fails if one is left to it. The planner counts what reaches it into `policyCoverage.unrecognised` on the plan.

Expand Down Expand Up @@ -62,13 +64,14 @@ Declares how APIM shapes map to target capabilities. Never versioned separately;
│ For each asset: │ │ For each policy: │
│ .asset_rules() │ │ .policy_rule() │
│ ↓ │ │ ↓ │
│ Match on │ │ Match on element │
│ family, │ │ ↓ │
│ modelsStatus, │ │ Get capability id │
│ surfaceStatus │ │ ↓ │
│ ↓ │ │ Build plan item │
│ Get capability │ │ │
│ from catalog │ │ │
│ selects: the │ │ selects: │
│ question asked │ │ policyElement │
│ ↓ │ │ ↓ │
│ where/derived: │ │ where: name, family │
│ which answer │ │ ↓ │
│ ↓ │ │ Get capability id │
│ Get capability │ │ ↓ │
│ from catalog │ │ Build plan item │
│ ↓ │ │ │
│ Build plan item │ │ │
│ with verdict │ │ │
Expand Down Expand Up @@ -131,13 +134,15 @@ The catalog says which release to install; nothing here reads `cli/` to find out

One question is answered in one place for the same reason. `migrate_apim/policy.py` owns which policy governs which API: the scope chain, `<base />` inheritance, fragment splicing and the workspace qualification of every name. `collect` asks it to decide what authenticates a backend and `plan` asks it to decide what a policy item covers, so the two cannot drift — which they had, the collector folding in the product and global policy but never the workspace, and the planner answering for neither a fragment nor an operation. Nothing is re-derived to answer it: `include-fragment` and `base` are already elements in the inventory, each with its section and path.

`compile` holds two invariants that keep this true rather than aspirational: every subject a site selects on has at least one rule, so a question the planner asks cannot be answered in code instead of in the file; and every `where` key names a field `inventory.schema.json` declares, so a rule cannot match on something no record carries and simply never fire. Both are checked against the registry the planner itself uses.

Reachability is checkable only because selection happens in one place. `migrate_apim/dispatch.py` defines `Selector`, which both performs a match and states what the match looks at; `plan.py` and `capability.py` declare one per selection site. `compile` imports those modules and reads `dispatch.REGISTRY`, so the contract it checks is the one the planner runs — not a second declaration that can drift from it.

A selector *governs* a rule when the rule's `match` keys are a subset of the keys that site reads, and every value it pins is one that site accepts. Subset, not equality: a rule may pin fewer keys, but pinning more means the surplus is silently ignored and the rule matches more broadly than it reads.
A selector *governs* a rule when the rule decides the subject that site selects, its `where` and `derived` keys are a subset of the ones that site examines, and every value it pins is one that site accepts. Subset, not equality: a rule may pin fewer keys, but pinning more means the surplus is silently ignored and the rule matches more broadly than it reads.

A selector also declares what it `reads`: the rule fields it consumes once it has chosen one. A field outside that union is a field somebody wrote expecting an effect it does not have — the same defect as an unreadable match key, one layer in — and it is found the same way, by asking the sites rather than by keeping a list in the checker. A list in the checker is a second declaration, and it drifted: `constraints` and `toolDiscoveryGuidance` sat unread for releases because nobody thought to add them to it.
A selector also declares what it `reads`: the rule fields it consumes once it has chosen one. A field outside that union is a field somebody wrote expecting an effect it does not have — the same defect as an unreadable `where` key, one layer in — and it is found the same way, by asking the sites rather than by keeping a list in the checker. A list in the checker is a second declaration, and it drifted: `constraints` and `toolDiscoveryGuidance` sat unread for releases because nobody thought to add them to it.

This is why the six `plan._structural` branches declare six selectors rather than one keyed on `kind`. They share a key and nothing else — each raises a different item and takes a different set of fields — and a single selector would have to declare the union, excusing a field on the workspace rule because the telemetry branch happens to read it.
This is why the six `plan._structural` branches declare six selectors rather than one, and why `callerDialect` declares two: branches that share a subject and nothing else each raise a different item and take a different set of fields, and a single selector would have to declare the union — excusing a field on the workspace rule because the telemetry branch happens to read it, or a `proposal` on the indeterminate-dialect rule that nothing reads. The declaration is only worth having while it is the narrowest true one.

Adding a selection site means declaring a selector there. A rule that no selector governs is an error, with the reason given — an unread key is a different mistake from an unknown value, and they have different fixes.

Expand Down
Loading