diff --git a/tools/migrate-apim/ARCHITECTURE.md b/tools/migrate-apim/ARCHITECTURE.md index 90aa28c..4f4fbbf 100644 --- a/tools/migrate-apim/ARCHITECTURE.md +++ b/tools/migrate-apim/ARCHITECTURE.md @@ -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. @@ -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 │ │ │ @@ -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, `` 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. diff --git a/tools/migrate-apim/capabilities/rules.json b/tools/migrate-apim/capabilities/rules.json index 5bd236c..c20bed3 100644 --- a/tools/migrate-apim/capabilities/rules.json +++ b/tools/migrate-apim/capabilities/rules.json @@ -17,8 +17,8 @@ ], "assets": [ { - "match": { - "family": "mcpServers", + "selects": "mcpServer", + "where": { "pattern": "passthrough" }, "verdict": "native", @@ -26,16 +26,16 @@ "note": "The target takes streamableHttp or sse transports, and authorizationCode for OAuth2. Nothing checks a collected server against that here: a transport or grant type outside it is a gap the apply step surfaces, not a rule this file can select on. Recorded so the limit is written down where the mapping is." }, { - "match": { - "family": "mcpServers", + "selects": "mcpServer", + "where": { "pattern": "federationRouter" }, "verdict": "native", "capabilityId": "mcp.create" }, { - "match": { - "family": "mcpServers", + "selects": "mcpServer", + "where": { "pattern": "toolProjection" }, "verdict": "partial", @@ -50,8 +50,8 @@ "rationale": "The REST contract becomes an openApi tool-server source, but APIM's per-tool policies and tool name overrides do not survive." }, { - "match": { - "family": "mcpServers", + "selects": "mcpServer", + "where": { "pattern": "unconfigured" }, "verdict": "gap", @@ -65,8 +65,8 @@ "proposal": "retain-in-apim" }, { - "match": { - "family": "mcpServers", + "selects": "mcpServer", + "where": { "toolDiscovery": "runtimeOnly" }, "verdict": "gap", @@ -89,9 +89,7 @@ "rationale": "APIM stores no tool names for a passthrough server, and the CLI cannot author allowList/blocked in this baseline regardless." }, { - "match": { - "family": "agents" - }, + "selects": "agent", "verdict": "gap", "itemKind": "accept-loss", "options": [ @@ -100,12 +98,262 @@ ], "proposal": "retain-in-apim", "rationale": "AI Gateway exposes no A2A building block. A2A is listed outside the confirmed typed-gateway surface." + }, + { + "selects": "modelProvider", + "verdict": "native", + "capabilityId": "provider.create", + "note": "A backend that speaks a model protocol registers directly as a provider. What it authenticates with travels with it; the endpoint and the protocol are the whole of the mapping. Said as a note because the item's sentence names the provider, so it is composed where the inventory is read: a `rationale` here would reach no plan." + }, + { + "selects": "publishedSurface", + "where": { + "status": "unbounded" + }, + "verdict": "partial", + "itemKind": "reduce-surface", + "capabilityId": "alias.create", + "proposal": "inference-only", + "options": [ + { + "value": "inference-only", + "consequence": "Publish the four inference routes; any other path callers use breaks." + }, + { + "value": "retain-in-apim", + "consequence": "Nothing moves for this API." + }, + { + "value": "block", + "consequence": "Stop the migration until the used routes are established." + } + ], + "blocking": true, + "rationale": "The exposed surface cannot be read from configuration." + }, + { + "selects": "publishedSurface", + "derived": { + "hasUnpublishable": true + }, + "verdict": "partial", + "itemKind": "reduce-surface", + "capabilityId": "alias.create", + "proposal": "split", + "options": [ + "split", + { + "value": "inference-only", + "consequence": "Inference moves and the rest is dropped; those callers break." + }, + { + "value": "retain-in-apim", + "consequence": "Nothing moves for this API." + }, + { + "value": "block", + "consequence": "Stop the migration until resolved." + } + ], + "blocking": true, + "note": "`split` is bare because what it costs is the number of operations that stay behind, which only this API's surface knows; the planner composes that sentence. The item's rationale is composed there too, for the same reason." + }, + { + "selects": "callerDialect", + "where": { + "status": "translating" + }, + "verdict": "partial", + "itemKind": "translate", + "capabilityId": "alias.create", + "proposal": "move-callers", + "options": [ + "move-callers", + { + "value": "retain-in-apim", + "consequence": "Keep APIM in front so callers are unchanged." + }, + { + "value": "block", + "consequence": "Stop until the caller impact is agreed." + } + ], + "blocking": true, + "rationale": "APIM is translating between the dialect callers speak and the one the backend speaks. The gateway publishes the backend's dialect, so the translation does not travel.", + "note": "`move-callers` is bare because what it costs is the dialect this backend speaks, which the planner reads off the asset. The rationale is used only when the collector left no note of its own." + }, + { + "selects": "callerDialect", + "where": { + "status": "indeterminate" + }, + "verdict": "partial", + "itemKind": "enumerate", + "capabilityId": "alias.create", + "options": [ + { + "value": "confirm-dialect", + "consequence": "State the dialect callers use." + }, + { + "value": "retain-in-apim", + "consequence": "Do not migrate this API." + } + ], + "blocking": true, + "rationale": "Which dialect callers speak could not be established from configuration, so whether the gateway can publish it is unknown rather than settled." + }, + { + "selects": "sessionAffinity", + "verdict": "gap", + "itemKind": "accept-loss", + "capabilityId": "alias.create", + "proposal": "accept-loss", + "options": [ + { + "value": "accept-loss", + "consequence": "Migrate without affinity, and configure it afterwards by hand." + }, + { + "value": "retain-in-apim", + "consequence": "Keep this API on APIM until affinity can be authored." + }, + { + "value": "block", + "consequence": "Stop the migration until it can be carried over." + } + ], + "note": "`block` is here because stopping the migration is the option an operator loses if nobody writes it down: this is a gap the target does not have, only the tooling. The item's sentence names which CLI gap it is, so it is composed in the planner rather than stated here." + }, + { + "selects": "modelCatalogue", + "derived": { + "hasCatalogue": true + }, + "verdict": "partial", + "itemKind": "enumerate", + "capabilityId": "model.create", + "proposal": "list-models", + "options": [ + "list-models", + { + "value": "retain-in-apim", + "consequence": "Do not migrate this API." + } + ], + "blocking": true, + "note": "The catalogue has been read. It lists what exists, not what each one can serve, which is why this is still a decision. `list-models` is bare and the item's rationale is composed in the planner: both name how many models came back and where from." + }, + { + "selects": "modelCatalogue", + "derived": { + "hasCatalogue": false + }, + "where": { + "discoverySource": "modelsEndpoint" + }, + "verdict": "partial", + "itemKind": "enumerate", + "capabilityId": "model.create", + "proposal": "resolve-models", + "options": [ + { + "value": "resolve-models", + "consequence": "Read the provider's catalogue with its credential." + }, + { + "value": "list-models", + "consequence": "Name the models to register." + }, + { + "value": "retain-in-apim", + "consequence": "Do not migrate this API." + } + ], + "blocking": true, + "rationale": "The model catalogue could not be resolved." + }, + { + "selects": "modelCatalogue", + "derived": { + "hasCatalogue": false + }, + "verdict": "partial", + "itemKind": "enumerate", + "capabilityId": "model.create", + "proposal": "list-models", + "options": [ + { + "value": "resolve-models", + "consequence": "Read the provider's catalogue with its credential." + }, + { + "value": "list-models", + "consequence": "Name the models to register." + }, + { + "value": "retain-in-apim", + "consequence": "Do not migrate this API." + } + ], + "blocking": true, + "rationale": "The model catalogue could not be resolved." + }, + { + "selects": "modelRegistration", + "verdict": "native", + "capabilityId": "model.create", + "note": "A model registers directly, whether it was resolved from a deployment or named in this API's catalogue decision. Which of the two it was is what the item says, so that sentence is composed in the planner." + }, + { + "selects": "aliasNames", + "verdict": "partial", + "itemKind": "name", + "capabilityId": "alias.create", + "proposal": "use-model-names", + "options": [ + { + "value": "use-model-names", + "consequence": "Publish each model under its own name." + }, + { + "value": "override", + "consequence": "Supply names per model; set them in this item's members." + } + ], + "rationale": "An alias publishes the route, and its routingName is what clients send as `model`. APIM does not store it.", + "note": "The planner follows this sentence with the names it proposes for this API's models, which is the only part of the item that is not the same for every API." + }, + { + "selects": "toolExposure", + "derived": { + "policiesBypassed": true + }, + "verdict": "partial", + "itemKind": "enumerate", + "proposal": "accept-as-listed", + "options": [ + { + "value": "accept-as-listed", + "consequence": "Federate every tool the upstream exposes." + }, + { + "value": "verify-through-gateway", + "consequence": "Re-list through APIM before deciding." + }, + { + "value": "retain-in-apim", + "consequence": "Do not migrate this server." + } + ], + "note": "The tool list came from the upstream with the API's policies bypassed, so it can be broader than what callers reach through the gateway. The item says how many tools that was, so its sentence is composed in the planner." } ], "policies": [ { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "azure-openai-token-limit", "llm-token-limit" ] @@ -132,8 +380,9 @@ ] }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "ip-filter" ] }, @@ -145,8 +394,9 @@ ] }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "authentication-managed-identity" ] }, @@ -156,8 +406,9 @@ "rationale": "Becomes provider authentication configuration. Carried by the model provider item rather than raised again here." }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "rate-limit-by-key", "rate-limit" ] @@ -179,8 +430,9 @@ ] }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "azure-openai-emit-token-metric", "llm-emit-token-metric" ] @@ -196,8 +448,9 @@ "rationale": "Token metrics are emitted by the gateway, but custom dimensions do not carry over one for one. Where the telemetry goes is a separate decision, on the telemetry destination item." }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "validate-jwt", "validate-azure-ad-token" ] @@ -217,8 +470,9 @@ "batchOn": [] }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "quota", "quota-by-key", "limit-concurrency" @@ -230,8 +484,9 @@ "proposal": "retain-in-apim" }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "azure-openai-semantic-cache-lookup", "azure-openai-semantic-cache-store", "llm-semantic-cache-lookup", @@ -248,8 +503,9 @@ "proposal": "accept" }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "azure-openai-content-safety", "llm-content-safety" ] @@ -260,7 +516,8 @@ "proposal": "retain-in-apim" }, { - "match": { + "selects": "policyElement", + "where": { "family": "transform" }, "verdict": "gap", @@ -269,7 +526,8 @@ "proposal": "accept" }, { - "match": { + "selects": "policyElement", + "where": { "family": "validation" }, "verdict": "gap", @@ -278,7 +536,8 @@ "proposal": "retain-in-apim" }, { - "match": { + "selects": "policyElement", + "where": { "family": "backendAuthentication" }, "verdict": "gap", @@ -287,7 +546,8 @@ "proposal": "retain-in-apim" }, { - "match": { + "selects": "policyElement", + "where": { "family": "authentication" }, "verdict": "gap", @@ -296,7 +556,8 @@ "proposal": "retain-in-apim" }, { - "match": { + "selects": "policyElement", + "where": { "family": "observability" }, "verdict": "gap", @@ -305,8 +566,9 @@ "proposal": "accept" }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "mcp-server" ] }, @@ -315,7 +577,8 @@ "rationale": "The tool server this policy exposes is collected as an MCP asset from the API that carries it, and registered by the MCP server item rather than raised again here." }, { - "match": { + "selects": "policyElement", + "where": { "family": "mcp" }, "verdict": "gap", @@ -324,7 +587,8 @@ "proposal": "retain-in-apim" }, { - "match": { + "selects": "policyElement", + "where": { "family": "routing" }, "verdict": "gap", @@ -333,8 +597,9 @@ "proposal": "retain-in-apim" }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "send-request", "send-one-way-request", "return-response", @@ -347,8 +612,9 @@ "proposal": "accept" }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "set-backend-service", "forward-request" ] @@ -381,8 +647,9 @@ } }, { - "match": { - "element": [ + "selects": "policyElement", + "where": { + "name": [ "base", "include-fragment", "choose", @@ -398,7 +665,8 @@ "rationale": "Composition, control flow, and gateway plumbing with no target object." }, { - "match": { + "selects": "policyElement", + "derived": { "hasExpression": true }, "verdict": "gap", @@ -408,9 +676,8 @@ "proposal": "retain-in-apim" }, { - "match": { - "anyElement": true - }, + "selects": "policyElement", + "fallback": true, "verdict": "gap", "itemKind": "accept-loss", "note": "Last of the four passes in capability.policy_rule, and the one that makes an unmapped element impossible rather than merely unlikely. `compile` holds every element in policy.FAMILIES to a rule of its own or a family rule, so nothing reaching here is a policy the tool has ever been taught; it is a policy APIM has that this catalog does not know about. Deliberately blocking: the alternative is a migration that silently drops a policy nobody has read.", @@ -420,9 +687,7 @@ ], "structural": [ { - "match": { - "kind": "workspace" - }, + "selects": "workspace", "note": "Selection is by kind alone. The default workspace is skipped by the planner before this rule is consulted, so a name condition here would be read by nobody.", "verdict": "partial", "itemKind": "collapse", @@ -435,9 +700,7 @@ "rationale": "AI Gateway configures the implicit default workspace only. Flattening can collide with same-named assets in other workspaces." }, { - "match": { - "kind": "subscriptions" - }, + "selects": "subscriptions", "verdict": "partial", "itemKind": "scope", "options": [ @@ -449,34 +712,30 @@ "rationale": "APIM subscription keys are scoped per product, per API, or service-wide. AI Gateway keys are gateway-wide and no key value can be imported, so every caller is re-keyed." }, { - "match": { - "kind": "certificates" - }, + "selects": "certificates", "verdict": "gap", "itemKind": "accept-loss", "rationale": "APIM does not export a certificate private key. Client certificates are re-provisioning work, not migration work.", "proposal": "accept" }, { - "match": { - "kind": "credentialProviders" - }, + "selects": "credentialProviders", "verdict": "gap", "itemKind": "accept-loss", "rationale": "Credential-manager connections are never exported. The equivalent tool-server OAuth connection is re-authorized interactively.", "proposal": "accept" }, { - "match": { - "kind": "policyFragments", + "selects": "policyFragment", + "where": { "disposition": "dissolved" }, "verdict": "handled", "rationale": "AI Gateway has no policy composition: no fragments, no includes, no inheritance. A fragment is therefore dissolved into every scope that includes it, and what it carries is assessed as the elements of that scope. Listed so a reader can see the fragment reached the plan rather than having to infer it from the policies it contributed." }, { - "match": { - "kind": "policyFragments", + "selects": "policyFragment", + "where": { "disposition": "conditional" }, "verdict": "partial", @@ -499,8 +758,8 @@ "rationale": "A `choose` branch at the include site decides whether this fragment runs at all, and dissolving it into the including scope keeps what it carries and not the condition on it. The target has nowhere to put the branch: its policy surface is six declarative types with no predicate." }, { - "match": { - "kind": "policyFragments", + "selects": "policyFragment", + "where": { "disposition": "splitSection" }, "verdict": "partial", @@ -523,16 +782,16 @@ "rationale": "The same fragment is included into more than one section, so what it does depends on where it was pulled in -- a check on the way in is not the same check on the way out. One dissolution cannot be both." }, { - "match": { - "kind": "policyFragments", + "selects": "policyFragment", + "where": { "disposition": "unreferenced" }, "verdict": "notApplicable", "rationale": "Nothing includes this fragment, so it governs no traffic and there is nothing to dissolve it into. Reported rather than dropped: a fragment that governs nothing and a fragment nobody looked for are the same silence, and operation policies are not collected unless asked for." }, { - "match": { - "kind": "policyFragments", + "selects": "policyFragment", + "where": { "disposition": "unresolved" }, "verdict": "gap", @@ -552,9 +811,7 @@ "rationale": "A policy includes a fragment this inventory does not hold, so what runs at that point is unknown rather than absent. It cannot be accepted as a loss: nobody has read it, so nobody can say what accepting it costs." }, { - "match": { - "kind": "coverageGap" - }, + "selects": "coverageGap", "verdict": "gap", "itemKind": "enumerate", "blocking": true, @@ -572,9 +829,7 @@ "rationale": "A control-plane read failed, so this is unknown rather than absent. Unknown coverage cannot be accepted as an acceptable loss." }, { - "match": { - "kind": "telemetry" - }, + "selects": "telemetry", "verdict": "partial", "itemKind": "translate", "capabilityId": "telemetry.create", @@ -603,6 +858,96 @@ "reuse-appinsights", "new-appinsights" ] + }, + { + "selects": "gatewayIdentity", + "derived": { + "hasUserAssigned": true + }, + "verdict": "partial", + "itemKind": "translate", + "capabilityId": "identity.assign", + "options": [ + { + "value": "system-assigned", + "consequence": "A new principal; every backend grant has to be made against it." + } + ], + "proposal": "system-assigned", + "note": "The source authenticates to its backends as a user-assigned identity, and the gateway can carry the same one or take a system-assigned identity of its own; the grants differ. `system-assigned` is the choice that exists whether or not the source carries any, so it is stated here; the reuse options are one per identity it does carry, so they are built where the inventory is read. The item's sentence counts the providers that need one, so it is composed there too." + }, + { + "selects": "gatewayIdentity", + "derived": { + "hasUserAssigned": false + }, + "verdict": "native", + "capabilityId": "identity.assign", + "proposal": "system-assigned", + "note": "A system-assigned identity is created with the gateway and granted on each provider. Nothing is offered because there is nothing to choose between: the verdict is what says so, rather than a planner branch emitting an empty option list." + }, + { + "selects": "backendReachability", + "where": { + "needsSubnet": true + }, + "verdict": "partial", + "itemKind": "translate", + "capabilityId": "network.update", + "proposal": "new-delegated-subnet", + "options": [ + { + "value": "new-delegated-subnet", + "consequence": "Provision a subnet delegated to Microsoft.App/environments and integrate the gateway." + }, + { + "value": "public-egress", + "consequence": "Reach backends over public networking; only viable if they accept it." + }, + { + "value": "retain-in-apim", + "consequence": "Keep workloads that need private backends on APIM." + }, + { + "value": "block", + "consequence": "Stop until the network design is agreed." + } + ], + "rationale": "Backends are reachable only over private networking, which the gateway joins differently from APIM." + }, + { + "selects": "backendReachability", + "where": { + "needsSubnet": false + }, + "verdict": "partial", + "itemKind": "translate", + "capabilityId": "network.update", + "proposal": "private-ingress", + "options": [ + { + "value": "private-ingress", + "consequence": "Expose the gateway privately, matching the source's ingress." + }, + { + "value": "new-delegated-subnet", + "consequence": "Provision a subnet delegated to Microsoft.App/environments and integrate the gateway." + }, + { + "value": "public-egress", + "consequence": "Reach backends over public networking; only viable if they accept it." + }, + { + "value": "retain-in-apim", + "consequence": "Keep workloads that need private backends on APIM." + }, + { + "value": "block", + "consequence": "Stop until the network design is agreed." + } + ], + "rationale": "The source restricts how it is reached, and the gateway expresses that differently.", + "note": "`private-ingress` is the proposal and was not among the options while this decision lived in `plan.py`: both cases were offered the subnet list, so the recommended value was one nobody could settle on. It is offered here, and the other four are kept, because which of them an operator can live with is theirs to say." } ] } diff --git a/tools/migrate-apim/migrate_apim/capability.py b/tools/migrate-apim/migrate_apim/capability.py index 71f8d23..749a8ac 100644 --- a/tools/migrate-apim/migrate_apim/capability.py +++ b/tools/migrate-apim/migrate_apim/capability.py @@ -36,16 +36,18 @@ "options", "partial", "partialWhen", "batchOn", ) POLICY_BY_ELEMENT = selector( - "policies", keys=("element",), site="capability.policy_rule element", - reads=_POLICY_FIELDS, + "policies", selects="policyElement", keys=("name",), + fields={"name": "policies[].elements[].name"}, + site="capability.policy_rule element", reads=_POLICY_FIELDS, ) POLICY_BY_FAMILY = selector( - "policies", keys=("family",), site="capability.policy_rule family", - reads=_POLICY_FIELDS, + "policies", selects="policyElement", keys=("family",), + fields={"family": "policies[].elements[].family"}, + site="capability.policy_rule family", reads=_POLICY_FIELDS, ) POLICY_BY_EXPRESSION = selector( - "policies", keys=("hasExpression",), site="capability.policy_rule expression", - reads=_POLICY_FIELDS, + "policies", selects="policyElement", derived=("hasExpression",), + site="capability.policy_rule expression", reads=_POLICY_FIELDS, ) # The pass that makes "no rule" unreachable. Everything above it answers some # part of APIM's policy vocabulary; this answers the rest, including whatever @@ -55,7 +57,7 @@ # an expression at least fell into the pass above. The simpler the policy, the # more completely it vanished. POLICY_TERMINAL = selector( - "policies", keys=("anyElement",), values={"anyElement": (True,)}, + "policies", selects="policyElement", fallback=True, site="capability.policy_rule terminal", reads=_POLICY_FIELDS, ) @@ -72,20 +74,20 @@ def resolve_policy_rule( for rule in rules: if not POLICY_BY_ELEMENT.governs(rule): continue - names = (rule.get("match") or {}).get("element") + names = (rule.get("where") or {}).get("name") if names and element_name in names: return rule for rule in rules: if not POLICY_BY_FAMILY.governs(rule): continue - match = rule.get("match") or {} - if match.get("family") and match["family"] == family: + where = rule.get("where") or {} + if where.get("family") and where["family"] == family: return rule if has_expression: for rule in rules: if not POLICY_BY_EXPRESSION.governs(rule): continue - if (rule.get("match") or {}).get("hasExpression"): + if (rule.get("derived") or {}).get("hasExpression"): return rule for rule in rules: if POLICY_TERMINAL.governs(rule): diff --git a/tools/migrate-apim/migrate_apim/compile.py b/tools/migrate-apim/migrate_apim/compile.py index a55ef58..61f19c0 100644 --- a/tools/migrate-apim/migrate_apim/compile.py +++ b/tools/migrate-apim/migrate_apim/compile.py @@ -335,8 +335,7 @@ def check_rules(catalog: dict[str, Any], rules: dict[str, Any], out: Compilation for section in _SELECTED_SECTIONS: for rule in rules.get(section) or []: - match = rule.get("match") or {} - label = f"{section} {json.dumps(match, sort_keys=True)}" + label = f"{section} {_rule_label(rule)}" governing = dispatch.governing(rule, section) if not governing: @@ -395,23 +394,40 @@ def _option_values(options: list[Any]) -> list[str]: return [o["value"] if isinstance(o, dict) else o for o in options if o] + +def _rule_label(rule: dict[str, Any]) -> str: + """A rule named by how it is selected, for a diagnostic to point at.""" + shown = {k: v for k, v in rule.items() + if k in ("selects", "where", "derived", "fallback")} + return json.dumps(shown, sort_keys=True) + + def _explain_unreachable(rule: dict[str, Any], section: str, label: str, out: Compilation) -> None: """Say *why* nothing can choose this rule, not merely that nothing can. - "No site selects this" is true of a bogus match value and of an invented - match key alike, and the fix is different. A rule whose keys a site does - read, but whose value it never compares against, is a vocabulary problem; - a rule naming a key no site reads at all is a different mistake. + "No site selects this" is true of a subject nothing decides about, of a + bogus `where` value, and of an invented `where` key alike, and the fix is + different each time. A rule whose keys a site does read but whose value it + never compares against is a vocabulary problem; a rule naming a key no site + reads is a different mistake; and a rule naming a subject no site has is the + one this check gained when subjects became explicit. """ - match = rule.get("match") or {} - sites = [s for s in dispatch.REGISTRY if s.section == section] - key_compatible = [s for s in sites if not set(match) - set(s.keys)] + where = rule.get("where") or {} + sites = [s for s in dispatch.REGISTRY if s.selects == rule.get("selects")] + if not sites: + out.error( + "rule-reachable", + f"{label}: selects {rule.get('selects')!r}, which no selection site decides about. " + f"Known subjects: {', '.join(sorted({s.selects for s in dispatch.REGISTRY}))}.", + ) + return + key_compatible = [s for s in sites if not set(where) - set(s.keys)] if key_compatible: for selector in key_compatible: for key, permitted in selector.values.items(): - value = match.get(key) - if key in match and permitted and value not in permitted: + value = where.get(key) + if key in where and permitted and value not in permitted: out.error( "match-value-known", f"{label}: {selector.site} never compares {key} against {value!r}; " @@ -420,11 +436,11 @@ def _explain_unreachable(rule: dict[str, Any], section: str, label: str, out: Co return readable = sorted({key for selector in sites for key in selector.keys}) - unknown = sorted(set(match) - set(readable)) + unknown = sorted(set(where) - set(readable)) detail = ( - f"it matches on {unknown}, which no {section} selection site reads" + f"it matches on {unknown}, which no site deciding {rule.get('selects')!r} reads" if unknown - else f"no site reads this combination of keys {sorted(match)}" + else f"no site reads this combination of keys {sorted(where)}" ) out.error( "rule-reachable", @@ -451,10 +467,9 @@ def check_fragment_dispositions(rules: dict[str, Any], out: Compilation) -> None ) seen: set[str] = set() for rule in structural: - match = rule.get("match") or {} - if match.get("kind") != "policyFragments": + if rule.get("selects") != "policyFragment": continue - disposition = match.get("disposition") + disposition = (rule.get("where") or {}).get("disposition") if disposition is None: out.error( "fragment-disposition", @@ -516,6 +531,100 @@ def check_policy_vocabulary(rules: dict[str, Any], out: Compilation) -> None: ) +def _inventory_schema() -> dict[str, Any]: + path = Path(__file__).resolve().parent.parent / "schemas" / "inventory.schema.json" + return json.loads(path.read_text(encoding="utf-8")) + + +def check_subjects_have_rules(rules: dict[str, Any], out: Compilation) -> None: + """Every subject a site selects on has at least one rule answering it. + + This is what keeps the decisions in the file. A subject with no rule is a + question the planner asks and the data does not answer -- which is how ten + of them came to be written in `plan.py` while `ARCHITECTURE.md` described + them as data. Declaring a site without writing its rule now fails the + build, so the gap cannot be reopened quietly. + + The other direction is already covered: a rule no site selects is caught by + `check_rules`. + """ + subjects = {site.selects for site in dispatch.REGISTRY} + answered = { + rule.get("selects") + for section in _SELECTED_SECTIONS + for rule in rules.get(section) or [] + } + out.cover(f"{len(subjects)} subjects the planner decides: each answered by at least one rule") + for subject in sorted(subjects - answered): + site_names = [s.site for s in dispatch.REGISTRY if s.selects == subject] + out.error( + "subject-has-rule", + f"{subject!r} is decided at {site_names} and no rule answers for it, so the " + "decision is either hardcoded or absent. Write the rule.", + ) + + +def check_where_keys_are_fields(rules: dict[str, Any], inventory_schema: dict[str, Any], + out: Compilation) -> None: + """Every `where` key names a field some inventory record actually has. + + The binding between a key and the field it is compared against used to live + inside the resolver, so a rule could match on a field no record carries and + simply never fire -- the failure `rule-reachable` cannot see, because the + key is one a site does read. Each site declares the path; this checks the + path against the schema, the way `check_capabilities` checks a declared CLI + option against the surface snapshot. + """ + declared = _schema_paths(inventory_schema) + checked = sum(len(site.fields) for site in dispatch.REGISTRY) + out.cover(f"{checked} where-key field paths: each declared in inventory.schema.json") + for site in dispatch.REGISTRY: + for key, path in (site.fields or {}).items(): + if _path_declared(path, declared): + continue + out.error( + "where-key-field", + f"{site.site}: {key!r} reads {path!r}, which inventory.schema.json does not " + "declare. Either the path is wrong or the schema has drifted from the collector.", + ) + + +def _schema_paths(schema: dict[str, Any]) -> set[str]: + """Every dotted property path the inventory schema declares.""" + defs = schema.get("$defs") or {} + + def walk(node: Any, seen: tuple[str, ...]) -> set[str]: + found: set[str] = set() + if not isinstance(node, dict): + return found + if "$ref" in node: + name = node["$ref"].rsplit("/", 1)[-1] + return set() if name in seen else walk(defs.get(name, {}), (*seen, name)) + for key, sub in (node.get("properties") or {}).items(): + found.add(key) + found.update(f"{key}.{nested}" for nested in walk(sub, seen)) + if "items" in node: + found |= walk(node["items"], seen) + for combinator in ("oneOf", "anyOf", "allOf"): + for sub in node.get(combinator) or []: + found |= walk(sub, seen) + return found + + return walk(schema, ()) + + +def _path_declared(path: str, declared: set[str]) -> bool: + """Whether the whole path exists, ignoring the `[]` that mark arrays. + + Whole, not its tail: `_schema_paths` resolves `$ref`s, so every shape is + reachable by its full route from the root. Accepting a suffix would pass + `assets.models[].endpoints.surface.status` on the strength of some other + record having a `surface.status`, which is the drift this check exists to + find rather than something to tolerate. + """ + return path.replace("[]", "") in declared + + def _check_uniqueness(rules: dict[str, Any], out: Compilation) -> None: """Selection is first-match or last-write; either way a tie is a silent bug. @@ -531,25 +640,36 @@ def _check_uniqueness(rules: dict[str, Any], out: Compilation) -> None: for rule in rules.get(section) or []: if not selector.governs(rule): continue - match = rule.get("match") or {} - # A match value may itself be a list of alternatives -- a policy - # rule naming several elements. Each alternative is its own way - # to reach the rule, so each is its own chance of a tie. - for key in _match_keys(match, selector.keys): + where = rule.get("where") or {} + # A `where` value may itself be a list of alternatives -- a + # policy rule naming several elements. Each alternative is its + # own way to reach the rule, so each is its own chance of a tie. + # + # Derived predicates count too. Two rules alike in `where` and + # differing only in what is computed are two answers, and + # judging the tie on `where` alone called them one. + for key in _where_keys( + {**where, **(rule.get("derived") or {})}, + (*selector.keys, *selector.derived), + ): if key in seen: out.error( "rule-unique", f"{section}: {selector.site} cannot tell two rules apart on " - f"{dict(zip(selector.keys, key))}; only one of them is ever used", + # Named over both blocks, because a tie the site can + # only see once `derived` is included reads as a tie + # on nothing at all when the message omits it. + f"{dict(zip((*selector.keys, *selector.derived), key))}; " + "only one of them is ever used", ) seen.add(key) -def _match_keys(match: dict[str, Any], keys: tuple[str, ...]) -> list[tuple]: +def _where_keys(where: dict[str, Any], keys: tuple[str, ...]) -> list[tuple]: """Every distinct way a site keyed on `keys` can arrive at this rule.""" combinations: list[tuple] = [()] for name in keys: - value = match.get(name) + value = where.get(name) alternatives = value if isinstance(value, list) else [value] combinations = [(*prefix, alt) for prefix in combinations for alt in alternatives] return combinations @@ -565,10 +685,9 @@ def _check_required_fields(rules: dict[str, Any], out: Compilation) -> None: for section in _SELECTED_SECTIONS: for rule in rules.get(section) or []: if "verdict" not in rule: - match = json.dumps(rule.get("match") or {}, sort_keys=True) out.error( "rule-has-verdict", - f"{section} {match}: has no verdict, which decides the item's status", + f"{section} {_rule_label(rule)}: has no verdict, which decides the item's status", ) @@ -672,6 +791,8 @@ def compile_contract( check_rules(catalog, rules, out) check_policy_vocabulary(rules, out) check_fragment_dispositions(rules, out) + check_subjects_have_rules(rules, out) + check_where_keys_are_fields(rules, _inventory_schema(), out) if newest_release: check_release_pin(catalog, newest_release, out) return out diff --git a/tools/migrate-apim/migrate_apim/dispatch.py b/tools/migrate-apim/migrate_apim/dispatch.py index bab1589..cf2365c 100644 --- a/tools/migrate-apim/migrate_apim/dispatch.py +++ b/tools/migrate-apim/migrate_apim/dispatch.py @@ -3,7 +3,7 @@ `rules.json` is only worth maintaining if the planner reads what it says. Three things can go wrong quietly, and all three had: -* a rule names a `match` key no selector examines, so it is never chosen; +* a rule names a `where` key no selector examines, so it is never chosen; * a rule carries an extra key the selector ignores, so it matches more broadly than it reads; * a rule names a value no asset ever carries, so it matches nothing. @@ -18,21 +18,24 @@ so the contract it checks is the one the planner actually runs; there is no second copy to fall out of step. -A selector `governs` a rule when the rule's `match` keys are a subset of the -keys the selector examines, and every value it constrains is one the selector -accepts. Subset rather than equality: a rule may legitimately pin fewer keys. -What it may not do is pin *more*, because the surplus would be silently ignored. +A selector `governs` a rule when the rule decides the subject the selector +selects, its `where` and `derived` keys are a subset of the ones the selector +examines, and every value it constrains is one the selector accepts. Subset +rather than equality: a rule may legitimately pin fewer keys. What it may not +do is pin *more*, because the surplus would be silently ignored. A fourth thing can go wrong, one layer in: the rule is selected, and then a -*field* of it is never looked at. That is the same defect as an unreadable match -key -- something written expecting an effect it does not have -- so it is -answered the same way. A selector also declares what it `reads`, and the site -that reads a field is the site that declares it. +*field* of it is never looked at. That is the same defect as an unreadable +`where` key -- something written expecting an effect it does not have -- so it +is answered the same way. A selector also declares what it `reads`, and the site +that reads a field is the site that declares it. The declaration is worth no +more than its narrowness: a site that claims to read `options` while writing its +own list satisfies the check and keeps the decision in the code. """ from __future__ import annotations -from dataclasses import dataclass +from dataclasses import dataclass, field from typing import Any, Mapping # Every selection site in the planner, in declaration order. Populated at import @@ -44,9 +47,9 @@ # Keys every rule carries that are not a field of the rule's own vocabulary: -# `match` is the selection criteria, and `note` is addressed to whoever reads the -# file. Neither is expected to be consumed by a selection site. -STRUCTURAL_KEYS = ("match", "note") +# the four that say how the rule is selected, and `note`, which is addressed to +# whoever reads the file. None is expected to be consumed by a selection site. +STRUCTURAL_KEYS = ("selects", "where", "derived", "fallback", "note") # Hashing is off because `values` is a Mapping, so the hash a frozen dataclass @@ -60,8 +63,21 @@ class Selector: section: str """Which top-level list of rules.json this reads: assets, structural, policies.""" + selects: str + """The subject this site decides about: `policyElement`, `mcpServer`, `workspace`. + + A rule's subject used to be implied by which array it sat in, which made + `family` name the subject in `assets[]` (`mcpServers`) and act as a + predicate on a field in `policies[]` (`authentication`). Naming the subject + lets `family` keep only the second job. + """ + keys: tuple[str, ...] - """The `match` keys this site examines. Anything else on a rule is ignored.""" + """The `where` keys this site examines. Anything else on a rule is ignored. + + Field predicates only. Each names a field of the subject's inventory record, + which is what lets `compile` check it against the schema. + """ values: Mapping[str, tuple[str, ...]] """Accepted literals per key. A key absent here, or mapped to (), is unconstrained.""" @@ -79,23 +95,61 @@ class Selector: where the reading happens rather than in the checker. """ + derived: tuple[str, ...] = () + """Predicates computed from the record rather than read off it. + + `hasExpression` is `bool(element["expressionIds"])`. No record carries it, + so holding it to the same schema check as a `where` key would reject it. + """ + + fallback: bool = False + """Whether this site chooses the rule that answers when nothing else did. + + A fallback is not a predicate, and writing it as one -- `anyElement: true` -- + made it look like a field of the subject. A site either selects fallbacks or + it does not, and the two never choose each other's rules. + """ + + fields: Mapping[str, str] = field(default_factory=dict) + """Per `where` key, the inventory path it is compared against. + + The binding between `where.name` and `element["name"]` lived only inside the + resolver, so a rule could match on a field no record has and simply never + fire. Declared here, `compile` checks it the way it already checks a + declared CLI option against the surface snapshot. + """ + def governs(self, rule: Rule) -> bool: """Whether this site could ever choose `rule`.""" - match = rule.get("match") or {} - if set(match) - set(self.keys): + if rule.get("selects") != self.selects: + return False + if bool(rule.get("fallback")) != self.fallback: + return False + where = rule.get("where") or {} + if set(where) - set(self.keys): return False for key, permitted in self.values.items(): - if key in match and permitted and match[key] not in permitted: + if key in where and permitted and where[key] not in permitted: return False + if set(rule.get("derived") or {}) - set(self.derived): + return False return True def first(self, rules: list[Rule], **criteria: Any) -> Rule | None: - """The first governed rule whose match equals `criteria`. First wins.""" + """The first governed rule whose predicates equal `criteria`. First wins. + + A criterion is looked up in whichever block declares it, so a caller + asks the same way whether the predicate is read off the record or + computed from it. The two vocabularies are disjoint by construction -- + a key is declared in `keys` or in `derived`, never both. + """ for rule in rules: if not self.governs(rule): continue - match = rule.get("match") or {} - if all(match.get(key) == value for key, value in criteria.items()): + where = rule.get("where") or {} + derived = rule.get("derived") or {} + if all((where if key in self.keys else derived).get(key) == value + for key, value in criteria.items()): return rule return None @@ -106,7 +160,7 @@ def index(self, rules: list[Rule], key: str) -> dict[str, Rule]: `compile` requires the key to be unique across the section. """ return { - (rule.get("match") or {}).get(key) or "": rule + (rule.get("where") or {}).get(key) or "": rule for rule in rules if self.governs(rule) } @@ -115,14 +169,19 @@ def index(self, rules: list[Rule], key: str) -> dict[str, Rule]: def selector( section: str, *, - keys: tuple[str, ...], + selects: str, site: str, + keys: tuple[str, ...] = (), values: Mapping[str, tuple[str, ...]] | None = None, reads: tuple[str, ...] = (), + derived: tuple[str, ...] = (), + fallback: bool = False, + fields: Mapping[str, str] | None = None, ) -> Selector: """Declare a selection site and register it.""" entry = Selector( - section=section, keys=keys, values=values or {}, site=site, reads=reads, + section=section, selects=selects, keys=keys, values=values or {}, site=site, + reads=reads, derived=derived, fallback=fallback, fields=fields or {}, ) REGISTRY.append(entry) return entry diff --git a/tools/migrate-apim/migrate_apim/plan.py b/tools/migrate-apim/migrate_apim/plan.py index aa11c79..82bceab 100644 --- a/tools/migrate-apim/migrate_apim/plan.py +++ b/tools/migrate-apim/migrate_apim/plan.py @@ -33,32 +33,105 @@ # list somewhere else. MCP_BY_PATTERN = selector( "assets", - keys=("family", "pattern"), - values={"family": ("mcpServers",), "pattern": MCP_PATTERNS}, + selects="mcpServer", + keys=("pattern",), + values={"pattern": MCP_PATTERNS}, + fields={"pattern": "assets.mcpServers[].pattern"}, site="plan._mcp", reads=("verdict", "itemKind", "capabilityId", "proposal", "rationale", "options"), ) MCP_BY_TOOL_DISCOVERY = selector( "assets", - keys=("family", "toolDiscovery"), - values={"family": ("mcpServers",), "toolDiscovery": ("runtimeOnly",)}, + selects="mcpServer", + keys=("toolDiscovery",), + values={"toolDiscovery": ("runtimeOnly",)}, + fields={"toolDiscovery": "assets.mcpServers[].toolDiscovery"}, site="plan._mcp tool exposure", reads=("verdict", "itemKind", "proposal", "rationale", "options"), ) AGENT_RULE = selector( - "assets", keys=("family",), values={"family": ("agents",)}, site="plan._agent", + "assets", selects="agent", site="plan._agent", reads=("verdict", "itemKind", "proposal", "rationale", "options"), ) +# The decisions that used to be written here rather than in the file. Each is a +# question the planner asks about one asset, which is the same shape the +# structural sites already have: a subject is a question, and `where` narrows +# which answer applies. `ARCHITECTURE.md` has described `assets[]` as covering +# models and modelProviders since before any of it existed -- the rules it named +# (`modelsStatus`, `surfaceStatus`) appeared nowhere but the suite's example of +# a rule nothing selects. +# +# Each declares only the fields its own branch takes off the rule. A shared list +# would have excused the ones it does not: `options` on a rule whose site writes +# its own, `rationale` on one whose sentence is always composed from the asset. +# Both were there, and `rule-field-unread` could not see either. +PROVIDER_RULE = selector( + "assets", selects="modelProvider", site="plan._provider", + reads=("verdict", "itemKind", "capabilityId"), +) +SURFACE_BY_STATUS = selector( + "assets", selects="publishedSurface", keys=("status",), + values={"status": ("unbounded",)}, + fields={"status": "assets.models[].endpoints.surface.status"}, + site="plan._model surface", + reads=("verdict", "itemKind", "capabilityId", "proposal", "rationale", "options", "blocking"), +) +SURFACE_PARTIALLY_PUBLISHABLE = selector( + "assets", selects="publishedSurface", derived=("hasUnpublishable",), + site="plan._model surface partial", + reads=("verdict", "itemKind", "capabilityId", "proposal", "options", "blocking"), +) +# Two cases, two sites: the indeterminate one proposes nothing, and one selector +# for both would have excused a `proposal` on it that the planner never reads. +DIALECT_TRANSLATING = selector( + "assets", selects="callerDialect", keys=("status",), + values={"status": ("translating",)}, + fields={"status": "assets.models[].endpoints.translation.status"}, + site="plan._model dialect translating", + reads=("verdict", "itemKind", "capabilityId", "proposal", "rationale", "options", "blocking"), +) +DIALECT_INDETERMINATE = selector( + "assets", selects="callerDialect", keys=("status",), + values={"status": ("indeterminate",)}, + fields={"status": "assets.models[].endpoints.translation.status"}, + site="plan._model dialect indeterminate", + reads=("verdict", "itemKind", "capabilityId", "rationale", "options", "blocking"), +) +SESSION_AFFINITY_RULE = selector( + "assets", selects="sessionAffinity", site="plan._pool_affinity", + reads=("verdict", "itemKind", "capabilityId", "proposal", "options"), +) +CATALOGUE_RULE = selector( + "assets", selects="modelCatalogue", keys=("discoverySource",), + values={"discoverySource": ("modelsEndpoint",)}, + derived=("hasCatalogue",), + fields={"discoverySource": "assets.models[].models.discoverySource"}, + site="plan._enumerate_models", + reads=("verdict", "itemKind", "capabilityId", "proposal", "rationale", "options", "blocking"), +) +MODEL_REGISTRATION_RULE = selector( + "assets", selects="modelRegistration", site="plan._model_registration", + reads=("verdict", "itemKind", "capabilityId"), +) +ALIAS_NAMES_RULE = selector( + "assets", selects="aliasNames", site="plan._alias_naming", + reads=("verdict", "itemKind", "capabilityId", "proposal", "rationale", "options"), +) +TOOL_EXPOSURE_BYPASSED = selector( + "assets", selects="toolExposure", derived=("policiesBypassed",), + site="plan._mcp tool exposure bypassed", + reads=("verdict", "itemKind", "proposal", "options"), +) + # `_structural` is six branches, not one. They share a key and nothing else: # each raises a different item and takes a different set of fields off its rule. # One selector for all six would have to declare the union of what they read, # which would excuse a field on the workspace rule because the telemetry branch # happens to read it. So each branch declares its own. -def _structural_selector(kind: str, *, reads: tuple[str, ...]) -> Any: +def _structural_selector(subject: str, *, reads: tuple[str, ...]) -> Any: return selector( - "structural", keys=("kind",), values={"kind": (kind,)}, - site=f"plan._structural {kind}", reads=reads, + "structural", selects=subject, site=f"plan._structural {subject}", reads=reads, ) @@ -78,14 +151,26 @@ def _structural_selector(kind: str, *, reads: tuple[str, ...]) -> Any: "coverageGap", reads=("verdict", "itemKind", "rationale", "options", "blocking", "cannotAccept"), ) +IDENTITY_RULE = selector( + "structural", selects="gatewayIdentity", derived=("hasUserAssigned",), + site="plan._identity", + reads=("verdict", "itemKind", "capabilityId", "proposal", "options"), +) +REACHABILITY_BY_SUBNET = selector( + "structural", selects="backendReachability", keys=("needsSubnet",), + values={"needsSubnet": (True, False)}, + fields={"needsSubnet": "service.networking.targetRequirement.needsSubnet"}, + site="plan._structural backendReachability", reads=(*_DECIDED, "capabilityId"), +) + # One kind, five cases, so this site dispatches on a second key. The gateway has # no policy composition at all -- no fragments, no includes, no inheritance -- so # every fragment has the same fate, dissolved into whatever includes it, and # what varies is only whether the dissolution can keep what the fragment meant. FRAGMENT_DISPOSITIONS = ("dissolved", "conditional", "splitSection", "unreferenced", "unresolved") STRUCTURAL_POLICY_FRAGMENTS = selector( - "structural", keys=("kind", "disposition"), - values={"kind": ("policyFragments",), "disposition": FRAGMENT_DISPOSITIONS}, + "structural", selects="policyFragment", keys=("disposition",), + values={"disposition": FRAGMENT_DISPOSITIONS}, site="plan._policy_fragments", reads=(*_DECIDED, "blocking", "cannotAccept"), ) @@ -376,22 +461,26 @@ def _identity(self) -> None: return identity = (self.inventory.get("service") or {}).get("identity") or {} assigned = identity.get("userAssignedIdentities") or [] - options = [ - _opt("system-assigned", - "A new principal; every backend grant has to be made against it."), - ] + rule = IDENTITY_RULE.first( + self.caps.structural_rules(), hasUserAssigned=bool(assigned) + ) or {} + # Taking a new principal is the choice that exists either way, so the + # rule states it; reusing one is an option per identity this source + # carries, which only the inventory can enumerate. + options = _options_of(rule) for entry in assigned: options.append(_opt( f"reuse:{entry['resourceId']}", "Carries the grants this identity already holds on the backends.", )) - proposal = f"reuse:{assigned[0]['resourceId']}" if assigned else "system-assigned" + proposal = f"reuse:{assigned[0]['resourceId']}" if assigned else rule.get( + "proposal", "system-assigned") self._add( item_id=ids.item("identity", "assign"), source={"assetId": None, "assetKind": "identity", "aspect": "gatewayIdentity"}, - kind="translate" if assigned else None, - verdict="partial" if assigned else "native", - capability_id="identity.assign", + kind=rule.get("itemKind"), + verdict=rule.get("verdict", "partial" if assigned else "native"), + capability_id=rule.get("capabilityId", "identity.assign"), proposal=proposal, rationale=( f"{len(needed)} provider(s) authenticate as a managed identity, so the gateway needs " @@ -403,7 +492,10 @@ def _identity(self) -> None: "over, so the target gets its own and the backend grants must be made against it." ) ), - options=options if assigned else [], + # Nothing is offered without a user-assigned identity to reuse, and + # that is now the rule for that case saying so rather than a guard + # here: its verdict is native and it carries no options. + options=options, evidence={ "sourceIdentity": identity, "providers": [p["id"] for p in needed], @@ -436,13 +528,19 @@ def _provider(self, provider: dict[str, Any]) -> None: "endpoint": provider.get("endpoint"), "authentication": _custom_auth(auth), } + rule = PROVIDER_RULE.first(self.caps.asset_rules()) or {} self._add( item_id=ids.item("modelProvider", provider["id"]), source={"assetId": provider["id"], "assetKind": "modelProvider", "aspect": "registration"}, - kind=None, - verdict="native", - capability_id="provider.create", - rationale=f"{provider.get('providerLabel') or provider.get('providerKind')} provider registers directly.", + kind=rule.get("itemKind"), + verdict=rule.get("verdict", "native"), + capability_id=rule.get("capabilityId", "provider.create"), + # Named after this provider, so the sentence is built here. The rule + # states the mapping as a note rather than a rationale: a rationale + # it carried would never reach an item, which is the kind of dead + # field `reads` exists to expose. + rationale=(f"{provider.get('providerLabel') or provider.get('providerKind')} provider " + "registers directly."), evidence={"endpoint": provider.get("endpoint"), "authMode": auth.get("mode")}, target={"capability": "provider.create", "objects": [objects]}, ) @@ -456,45 +554,46 @@ def _model(self, model: dict[str, Any]) -> None: # Scope: how much of what this API publishes can move at all. if surface.get("status") == "unbounded": + rule = SURFACE_BY_STATUS.first(self.caps.asset_rules(), status="unbounded") or {} self._add( item_id=ids.item(asset_id, "surface"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "publishedSurface"}, - kind="reduce-surface", - verdict="partial", - capability_id="alias.create", - proposal="inference-only", - rationale=surface.get("note") or "The exposed surface cannot be read from configuration.", - options=[ - _opt("inference-only", "Publish the four inference routes; any other path callers use breaks."), - _opt("retain-in-apim", "Nothing moves for this API."), - _opt("block", "Stop the migration until the used routes are established."), - ], + kind=rule.get("itemKind", "reduce-surface"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId"), + proposal=rule.get("proposal"), + # The collector's note says which wildcards made it unreadable; + # the rule's sentence is the one that holds without them. + rationale=surface.get("note") or rule.get("rationale", ""), + options=_options_of(rule), evidence={"surface": surface}, - blocking=True, + blocking=rule.get("blocking", True), ) elif surface.get("unpublishableCount"): groups = ", ".join( f"{entry['group']} x{entry['count']}" for entry in surface.get("unpublishable", []) ) + rule = SURFACE_PARTIALLY_PUBLISHABLE.first( + self.caps.asset_rules(), hasUnpublishable=True + ) or {} self._add( item_id=ids.item(asset_id, "surface"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "publishedSurface"}, - kind="reduce-surface", - verdict="partial", - capability_id="alias.create", - proposal="split", + kind=rule.get("itemKind", "reduce-surface"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId"), + proposal=rule.get("proposal"), rationale=( f"{surface['publishableCount']} of {surface['operationCount']} operations map to the " f"four publishable routes. No target for: {groups}." ), - options=[ - _opt("split", f"Inference moves; {surface['unpublishableCount']} operations stay on APIM."), - _opt("inference-only", "Inference moves and the rest is dropped; those callers break."), - _opt("retain-in-apim", "Nothing moves for this API."), - _opt("block", "Stop the migration until resolved."), - ], + # What `split` costs is this API's number of left-behind + # operations, so that one sentence is built here. + options=_options_of(rule, { + "split": f"Inference moves; {surface['unpublishableCount']} operations stay on APIM.", + }), evidence={"surface": surface}, - blocking=True, + blocking=rule.get("blocking", True), ) # Models: a registration needs a model name. @@ -510,36 +609,36 @@ def _model(self, model: dict[str, Any]) -> None: # Dialect translation. translation = endpoints.get("translation") or {} if translation.get("status") == "translating": + rule = DIALECT_TRANSLATING.first(self.caps.asset_rules(), status="translating") or {} self._add( item_id=ids.item(asset_id, "dialect"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "callerDialect"}, - kind="translate", - verdict="partial", - capability_id="alias.create", - proposal="move-callers", - rationale=translation.get("note") or "", - options=[ - _opt("move-callers", f"Callers move to {', '.join(translation.get('backend') or [])}."), - _opt("retain-in-apim", "Keep APIM in front so callers are unchanged."), - _opt("block", "Stop until the caller impact is agreed."), - ], + kind=rule.get("itemKind", "translate"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId"), + proposal=rule.get("proposal"), + rationale=translation.get("note") or rule.get("rationale", ""), + # Moving the callers costs them the dialect this backend + # speaks, which is read off the asset rather than stated once. + options=_options_of(rule, { + "move-callers": f"Callers move to {', '.join(translation.get('backend') or [])}.", + }), evidence={"translation": translation}, - blocking=True, + blocking=rule.get("blocking", True), ) elif translation.get("status") == "indeterminate": + rule = DIALECT_INDETERMINATE.first( + self.caps.asset_rules(), status="indeterminate") or {} self._add( item_id=ids.item(asset_id, "dialect"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "callerDialect"}, - kind="enumerate", - verdict="partial", - capability_id="alias.create", - rationale=translation.get("note") or "", - options=[ - _opt("confirm-dialect", "State the dialect callers use."), - _opt("retain-in-apim", "Do not migrate this API."), - ], + kind=rule.get("itemKind", "enumerate"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId"), + rationale=translation.get("note") or rule.get("rationale", ""), + options=_options_of(rule), evidence={"translation": translation}, - blocking=True, + blocking=rule.get("blocking", True), ) def _pool_affinity(self, model: dict[str, Any]) -> None: @@ -564,13 +663,14 @@ def _pool_affinity(self, model: dict[str, Any]) -> None: # someone else's. gap = (entry.get("cliGap") or "the installed CLI cannot author it").rstrip(". ") gap = gap[0].lower() + gap[1:] if gap else gap + rule = SESSION_AFFINITY_RULE.first(self.caps.asset_rules()) or {} self._add( item_id=ids.item(asset_id, "sessionAffinity"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "sessionAffinity"}, - kind="accept-loss", - verdict="gap", - capability_id="alias.create", - proposal="accept-loss", + kind=rule.get("itemKind", "accept-loss"), + verdict=rule.get("verdict", "gap"), + capability_id=rule.get("capabilityId", "alias.create"), + proposal=rule.get("proposal", "accept-loss"), rationale=( "This API's backend pool pins a session to the backend that served it. The gateway " "supports the same idea on an alias (a `sessionBackendPreference` stage with a CEL " @@ -578,11 +678,7 @@ def _pool_affinity(self, model: dict[str, Any]) -> None: "run cannot configure it. Without it, each request is routed independently and a " "session can move between backends mid-conversation." ), - options=[ - _opt("accept-loss", "Migrate without affinity, and configure it afterwards by hand."), - _opt("retain-in-apim", "Keep this API on APIM until affinity can be authored."), - _opt("block", "Stop the migration until it can be carried over."), - ], + options=_options_of(rule), evidence={ "apimSessionAffinity": affinity, "targetProperty": entry.get("property"), @@ -616,13 +712,15 @@ def _enumerate_models( # detail. Confirming is one step; pruning is an edit to the same list. sample = ", ".join(str(name) for name in catalogue[:6]) more = f" and {len(catalogue) - 6} more" if len(catalogue) > 6 else "" - options = [ - _opt("list-models", - f"Publish the {len(catalogue)} the catalogue returned; drop any that cannot " - "serve an inference route by editing `decision.models`."), - _opt("retain-in-apim", "Do not migrate this API."), - ] - proposal = "list-models" + rule = CATALOGUE_RULE.first(self.caps.asset_rules(), hasCatalogue=True) or {} + # Listing them costs nothing to say except how many there are, which + # is this catalogue's count. + options = _options_of(rule, { + "list-models": + f"Publish the {len(catalogue)} the catalogue returned; drop any that cannot " + "serve an inference route by editing `decision.models`.", + }) + proposal = rule.get("proposal", "list-models") rationale = ( f"The catalogue at {models.get('resolvedFrom')} returned {len(catalogue)} model(s): " f"{sample}{more}. It states no modality, so whether each one serves an inference " @@ -630,24 +728,27 @@ def _enumerate_models( "the upstream." ) else: - options = [ - _opt("resolve-models", "Read the provider's catalogue with its credential."), - _opt("list-models", "Name the models to register."), - _opt("retain-in-apim", "Do not migrate this API."), - ] # A provider with a catalogue endpoint has an actionable default: - # fetch it rather than ask someone to type model names. - proposal = ("resolve-models" - if models.get("discoverySource") == "modelsEndpoint" else "list-models") - rationale = (" ".join(models.get("notes") or []) - or "The model catalogue could not be resolved.") + # fetch it rather than ask someone to type model names. Which is + # which is the rule's to say, so the two cases are two rules. + rule = CATALOGUE_RULE.first( + self.caps.asset_rules(), hasCatalogue=False, + discoverySource=models.get("discoverySource"), + ) or CATALOGUE_RULE.first( + # The rule that pins no source, which is the one that answers + # when this provider's is not one a rule names. + self.caps.asset_rules(), hasCatalogue=False, discoverySource=None, + ) or {} + options = _options_of(rule) + proposal = rule.get("proposal", "list-models") + rationale = (" ".join(models.get("notes") or []) or rule.get("rationale", "")) item = self._add( item_id=ids.item(asset_id, "models"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "modelCatalogue"}, - kind="enumerate", - verdict="partial", - capability_id="model.create", + kind=rule.get("itemKind", "enumerate"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId", "model.create"), proposal=proposal, rationale=rationale, options=options, @@ -656,7 +757,7 @@ def _enumerate_models( "catalogue": catalogue, "notes": models.get("notes"), }, - blocking=True, + blocking=rule.get("blocking", True), ) decision = self._settled(item["id"]) @@ -735,13 +836,14 @@ def _model_registration(self, model: dict[str, Any], resolved: dict[str, Any]) - pooled = len({r.get("backendId") for r in (model.get("models") or {}).get("resolved") or []}) > 1 item_key = f"model/{name}@{provider_name}" if pooled else f"model/{name}" + registration_rule = MODEL_REGISTRATION_RULE.first(self.caps.asset_rules()) or {} self._add( item_id=ids.item(asset_id, item_key), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": f"model:{name}" + (f"@{provider_name}" if pooled else "")}, - kind=None, - verdict="native", - capability_id="model.create", + kind=registration_rule.get("itemKind"), + verdict=registration_rule.get("verdict", "native"), + capability_id=registration_rule.get("capabilityId", "model.create"), rationale=( f"Registers {resolved.get('modelName')} named in this API's model catalogue decision." if resolved.get("enumerated") @@ -825,22 +927,23 @@ def _alias_naming(self, model: dict[str, Any], registrations: list[dict[str, Any f"{'...' if len(partial) > 3 else ''}), so those route to that member alone " "instead of being split." ) + rule = ALIAS_NAMES_RULE.first(self.caps.asset_rules()) or {} self._add( item_id=ids.item(asset_id, "aliasNames"), source={"assetId": asset_id, "assetKind": "modelApi", "aspect": "aliasNames"}, - kind="name", - verdict="partial", - capability_id="alias.create", - proposal="use-model-names", - rationale=( - f"An alias publishes the route, and its routingName is what clients send as `model`. " - f"APIM does not store it. Proposed for {len(members)} model(s): {sample}{more}." - + balance - ), - options=[ - _opt("use-model-names", "Publish each model under its own name."), - _opt("override", "Supply names per model; set them in this item's members."), - ], + kind=rule.get("itemKind", "name"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId", "alias.create"), + proposal=rule.get("proposal", "use-model-names"), + # What an alias name is holds for every API, so it is said once in + # the rule; which names are proposed is this API's models. The two + # sentences were both written here, and the rule's copy was read by + # nobody. + rationale=" ".join(filter(None, [ + rule.get("rationale"), + f"Proposed for {len(members)} model(s): {sample}{more}." + balance, + ])), + options=_options_of(rule), evidence={"members": members, "count": len(members), "pooled": pooled, "singleMemberModels": partial}, target={ @@ -868,7 +971,7 @@ def _mcp(self, server: dict[str, Any]) -> None: asset_id = server["id"] pattern = server.get("pattern") rule = MCP_BY_PATTERN.first( - self.caps.asset_rules(), family="mcpServers", pattern=pattern + self.caps.asset_rules(), pattern=pattern ) if rule: self._add( @@ -894,29 +997,28 @@ def _mcp(self, server: dict[str, Any]) -> None: # The list came from the upstream with the API's policies bypassed, so # it can be broader than what callers reach through the gateway. # Treating it as settled would publish tools APIM currently withholds. + bypass_rule = TOOL_EXPOSURE_BYPASSED.first( + self.caps.asset_rules(), policiesBypassed=True + ) or {} self._add( item_id=ids.item(asset_id, "tools"), source={"assetId": asset_id, "assetKind": "mcpServer", "aspect": "toolExposure"}, - kind="enumerate", - verdict="partial", - proposal="accept-as-listed", + kind=bypass_rule.get("itemKind", "enumerate"), + verdict=bypass_rule.get("verdict", "partial"), + proposal=bypass_rule.get("proposal", "accept-as-listed"), rationale=( f"{discovery_record.get('discoveredCount')} tools were listed directly from the " "upstream because the gateway route was unavailable, so the API's policies did " "not run. APIM may be withholding some of these from callers today." ), - options=[ - _opt("accept-as-listed", "Federate every tool the upstream exposes."), - _opt("verify-through-gateway", "Re-list through APIM before deciding."), - _opt("retain-in-apim", "Do not migrate this server."), - ], + options=_options_of(bypass_rule), evidence={"toolDiscovery": discovery_record, "tools": [tool.get("name") for tool in server.get("tools") or []]}, blocking=True, ) if discovery == "runtimeOnly": tool_rule = MCP_BY_TOOL_DISCOVERY.first( - self.caps.asset_rules(), family="mcpServers", toolDiscovery="runtimeOnly" + self.caps.asset_rules(), toolDiscovery="runtimeOnly" ) or {} self._add( item_id=ids.item(asset_id, "tools"), @@ -930,7 +1032,7 @@ def _mcp(self, server: dict[str, Any]) -> None: ) def _agent(self, agent: dict[str, Any]) -> None: - rule = AGENT_RULE.first(self.caps.asset_rules(), family="agents") or {} + rule = AGENT_RULE.first(self.caps.asset_rules()) or {} self._add( item_id=ids.item(agent["id"], "registration"), source={"assetId": agent["id"], "assetKind": "agent", "aspect": "registration"}, @@ -1109,7 +1211,7 @@ def _policy_fragments(self, structural: list[dict[str, Any]]) -> None: else: disposition = "dissolved" rule = STRUCTURAL_POLICY_FRAGMENTS.first( - structural, kind="policyFragments", disposition=disposition + structural, disposition=disposition ) or {} self._add( item_id=ids.item("fragment", document["id"]), @@ -1147,7 +1249,7 @@ def _policy_fragments(self, structural: list[dict[str, Any]]) -> None: # by name left the unknown policy unmentioned. for missing in sorted(set(self._unresolved_fragments)): rule = STRUCTURAL_POLICY_FRAGMENTS.first( - structural, kind="policyFragments", disposition="unresolved" + structural, disposition="unresolved" ) or {} self._add( item_id=ids.item("fragment", f"unresolved/{missing}"), @@ -1315,7 +1417,7 @@ def _structural(self) -> None: for workspace in self.inventory.get("workspaces") or []: if workspace.get("name") == "default" or not workspace.get("collected"): continue - rule = STRUCTURAL_WORKSPACE.first(structural, kind="workspace") or {} + rule = STRUCTURAL_WORKSPACE.first(structural) or {} self._add( item_id=ids.item("workspace", workspace["name"]), source={"assetId": None, "assetKind": "workspace", "aspect": workspace["name"]}, @@ -1330,7 +1432,7 @@ def _structural(self) -> None: subscriptions = shared.get("subscriptions") or [] if subscriptions: - rule = STRUCTURAL_SUBSCRIPTIONS.first(structural, kind="subscriptions") or {} + rule = STRUCTURAL_SUBSCRIPTIONS.first(structural) or {} scopes = sorted({entry["scope"]["level"] for entry in subscriptions}) self._add( item_id=ids.item("access", "subscriptions"), @@ -1359,7 +1461,7 @@ def _structural(self) -> None: # cost, and that is mapping knowledge: one touches a resource other # workloads may be reading, the next leaves every existing dashboard # pointing at a gateway that no longer reports to it. - rule = STRUCTURAL_TELEMETRY.first(structural, kind="telemetry") or {} + rule = STRUCTURAL_TELEMETRY.first(structural) or {} loggers = [ logger.get("name") for logger in ((self.inventory.get("shared") or {}).get("telemetry") or {}).get("loggers") or [] @@ -1384,7 +1486,7 @@ def _structural(self) -> None: entries = shared.get(kind) or [] if not entries: continue - rule = site.first(structural, kind=kind) or {} + rule = site.first(structural) or {} verdict = rule.get("verdict", "gap") self._add( item_id=ids.item("shared", kind), @@ -1400,22 +1502,18 @@ def _structural(self) -> None: networking = (self.inventory.get("service") or {}).get("networking") or {} requirement = networking.get("targetRequirement") if requirement: + rule = REACHABILITY_BY_SUBNET.first( + structural, needsSubnet=bool(requirement.get("needsSubnet")) + ) or {} self._add( item_id=ids.item("network", "reachability"), source={"assetId": None, "assetKind": "networking", "aspect": "backendReachability"}, - kind="translate", - verdict="partial", - capability_id="network.update", - proposal="new-delegated-subnet" if requirement.get("needsSubnet") else "private-ingress", - rationale=requirement.get("note", ""), - options=[ - _opt("new-delegated-subnet", - "Provision a subnet delegated to Microsoft.App/environments and integrate the gateway."), - _opt("public-egress", - "Reach backends over public networking; only viable if they accept it."), - _opt("retain-in-apim", "Keep workloads that need private backends on APIM."), - _opt("block", "Stop until the network design is agreed."), - ], + kind=rule.get("itemKind", "translate"), + verdict=rule.get("verdict", "partial"), + capability_id=rule.get("capabilityId", "network.update"), + proposal=rule.get("proposal"), + rationale=requirement.get("note", "") or rule.get("rationale", ""), + options=_options_of(rule), evidence={"networking": networking}, blocking=True, ) @@ -1426,7 +1524,7 @@ def _structural(self) -> None: if entry.get("status") == "failed" ] for failure in failures: - rule = STRUCTURAL_COVERAGE_GAP.first(structural, kind="coverageGap") or {} + rule = STRUCTURAL_COVERAGE_GAP.first(structural) or {} self._add( item_id=ids.item("coverage", f"{failure['collection']}/{failure['scope']}"), source={"assetId": None, "assetKind": "coverageGap", "aspect": failure["collection"]}, @@ -1518,8 +1616,7 @@ def _manual_prerequisites(self) -> None: # resource, and two do not. Which is which is mapping knowledge, so the # rule says it; until the item is settled nothing is ruled out and the # administrator still has to know. An unsettled plan asks. - telemetry_rule = STRUCTURAL_TELEMETRY.first( - self.caps.structural_rules(), kind="telemetry") or {} + telemetry_rule = STRUCTURAL_TELEMETRY.first(self.caps.structural_rules()) or {} needs_endpoint = telemetry_rule.get("prerequisiteWhen") if self._reports_telemetry() and ( settled is None or not needs_endpoint or settled in needs_endpoint @@ -2163,19 +2260,29 @@ def _opt(value: str, consequence: str) -> dict[str, str]: return {"value": value, "consequence": consequence} -def _options_of(rule: dict[str, Any]) -> list[dict[str, str]]: +def _options_of(rule: dict[str, Any], + composed: dict[str, str] | None = None) -> list[dict[str, str]]: """A rule's options, in either of the two shapes rules.json uses. A bare string is the choice with nothing said about it; the object form carries what choosing it costs. Both reach the plan as {value, consequence}, so a rule can gain a consequence later without the reader changing. + + `composed` carries the costs that are this asset's own numbers -- how many + operations stay behind, which dialect the callers move to. Those sites used + to write the whole list, so the vocabulary in the file was never read and + editing it changed nothing; the choices are the rule's either way, and only + the sentence is built where the inventory is. """ options = [] for option in rule.get("options") or []: - if isinstance(option, dict): - options.append(_opt(option["value"], option.get("consequence", ""))) - elif option: - options.append(_opt(option, "")) + value = option["value"] if isinstance(option, dict) else option + if not value: + continue + consequence = (composed or {}).get(value) + if consequence is None: + consequence = option.get("consequence", "") if isinstance(option, dict) else "" + options.append(_opt(value, consequence)) return options diff --git a/tools/migrate-apim/schemas/inventory.schema.json b/tools/migrate-apim/schemas/inventory.schema.json index f80c7ba..37fc0e5 100644 --- a/tools/migrate-apim/schemas/inventory.schema.json +++ b/tools/migrate-apim/schemas/inventory.schema.json @@ -78,7 +78,46 @@ "virtualNetworkType": {"type": ["string", "null"]}, "publicNetworkAccess": {"type": ["string", "null"]}, "hostnameConfigurations": {"type": "array"}, - "identity": {"type": ["object", "null"]}, + "identity": { + "description": "The service's managed identities. `userAssignedIdentities` decides whether the gateway can carry one over with the grants it already holds, or needs a new principal granted from scratch.", + "type": ["object", "null"], + "properties": { + "type": {"type": ["string", "null"]}, + "principalId": {"type": ["string", "null"]}, + "tenantId": {"type": ["string", "null"]}, + "userAssignedIdentities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resourceId": {"type": "string"}, + "clientId": {"type": ["string", "null"]} + } + } + } + } + }, + "networking": { + "description": "How the service reaches its backends and is reached. `targetRequirement` is the collector's reading of what the gateway would have to do to match it; null when nothing private is in play.", + "type": ["object", "null"], + "properties": { + "virtualNetworkType": {"type": ["string", "null"]}, + "publicNetworkAccess": {"type": ["string", "null"]}, + "vnetId": {"type": ["string", "null"]}, + "vnetIntegrated": {"type": "boolean"}, + "subnetResourceId": {"type": ["string", "null"]}, + "natGatewayState": {"type": ["string", "null"]}, + "outboundPublicIPAddresses": {"type": ["array", "null"]}, + "privateEndpointConnections": {"type": ["array", "null"]}, + "targetRequirement": { + "type": ["object", "null"], + "properties": { + "needsSubnet": {"type": "boolean"}, + "note": {"type": "string"} + } + } + } + }, "tags": {"type": "object"} } }, @@ -250,7 +289,18 @@ "type": "object", "required": ["status", "discoverySource", "resolved"], "properties": { - "status": {"enum": ["resolved", "declared", "unresolved", "empty"]}, + "status": { + "description": "catalogued is what `migrate-apim resolve` writes after reading a provider's own catalogue: the models exist, but the response states no modality, so which of them can serve an inference route is still a decision. It was missing here while `resolve.py` wrote it and `plan.py` branched on it, so validating a resolved inventory failed on a value the tool had just produced -- the same hole `auth.mode: undetermined` left.", + "enum": ["resolved", "declared", "unresolved", "empty", "catalogued"] + }, + "resolvedFrom": { + "description": "The catalogue endpoint the models were read from. Null until a resolve run writes one.", + "type": ["string", "null"] + }, + "catalogue": { + "description": "The model names the catalogue returned, which the planner samples into the question it asks.", + "type": "array", "items": {"type": "string"} + }, "discoverySource": { "enum": ["armDeployments", "backendLanguageModel", "modelsEndpoint", "awsCli", "gcloudCli", "manual", "unknown"] }, @@ -350,6 +400,21 @@ "type": "array", "items": {"type": "string"} }, "backendDialectsDeclared": {"type": "boolean"}, + "surface": { + "description": "How much of what the API publishes can move. `unbounded` means a wildcard operation forwards every upstream path, so the exposed surface cannot be read from configuration at all -- which is not the same as publishing nothing.", + "type": "object", + "properties": { + "status": {"enum": ["bounded", "unbounded", "unknown"]}, + "basis": {"type": "string"}, + "operationCount": {"type": "integer"}, + "publishable": {"type": "array"}, + "unpublishable": {"type": "array"}, + "publishableCount": {"type": "integer"}, + "unpublishableCount": {"type": "integer"}, + "targetRoutes": {"type": "array", "items": {"type": "string"}}, + "note": {"type": "string"} + } + }, "translation": { "description": "Null only when the backend declares no dialect to compare against.", "oneOf": [ diff --git a/tools/migrate-apim/schemas/rules.schema.json b/tools/migrate-apim/schemas/rules.schema.json index 1c0cc63..996467c 100644 --- a/tools/migrate-apim/schemas/rules.schema.json +++ b/tools/migrate-apim/schemas/rules.schema.json @@ -99,20 +99,40 @@ }, "assetRule": { "type": "object", - "required": ["match", "verdict"], + "required": ["selects", "verdict"], "additionalProperties": false, "allOf": [{"$ref": "#/$defs/partialNeedsOptions"}], "properties": { - "match": { + "selects": { + "description": "The question this rule answers. A subject is a question the planner asks about one asset, not the asset's type: an API raises six, and they are decided separately.", + "enum": ["mcpServer", "agent", "toolExposure", "modelProvider", "publishedSurface", + "callerDialect", "sessionAffinity", "modelCatalogue", "modelRegistration", + "aliasNames"] + }, + "where": { "type": "object", "additionalProperties": false, "minProperties": 1, + "description": "Field predicates on the subject's inventory record. Every key is a field a selection site declares a path for, which is what lets `compile` check it against inventory.schema.json.", "properties": { - "family": {"enum": ["models", "modelProviders", "mcpServers", "agents"]}, "pattern": {"type": "string"}, - "toolDiscovery": {"type": "string"} + "toolDiscovery": {"type": "string"}, + "status": {"type": "string"}, + "discoverySource": {"type": "string"} } }, + "derived": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "description": "Predicates computed from the record rather than read off it, so they are not held to the field check `where` keys are.", + "properties": { + "hasUnpublishable": {"type": "boolean"}, + "hasCatalogue": {"type": "boolean"}, + "policiesBypassed": {"type": "boolean"} + } + }, + "blocking": {"type": "boolean"}, "verdict": {"$ref": "#/$defs/verdict"}, "itemKind": {"$ref": "#/$defs/itemKind"}, "capabilityId": {"type": "string"}, @@ -128,22 +148,33 @@ }, "structuralRule": { "type": "object", - "required": ["match", "verdict"], + "required": ["selects", "verdict"], "additionalProperties": false, "allOf": [ {"$ref": "#/$defs/partialNeedsOptions"}, {"$ref": "#/$defs/decidedNeedsItemKind"} ], "properties": { - "match": { + "selects": { + "description": "The question this rule answers. `kind` used to say this, which made it a subject declaration wearing a predicate's name.", + "enum": ["workspace", "subscriptions", "telemetry", "certificates", "credentialProviders", + "coverageGap", "policyFragment", "gatewayIdentity", "backendReachability"] + }, + "derived": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": {"hasUserAssigned": {"type": "boolean"}} + }, + "where": { "type": "object", - "required": ["kind"], "additionalProperties": false, + "minProperties": 1, "properties": { - "kind": {"type": "string"}, + "needsSubnet": {"type": "boolean"}, "disposition": { "type": "string", - "description": "Which case of `kind` this rule answers for, when one asset family resolves to several. A fragment the target must dissolve is not a fragment nothing includes, and neither is an `include-fragment` naming one this inventory does not hold." + "description": "Which case of the subject this rule answers for, when one subject resolves to several. A fragment the target must dissolve is not a fragment nothing includes, and neither is an `include-fragment` naming one this inventory does not hold." } } }, @@ -166,25 +197,40 @@ }, "policyRule": { "type": "object", - "required": ["match", "verdict"], + "required": ["selects", "verdict"], "additionalProperties": false, "allOf": [{"$ref": "#/$defs/partialNeedsOptions"}], "dependentRequired": {"partial": ["partialWhen"]}, "properties": { - "match": { + "selects": {"const": "policyElement"}, + "derived": { "type": "object", "additionalProperties": false, "minProperties": 1, + "description": "Predicates computed from the record rather than read off it, so they are not held to the field check `where` keys are.", "properties": { - "element": {"type": "array", "items": {"type": "string"}, "minItems": 1}, - "family": {"type": "string"}, - "hasExpression": {"type": "boolean"}, - "anyElement": { + "hasExpression": { "const": true, - "description": "The terminal rule, tried last and matching anything the passes above did not. There is exactly one; a second is a tie `compile` rejects. It exists so that an element no rule recognises still reaches the plan, rather than being dropped where it was classified." + "description": "The element evaluates a policy expression anywhere in it: `bool(element.expressionIds)`. No record carries this field." } } }, + "fallback": { + "const": true, + "description": "Answers for whatever the passes above it did not, and is tried last. There is exactly one per subject; a second is a tie `compile` rejects. It exists so an element no rule recognises still reaches the plan rather than being dropped where it was classified. Written as a flag and not as a predicate, because matching everything is not a statement about the element." + }, + "where": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": { + "name": { + "type": "array", "items": {"type": "string"}, "minItems": 1, + "description": "Element names, compared against `policies[].elements[].name`." + }, + "family": {"type": "string"} + } + }, "verdict": {"$ref": "#/$defs/verdict"}, "itemKind": {"$ref": "#/$defs/itemKind"}, "capabilityId": {"type": "string"}, diff --git a/tools/migrate-apim/tests/golden/decisions.json b/tools/migrate-apim/tests/golden/decisions.json new file mode 100644 index 0000000..aad8826 --- /dev/null +++ b/tools/migrate-apim/tests/golden/decisions.json @@ -0,0 +1,2366 @@ +{ + "plan": { + "$schema": "https://github.com/Azure/aigateway/tools/migrate-apim/schemas/plan.schema.json", + "generator": { + "command": "plan", + "name": "migrate-apim", + "version": "0.1.0" + }, + "items": [ + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "identity.assign", + "capabilityLimitations": [ + "Assignment does not copy source principal IDs or grant backend RBAC. An absent identity on a successfully read gateway is normalized to an empty object." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "audiences": [ + "https://cognitiveservices.azure.com/" + ], + "providers": [ + "modelProvider:aoai-east" + ], + "sourceIdentity": { + "principalId": "p-1", + "tenantId": "t-1", + "type": "SystemAssigned", + "userAssignedIdentities": [] + } + }, + "id": "item:identity/assign", + "kind": null, + "memberDigests": { + "item:identity/assign": "sha256:c96447348b9dc37dd5ea95e12192020710adc1664fa3ae3d0cb1028e754caff2" + }, + "options": [], + "proposal": "system-assigned", + "rationale": "1 provider(s) authenticate as a managed identity, so the gateway needs one. The source uses a system-assigned identity, whose principal cannot be carried over, so the target gets its own and the backend grants must be made against it.", + "shapeDigest": "sha256:decc47869967de1ee9e5e878d0ae318e3d0522715c6a27326cbcc099b620a5d0", + "source": { + "aspect": "gatewayIdentity", + "assetId": null, + "assetKind": "identity" + }, + "status": "ready", + "target": { + "capability": "identity.assign", + "objects": [ + { + "systemAssigned": true, + "userAssigned": null + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "provider.create", + "capabilityLimitations": [ + "Low-level registration only; no automatic model import or RBAC unless --import-models is passed. Create is not guaranteed create-only. The --import-models flag with Foundry imports all deployments; equivalent to running model-provider import separately." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "authMode": "managedIdentity", + "endpoint": "https://aif.openai.azure.com/" + }, + "id": "item:modelProvider/modelProvider-aoai-east", + "kind": null, + "memberDigests": { + "modelProvider:aoai-east": "sha256:1b9cf55b08608c654f3035aceeef7d588082cab5b7837337a45fb4d0e8909bb6" + }, + "options": [], + "proposal": null, + "rationale": "Microsoft Foundry / Azure OpenAI provider registers directly.", + "shapeDigest": "sha256:0a5d33b94bb18e7ce5a0cd5754eb04da5a4b76921a96b31e00615d1e3a685cf6", + "source": { + "aspect": "registration", + "assetId": "modelProvider:aoai-east", + "assetKind": "modelProvider" + }, + "status": "ready", + "target": { + "capability": "provider.create", + "objects": [ + { + "foundry": { + "authentication": { + "kind": "ManagedIdentity", + "managedIdentity": { + "resource": "https://cognitiveservices.azure.com/" + } + }, + "endpoint": "https://aif.openai.azure.com/", + "resourceIds": [ + "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif" + ] + }, + "kind": "Foundry", + "name": "aoai-east" + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "provider.create", + "capabilityLimitations": [ + "Low-level registration only; no automatic model import or RBAC unless --import-models is passed. Create is not guaranteed create-only. The --import-models flag with Foundry imports all deployments; equivalent to running model-provider import separately." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "authMode": "apiKey", + "endpoint": "https://aif-west.openai.azure.com/" + }, + "id": "item:modelProvider/modelProvider-aoai-west", + "kind": null, + "memberDigests": { + "modelProvider:aoai-west": "sha256:998814ec8b516d853248ddcd5a24224357b41598da5dd28949ee99cecf1d1829" + }, + "options": [], + "proposal": null, + "rationale": "Microsoft Foundry / Azure OpenAI provider registers directly.", + "shapeDigest": "sha256:0a5d33b94bb18e7ce5a0cd5754eb04da5a4b76921a96b31e00615d1e3a685cf6", + "source": { + "aspect": "registration", + "assetId": "modelProvider:aoai-west", + "assetKind": "modelProvider" + }, + "status": "ready", + "target": { + "capability": "provider.create", + "objects": [ + { + "foundry": { + "authentication": { + "kind": "ManagedIdentity", + "managedIdentity": { + "resource": "https://cognitiveservices.azure.com/" + } + }, + "endpoint": "https://aif-west.openai.azure.com/", + "resourceIds": [ + "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif-west" + ] + }, + "kind": "Foundry", + "name": "aoai-west" + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "provider.create", + "capabilityLimitations": [ + "Low-level registration only; no automatic model import or RBAC unless --import-models is passed. Create is not guaranteed create-only. The --import-models flag with Foundry imports all deployments; equivalent to running model-provider import separately." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "authMode": "apiKey", + "endpoint": "https://api.meta.ai" + }, + "id": "item:modelProvider/modelProvider-meta-ai-openai-endpoint", + "kind": null, + "memberDigests": { + "modelProvider:meta-ai-openai-endpoint": "sha256:940ea3e9c3675f11df3878a29e5a6178c0291c21ee5b5492d8380fa455c96834" + }, + "options": [], + "proposal": null, + "rationale": "openAiCompatible provider registers directly.", + "shapeDigest": "sha256:0a5d33b94bb18e7ce5a0cd5754eb04da5a4b76921a96b31e00615d1e3a685cf6", + "source": { + "aspect": "registration", + "assetId": "modelProvider:meta-ai-openai-endpoint", + "assetKind": "modelProvider" + }, + "status": "ready", + "target": { + "capability": "provider.create", + "objects": [ + { + "custom": { + "authentication": { + "apiKey": { + "headerName": "Authorization", + "value": { + "$secretRef": "secret:namedValue/meta-ai-Authorization-LLM" + } + }, + "kind": "ApiKey" + }, + "endpoint": "https://api.meta.ai" + }, + "kind": "Custom", + "name": "meta-ai-openai-endpoint" + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "provider.create", + "capabilityLimitations": [ + "Low-level registration only; no automatic model import or RBAC unless --import-models is passed. Create is not guaranteed create-only. The --import-models flag with Foundry imports all deployments; equivalent to running model-provider import separately." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "authMode": "apiKey", + "endpoint": "https://demo.services.ai.azure.com/anthropic" + }, + "id": "item:modelProvider/modelProvider-finance/claude-backend", + "kind": null, + "memberDigests": { + "modelProvider:finance/claude-backend": "sha256:e08460167b47b40d80ae2f4e0e4073563fb03507390f73daed74021d0ab85c1a" + }, + "options": [], + "proposal": null, + "rationale": "Microsoft Foundry / Azure OpenAI provider registers directly.", + "shapeDigest": "sha256:0a5d33b94bb18e7ce5a0cd5754eb04da5a4b76921a96b31e00615d1e3a685cf6", + "source": { + "aspect": "registration", + "assetId": "modelProvider:finance/claude-backend", + "assetKind": "modelProvider" + }, + "status": "ready", + "target": { + "capability": "provider.create", + "objects": [ + { + "custom": { + "authentication": { + "apiKey": { + "headerName": "api-key", + "value": { + "$secretRef": "secret:namedValue/finance/claude-key" + } + }, + "kind": "ApiKey" + }, + "endpoint": "https://demo.services.ai.azure.com/anthropic" + }, + "kind": "Custom", + "name": "finance-claude-backend" + } + ] + }, + "verdict": "native" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": "alias.create", + "capabilityLimitations": [ + "Creates an explicit callable model name. GET-before-PUT is not atomic; no implicit piped/batch alias creation." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "surface": { + "basis": "operationTemplates", + "operationCount": 6, + "publishable": [ + { + "count": 1, + "group": "chatCompletions", + "publishable": true, + "route": "/openai/v1/chat/completions", + "samples": [ + "/deployments/{deployment-id}/chat/completions" + ], + "subresources": 0 + }, + { + "count": 1, + "group": "embeddings", + "publishable": true, + "route": "/openai/v1/embeddings", + "samples": [ + "/deployments/{deployment-id}/embeddings" + ], + "subresources": 0 + } + ], + "publishableCount": 2, + "status": "bounded", + "targetRoutes": [ + "/openai/v1/chat/completions", + "/openai/v1/embeddings", + "/openai/v1/responses", + "/v1/messages" + ], + "unpublishable": [ + { + "count": 2, + "group": "threads", + "publishable": false, + "route": null, + "samples": [ + "/threads?api-version={api-version}", + "/threads/{thread_id}/runs?api-version={api-version}" + ], + "subresources": 0 + }, + { + "count": 1, + "group": "assistants", + "publishable": false, + "route": null, + "samples": [ + "/assistants?api-version={api-version}" + ], + "subresources": 0 + }, + { + "count": 1, + "group": "vectorStores", + "publishable": false, + "route": null, + "samples": [ + "/vector_stores?api-version={api-version}" + ], + "subresources": 0 + } + ], + "unpublishableCount": 4 + } + }, + "id": "item:model/aoai-api/surface", + "kind": "reduce-surface", + "memberDigests": { + "model:aoai-api": "sha256:603ff058414ef31983635204fa479a763de6a8c08dae13e80112b8e1fdbbf9b9" + }, + "options": [ + { + "consequence": "Inference moves; 4 operations stay on APIM.", + "value": "split" + }, + { + "consequence": "Inference moves and the rest is dropped; those callers break.", + "value": "inference-only" + }, + { + "consequence": "Nothing moves for this API.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop the migration until resolved.", + "value": "block" + } + ], + "proposal": "split", + "rationale": "2 of 6 operations map to the four publishable routes. No target for: threads x2, assistants x1, vectorStores x1.", + "shapeDigest": "sha256:8d193ace4f14fc89fb6d5c5cf9968d775919978350810f797d2847a05ed141ba", + "source": { + "aspect": "publishedSurface", + "assetId": "model:aoai-api", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "model.create", + "capabilityLimitations": [ + "Explicit selected models/operations only. No Foundry onboarding side effects or implicit aliases; callable routes require separate alias nodes." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "modelName": "gpt-5.2", + "modelVersion": "2025-12-11" + }, + "id": "item:model/aoai-api/model/gpt-5-aoai-east", + "kind": null, + "memberDigests": { + "model:aoai-api": "sha256:62d3f8ecb3430d4af1f0cf4f2e8de3faff23fee51d4454bb401010f732121f11" + }, + "options": [], + "proposal": null, + "rationale": "Registers gpt-5.2 from a resolved deployment.", + "shapeDigest": "sha256:a30245f530761bfb155104f1da33dc94558d0e2acc39a1f051425b3695ce4fa1", + "source": { + "aspect": "model:gpt-5@aoai-east", + "assetId": "model:aoai-api", + "assetKind": "modelApi" + }, + "status": "ready", + "target": { + "capability": "model.create", + "objects": [ + { + "apiFormat": "OpenAIChatCompletions", + "deploymentConfig": { + "modelName": "gpt-5.2", + "modelVersion": "2025-12-11", + "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif/deployments/gpt-5" + }, + "name": "gpt-5", + "providerName": "aoai-east", + "supportedEndpoints": [ + "/openai/v1/chat/completions", + "/openai/v1/responses" + ] + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "model.create", + "capabilityLimitations": [ + "Explicit selected models/operations only. No Foundry onboarding side effects or implicit aliases; callable routes require separate alias nodes." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "modelName": "text-embedding-3-large", + "modelVersion": "1" + }, + "id": "item:model/aoai-api/model/text-embedding-3-large-aoai-east", + "kind": null, + "memberDigests": { + "model:aoai-api": "sha256:809bd1a871d6523eb298711fc8fef8a983c30fcacd07072df61de49c0cb760ed" + }, + "options": [], + "proposal": null, + "rationale": "Registers text-embedding-3-large from a resolved deployment.", + "shapeDigest": "sha256:a30245f530761bfb155104f1da33dc94558d0e2acc39a1f051425b3695ce4fa1", + "source": { + "aspect": "model:text-embedding-3-large@aoai-east", + "assetId": "model:aoai-api", + "assetKind": "modelApi" + }, + "status": "ready", + "target": { + "capability": "model.create", + "objects": [ + { + "apiFormat": "OpenAIChatCompletions", + "deploymentConfig": { + "modelName": "text-embedding-3-large", + "modelVersion": "1", + "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif/deployments/text-embedding-3-large" + }, + "name": "text-embedding-3-large", + "providerName": "aoai-east", + "supportedEndpoints": [ + "/openai/v1/embeddings" + ] + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "model.create", + "capabilityLimitations": [ + "Explicit selected models/operations only. No Foundry onboarding side effects or implicit aliases; callable routes require separate alias nodes." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "modelName": "gpt-5.2", + "modelVersion": "2025-12-11" + }, + "id": "item:model/aoai-api/model/gpt-5-aoai-west", + "kind": null, + "memberDigests": { + "model:aoai-api": "sha256:62d3f8ecb3430d4af1f0cf4f2e8de3faff23fee51d4454bb401010f732121f11" + }, + "options": [], + "proposal": null, + "rationale": "Registers gpt-5.2 from a resolved deployment.", + "shapeDigest": "sha256:a30245f530761bfb155104f1da33dc94558d0e2acc39a1f051425b3695ce4fa1", + "source": { + "aspect": "model:gpt-5@aoai-west", + "assetId": "model:aoai-api", + "assetKind": "modelApi" + }, + "status": "ready", + "target": { + "capability": "model.create", + "objects": [ + { + "apiFormat": "OpenAIChatCompletions", + "deploymentConfig": { + "modelName": "gpt-5.2", + "modelVersion": "2025-12-11", + "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif-west/deployments/gpt-5" + }, + "name": "gpt-5", + "providerName": "aoai-west", + "supportedEndpoints": [ + "/openai/v1/chat/completions", + "/openai/v1/responses" + ] + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "alias.create", + "capabilityLimitations": [ + "Creates an explicit callable model name. GET-before-PUT is not atomic; no implicit piped/batch alias creation." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "count": 2, + "members": [ + { + "backends": [ + { + "priority": 1, + "providerName": "aoai-east", + "weight": 80 + }, + { + "priority": 2, + "providerName": "aoai-west", + "weight": 20 + } + ], + "modelName": "gpt-5.2", + "proposedAliasName": "gpt-5", + "supportedEndpoints": [ + "/openai/v1/chat/completions", + "/openai/v1/responses" + ] + }, + { + "backends": [ + { + "priority": 1, + "providerName": "aoai-east", + "weight": 80 + } + ], + "modelName": "text-embedding-3-large", + "proposedAliasName": "text-embedding-3-large", + "supportedEndpoints": [ + "/openai/v1/embeddings" + ] + } + ], + "pooled": true, + "singleMemberModels": [ + "text-embedding-3-large" + ] + }, + "id": "item:model/aoai-api/aliasNames", + "kind": "name", + "memberDigests": { + "gpt-5.2": "sha256:8722b822bee2d6bd8c8d1fdd25c267646436ed2eba3929aa35356f9255251c7d", + "text-embedding-3-large": "sha256:e86f2572e76bbc9c98f418cc96a700b62ce67f2f9c4cf36d5d6c4860f9586284" + }, + "options": [ + { + "consequence": "Publish each model under its own name.", + "value": "use-model-names" + }, + { + "consequence": "Supply names per model; set them in this item's members.", + "value": "override" + } + ], + "proposal": "use-model-names", + "rationale": "An alias publishes the route, and its routingName is what clients send as `model`. APIM does not store it. Proposed for 2 model(s): gpt-5, text-embedding-3-large. This API load-balances across 2 backends; each alias carries the pool's priority and weight. 1 of them are deployed in only one member (text-embedding-3-large), so those route to that member alone instead of being split.", + "shapeDigest": "sha256:5724bebaee31ae3db183f70029051e2ab0e6ff31df530eeb6539e4fe400b7241", + "source": { + "aspect": "aliasNames", + "assetId": "model:aoai-api", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": { + "capability": "alias.create", + "objects": [ + { + "backendModels": [ + { + "modelName": "gpt-5", + "priority": 1, + "providerName": "aoai-east", + "resourceId": null, + "weight": 80 + }, + { + "modelName": "gpt-5", + "priority": 2, + "providerName": "aoai-west", + "resourceId": null, + "weight": 20 + } + ], + "routingName": "gpt-5", + "supportedEndpoints": [ + "/openai/v1/chat/completions", + "/openai/v1/responses" + ] + }, + { + "backendModels": [ + { + "modelName": "text-embedding-3-large", + "priority": 1, + "providerName": "aoai-east", + "resourceId": null, + "weight": 80 + } + ], + "routingName": "text-embedding-3-large", + "supportedEndpoints": [ + "/openai/v1/embeddings" + ] + } + ] + }, + "verdict": "partial" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": "alias.create", + "capabilityLimitations": [ + "Creates an explicit callable model name. GET-before-PUT is not atomic; no implicit piped/batch alias creation." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "surface": { + "basis": "operationTemplates", + "note": "1 wildcard operation(s) forward every upstream path, so the exposed surface cannot be read from configuration. The routes callers actually use have to be established with the operator or from traffic.", + "operationCount": 1, + "publishable": [], + "publishableCount": 0, + "status": "unbounded", + "targetRoutes": [ + "/openai/v1/chat/completions", + "/openai/v1/embeddings", + "/openai/v1/responses", + "/v1/messages" + ], + "unpublishable": [], + "unpublishableCount": 0 + } + }, + "id": "item:model/meta-ai/surface", + "kind": "reduce-surface", + "memberDigests": { + "model:meta-ai": "sha256:ab8be6db208aa5234e8ba24b2607047d3ea35d0066afa3ffced6aad155e3137e" + }, + "options": [ + { + "consequence": "Publish the four inference routes; any other path callers use breaks.", + "value": "inference-only" + }, + { + "consequence": "Nothing moves for this API.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop the migration until the used routes are established.", + "value": "block" + } + ], + "proposal": "inference-only", + "rationale": "1 wildcard operation(s) forward every upstream path, so the exposed surface cannot be read from configuration. The routes callers actually use have to be established with the operator or from traffic.", + "shapeDigest": "sha256:e71dfd05d5ce3a52b1909a720f393641f7fbbe9baf92f6f870a0e6ec9b7e2f95", + "source": { + "aspect": "publishedSurface", + "assetId": "model:meta-ai", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": "model.create", + "capabilityLimitations": [ + "Explicit selected models/operations only. No Foundry onboarding side effects or implicit aliases; callable routes require separate alias nodes." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "catalogue": [], + "discoverySource": "modelsEndpoint", + "notes": [ + "openAiCompatible speaks the OpenAI protocol, so its model list is one GET away at https://api.meta.ai/v1/models with the backend credential. Run 'migrate-apim resolve-models' to fetch it without persisting the key." + ] + }, + "id": "item:model/meta-ai/models", + "kind": "enumerate", + "memberDigests": { + "model:meta-ai": "sha256:045cccb86a3c9ac13a677c0c540cedd6718a58c1e8a04f6aa0a14b61131227c9" + }, + "options": [ + { + "consequence": "Read the provider's catalogue with its credential.", + "value": "resolve-models" + }, + { + "consequence": "Name the models to register.", + "value": "list-models" + }, + { + "consequence": "Do not migrate this API.", + "value": "retain-in-apim" + } + ], + "proposal": "resolve-models", + "rationale": "openAiCompatible speaks the OpenAI protocol, so its model list is one GET away at https://api.meta.ai/v1/models with the backend credential. Run 'migrate-apim resolve-models' to fetch it without persisting the key.", + "shapeDigest": "sha256:d8cc1ffe446dee43ffebaff266c17add0d1d85dd9e49fd00c506631607d9ad02", + "source": { + "aspect": "modelCatalogue", + "assetId": "model:meta-ai", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": "alias.create", + "capabilityLimitations": [ + "Creates an explicit callable model name. GET-before-PUT is not atomic; no implicit piped/batch alias creation." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "surface": { + "basis": "operationTemplates", + "operationCount": 2, + "publishable": [ + { + "count": 1, + "group": "chatCompletions", + "publishable": true, + "route": "/openai/v1/chat/completions", + "samples": [ + "/chat/completions" + ], + "subresources": 0 + } + ], + "publishableCount": 1, + "status": "bounded", + "targetRoutes": [ + "/openai/v1/chat/completions", + "/openai/v1/embeddings", + "/openai/v1/responses", + "/v1/messages" + ], + "unpublishable": [ + { + "count": 1, + "group": "modelCatalogue", + "publishable": false, + "route": null, + "samples": [ + "/models" + ], + "subresources": 0 + } + ], + "unpublishableCount": 1 + } + }, + "id": "item:model/finance/model-api/surface", + "kind": "reduce-surface", + "memberDigests": { + "model:finance/model-api": "sha256:f0460375fc9b1169a3692ea83ee5f0fdc05479786a1ee77ba912c9a0e2299464" + }, + "options": [ + { + "consequence": "Inference moves; 1 operations stay on APIM.", + "value": "split" + }, + { + "consequence": "Inference moves and the rest is dropped; those callers break.", + "value": "inference-only" + }, + { + "consequence": "Nothing moves for this API.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop the migration until resolved.", + "value": "block" + } + ], + "proposal": "split", + "rationale": "1 of 2 operations map to the four publishable routes. No target for: modelCatalogue x1.", + "shapeDigest": "sha256:8d193ace4f14fc89fb6d5c5cf9968d775919978350810f797d2847a05ed141ba", + "source": { + "aspect": "publishedSurface", + "assetId": "model:finance/model-api", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "model.create", + "capabilityLimitations": [ + "Explicit selected models/operations only. No Foundry onboarding side effects or implicit aliases; callable routes require separate alias nodes." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "modelName": "claude-opus-5", + "modelVersion": null + }, + "id": "item:model/finance/model-api/model/claude-opus-5", + "kind": null, + "memberDigests": { + "model:finance/model-api": "sha256:9c2f3352b9b3cb176de3495e41bdfa74ca71cc30558e625362714e2ad171db8a" + }, + "options": [], + "proposal": null, + "rationale": "Registers claude-opus-5 from a resolved deployment.", + "shapeDigest": "sha256:a30245f530761bfb155104f1da33dc94558d0e2acc39a1f051425b3695ce4fa1", + "source": { + "aspect": "model:claude-opus-5", + "assetId": "model:finance/model-api", + "assetKind": "modelApi" + }, + "status": "ready", + "target": { + "capability": "model.create", + "objects": [ + { + "apiFormat": "AnthropicMessages", + "deploymentConfig": { + "modelName": "claude-opus-5" + }, + "name": "claude-opus-5", + "providerName": "finance-claude-backend", + "supportedEndpoints": [ + "/v1/messages" + ] + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "alias.create", + "capabilityLimitations": [ + "Creates an explicit callable model name. GET-before-PUT is not atomic; no implicit piped/batch alias creation." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "count": 1, + "members": [ + { + "backends": [ + { + "priority": 0, + "providerName": "finance-claude-backend", + "weight": 100 + } + ], + "modelName": "claude-opus-5", + "proposedAliasName": "claude-opus-5", + "supportedEndpoints": [ + "/v1/messages" + ] + } + ], + "pooled": false, + "singleMemberModels": [] + }, + "id": "item:model/finance/model-api/aliasNames", + "kind": "name", + "memberDigests": { + "claude-opus-5": "sha256:59f6b52ef3f09e1243ef6543c1db175ec2fbce577672adfe97e9f805f3f7b50f" + }, + "options": [ + { + "consequence": "Publish each model under its own name.", + "value": "use-model-names" + }, + { + "consequence": "Supply names per model; set them in this item's members.", + "value": "override" + } + ], + "proposal": "use-model-names", + "rationale": "An alias publishes the route, and its routingName is what clients send as `model`. APIM does not store it. Proposed for 1 model(s): claude-opus-5.", + "shapeDigest": "sha256:5724bebaee31ae3db183f70029051e2ab0e6ff31df530eeb6539e4fe400b7241", + "source": { + "aspect": "aliasNames", + "assetId": "model:finance/model-api", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": { + "capability": "alias.create", + "objects": [ + { + "backendModels": [ + { + "modelName": "claude-opus-5", + "priority": 0, + "providerName": "finance-claude-backend", + "resourceId": null, + "weight": 100 + } + ], + "routingName": "claude-opus-5", + "supportedEndpoints": [ + "/v1/messages" + ] + } + ] + }, + "verdict": "partial" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": "alias.create", + "capabilityLimitations": [ + "Creates an explicit callable model name. GET-before-PUT is not atomic; no implicit piped/batch alias creation." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "translation": { + "backend": [ + "anthropicMessages" + ], + "basis": { + "caveat": "Inbound dialect is inferred from operation URL templates, which are operator-configured. It is evidence, not a declaration.", + "inboundFrom": "operationTemplates", + "operationCount": 2 + }, + "inbound": [ + "openAIChatCompletions" + ], + "note": "This API accepts one dialect and calls another, so APIM is translating formats. AI Gateway publishes a model at its native endpoint instead, so callers would have to move to the backend dialect or keep a translation layer in front of the gateway.", + "status": "translating" + } + }, + "id": "item:model/finance/model-api/dialect", + "kind": "translate", + "memberDigests": { + "model:finance/model-api": "sha256:f83aa392586b99907c42384d86fa0c98d1ffecd917e4866c84a7d32f92ecd488" + }, + "options": [ + { + "consequence": "Callers move to anthropicMessages.", + "value": "move-callers" + }, + { + "consequence": "Keep APIM in front so callers are unchanged.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop until the caller impact is agreed.", + "value": "block" + } + ], + "proposal": "move-callers", + "rationale": "This API accepts one dialect and calls another, so APIM is translating formats. AI Gateway publishes a model at its native endpoint instead, so callers would have to move to the backend dialect or keep a translation layer in front of the gateway.", + "shapeDigest": "sha256:ddcc8ba3fa0dcc687d54df911ce7b5068f5de03be8a0d2358940ebd7b579901e", + "source": { + "aspect": "callerDialect", + "assetId": "model:finance/model-api", + "assetKind": "modelApi" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "mcp.create", + "capabilityLimitations": [ + "Explicit source contracts, finite versions, selection and behavior verification required; endpoint kind alone is not equivalence." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "pattern": "passthrough", + "upstream": [ + { + "backendId": "backend:support-backend", + "circuitBreaker": null, + "languageModel": null, + "mcpPath": "/mcp", + "priority": null, + "provider": null, + "resourceIdRef": null, + "secretRefs": [ + "secret:backendInline/support-backend/credentials.header.x-api-key-0" + ], + "transport": "streamableHttp", + "transportBasis": { + "basis": "transportType", + "status": "declared" + }, + "url": "https://support.contoso.com:8000", + "weight": null + } + ] + }, + "id": "item:mcp/support-mcp/registration", + "kind": null, + "memberDigests": { + "mcp:support-mcp": "sha256:f1bb491e6f8565c9162b5296a4b51e718422a683d6959fcb7e87d281d0376bf4" + }, + "options": [], + "proposal": null, + "rationale": "A passthrough MCP server registers as a tool server with its upstream endpoints.", + "shapeDigest": "sha256:e34b54f5c3a49c6fbd3c67a4a0f6fac01fb65f5d3f72694068d7d3b6a6485957", + "source": { + "aspect": "registration", + "assetId": "mcp:support-mcp", + "assetKind": "mcpServer" + }, + "status": "ready", + "target": { + "capability": "mcp.create", + "objects": [ + { + "endpoints": [ + { + "kind": "mcp", + "mcp": { + "transport": "streamableHttp", + "url": "https://support.contoso.com:8000/mcp" + }, + "namespace": "support-mcp", + "required": true + } + ], + "name": "support-mcp" + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "toolDiscovery": { + "discoveredCount": 0, + "note": "APIM proxies tools/list to the upstream server and stores no tool names. Call tools/list against the gateway or the upstream to enumerate them before writing an AI Gateway allowList or blocked list.", + "source": "upstreamMcpServer", + "status": "runtimeOnly" + } + }, + "id": "item:mcp/support-mcp/tools", + "kind": "enumerate", + "memberDigests": { + "mcp:support-mcp": "sha256:3228c57de83b7d4250bc8c5cd6a34088f3056ab72e8e4e269a16ecf223a120c9" + }, + "options": [ + { + "consequence": "Federate whatever the server exposes at runtime. If the tool list was read from the upstream rather than through APIM, the API's policies did not run, so this can widen what callers reach beyond what APIM serves today.", + "value": "accept-all" + }, + { + "consequence": "List the tools through the gateway before deciding. That list is authoritative for what the gateway will serve, because it is what callers see with APIM's policies applied.", + "value": "discover-at-runtime" + }, + { + "consequence": "Keep this server on APIM, where the current tool exposure already holds.", + "value": "retain-in-apim" + } + ], + "proposal": "accept-all", + "rationale": "APIM stores no tool names for a passthrough server, and the CLI cannot author allowList/blocked in this baseline regardless.", + "shapeDigest": "sha256:0d1242ff259c616e3d91c44c6fdf2422c81c7d6d07d5fbb04a38ffd27c1a1977", + "source": { + "aspect": "toolExposure", + "assetId": "mcp:support-mcp", + "assetKind": "mcpServer" + }, + "status": "needs-decision", + "target": {}, + "verdict": "gap" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "mcp.create", + "capabilityLimitations": [ + "Explicit source contracts, finite versions, selection and behavior verification required; endpoint kind alone is not equivalence." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "pattern": "toolProjection", + "upstream": [ + { + "backendId": null, + "priority": null, + "transport": "http", + "url": "https://orders.contoso.com", + "viaApi": "api:orders-rest", + "weight": null + } + ] + }, + "id": "item:mcp/orders-mcp/registration", + "kind": "accept-loss", + "memberDigests": { + "mcp:orders-mcp": "sha256:1ac520a88ff484e6299212cf62ab33909a121a8ceabd101a5f5d80e82cd0879a" + }, + "options": [ + { + "consequence": "", + "value": "accept" + }, + { + "consequence": "", + "value": "retain-in-apim" + }, + { + "consequence": "", + "value": "block" + } + ], + "proposal": "accept", + "rationale": "The REST contract becomes an openApi tool-server source, but APIM's per-tool policies and tool name overrides do not survive.", + "shapeDigest": "sha256:ace3fc6746bf5636c236cacc7f170db77b71dc0adf2de3af701d93d1da6a25bf", + "source": { + "aspect": "registration", + "assetId": "mcp:orders-mcp", + "assetKind": "mcpServer" + }, + "status": "needs-decision", + "target": { + "capability": "mcp.create", + "objects": [ + { + "endpoints": [ + { + "kind": "mcp", + "mcp": { + "transport": "http", + "url": "https://orders.contoso.com/mcp" + }, + "namespace": "orders-mcp", + "required": true + }, + { + "kind": "openApi", + "namespace": "orders-mcp-2", + "openApi": { + "specSource": { + "$fromExport": "orders-rest", + "type": "url" + } + }, + "required": true + } + ], + "name": "orders-mcp" + } + ] + }, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "agent": { + "id": "support-bot", + "managementPortalUrl": null, + "name": null, + "providerName": null + }, + "hosting": { + "agentId": "support-bot", + "azure": { + "accountName": "aif", + "accountResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif", + "kind": "AIServices", + "location": "westus3", + "resourceGroup": "rg-demo", + "subscriptionId": "00000000-0000-0000-0000-000000000000" + }, + "endpoint": "https://aif.services.ai.azure.com/api/projects/default-project/agents/support-bot/endpoint/protocols/a2a/", + "kind": "foundry", + "project": "default-project" + } + }, + "id": "item:agent/support-agent/registration", + "kind": "accept-loss", + "memberDigests": { + "agent:support-agent": "sha256:f8f383b95262ceef01c33d4e99d3673b746df3a7637c4657c7107a7717c9755e" + }, + "options": [ + { + "consequence": "", + "value": "retain-in-apim" + }, + { + "consequence": "", + "value": "block" + } + ], + "proposal": "retain-in-apim", + "rationale": "AI Gateway exposes no A2A building block. A2A is listed outside the confirmed typed-gateway surface.", + "shapeDigest": "sha256:dd4a23de5b2c4edcd9fb0502d7b446f80f05c1bb3d13c306578b254e82301329", + "source": { + "aspect": "registration", + "assetId": "agent:support-agent", + "assetKind": "agent" + }, + "status": "needs-decision", + "target": {}, + "verdict": "gap" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "llm-semantic-cache-lookup", + "hasExpression": false, + "members": [ + { + "arrival": [], + "assetId": "model:aoai-api", + "attributes": { + "embeddings-backend-id": "embed", + "score-threshold": "0.9" + }, + "element": "llm-semantic-cache-lookup", + "governedAt": "api", + "governedBy": "policy:api/aoai-api", + "path": "inbound/llm-semantic-cache-lookup[1]", + "policyId": "policy:api/aoai-api", + "scope": "api", + "scopeName": "aoai-api", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 1, + "target": null + }, + "id": "item:policy/2a4d61d0b3ce", + "kind": "accept-loss", + "memberDigests": { + "model:aoai-api#policy:api/aoai-api#inbound/llm-semantic-cache-lookup[1]#inbound#direct": "sha256:8b61e39f1e9a3e770856eaf588cf4998424a13d4ca11b10f66009adde9391330" + }, + "options": [ + { + "consequence": "Migrate without it and accept the reduced posture.", + "value": "accept" + }, + { + "consequence": "Replace it with a different control on the target.", + "value": "compensate" + }, + { + "consequence": "Keep this workload on APIM.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop the migration until resolved.", + "value": "block" + } + ], + "proposal": "accept", + "rationale": "No caching of any kind on the typed gateway.", + "shapeDigest": "sha256:5b57d38732057a07f45e21d49a8731b90d63cec9e967e5b5191675fb466fe14e", + "source": { + "aspect": "llm-semantic-cache-lookup", + "assetId": null, + "assetKind": "policy" + }, + "status": "needs-decision", + "target": {}, + "verdict": "gap" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "llm-content-safety", + "hasExpression": false, + "members": [ + { + "arrival": [], + "assetId": "model:aoai-api", + "attributes": { + "backend-id": "AI-CS-demo", + "shield-prompt": "true" + }, + "element": "llm-content-safety", + "governedAt": "api", + "governedBy": "policy:api/aoai-api", + "path": "inbound/llm-content-safety[1]", + "policyId": "policy:api/aoai-api", + "scope": "api", + "scopeName": "aoai-api", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 1, + "target": null + }, + "id": "item:policy/35f80ef0a2d4", + "kind": "accept-loss", + "memberDigests": { + "model:aoai-api#policy:api/aoai-api#inbound/llm-content-safety[1]#inbound#direct": "sha256:e1d61e4ed9e5cf312548163ccdd1851f42d5883c4395473fd839bfbc1a789fba" + }, + "options": [ + { + "consequence": "Migrate without it and accept the reduced posture.", + "value": "accept" + }, + { + "consequence": "Replace it with a different control on the target.", + "value": "compensate" + }, + { + "consequence": "Keep this workload on APIM.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop the migration until resolved.", + "value": "block" + } + ], + "proposal": "retain-in-apim", + "rationale": "Content-safety flags are visible in the CLI but are not supported on typed aigateways. The policy also pulls in a separate Content Safety backend.", + "shapeDigest": "sha256:5b57d38732057a07f45e21d49a8731b90d63cec9e967e5b5191675fb466fe14e", + "source": { + "aspect": "llm-content-safety", + "assetId": null, + "assetKind": "policy" + }, + "status": "needs-decision", + "target": {}, + "verdict": "gap" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "policy.update", + "capabilityLimitations": [ + "Default-workspace scope, not per-API/product access. Sibling types are preserved. Missing workspace ETag permits an unconditional write; freshness/read-back are not atomic concurrency protection." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "rate-limit-by-key", + "hasExpression": true, + "members": [ + { + "arrival": [], + "assetId": "mcp:support-mcp", + "attributes": { + "calls": "60", + "counter-key": "@(context.Subscription.Id)", + "renewal-period": "60" + }, + "element": "rate-limit-by-key", + "governedAt": "api", + "governedBy": "policy:api/support-mcp", + "path": "inbound/rate-limit-by-key[1]", + "policyId": "policy:api/support-mcp", + "scope": "api", + "scopeName": "support-mcp", + "section": "inbound", + "underConditional": false, + "via": [] + }, + { + "arrival": [], + "assetId": "mcp:orders-mcp", + "attributes": { + "calls": "60", + "counter-key": "@(context.Subscription.Id)", + "renewal-period": "60" + }, + "element": "rate-limit-by-key", + "governedAt": "api", + "governedBy": "policy:api/orders-mcp", + "path": "inbound/rate-limit-by-key[1]", + "policyId": "policy:api/orders-mcp", + "scope": "api", + "scopeName": "orders-mcp", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 2, + "target": "requestRateLimit" + }, + "id": "item:policy/47fe6143c36c", + "kind": "translate", + "memberDigests": { + "mcp:orders-mcp#policy:api/orders-mcp#inbound/rate-limit-by-key[1]#inbound#direct": "sha256:93180bc637aebcc525539a99d1477ed1cb04ef81723c98bb2dd9182c1070cdd7", + "mcp:support-mcp#policy:api/support-mcp#inbound/rate-limit-by-key[1]#inbound#direct": "sha256:a7045e5ec362e11bee5b59354db976d45c9883775324e341ed9618ad683048a7" + }, + "options": [ + { + "consequence": "", + "value": "identity" + }, + { + "consequence": "", + "value": "ipAddress" + }, + { + "consequence": "", + "value": "identity+ipAddress" + }, + { + "consequence": "", + "value": "pooled" + } + ], + "proposal": "identity", + "rationale": "APIM counter-key is an arbitrary expression; AI Gateway partitions by identity, IP, both, or a single pooled counter. @(context.Subscription.Id) is close to identity but not identical.", + "shapeDigest": "sha256:9383630f7f9d4f2034c8f95d396b2deaaece03d8c75017e15a194d1e5a7c285f", + "source": { + "aspect": "rate-limit-by-key", + "assetId": null, + "assetKind": "policy" + }, + "status": "needs-decision", + "target": { + "capability": "policy.update", + "objects": [ + { + "configurationComplete": true, + "fullConfigurationAt": { + "path": "inbound/rate-limit-by-key[1]", + "policyId": "policy:api/support-mcp" + }, + "scope": { + "level": "gateway", + "name": "default" + }, + "settings": { + "callsPerPeriod": "60", + "counterKey": "@(context.Subscription.Id)", + "periodSeconds": "60" + }, + "type": "requestRateLimit", + "unmappedAttributes": {} + } + ] + }, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "model.policy", + "capabilityLimitations": [ + "Requires model ETag and sends If-Match; service enforcement requires authorized verification. Counters are identity/ipAddress arrays. Preserve siblings and inherited scope explicitly; cost limits are optional governance, not APIM quota equivalence." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "azure-openai-token-limit", + "hasExpression": true, + "members": [ + { + "arrival": [], + "assetId": "model:aoai-api", + "attributes": { + "counter-key": "@(context.Subscription.Id)", + "estimate-prompt-tokens": "false", + "tokens-per-minute": "30000" + }, + "element": "azure-openai-token-limit", + "governedAt": "api", + "governedBy": "policy:api/aoai-api", + "path": "inbound/azure-openai-token-limit[1]", + "policyId": "policy:api/aoai-api", + "scope": "api", + "scopeName": "aoai-api", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 1, + "target": "tokenLimit" + }, + "id": "item:policy/776f3ec27e55", + "kind": "translate", + "memberDigests": { + "model:aoai-api#policy:api/aoai-api#inbound/azure-openai-token-limit[1]#inbound#direct": "sha256:549f258c3c20722883fe944cf5372ddf07c8d4b0d259c35c3d7e8b7770b7c9e6" + }, + "options": [ + { + "consequence": "", + "value": "identity" + }, + { + "consequence": "", + "value": "ipAddress" + }, + { + "consequence": "", + "value": "identity+ipAddress" + }, + { + "consequence": "", + "value": "pooled" + } + ], + "proposal": "identity", + "rationale": "The counter partitions by an arbitrary expression in APIM; the target partitions by identity, IP, both, or one pooled counter. @(context.Subscription.Id) is close to identity but not identical. The source also sets estimate-prompt-tokens, which the target has no field for: applying this carries the rest and leaves those behind.", + "shapeDigest": "sha256:af4a90487d6a0d563940826698b50975568520d625087b59992e009e20b8ffef", + "source": { + "aspect": "azure-openai-token-limit", + "assetId": null, + "assetKind": "policy" + }, + "status": "needs-decision", + "target": { + "capability": "model.policy", + "objects": [ + { + "configurationComplete": true, + "fullConfigurationAt": { + "path": "inbound/azure-openai-token-limit[1]", + "policyId": "policy:api/aoai-api" + }, + "modelName": "gpt-5", + "providerName": "aoai-east", + "scope": { + "level": "api", + "name": "aoai-api" + }, + "settings": { + "count": "30000", + "counterKey": "@(context.Subscription.Id)" + }, + "type": "tokenLimit", + "unmappedAttributes": { + "estimate-prompt-tokens": "false" + } + }, + { + "configurationComplete": true, + "fullConfigurationAt": { + "path": "inbound/azure-openai-token-limit[1]", + "policyId": "policy:api/aoai-api" + }, + "modelName": "text-embedding-3-large", + "providerName": "aoai-east", + "scope": { + "level": "api", + "name": "aoai-api" + }, + "settings": { + "count": "30000", + "counterKey": "@(context.Subscription.Id)" + }, + "type": "tokenLimit", + "unmappedAttributes": { + "estimate-prompt-tokens": "false" + } + }, + { + "configurationComplete": true, + "fullConfigurationAt": { + "path": "inbound/azure-openai-token-limit[1]", + "policyId": "policy:api/aoai-api" + }, + "modelName": "gpt-5", + "providerName": "aoai-west", + "scope": { + "level": "api", + "name": "aoai-api" + }, + "settings": { + "count": "30000", + "counterKey": "@(context.Subscription.Id)" + }, + "type": "tokenLimit", + "unmappedAttributes": { + "estimate-prompt-tokens": "false" + } + } + ] + }, + "unmappedAttributes": [ + "estimate-prompt-tokens" + ], + "verdict": "partial" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "set-header", + "hasExpression": false, + "members": [ + { + "arrival": [], + "assetId": "mcp:support-mcp", + "attributes": { + "exists-action": "override", + "name": "x-mcp-caller" + }, + "element": "set-header", + "governedAt": "api", + "governedBy": "policy:api/support-mcp", + "path": "inbound/set-header[1]", + "policyId": "policy:api/support-mcp", + "scope": "api", + "scopeName": "support-mcp", + "section": "inbound", + "underConditional": false, + "via": [] + }, + { + "arrival": [], + "assetId": "mcp:orders-mcp", + "attributes": { + "exists-action": "override", + "name": "x-mcp-caller" + }, + "element": "set-header", + "governedAt": "api", + "governedBy": "policy:api/orders-mcp", + "path": "inbound/set-header[1]", + "policyId": "policy:api/orders-mcp", + "scope": "api", + "scopeName": "orders-mcp", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 2, + "target": null + }, + "id": "item:policy/800b18024fa2", + "kind": "accept-loss", + "memberDigests": { + "mcp:orders-mcp#policy:api/orders-mcp#inbound/set-header[1]#inbound#direct": "sha256:e9b76db8a16bd08987d82f31d24c4d1ab0ee74e1e97dbd29cfa61df57ea3a066", + "mcp:support-mcp#policy:api/support-mcp#inbound/set-header[1]#inbound#direct": "sha256:a027c322e818f45d954371c9242dc825288c0f796cb5911fb6387a18b9643ade" + }, + "options": [ + { + "consequence": "Migrate without it and accept the reduced posture.", + "value": "accept" + }, + { + "consequence": "Replace it with a different control on the target.", + "value": "compensate" + }, + { + "consequence": "Keep this workload on APIM.", + "value": "retain-in-apim" + }, + { + "consequence": "Stop the migration until resolved.", + "value": "block" + } + ], + "proposal": "accept", + "rationale": "No request or response rewriting on the target.", + "shapeDigest": "sha256:5b57d38732057a07f45e21d49a8731b90d63cec9e967e5b5191675fb466fe14e", + "source": { + "aspect": "set-header", + "assetId": null, + "assetKind": "policy" + }, + "status": "needs-decision", + "target": {}, + "verdict": "gap" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "policy.update", + "capabilityLimitations": [ + "Default-workspace scope, not per-API/product access. Sibling types are preserved. Missing workspace ETag permits an unconditional write; freshness/read-back are not atomic concurrency protection." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "ip-filter", + "hasExpression": false, + "members": [ + { + "arrival": [], + "assetId": "mcp:support-mcp", + "attributes": { + "action": "allow" + }, + "element": "ip-filter", + "governedAt": "api", + "governedBy": "policy:api/support-mcp", + "path": "inbound/ip-filter[1]", + "policyId": "policy:api/support-mcp", + "scope": "api", + "scopeName": "support-mcp", + "section": "inbound", + "underConditional": false, + "via": [] + }, + { + "arrival": [], + "assetId": "mcp:orders-mcp", + "attributes": { + "action": "allow" + }, + "element": "ip-filter", + "governedAt": "api", + "governedBy": "policy:api/orders-mcp", + "path": "inbound/ip-filter[1]", + "policyId": "policy:api/orders-mcp", + "scope": "api", + "scopeName": "orders-mcp", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 2, + "target": "ipFilter" + }, + "id": "item:policy/8d815c427612", + "kind": "accept-loss", + "memberDigests": { + "mcp:orders-mcp#policy:api/orders-mcp#inbound/ip-filter[1]#inbound#direct": "sha256:57ed02f468a2cbee06a9aa8af323ae0753248652f8001d52bdeeaf0945dae56b", + "mcp:support-mcp#policy:api/support-mcp#inbound/ip-filter[1]#inbound#direct": "sha256:8d6a2cf2495721400242d4af3d8c9c6386882d3e1f6bd7ef011fa8bb4b9669ae" + }, + "options": [], + "proposal": null, + "rationale": "`ip-filter` maps to the target's `ipFilter` policy.", + "shapeDigest": "sha256:866d8e2e45b85f370c20eae2dd26384825a83697b3b0bcf3976a7cf10a1f9fd5", + "source": { + "aspect": "ip-filter", + "assetId": null, + "assetKind": "policy" + }, + "status": "ready", + "target": { + "capability": "policy.update", + "objects": [ + { + "configurationComplete": true, + "fullConfigurationAt": { + "path": "inbound/ip-filter[1]", + "policyId": "policy:api/support-mcp" + }, + "scope": { + "level": "gateway", + "name": "default" + }, + "settings": { + "action": "allow", + "ranges": [ + "10.0.0.0/24" + ] + }, + "type": "ipFilter", + "unmappedAttributes": {} + } + ] + }, + "verdict": "native" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "element": "azure-openai-emit-token-metric", + "hasExpression": false, + "members": [ + { + "arrival": [], + "assetId": "model:aoai-api", + "attributes": { + "namespace": "llm" + }, + "element": "azure-openai-emit-token-metric", + "governedAt": "api", + "governedBy": "policy:api/aoai-api", + "path": "inbound/azure-openai-emit-token-metric[1]", + "policyId": "policy:api/aoai-api", + "scope": "api", + "scopeName": "aoai-api", + "section": "inbound", + "underConditional": false, + "via": [] + } + ], + "occurrences": 1, + "target": null + }, + "id": "item:policy/ec722b61308c", + "kind": "accept-loss", + "memberDigests": { + "model:aoai-api#policy:api/aoai-api#inbound/azure-openai-emit-token-metric[1]#inbound#direct": "sha256:20d40c54d2614c6881179f0463e2b890f07187de9329f693cf5b4cdf73a52fca" + }, + "options": [ + { + "consequence": "", + "value": "accept" + }, + { + "consequence": "", + "value": "compensate" + }, + { + "consequence": "", + "value": "retain-in-apim" + } + ], + "proposal": "accept", + "rationale": "Token metrics are emitted by the gateway, but custom dimensions do not carry over one for one. Where the telemetry goes is a separate decision, on the telemetry destination item.", + "shapeDigest": "sha256:53997e24500db34ff672385fa830641ef6accd538dcbed48d98674bb64a05a5a", + "source": { + "aspect": "azure-openai-emit-token-metric", + "assetId": null, + "assetKind": "policy" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "disposition": "dissolved", + "elementCount": 1, + "fragment": "killswitch", + "includedBy": [ + { + "assetId": "mcp:support-mcp", + "policyId": "policy:api/support-mcp", + "scopeLevel": "api", + "section": "inbound", + "underConditional": false, + "via": [ + "policy:fragment/killswitch" + ] + }, + { + "assetId": "mcp:orders-mcp", + "policyId": "policy:api/orders-mcp", + "scopeLevel": "api", + "section": "inbound", + "underConditional": false, + "via": [ + "policy:fragment/killswitch" + ] + } + ], + "operationPoliciesCollected": false, + "parseError": null, + "sections": [ + "inbound" + ] + }, + "id": "item:fragment/policy-fragment/killswitch", + "kind": null, + "memberDigests": { + "policy:fragment/killswitch": "sha256:03676cf8baf2457d683dd14353e818a85f4f279518221f3cc7e3d02e4e1bfed4" + }, + "options": [], + "proposal": null, + "rationale": "AI Gateway has no policy composition: no fragments, no includes, no inheritance. A fragment is therefore dissolved into every scope that includes it, and what it carries is assessed as the elements of that scope. Listed so a reader can see the fragment reached the plan rather than having to infer it from the policies it contributed.", + "shapeDigest": "sha256:985bba75ef3e9492c6d88e228bbc97fcf8fa98938a61ee297df2e630eaa1b791", + "source": { + "aspect": "killswitch", + "assetId": "policy:fragment/killswitch", + "assetKind": "policyFragment" + }, + "status": "excluded", + "target": {}, + "verdict": "handled" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": null, + "decidedAgainst": null, + "decision": null, + "evidence": { + "workspace": { + "collected": true, + "description": "", + "displayName": "finance", + "name": "finance", + "serveOn": "workspaceAndDefault" + } + }, + "id": "item:workspace/finance", + "kind": "collapse", + "memberDigests": { + "item:workspace/finance": "sha256:108d6d342392ed0ed72fd4c838a0777c13e73bfbca52214ad4c9a4f77ae60b9a" + }, + "options": [ + { + "consequence": "", + "value": "flatten" + }, + { + "consequence": "", + "value": "retain-in-apim" + }, + { + "consequence": "", + "value": "block" + } + ], + "proposal": "flatten", + "rationale": "AI Gateway configures the implicit default workspace only. Flattening can collide with same-named assets in other workspaces.", + "shapeDigest": "sha256:ee62d1f6e1dc46b66d50c4d0813f48f065d667780ef8e6984542918aa6b6c90e", + "source": { + "aspect": "finance", + "assetId": null, + "assetKind": "workspace" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": true, + "cannotAccept": false, + "capabilityId": "key.create", + "capabilityLimitations": [ + "Creates new gateway-wide key metadata, not imported APIM secrets or per-API access. Does not read key values." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "count": 2, + "scopeLevels": [ + "product", + "service" + ] + }, + "id": "item:access/subscriptions", + "kind": "scope", + "memberDigests": { + "item:access/subscriptions": "sha256:a4375c884d07f3bc9be51e144ad785efaf1743eb5a2cd8156e05185146bfc7ea" + }, + "options": [ + { + "consequence": "", + "value": "gateway-key-per-consumer" + }, + { + "consequence": "", + "value": "entra-rbac" + }, + { + "consequence": "", + "value": "retain-in-apim" + } + ], + "proposal": "entra-rbac", + "rationale": "APIM subscription keys are scoped per product, per API, or service-wide. AI Gateway keys are gateway-wide and no key value can be imported, so every caller is re-keyed.", + "shapeDigest": "sha256:1d79f2a20fa666b7a9dbc80c34fb1a287aef6f682950c78ccb80f6e41d2d54da", + "source": { + "aspect": "subscriptions", + "assetId": null, + "assetKind": "access" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + }, + { + "blocking": false, + "cannotAccept": false, + "capabilityId": "telemetry.create", + "capabilityLimitations": [ + "Reviewed ApplicationInsights connectionString input only; OpenTelemetry/free-form telemetry fields lack a reviewed child schema. Runtime-only credentials, explicit payload capture, and existing external telemetry resources." + ], + "decidedAgainst": null, + "decision": null, + "evidence": { + "apimLoggers": [] + }, + "id": "item:telemetry/destination", + "kind": "translate", + "memberDigests": { + "item:telemetry/destination": "sha256:44a76fab9f244e58d38ac8c4e3594b470748a2047f93320859ed42b7dc0626f0" + }, + "options": [ + { + "consequence": "Enable the OTLP endpoint on the Application Insights resource APIM already reports to. Both products' telemetry stays in one place, and enabling it changes a resource other workloads may share.", + "value": "reuse-appinsights" + }, + { + "consequence": "Create an Application Insights resource with the OTLP endpoint enabled, for the gateway alone. Nothing shared changes; existing dashboards and alerts do not cover the gateway until they are rebuilt.", + "value": "new-appinsights" + }, + { + "consequence": "No exporter. The gateway's own metrics are the only telemetry, and nothing reports into Application Insights.", + "value": "gateway-metrics-only" + }, + { + "consequence": "Keep this workload on APIM, reporting as it does now.", + "value": "retain-in-apim" + } + ], + "proposal": "reuse-appinsights", + "rationale": "APIM reports to Azure Application Insights and the gateway exports OpenTelemetry. The only surface both support is the OTLP endpoint on an Application Insights resource. This question asks where that is: reuse the resource APIM already reports to, create a new one for the gateway alone, configure the gateway only, or keep both separate.", + "shapeDigest": "sha256:3860a0d45492799823ef848d18f79ee7d792daeff7fb34b8b8f351b1341ca80e", + "source": { + "aspect": "destination", + "assetId": null, + "assetKind": "telemetry" + }, + "status": "needs-decision", + "target": {}, + "verdict": "partial" + } + ], + "kind": "apimMigrationPlan", + "orphanedDecisions": [], + "plannerGaps": [], + "policyCoverage": { + "dispositions": { + "classified": 10, + "configuration": 8, + "handled": 1, + "notApplicable": 15 + }, + "unrecognised": [], + "walked": 34 + }, + "prerequisites": [ + { + "commands": [ + { + "command": "az role assignment create --role 'Foundry User' --assignee-object-id --assignee-principal-type ServicePrincipal --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif", + "principalFrom": "az aigateway show ... --query identity.principalId -o tsv, after the identity phase", + "roleDefinitionId": "53ca6127-db72-4b80-b1b0-d745d6d5456d", + "scope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.CognitiveServices/accounts/aif" + } + ], + "detail": "A provider using ManagedIdentity needs a role assignment on the backend account, and role assignments are outside the gateway resource provider. The target's system-assigned identity is a new principal, so the source's existing grants do not apply to it.", + "id": "prereq:foundry-rbac", + "owner": "azure-administrator", + "summary": "Grant the gateway identity data-plane access on each Foundry account" + }, + { + "commands": [], + "detail": "APIM sends telemetry to Azure Application Insights; AI Gateway sends it through an OpenTelemetry exporter. The only surface both support is the OTLP endpoint on the Application Insights resource, which is off until someone turns it on. Enable it on the existing resource, or create one with it enabled, then settle the telemetry item on an OpenTelemetry exporter pointed at it. Without that endpoint there is no path at all, and the gateway's own metrics are the only telemetry the migration produces.", + "id": "prereq:appinsights-otlp", + "owner": "azure-administrator", + "summary": "Enable the OTLP endpoint on the Application Insights resource APIM reports to" + }, + { + "commands": [ + { + "command": "az role assignment create --role 'AI Gateway Models User' --assignee --scope ", + "note": "Use 'AI Gateway Tools User' for MCP callers, or 'AI Gateway User' for both.", + "roleDefinitionId": "a6b68e3d-a1f0-4c60-8678-237c050cf4ea" + } + ], + "detail": "A management role such as Contributor does not imply runtime invocation access.", + "id": "prereq:caller-rbac", + "owner": "azure-administrator", + "summary": "Assign callers AI Gateway Models User / Tools User at the right scope" + }, + { + "detail": "Several CLI commands dispatch by name without --ids, and in a migration the source APIM and the target gateway plausibly share a name.", + "id": "prereq:name-collision", + "owner": "migrate-apim", + "summary": "Preflight the target name against Microsoft.ApiManagement/service" + } + ], + "schemaVersion": "1.0", + "source": { + "name": "apim-demo", + "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-demo/providers/Microsoft.ApiManagement/service/apim-demo" + }, + "summary": { + "blocking": 10, + "byKind": { + "accept-loss": 6, + "collapse": 1, + "enumerate": 2, + "name": 2, + "reduce-surface": 3, + "scope": 1, + "translate": 4 + }, + "byStatus": { + "excluded": 1, + "needs-decision": 19, + "ready": 11 + }, + "orphanedDecisions": 0, + "plannerGaps": 0, + "total": 31, + "unsettled": 19 + }, + "target": { + "capabilities": { + "capabilities": { + "alias.create": "declared", + "alias.update": "declared", + "alias.verify": "declared", + "connection.update": "declared", + "connection.verify": "declared", + "gateway.create": "declared", + "gateway.verify": "declared", + "identity.assign": "declared", + "key.create": "declared", + "key.update": "declared", + "key.verify": "declared", + "mcp.create": "declared", + "mcp.source.add": "declared", + "mcp.update": "declared", + "mcp.verify": "declared", + "model-policy.verify": "declared", + "model.create": "declared", + "model.policy": "declared", + "model.update": "declared", + "model.verify": "declared", + "network.update": "declared", + "network.verify": "declared", + "policy.update": "declared", + "policy.verify": "declared", + "provider.create": "declared", + "provider.import": "declared", + "provider.update": "declared", + "provider.verify": "declared", + "telemetry.create": "declared", + "telemetry.update": "declared", + "telemetry.verify": "declared" + }, + "catalog": "aigateway-1.0.0b31", + "cliVersion": "1.0.0b31", + "probed": false, + "serviceOnly": [ + "alias-selection-order", + "alias-session-affinity", + "alias-auto-model-selection" + ], + "unsupported": [ + "subscription-key-copy", + "products", + "arbitrary-policy-xml", + "workspace-creation", + "bulk-provider-sync-apply", + "source-sku-conversion", + "client-cutover", + "external-resource-provisioning", + "automatic-foundry-rbac", + "api-key-rename", + "opaque-cost-overrides" + ] + }, + "publishableRoutes": [ + "/openai/v1/chat/completions", + "/openai/v1/responses", + "/openai/v1/embeddings", + "/v1/messages" + ], + "resourceId": null + } + }, + "resolution": { + "authentication-basic|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A model provider authenticates with a managed identity or an API key. `model-provider create` and `model-provider update` expose no basic credential, no client certificate, and nothing equivalent to an APIM credential manager, so a backend secured any other way has no target. `authentication-managed-identity` is the one member of this family that does map, and it has a rule of its own.\", \"verdict\": \"gap\"}", + "authentication-basic|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A model provider authenticates with a managed identity or an API key. `model-provider create` and `model-provider update` expose no basic credential, no client certificate, and nothing equivalent to an APIM credential manager, so a backend secured any other way has no target. `authentication-managed-identity` is the one member of this family that does map, and it has a rule of its own.\", \"verdict\": \"gap\"}", + "authentication-certificate|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A model provider authenticates with a managed identity or an API key. `model-provider create` and `model-provider update` expose no basic credential, no client certificate, and nothing equivalent to an APIM credential manager, so a backend secured any other way has no target. `authentication-managed-identity` is the one member of this family that does map, and it has a rule of its own.\", \"verdict\": \"gap\"}", + "authentication-certificate|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A model provider authenticates with a managed identity or an API key. `model-provider create` and `model-provider update` expose no basic credential, no client certificate, and nothing equivalent to an APIM credential manager, so a backend secured any other way has no target. `authentication-managed-identity` is the one member of this family that does map, and it has a rule of its own.\", \"verdict\": \"gap\"}", + "authentication-managed-identity|expr=False": "{\"capabilityId\": \"provider.create\", \"rationale\": \"Becomes provider authentication configuration. Carried by the model provider item rather than raised again here.\", \"target\": \"provider.authentication.ManagedIdentity\", \"verdict\": \"handled\"}", + "authentication-managed-identity|expr=True": "{\"capabilityId\": \"provider.create\", \"rationale\": \"Becomes provider authentication configuration. Carried by the model provider item rather than raised again here.\", \"target\": \"provider.authentication.ManagedIdentity\", \"verdict\": \"handled\"}", + "azure-openai-content-safety|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Content-safety flags are visible in the CLI but are not supported on typed aigateways. The policy also pulls in a separate Content Safety backend.\", \"verdict\": \"gap\"}", + "azure-openai-content-safety|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Content-safety flags are visible in the CLI but are not supported on typed aigateways. The policy also pulls in a separate Content Safety backend.\", \"verdict\": \"gap\"}", + "azure-openai-emit-token-metric|expr=False": "{\"itemKind\": \"accept-loss\", \"options\": [\"accept\", \"compensate\", \"retain-in-apim\"], \"proposal\": \"accept\", \"rationale\": \"Token metrics are emitted by the gateway, but custom dimensions do not carry over one for one. Where the telemetry goes is a separate decision, on the telemetry destination item.\", \"verdict\": \"partial\"}", + "azure-openai-emit-token-metric|expr=True": "{\"itemKind\": \"accept-loss\", \"options\": [\"accept\", \"compensate\", \"retain-in-apim\"], \"proposal\": \"accept\", \"rationale\": \"Token metrics are emitted by the gateway, but custom dimensions do not carry over one for one. Where the telemetry goes is a separate decision, on the telemetry destination item.\", \"verdict\": \"partial\"}", + "azure-openai-semantic-cache-lookup|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "azure-openai-semantic-cache-lookup|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "azure-openai-semantic-cache-store|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "azure-openai-semantic-cache-store|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "azure-openai-token-limit|expr=False": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"model.policy\", \"partial\": {\"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"The counter partitions by an arbitrary expression in APIM; the target partitions by identity, IP, both, or one pooled counter. @(context.Subscription.Id) is close to identity but not identical.\"}, \"partialWhen\": {\"attributeIsExpression\": \"counter-key\"}, \"target\": \"tokenLimit\", \"verdict\": \"native\"}", + "azure-openai-token-limit|expr=True": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"model.policy\", \"partial\": {\"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"The counter partitions by an arbitrary expression in APIM; the target partitions by identity, IP, both, or one pooled counter. @(context.Subscription.Id) is close to identity but not identical.\"}, \"partialWhen\": {\"attributeIsExpression\": \"counter-key\"}, \"target\": \"tokenLimit\", \"verdict\": \"native\"}", + "base|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "base|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "cache-lookup-value|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-lookup-value|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-lookup|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-lookup|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-store-value|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-store-value|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-store|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "cache-store|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "check-header|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Caller authentication on the gateway is Entra auth plus data-plane RBAC, or an API key. A gate on a shared secret in a header, or on a client certificate, is neither. `validate-jwt` and `validate-azure-ad-token` are the members of this family that do map, and they have a rule of their own.\", \"verdict\": \"gap\"}", + "check-header|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Caller authentication on the gateway is Entra auth plus data-plane RBAC, or an API key. A gate on a shared secret in a header, or on a client certificate, is neither. `validate-jwt` and `validate-azure-ad-token` are the members of this family that do map, and they have a rule of their own.\", \"verdict\": \"gap\"}", + "choose|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "choose|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "cors|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "cors|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "emit-metric|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"The gateway reports through a telemetry exporter it owns: `telemetry-exporter create` takes a kind and an endpoint, not a metric to emit or a sink to write to. There is no Event Hub destination and no way to author a custom metric. Where the gateway's own telemetry reports is a separate decision, on the telemetry destination item.\", \"verdict\": \"gap\"}", + "emit-metric|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"The gateway reports through a telemetry exporter it owns: `telemetry-exporter create` takes a kind and an endpoint, not a metric to emit or a sink to write to. There is no Event Hub destination and no way to author a custom metric. Where the gateway's own telemetry reports is a separate decision, on the telemetry destination item.\", \"verdict\": \"gap\"}", + "find-and-replace|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "find-and-replace|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "forward-request|expr=False": "{\"capabilityId\": \"alias.create\", \"partial\": {\"itemKind\": \"accept-loss\", \"options\": [{\"consequence\": \"Every call takes the alias backend pool in its own order, whatever the source would have chosen for it.\", \"value\": \"accept\"}, {\"consequence\": \"Say what the condition was for in the priority and weight of the alias backend models, as far as it can be said that way.\", \"value\": \"compensate\"}, {\"consequence\": \"Keep this workload on APIM, where the routing logic still runs.\", \"value\": \"retain-in-apim\"}], \"proposal\": \"compensate\", \"rationale\": \"The source decides where the request goes with logic the target has no place for: a policy expression, a branch of a `choose`, or both. The alias backend pool carries the set of backends and their priority and weight, not the rule that picked among them.\"}, \"partialWhen\": {\"hasExpression\": true, \"underConditional\": true}, \"rationale\": \"Backend selection becomes the alias backend pool.\", \"verdict\": \"handled\"}", + "forward-request|expr=True": "{\"capabilityId\": \"alias.create\", \"partial\": {\"itemKind\": \"accept-loss\", \"options\": [{\"consequence\": \"Every call takes the alias backend pool in its own order, whatever the source would have chosen for it.\", \"value\": \"accept\"}, {\"consequence\": \"Say what the condition was for in the priority and weight of the alias backend models, as far as it can be said that way.\", \"value\": \"compensate\"}, {\"consequence\": \"Keep this workload on APIM, where the routing logic still runs.\", \"value\": \"retain-in-apim\"}], \"proposal\": \"compensate\", \"rationale\": \"The source decides where the request goes with logic the target has no place for: a policy expression, a branch of a `choose`, or both. The alias backend pool carries the set of backends and their priority and weight, not the rule that picked among them.\"}, \"partialWhen\": {\"hasExpression\": true, \"underConditional\": true}, \"rationale\": \"Backend selection becomes the alias backend pool.\", \"verdict\": \"handled\"}", + "get-authorization-context|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A model provider authenticates with a managed identity or an API key. `model-provider create` and `model-provider update` expose no basic credential, no client certificate, and nothing equivalent to an APIM credential manager, so a backend secured any other way has no target. `authentication-managed-identity` is the one member of this family that does map, and it has a rule of its own.\", \"verdict\": \"gap\"}", + "get-authorization-context|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A model provider authenticates with a managed identity or an API key. `model-provider create` and `model-provider update` expose no basic credential, no client certificate, and nothing equivalent to an APIM credential manager, so a backend secured any other way has no target. `authentication-managed-identity` is the one member of this family that does map, and it has a rule of its own.\", \"verdict\": \"gap\"}", + "include-fragment|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "include-fragment|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "ip-filter|expr=False": "{\"batchOn\": [\"action\"], \"capabilityId\": \"policy.update\", \"target\": \"ipFilter\", \"verdict\": \"native\"}", + "ip-filter|expr=True": "{\"batchOn\": [\"action\"], \"capabilityId\": \"policy.update\", \"target\": \"ipFilter\", \"verdict\": \"native\"}", + "json-to-xml|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "json-to-xml|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "limit-concurrency|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"costLimit is a dollar budget, not a call quota or a concurrency ceiling.\", \"verdict\": \"gap\"}", + "limit-concurrency|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"costLimit is a dollar budget, not a call quota or a concurrency ceiling.\", \"verdict\": \"gap\"}", + "llm-content-safety|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Content-safety flags are visible in the CLI but are not supported on typed aigateways. The policy also pulls in a separate Content Safety backend.\", \"verdict\": \"gap\"}", + "llm-content-safety|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Content-safety flags are visible in the CLI but are not supported on typed aigateways. The policy also pulls in a separate Content Safety backend.\", \"verdict\": \"gap\"}", + "llm-emit-token-metric|expr=False": "{\"itemKind\": \"accept-loss\", \"options\": [\"accept\", \"compensate\", \"retain-in-apim\"], \"proposal\": \"accept\", \"rationale\": \"Token metrics are emitted by the gateway, but custom dimensions do not carry over one for one. Where the telemetry goes is a separate decision, on the telemetry destination item.\", \"verdict\": \"partial\"}", + "llm-emit-token-metric|expr=True": "{\"itemKind\": \"accept-loss\", \"options\": [\"accept\", \"compensate\", \"retain-in-apim\"], \"proposal\": \"accept\", \"rationale\": \"Token metrics are emitted by the gateway, but custom dimensions do not carry over one for one. Where the telemetry goes is a separate decision, on the telemetry destination item.\", \"verdict\": \"partial\"}", + "llm-semantic-cache-lookup|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "llm-semantic-cache-lookup|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "llm-semantic-cache-store|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "llm-semantic-cache-store|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No caching of any kind on the typed gateway.\", \"verdict\": \"gap\"}", + "llm-token-limit|expr=False": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"model.policy\", \"partial\": {\"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"The counter partitions by an arbitrary expression in APIM; the target partitions by identity, IP, both, or one pooled counter. @(context.Subscription.Id) is close to identity but not identical.\"}, \"partialWhen\": {\"attributeIsExpression\": \"counter-key\"}, \"target\": \"tokenLimit\", \"verdict\": \"native\"}", + "llm-token-limit|expr=True": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"model.policy\", \"partial\": {\"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"The counter partitions by an arbitrary expression in APIM; the target partitions by identity, IP, both, or one pooled counter. @(context.Subscription.Id) is close to identity but not identical.\"}, \"partialWhen\": {\"attributeIsExpression\": \"counter-key\"}, \"target\": \"tokenLimit\", \"verdict\": \"native\"}", + "log-to-eventhub|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"The gateway reports through a telemetry exporter it owns: `telemetry-exporter create` takes a kind and an endpoint, not a metric to emit or a sink to write to. There is no Event Hub destination and no way to author a custom metric. Where the gateway's own telemetry reports is a separate decision, on the telemetry destination item.\", \"verdict\": \"gap\"}", + "log-to-eventhub|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"The gateway reports through a telemetry exporter it owns: `telemetry-exporter create` takes a kind and an endpoint, not a metric to emit or a sink to write to. There is no Event Hub destination and no way to author a custom metric. Where the gateway's own telemetry reports is a separate decision, on the telemetry destination item.\", \"verdict\": \"gap\"}", + "mcp-server|expr=False": "{\"capabilityId\": \"mcp.create\", \"rationale\": \"The tool server this policy exposes is collected as an MCP asset from the API that carries it, and registered by the MCP server item rather than raised again here.\", \"verdict\": \"handled\"}", + "mcp-server|expr=True": "{\"capabilityId\": \"mcp.create\", \"rationale\": \"The tool server this policy exposes is collected as an MCP asset from the API that carries it, and registered by the MCP server item rather than raised again here.\", \"verdict\": \"handled\"}", + "otherwise|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "otherwise|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "quantum-shield|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"This policy is not in the vocabulary this catalog was written against, so nothing can be said about what it does or whether the target has an equivalent. It is reported rather than assumed harmless.\", \"verdict\": \"gap\"}", + "quantum-shield|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A policy expression doing more than reading a well-known context property has no equivalent. The target's policy surface is six declarative types.\", \"verdict\": \"gap\"}", + "quota-by-key|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"costLimit is a dollar budget, not a call quota or a concurrency ceiling.\", \"verdict\": \"gap\"}", + "quota-by-key|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"costLimit is a dollar budget, not a call quota or a concurrency ceiling.\", \"verdict\": \"gap\"}", + "quota|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"costLimit is a dollar budget, not a call quota or a concurrency ceiling.\", \"verdict\": \"gap\"}", + "quota|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"costLimit is a dollar budget, not a call quota or a concurrency ceiling.\", \"verdict\": \"gap\"}", + "rate-limit-by-key|expr=False": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"policy.update\", \"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"APIM counter-key is an arbitrary expression; AI Gateway partitions by identity, IP, both, or a single pooled counter. @(context.Subscription.Id) is close to identity but not identical.\", \"target\": \"requestRateLimit\", \"verdict\": \"partial\"}", + "rate-limit-by-key|expr=True": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"policy.update\", \"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"APIM counter-key is an arbitrary expression; AI Gateway partitions by identity, IP, both, or a single pooled counter. @(context.Subscription.Id) is close to identity but not identical.\", \"target\": \"requestRateLimit\", \"verdict\": \"partial\"}", + "rate-limit|expr=False": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"policy.update\", \"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"APIM counter-key is an arbitrary expression; AI Gateway partitions by identity, IP, both, or a single pooled counter. @(context.Subscription.Id) is close to identity but not identical.\", \"target\": \"requestRateLimit\", \"verdict\": \"partial\"}", + "rate-limit|expr=True": "{\"batchOn\": [\"counter-key\"], \"capabilityId\": \"policy.update\", \"itemKind\": \"translate\", \"options\": [\"identity\", \"ipAddress\", \"identity+ipAddress\", \"pooled\"], \"proposal\": \"identity\", \"rationale\": \"APIM counter-key is an arbitrary expression; AI Gateway partitions by identity, IP, both, or a single pooled counter. @(context.Subscription.Id) is close to identity but not identical.\", \"target\": \"requestRateLimit\", \"verdict\": \"partial\"}", + "redirect-content-urls|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "redirect-content-urls|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "retry|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "retry|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "return-response|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "return-response|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "rewrite-uri|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "rewrite-uri|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "send-one-way-request|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "send-one-way-request|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "send-request|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "send-request|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "set-backend-service|expr=False": "{\"capabilityId\": \"alias.create\", \"partial\": {\"itemKind\": \"accept-loss\", \"options\": [{\"consequence\": \"Every call takes the alias backend pool in its own order, whatever the source would have chosen for it.\", \"value\": \"accept\"}, {\"consequence\": \"Say what the condition was for in the priority and weight of the alias backend models, as far as it can be said that way.\", \"value\": \"compensate\"}, {\"consequence\": \"Keep this workload on APIM, where the routing logic still runs.\", \"value\": \"retain-in-apim\"}], \"proposal\": \"compensate\", \"rationale\": \"The source decides where the request goes with logic the target has no place for: a policy expression, a branch of a `choose`, or both. The alias backend pool carries the set of backends and their priority and weight, not the rule that picked among them.\"}, \"partialWhen\": {\"hasExpression\": true, \"underConditional\": true}, \"rationale\": \"Backend selection becomes the alias backend pool.\", \"verdict\": \"handled\"}", + "set-backend-service|expr=True": "{\"capabilityId\": \"alias.create\", \"partial\": {\"itemKind\": \"accept-loss\", \"options\": [{\"consequence\": \"Every call takes the alias backend pool in its own order, whatever the source would have chosen for it.\", \"value\": \"accept\"}, {\"consequence\": \"Say what the condition was for in the priority and weight of the alias backend models, as far as it can be said that way.\", \"value\": \"compensate\"}, {\"consequence\": \"Keep this workload on APIM, where the routing logic still runs.\", \"value\": \"retain-in-apim\"}], \"proposal\": \"compensate\", \"rationale\": \"The source decides where the request goes with logic the target has no place for: a policy expression, a branch of a `choose`, or both. The alias backend pool carries the set of backends and their priority and weight, not the rule that picked among them.\"}, \"partialWhen\": {\"hasExpression\": true, \"underConditional\": true}, \"rationale\": \"Backend selection becomes the alias backend pool.\", \"verdict\": \"handled\"}", + "set-body|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "set-body|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "set-header|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "set-header|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "set-query-parameter|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "set-query-parameter|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "set-service-url|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"An alias backend pool holds backends the gateway knows, with a priority and a weight each. Overriding the destination URL outright names no backend, so there is nothing for the pool to hold. `set-backend-service` and `forward-request` choose among backends and have a rule of their own.\", \"verdict\": \"gap\"}", + "set-service-url|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"An alias backend pool holds backends the gateway knows, with a priority and a weight each. Overriding the destination URL outright names no backend, so there is nothing for the pool to hold. `set-backend-service` and `forward-request` choose among backends and have a rule of their own.\", \"verdict\": \"gap\"}", + "set-variable|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "set-variable|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "some-future-policy|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"This policy is not in the vocabulary this catalog was written against, so nothing can be said about what it does or whether the target has an equivalent. It is reported rather than assumed harmless.\", \"verdict\": \"gap\"}", + "some-future-policy|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"A policy expression doing more than reading a well-known context property has no equivalent. The target's policy surface is six declarative types.\", \"verdict\": \"gap\"}", + "trace|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "trace|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "validate-azure-ad-token|expr=False": "{\"batchOn\": [], \"capabilityId\": \"key.create\", \"itemKind\": \"translate\", \"options\": [\"entra-rbac\", \"compensate\", \"retain-in-apim\", \"block\"], \"proposal\": \"entra-rbac\", \"rationale\": \"Issuer and audience validation is covered by gateway Entra auth plus data-plane RBAC. Gating on custom claims or app roles is not.\", \"target\": \"entraAuth\", \"verdict\": \"partial\"}", + "validate-azure-ad-token|expr=True": "{\"batchOn\": [], \"capabilityId\": \"key.create\", \"itemKind\": \"translate\", \"options\": [\"entra-rbac\", \"compensate\", \"retain-in-apim\", \"block\"], \"proposal\": \"entra-rbac\", \"rationale\": \"Issuer and audience validation is covered by gateway Entra auth plus data-plane RBAC. Gating on custom claims or app roles is not.\", \"target\": \"entraAuth\", \"verdict\": \"partial\"}", + "validate-client-certificate|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Caller authentication on the gateway is Entra auth plus data-plane RBAC, or an API key. A gate on a shared secret in a header, or on a client certificate, is neither. `validate-jwt` and `validate-azure-ad-token` are the members of this family that do map, and they have a rule of their own.\", \"verdict\": \"gap\"}", + "validate-client-certificate|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"Caller authentication on the gateway is Entra auth plus data-plane RBAC, or an API key. A gate on a shared secret in a header, or on a client certificate, is neither. `validate-jwt` and `validate-azure-ad-token` are the members of this family that do map, and they have a rule of their own.\", \"verdict\": \"gap\"}", + "validate-content|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-content|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-graphql-request|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-graphql-request|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-headers|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-headers|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-jwt|expr=False": "{\"batchOn\": [], \"capabilityId\": \"key.create\", \"itemKind\": \"translate\", \"options\": [\"entra-rbac\", \"compensate\", \"retain-in-apim\", \"block\"], \"proposal\": \"entra-rbac\", \"rationale\": \"Issuer and audience validation is covered by gateway Entra auth plus data-plane RBAC. Gating on custom claims or app roles is not.\", \"target\": \"entraAuth\", \"verdict\": \"partial\"}", + "validate-jwt|expr=True": "{\"batchOn\": [], \"capabilityId\": \"key.create\", \"itemKind\": \"translate\", \"options\": [\"entra-rbac\", \"compensate\", \"retain-in-apim\", \"block\"], \"proposal\": \"entra-rbac\", \"rationale\": \"Issuer and audience validation is covered by gateway Entra auth plus data-plane RBAC. Gating on custom claims or app roles is not.\", \"target\": \"entraAuth\", \"verdict\": \"partial\"}", + "validate-mcp-request|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"`mcp create` registers a tool server, its endpoints and its supported versions. Guarding a tool call on the way through is not part of that surface. `mcp-server`, which declares the server itself, is carried by the MCP server item and has a rule of its own.\", \"verdict\": \"gap\"}", + "validate-mcp-request|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"`mcp create` registers a tool server, its endpoints and its supported versions. Guarding a tool call on the way through is not part of that surface. `mcp-server`, which declares the server itself, is carried by the MCP server item and has a rule of its own.\", \"verdict\": \"gap\"}", + "validate-odata-request|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-odata-request|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-parameters|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-parameters|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-status-code|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "validate-status-code|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"retain-in-apim\", \"rationale\": \"No schema, header, or status validation on the target.\", \"verdict\": \"gap\"}", + "wait|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "wait|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No side-effecting call-outs. agentHooks is the nearest mechanism and applies to tool traffic only.\", \"verdict\": \"gap\"}", + "when|expr=False": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "when|expr=True": "{\"rationale\": \"Composition, control flow, and gateway plumbing with no target object.\", \"verdict\": \"notApplicable\"}", + "xml-to-json|expr=False": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}", + "xml-to-json|expr=True": "{\"itemKind\": \"accept-loss\", \"proposal\": \"accept\", \"rationale\": \"No request or response rewriting on the target.\", \"verdict\": \"gap\"}" + } +} \ No newline at end of file diff --git a/tools/migrate-apim/tests/test_capability.py b/tools/migrate-apim/tests/test_capability.py index 88fdab6..3373784 100644 --- a/tools/migrate-apim/tests/test_capability.py +++ b/tools/migrate-apim/tests/test_capability.py @@ -127,7 +127,7 @@ def test_a_family_rule_catches_elements_with_no_rule_of_their_own(self, caps): def test_expression_is_the_fallback_for_unmapped_elements(self, caps): rule = caps.policy_rule("some-future-policy", family="other", has_expression=True) assert rule["verdict"] == "gap" - assert (rule.get("match") or {}).get("hasExpression") is True + assert (rule.get("derived") or {}).get("hasExpression") is True def test_an_unmapped_element_without_an_expression_reaches_the_terminal_rule(self, caps): # It used to match nothing, and `plan._policies` dropped what matched @@ -179,7 +179,7 @@ def test_every_policy_rule_names_a_real_capability(self, caps): def test_an_unknown_coverage_gap_cannot_be_accepted(self, caps): rule = next( - r for r in caps.structural_rules() if (r.get("match") or {}).get("kind") == "coverageGap" + r for r in caps.structural_rules() if r.get("selects") == "coverageGap" ) assert rule["cannotAccept"] is True assert rule["blocking"] is True diff --git a/tools/migrate-apim/tests/test_compile.py b/tools/migrate-apim/tests/test_compile.py index bd9df64..26c6268 100644 --- a/tools/migrate-apim/tests/test_compile.py +++ b/tools/migrate-apim/tests/test_compile.py @@ -8,6 +8,7 @@ so each check is exercised against the defect it exists for. """ +import contextlib import copy import json @@ -116,7 +117,7 @@ class TestRulesThatCannotBeApplied: def test_a_rule_no_site_selects_is_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) rules["assets"].append({ - "match": {"family": "models", "modelsStatus": ["resolved"]}, + "selects": "modelApi", "where": {"modelsStatus": ["resolved"]}, "verdict": "native", "capabilityId": "model.create", }) result = compile_with(rules=rules) @@ -126,7 +127,7 @@ def test_an_invented_match_key_is_caught(self, compile_with, shipped): # A key no collector emits. The rule looks plausible and selects nothing. rules = copy.deepcopy(shipped[1]) rules["assets"].append({ - "match": {"family": "mcpServers", "isPartOfBulkImportable": True}, + "selects": "mcpServer", "where": {"isPartOfBulkImportable": True}, "verdict": "native", "capabilityId": "mcp.create", }) assert "rule-reachable" in codes(compile_with(rules=rules)) @@ -134,7 +135,7 @@ def test_an_invented_match_key_is_caught(self, compile_with, shipped): def test_a_match_value_outside_the_vocabulary_is_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) rules["assets"].append({ - "match": {"family": "mcpServers", "pattern": "notAPattern"}, + "selects": "mcpServer", "where": {"pattern": "notAPattern"}, "verdict": "native", "capabilityId": "mcp.create", }) assert "match-value-known" in codes(compile_with(rules=rules)) @@ -146,13 +147,32 @@ def test_a_rule_naming_an_absent_capability_is_caught(self, compile_with, shippe def test_two_rules_one_site_cannot_tell_apart_are_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) - first = next(r for r in rules["assets"] if (r["match"].get("pattern"))) + first = next(r for r in rules["assets"] if (r.get("where") or {}).get("pattern")) rules["assets"].append(copy.deepcopy(first)) assert "rule-unique" in codes(compile_with(rules=rules)) + def test_two_rules_differing_only_in_what_is_computed_are_not_a_tie(self, compile_with): + """A site that dispatches on `derived` can tell them apart. + + Judged on `where` alone, the two catalogue rules and the two identity + rules read as one rule written twice, and the shipped file could not + compile. + """ + assert "rule-unique" not in codes(compile_with()) + + def test_a_tie_on_a_computed_predicate_says_which_one(self, compile_with, shipped): + rules = copy.deepcopy(shipped[1]) + catalogued = next(r for r in rules["assets"] + if (r.get("derived") or {}).get("hasCatalogue") is True) + rules["assets"].append(copy.deepcopy(catalogued)) + [diagnostic] = [d for d in compile_with(rules=rules).errors if d.check == "rule-unique"] + # Reported over both blocks: a tie the site can only see once `derived` + # is included reads as a tie on nothing when the message leaves it out. + assert "'hasCatalogue': True" in diagnostic.message + def test_a_partial_rule_without_options_is_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) - rules["structural"].append({"match": {"kind": "subscriptions"}, "verdict": "partial"}) + rules["structural"].append({"selects": "subscriptions", "verdict": "partial"}) assert "partial-needs-options" in codes(compile_with(rules=rules)) def test_a_proposal_that_is_not_an_option_is_caught(self, compile_with, shipped): @@ -217,7 +237,7 @@ def test_an_unknown_match_key_is_rejected_at_the_shape_level(self, compile_with, # The same defect as test_an_invented_match_key_is_caught, one layer out: # the schema rejects it before reachability has to reason about it. rules = copy.deepcopy(shipped[1]) - rules["assets"][0]["match"]["isPartOfBulkImportable"] = True + rules["assets"][0].setdefault("where", {})["isPartOfBulkImportable"] = True assert "schema" in codes(compile_with(rules=rules)) def test_an_unknown_capability_field_is_rejected(self, compile_with, shipped): @@ -234,7 +254,7 @@ def test_the_rich_option_shape_is_accepted(self, compile_with, shipped): # The telemetry rule carries {value, consequence} options rather than # bare strings; both shapes are legitimate. rules = copy.deepcopy(shipped[1]) - rule = next(r for r in rules["structural"] if (r["match"]["kind"]) == "telemetry") + rule = next(r for r in rules["structural"] if r["selects"] == "telemetry") assert any(isinstance(option, dict) for option in rule["options"]) assert "schema" not in codes(compile_with(rules=rules)) @@ -243,7 +263,7 @@ def test_an_asset_rule_matching_on_nothing_is_rejected(self, compile_with, shipp # every site's keys, so every site governs it -- and none ever selects # it, because selection compares values. rules = copy.deepcopy(shipped[1]) - rules["assets"].append({"match": {}, "verdict": "gap"}) + rules["assets"].append({"selects": "mcpServer", "where": {}, "verdict": "gap"}) assert "schema" in codes(compile_with(rules=rules)) def test_a_structural_rule_without_a_verdict_is_rejected(self, compile_with, shipped): @@ -251,7 +271,7 @@ def test_a_structural_rule_without_a_verdict_is_rejected(self, compile_with, shi # hardcoding one per branch, so the exemption these had is gone. rules = copy.deepcopy(shipped[1]) rules["structural"] = [ - {k: v for k, v in r.items() if k != "verdict"} if r["match"]["kind"] == "telemetry" + {k: v for k, v in r.items() if k != "verdict"} if r["selects"] == "telemetry" else r for r in rules["structural"] ] @@ -288,7 +308,7 @@ class TestEveryRuleFieldHasAReader: def test_a_field_no_site_reads_is_reported(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) rules["structural"] = [ - {**r, "prerequisiteWhen": ["flatten"]} if r["match"]["kind"] == "workspace" else r + {**r, "prerequisiteWhen": ["flatten"]} if r["selects"] == "workspace" else r for r in rules["structural"] ] result = compile_with(rules=rules) @@ -315,16 +335,22 @@ def test_an_unreachable_rule_is_not_also_reported_field_by_field( `policyFragments` used to be the example here, which is the whole of what was wrong with it: the tool collected fragments and the one rule describing them was the suite's stock illustration of a rule nothing - asks for. It is selectable now, so the illustration needs a kind that - genuinely is not. + asks for. It is selectable now, so the illustration needs a subject + that genuinely is not. + + The code is `rule-reachable` rather than `match-value-known` because a + rule now names its subject outright. Unreachability used to be inferred + from a value no site compares against; it is now read off the rule. """ rules = copy.deepcopy(shipped[1]) rules["structural"].append({ - "match": {"kind": "loggers"}, "verdict": "handled", + "selects": "loggers", "verdict": "handled", "itemKind": "accept-loss", "rationale": "x", "proposal": "accept", }) result = compile_with(rules=rules) - assert "match-value-known" in codes(result) + [reachability] = [d for d in result.errors + if d.check == "rule-reachable" and "loggers" in d.message] + assert "no selection site decides about" in reachability.message assert not [d for d in result.warnings if d.check == "rule-field-unread" and "loggers" in str(d)] @@ -341,18 +367,18 @@ class TestEveryPolicyPassIsCheckedForTies: def test_two_rules_with_the_same_family_are_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) - rules["policies"].append({"match": {"family": "transform"}, "verdict": "gap"}) + rules["policies"].append({"selects": "policyElement", "where": {"family": "transform"}, "verdict": "gap"}) assert "rule-unique" in codes(compile_with(rules=rules)) def test_two_expression_fallbacks_are_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) - rules["policies"].append({"match": {"hasExpression": True}, "verdict": "gap"}) + rules["policies"].append({"selects": "policyElement", "derived": {"hasExpression": True}, "verdict": "gap"}) assert "rule-unique" in codes(compile_with(rules=rules)) def test_one_repeated_element_among_many_is_still_caught(self, compile_with, shipped): rules = copy.deepcopy(shipped[1]) rules["policies"].append( - {"match": {"element": ["brand-new", "ip-filter"]}, "verdict": "gap"}) + {"selects": "policyElement", "where": {"name": ["brand-new", "ip-filter"]}, "verdict": "gap"}) result = compile_with(rules=rules) assert "rule-unique" in codes(result) assert any("ip-filter" in str(d) for d in result.errors) @@ -451,14 +477,14 @@ def test_a_selector_can_go_in_a_set(self): def test_a_selector_rejects_a_rule_pinning_a_key_it_ignores(self): site = next(s for s in dispatch.REGISTRY if s.site == "plan._agent") - assert site.governs({"match": {"family": "agents"}}) + assert site.governs({"selects": "agent"}) # An extra key would be silently ignored at selection time, so the rule # would match more broadly than it reads. - assert not site.governs({"match": {"family": "agents", "pattern": "passthrough"}}) + assert not site.governs({"selects": "agent", "where": {"pattern": "passthrough"}}) def test_a_selector_rejects_a_value_it_never_compares_against(self): site = next(s for s in dispatch.REGISTRY if s.site == "plan._agent") - assert not site.governs({"match": {"family": "models"}}) + assert not site.governs({"selects": "modelApi"}) class TestTheKnownPolicyVocabularyIsAnswered: @@ -470,11 +496,16 @@ class TestTheKnownPolicyVocabularyIsAnswered: somebody never got round to -- so what it may answer for is held down here. """ + def _trimmed_of_fallback(self, rules): + trimmed = copy.deepcopy(rules) + trimmed["policies"] = [r for r in trimmed["policies"] if not r.get("fallback")] + return trimmed + def _without(self, rules, **match): trimmed = copy.deepcopy(rules) trimmed["policies"] = [ rule for rule in trimmed["policies"] - if not all((rule.get("match") or {}).get(k) == v for k, v in match.items()) + if not all((rule.get("where") or {}).get(k) == v for k, v in match.items()) ] return trimmed @@ -494,14 +525,14 @@ def test_losing_the_terminal_rule_is_an_error_of_its_own(self, compile_with, shi # Without it an unknown element resolves to nothing, and resolving to # nothing is what the planner used to drop in silence. _, rules, _ = shipped - result = compile_with(rules=self._without(rules, anyElement=True)) + result = compile_with(rules=self._trimmed_of_fallback(rules)) assert "policy-terminal" in codes(result) def test_a_second_terminal_rule_is_a_tie_and_rejected(self, compile_with, shipped): # Selection is first-match, so two of them means one is never reached. _, rules, _ = shipped doubled = copy.deepcopy(rules) - terminal = next(r for r in doubled["policies"] if (r.get("match") or {}).get("anyElement")) + terminal = next(r for r in doubled["policies"] if r.get("fallback")) doubled["policies"].append(copy.deepcopy(terminal)) assert "rule-unique" in codes(compile_with(rules=doubled)) @@ -514,7 +545,7 @@ class TestACleanRunSaysWhatItChecked: def test_every_check_reports_what_it_covered(self, compile_with, shipped): documented = shipped[0]["cliEvidence"]["documentedVersion"] covered = compile_with(newest_release=f"cli-v{documented}").covered - assert len(covered) == 7, covered + assert len(covered) == 9, covered def test_the_counts_are_the_real_ones(self, compile_with, shipped): catalog, rules, surface = shipped @@ -526,3 +557,56 @@ def test_without_tags_the_release_line_is_absent(self, compile_with): """Nothing was compared, so claiming a check ran would be a lie.""" covered = " ".join(compile_with().covered) assert "published release" not in covered + + +class TestTheDecisionsStayInTheFile: + """Twelve decisions were written in `plan.py` while `ARCHITECTURE.md` + described them as data. These are what stops that reopening quietly.""" + + def test_a_site_with_no_rule_is_an_error(self, compile_with, shipped): + _, rules, _ = shipped + stripped = copy.deepcopy(rules) + stripped["assets"] = [r for r in stripped["assets"] + if r.get("selects") != "sessionAffinity"] + result = compile_with(rules=stripped) + assert "subject-has-rule" in codes(result) + [diagnostic] = [d for d in result.errors if d.check == "subject-has-rule"] + # Named, with where the question is asked, because "something is + # unanswered" is not a fix. + assert "sessionAffinity" in diagnostic.message + assert "plan._pool_affinity" in diagnostic.message + + def test_the_shipped_rules_answer_every_site(self, compile_with): + assert "subject-has-rule" not in codes(compile_with()) + + def test_a_where_key_reading_no_real_field_is_an_error(self): + """The failure `rule-reachable` cannot see: the key is one a site reads, + so the rule looks selectable and simply never fires.""" + from migrate_apim import compile as compile_mod + from migrate_apim.dispatch import Selector + + bogus = Selector( + section="assets", selects="publishedSurface", keys=("status",), values={}, + site="test", fields={"status": "assets.models[].endpoints.surface.nope"}, + ) + out = compile_mod.Compilation() + with _only_site(bogus): + compile_mod.check_where_keys_are_fields({}, compile_mod._inventory_schema(), out) + [diagnostic] = [d for d in out.errors if d.check == "where-key-field"] + assert "surface.nope" in diagnostic.message + + def test_the_shipped_paths_all_exist(self, compile_with): + assert "where-key-field" not in codes(compile_with()) + + +@contextlib.contextmanager +def _only_site(site): + """Run a registry-wide check against one selector, without mutating the rest.""" + from migrate_apim import dispatch + + saved = list(dispatch.REGISTRY) + dispatch.REGISTRY[:] = [site] + try: + yield + finally: + dispatch.REGISTRY[:] = saved diff --git a/tools/migrate-apim/tests/test_decisions_moved_intact.py b/tools/migrate-apim/tests/test_decisions_moved_intact.py new file mode 100644 index 0000000..febf928 --- /dev/null +++ b/tools/migrate-apim/tests/test_decisions_moved_intact.py @@ -0,0 +1,316 @@ +"""Each decision that moved from `plan.py` into `rules.json`, as it was. + +`test_decisions_unchanged.py` compares the plan built from the fake ARM +fixture, which proves the wiring but only for the cases that fixture reaches. +It does not reach a pool using session affinity, an unbounded published +surface, or a private-networking requirement -- and a decision that moved +wrongly in one of those stayed green there. One did: the session-affinity +options lost `block`, the option that stops a migration, and gained an invented +one, and the fixture's silence let it through. + +So every moved decision is pinned here instead, transcribed from the code that +held it before the move. These are not assertions about what the rules *should* +say; they are a copy of what they *did* say, and a diff is a decision changed. + +Pinning the rule is half of it. A decision is only in the file if the planner +reads it from there, and seven sites kept writing their own option list beside a +rule that carried one -- editing the file moved nothing, and `rule-field-unread` +could not see it because each site declared it read `options`. So every site is +asked the other question too: say something different in the rule, and the plan +has to say it back. +""" + +from __future__ import annotations + +import copy + +import pytest + +from migrate_apim.capability import CapabilityMap +from migrate_apim.collect import Collector, CollectOptions +from migrate_apim.plan import build_plan +from migrate_apim import plan as plan_mod +from fake_arm import SERVICE, FakeArmClient + + +@pytest.fixture(scope="module") +def caps(): + return CapabilityMap.load() + + +@pytest.fixture(scope="module") +def inventory(): + return Collector(FakeArmClient(), SERVICE, + CollectOptions(cognitive_api_version="2025-06-01")).run() + + +def decision(rule): + """The fields that decide an item, ignoring how the rule was selected.""" + return { + "verdict": rule.get("verdict"), + "itemKind": rule.get("itemKind"), + "capabilityId": rule.get("capabilityId"), + "proposal": rule.get("proposal"), + "options": [o["value"] if isinstance(o, dict) else o for o in rule.get("options") or []], + "blocking": rule.get("blocking"), + } + + +def expected(verdict, itemKind=None, capabilityId=None, proposal=None, options=(), blocking=None): + return {"verdict": verdict, "itemKind": itemKind, "capabilityId": capabilityId, + "proposal": proposal, "options": list(options), "blocking": blocking} + + +class TestTheDecisionsThatMovedAreTheOnesThatWereThere: + def test_a_provider_registers_directly(self, caps): + rule = plan_mod.PROVIDER_RULE.first(caps.asset_rules()) + assert decision(rule) == expected("native", capabilityId="provider.create") + + def test_a_model_registers_directly(self, caps): + rule = plan_mod.MODEL_REGISTRATION_RULE.first(caps.asset_rules()) + assert decision(rule) == expected("native", capabilityId="model.create") + + def test_an_unbounded_surface_publishes_inference_only(self, caps): + rule = plan_mod.SURFACE_BY_STATUS.first(caps.asset_rules(), status="unbounded") + assert decision(rule) == expected( + "partial", "reduce-surface", "alias.create", "inference-only", + ["inference-only", "retain-in-apim", "block"], blocking=True) + + def test_a_partly_publishable_surface_splits(self, caps): + rule = plan_mod.SURFACE_PARTIALLY_PUBLISHABLE.first( + caps.asset_rules(), hasUnpublishable=True) + assert decision(rule) == expected( + "partial", "reduce-surface", "alias.create", "split", + ["split", "inference-only", "retain-in-apim", "block"], blocking=True) + + def test_a_translating_dialect_moves_callers(self, caps): + rule = plan_mod.DIALECT_TRANSLATING.first(caps.asset_rules(), status="translating") + assert decision(rule) == expected( + "partial", "translate", "alias.create", "move-callers", + ["move-callers", "retain-in-apim", "block"], blocking=True) + + def test_an_indeterminate_dialect_asks_and_proposes_nothing(self, caps): + rule = plan_mod.DIALECT_INDETERMINATE.first(caps.asset_rules(), status="indeterminate") + assert decision(rule) == expected( + "partial", "enumerate", "alias.create", None, + ["confirm-dialect", "retain-in-apim"], blocking=True) + + def test_session_affinity_keeps_the_option_that_stops_a_migration(self, caps): + """The one the fixture does not reach, and the one that moved wrongly.""" + rule = plan_mod.SESSION_AFFINITY_RULE.first(caps.asset_rules()) + assert decision(rule) == expected( + "gap", "accept-loss", "alias.create", "accept-loss", + ["accept-loss", "retain-in-apim", "block"]) + + def test_a_read_catalogue_is_published_as_listed(self, caps): + rule = plan_mod.CATALOGUE_RULE.first(caps.asset_rules(), hasCatalogue=True) + assert decision(rule) == expected( + "partial", "enumerate", "model.create", "list-models", + ["list-models", "retain-in-apim"], blocking=True) + + def test_an_unread_catalogue_with_an_endpoint_proposes_resolving_it(self, caps): + rule = plan_mod.CATALOGUE_RULE.first( + caps.asset_rules(), hasCatalogue=False, discoverySource="modelsEndpoint") + assert decision(rule) == expected( + "partial", "enumerate", "model.create", "resolve-models", + ["resolve-models", "list-models", "retain-in-apim"], blocking=True) + + def test_an_unread_catalogue_without_one_proposes_naming_them(self, caps): + rule = plan_mod.CATALOGUE_RULE.first( + caps.asset_rules(), hasCatalogue=False, discoverySource=None) + assert decision(rule) == expected( + "partial", "enumerate", "model.create", "list-models", + ["resolve-models", "list-models", "retain-in-apim"], blocking=True) + + def test_alias_names_default_to_the_model_names(self, caps): + rule = plan_mod.ALIAS_NAMES_RULE.first(caps.asset_rules()) + assert decision(rule) == expected( + "partial", "name", "alias.create", "use-model-names", + ["use-model-names", "override"]) + + def test_a_bypassed_tool_list_is_a_decision(self, caps): + rule = plan_mod.TOOL_EXPOSURE_BYPASSED.first(caps.asset_rules(), policiesBypassed=True) + assert decision(rule) == expected( + "partial", "enumerate", None, "accept-as-listed", + ["accept-as-listed", "verify-through-gateway", "retain-in-apim"]) + + def test_a_user_assigned_identity_is_a_choice(self, caps): + rule = plan_mod.IDENTITY_RULE.first(caps.structural_rules(), hasUserAssigned=True) + # The reuse options are one per identity the source carries, so they are + # built where the inventory is read; `system-assigned` is the choice + # that exists either way. + assert decision(rule) == expected( + "partial", "translate", "identity.assign", "system-assigned", ["system-assigned"]) + + def test_without_one_the_gateway_takes_its_own(self, caps): + rule = plan_mod.IDENTITY_RULE.first(caps.structural_rules(), hasUserAssigned=False) + assert decision(rule) == expected( + "native", capabilityId="identity.assign", proposal="system-assigned") + + def test_backends_needing_a_subnet_propose_one(self, caps): + rule = plan_mod.REACHABILITY_BY_SUBNET.first(caps.structural_rules(), needsSubnet=True) + assert decision(rule) == expected( + "partial", "translate", "network.update", "new-delegated-subnet", + ["new-delegated-subnet", "public-egress", "retain-in-apim", "block"]) + + def test_backends_not_needing_one_propose_private_ingress(self, caps): + """The one case where moving a decision had to change it. + + `plan.py` offered the same four options whichever way `needsSubnet` + went, and proposed `private-ingress` here -- a recommendation that was + not among the choices, so nobody could settle the item on it. + `proposal-is-an-option` says that cannot be written down, so the + proposal joins the options rather than the four being narrowed. + """ + rule = plan_mod.REACHABILITY_BY_SUBNET.first(caps.structural_rules(), needsSubnet=False) + assert decision(rule) == expected( + "partial", "translate", "network.update", "private-ingress", + ["private-ingress", "new-delegated-subnet", "public-egress", + "retain-in-apim", "block"]) + + +OFFERED = ["named-only-in-the-file"] + + +def saying(caps, selects, overrides, **predicates): + """The shipped rules with one rule rewritten, as a map the planner can use. + + Selection is left exactly as it ships: the question is whether the planner + reads the rule it already chooses, not whether a different one can be made + to win. + """ + rules = copy.deepcopy(caps.rules) + for section in ("assets", "structural"): + for rule in rules[section]: + if rule.get("selects") != selects: + continue + pinned = {**(rule.get("where") or {}), **(rule.get("derived") or {})} + if all(pinned.get(key) == value for key, value in predicates.items()): + rule.update(overrides) + return CapabilityMap(caps.catalog, rules) + raise AssertionError(f"no {selects} rule matching {predicates}") + + +def item_with(plan, aspect): + return next(item for item in plan["items"] if item["source"]["aspect"] == aspect) + + +def offered(item): + return [option["value"] for option in item["options"]] + + +class TestThePlannerOffersWhatTheFileSays: + """Change a rule, and the item it decides has to change with it.""" + + def test_a_provider_takes_its_verdict_from_the_rule(self, inventory, caps): + built = build_plan(inventory, saying(caps, "modelProvider", {"verdict": "handled"})) + item = next(i for i in built["items"] if i["source"]["assetKind"] == "modelProvider") + assert item["verdict"] == "handled" + + def test_a_model_registration_takes_its_verdict_from_the_rule(self, inventory, caps): + built = build_plan(inventory, saying(caps, "modelRegistration", {"verdict": "handled"})) + item = next(i for i in built["items"] if i["source"]["aspect"].startswith("model:")) + assert item["verdict"] == "handled" + + def test_an_unbounded_surface_offers_the_rules_choices(self, inventory, caps): + built = build_plan(inventory, saying( + caps, "publishedSurface", {"options": OFFERED}, status="unbounded")) + # Three APIs raise this question; the unbounded one is the API whose + # surface could not be read, which is the rule being changed here. + item = next(i for i in built["items"] + if i["source"]["aspect"] == "publishedSurface" + and i["proposal"] == "inference-only") + assert offered(item) == OFFERED + + def test_a_partly_publishable_surface_offers_the_rules_choices(self, inventory, caps): + built = build_plan(inventory, saying( + caps, "publishedSurface", {"options": OFFERED}, hasUnpublishable=True)) + item = next(i for i in built["items"] + if i["source"]["aspect"] == "publishedSurface" and i["proposal"] == "split") + assert offered(item) == OFFERED + + def test_what_splitting_costs_is_still_this_apis_number(self, inventory, caps): + """The half that stays in code: the choice is the rule's, the sentence + counts the operations this API leaves behind, which no rule can know.""" + item = next(i for i in build_plan(inventory, caps)["items"] + if i["source"]["aspect"] == "publishedSurface" and i["proposal"] == "split") + consequence = {o["value"]: o["consequence"] for o in item["options"]}["split"] + left_behind = item["evidence"]["surface"]["unpublishableCount"] + assert f"{left_behind} operations stay on APIM" in consequence + + def test_a_translating_dialect_offers_the_rules_choices(self, inventory, caps): + built = build_plan(inventory, saying( + caps, "callerDialect", {"options": OFFERED}, status="translating")) + assert offered(item_with(built, "callerDialect")) == OFFERED + + def test_an_indeterminate_dialect_offers_the_rules_choices(self, inventory, caps): + changed = copy.deepcopy(inventory) + asset = next(m for m in changed["assets"]["models"] if m["source"]["name"] == "model-api") + asset["endpoints"]["translation"]["status"] = "indeterminate" + built = build_plan(changed, saying( + caps, "callerDialect", {"options": OFFERED}, status="indeterminate")) + assert offered(item_with(built, "callerDialect")) == OFFERED + + def test_session_affinity_offers_the_rules_choices(self, inventory, caps): + changed = copy.deepcopy(inventory) + asset = next(m for m in changed["assets"]["models"] if m["source"]["name"] == "aoai-api") + asset["routing"]["sessionAffinity"] = {"enabled": True} + built = build_plan(changed, saying(caps, "sessionAffinity", {"options": OFFERED})) + assert offered(item_with(built, "sessionAffinity")) == OFFERED + + def test_an_unread_catalogue_offers_the_rules_choices(self, inventory, caps): + built = build_plan(inventory, saying( + caps, "modelCatalogue", {"options": OFFERED}, + hasCatalogue=False, discoverySource="modelsEndpoint")) + assert offered(item_with(built, "modelCatalogue")) == OFFERED + + def test_alias_naming_offers_the_rules_choices(self, inventory, caps): + built = build_plan(inventory, saying(caps, "aliasNames", {"options": OFFERED})) + assert offered(item_with(built, "aliasNames")) == OFFERED + + def test_a_bypassed_tool_list_offers_the_rules_choices(self, inventory, caps): + changed = copy.deepcopy(inventory) + server = changed["assets"]["mcpServers"][0] + server["toolDiscovery"] = {"status": "complete", "policiesApplied": False, + "discoveredCount": 3} + built = build_plan(changed, saying( + caps, "toolExposure", {"options": OFFERED}, policiesBypassed=True)) + assert offered(item_with(built, "toolExposure")) == OFFERED + + def test_a_user_assigned_identity_offers_the_rules_choice_and_the_reuse( + self, inventory, caps + ): + changed = copy.deepcopy(inventory) + changed["service"]["identity"]["userAssignedIdentities"] = [{"resourceId": "/uai/one"}] + built = build_plan(changed, saying( + caps, "gatewayIdentity", {"options": OFFERED}, hasUserAssigned=True)) + assert offered(item_with(built, "gatewayIdentity")) == [*OFFERED, "reuse:/uai/one"] + + def test_backend_reachability_offers_the_rules_choices(self, inventory, caps): + changed = copy.deepcopy(inventory) + changed["service"]["networking"]["targetRequirement"] = { + "needsSubnet": True, "note": "Collected."} + built = build_plan(changed, saying( + caps, "backendReachability", {"options": OFFERED}, needsSubnet=True)) + assert offered(item_with(built, "backendReachability")) == OFFERED + + +class TestEveryMovedDecisionIsPinned: + """A pin that quietly stops covering a site proves nothing.""" + + MOVED = ( + "modelProvider", "publishedSurface", "callerDialect", "sessionAffinity", + "modelCatalogue", "modelRegistration", "aliasNames", "toolExposure", + "gatewayIdentity", "backendReachability", + ) + + def test_each_subject_has_a_rule(self, caps): + rules = [*caps.asset_rules(), *caps.structural_rules()] + answered = {rule.get("selects") for rule in rules} + assert set(self.MOVED) <= answered, sorted(set(self.MOVED) - answered) + + def test_each_subject_has_a_selection_site(self): + from migrate_apim.dispatch import REGISTRY + + sites = {site.selects for site in REGISTRY} + assert set(self.MOVED) <= sites, sorted(set(self.MOVED) - sites) diff --git a/tools/migrate-apim/tests/test_decisions_unchanged.py b/tools/migrate-apim/tests/test_decisions_unchanged.py new file mode 100644 index 0000000..c8559a8 --- /dev/null +++ b/tools/migrate-apim/tests/test_decisions_unchanged.py @@ -0,0 +1,107 @@ +"""What the tool decides, pinned against how it expresses the decision. + +`rules.json` is being restructured: the subject of a rule moves out of which +array it sits in and into a `selects` key, its predicates move into `where`, and +decisions that were written in `plan.py` move into the file. None of that may +change a single verdict, option or proposal. + +That property is hard to hold by reading a diff -- the diff is thousands of +lines and touches every rule -- so it is held here instead. `golden/decisions.json` +records two things, generated before the restructure began: + +* **the resolution table** -- every element the collector can name, with and + without an expression, against the decision the rules give it. A rule is + identified by what it decides and not by how it is matched, because how it is + matched is exactly what changes. +* **the plan** built from the fake ARM fixture, scrubbed of timestamps. + +Regenerate it only when a decision is *meant* to change, and say so in the +commit. A diff here is either a bug or a deliberate answer to a new question. +""" + +from __future__ import annotations + +import json +import pathlib + +import pytest + +from migrate_apim.capability import CapabilityMap +from migrate_apim.collect import Collector, CollectOptions +from migrate_apim.plan import build_plan +from migrate_apim.policy import FAMILIES, family_of +from fake_arm import SERVICE, FakeArmClient + +GOLDEN = pathlib.Path(__file__).parent / "golden" / "decisions.json" + +# How a rule is matched is what this refactor changes; what it decides is what +# must not. Identify a rule by the second. +_MATCHING = {"match", "selects", "where", "derived", "fallback", "note"} + +_UNKNOWN = ("some-future-policy", "quantum-shield") + + +def rule_id(rule): + if rule is None: + return None + return json.dumps({k: v for k, v in rule.items() if k not in _MATCHING}, sort_keys=True) + + +def resolution_table(caps): + table = {} + for name in sorted(FAMILIES): + for expr in (False, True): + table[f"{name}|expr={expr}"] = rule_id( + caps.policy_rule(name, family=family_of(name), has_expression=expr) + ) + for name in _UNKNOWN: + for expr in (False, True): + table[f"{name}|expr={expr}"] = rule_id( + caps.policy_rule(name, family="other", has_expression=expr) + ) + return table + + +def scrub(value): + """Drop what moves between runs; keep every decision.""" + if isinstance(value, dict): + return {k: scrub(v) for k, v in sorted(value.items()) + if k not in {"generatedAt", "inventoryCapturedAt"}} + if isinstance(value, list): + return [scrub(v) for v in value] + return value + + +class TestTheDecisionsAreTheOnesThatWereThereBefore: + def test_every_element_resolves_to_the_decision_it_did(self): + expected = json.loads(GOLDEN.read_text())["resolution"] + actual = resolution_table(CapabilityMap.load()) + assert set(actual) == set(expected), "the vocabulary itself moved" + moved = { + name: (json.loads(expected[name] or "null"), json.loads(actual[name] or "null")) + for name in sorted(expected) + if actual[name] != expected[name] + } + assert not moved, f"{len(moved)} element(s) now resolve differently: {list(moved)[:5]}" + + def test_the_plan_is_the_one_that_was_there(self, inventory, capabilities): + expected = json.loads(GOLDEN.read_text())["plan"] + actual = scrub(build_plan(inventory, capabilities)) + assert actual == expected + + def test_the_golden_covers_every_element_the_collector_classifies(self): + """A snapshot that quietly stops covering something proves nothing.""" + expected = json.loads(GOLDEN.read_text())["resolution"] + covered = {name.split("|", 1)[0] for name in expected} + assert covered == set(FAMILIES) | set(_UNKNOWN) + + +@pytest.fixture(scope="module") +def inventory(): + return Collector(FakeArmClient(), SERVICE, + CollectOptions(cognitive_api_version="2025-06-01")).run() + + +@pytest.fixture(scope="module") +def capabilities(): + return CapabilityMap.load() diff --git a/tools/migrate-apim/tests/test_plan.py b/tools/migrate-apim/tests/test_plan.py index 642318b..662d451 100644 --- a/tools/migrate-apim/tests/test_plan.py +++ b/tools/migrate-apim/tests/test_plan.py @@ -359,7 +359,7 @@ class TestTheRulesDecideAndTheBuilderReads: def test_the_verdict_and_kind_come_from_the_rule(self, plan, capabilities): rule = next(r for r in capabilities.structural_rules() - if r["match"]["kind"] == "workspace") + if r["selects"] == "workspace") [item] = items_of(plan, "collapse") assert (item["verdict"], item["kind"]) == (rule["verdict"], rule["itemKind"]) @@ -376,7 +376,7 @@ def test_a_reprovisioning_loss_carries_the_proposal_its_rule_names( for kind in ("certificates", "credentialProviders"): item = next(i for i in built["items"] if i["source"]["assetKind"] == kind) rule = next(r for r in capabilities.structural_rules() - if r["match"]["kind"] == kind) + if r["selects"] == kind) assert item["proposal"] == rule["proposal"], kind assert item["proposal"] in {o["value"] for o in item["options"]}, kind @@ -1552,7 +1552,7 @@ def test_an_undecided_plan_still_asks(self, plan): def test_which_destinations_need_it_is_the_rule_s_to_say(self, capabilities): rule = next(r for r in capabilities.structural_rules() - if r["match"]["kind"] == "telemetry") + if r["selects"] == "telemetry") assert set(rule["prerequisiteWhen"]) == {"reuse-appinsights", "new-appinsights"} assert set(rule["prerequisiteWhen"]) <= {o["value"] for o in rule["options"]} diff --git a/tools/migrate-apim/tests/test_resolve.py b/tools/migrate-apim/tests/test_resolve.py index 051a207..2d27371 100644 --- a/tools/migrate-apim/tests/test_resolve.py +++ b/tools/migrate-apim/tests/test_resolve.py @@ -5,6 +5,7 @@ from migrate_apim.arm import ArmResponse from migrate_apim.capability import CapabilityMap +from migrate_apim.cli import validate_inventory from migrate_apim.collect import Collector, CollectOptions from migrate_apim.plan import build_plan from migrate_apim.resolve import ( @@ -149,6 +150,19 @@ def test_the_apis_using_that_provider_are_updated_too(self, inventory): assert asset["models"]["discoverySource"] == "modelsEndpoint" assert asset["models"]["catalogue"] == ["model-a"] + def test_a_resolved_inventory_still_validates(self, inventory): + """The schema has to know the status the resolver writes. + + `catalogued` was not in its enum while `resolve.py` wrote it and + `plan.py` branched on it, so `migrate-apim validate` rejected an + inventory the tool itself had just produced. Only a resolve run reaches + the value, and nothing here had asked the schema about one. + """ + document = copy.deepcopy(inventory) + resolve_models(document, client=_SecretClient(), allow={"all"}, + fetcher=lambda url, headers: ["model-a"]) + assert validate_inventory(document) == [] + def test_the_credential_never_reaches_the_inventory(self, inventory): document = copy.deepcopy(inventory) secret = "Bearer s3cret-value-not-in-any-file"