FEAT-STOR-002: Entitlement Lifecycle Transition

Reference Number	Version	Effective Date	Supersedes	Authority Level
FEAT-STOR-002	2.4	2026-10-14	2.3	Normative

I. Purpose

Define the lawful orchestration path by which an entitlement reaches a Store-owned lifecycle disposition.

This FEAT coordinates:

• Store-owned consumption;
• Store-owned expiration;
• Store-owned revocation;
• cross-domain consumption handoff when another domain owns the authoritative exercise event.

The FEAT SHALL NOT mutate the entitlement grant row to represent terminal state. It SHALL write immutable entitlement events only.

II. Authority

This FEAT is the sole lawful writer for entitlement lifecycle events with:

• event_type = CONSUMED
• event_type = EXPIRED
• event_type = REVOKED

when Store and Entitlements owns the lifecycle disposition.

It does not own:

• grant creation;
• class configuration;
• policy definitions;
• Ledger truth;
• obligations truth;
• Productivity or Attendance truth;
• another domain’s authoritative exercise event.

III. Dependencies

• FEAT-CORE-000_FEATURE_EXECUTION_CONSTITUTIONAL_DIRECTIVE.md
• DOM-STORE-001_STORE_AND_ENTITLEMENTS_DOMAIN.md
• DOM-CLASS-001_CLASS_CONFIGURATION_DOMAIN.md
• DOM-POL-001_POLICIES_DOMAIN.md
• DOM-LED-001_LEDGER_DOMAIN.md
• lawful consuming-domain FEAT contracts
• INV-ARC-015_TEMPORAL_MODEL_AND_BOUNDARY_ENFORCEMENT.md
• INV-ARC-016_LAWFUL_EXISTENCE_AND_AUDIT_LINEAGE.md
• INV-ARC-021_CROSS_DOMAIN_REFERENCE_AND_COORDINATION.md

IV. Required Execution Context

The caller SHALL resolve canonical request context before entering this FEAT.

Required canonical context:

• user_id
• class_id
• seat_id
• actor_role

System-driven expiration SHALL use explicit canonical class/seat identifiers and canonical temporal context.

The FEAT SHALL NOT reconstruct seat or class authority from labels, route-local lookups, or cached UI state.

V. Common Preconditions

Before any lifecycle mutation, the FEAT SHALL establish:

1. the entitlement exists;
2. it belongs to the expected class_id and target seat;
3. no conflicting terminal lifecycle event already exists;
4. the requested disposition is lawful for the entitlement type and acquisition provenance;
5. any required cross-domain event has not already been recorded.

Failure to establish any required fact SHALL fail closed.

VI. Store-Owned Consumption

When Store and Entitlements owns the exercise of the entitlement, this FEAT may create:

• event_type = CONSUMED

through consume_entitlement(...).

The FEAT SHALL validate:

• the entitlement is currently exercisable;
• any configured activation condition is satisfied;
• the entitlement has not already terminated;
• the actor is permitted to exercise or authorize the benefit;
• no prior terminal or cross-domain consumption exists.

The created event SHALL reference the exact entitlement_id.

An entitlement type may lawfully support multiple CONSUMED events when its lifecycle semantics permit repeated exercise.

VII. Cross-Domain Consumption

When exercising the entitlement produces an authoritative event owned by another domain, this FEAT SHALL NOT create a Store-owned CONSUMED event for the same exercise.

Instead:

1. the consuming domain’s lawful FEAT validates the entitlement through Store and Entitlements reads;
2. the consuming domain creates its authoritative exercise event;
3. that event references the exact entitlement_id;
4. Store and Entitlements derives that the entitlement is no longer available from the authoritative cross-domain event.

Example:

A hall-pass entitlement is exercised by the Productivity/Hall-Pass domain through hall_pass_logs. No duplicate Store-owned consumption row is created.

VIII. Expiration

Expiration creates:

• event_type = EXPIRED

through expire_entitlement(...).

Expiration is lawful only when:

• the governing policy or product defines a finite validity or coverage boundary;
• canonical temporal resolution proves that boundary has been reached;
• the entitlement has not already terminated or been exercised elsewhere.

Expiration SHALL NOT rewrite the grant.

