Compositions

Table of contents

Compositions
1. Format
2. Compositions in this library

This folder holds compositions — specifications that wire two or more atoms from atoms/ into a single coherent artifact.

A composition names at least one other pattern in its specification. Where atoms describe self-contained concepts (Personal Todo, Duplicate Prevention, Event Log), compositions describe how those concepts come together to do real work — Audit Trail composing Event Log with retention and tamper-evidence; Shared Todo composing Personal Todo with Permissions and Assignment; Reserve from Pool composing Reservation with Hold Window and Capacity.

Each file in this folder declares the atoms it composes and the logic that wires them together.

Vocabulary note. EOS literature and concept-catalog use applications for the same artifact. Grace Commons uses compositions because these files are structurally compositions — formal combinations of independently valid patterns — not deployable products. The underlying mechanism is identical; only the label differs.

Format

A composition spec at minimum names:

Composes — which atoms it brings together (linked).
Composition logic — how the atoms are wired: which actions in one trigger which in another, what policy parameters each atom is configured with, how cross-atom invariants are maintained.
Composition-level invariants — invariants that emerge from composition and don’t belong to any single constituent.
Examples — concrete scenarios showing the composition in action.
Edge cases — failure modes that arise from composition, including conflicts between constituent atoms.

See contributing.md for the full contribution shape.

Compositions in this library

