hecks 1.4.0 → 1.5.1

data/lib/hecks/framework/bluebook/compliance.bluebook

@@ -0,0 +1,221 @@
+Hecks.bluebook "Compliance" do
+  vision "Something elsewhere already acted to contain a risk; this domain tracks the human review that decides what happens next."
+  supporting
+
+  # LIVES HERE (lib/hecks/framework/bluebook/), NOT under some
+  # domain's own examples/ directory, but that's a statement about
+  # SOURCE SHARING, not about how it's consumed — unlike Governance/
+  # Identity (which every real attaching domain only ever wants IN-
+  # PROCESS), Compliance genuinely supports BOTH modes from the same
+  # source: a domain that wants Review handled locally can
+  # `uses_framework "Compliance"` exactly like those two; a domain that
+  # wants it as a real, separately-deployed service — Banking's own
+  # choice, examples/compliance/ — reaches it through `across
+  # "Compliance"` on a policy instead, genuine cross-Lambda delivery.
+  # Nothing about this bluebook's own declarations changes between the
+  # two; only whether the CONSUMER merges it in or deploys it apart.
+  #
+  # examples/compliance/bluebook/compliance.bluebook is a SYMLINK back
+  # to this file (not the other way around, as it briefly was in
+  # 1.5.0) — a symlink pointing outside lib/ never survives `gem
+  # build` (RubyGems drops it, warning "not supported on all
+  # platforms"), so the real content has to live in the tree the
+  # gemspec actually packages.
+  #
+  # CONTAIN FIRST, INVESTIGATE SECOND — the real pattern this domain
+  # exists for. Banking's own "Compliance officer" role already acts
+  # directly and synchronously in three places (Customer.Suspend/
+  # Reinstate, Account.Freeze/Unfreeze, OnboardingCase.Clear/Decline) —
+  # this domain is deliberately NOT a fourth. By the time either
+  # aggregate below is opened, the containing action (a freeze, a box
+  # surrender) has ALREADY happened, unilaterally, elsewhere; this
+  # domain never asks permission, it is TOLD a fact and gives the same
+  # officer a place to record what they decided about it afterward.
+  #
+  # TWO AGGREGATES, NOT ONE — found live, designing this: Banking's own
+  # `ReviewOnFreeze`/`ReviewOnBoxSurrender` policies forward their
+  # triggering event's payload VERBATIM (neither declares a `with:`
+  # projection, which policies have gained since), and the two events
+  # carry genuinely different fields (`AccountFrozen`: `number`;
+  # `BoxSurrendered`: `branch_code` + `box_number`). One shared
+  # aggregate would need an artificial union of both shapes — and while
+  # `with:` could now reshape either side into it, that would be
+  # inventing a sameness the domain does not have. Two small aggregates,
+  # each identified by its own subject's own natural key, need neither.
+
+  aggregate "AccountFreezeReview" do
+    description "The compliance review a frozen account gets, opened the moment Banking::Account.Freeze already happened."
+
+    attribute :number, AccountNumber
+
+    identified_by :number
+
+    value_object "AccountNumber" do
+      attribute :value, String
+      invariant("an account number is present") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "open" do
+      transition "Clear"    => "cleared",   from: "open"
+      transition "Escalate" => "escalated", from: "open"
+    end
+
+    # SYSTEM-TRIGGERED, matching `AccountFrozen`'s own payload shape
+    # field for field — `Banking::Account.AccountFrozen`'s `number` is
+    # the ONLY field this ever receives (ReviewOnFreeze's own `on
+    # "Account.AccountFrozen"`), so this declares exactly that and
+    # nothing more; an unrecognized field would refuse at the JSON
+    # boundary rather than silently drop it.
+    command "Open" do
+      role "System"
+      goal "Register that a frozen account needs compliance review"
+
+      sets :number
+
+      emits AccountFreezeReviewOpened
+    end
+
+    command "Clear" do
+      role "Compliance officer"
+      goal "Confirm the freeze was warranted, or resolve it, with nothing further to escalate"
+
+      reference_to AccountFreezeReview
+
+      emits AccountFreezeReviewCleared
+    end
+
+    command "Escalate" do
+      role "Compliance officer"
+      goal "Send a genuine finding on to whatever handles it next — a formal filing, a longer hold, a referral"
+
+      reference_to AccountFreezeReview
+
+      emits AccountFreezeReviewEscalated
+    end
+  end
+
+  aggregate "BoxSurrenderReview" do
+    description "The compliance review a surrendered safe deposit box gets — audit/escheatment implications, not a fraud contain the way a freeze is, but the same after-the-fact review shape."
+
+    attribute :branch_code, BranchCode
+    attribute :box_number,  BoxNumber
+
+    identified_by :branch_code, :box_number
+
+    value_object "BranchCode" do
+      attribute :value, String
+      invariant("a branch is coded") { !value.to_s.empty? }
+    end
+
+    value_object "BoxNumber" do
+      attribute :value, Integer
+      invariant("a box is numbered from one") { value.positive? }
+    end
+
+    lifecycle :status, default: "open" do
+      transition "Clear"    => "cleared",   from: "open"
+      transition "Escalate" => "escalated", from: "open"
+    end
+
+    # Matches `BoxSurrendered`'s own payload field for field
+    # (`ReviewOnBoxSurrender`'s own `on SafeDepositBox::BoxSurrendered`) — the same
+    # discipline `AccountFreezeReview.Open` holds itself to, above.
+    command "Open" do
+      role "System"
+      goal "Register that a surrendered box needs compliance review"
+
+      sets :branch_code
+      sets :box_number
+
+      emits BoxSurrenderReviewOpened
+    end
+
+    command "Clear" do
+      role "Compliance officer"
+      goal "Confirm the surrender needs no further compliance action"
+
+      reference_to BoxSurrenderReview
+
+      emits BoxSurrenderReviewCleared
+    end
+
+    command "Escalate" do
+      role "Compliance officer"
+      goal "Send a genuine finding on to whatever handles it next"
+
+      reference_to BoxSurrenderReview
+
+      emits BoxSurrenderReviewEscalated
+    end
+  end
+
+  # A THIRD SHAPE, NOT A UNION OF THE OTHER TWO — the same restraint the
+  # header above holds Banking's own two events to. `Privacy::Marking`'s
+  # own `Marked` event carries `domain`/`attribute_path`, matching
+  # neither `AccountFrozen` (`number`) nor `BoxSurrendered`
+  # (`branch_code`/`box_number`), so this gets its own aggregate rather
+  # than an artificial union.
+  #
+  # REACHED VIA `translates`, NOT a `policy` this bluebook declares —
+  # which foreign domain's event a consumer conforms to is a wiring
+  # decision (see `HecksagonBuilder#translates`'s own header), so the
+  # reaction lives in whichever `.hecksagon` attaches both Privacy and
+  # Compliance, not here.
+  aggregate "PrivacyReview" do
+    description "The compliance review a newly marked sensitive field gets, opened the moment Privacy::Marking.Mark already happened."
+
+    attribute :domain,         Domain
+    attribute :attribute_path, AttributePath
+
+    identified_by :domain, :attribute_path
+
+    value_object "Domain" do
+      attribute :value, String
+      invariant("a review names the domain whose attribute was marked") { !value.to_s.empty? }
+    end
+
+    value_object "AttributePath" do
+      attribute :value, String
+      invariant("a review names the attribute that was marked") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "open" do
+      transition "Clear"    => "cleared",   from: "open"
+      transition "Escalate" => "escalated", from: "open"
+    end
+
+    # SYSTEM-TRIGGERED, matching only `Privacy::Marking`'s own identity
+    # fields — the `translates` block that reacts to `Marked` forwards
+    # just `domain`/`attribute_path`, the same restraint
+    # `AccountFreezeReview.Open`/`BoxSurrenderReview.Open` already hold
+    # themselves to above; `category`/`readable_by` stay on the
+    # marking itself, not duplicated here.
+    command "Open" do
+      role "System"
+      goal "Register that a newly marked sensitive field needs compliance review"
+
+      sets :domain
+      sets :attribute_path
+
+      emits PrivacyReviewOpened
+    end
+
+    command "Clear" do
+      role "Compliance officer"
+      goal "Confirm the marking was warranted, or resolve it, with nothing further to escalate"
+
+      reference_to PrivacyReview
+
+      emits PrivacyReviewCleared
+    end
+
+    command "Escalate" do
+      role "Compliance officer"
+      goal "Send a genuine finding on to whatever handles it next"
+
+      reference_to PrivacyReview
+
+      emits PrivacyReviewEscalated
+    end
+  end
+end

