hecks 1.5.0 → 2.0.0

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/identity.bluebook

@@ -9,6 +9,17 @@ Hecks.bluebook "Identity" do
   # identity provider is.
   generic
 
+  # WHAT THIS CHAPTER ANSWERS FOR EVERY DOMAIN THAT ATTACHES IT. Same
+  # declared-not-named shape Governance's own `provides "authorization"`
+  # already is. rust/host does not build this chapter's payloads — any
+  # field mapping lives on the consuming hecksagon's `translates` ACL
+  # (any field; this chapter does not list which). Link's reference is
+  # `identity`, not `identity_id` and not `to:`.
+  provides "identity",
+           register: "Identity.Register",
+           link:     "ExternalIdentifier.Link",
+           resolve:  "ExternalIdentifier.ResolvedBy"
+
   aggregate "Identity" do
     description "A stable organizational identity, independent of how it was authenticated."
 

data/lib/hecks/fuzzing/concurrent_dispatch.rb

@@ -435,11 +435,18 @@ module Hecks
       # @param schema [String] the PostgresEra schema name to write into the `.world` file
       # @return [void]
       def write_postgres_era_world!(copy, database:, schema:)
+        # Same merge IsolatedBoot.rebind_to_postgres_era! now does — one
+        # world file per directory, every hecksagon name in that directory.
+        worlds_by_dir = Hash.new { |h, k| h[k] = [] }
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
-          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq
+          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+          worlds_by_dir[File.dirname(hecksagon_path)].concat(names)
+        end
+        worlds_by_dir.each do |dir, names|
+          names = names.uniq
           next if names.empty?
 