Insurance expiration

Insurance entitlements may be exercised multiple times during an active coverage cycle according to policy and claim rules.

When a lawful coverage-end boundary is reached, the insurance entitlement terminates through:

• event_type = EXPIRED.

The lawful coverage-end boundaries are (DOM-STORE-001 §VIII.C, §VIII.E.1):

• the end of the last covered period, when renewal has stopped;
• the nonpayment deadline of a CANCEL_AFTER_X_DAYS policy, when the triggering premium is still unsatisfied. This expiry carries a nonpayment cause in its payload and coordinates termination of the premium lineage in the same transaction.

Teacher cancellation of an insurance offering is prospective and SHALL NOT cause early expiration of existing coverage. Nonpayment expiry is not a revocation, is not a refund, and does not reverse or forgive any assessed premium.

IX. Revocation

Revocation creates:

• event_type = REVOKED

through revoke_entitlement(...).

Revocation authority depends on provenance, entitlement type, and policy semantics.

A. Direct grant

A direct teacher grant may be revoked by a lawful teacher actor while unused.

The original grant remains immutable history.

B. Ordinary purchase

An ordinary purchased entitlement may be revoked only through a lawful coordinated REVERSE workflow when that entitlement remains unused or pending. An authorized REFUND workflow may compensate the purchase while retaining the entitlement. The two outcomes MUST NOT be collapsed into one generic “compensation” action.

The FEAT SHALL require:

• the entitlement remains unused;
• the capability is refundable;
• the capability is not insurance or otherwise explicitly non-revocable;
• the corresponding Ledger reversal is authorized;
• entitlement revocation and monetary reversal participate in the required coordinated transaction.

A route or teacher action SHALL NOT directly revoke an ordinary purchased entitlement independently of Ledger reversal authority.

C. Insurance

A lawfully purchased insurance entitlement SHALL NOT be revoked or refunded.

Teacher cancellation affects future acquisition or renewal only.

Withdrawing an offering (hiding or retiring its version) with no successor on sale stops renewal of every entitlement granted under it; each ends at its next coverage boundary. Superseding a version by an edit ends each holder’s entitlement at its boundary and continues the coverage under the successor through a new entitlement (DOM-STORE-001 §VIII.E.1, FEAT-STOR-007 §V.A). Neither expires coverage early.

Existing coverage remains valid until its configured coverage boundary and then expires normally. Nonpayment expiry (§VIII) is an expiry at a lawful coverage-end boundary, not a revocation.

D. Obligations-derived perks

An entitlement with acquisition provenance PERK SHALL NOT be revoked by this FEAT unless the owning policy explicitly allows it.

Any correction to the originating obligation lifecycle must follow the lawful Obligations contract and SHALL NOT erase the historical entitlement event through this FEAT.

X. Instant-Use Coordination

For an instant-use Store-owned capability, FEAT-STOR-001 may coordinate this FEAT within the original purchase transaction.

The transaction SHALL:

1. create the entitlement grant event;
2. create the CONSUMED event for that exact entitlement lifecycle;
3. create one pending action per consumed entitlement, as a reminder for the teacher (DOM-STORE-001 §VIII.E.3);
4. commit the purchase, grant, consumption, and reminder atomically.

If another domain owns the immediate exercise, that domain’s authoritative exercise event replaces the Store-owned CONSUMED write.

The reminder is a pending_actions row with authoritative_feat = FEAT-STOR-002 and the typed payload {kind: "immediate_use_acknowledgement", product_id, policy_uuid}. This FEAT resolves it in one way only: the teacher marks it complete, which deletes the row and writes no entitlement event, because the entitlement is already CONSUMED.

X.B Delayed-Use Redemption Verdicts

A delayed-use redemption request is a pending_actions row with no kind, submitted by the student and resolved by this FEAT with one of the three verdicts of DOM-STORE-001 §VIII.E.4. No terminal event is written while the request waits. The resolution SHALL, in one transaction:

• Accept: record CONSUMED;
• Deny: record REVOKED;
• Return: record no entitlement event;

and delete the pending action. A verdict moves no money and is final for that request. After a return, the student still holds the entitlement and may submit a new request.

