@plasius/economy 0.4.0 → 0.5.0

package/README.md

@@ -93,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",
@@ -120,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
@@ -306,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
@@ -329,9 +459,12 @@ 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).