hecks 2.8.0 → 3.0.0

data/lib/hecks/framework/bluebook/identity.bluebook

@@ -1,20 +1,13 @@
 Hecks.bluebook "Identity" do
   vision "Authentication proves an identifier; the organization decides what that identity means."
-  # S13, ADR 0025 (coverage standard) — GENERIC, not `supporting`: an
-  # OIDC-shaped external identifier is the textbook generic subdomain
-  # (Vernon's own example of one), off-the-shelf and buyable —
-  # `Governance` (role/scope RBAC beside it) stays `supporting`
-  # instead, since ITS OWN model is bespoke to this codebase's actor/
-  # role/scope shape, not a drop-in replaceable concept the way an
-  # identity provider is.
+  # Generic, not `supporting`: an OIDC-shaped external identifier is the textbook generic
+  # subdomain. Governance's role/scope RBAC is bespoke to this codebase, so it stays
+  # `supporting` (ADR 0025).
   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:`.
+  # What this chapter answers for every attaching domain, declared rather than named as
+  # Governance's `provides "authorization"` is. Field mapping lives on the consuming
+  # hecksagon's `translates` ACL; Link's reference is `identity`, not `identity_id` or `to:`.
   provides "identity",
            register: "Identity.Register",
            link:     "ExternalIdentifier.Link",
@@ -32,10 +25,8 @@ Hecks.bluebook "Identity" do
       invariant("an identity id is present") { !value.to_s.empty? }
     end
 
-    # No natural key exists for "a newly recognized identity" — the
-    # caller mints identity_id via Ports::IdentityGeneration.uuid
-    # before dispatching (see spec/ports/identity_generation_spec.rb),
-    # the same pattern proven there against Pizzas.
+    # No natural key exists for a new identity: the caller mints `identity_id` via
+    # `Ports::IdentityGeneration.uuid` before dispatching.
     command "Register" do
       role "Identity registrar"
       goal "Recognize an identity"
@@ -70,9 +61,7 @@ Hecks.bluebook "Identity" do
       invariant("a subject is present") { !value.to_s.empty? }
     end
 
-    # `key` is deliberately not derived here — a caller-side concern
-    # (e.g. SHA256 of issuer+subject), same as any other identity
-    # field this domain never mints itself.
+    # `key` is not derived here; the caller derives it (e.g. SHA256 of issuer+subject).
     command "Link" do
       role "Identity registrar"
       goal "Associate an external authenticated subject with an identity"
@@ -85,12 +74,8 @@ Hecks.bluebook "Identity" do
       emits ExternalIdentifierLinked
     end
 
-    # THE OIDC-SHAPED LOOKUP — a token hands over `(issuer, subject)`,
-    # never the `key` this aggregate is actually identified by (`key`
-    # is a caller-side derivation, deliberately not reproduced here —
-    # see `Link`'s own comment). `identity` rides the row already,
-    # from `reference_to Identity` above, so a caller reads it straight
-    # off the match rather than needing a second query.
+    # The OIDC-shaped lookup: a token hands over `(issuer, subject)`, never `key`. `identity`
+    # rides the row from `reference_to Identity`, so no second query is needed.
     query "ResolvedBy" do
       description "The external identifier linked to this exact (issuer, subject) pair, if any."
       attribute :issuer,  Issuer

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

@@ -2,12 +2,7 @@ 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.
+  # A domain never marks itself: `Mark` is a wiring-time command (role "Deployment").
   aggregate "Marking" do
     description "One attribute of one domain's own aggregate, flagged sensitive — and the role required to read it unredacted."
 
@@ -23,20 +18,13 @@ Hecks.bluebook "Privacy" do
       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.
+    # Dotted, e.g. "attendee.medications", so a marking can reach a nested value object.
     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.
+    # Open-ended on purpose ("pii", "phi", ...): this bluebook does not own the vocabulary.
     value_object "Category" do
       attribute :value, String
       invariant("a marking is categorized") { !value.to_s.empty? }
@@ -75,15 +63,8 @@ Hecks.bluebook "Privacy" do
     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.
+  # Cryptoshredding: erasure without rewriting events. `key_reference` is an opaque handle
+  # from `Ports::KeyVault.issue`, obtained before `Issue`; key material never appears here.
   aggregate "SubjectKey" do
     description "One data subject's own encryption key, from the moment it exists to the moment it is destroyed."
 
@@ -108,9 +89,7 @@ Hecks.bluebook "Privacy" do
       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`.
+    # Guards `Shred` against running twice.
     lifecycle :status, default: "active" do
       transition "Shred" => "shredded", from: "active"
     end
@@ -130,12 +109,8 @@ Hecks.bluebook "Privacy" do
       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.
+    # Records the destruction, never performs it: `Ports::KeyVault.destroy` runs in
+    # driving-side code before this is dispatched.
     command "Shred" do
       role "Privacy officer"
       goal "Mark this subject's key destroyed, so its ciphertext is recorded as permanently unrecoverable"

data/lib/hecks/framework.rb

@@ -1,67 +1,12 @@
 require_relative "runtime/registry"
 
 module Hecks