Undo History — Personal Todo + Event Log. Every Personal Todo action is reversible; the user gets a familiar Cmd+Z experience without modifying either constituent atom.
Idempotent Reservation — Provisional Commitment + Duplicate Prevention. Every state-changing call is safely retryable: same idempotency token, same result, regardless of retry count. The composition formalizes what every production payment processor and reservation system implements today.
Audit Trail — Event Log + Actor Identity + Retention Window + Tamper Evidence. Every action of consequence is recorded, attributed to a verifiable actor, retained for its regulatory lifetime, and protected against after-the-fact rewriting. The canonical four-atom composition behind SOX (Sarbanes-Oxley Act) §404, HIPAA (Health Insurance Portability and Accountability Act) §164.312(b), PCI DSS (Payment Card Industry Data Security Standard) Requirement 10, 21 CFR (Code of Federal Regulations) Part 11, SEC (Securities and Exchange Commission) Rule 17a-4, and ISO/IEC 27001 §A.12.4.
Shared Todo — Personal Todo + Permissions + Assignment. A shared list where actors see and act on tasks according to explicit grants, and at most one actor is responsible for each task at any time. The emergent guarantee: every mutation is permission-gated, and no assignment is left dangling against a deleted task.
Notification Fanout — Subscription + Notification. When an event fires, every Active subscriber for the event scope receives a Notification record. The first composition in the library to produce a variable number of effects from a single trigger; fan-out is the directed invocation graph over the two messaging atoms, with per-recipient failure isolation and an ephemeral fanout_id correlation handle that becomes durable when Event Log is composed in.
Multi-Party Approval — Approval Step + Permissions + Assignment, layered on Audit Trail (Event Log + Actor Identity + Retention Window + Tamper Evidence). Wires N Approval Step instances under a named quorum rule (all-of-N, M-of-N, one-of-N) into a single enforced chain with deterministic quorum evaluation, in-tray binding per pending step, and full audit-substrate coverage. The first composition in the library to compose another composition (Audit Trail as substrate). Anchors SOX §404, FDA 21 CFR Part 211 / Part 11, ICH E6 GCP, ISO 9001 §8.5.1, ISO 13485 §7.3, SOC 2, and NIST SP 800-53 AC-5 / CM-3.
Defensible Retention — Legal Hold + Retention Window + Audit Trail (substrate). Makes record retention defensible: a record under any Active Legal Hold cannot be purged regardless of retention eligibility; every retention decision is attribution-stamped and tamper-evident via the Audit Trail substrate; the destruction of any record is provably authorized or provably blocked. Emergent invariants: hold-blocks-purge, retention coverage, hold audit coverage, retention-decision audit coverage, defensible destruction. Retires forthcoming-links in Legal Hold, Retention Window, and Audit Trail. Anchors FRCP (Federal Rules of Civil Procedure) Rule 37(e), SOX §802, HIPAA §164.530(j), SEC Rule 17a-4, and GDPR (General Data Protection Regulation) Article 17.
Attributed Permissions Admin — Permissions + Actor Identity. Every permission grant and every revocation is paired atomically with a verifiable attestation under the issuing actor’s credential — the records alone answer the regulator’s question “who granted this access, when, and under what credential?” Eight emergent invariants including attribution completeness, revocation attribution, attestation exclusivity, and orphan-log durability. The first composition in the library to pair two compliance-infrastructure atoms into a single administrative surface and to ship with a dynamic Alloy trace model verifying its load-bearing temporal claims. Anchors NIST SP 800-53 AC-3 + AU-2 + IA-2, SOX §404, HIPAA §164.312(a)(1) + §164.312(b), PCI DSS Req. 7 + Req. 10, 21 CFR Part 11 §11.10 + §11.50, GDPR Articles 25 and 30, and ISO/IEC 27001 §A.9.2.
Privileged Access Provisioning — Multi-Party Approval + Credential + Session + Capability + Audit Trail. A principal’s request for elevated access is gated by a mandatory multi-party approval chain; only after all required approvals commit does the composition allocate a time-limited, scoped Capability token. Session validity is checked before every access exercise; the cascade from Credential revocation through Session invalidation is the emergent property that closes the blast-radius of a compromised principal. Ships with a Python-based TLA+ behavioral model (841 states, all invariants held). Anchors NIST SP 800-53 AC-6 (least privilege), SOX §302 / §404, HIPAA §164.312(a)(1), PCI DSS Req. 7 + Req. 8.
Login — Credential + Session + Audit Trail. Every login call wires Credential.verify → Session.issue in the only safe order; every attempt (successful or failed) is recorded. The load-bearing emergent invariant is the cascade: revoke_sessions_for_credential walks the credential_to_sessions map and invalidates every Active session derived from a revoked credential in a single operation, with a reconcilable Audit Trail record. Six emergent invariants including credential-gates-issuance, cascade completeness (snapshot-scoped), and session-credential traceability. Anchors NIST SP 800-63B §7, NIST SP 800-53 AC-12, OWASP ASVS V3.1 + V3.3, HIPAA §164.312(d), PCI DSS Req. 8.2 + Req. 8.6.
Customer Onboarding (grounded on Final Critique 4) — Party Identity + Retention Window + Audit Trail (substrate). The full Customer Due Diligence arc for an external party: identity verified before regulated activity, the Verified state gated as the single precondition any activity system consumes through activity_permitted, ongoing monitoring driving adverse-trigger suspension and re-verification, and a post-closure retention floor that outlasts the relationship. Seven emergent invariants including verification-gates-activity, adverse-trigger-precedes-state-transition, open-trigger/suspension correspondence, and the post-closure retention floor. The gate enforces verified through this composition (it consults the composition’s own case index, so a party verified outside it fails with not-known), and every adverse trigger carries a records-alone trigger_id lifecycle. Anchors FATF Recommendations 10–12, BSA/AML 31 CFR §1020.220, FinCEN Beneficial Ownership 31 CFR §1010.230, EU AMLD5, and GDPR Article 6(1)(c).
Session-Gated Authorization — Session + Permissions. Every permission query is gated by a mandatory session validation before the Permissions atom is consulted. The load-bearing emergent invariant is principal binding: the principal_ref passed to Permissions.permitted is always the principal extracted from the validated session — never a caller-supplied value. A caller cannot interrogate permissions for an arbitrary principal by presenting an arbitrary session token. Expired, revoked, and unrecognized sessions block the query before Permissions is reached. Introduces no cross-atom state; the gate is a sequencing constraint at the composition boundary. Four emergent invariants. Anchors NIST SP 800-53 AC-3 + AC-12, NIST SP 800-63B §7, OWASP ASVS V3.3, HIPAA §164.312(a)(1) + §164.312(d), PCI DSS Req. 7 + Req. 8, ISO/IEC 27001 §A.9.4.1.
External Onboarding — Invitation + Credential + Party Identity + Audit Trail. The full arc of admitting an external entity: invitation issued by an authorized actor, accepted (binding the invitee’s identity reference), Party Identity enrolled in Unverified state, credential registered, every step attested in the Audit Trail. The load-bearing emergent invariant is invitation-gates-enrollment: no Party Identity is created unless an Invitation’s Accepted transition precedes it in the same onboarding call, and the Audit Trail completion record names the invitation token, accepting identity reference, party record, and credential in one tamper-evident entry. Five emergent invariants. Anchors GDPR Articles 6–7, HIPAA §164.312(a)(1) + §164.312(d), SOC 2 CC6.2, NIST SP 800-63A, SCIM 2.0 RFC 7644.
Chain of Custody — Provenance + Audit Trail (substrate). The full chain-of-custody surface: Provenance’s structural custody continuity made attributed (each custodian verified via credential through Actor Identity), tamper-evident (each entry sealed via Tamper Evidence), and retention-governed (each entry retained via Retention Window) — all reached transitively through the Audit Trail substrate. The load-bearing emergent guarantee is records-alone custody proof: verify_custody proves unbroken + attributed + tamper-evident + retention-governed custody from origin to disposition, which neither constituent provides alone. The cross-domain flagship: pharmaceutical chain of custody (FDA 21 CFR Part 211 / DEA 21 CFR Part 1304) and legal-evidence chain of custody (FRE 901(b)(9)) are the same structure — one composition serves both. First composition to compose the Provenance atom; ships with a TLA+ binding-bijection model + buggy twin. Retires the Chain-of-Custody forthcoming-link in Provenance. Anchors FDA 21 CFR Part 211, DEA 21 CFR Part 1304, FRE 901(b)(9), ISO 23081, W3C PROV, and SEC Rule 17a-4.
Execute Gated Workflow — State Machine + Approval Step + Permissions + Assignment + Audit Trail (substrate). A multi-actor gated workflow made auditably complete: a declared state machine governs the process, specific transitions are gated by human Approval Steps, Permissions governs who may advance the process, Assignment puts each open gate in the approver’s in-tray, and the Audit Trail substrate attributes, seals, and retention-governs every transition and gate decision. The load-bearing emergent property: guard evaluation re-converges here — State Machine deliberately gates on a caller-asserted guard_satisfied without evaluating; this composition evaluates approval-type guards by binding each guarded transition to an Approval Step and firing only when that step is genuinely Approved. First composition to compose the State Machine atom; ships with a TLA+ approval-gated-transition model + buggy twin. Retires the forthcoming-links in State Machine and Approval Step. Anchors FDA 21 CFR Part 11 + Part 211, SOX §404, ISO 9001 §8.5.1, BPMN 2.0, ICH E6 GCP.
Forensic Recovery — Soft Delete + Audit Trail (substrate). Soft deletion made forensically complete: every delete, restore, and purge is attributed (actor verified), tamper-evidently sealed, and retention-governed, and recover_history reconstructs the complete ordered delete/restore/purge history of any record — including prior epochs that Soft Delete’s current-state-only summary overwrites. The headline emergent invariant: no record reaches Purged without an auditable, sealed record naming who purged it, when, and under what stated reason. The purge-eligibility gate (Legal Hold / Retention Window blocking) is deliberately delegated to Defensible Retention, not absorbed here. Ships with a TLA+ binding-bijection model + buggy twin. Retires the Forensic Recovery forthcoming-links in Soft Delete. Anchors GDPR Article 17, HIPAA §164.310(d)(2) / §164.312(b), FRCP Rule 37(e), SOX §802, ISO 15489-1, NIST SP 800-88.
Propagate Consent Revocation Downstream — Consent + Permissions + Audit Trail (substrate) + a distinct consent-record Retention Window placement. Consent made operational: processing_permitted is the single gate every processing system consumes (consent-gates-processing), and withdraw_consent — the load-bearing emergent action — commits the Consent revoke and a consent.revoked propagation event enumerating the complete set of downstream processing scopes the consent governed, together or not at all (the revoke ⇔ complete-propagation-record binding bijection). Seven emergent invariants including consent-gates-processing, revocation-propagation completeness, downstream-registration recording, the consent-record retention floor, and inward/outward authorization separation (Permissions gates administration; the gate consults only Consent). Ships with a TLA+ binding-bijection model + buggy twin. Retires the Propagate Consent Revocation Downstream forthcoming-links in Consent and Customer Onboarding. Anchors GDPR Articles 6–7, 7(3), 17(1)(b), 30, CCPA/CPRA, HIPAA §164.508, the ePrivacy Directive, and ISO/IEC 29184.
Reserve from Pool — Capacity Constraint Enforcement + Provisional Commitment + Duplicate Prevention + Event Log + Actor Identity. The full arc of a reservation against a bounded pool: a capacity-gated provisional hold, an idempotent confirmation under concurrent demand, and a terminal resolution that returns the slot to the pool atomically, with every state change attributed and journaled. The load-bearing emergent guarantee is allocation coherence — the pool’s allocated total stays in exact lockstep with the set of live reservations (Held or Confirmed), so confirmed reservations never exceed capacity (no oversell) and a cancelled or expired reservation returns its slot exactly once (no leak, no double-release). The pool-arithmetic superset of Idempotent Reservation: it carries the idempotency surface and adds the Capacity Constraint binding (reservation_to_pool with a slot_released flag). Seven emergent invariants including allocation coherence, slot-returned-at-most-once, no-oversell, no-confirmation-of-a-lapsed-hold, and idempotent reservation actions. Ships with a TLA+ allocation-coherence model + buggy twin (a non-atomic cancel that leaks a slot). Retires the forthcoming-links in Capacity Constraint Enforcement and Provisional Commitment. Anchors ISO 9001 §8.5, PCI DSS Req. 10, IATA Resolution 830a / NDC, Joint Commission care-coordination, and GS1 inventory-reservation conventions.
Immutable Transaction Ledger with Selective Disclosure — Audit Trail (substrate, → Event Log + Actor Identity + Tamper Evidence + Retention Window) + Selective Disclosure. An append-only transaction ledger that is immutable, attributed, tamper-evident, and retained (the Audit Trail substrate) wired to accountable, independently verifiable partial disclosure (Selective Disclosure). Two load-bearing emergent guarantees: the disclosure-accountability binding bijection — every disclose_subset writes exactly one Selective Disclosure record and exactly one ledger.disclosed Audit Trail event, atomically, so the act of disclosing is itself an immutable, attributed ledger entry; and verifiable partial disclosure — any disclosed subset is independently provable authentic against the ledger seal while the undisclosed remainder stays undisclosed and uncompromised, stated as a behavioral capability obligation on the substrate’s tamper-evidence (mechanism-neutral — Merkle proofs, accumulators, and signed packages are typical realizations only, never mandated). Idempotent Reservation / Duplicate Prevention is named as optional at-most-once-append enrichment, not core. The first composition to compose the Selective Disclosure atom, and the cross-domain reference case: broker-dealer trade confirmations (SEC Rule 17a-4), healthcare accounting-of-disclosures (HIPAA §164.528), and clinical-trial submissions (21 CFR Part 11) are the same structure — one composition serves all three. Ships with a TLA+ disclosure-accountability binding-bijection model + buggy twin. Retires the Immutable Transaction Ledger forthcoming-links in Selective Disclosure and Provenance. Anchors SEC Rule 17a-4, HIPAA §164.528, 21 CFR Part 11, GDPR Article 15, and W3C Verifiable Credentials.
Resolve a Person’s Data Rights (grounded on Final Critique 5) — Selective Disclosure + Defensible Retention (substrate → Legal Hold + Retention Window + Audit Trail) + Consent (read-only oracle). When a data subject exercises access (GDPR Article 15) or erasure (Article 17), four claims collide on their records — access, erasure, legal hold/retention, and consent — and Resolve a Person’s Data Rights resolves the collision per record into one recorded, attributed disposition (access: included / withheld(...); erasure: erased / retained(legal-hold | retention-obligation | other-lawful-basis)). Two load-bearing emergent guarantees: no-silent-omission — every record in the subject’s enumerated universe carries exactly one disposition, none silently dropped; and the request ⇔ accountable-complete-fulfillment binding bijection — the complete disposition set, the response-disclosure, and the sealed dsar.*_fulfilled event commit together or not at all. The erasure path wraps Defensible Retention’s purge_record gate (hold-blocks-purge is the resolution of delete-vs-preserve), adding only the Article 17(1)(b) Consent-oracle branch; Consent is consulted read-only, never mutated. The first composition to compose Consent as a read-only authority oracle and Defensible Retention as a substrate, and the first authored under the capability-provenance rule. Ships with a TLA+ model checking the binding bijection and a no-silent-omission coverage totality, with two buggy twins (one per load-bearing invariant). Seeds a forthcoming Completeness Model atom (accountable enumeration of a record universe with per-record disposition — a shared Resolve a Person’s Data Rights/Customer Onboarding primitive Resolve a Person’s Data Rights exposes). Retires the Resolve a Person’s Data Rights forthcoming-links in Consent, Legal Hold, Selective Disclosure, and Provenance. Anchors GDPR Articles 15–17 (incl. 15(4), 17(1)(b), 17(3)), CCPA/CPRA, and HIPAA §164.524 / §164.526 / §164.528.
Authenticated Actor (grounded on Final Critique 4) — Credential (the authentication / gating surface) + Actor Identity (the attestation surface). Ties a principal’s login to their signature: it answers the three cross-atom questions neither freestanding atom owns, surfaced by the Attributed Permissions Admin demo’s identity-surface aliasing. The load-bearing emergent guarantee is the revocation cascade as forward closure — attest_as_actor is gated on the bound credential’s live Active status, read atomically with the attestation write (serialized on the gating (principal_ref, credential_type) credential record, the row Credential.revoke also locks), so a revoked login can produce no new attestations; crucially, attestations made before revocation stay valid (the cascade closes the surface going forward and never rewrites the past, because attestations are immutable point-in-time records — there is no active-attestation set to walk, so it is not a set-revocation). The other two emergent invariants are the structural conditions that make the cascade meaningful: secret-surface separation (the login verifier and the signing key are distinct surfaces — cross-routing foreclosed structurally; cryptographic distinctness an externally-clearable deployment obligation) and the principal_ref ⇔ actor_ref namespace bijection (register-time conflict guard + atomic strict-inverse maps + immutability, so every signature traces back to the authenticated principal). Login’s outbound-attestation counterpart (Login forward-closes the session set; Authenticated Actor forward-closes the attest surface) and the first composition to pair Credential with Actor Identity. Carries no Audit Trail substrate — the attestations are themselves the regulator-grade record of record. Ships with a TLA+ revocation-cascade model + TOCTOU buggy twin. Retires the Authenticated Actor pending markers in Credential and Actor Identity. Anchors NIST SP 800-63B §5.2, NIST SP 800-57 Part 1, PCI DSS Requirement 8.6, and FIPS 140-3.
Actor Suspension (grounded on Final Critique 4) — Actor Identity (the suspended actor’s composition-introduced Active/Suspended lifecycle) + Permissions (grant-revocation target) + Session (session-revocation target) + Audit Trail (substrate → Event Log + Actor Identity + Tamper Evidence + Retention Window) + optional Credential. The outbound multi-surface de-authorization surface: when an actor must be cut off — a departing employee, a compromised account, a contractor whose engagement ended — suspend_actor snapshots both authorization surfaces, revokes every active Permissions grant and every active Session (and, optionally, the Credential), transitions the actor Active→Suspended, and seals the complete revoked set into one tamper-evident actor.suspended Audit Trail event — all in one transaction. Three load-bearing emergent invariants: atomicity of multi-surface revocation — after suspend_actor succeeds, the actor holds zero active grants and zero active sessions, committed all-or-nothing with no partial state (a half-suspended actor is a worse security state than a clean failure — a deliberate inversion of Login’s best-effort cascade); audit completeness — the sealed event enumerates every revoked grant_id and session_token; and suspension cascade ordering — the Active→Suspended gate fires the cascade exactly once, a second suspend_actor is a no-op, and a benign already-terminal target is counted, not aborted. Login’s outbound-side counterpart (Login wires Credential.verify → Session.issue on the way in; Actor Suspension wires suspend → revoke every grant + every session on the way out). The unified_actor_namespace join precondition (satisfiable via Authenticated Actor) is a deployment-config capability whose actual coincidence is routed to an externally-clearable check. Ships with a TLA+ atomic-cascade model + non-atomic buggy twin. Anchors NIST SP 800-53 AC-2(3) + AC-6(5), SOX §404, HIPAA §164.308(a)(3)(ii)(C), PCI DSS Requirement 8.1.3, and ISO/IEC 27001 §A.9.2.6.
Capability-Backed Sharing (grounded on Final Critique 4) — Capability + Selective Disclosure + Audit Trail (substrate → Event Log + Actor Identity + Tamper Evidence + Retention Window). Reconciles bearer-token sharing (possession authorizes; the redeemer is never identified or recorded) with regulated disclosure audit (every disclosure accountable to a named, non-repudiable authorizing party). The load-bearing emergent property is the audit-subject asymmetry: every capability-backed disclosure names the allocator — attested under their own credential at allocation, carried immutably in the capability — and, by construction, names no redeemer, resting on Capability’s declared bearer-redemption (Invariant 3) and audit-asymmetry (Invariant 5) invariants surfaced through redeem’s allocator_ref return, never an ambient “the system records no redeemer.” Its second guarantee is the disclosure-accountability binding bijection (mirroring Immutable Transaction Ledger): each redemption-that-discloses commits the Selective Disclosure record, the sealed sharing.disclosed event, and the redemption-decrement together or not at all — a recoverable store write under the host transaction, closer to Immutable Transaction Ledger than to Resolve a Person’s Data Rights’ irreversible purge. The recorded recipient is the allocator-declared intended recipient, not the unknowable bearer. The library’s worked example of the object-capability (OCAP) model composed with regulated audit, and the first composition to compose Capability with Selective Disclosure. Ships with a TLA+ binding-bijection model + non-atomic buggy twin. Retires the forthcoming-reference in Capability. Anchors GDPR Article 32, HIPAA §164.514(d), and the object-capability (OCAP) model.
Preference-Aware Notification Fanout (grounded on Final Critique 9) — Subscription + Notification + Message Preference + Event Log. The preference-shaped superset of Notification Fanout: the same query-then-create loop with a shaping gate between the subscriber query and each create that reads the subscriber’s in-effect Message Preference record and renders exactly one journaled disposition per subscriber — created (shaped to channel and format), failed-with-cause, or suppressed-with-reason (suspended, no-record, quiet-window, frequency-cap, channel-opt-out). Emergent invariants include the disposition trichotomy, quiet-window safety (stored-preference and statutory arms — the TCPA teeth), per-commit frequency-cap safety conditional on the declared per-principal serialization capability, no-silent-disposition, and disposition replayability from journaled inputs under a versioned interpretation configuration; redispose is the journaled, gate-re-evaluated retry surface that forecloses bypass-shaped recovery. Ships with a TLA+ cap-TOCTOU model + overshoot buggy twin (the capacity-constraint precedent at the composition layer). Retires the forthcoming-links in Message Preference and Propagate Consent Revocation Downstream. Anchors TCPA 47 U.S.C. §227 / 47 CFR §64.1200(c)(1), CAN-SPAM §7704, GDPR Articles 7(3) and 21(2), CASL, and the ePrivacy Directive.

Atoms describe what; compositions describe what happens when atoms meet.