Polaris Tag Management: tag assignment write path

[flyingImer]

Tip

Until #5391 merges, the files view includes the spec commit from #5366 and the definition commit from #5391. For this slice's own diff, review the head commit: flyingImer@fff2ce1

GH proposal tracking: #5442

Why

#5391 makes Tag definitions usable, but nothing can be attached to them yet, and an authorized detach-all=true drop answers 501. This PR lets a tag be assigned to a catalog, a namespace, a table-like object, or a top-level Iceberg table column, one value per definition and target, validated against the allowed values, and unassigned again. Dropping a definition with detach-all=true now removes the definition and every assignment together, or nothing at all.

Reads and reverse lookup are the next slice. Management grants for the new privileges are a later slice. NoSQL stays unsupported.

Scope

• PUT and POST on /tags/{tag-name}/mappings assign and unassign; assigning again replaces the stored value.
• Both operations check two privileges: TAG_ATTACH or TAG_DETACH on the definition, plus a target-side {CATALOG,NAMESPACE,TABLE}_{ATTACH,DETACH}_TAG. CATALOG_MANAGE_CONTENT covers all of them. Tags classify resources only; they do not grant or deny access.
• JDBC persistence on schema v7 (new tag_assignment_record table; existing databases need a one-time manual SQL, documented in the CHANGELOG and the metastore docs); writes on an older schema fail with an error naming the v7 requirement. In-memory is supported. NoSQL rejects assignment operations and tag drops explicitly. A backend that cannot guarantee the detach-all result answers 501 to detach-all=true and changes nothing.
• The selected value is checked against the definition inside the write transaction, and the write conflicts with a concurrent update of the definition's allowed values: an update that completes first rejects a removed value, an assignment that completes first is grandfathered. A first-write race on one identity re-runs once; a second conflict surfaces as a server error. Unassigning an assignment that is already gone answers 404.
• Allowed values and assigned values are limited to 2000 UTF-8 bytes: the value is part of a database index key, an implementation limit under the spec's section 1.3.
• A malformed target, a view, a non-Iceberg column, a null or empty path segment, a path segment containing U+001F, or more than one selected value answers 400.
• Tags remain disabled by default behind ENABLE_TAG_STORE. Target deletion cleans up assignments best-effort on the shared entity drop path; leftover rows are hidden by the read slice.

Extension points

Three mixin interfaces carry the assignment contract, threaded the same way PolicyMappingPersistence was: BasePersistence gains TagAssignmentPersistence, TransactionalPersistence gains TransactionalTagAssignmentPersistence, and PolarisMetaStoreManager gains PolarisTagAssignmentManager. Every persistence method, including the detach-all capability, is a default that reports "not supported", so an out-of-tree backend keeps compiling and stays fail-closed until it opts in. The manager's assignTagToEntity and unassignTagFromEntity are abstract, the same shape as PolarisPolicyMappingManager's attach and detach. A note describing this delta is posted on the design thread with this PR.

Validation

The integration test covers assign, unassign and detach-all end to end on JDBC and in-memory, replacement and grandfathering, malformed targets answering 400 and the value bound. The authorization test covers the privilege matrix and the detach-all two-privilege rule. The schema gate test pins the write rejection below v7. The JDBC unit tests inject a failure between the two deletes of the atomic drop and assert the rollback, and drive the two-writer conflict cases for the definition check and the first-write race. The shared metastore contract runs against PostgreSQL at every schema version.

This PR will remain Draft until #5391 merges and the rebased SHA passes CI.

Context

• Tag API contract
• Tag definition CRUD
• Design doc
• Dev-list discussion

AI-assisted contribution

AI assistance was used for implementation and consistency review. I reviewed the final behavior and diff and take full responsibility for the contribution.

Checklist

• 🛡️ Don't disclose security issues! (contact security@apache.org)
• 🔗 Clearly explained why the changes are needed, with design and dev-list links
• 🧪 Added/updated tests with good coverage, or manually tested
• 💡 Added comments for complex logic
• 🧾 Updated CHANGELOG.md
• 📚 Updated documentation in site/content/in-dev/unreleased