-  # **The registry of framework bluebooks** — Governance, Identity, and
-  # whatever lands beside them in `lib/hecks/framework/bluebook/`:
-  # 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/`
-  # sitting beside `lib/` rather than inside it packaged and vendored
-  # cleanly but left `uses_framework` finding nothing at runtime —
-  # `Framework::ROOT` pointed at a directory that simply never shipped.
-  # Nothing in this repo's own suite caught it, since every spec here
-  # reads the working tree directly; only vendoring into a real consumer
-  # did. Same reasoning `lib/hecks/language/bluebook/` already
-  # settled for the self-hosted grammar's own `.bluebook` files —
-  # 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
-  # and forgotten in a list would be a member `uses_framework` could
-  # never find, and a hand-kept list is exactly the shape that goes
-  # 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.
+  # Registry of framework bluebooks (Governance, Identity, ...) in `lib/hecks/framework/bluebook/`.
+  # Members are derived from the directory and named by capitalized file stem.
   module Framework
-    # 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
-    # constant points at, because `uses_framework` runs `Kernel.load`
-    # against `ROOT`, not against anything inside the copied domain
-    # directory — there is nothing here for a relocated copy to break,
-    # the way a symlink carried along with the copy would.
-    #
-    # Only the bluebook — a framework member's own `.hecksagon`, if it
-    # has one, is not auto-loaded. Persistence is a wiring decision, the
-    # same as any other aggregate's, and belongs to whoever is doing the
-    # deploying, not to a default baked into the framework member
-    # itself: a consuming app needs `Governance::RoleAssignment` durable
-    # (Postgres, say), and a framework member hard-coding Memory for its
-    # own specs would silently make that decision for every app that
-    # attaches it. The consuming app declares its own, separate
-    # `Hecks.hecksagon "Governance" do ... end` block for that — not
-    # binds folded into its own hecksagon, which would build but never
-    # resolve: `Ports::Persistence::BindingPolicy.resolve` looks up
-    # `registry.hecksagon` by the aggregate's own domain name, not the
-    # domain doing the binding, the one invariant this runtime holds
-    # 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.
+    # Directory the members load from, never a copy, so relocated domain copies still resolve.
+    # Lives under `lib/` because consumers vendor only `lib/`.
+    # Only the bluebook loads: persistence is the consumer's own `Hecks.hecksagon` block.
     ROOT = File.expand_path("framework/bluebook", __dir__).freeze
 
     # Every framework member available to attach, by declared name.
@@ -74,11 +19,7 @@ module Hecks
       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`).
+    # Every member whose bluebook declares `provides capability`, read from its IR, not its name.
     #
     # @param capability [String, Symbol] the capability name to look for
     # @return [Array<String>] the names of every framework member that provides it,
@@ -101,9 +42,7 @@ module Hecks
       lib = File.expand_path("..", __dir__)
       registry = Runtime::Registry.new
       Hecks.with_registry(registry) do
-        # The same four a chapter needs to build at all (a predicate's
-        # source is recovered through the extraction port) — the seed
-        # `Grammar#grammar_chapters` and `bin/model_check` use.
+        # A chapter needs these four to build (predicate source is recovered via extraction).
         Kernel.load(File.join(lib, "hecks/ports/persistence.port"))
         Kernel.load(File.join(lib, "hecks/ports/extraction.port"))
         Kernel.load(File.join(lib, "hecks/adapters/driven/memory.adapter"))
@@ -113,18 +52,10 @@ 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.
+    # Loads a member's bluebook unless this registry already holds it.
+    #
+    # `Kernel.load` re-executes the file, and a second `Declare` of the same aggregate is
+    # `AlreadyExists`, so repeated `uses_framework` calls in one boot must skip.
     #
     # @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

data/lib/hecks/freezer.rb

@@ -1,38 +1,10 @@
 module Hecks
-  # The one place that knows how to freeze a domain value.
-  #
-  # Freezing here has been fixed four times in four places, each time by
-  # topping the container and leaving the contents: list attributes, the
-  # event log, query rows, and value objects. `.freeze` on a Hash stops a
-  # key being added or removed and nothing else — the String, Array or
-  # 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
-  #
-  #   a value object has no identity to change over. `with` already
-  #   answers a new one rather than mutating, so freezing it through is
-  #   what it always claimed to be.
-  #
-  #   an emitted event is a record of something that happened. A mutable
-  #   audit trail is not one.
-  #
-  #   a query row is an answer, not a handle — mutating one edits nobody's
-  #   state and silently disagrees with the store.
-  #
-  #   an instance's state is not frozen, deliberately: the interpreter
-  #   builds it up across a dispatch, and a command's whole job is to
-  #   change it. Its values are frozen; the holder is not.
-  #
-  #   a command's arguments are not frozen either. They arrive from
-  #   outside, are normalised and coerced on the way in, and the coerced
-  #   result is what becomes a frozen value.
+  # The one place that freezes a domain value all the way down, not just its container.
+  # Instance state and command arguments are deliberately left unfrozen; values and events are.
   module Freezer
     module_function
 
-    # 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.
+    # Freezes a Hash, Array or String and everything inside it.
     #
     # @param held [Object] any domain value
     # @return [Object] `held`, recursively frozen if it is a Hash, Array, or
@@ -46,17 +18,13 @@ module Hecks
       end
     end
 
-    # 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.
+    # True when `held` and everything reachable from it is frozen.
     #
     # @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
@@ -72,9 +40,7 @@ module Hecks
       end
     end
 
-    # 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.
+    # Explicit rather than trusting `frozen?` on immediates.
     #
     # @param held [Object] any domain value
     # @return [Boolean] true if `held` is nil, true, false, a Numeric, or a Symbol