hecks 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830e92d9660dc86cc7de1af49d85fd7ce5ab611e07341dd11f4633274b920fda
-  data.tar.gz: 1c70b3c2994fd520a604ebd8c8cc8a53e7531e3cb5ba1dd59c6fd751b9b9dd99
+  metadata.gz: 29c54ce86e36189a63578e970929e42c213d5812282c5cf5ca6e56820eb02938
+  data.tar.gz: 1d564ee387fb38c619fbdfef209bcc757570a492e70dac16f1d5fb80889c37e8
 SHA512:
-  metadata.gz: 3aeb0240903bed58fbd5684c23ee2069e9b3021aef07082d11e26ffa5052cebccf42d78e3aff243ba192183460056113e0510c7667306d1ed2cde3048ad118c0
-  data.tar.gz: e104c2252f0dbbb1ba5ea97a0f6f56f890cab76e12ff86f246605003738228b94062e317f16db1ebfb376753536d8309cedff86e00275781497232de67b17e1e
+  metadata.gz: 24794f4aaa4f5d2268f27e063b79a23b61c7dffe7b4a87b4b58f83db73188d57716fd734d695082bdf11d78d3101fc41640a45f76510fe7cc45fd9c3cd9347a8
+  data.tar.gz: 9ce51558bbe7c55e9dc451140a21d7c83b7073b8a692304579f15c76db3c56371cb90c7cac07b6c02e6eb64ddd73c27572e786ab941659d2a76e649de5d2a699

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -133,6 +133,111 @@ Hecks.bluebook "Deploy" do
     end
   end
 
+  # A sibling of `LambdaTarget`, not a shared shape with it — value objects
+  # are not shared across aggregates in this DSL (`Tenant`'s own
+  # `DomainName`/`Realm`/`Schema` below already make the same point), so
+  # this aggregate carries its own copies of `DomainName`/`Region`/
+  # `Database`/`Web` rather than reaching into `LambdaTarget`'s.
+  aggregate "FargateTarget" do
+    description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before bin/project_deploy generates anything from it."
+
+    identified_by :domain
+
+    attribute :domain,   DomainName
+    attribute :region,   Region
+    attribute :cpu,      Cpu
+    attribute :memory,   Memory
+    attribute :database, Database
+    attribute :web,      Web
+    attribute :port,     Port
+
+    value_object "DomainName" do
+      attribute :value, String
+      invariant("a domain is named") { !value.to_s.empty? }
+    end
+
+    value_object "Region" do
+      attribute :value, String
+      invariant("a region is named") { !value.to_s.empty? }
+    end
+
+    # A positive integer, nothing more — AWS's real cpu/memory
+    # combinations (256 cpu units needs 512-2048 MB of `memory`, say)
+    # are a pairing `ECS` itself enforces at deploy time; encoding that
+    # whole table here would duplicate AWS's own rules for no benefit
+    # this generator needs. This only catches a typo (zero, negative)
+    # before a single file is generated, the same floor `Memory`/`Port`
+    # below hold for their own ranges.
+    value_object "Cpu" do
+      attribute :value, Integer
+      invariant("cpu is positive") { value.positive? }
+    end
+
+    # Fargate's own valid range, not Lambda's 128-10240 MB —
+    # `LambdaTarget`'s own `Memory` value object (above) is scoped to
+    # that aggregate alone, so this is a distinct value object under the
+    # same name rather than a shared one. A plain sanity floor and
+    # ceiling, not AWS's own cpu-paired table (see `Cpu`'s own comment).
+    value_object "Memory" do
+      attribute :value, Integer
+      invariant("memory is positive") { value.positive? }
+      invariant("memory is at most 122880 MB") { value <= 122880 }
+    end
+
+    # Same shape and reasoning as `LambdaTarget`'s own `Database` —
+    # "Postgres"/"Aurora" provision this domain's own RDS instance;
+    # "Shared" borrows another already-deployed domain's instance,
+    # isolated by a native Postgres schema. See that value object's own
+    # comment for the full reasoning; it applies unchanged here.
+    value_object "Database" do
+      attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
+    end
+
+    # Same shape and reasoning as `LambdaTarget`'s own `Web` — "Rust"
+    # means the domain's own task also serves its public web UI
+    # in-process, over the port this aggregate's own `Port` attribute
+    # declares.
+    value_object "Web" do
+      attribute :value, String, one_of: ["None", "Rust"]
+    end
+
+    # The container port the task listens on and the target group
+    # routes to — a real TCP port, not an arbitrary integer.
+    value_object "Port" do
+      attribute :value, Integer
+      invariant("a port is at least 1") { value >= 1 }
+      invariant("a port is at most 65535") { value <= 65535 }
+    end
+
+    # All seven required, for the identical reason `LambdaTarget.Declare`
+    # requires all of its own attributes — see that command's own
+    # comment on `normalize_args`/`coerce_declared_arguments`. This
+    # validates a fully-resolved target, after `bin/project_deploy`'s own
+    # defaulting (`cpu`/`memory`/`port` each fall back to a Ruby-side
+    # default before this ever dispatches), not instead of it.
+    command "Declare" do
+      goal "Validate one domain's AwsFargate deploy target before anything is generated from it"
+
+      attribute :domain,   DomainName
+      attribute :region,   Region
+      attribute :cpu,      Cpu
+      attribute :memory,   Memory
+      attribute :database, Database
+      attribute :web,      Web
+      attribute :port,     Port
+
+      sets :domain
+      sets :region
+      sets :cpu
+      sets :memory
+      sets :database
+      sets :web
+      sets :port
+
+      emits "FargateTargetDeclared"
+    end
+  end
+
   # `bin/project_tenant`'S OWN VALIDATED SHAPE — same split LambdaTarget
   # draws with `bin/project_deploy`: this aggregate validates, that
   # script GENERATES/ACTS (writes `environments/<slug>.world`, ensures

data/lib/hecks/deploy/oidc.json

@@ -1,6 +1,11 @@
 {
   "audience": "Deploy",
   "scopes": [
+    {
+      "scope": "deploy:fargate_target.declare",
+      "verb": "Deploy::FargateTarget.Declare",
+      "role": null
+    },
     {
       "scope": "deploy:lambda_target.declare",
       "verb": "Deploy::LambdaTarget.Declare",

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/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