Accept and deny carry the request’s facts (the student’s note and the submission time) onto the terminal event’s payload, because the pending action they came from is deleted.

X.A Hall-Pass Request Submission

A hall-pass entitlement whose exercise requires approval supports a pending action (DOM-STORE-001 §VIII.E.6, §IX). This FEAT submits it; the exercise itself belongs to FEAT-PROD-002 (§VII).

Required context: the requesting student’s CanonicalContext (class_id, seat_id). Callers SHALL have verified the student’s credential and active work session before entering.

The FEAT SHALL, in one transaction:

1. resolve a hall-pass entitlement available to the seat in the class, and fail closed when there is none;
2. delete the seat’s earlier pending hall-pass request in that class, if any. A student’s new request is their cancellation of the earlier one, and it happens here rather than as a separate step;
3. write one pending_actions row with:
   • class_id and seat_id from context;
   • entitlement_id — the available entitlement resolved in step 1, the lifecycle acted upon;
   • correlation_id — hall_pass_request:{class_id}:{pending_action_id};
   • authoritative_feat = FEAT-PROD-002;
   • payload — exactly the typed envelope {kind: "hall_pass_request", requested_by_seat_id, destination}. These are the inputs FEAT-PROD-002 takes when it records the pass; the envelope SHALL NOT carry names or other identity material;
   • submitted_at — the request instant in class canonical time (canonical_temporal_resolver, current time). It is authoritative and SHALL NOT be rewritten.

Submission writes no entitlement event and no hall_pass_logs row. It does not consume the pass, and the entitlement_id it records does not reserve that entitlement: approval consumes whichever pass is available when it is approved.

XI. Idempotency

Lifecycle operations SHALL be idempotent.

A replay of the same lawful lifecycle operation SHALL NOT create duplicate terminal events.

A request attempting a different terminal disposition after an authoritative event exists SHALL fail.

XII. Correlation and Lineage

Every terminal event SHALL carry a lawful correlation_id.

For manual consumption or revocation, the correlation identifies that lifecycle.

For purchase reverse or refund, correlation SHALL preserve the original purchase’s correlation_id across the terminal Ledger compensation and any resulting entitlement event.

For expiration, correlation SHALL identify the lawful expiration operation or batch lifecycle without converting audit lineage into business authority.

XIII. Failure Contract

Representative failures include:

• ENTITLEMENT_NOT_FOUND
• SCOPE_MISMATCH
• ENTITLEMENT_NOT_EXERCISABLE
• ENTITLEMENT_ALREADY_TERMINATED
• ENTITLEMENT_ALREADY_CONSUMED_EXTERNALLY
• NOT_YET_EXPIRED
• REVOCATION_PROHIBITED
• INSURANCE_NON_REVOCABLE
• OBLIGATION_GRANT_NON_REVOCABLE
• LEDGER_REVERSAL_REQUIRED
• CROSS_DOMAIN_FAILURE

XIV. Prohibited Patterns

The following are prohibited:

• mutating or deleting the original entitlement grant to represent termination;
• storing status on the grant row as canonical authority;
• creating both a Store CONSUMED row and a cross-domain consumption record for the same exercise;
• revoking purchased items without lawful Ledger reversal/refund coordination when revocation is permitted;
• revoking or refunding insurance coverage;
• revoking obligation-derived entitlements contrary to policy;
• treating insurance claim submission, approval, or rejection as entitlement consumption;
• expiring active insurance early because the teacher cancelled future coverage;
• deriving expiration from server-local time instead of canonical temporal context.

XV. Postconditions

On successful Store-owned termination:

1. the original entitlement grant remains unchanged;
2. exactly one authoritative lifecycle fact exists for the disposition;
3. the terminal fact references the exact entitlement;
4. availability projections exclude the terminated entitlement;
5. any required cross-domain coordinated effect has completed atomically.

XVI. Amendment

2.4 (2026-10-14) §IX.C states what withdrawing and superseding an insurance offering do to existing holders (owner ruling 2026-10-14).

Revisions must remain consistent with DOM-STORE-001, FEAT-STOR-001, DOM-CLASS-001, DOM-POL-001, DOM-LED-001, and the governing FEAT and temporal invariants.