// Package entitlements owns runtime entitlement state for resource pools:
// grants (decrees), materialized provisions, ladder attachments, and the
// audit trail of position changes.
//
// # Sole-writer rule (Doc 41)
//
// "Doc 41" throughout this codebase cites the upstream design decision
// record doc-41-product-kind-taxonomy-recommendation.md (membcons-db
// documents/, Decisions 134-139), implemented here by the archived change
// openspec/changes/archive/2026-07-11-doc41-conferral-uniformity and
// migrations 00004-00006.
//
// The five SECURITY DEFINER database functions installed by migration 00005
// — core.confer, core.end_conferral, core.sync_source_status,
// core.align_conferral_shape, core.update_conferral_bounds — are the only
// writers of core.pool_provisions, core.pool_provision_ladders, and
// core.pool_provision_transitions. The application role holds no direct DML
// on those tables; the enclosure is enforced by the database, not by
// convention. Go calls the functions through the typed wrappers in
// conferral.go, the single boundary that also maps the functions' named
// errors (SQLSTATEs CF001-CF004) to the exported ErrConferral* sentinels.
//
// Callers never choose position behavior: everything beyond (pool, product,
// source, bounds, attribution) is derived inside the functions from
// core.product_conferral_shapes.
//
// # Composition contract
//
// Every conferring flow composes decree -> confer -> materialize in one
// transaction (ConferGrantTx is the grant-sourced helper); ending flows
// compose decree -> end_conferral -> materialize likewise. Materialization
// (MaterializePoolEntitlements, materialize.go) stays application-side,
// below the enclosure line.
//
// Call sites:
//
//   - internal/server/operator_enrollment.go  — operator issue/extend/revoke
//   - internal/server/operator_org_types.go   — default-change commit: initiate/grandfather/migrate
//   - internal/server/operator_plan_ladders.go — align_conferral_shape on tier add
//   - internal/fulfillment/reconcile.go       — subscription diff: confer/end/bounds/sync
//   - internal/workflows/entitlements/        — grant expiry: decree + end_conferral
//   - internal/provisioning/provisioning.go   — default grant on org creation
//   - internal/demoseed/                      — seeded grants
//
// See docs/models/plan-ladders-transitions.md for the full model description
// and status/archive/incident-2026-04-grant-provision-sync.md for the
// incident that motivated the sole-writer protections.
package entitlements