You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(migrate-apim): resolve policy scope through fragments, inheritance and operations - #67
migrate-apim plans a migration by working out which APIM policies govern which API, then expanding
each one into the AI Gateway objects that carry it. Two modules answered that question
independently — collect, to decide how a backend authenticates, and plan, to decide what a policy
item covers — and neither understood policy fragments, <base /> inheritance, or operation scope.
The consequences were not subtle. A token limit an operator had factored into a shared fragment —
the way APIM is meant to share one — reached no API at all: the plan listed it as ready, provisioned
nothing, and the first such object aborted the policies phase for every policy queued behind it.
The same hole swallowed operation-scoped policies. Elsewhere the two answers disagreed, and a
migrated provider could be given the wrong managed identity.
This replaces both answers with one resolver.
The resolver
policy.PolicyGraph owns which policy governs which API. collect and plan both read it.
It is built from the inventory as the collector already writes it — include-fragment and base are
ordinary elements, each carrying its section and path, so inclusion and inheritance are read rather
than inferred. No new inventory field is required for any of this.
Fragments are spliced at the site that included them, transitively, guarding against the cycle
APIM will store but never run. A fragment's elements have no section of their own, so they take the
include site's — and a fragment pulled in under a choose is conditional however unconditionally
its body reads.
<base /> decides inheritance. A parent scope's section runs only where the child asks for it,
so an API that overrides its inbound does not inherit the global policy. A scope with no policy
of its own inherits, which is APIM's default template. An omission is recorded, not just acted on.
Products are alternatives, not links. Which product's policy runs depends on the subscription a
call arrived on, so each is its own chain, alongside the chain with no product in it. One product's
section without <base /> cannot suppress a sibling's policy or the global policy behind it.
Operations are resolved through the full chain where every operation of an API carries a policy
of its own; otherwise traffic reaches an operation that inherits, and the API's resolution governs.
Names are scoped. Every comparison is keyed on the workspace-qualified name, and a fragment-id
is matched without regard to case, as APIM compares resource names.
Resolution returns the union of what governs a scope and the chains it came from. The union is a
set, not an execution order — alternatives flattened together have no "last" — so anything deciding
which of two elements overrides the other reads a chain. Backend authentication does.
What changes in a plan
Before
After
A policy in a fragment reaches no API; the item reads ready and aborts the policies phase
It reaches the models of every API that includes it, through nesting, products or the global policy
An operation-scoped policy reaches no API
It reaches its own API's models
finance/shared and hr/shared are one API; a limit on either reaches both
Workspace-qualified throughout
Two workspaces with a same-named fragment collapse to one, first wins
Two fragments
A global policy covers every API
It covers the APIs whose section asks for it
A policy on an API excluded as non-AI raises a blocking decision
It raises nothing, and is counted under policyCoverage.governsNothing
Policies inside retry and wait never reach rule selection
They do
validate-jwt plans an object with no settings that no builder can write
It is a decision about caller authentication, with no object
A fragment whose body could not be read parses as empty and reads as "resolves, contains nothing"
Blocking, and cannot be accepted as a loss
10 of the 62 policy elements the collector classifies match no rule and are dropped where classified
Every element is answered, and compile fails if one is left to the catch-all
Policy items now carry what they govern as well as where they are written, so a settled decision
notices an API joining a fragment it was settled against, and a decision that shares no source with
the item it was settled against is re-asked rather than carried forward.
Contract
AI Gateway has no policy composition — no fragments, no includes, no inheritance; the catalog and the
CLI surface snapshot contain the word zero times. A fragment therefore has one fate, dissolved into
whatever includes it, and the only question is whether the dissolution keeps what it meant.
rules.json gains five structural rules, one per case the planner can classify a fragment into:
dissolved, conditional, split across sections, unreferenced, and unresolved. A policyFragments rule
pins a second match key, disposition, and compile holds the five to the planner's own list —
including the case that passes Selector.governs while never equalling any disposition a selection
site asks for.
Most of the logic is in PolicyGraph, which is pure, so most of the tests build documents directly:
splicing, nesting, cycles, case-mismatched and unresolvable fragment-ids, <base /> present and
absent, product/operation/workspace scope, two workspaces holding a same-named fragment, and the
ordering guarantees the chains exist to provide. The rest pin behaviour end to end, including that a
loss is reported identically whether a policy is written inline or extracted into a fragment.
Against the shipped fixture the plan gains one item — the fragment — and the coverage tally. No
existing item changes status, verdict or object count.
All offline: no Azure resources created, nothing run against a live APIM instance or gateway. These
are contract defects, decidable against the committed catalog, the CLI surface snapshot and the fake
ARM fixture.
Not verified here
A live run against an instance with real fragments. apim-gateway-demo (StandardV2) is noted in the
README as carrying policy fragments with C# expressions; collect + plan against it, checking each
fragment item against the portal's Used by list, is worth doing before this merges.
Supersedes #66, which fixes the same four issues and should be closed in favour of this.
`plan` sets `configurationComplete: false` with an `incompleteReason` on an
object it cannot shape in full, and nothing read either field back. The
condition surfaced only when the step ran: the builder refused, reporting
whatever cause it could work out, and a failed step stops its phase -- so a
problem the planner had already detected and explained cost the rest of a
phase to rediscover, in worse words.
Preflight now enumerates them. Blocking, because the builder cannot produce
the object either and the run stops at it either way, which is the bargain
`plannerGap` already makes. Scoped to `steps_for`, so the objects checked are
the objects that run: one on work no phase performs cannot fail a phase, and
blocking on it would stop a migration over work the operator was going to
apply by hand, which `notExecutable` already names. The message quotes
`incompleteReason` and `fullConfigurationAt` rather than restating them,
since the planner is the only thing that knows why; two planner paths mark an
object incomplete from empty settings alone and write no reason, and those
report the silence instead of an empty quote.
The three fields are a contract between `plan` and `apply` and now a blocking
one, so the plan schema declares them. The rest of an object stays open,
because its shape is the capability's.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`handled` is the strongest claim the planner makes about a policy element:
another object carries this, so there is nothing to decide. `_policies` acted
on it before `_apply_partial_when` ran, so it was a claim about the element
name rather than about the element.
`set-backend-service` is where that fails. The rule says "Backend selection
becomes the alias backend pool", and the pool is built from the APIM backend
pool, which carries no conditional logic at all. So
`<set-backend-service backend-id="@(expression)" />`, and the same element
inside a `choose`, were classified and then dropped: no item, no gap, and
nothing in the plan recording that routing logic had existed. The same
project rule that `collect` answered when a backend id built inside a policy
expression was invisible -- a failed inference must not read as a confident
negative -- was unanswered here one level up.
Analyse first, exclude after. `partialWhen` already expresses "this mapping
is lossy for this element" in data, so it gains two conditions beside
`attributeIsExpression`: `hasExpression`, and `underConditional`, read off
the path, which is the only place the enclosing `choose` survives
normalization. Any one of them demotes; requiring all would let an element
that trips a single condition read as cleanly mapped.
So the routing becomes a `partial` / `accept-loss` item proposing
`compensate`, carrying `alias.create` so the plan says what did travel, with
accept, compensate and retain-in-apim spelled out. Not a `gap`: the backends
and their priority and weight do reach the alias, and blocking a migration
over a `choose` between two members of one pool is the false alarm that
teaches people to ignore the plan. Not a note either -- `needs-decision` is
this plan's word for a fact somebody has to dispose of, and anything weaker
is not counted, not carried across a regeneration, and not read by `apply`.
Nothing changes for a `handled` element that is plain and unconditional, or
for one whose rule declares no condition: `authentication-managed-identity`
is a sound `handled` -- the provider item genuinely carries it -- and is
still excluded, expression or no expression. The trigger is per-rule data,
not a blanket policy, so plans do not fill with items for mappings that
really did hold.
The schema closes `partialWhen` and the `partial` overlay. A condition key
the planner does not know would never fire while reading as though it did,
which is the defect `additionalProperties: false` is there to catch.
559 passed, 1 skipped. compile --strict exits 0; no selector changed, since
`partial` and `partialWhen` were already in the policy sites' `reads`.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`_policies` dropped any element `policy_rule` did not answer for, and it did
not answer for ten of them: authentication-basic, authentication-certificate
and get-authorization-context, which carry backend credentials; check-header
and validate-client-certificate, which gate callers; emit-metric and
log-to-eventhub; mcp-server and validate-mcp-request; set-service-url; and
every policy APIM ships from now on. None of them reached the plan in any form.
An `<authentication-basic>` was read, classified, and discarded in silence.
The selection order made it worse than it reads. An element carrying a policy
expression fell into the hasExpression pass and was reported as a gap, so what
vanished completely were the elements with no expression in them -- the simpler
the policy, the more certainly it disappeared.
Closed in the three places it can be closed, because no one of them is enough.
A terminal rule, tried after the expression pass and matching anything, makes
"no rule" unreachable at runtime; what reaches it is a blocking gap, since the
alternative is migrating past a policy nobody has read. It is data, not a
default in the planner, so what an unknown element costs stays editable.
A net makes a poor mapping, so `compile` holds every element in policy.FAMILIES
to a rule of its own or a family rule and fails naming any left to the terminal
rule. FAMILIES is committed data, so the question is decidable offline, which is
what compile is for. The eleven are answered by five family rules and one
element rule rather than eleven entries, so the next member of a family is
answered before it is written.
And the plan now counts what became of every element walked, under exactly one
disposition each, with the unrecognised ones named and located. Three
dispositions raise no item; while they were uncounted, a plan that had
classified an element and discarded it could not be told from one that had never
seen it. `walked` is the sum, so the planner can be checked against the
inventory instead of trusted.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The question had two answers in two modules: a forward walk in the
collector that resolved fragments and folded in product and global
scopes, and a backward one in the planner that read a scope level and
returned the APIs under it. They were built from different inputs and
already disagreed -- the collector never folded in the workspace
document, which the planner has a branch for.
So it is answered once, in `policy`, beside the parser whose output it
indexes. `include-fragment` and `base` are already elements carrying a
section and a path, which means inclusion and inheritance are facts in
the document rather than something a caller re-derives: `PolicyGraph`
reads them, and the forward and backward views come off one index, which
is what stops them drifting again.
Three things the collector gets for nothing, because they live in the
new unit rather than at a call site:
* `<base />`. A parent scope's policy runs in a section only where the
child carries `<base />`. An API that overrides its inbound without it
does not inherit the global policy, however globally that policy is
written.
* Workspace. Folded into the chain, and every scope comparison keyed on
the scoped name.
* A fragment included by a fragment, or by the product or global policy.
`policyRefs.fragments` was the first hop of the API's own document;
it is now every fragment that reaches the API, taken from the
resolution so it cannot disagree with it.
Fragment identity is scoped like every other shared asset. Unscoped, two
workspaces with a same-named fragment collapsed onto one id and the
collector kept whichever it saw first, so one workspace's fragment
quietly became the other's.
Two reads that were lying are fixed on the way past. The fragment list
is read with `format=rawxml`, as every other policy read already is, so
a fragment's expressions are captured as authored rather than
XML-encoded and hashed to `expr:` ids that match nothing. And a fragment
whose body could not be read is marked `parseError` instead of parsing
as the empty string, which registered it as a fragment that resolves and
contains nothing -- so whatever it carried migrated as though it were
not there.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`_policies` walked policy documents and asked `_apis_in_scope` to turn a
scope level and a bare name back into the APIs under it. That derivation
could not answer for a fragment or an operation at all -- both fell
through to "covers nothing" -- and answered for an API by its
unqualified name, so `finance/shared` and `hr/shared` were one API to it
and a limit on either reached the models of both.
It is now asked of the graph, per asset, so a member carries the asset
it governs as well as the document it is written in. Four things follow
with no code of their own:
* A policy in a fragment reaches the models of every API that includes
it, through the fragment, through a chain of fragments, or through a
product or global policy -- and not through an API whose section omits
`<base />`.
* `partialWhen: underConditional` sees the include site, so a plain
`set-backend-service` in a fragment pulled in under a `choose` is
demoted. Reading the element's own path, as it had to before, saw
nothing conditional about it.
* A member digest changes when inclusion changes, because the member
leads with the asset. Keyed on where the element is written, a
fragment included by four APIs was one member, and adding a fifth left
a settled decision reading as unchanged.
* A policy on an API this migration excludes raises nothing. Policies
are captured before an API is classified, so every excluded API's
document was walked and could raise a blocking decision about a
workload nobody is migrating.
`policyCoverage` still walks the documents, so it stays a sum over the
inventory rather than over whatever the asset pass happened to reach,
and the elements that reach no asset are counted under `governsNothing`
rather than being absent.
Two things the tally would otherwise have asserted falsely:
* `retry` and `wait` hold real policies. Their children failed the
statement test, never reached rule selection, and would now have been
counted as a statement being configured.
* `validate-jwt` became Entra auth and data-plane RBAC, which is a
decision about how callers authenticate, not an object to write. It
was shaped as a gateway baseline anyway, producing an object with no
settings on it that `api-key create` could never have built -- so
every plan carrying a `validate-jwt` had an object the plan could not
finish configuring, and preflight now blocks on exactly that.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A rule describing policy fragments used to exist and was deleted for
being unreachable -- `_structural` never asked for its kind -- and it
now survives only as the suite's stock illustration of a rule nothing
can select. That is the whole of what was wrong: the tool collects
fragments, and the one place the contract described them was an example
of a rule nobody reads.
So it comes back selectable. AI Gateway has no policy composition at
all: the catalog and the CLI surface snapshot contain the word fragment
zero times, and the policy surface is six declarative types on a
workspace, an alias, a model or a tool server. A fragment therefore has
one fate -- dissolved into whatever includes it -- and the only question
is whether the dissolution keeps what the fragment meant. Five rules,
one per case the planner can classify, and an item per fragment so the
answer is readable without working backwards from the policies the
fragment contributed.
The two cases that are not clean dissolutions are both losses the target
has no place for: a fragment pulled in under a `choose`, where the
condition does not travel, and one included into more than one section,
where one dissolution cannot be both. A fragment nothing includes is
reported rather than dropped, and says whether operation policies were
collected -- an operation can include a fragment, and those documents
are read only when asked for, so "nothing includes it" and "nobody
looked" are otherwise the same silence. An `include-fragment` naming a
fragment this inventory does not hold is blocking and cannot be
accepted: nobody has read it, so nobody can say what accepting it costs.
`compile` holds the five to the planner's own list. The gap it closes is
particular to a site that dispatches on a second match key: a
`policyFragments` rule naming no disposition passes `Selector.governs`,
because pinning fewer keys is allowed and usually right, and is then
never equal to any disposition the planner asks for -- reachable and
unselectable at once.
`structuralRule` now requires `itemKind` only of a verdict that needs
deciding. A handled or notApplicable item has no kind, and demanding one
would have meant inventing a decision shape for a fragment that raises
no decision.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Most of it is `PolicyGraph`, which is pure and takes hand-built
documents, so most of the tests are there rather than in the planner:
splicing, nesting, a cycle, a case-mismatched `fragment-id`, one naming
nothing, `<base />` present and absent, product, operation and workspace
scope, and two workspaces holding a same-named fragment.
The integration tests pin the four claims that only hold end to end: a
fragment's limit lands on the models of every API that includes it and
asks once; a conditional include is not a clean mapping; a globally
included fragment stops at an API whose section omits `<base />`; and
adding an API to a settled fragment decision flags the widening instead
of leaving it reading as unchanged.
Two are regressions in the direction a safety check makes expensive.
`validate-jwt` is on every second AI-fronting APIM instance, and
preflight blocking on it would have cost a migration rather than a
phase. A fragment nothing includes is a fact about the fragment, not an
object the plan failed to build.
The unreachable-rule fixture in `test_compile` needed a different kind:
it was `policyFragments`, which was the whole of what was wrong -- the
tool collected fragments, and the one rule describing them was the
suite's illustration of a rule nobody asks for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The README said policy fragments had no equivalent and that values were
inlined into target configuration, which described named values and
said nothing true about fragments. It now says what the gateway has --
no policy composition of any kind -- and what follows from that, with
the resolution rules written down where a reader can check them against
the plan.
The preflight list said five conditions and refused on eight. A list
that reads as complete and is not teaches an operator to trust it.
Two corrections to claims that were simply wrong. Ten elements matched
no rule, not eleven, which is the number the change that fixed them
reported. And `incompleteObject` told the operator to re-plan, which
reproduces the same objects from the same inventory, and that every one
fails its step, which an `ip-filter` with some convertible ranges does
not -- it succeeds while carrying less than the source did, and that is
the worse of the two outcomes to describe as the impossible one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Some items deliberately recommend nothing: a control-plane read that
failed, and now a fragment nobody could open. Nothing is known about
what choosing would cost, so there is no choice to recommend -- but
rendered as `proposal=None` that read as a defect in the plan rather
than as the plan being honest.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A scope with no policy of its own is transparent, so an API that drops
`<base />` while its product is silent is still overriding the global
policy. Checking only the immediate parent found nothing to report and
left the override unrecorded.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Critical policy-resolution defects can omit operation-level safeguards, misapply inherited policies, and silently drop conditional or unparseable fragment content while marking it handled.
This PR centralizes policy applicability in PolicyGraph so APIM collection and migration planning share fragment and inheritance resolution. It also adds safeguards against silently omitted policies and incomplete target objects.
Changes:
Introduces shared policy resolution with workspace-qualified fragment identities.
Adds fallback rules, policy coverage accounting, and compile-time contract checks.
Blocks incomplete executable objects during preflight and expands regression coverage and documentation.
File
Description
tools/migrate-apim/tests/test_policy.py
Tests fragment resolution, inheritance, and scope handling.
tools/migrate-apim/tests/test_plan.py
Tests routing decisions, fragment applicability, and coverage accounting.
tools/migrate-apim/tests/test_compile.py
Tests policy vocabulary and terminal-rule checks.
tools/migrate-apim/tests/test_collect.py
Tests scoped fragments, unreadable bodies, and raw XML requests.
tools/migrate-apim/tests/test_capability.py
Tests fallback rule selection and known-element coverage.
tools/migrate-apim/tests/test_apply.py
Tests incomplete-object preflight blocking and policy regressions.
tools/migrate-apim/schemas/rules.schema.json
Defines conditional overlays, terminal rules, and fragment dispositions.
tools/migrate-apim/schemas/plan.schema.json
Declares coverage accounting and object-completeness fields.
Review of the first pass found seven places where resolving a scope
once was not the same as resolving every way into it. All seven are the
same mistake in different directions.
**Two arrivals are two arrivals.** A fragment included plainly and again
under a `choose` reaches the same elements by the same chain, and
deduplicating on that kept whichever came first -- losing the
conditional one, which is the only one that needs deciding. The section
is part of a route for the same reason: one fragment pulled into
`inbound` and `outbound` does two different things.
**A branch anywhere on a chain reaches the end of it.** The forward walk
accumulated that and the reverse walk did not, so a fragment included
under a `choose` two hops down reported as plainly dissolved while the
elements inside it were correctly conditional. The two directions come
off one index precisely so they cannot say different things.
**A product is an alternative, not a link.** Which product's policy runs
depends on the subscription a call arrived on, so chaining them let one
product's section without `<base />` suppress a sibling's policy and the
global policy with it -- and made the order they were collected in
decide what reached the plan. Each product is now its own chain, unioned.
**An include is resolved where it is written.** Resolving against the
consuming API's workspace handed a finance API the finance fragment out
of the service's own global policy: a different fragment, a different
policy, and one the reverse lookup disagreed with.
**An operation is a scope of its own.** The chain only reaches it when
asked, and nothing asked -- so an operation-scoped token limit raised no
item and was counted as governing nothing. That is quieter than the
stranding this change exists to end, and worse for being quieter.
**A fragment nobody could read is not an empty one.** The previous pass
marked an unreadable body `parseError` and then spliced its empty
element list anyway, so an include of it reported as a clean dissolution
carrying nothing. It is the same unknown as a `fragment-id` naming
nothing, and is now treated as one.
**Blocking is scoped to what is being migrated.** Unresolved includes
came from every reference in the inventory, so an unreferenced fragment
naming a missing one blocked a migration over a workload nobody was
moving. They now come from what the selected assets actually resolve to
-- the same rule that keeps an excluded API's policy from raising a
decision.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A second review found six more, and they are one mistake again: a
reference in a document is not an arrival at a scope.
**Fragment dispositions come from the resolution now.** Reading them
from the include references called a fragment that only an excluded API
includes "included", raised a decision about a conditional include on a
path nothing reaches, and blocked a migration on an unreadable fragment
no migrated workload touches. The reverse query that answered them is
deleted rather than fixed: it could only ever answer syntactically, and
it had already drifted from the forward walk twice -- missing a branch
partway down a chain, and dropping a second route into a fragment it had
already visited. One direction is the point of the module.
**A member says which scope pulled it in.** A fragment is never an
API's own policy, so asking the document an element is written in made
extracting a policy into a fragment change the answer: a model API that
registers nothing had its loss reported when the limit was inline and
silently dropped when it came from a fragment it included itself.
**A product is an alternative, and so is no product at all.** The chain
with no product in it is always one of them -- a subscription scoped to
the API or service-wide passes through none -- and a linked product with
no policy document of its own inherits transparently but is filtered out
of the product chains for having nothing to contribute. Without the
plain chain, both lost the global policy.
**An operation that overrides is not one that inherits.** Where every
operation of an API carries a policy, each is resolved through the whole
chain and the API's own resolution is dropped: nothing arrives there.
Where some operation has no policy, traffic does arrive there and
inherits, so the API's resolution governs it. Shared ancestors are
deduplicated across operations, or an inherited limit would have been
applied once per operation.
**An include is deduplicated by its route.** A document that includes
one fragment twice runs it twice, and `_backend_auth` reads the last
managed identity in the list -- so collapsing the second arrival changed
which credential an API was recorded as using. What is genuinely one
execution seen twice is the same include reached down two product
chains, and that still collapses, because the route is identical.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Critical unresolved issues can hide missing fragments and policy changes, select the wrong backend identity, and apply operation-scoped limits to unrelated models.
Preserve operation scope when applying model token limits
tools/migrate-apim/migrate_apim/plan.py:1663
An operation-scoped token limit now expands to every model registration of its API, so a chat-only limit also becomes a native/ready write for embeddings models. Different operation limits can consequently overwrite one another because apply._model_policy_set() writes the whole registration without an operation selector. Preserve operation identity, restrict targets where the operation-to-model mapping is known, and require a partial-mapping decision wherever the target cannot preserve that scope.
Three more, from a third review, all in the seam between "what covers
this" and "what runs last".
**A union of alternatives is not an execution sequence.** `Resolution`
now keeps the chains it unioned. An API that sets a managed identity
after `<base />` overrides whatever it inherited, in every context --
but flattened first-seen, its identity was emitted once from the chain
with no product in it and then dropped from the product chain as a
duplicate, leaving the product's reading as the later of the two.
`_backend_auth` takes the last identity of each chain and compares
them. Where they differ there is no answer to pick: two products each
setting their own identity authenticate differently depending on which
one a call arrives through, and a provider cannot do both. The first is
proposed and the alternatives recorded, because choosing silently is a
guess reported as a fact.
**A name is not an identity.** An unreadable fragment was matched to
its reference by name, so an `hr` API naming `limits` when only
`finance/limits` exists looked answered -- the unknown policy went
unmentioned and the finance fragment reported as unused. Reaching a
document and not being able to read it is now tracked by document id,
apart from naming nothing at all, and only the first suppresses the
missing-fragment item.
**A route is part of a member's identity.** One API can include one
fragment twice. Keyed on the destination, the two members agreed on
everything the key read, so one overwrote the other's digest -- and
moving the earlier include, or adding a third, left a settled decision
reading as unchanged.
One thing found on the way past: `auth.mode` has been able to be
`undetermined` since the collector learned to say so, and the schema's
enum never listed it. A value the code produces and the schema rejects
is a contract that holds only until something hits the case.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Replacing legacy member keys can preserve outdated plan decisions as adapted instead of marking them stale, while unreadable fragments can cause false unauthenticated results and missing policy references.
…facts
Two of these are mine from the last round. Splitting "names no fragment"
from "names one that would not load" gave the second nowhere to be
counted, and two readers were counting the first.
**A fragment nobody could read is not an absence of credentials.**
`_backend_auth` consulted only the unresolved list, so an API whose
authentication sits in a fragment with an unreadable body reported
`mode: none` -- the backend called without credentials, stated as a
fact, on the strength of a document nobody opened. Both kinds of
"could not be read" are in the basis now, because for this question
they cost the same.
**And it is not an absence of a fragment.** It contributes no elements,
so it appears on no route, so it fell out of `policyRefs.fragments` --
cutting the asset's only link to the document that records why.
**A decision that shares no member with the item it was settled against
is stale.** `changed` compares the members two plans have in common;
with none in common it finds nothing to compare and the decision
carried forward untouched. That is what every source being replaced
looks like, and it is also what a change to how members are identified
looks like -- this PR gave them the route an element arrives by, so a
plan settled by an earlier build has keys none of these match. Both
want the same answer, which is to ask again.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because interacting policy-scope, overwrite, and coverage gaps can silently weaken rate limits or omit authentication requirements in the migrated workload.
The fix landed last round and the tests covering it used a product that
sets an identity directly. The case as reported has the product
*including a fragment* that sets it, which exercises one more hop and
is the shape an operator actually writes.
It passes, and the test now says so from both ends: the union really
does emit the API's identity first and the product's second -- that is
what resolving the no-product chain first looks like -- and every chain
ends on the API's. Which is the whole argument for the chains existing,
so it is worth having executable rather than argued.
`Resolution.occurrences` says outright that it is a set and not a
sequence. A union of alternatives reads like an order, and the next
reader to want "what runs last" will reach for it; the one before them
did, and got a credential wrong.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because interacting policy-scope and resolution issues can misapply limits or authentication, retain stale routing approvals, and suppress migration blockers.
Facundo Santiago (santiagxf)
changed the title
fix(migrate-apim): answer "which policy governs this API" once
fix(migrate-apim): resolve policy scope through fragments, inheritance and operations
Nov 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #58, closes #59, closes #60, closes #65.
migrate-apimplans a migration by working out which APIM policies govern which API, then expandingeach one into the AI Gateway objects that carry it. Two modules answered that question
independently —
collect, to decide how a backend authenticates, andplan, to decide what a policyitem covers — and neither understood policy fragments,
<base />inheritance, or operation scope.The consequences were not subtle. A token limit an operator had factored into a shared fragment —
the way APIM is meant to share one — reached no API at all: the plan listed it as ready, provisioned
nothing, and the first such object aborted the
policiesphase for every policy queued behind it.The same hole swallowed operation-scoped policies. Elsewhere the two answers disagreed, and a
migrated provider could be given the wrong managed identity.
This replaces both answers with one resolver.
The resolver
policy.PolicyGraphowns which policy governs which API.collectandplanboth read it.It is built from the inventory as the collector already writes it —
include-fragmentandbaseareordinary elements, each carrying its section and path, so inclusion and inheritance are read rather
than inferred. No new inventory field is required for any of this.
APIM will store but never run. A fragment's elements have no section of their own, so they take the
include site's — and a fragment pulled in under a
chooseis conditional however unconditionallyits body reads.
<base />decides inheritance. A parent scope's section runs only where the child asks for it,so an API that overrides its
inbounddoes not inherit the global policy. A scope with no policyof its own inherits, which is APIM's default template. An omission is recorded, not just acted on.
call arrived on, so each is its own chain, alongside the chain with no product in it. One product's
section without
<base />cannot suppress a sibling's policy or the global policy behind it.of its own; otherwise traffic reaches an operation that inherits, and the API's resolution governs.
fragment-idis matched without regard to case, as APIM compares resource names.
Resolutionreturns the union of what governs a scope and the chains it came from. The union is aset, not an execution order — alternatives flattened together have no "last" — so anything deciding
which of two elements overrides the other reads a chain. Backend authentication does.
What changes in a plan
policiesphasefinance/sharedandhr/sharedare one API; a limit on either reaches bothpolicyCoverage.governsNothingretryandwaitnever reach rule selectionvalidate-jwtplans an object with no settings that no builder can writecompilefails if one is left to the catch-allPolicy items now carry what they govern as well as where they are written, so a settled decision
notices an API joining a fragment it was settled against, and a decision that shares no source with
the item it was settled against is re-asked rather than carried forward.
Contract
AI Gateway has no policy composition — no fragments, no includes, no inheritance; the catalog and the
CLI surface snapshot contain the word zero times. A fragment therefore has one fate, dissolved into
whatever includes it, and the only question is whether the dissolution keeps what it meant.
rules.jsongains fivestructuralrules, one per case the planner can classify a fragment into:dissolved, conditional, split across sections, unreferenced, and unresolved. A
policyFragmentsrulepins a second match key,
disposition, andcompileholds the five to the planner's own list —including the case that passes
Selector.governswhile never equalling any disposition a selectionsite asks for.
Testing
672 passed, 1 skipped;compile --strictexits 0; pyflakes clean.Most of the logic is in
PolicyGraph, which is pure, so most of the tests build documents directly:splicing, nesting, cycles, case-mismatched and unresolvable
fragment-ids,<base />present andabsent, product/operation/workspace scope, two workspaces holding a same-named fragment, and the
ordering guarantees the chains exist to provide. The rest pin behaviour end to end, including that a
loss is reported identically whether a policy is written inline or extracted into a fragment.
Against the shipped fixture the plan gains one item — the fragment — and the coverage tally. No
existing item changes status, verdict or object count.
All offline: no Azure resources created, nothing run against a live APIM instance or gateway. These
are contract defects, decidable against the committed catalog, the CLI surface snapshot and the fake
ARM fixture.
Not verified here
A live run against an instance with real fragments.
apim-gateway-demo(StandardV2) is noted in theREADME as carrying policy fragments with C# expressions;
collect+planagainst it, checking eachfragment item against the portal's Used by list, is worth doing before this merges.
Supersedes #66, which fixes the same four issues and should be closed in favour of this.
🤖 Generated with Claude Code