@plasius/economy 0.3.1 → 0.4.0

package/README.md

@@ -4,10 +4,11 @@ Provider-neutral TypeScript contracts and deterministic invariants for the
 Plasius sitewide Token economy.
 
 This package models exact TokenSubunit amounts, immutable double-entry journal
-transactions, source lots, family gameplay reservations, early-backer basis,
-future spend requests, acquisition contracts, projections, and persistence
-ports. It intentionally contains no HTTP, authentication, provider SDK,
-database driver, secret, or Azure implementation.
+transactions, source lots, family gameplay reservations, purpose-bound learning
+module allowances, early-backer basis, future spend requests, acquisition
+contracts, projections, and persistence ports. It intentionally contains no
+HTTP, authentication, provider SDK, database driver, secret, or Azure
+implementation.
 
 ## Product boundary
 
@@ -160,6 +161,44 @@ settlements after `evaluatedAt`. The caller must derive both window timestamps
 from the entire public cohort and exclude non-production/test lots: staff,
 closed-beta, and test availability must never open or close the public window.
 
+## Junior Coder Module Allowances
+
+`ModuleAllowanceV1` is a Guardian-funded reservation for one linked child and
+one purpose: purchasing independently sellable Junior Coder module
+entitlements. It is deliberately separate from `GameplayAllocationV1`; callers
+cannot spend gameplay value as a learning allowance or silently move learning
+value into gameplay.
+
+The purchase contracts implement the deterministic parts of:
+
+```text
+immutable quote -> allowance hold -> pending entitlement
+  -> settle spend -> activate entitlement -> durable receipt
+```
+
+An immutable quote binds the exact module version, Token price, child,
+Guardian acknowledgement, catalog version, and requirements-manifest version
+plus canonical SHA-256 reference. This makes software-only declarations and
+robotics bills of materials durable pre-purchase evidence even after a live
+manifest changes.
+
+`createModuleSpendHold()` moves whole Tokens from available to held value.
+`settleModuleSpendHold()` requires a pending entitlement ID before it can move
+held value to spent value. `releaseModuleSpendHold()` returns failed or expired
+holds to the same Module Allowance. `createModulePurchaseReceipt()` accepts only
+matching quote and settled-hold evidence. `reconcileModulePurchase()` returns
+one forward-safe repair instruction and fails closed to manual review for a
+settled debit without an entitlement or an active paid entitlement without a
+settled debit.
+
+These functions produce immutable next-state projections; they do not perform
+authorization or persistence. The consuming service must evaluate
+`learning.junior-coder.purchase.enabled`, enforce Guardian/child capabilities,
+store actor/subject/operation-scoped idempotency evidence, and compare-and-swap
+allowance and hold versions alongside the balanced journal, entitlement,
+receipt, and outbox in a serializable transaction. A disabled feature may still
+release and reconcile existing holds, but must reject new quotes and purchases.
+
 ## Acquisition and future contracts
 
 Purchase intents bind payer, receiving household/wallet, pack, catalog,
@@ -172,6 +211,45 @@ versions, exact payout values, and beneficiary/wallet IDs. ayeT and BitLabs lots
 are structurally restricted to `same-user-only`; changing a provider-earned lot
 to household-allocatable is rejected.
 
+### Deterministic paid-acquisition lifecycle
+
+`PurchaseIntentLifecycleV1` adds receipts and optimistic versions around the
+unchanged `PurchaseIntentV1`. `reducePurchaseIntentTransitions()` canonicalizes
+out-of-order checkout, payment, credit, expiry, cancellation, and dispute
+evidence. Exact retries collapse, conflicting ID reuse fails, and one intent
+can emit at most one stable intent-ID-scoped credit instruction. The transition
+name is `checkout-bound`; the published compatible intent status remains
+`checkout-created`.
+
+`reserveRollingPurchaseCaps()` mirrors one exact GBP-minor-unit reservation
+into payer and household aggregates. Both expected versions must match and both
+returned versions must be committed in one serializable transaction.
+Settlement keeps the amount in the rolling window; release and expiry free it.
+Exact command replays are no-ops, including after finalization. GBP minor units
+use canonical non-negative signed-64-bit strings through
+`parseGbpMinorUnits()` and `serializeGbpMinorUnits()`.
+
+`PaidLotLifecycleV1` separately preserves early-backer retained basis:
+
+- a dispute hold leaves retained basis unchanged;
+- a dispute win releases only the hold;
+- refunds, lost disputes, direct chargebacks, and the one permitted reversal
+  reduce retained basis exactly;
+- partial outcomes retain their unreversed remainder;
+- `createEarlyBackerRetentionFromPaidLot()` supplies a current
+  `PaidLotRetentionV1` for recalculation.
+
+Retained basis is not a spendable-balance claim. Before a compensation commits,
+the authoritative service must atomically reclaim allocated-but-unused value,
+reject value already spent or otherwise unavailable, append balanced journal
+postings, update source-lot/lifecycle projections, save idempotency evidence,
+and append the outbox. This package contains none of those provider or
+persistence adapters.
+
+These contracts do not enable checkout. The site must still enforce
+`economy.tokens.shopify.enabled`, payer/household authorization, legal gates,
+provider-signature verification, and server-derived purchase facts.
+
 `BASELINE_MONTHLY_SUBSCRIPTION_PLAN` preserves the provider-neutral future £10
 monthly/100 Token shape with `enabled: false`. Spend-request contracts likewise
 exist for future use but this package does not enable their creation.
@@ -243,7 +321,14 @@ Coverage must remain at least 80%, and every changed source file must appear in
 LCOV. Generated property tests cover exact arithmetic, double-entry balance,
 projection rebuilds, idempotency, reversals, lot isolation, and allocation
 non-negativity. npm publication is performed only by the approved GitHub CD
-workflow.
+workflow on configurable trusted self-hosted runners. Release LCOV and the
+CycloneDX SBOM remain retained even when an external coverage or npm provenance
+service is unavailable. Release tags and GitHub Releases use a current-repository
+GitHub App token with explicit Contents and Workflows write permissions; npm
+publication continues to use only the protected `NPM_TOKEN`. Both release jobs
+install a checksum-pinned GitHub CLI under `RUNNER_TEMP`. A requested version
+bump reuses the current version only when neither npm nor GitHub records it as a
+completed release; use `bump=none` for deliberate recovery of prepared metadata.
 
 ## Security