@plasius/economy 0.3.2 → 0.5.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
 
@@ -92,6 +93,7 @@ const transaction: LedgerTransactionV1 = {
   transactionId: "txn:purchase:1",
   activityType: "purchase",
   status: "settled",
+  // Legacy V1 example. V3 writes the domain-separated HMAC digest here.
   idempotencyKey: "intent:1:paid",
   effectiveAt: "2026-07-15T10:00:00.000Z",
   recordedAt: "2026-07-15T10:00:01.000Z",
@@ -119,13 +121,133 @@ assertBalancedTransaction(transaction);
 const payloadForApprovedHashAdapter = canonicalTransactionPayload(transaction);
 ```
 
-The package produces canonical bytes but deliberately leaves SHA-256/HSM
-signing to an approved infrastructure adapter. Metadata keys and posting IDs
-are ordered with locale-independent UTF-16 code-unit comparison. Their
+The package produces canonical bytes but deliberately leaves SHA-256 hashing
+and any signing to an approved infrastructure adapter. Metadata keys and
+posting IDs are ordered with locale-independent UTF-16 code-unit comparison. Their
 validated ASCII alphabet makes that ordering identical to PostgreSQL
 `COLLATE "C"`; adapters must hash the exact UTF-8 bytes returned by
 `canonicalTransactionPayload()`.
 
+## Audit receipts and integrity verification
+
+`AuditedEconomyCommandEnvelopeV1` is a standalone, fingerprint-only V3
+contract. It binds actor, subject, principal type, delegated
+relationship/version, sanitized capability/flag/assurance evidence, route,
+build, region, writer fence, correlation, causation, and payload. It never
+extends the legacy raw-key envelope.
+
+`EconomyHmacFingerprintV1` records an exact domain, key version, and
+`hmac-sha256:` digest. Raw idempotency keys, provider event/object IDs,
+callback bodies, and reconciliation material use distinct domains. Provider
+commands require a canonical `EconomyProviderEvidenceManifestV1`; callback
+signatures and payment data have no contract field.
+
+Encrypted operational provider handles remain site-owned.
+`EconomyEncryptedOperationalHandleBindingV1` binds only their purpose,
+provider, AES-256-GCM label, key version, ciphertext-content hash, and
+encryption-context hash. It contains no ciphertext, nonce, authentication tag,
+plaintext, or Key Vault URI.
+
+`EconomyAcceptedCommandReceiptV1` is safe to return after durable acceptance:
+it exposes only receipt, command, and correlation IDs plus the command-envelope
+hash and acceptance time. `EconomyCommandResultReceiptV1` is terminal and
+exclusive:
+
+- `completed` requires a transaction ID and its existing canonical hash and
+  forbids outcome codes;
+- `failed` requires one bounded safe failure code and forbids transaction
+  fields;
+- `no-op` requires one bounded safe no-op code and forbids transaction fields.
+
+Every terminal shape retains a result hash. Replay is a processing mode, not a
+command source: `assertExactAuditedEconomyCommandReplay()` requires identical
+canonical bytes and preserves the original source. A collision with different
+bytes is a security conflict.
+
+The audit canonicalizers use explicit fixed field order and omit absent optional
+fields. Runtime validators reject unknown fields rather than allowing raw
+evidence to be persisted accidentally. `canonicalTransactionPayload()` is
+unchanged. A V3 transaction stores the HMAC digest in its legacy canonical
+`idempotencyKey` field; the HTTP key is never stored.
+
+`EconomyAuthorityHeadV1` and hash-linked
+`EconomyAuthorityCommitManifestV1` cover every immutable record, conditional
+projection replacement, idempotency result, and outbox effect. Manifests
+support only `create` and `conditional-replace`; batches are limited to 80
+operations and 1.5 MiB. The manifest create and head replacement reserve
+two operations, leaving at most 78 canonical record references.
+`assertEconomyAuditGraph()` recomputes the complete command/evidence/receipt/
+transaction/manifest graph and expected head.
+`assertEconomyAuthorityRecoveryEvidence()` additionally recomputes the
+successful prior verification receipt bound by any reopening manifest.
+
+First-party commands use one atomic authority boundary. Provider workflows use
+one boundary to durably accept verified evidence before acknowledgement and a
+second boundary to record the externally reconciled completed, failed, or
+no-op result.
+
+`verifyJournalChainSegment()` accepts an approved canonical-payload hash
+function, recomputes every transaction hash, checks previous-hash links and
+duplicate transaction IDs, and proves the resulting head against an expected
+head. `EconomyIntegrityVerificationReceiptV1` binds authority, journal, and
+projection verification outcomes. `EconomyIntegrityAnchorManifestV1` defines
+canonical hourly Merkle evidence while signing, keys, and storage remain
+infrastructure responsibilities.
+
+## Recoverable acknowledgements and portable receipts
+
+The additive recovery protocol protects the acknowledgement boundary without
+turning an evidence store into a second economy writer:
+
+- `EconomyRecoveryAcceptanceEnvelopeV1` binds the provider-neutral audited
+  command, accepted receipt, HMAC idempotency fingerprint, and an AES-256-GCM
+  sealed reconstruction payload before command processing;
+- `EconomyRecoveryCommittedResultV1` binds that exact acceptance to the
+  terminal result receipt, authority commit/head, sequence, optional completed
+  transaction, and sealed reconstruction payload after the authority commits;
+- `EconomyRegionalEvidenceReceiptV1` is a signed, sequence-addressed,
+  hash-chained retention assertion for the byte-identical acceptance or result
+  stored in one evidence region; and
+- `EconomyPortableCustomerReceiptV1` binds a positive TokenSubunit amount and
+  direction to the completed transaction, result, authority sequence, at least
+  two regional evidence receipts, and an optional authority-commit Merkle
+  inclusion proof.
+
+Every recovery record has a SHA-256 content-addressed ID derived from a
+separate, explicitly ordered canonical body. Detached signatures cover that ID,
+the complete body, and public algorithm/key-version/time metadata. The package
+does not implement hashing, encryption, signing, key lookup, Blob access, or
+identity. Callers supply approved hash and signature-verification functions;
+`assertEconomyRegionalEvidenceChain()`,
+`assertEconomyRegionalEvidenceEquality()`,
+`assertEconomyMerkleInclusion()`, and
+`assertEconomyPortableCustomerReceiptEvidence()` run without a cloud SDK or
+authentication dependency.
+
+Recovery validators reject unknown fields. Plaintext records have no field for
+raw idempotency keys, provider/payment facts, callback bodies/signatures,
+storage URIs, payer/household/account identity, email, session data, or exact
+birth data. A portable receipt contains only opaque command/transaction
+references, proof hashes, amount/direction, safe activity, terms version, and
+`cashRedemptionAllowed: false`. The sealed payload's plaintext remains subject
+to the same approved privacy-minimized authority schema; encryption is not
+permission to retain unnecessary data.
+
+A consuming service may acknowledge a provider callback after identical
+acceptance evidence is durable in both approved regions, then process it
+asynchronously. A successful browser value command is not customer-acknowledged
+until the authoritative commit and both regional committed-result receipts
+exist. Cross-service writes are not a distributed ACID transaction: exact
+content IDs and idempotent create-only completion make orphan acceptances and
+committed-but-not-yet-acknowledged results recoverable without duplicating
+value.
+
+These contracts enable a scoped recoverability claim only after the consuming
+infrastructure proves dual durable writes, locked retention, independent keys,
+monitoring, and tested reconstruction. They do not by themselves establish
+zero RPO, WORM retention, HSM custody, administrator-proof storage, or
+availability.
+
 ## Source-lot policy and allocations
 
 `selectSourceLots()` selects spendable slices in credited-time/lot-ID order and
@@ -160,6 +282,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,
@@ -267,6 +427,15 @@ journal rows directly. The V2 adapter is responsible for:
 - managed identity and least-privilege database access; and
 - immutable audit/integrity evidence outside this package.
 
+`EconomyPersistencePortV3` is additive and retains every V2 economic primitive.
+It removes V2's raw-key idempotency operations from its unit and replaces them
+with `EconomyAuditedIdempotencyScopeV1` and
+`EconomyAuditedIdempotencyResultV1`. It adds audited commands, evidence
+manifests, encrypted-handle bindings, receipts, authority commits/head CAS,
+integrity receipts, and anchor manifests. Its journal method accepts
+`AuditedChainedEconomicJournalTransactionV1`, whose legacy idempotency slot is
+type-narrowed to an HMAC digest. V1 and V2 remain exported unchanged.
+
 ## Development
 
 ```bash
@@ -282,10 +451,20 @@ 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.
+Publication checks out the verified current release-branch HEAD so that recovery
+always includes the reviewed workflow tooling.
 
 ## Security
 
-Do not include raw payment details, personal data, provider callback bodies, or
-secrets in contracts, metadata, tests, examples, or logs. Report vulnerabilities
-privately according to [SECURITY.md](./SECURITY.md).
+Do not include raw idempotency keys, provider identifiers, provider callback
+bodies or signatures, payment details, personal data, encrypted-handle
+ciphertext, or secrets in contracts, metadata, tests, examples, or logs.
+Report vulnerabilities privately according to [SECURITY.md](./SECURITY.md).