hecks 0.2.0 → 1.0.0

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

@@ -0,0 +1,90 @@
+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
+
+  aggregate "Identity" do
+    description "A stable organizational identity, independent of how it was authenticated."
+
+    attribute :identity_id, IdentityId
+
+    identified_by :identity_id
+
+    value_object "IdentityId" do
+      attribute :value, String
+      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.
+    command "Register" do
+      role "Identity registrar"
+      goal "Recognize an identity"
+
+      attribute :identity_id, IdentityId
+      emits IdentityRegistered
+    end
+  end
+
+  aggregate "ExternalIdentifier" do
+    description "One authenticated (issuer, subject) pair, linked to the identity it proves control of."
+
+    reference_to Identity
+    attribute :key,     ExternalIdentifierKey
+    attribute :issuer,  Issuer
+    attribute :subject, Subject
+
+    identified_by :key
+
+    value_object "ExternalIdentifierKey" do
+      attribute :value, String
+      invariant("a key is present") { !value.to_s.empty? }
+    end
+
+    value_object "Issuer" do
+      attribute :value, String
+      invariant("an issuer is present") { !value.to_s.empty? }
+    end
+
+    value_object "Subject" do
+      attribute :value, String
+      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.
+    command "Link" do
+      role "Identity registrar"
+      goal "Associate an external authenticated subject with an identity"
+
+      reference_to Identity
+      attribute :key,     ExternalIdentifierKey
+      attribute :issuer,  Issuer
+      attribute :subject, Subject
+
+      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.
+    query "ResolvedBy" do
+      description "The external identifier linked to this exact (issuer, subject) pair, if any."
+      attribute :issuer,  Issuer
+      attribute :subject, Subject
+      where(issuer: :issuer, subject: :subject)
+    end
+  end
+end

data/lib/hecks/framework/oidc.json

@@ -0,0 +1,39 @@
+{
+  "audience": "Compliance",
+  "scopes": [
+    {
+      "scope": "compliance:account_freeze_review.clear",
+      "verb": "Compliance::AccountFreezeReview.Clear",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:account_freeze_review.escalate",
+      "verb": "Compliance::AccountFreezeReview.Escalate",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:account_freeze_review.open",
+      "verb": "Compliance::AccountFreezeReview.Open",
+      "role": "System"
+    },
+    {
+      "scope": "compliance:box_surrender_review.clear",
+      "verb": "Compliance::BoxSurrenderReview.Clear",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:box_surrender_review.escalate",
+      "verb": "Compliance::BoxSurrenderReview.Escalate",
+      "role": "Compliance officer"
+    },
+    {
+      "scope": "compliance:box_surrender_review.open",
+      "verb": "Compliance::BoxSurrenderReview.Open",
+      "role": "System"
+    }
+  ],
+  "roles": [
+    "Compliance officer",
+    "System"
+  ]
+}

data/lib/hecks/framework.rb

@@ -0,0 +1,90 @@
+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.
+  #
+  # 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 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.
+  #
+  # 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
+    # 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.
+    # 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.
+    def self.load!(name)
+      path = members.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no framework member named #{name.inspect} — known: #{members.keys.sort.join(', ')}"
+      end
+
+      return if Hecks.current_registry.bluebook(name.to_s)
+
+      Kernel.load(path)
+    end
+  end
+end

data/lib/hecks/freezer.rb

@@ -0,0 +1,67 @@
+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.
+  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.
+    def deep(held)
+      case held
+      when Hash   then held.each_value { |inner| deep(inner) }.freeze
+      when Array  then held.each { |inner| deep(inner) }.freeze
+      when String then held.freeze
+      else held
+      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.
+    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.
+    def unfrozen_within(held, path = [])
+      return (path.empty? ? "(the value itself)" : path.join(".")) unless immune?(held) || held.frozen?
+
+      case held
+      when Hash  then held.lazy.filter_map { |key, inner| unfrozen_within(inner, path + [key.to_s]) }.first
+      when Array then held.each_with_index.lazy.filter_map { |inner, i| unfrozen_within(inner, path + [i.to_s]) }.first
+      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.
+    def immune?(held) = held.nil? || held == true || held == false || held.is_a?(Numeric) || held.is_a?(Symbol)
+  end
+end