data/lib/hecks/framework/bluebook/privacy.bluebook

@@ -0,0 +1,155 @@
+Hecks.bluebook "Privacy" do
+  vision "Which fields of a domain's own aggregates are sensitive is a fact about that domain, declared apart from it — the domain itself never spells out that one of its own attributes is PII or PHI."
+  supporting
+
+  # A DOMAIN ATTACHING THIS NEVER MARKS ITSELF — `Mark`'s `role
+  # "Deployment"` matches every other wiring-time command in this
+  # codebase (`Hecksagon::UsesFramework`, `Tenancy::Tenant.Register`):
+  # something outside the domain's own bluebook decides a field is
+  # sensitive, the same way persistence binds are a wiring decision
+  # and not baked into an aggregate's own declaration.
+  aggregate "Marking" do
+    description "One attribute of one domain's own aggregate, flagged sensitive — and the role required to read it unredacted."
+
+    attribute :domain,         MarkingDomain
+    attribute :attribute_path, AttributePath
+    attribute :category,       Category
+    attribute :readable_by,    RoleName
+
+    identified_by :domain, :attribute_path
+
+    value_object "MarkingDomain" do
+      attribute :value, String
+      invariant("a marking names the domain it applies to") { !value.to_s.empty? }
+    end
+
+    # DOTTED, same convention Forms' own `Field#path` and a query's
+    # cross-object `where` clause already use — `"attendee.medications"`,
+    # not a bare leaf name, so a marking can reach into a nested value
+    # object rather than only a top-level attribute.
+    value_object "AttributePath" do
+      attribute :value, String
+      invariant("a marking names an attribute path") { !value.to_s.empty? }
+    end
+
+    # OPEN-ENDED ON PURPOSE — "pii", "phi", whatever else a consuming
+    # domain finds itself needing, none of it enumerated here. This
+    # bluebook is the mechanism (mark, gate, redact); it does not also
+    # own the vocabulary of sensitivity categories that exist in the
+    # world.
+    value_object "Category" do
+      attribute :value, String
+      invariant("a marking is categorized") { !value.to_s.empty? }
+    end
+
+    value_object "RoleName" do
+      attribute :value, String
+      invariant("reading a marked field unredacted requires a named role") { !value.to_s.empty? }
+    end
+
+    command "Mark" do
+      role "Deployment"
+      goal "Flag one attribute of a domain's own aggregate as sensitive, gating who may read it unredacted"
+
+      attribute :domain,         MarkingDomain
+      attribute :attribute_path, AttributePath
+      attribute :category,       Category
+      attribute :readable_by,    RoleName
+
+      emits Marked
+    end
+
+    command "Unmark" do
+      role "Deployment"
+      goal "Remove a sensitivity flag from an attribute"
+
+      reference_to Marking
+
+      emits Unmarked
+    end
+
+    query "ForDomain" do
+      description "Every marking declared for one domain, read by whatever gates or redacts that domain's own records."
+      attribute :domain, MarkingDomain
+      where(domain: :domain)
+    end
+  end
+
+  # **Cryptoshredding** — a right-to-erasure request satisfied without
+  # rewriting or deleting a single event. `key_reference` is an opaque
+  # handle a caller obtains from `Ports::KeyVault.issue` before
+  # dispatching `Issue`, the same "nothing is minted inside a bluebook"
+  # convention `Identity::Register`'s own `identity_id` and
+  # `Delivery::Record`'s own `message_id` already hold to (the
+  # expression sublanguage cannot call a port at all). The key material
+  # itself never appears here or on any emitted event — only the fact
+  # that a reference exists, and the fact that it was destroyed.
+  aggregate "SubjectKey" do
+    description "One data subject's own encryption key, from the moment it exists to the moment it is destroyed."
+
+    attribute :domain,        KeyDomain
+    attribute :subject_id,    SubjectId
+    attribute :key_reference, KeyReference
+
+    identified_by :domain, :subject_id
+
+    value_object "KeyDomain" do
+      attribute :value, String
+      invariant("a key names the domain its subject belongs to") { !value.to_s.empty? }
+    end
+
+    value_object "SubjectId" do
+      attribute :value, String
+      invariant("a key names the subject it was issued for") { !value.to_s.empty? }
+    end
+
+    value_object "KeyReference" do
+      attribute :value, String
+      invariant("a key carries the vault's own opaque reference to it") { !value.to_s.empty? }
+    end
+
+    # `Shred`'s own guard against running twice — the same mechanism
+    # `Compliance::PrivacyReview`'s `Clear`/`Escalate` already use rather
+    # than an optional timestamp plus a hand-written `given`.
+    lifecycle :status, default: "active" do
+      transition "Shred" => "shredded", from: "active"
+    end
+
+    command "Issue" do
+      role "System"
+      goal "Record that a subject's data is now encrypted under a fresh, dedicated key"
+
+      attribute :domain,        KeyDomain
+      attribute :subject_id,    SubjectId
+      attribute :key_reference, KeyReference
+
+      sets :domain
+      sets :subject_id
+      sets :key_reference
+
+      emits SubjectKeyIssued
+    end
+
+    # **Records destruction, never performs it** — the actual
+    # `Ports::KeyVault.destroy` call happens in driving-side code before
+    # this is ever dispatched, the same boundary `send_issue.rb` draws
+    # around `Delivery::Record` for an already-sent email. This
+    # command's own job is to make an already-irreversible fact
+    # durable, not to cause it.
+    command "Shred" do
+      role "Privacy officer"
+      goal "Mark this subject's key destroyed, so its ciphertext is recorded as permanently unrecoverable"
+
+      reference_to SubjectKey
+
+      emits SubjectKeyShredded
+    end
+
+    query "ForSubject" do
+      description "One subject's key record, checked before any attempt to decrypt their sensitive fields."
+      attribute :domain,     KeyDomain
+      attribute :subject_id, SubjectId
+      where(domain: :domain, subject_id: :subject_id)
+    end
+  end
+end