-          world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres_era.world")
+          world_path = File.join(dir, "hecks_fuzz_postgres_era.world")
           File.write(world_path, names.map do |name|
             <<~WORLD
               Hecks.world "#{name}" do

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -404,11 +404,21 @@ module Hecks
         # database it is about to throw away; the one-line warning
         # PostgresEra prints per boot under the opt-in is the honest
         # price. Inert on a machine whose ambient user is ordinary.
+        # One world file per directory, every hecksagon name in that
+        # directory — not one write per *.hecksagon file. context_map.hecksagon
+        # sits beside the domain file; a second File.write to the same
+        # hecks_fuzz_postgres_era.world would drop the first file's names
+        # (found live: ConcurrentDispatchUnboundFixture + Governance).
+        worlds_by_dir = Hash.new { |h, k| h[k] = [] }
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
-          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq
+          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+          worlds_by_dir[File.dirname(hecksagon_path)].concat(names)
+        end
+        worlds_by_dir.each do |dir, names|
+          names = names.uniq
           next if names.empty?
 
-          world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres_era.world")
+          world_path = File.join(dir, "hecks_fuzz_postgres_era.world")
           File.write(world_path, names.map do |name|
             <<~WORLD
               Hecks.world "#{name}" do

data/lib/hecks/language/bluebook/bluebook.bluebook

@@ -181,7 +181,11 @@ Hecks.bluebook "Bluebook", version: "1" do
 
     # ONE ROW OF ONE CAPABILITY — `provides "authorization", assignments:
     # ..., grant: ..., transitions: ...` offers three, one per key, in the
-    # order they were written.
+    # order they were written. Membership (`admit`/`grant`/`people`) and
+    # identity (`register`/`link`/`resolve`) use the same word with their
+    # own named keys; the argument table admits every key any capability
+    # declares, and `Capabilities::CONTRACTS` holds which keys a given
+    # capability must name.
     command "Provide" do
       role "Language"
       goal "Declare one verb this chapter answers a capability with"
@@ -287,6 +291,11 @@ Hecks.bluebook "Bluebook", version: "1" do
       member keyword: "provides",        context: "Bluebook", at: "",  named: "assignments", kind: "text", required: "false", fills: "provides"
       member keyword: "provides",        context: "Bluebook", at: "",  named: "grant",       kind: "text", required: "false", fills: "provides"
       member keyword: "provides",        context: "Bluebook", at: "",  named: "transitions", kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "admit",       kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "people",      kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "register",    kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "link",        kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "resolve",     kind: "text", required: "false", fills: "provides"
       member keyword: "aggregate",       context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"
       member keyword: "read_model", context: "Bluebook", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "policy",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"

data/lib/hecks/language/hecksagon/hecksagon.bluebook

@@ -110,6 +110,12 @@ Hecks.bluebook "Hecksagon" do
       # the same shape `subscribe`/`uses_framework` already are, reached
       # by Ruby's own method lookup before `word_gate` ever runs.
       member word: "translates",      context: "Hecksagon",     body: "keywords", inner: "Policy",        opens: "Policy",        fills: ""
+      # A CONSUMER-OWNED bounded context — framework/vendored packages
+      # get this mark automatically from uses_framework /
+      # uses_embryonaut_bluebook and never write it in their own files.
+      # No `calls:` — `HecksagonBuilder#bounded` is an ordinary method,
+      # same shape `subscribe` already is.
+      member word: "bounded",         context: "Hecksagon", body: "none", inner: "", opens: "", fills: ""
 
     end
 

data/lib/hecks/ports/key_vault.rb

@@ -34,6 +34,33 @@ module Hecks
       #   already destroyed, or was never issued
       def destroy(registry, key_reference:) = adapter(registry).destroy(key_reference: key_reference)
 
+      # Erases one subject: destroys their key in the vault, then durably records that it
+      # happened — in that fixed order, so a caller cannot dispatch `Shred` before the key
+      # is actually gone the way calling {#destroy} and `dispatch_flat` separately would
+      # allow. `Privacy::SubjectKey.Shred`'s own lifecycle guard (`from: "active"`) still
+      # refuses a raw double-dispatch; this is what closes the gap one level up, where the
+      # danger isn't a duplicate `Shred` but `Shred` running *before* {#destroy} does.
+      #
+      # Idempotent: a subject with no live `SubjectKey` record, or one already shredded,
+      # is left alone and answered `false` — a retried erasure request never re-destroys
+      # an already-gone key or double-dispatches `Shred`.
+      #
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   dispatcher both the lookup query and the `Shred` dispatch run through
+      # @param domain [String] the subject's own domain FQN, e.g. `"Lifeadelics::Registration"`
+      # @param subject_id [String] the data subject to erase
+      # @return [Boolean] true when a live key was found and shredded by this call; false
+      #   when no `SubjectKey` record exists for this subject, or it was already shredded
+      def shred!(dispatcher, domain:, subject_id:) # rubocop:disable Naming/PredicateMethod
+        record = dispatcher.query("Privacy::SubjectKey.ForSubject", domain: domain, subject_id: subject_id).first
+        return false unless record
+        return false if record[:status].to_s == "shredded"
+
+        destroy(dispatcher.registry, key_reference: record[:key_reference].value)
+        dispatcher.dispatch_flat("Privacy::SubjectKey.Shred", domain: { value: domain }, subject_id: { value: subject_id })
+        true
+      end
+
       # Finds the single adapter bound to this port, refusing an ambiguous wiring.
       #
       # @param registry [Runtime::Registry] the booted registry to search

data/lib/hecks/ports/persistence/plugins/era/lineage.rb

@@ -155,8 +155,13 @@ module Hecks
           @drops.each { |name| apply_drop(state, name) }
           # Last, and only where nothing already answered — a backfill
           # fills the gap a rename/move/convert left untouched, never
-          # overwrites a value that already made it across.
-          @backfills.each { |backfill| state[backfill.name] = backfill.default unless state.key?(backfill.name) }
+          # overwrites a value that already made it across. Dotted-path
+          # aware, same as `apply_drop` above (`apply_backfill`'s own
+          # header) — a bare name was the only shape this ever needed
+          # until a value object gained new required members with zero
+          # source data of their own (found live: lifeadelics' Attendee
+          # redesign, commit 4326dcd).
+          @backfills.each { |backfill| apply_backfill(state, backfill) }
           Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)
         end
 
@@ -312,6 +317,31 @@ module Hecks
           end
         end
 
+        # Applies one backfill, dotted-path aware — `apply_drop`'s own
+        # mirror on the addition side. A bare name sets a plain top-level
+        # key, unchanged from before; a dotted name (`"attendee.
+        # first_name"`) reaches into an existing value-object member the
+        # same way `apply_drop`/`hecks_tr_insert` (rule_compiler.rb's own
+        # SQL-compiled twin, kept in step with this) already do — creating
+        # the container Hash if an old record somehow lacks it entirely,
+        # never overwriting a value already there at either level.
+        #
+        # @param state [Hash] the entry's own state Hash, mutated in place
+        # @param backfill [Bluebook::TranslationBackfill] the backfill rule to apply
+        # @return [void]
+        def apply_backfill(state, backfill)
+          name = backfill.name.to_s
+          top, member = name.split(".", 2)
+          top = top.to_sym
+
+          if member
+            nested = (state[top] ||= {})
+            nested[member] = backfill.default unless nested.key?(member)
+          else
+            state[top] = backfill.default unless state.key?(top)
+          end
+        end
+
         # A dotted path's first segment is a top-level (symbol) key; a
         # second segment reaches into a value-object member by its string
         # key — the spelling a raw stored row carries. Translation runs on

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -54,6 +54,21 @@ module Hecks
         declared.computes.each do |compute|
           expression = compile_compute(expression, compute)
         end
+        # Backfills last, same order `Lineage#translate` already applies
+        # in-process (that method's own comment: "only where nothing
+        # already answered") — now compiled here too, closing the gap
+        # this rule kind otherwise leaves: `rust/host`'s boot-time mint
+        # audit reads this exact compiled expression, never
+        # `Lineage#translate`, so it cannot see a backfilled value unless
+        # backfills compile to SQL like every other rule kind here. A
+        # real, live gap for any new required value-object member with no
+        # source data at all — `compute` cannot fill it either, since its
+        # own guard requires a real, already-present field to consume
+        # (found live: lifeadelics' Attendee redesign, commit 4326dcd,
+        # needed exactly this and had nothing that worked).
+        declared.backfills.each do |backfill|
+          expression = compile_backfill(expression, backfill)
+        end
         expression
       end
 
@@ -124,6 +139,32 @@ module Hecks
           "LATERAL (SELECT (__s ->> #{text_literal(from)}) AS #{quote(from)}) __fields)"
       end
 
+      # A newly added, required attribute with no source at all — the
+      # addition-side sibling of `compile_compute`'s own header, but with
+      # no field to consume: `hecks_tr_extract`'s own `.present` flag
+      # (already installed for `hecks_tr_drop`/`hecks_tr_move`/
+      # `hecks_tr_convert` — no new database function needed) answers
+      # "is this path — bare or a dotted value-object member alike —
+      # already there," and `hecks_tr_insert` (already merge-safe: it
+      # creates a missing intermediate container without disturbing any
+      # sibling member already in it) fills it only when it is not, the
+      # exact "never overwrites a value already there" rule `Lineage#
+      # translate`'s own in-process backfill already holds itself to.
+      #
+      # @param expression [String] the SQL expression built so far by `compile_rules`, read as
+      #   `__s` inside this backfill's own check
+      # @param backfill [Bluebook::TranslationBackfill] the declared backfill rule
+      # @return [String] `expression` wrapped so the backfill's default lands at its declared
+      #   path when nothing is there yet, unchanged otherwise
+      def compile_backfill(expression, backfill)
+        name = backfill.name.to_s
+        default_json = JSON.generate(backfill.default)
+        "(SELECT CASE WHEN (hecks_tr_extract(__s, #{path_literal(name)})).present THEN __s " \
+          "ELSE hecks_tr_insert(__s, #{path_literal(name)}, #{text_literal(default_json)}::jsonb, " \
+          "#{text_literal("backfill #{name}")}) END " \
+          "FROM (SELECT (#{expression}) AS __s) __outer)"
+      end
+
       # `PG::Connection.quote_ident` needs the `pg` gem loaded, not
       # connected — required here, lazily, the same "a domain that
       # never wires PostgresEra should never need the gem" reasoning