49 lines
2.5 KiB
Go
49 lines
2.5 KiB
Go
// 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
|