fix(#77): surface parser policy ids in diagnostics + add id_annotations map

[skuenzli]

Summary

• Reverts the 4.8.2 behavior of renaming AuthzResult.diagnostics.reasons entries and ValidationError.policy_id to the @id annotation value, which collapsed identity when multiple policies shared the same @id (e.g. the multi-tenant baseline-permit pattern reported in v4.8.2: diagnostics.reasons collapses tenant identity when two policies share an @id annotation #77). Both surfaces are back to the parser-generated PolicyId (e.g. "policy0").
• Exposes the @id label via a new parallel id_annotations: Dict[str, str] map on Diagnostics and ValidationResult, keyed by the parser id. An entry is present whenever the policy declares an @id annotation, with the literal value — so @id("foo") contributes "foo", and @id("") / bare @id (which the Cedar docs define as equivalent to @id("")) contributes "". Policies with no @id annotation are omitted from the map.

Why

Issue #77 reported a regression in the diagnostic surface: in 4.8.1, two policies sharing @id("baseline-permit-all") returned distinct reasons ("policy0" vs "policy1"); in 4.8.2 they collapsed to the same string, silently misrouting in callers that used reasons as the lookup key into their own {positional_id → caller_id} map.

This PR keeps the 4.8.2 ergonomics gain — recover the @id label without rebuilding the policy set — while restoring the 4.8.1 disambiguation property.

Shape of the change

result = is_authorized(request, policies, entities)
result.diagnostics.reasons              # ["policy0"]  — parser-generated id, stable per policy
result.diagnostics.id_annotations       # {"policy0": "baseline-permit-all"}  — present iff @id declared

vr = validate_policies(policies, schema)
vr.errors[0].policy_id                  # "policy0"
vr.id_annotations                       # {"policy0": "baseline-permit-all"}

Implementation notes:

• reason is now typed HashSet<PolicyId> (was HashSet<String>) — JSON serialization unchanged (PolicyId emits a string), but the Rust type is tighter now that the field no longer holds annotation values.
• lookup_id_annotation replaces resolve_display_id; it is purely an existence check on the @id annotation key with raw &str matching (no PolicySet::annotation identifier-parse cost on the hot path).

Behavior of id_annotations

policy declares	id_annotations[pid]
@id("foo")	"foo"
@id("")	""
@id (no parens, per docs ≡ @id(""))	""
no @id	omitted

Test plan

• Unit tests rewritten for the new shape; new test_issue_77_multi_tenant_baseline_permit_disambiguates exercises the reproducer from the issue.
• pytest tests/unit — 63 passed, 2 subtests passed.
• make benchmark-compare (release-mode build, 5% median / 15% mean gates) — 26 passed, no regression. Largest movement is test_large_entity_set at ~4% faster than baseline; everything else within ±2% on median.

Closes

Closes #77.

🤖 Generated with Claude Code

[skuenzli]

What do you think about this approach @aashitk and @Iamrodos ?

[Iamrodos]

See my commend in #77 suggesting reasons_ids (growing as my preferred) or reasons_as_ids

[skuenzli]

re reasons_ids:

from #77 (comment)

Good approach. As policies as passed, id_annotations could speak to a parsing use case or any number of other things. I would prefer to see reasons in the name so it's linked to what the values are. Potentially reasons_as_ids or reasons_ids.

Thank you. I think including 'reason` in the name makes a lot of sense to connect with related data.

I brainstormed names that would connect the id annotations to authz diagnostic reasons and validate policies in the most Pythonic way and settled on:

• Diagnostics.id_annotations_by_reason
• ValidationResult.id_annotations_by_policy_id (this validation result is always for policy validation)

[skuenzli]

Merging to restore unambiguous (policy id) reasons and support improved ergonomics with supplemental Diagnostics.id_annotations_by_reason and ValidationResult.id_annotations_by_policy_id fields.