Simplify policy import model: replace entriesAdditions and importsAliases with entry-level references

[thjaeckle]

Summary

Resolves #2423

Replace entriesAdditions and importsAliases concepts with a single references array on policy entries. Each reference is either:

• Import reference ({"import": "policyId", "entry": "label"}) — inherits resources and namespaces from the imported entry
• Local reference ({"entry": "label"}) — inherits subjects, resources, and namespaces from a local entry

What's new

• EntryReference model with import and local reference support
• REST API: GET/PUT/DELETE /entries/{label}/references
• Commands, responses, events for references with full Ditto protocol adapter coverage
• Referential integrity validation:
  • Local references must target existing entries (400)
  • Import references must target declared imports (400)
  • Cannot delete an import still referenced by entries (409)
  • Cannot delete an entry locally referenced by another entry (409)
  • Validated on CreatePolicy, ModifyPolicy, ModifyPolicyEntries, ModifyPolicyEntry, ModifyPolicyEntryReferences

What's removed

• entriesAdditions on imports (model, signals, strategies, routes, tests)
• importsAliases on policy (model, signals, strategies, routes, tests)
• ~17,700 lines of code deleted

What's preserved (backward compat)

• entries filter on import
• importable (implicit/never)
• transitiveImports
• allowedImportAdditions

[hu-ahmed]

Thanks @thjaeckle — the 4 design answers all verified against code and runtime:

• A1 (one-level resolution, no cycles) — confirmed at PolicyImporter.java:307-324
• A2 (409 on delete of referenced entry) — verified live: "policies:entry.referenceconflict" with clear message naming both entries
• A3 (self-reference rejection at write time) — verified on PUT /references, PUT /entries/{label}, and PUT /policies/{id}
• A4 (allowedImportAdditions only for import refs) — confirmed at PolicyImporter.java:366-368

Four follow-up items from live testing against the branch:

1. Local-ref-only policies silently lose authorization

This is the one I'd most like to address before merge. Reproduced live:

Same policy structure; only difference is top-level imports{} being empty vs populated.
  imports: {}                      → Alice GET /features/temp → HTTP 404                                                                                                                                                        
  imports: {ns:template-empty: {}} → Alice GET /features/temp → HTTP 200

Root cause: Policy.java:470 gates resolveReferences behind !imports.isEmpty(). A policy that uses only local references — exactly the shape in the power-plant example in this issue's body — never triggers reference resolution. Suggest calling resolveReferences whenever any entry has non-empty references, regardless of whether imports is empty.

2. Status code / exception type inconsistency

The issue body describes rule 1 as "400 Bad Request." Actual behavior:

Scenario	Status	Error code
PUT /entries/{label}/references with undeclared import	400	policies:import.invalid
CreatePolicy / ModifyPolicy / ModifyPolicyEntry with invalid reference	403	policies:entry.modificationinvalid
Self-reference (any path)	403	policies:entry.modificationinvalid
Ref to non-existent local entry	403	policies:entry.modificationinvalid

PolicyEntryModificationInvalidException is hardcoded HttpStatus.FORBIDDEN at line 57 with a DEFAULT_DESCRIPTION about WRITE-on-policy:/ — it's the "no-writer-left" exception. Reusing it for reference validation produces a 403 where 400 is more appropriate, and a cross-command inconsistency (400 via one endpoint, 403 via others). Suggest PolicyEntryInvalidException (400) or a reference-specific exception.

3. Silent drop of non-object elements in references arrays

PUT /entries/operator/references                          
Body:     [{"entry":"shared"}, 42, "bogus"]
Response: 204                                                                                                                                                                                                                   
Stored:   [{"entry":"shared"}]

Six call sites using .filter(JsonValue::isObject) — ImmutablePolicyEntry.readReferences, ModifyPolicyEntryReferences.fromJson/setEntity, PolicyEntryReferencesModified.fromJson/setEntity,
RetrievePolicyEntryReferencesResponse, AbstractPolicyMappingStrategies.entryReferencesFrom. Same antipattern class flagged before — worth an explicit validating loop that throws PolicyEntryInvalidException naming the bad element.

4. Cross-command READ authorization for references

PolicyImportsPreEnforcer.apply (lines 94-108) routes only ModifyPolicyEntryReferences to validateReferencesModification. For CreatePolicy, ModifyPolicy, ModifyPolicyEntries, and ModifyPolicyEntry — only top-level imports are READ-checked, per-entry reference targets are not. A caller can add an import reference to a template entry they don't have READ on by going through ModifyPolicyEntry rather than /references. Impact scope: information disclosure at resolution time rather than privilege escalation (import refs don't merge subjects), but a cross-command discipline gap worth closing.

Smaller notes:

• PolicyImporter.rewriteLabel drops references from imported entries (6-param factory) while the merge path preserves them (7-param). Either reject references on non-NEVER entries at write time, or extract a
  cloneEntry helper so no path reconstructs a PolicyEntry with fewer than 7 fields.
• Duplicate references ([{entry:"x"},{entry:"x"}]) are accepted as-is; resolution merges twice.
• No ETag support on /references sub-resource.
• ImmutablePolicyBuilder.setPolicyEntry only puts entryReferences when non-empty — re-setting with an empty list doesn't clear prior value (latent).