data/lib/hecks/framework/oidc.json

@@ -30,6 +30,21 @@
       "scope": "compliance:box_surrender_review.open",
       "verb": "Compliance::BoxSurrenderReview.Open",
       "role": "System"
+    },
+    {
+      "scope": "compliance:privacy_review.clear",
+      "verb": "Compliance::PrivacyReview.Clear",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:privacy_review.escalate",
+      "verb": "Compliance::PrivacyReview.Escalate",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:privacy_review.open",
+      "verb": "Compliance::PrivacyReview.Open",
+      "role": "System"
     }
   ],
   "roles": [

data/lib/hecks/framework.rb

@@ -6,6 +6,8 @@ module Hecks
   # domain-agnostic chapters no single example owns, shared by reference
   # rather than copied into every domain that wants one.
   #
+  # ## Where it lives
+  #
   # Under `lib/`, not a top-level sibling — a real consumer (embryonaut)
   # vendors only `lib/` (`bin/vendor-hecks`, and this gem's own
   # `hecks.gemspec`, both glob `lib/**/*`), so a `framework/`
@@ -19,6 +21,8 @@ module Hecks
   # non-Ruby data a module owns lives inside `lib/` with the code that
   # reads it, not beside it.
   #
+  # ## Derived, not hand-listed
+  #
   # Derived from the directory, not hand-listed a second time — the same
   # reasoning `Assembly::CONTRACTS` gives for reading the language's own
   # fields from a table instead of restating them: a member added here
@@ -27,19 +31,13 @@ module Hecks
   # stale in silence. `spec/corpus_spec.rb`'s own `FRAMEWORK_MEMBERS`
   # glob is the precedent this mirrors.
   #
+  # ## Naming
+  #
   # Named by file stem, capitalized — `governance.bluebook` holds
   # `Hecks.bluebook "Governance"`, the same one-to-one spelling every
   # other chapter in this codebase already keeps between its filename
   # and its declared name.
   module Framework
-    ROOT = File.expand_path("framework/bluebook", __dir__).freeze
-
-    def self.members
-      Dir.glob(File.join(ROOT, "*.bluebook")).to_h do |path|
-        [Naming.pascal(File.basename(path, ".bluebook")), path]
-      end
-    end
-
     # Loaded from its own real path, always — never a copy. A domain
     # booted through `Fuzzing::IsolatedBoot`'s tmp-directory copy still
     # reaches the same `framework/bluebook/governance.bluebook` this
@@ -64,28 +62,36 @@ module Hecks
     # everywhere else too. See `examples/banking/bluebook/banking.hecksagon`
     # for the pattern — a real `.hecksagon` file can hold more than one
     # `Hecks.hecksagon` call, one per domain it wires.
-    # Idempotent, per registry — `uses_framework` is now called more than
-    # once for the same member within a single boot (S8: a domain
-    # attaching Governance for its own role check, plus a framework
-    # sibling attaching it too, e.g. `banking.hecksagon`'s Identity
-    # block). `Kernel.load` always re-executes the file, unlike
-    # `require`, so a second call would re-run `Hecks.bluebook
-    # "Governance"` a second time — and the self-hosting meta-domain
-    # records every declaration as a real dispatched command against its
-    # own ledger, so a second `Declare` for the same aggregate is a real
-    # `AlreadyExists`, not a no-op. Skipped once the member's bluebook is
-    # already registered in this registry — the same chapter, not merely
-    # a same-named one from a stale prior boot.
+    ROOT = File.expand_path("framework/bluebook", __dir__).freeze
+
+    # Every framework member available to attach, by declared name.
+    #
+    # @return [Hash{String => String}] each member's capitalized bluebook name,
+    #   mapped to the absolute path of its `.bluebook` file
+    def self.members
+      Dir.glob(File.join(ROOT, "*.bluebook")).to_h do |path|
+        [Naming.pascal(File.basename(path, ".bluebook")), path]
+      end
+    end
+
     # Every member whose own bluebook declares `provides capability` —
     # read off the member's real IR (each loaded into a scratch registry,
     # never the caller's), not off its name. Used where a check needs to
     # say which member would satisfy it (`refuse_ungoverned_roles!`'s own
     # suggestion, `Fuzzing::TargetCapabilities`).
+    #
+    # @param capability [String, Symbol] the capability name to look for
+    # @return [Array<String>] the names of every framework member that provides it,
+    #   sorted
     def self.providers_of(capability)
       members.keys.select { |name| chapter(name).provides?(capability) }.sort
     end
 
     # One member's chapter, built in isolation.
+    #
+    # @param name [String, Symbol] the member's name, such as `"Governance"`
+    # @return [Bluebook::Chapter] the member's chapter, loaded into a scratch registry
+    # @raise [Runtime::WiringError] if no framework member has that name
     def self.chapter(name)
       path = members.fetch(name.to_s) do
         raise Runtime::WiringError,
@@ -107,6 +113,23 @@ module Hecks
       registry.bluebook(name.to_s)
     end
 
+    # Idempotent, per registry — `uses_framework` is now called more than
+    # once for the same member within a single boot (S8: a domain
+    # attaching Governance for its own role check, plus a framework
+    # sibling attaching it too, e.g. `banking.hecksagon`'s Identity
+    # block). `Kernel.load` always re-executes the file, unlike
+    # `require`, so a second call would re-run `Hecks.bluebook
+    # "Governance"` a second time — and the self-hosting meta-domain
+    # records every declaration as a real dispatched command against its
+    # own ledger, so a second `Declare` for the same aggregate is a real
+    # `AlreadyExists`, not a no-op. Skipped once the member's bluebook is
+    # already registered in this registry — the same chapter, not merely
+    # a same-named one from a stale prior boot.
+    #
+    # @param name [String, Symbol] the member's name, such as `"Governance"`
+    # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when
+    #   the current registry already held it
+    # @raise [Runtime::WiringError] if no framework member has that name
     def self.load!(name)
       path = members.fetch(name.to_s) do
         raise Runtime::WiringError,

data/lib/hecks/freezer.rb

@@ -8,7 +8,7 @@ module Hecks
   # Hash a field holds stays mutable, so a caller reaches straight
   # through and edits in place. Each fix looked complete and none was.
   #
-  # What should be frozen, and why it is not everything:
+  # ## What should be frozen, and why it is not everything
   #
   #   a value object has no identity to change over. `with` already
   #   answers a new one rather than mutating, so freezing it through is
@@ -33,6 +33,10 @@ module Hecks
     # Numbers, symbols, nil and booleans are already immediate or frozen;
     # a Value froze itself when it was built. What is left is the mutable
     # trio, and each has to be walked rather than topped.
+    #
+    # @param held [Object] any domain value
+    # @return [Object] `held`, recursively frozen if it is a Hash, Array, or
+    #   String; returned unchanged otherwise
     def deep(held)
       case held
       when Hash   then held.each_value { |inner| deep(inner) }.freeze
@@ -45,11 +49,20 @@ module Hecks
     # The question a gate asks, rather than the act. Answers false for the
     # first thing that is reachable and mutable, which is what makes a
     # failure message worth reading.
+    #
+    # @param held [Object] any domain value
+    # @return [Boolean] true if `held` and everything reachable from it is frozen
     def deeply_frozen?(held) = unfrozen_within(held).nil?
 
     # The path to the first mutable thing reachable from `held`, or nil.
     # A path rather than a boolean because "something in this event is
     # mutable" is not an actionable sentence.
+    #
+    # @param held [Object] any domain value
+    # @param path [Array<String>] the owner path accumulated by the recursive
+    #   walk so far; callers pass nothing and get the default
+    # @return [String, nil] the dotted path (Hash keys, Array indices, or
+    #   `"(the value itself)"`) to the first mutable value found, or nil if none
     def unfrozen_within(held, path = [])
       return (path.empty? ? "(the value itself)" : path.join(".")) unless immune?(held) || held.frozen?
 
@@ -62,6 +75,9 @@ module Hecks
     # Immediates are frozen in every Ruby that matters, but asking
     # `frozen?` of them and trusting the answer has bitten enough people
     # that it is worth being explicit.
+    #
+    # @param held [Object] any domain value
+    # @return [Boolean] true if `held` is nil, true, false, a Numeric, or a Symbol
     def immune?(held) = held.nil? || held == true || held == false || held.is_a?(Numeric) || held.is_a?(Symbol)
   end
 end