hecks 0.2.0 → 0.3.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

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -0,0 +1,86 @@
+module Hecks
+  module Fuzzing
+    # A value that is DELIBERATELY THE WRONG SHAPE for the attribute it is handed
+    # to — the sibling of ValueGenerator, which only ever builds values that satisfy
+    # a declared type.
+    #
+    # That limit is why the fuzzer could not reach the space a hand-written
+    # adversarial corpus covers. spec/corpus/banking.json got there one step at a
+    # time, by hand : a value object where an Integer is declared, a Float where an
+    # Integer is declared, a numeral wearing quotes, an attribute missing entirely,
+    # an attribute the command never declared. One of those — a hash reaching a
+    # refusal message — is the exact shape that exposed refusal wording drift
+    # (a composite rendered with `inspect` at one site and JSON at another —
+    # Rendering's whole story), and no generated value
+    # could ever have produced it.
+    #
+    # These are expected to be REFUSED, and that is the point : a refusal is an
+    # answer, and its wording is pinned byte-for-byte. The bugs live in
+    # the sentence, not in the happy path.
+    module InvalidValueGenerator
+      module_function
+
+      # Each kind names a real confusion, not random noise. Ordered roughly by how
+      # often this codebase has actually been bitten by it.
+      KINDS = %i[
+        object_for_scalar
+        scalar_for_object
+        float_for_integer
+        numeral_string
+        array_for_scalar
+        boolean_for_string
+        null
+      ].freeze
+
+      def corrupt(attribute, aggregate, random:)
+        kind = kinds_for(attribute, aggregate).sample(random: random)
+        build(kind, attribute, aggregate, random: random)
+      end
+
+      # Only the confusions that MEAN anything for this attribute. Offering
+      # `scalar_for_object` for a plain Integer would just be a second spelling of
+      # `numeral_string`, and a kind that cannot be wrong for the attribute it is
+      # handed teaches the corpus nothing.
+      def kinds_for(attribute, aggregate)
+        value_object = aggregate.value_object(attribute.type.to_s)
+        return %i[scalar_for_object array_for_scalar null] if value_object
+        return %i[object_for_scalar float_for_integer numeral_string array_for_scalar null] if attribute.type.to_s == "Integer"
+
+        %i[object_for_scalar array_for_scalar boolean_for_string null]
+      end
+
+      def build(kind, attribute, aggregate, random:)
+        case kind
+        when :object_for_scalar then { "cents" => random.rand(1..1000) }
+        when :scalar_for_object then scalar_for(attribute, aggregate, random: random)
+        when :float_for_integer then random.rand(1.0..100.0).round(2)
+        when :numeral_string    then random.rand(1..1000).to_s
+        when :array_for_scalar  then [random.rand(1..10), random.rand(1..10)]
+        when :boolean_for_string then random.rand(2).zero?
+        else nil
+        end
+      end
+
+      # A bare scalar where a value object is declared. A SINGLE-FIELD value object
+      # legitimately accepts one (that is the standing-in rule every domain relies
+      # on), so the interesting case is a value object with SEVERAL fields, where a
+      # scalar cannot stand for anything and the refusal has to say so.
+      def scalar_for(attribute, aggregate, random:)
+        value_object = aggregate.value_object(attribute.type.to_s)
+        return "a bare scalar" unless value_object && value_object.attributes.size == 1
+
+        # One field, so a scalar is legal — corrupt the FIELD's own type instead,
+        # which is still a shape the attribute cannot accept.
+        { value_object.attributes.first.name.to_s => ["nested", "array"] }
+      end
+
+      # An attribute the command never declared. `refuse_unknown_arguments` is a
+      # real dispatch step (Vocabulary::AggregateDispatchOrder), and nothing
+      # generated had ever exercised it.
+      def undeclared_argument(random:)
+        name = %w[colour flavour rank note].sample(random: random)
+        [name, %w[red loud third scribbled].sample(random: random)]
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -0,0 +1,92 @@
+require "fileutils"
+require "tmpdir"
+
+module Hecks
+  module Fuzzing
+    # A FRESH, IN-PROCESS ADAPTER FOR EVERY EPHEMERAL BOOT.
+    #
+    # Fuzzing/replay copies a domain to a tmpdir and boots from there
+    # specifically to get zero-history state — `rm_rf`ing the copy's own
+    # `data/` achieves that for a file-based adapter (Memory,
+    # SqlitePersistence, Heki), because copying the DIRECTORY copies the
+    # store. It achieves nothing for an adapter that lives outside the
+    # copied directory entirely — Postgres, named by a fixed connection
+    # string in `.world` (examples/pizzas/bluebook/pizzas.world, for
+    # instance). Copying the directory does not copy or isolate the
+    # DATABASE, so a "fresh" boot against a Postgres-bound domain would
+    # still see every record any other run, ever, wrote to it.
+    #
+    # So every `.hecksagon` in the copy gets its persistence binding
+    # rewritten to Memory before booting, and any `projected_by` bind
+    # dropped outright (optional — `Registry#read_repository` already
+    # falls back to the authoritative repository when none exists). The
+    # domain's own rules and shape are untouched ; only WHICH adapter this
+    # one ephemeral copy answers through changes. What the domain is
+    # bound to for real deployment is never touched — only this tmp copy.
+    module IsolatedBoot
+      module_function
+
+      def call(domain_path)
+        Dir.mktmpdir("hecks-fuzz") do |tmp|
+          copy = File.join(tmp, File.basename(domain_path))
+          copy_dereferencing(domain_path, copy)
+          FileUtils.rm_rf(File.join(copy, "data"))
+          rebind_to_memory!(copy)
+          yield copy
+        end
+      end
+
+      # SYMLINKS ARE FOLLOWED, NOT COPIED. `FileUtils.cp_r` reproduces a
+      # symlink AS a symlink, and a RELATIVE one then points at nothing
+      # from a tmpdir — `lib/hecks/framework/bluebook/compliance
+      # .bluebook` is exactly that, a link to
+      # `examples/compliance/bluebook/compliance.bluebook`, so the whole
+      # framework domain failed to boot here with a LoadError naming a
+      # path under /var/folders that had never existed. Nothing about the
+      # domain was wrong; the copy was.
+      #
+      # `FileUtils.cp` follows a symlink and copies its CONTENT, which is
+      # what an isolated boot wants: the copy has to stand alone, since
+      # rebind_to_memory! rewrites files in it and must not reach back
+      # through a link into the real tree.
+      def copy_dereferencing(source, destination)
+        FileUtils.mkdir_p(destination)
+        Dir.glob(File.join(source, "**", "*"), File::FNM_DOTMATCH).each do |path|
+          next if [".", ".."].include?(File.basename(path))
+
+          target = File.join(destination, path.delete_prefix("#{source}/"))
+          if File.directory?(path)
+            FileUtils.mkdir_p(target)
+          else
+            FileUtils.mkdir_p(File.dirname(target))
+            FileUtils.cp(path, target)
+          end
+        end
+      end
+
+      def rebind_to_memory!(copy)
+        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |path|
+          # `persisted_by`/`projected_by` can be spelled two ways now —
+          # aggregate-scoped (`Banking::Customer.persisted_by("Heki")`,
+          # always parenthesised) and, since §0's domain-level default
+          # binds, a bare call at the hecksagon's own root
+          # (`persisted_by "Heki"`, no parens, no receiver). Both must
+          # be caught here or a domain that only declares the bare form
+          # keeps its real adapter under an "isolated" fuzz boot.
+          lines = File.readlines(path).reject { |line| line.match?(/\bprojected_by\s*\(?\s*"/) }
+          File.write(path, lines.join.gsub(/persisted_by\s*\(?\s*"[^"]+"\s*\)?/, 'persisted_by("Memory")'))
+        end
+
+        # THE SETTINGS, NOT JUST THE BIND — `WorldBuilder#method_missing`
+        # stores a settings block under BOTH "verb:adapter" and the bare
+        # "verb" (world_builder.rb:32-33), so a bind rewritten to Memory
+        # still falls back to whatever adapter's settings were declared
+        # bare — Postgres's `database:`, which Memory does not take and
+        # WiringError refuses on sight. Memory needs no settings at all
+        # (a domain with no .world boots it as the default), so the
+        # simplest correct fix is dropping .world from the copy entirely.
+        Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
+      end
+    end
+  end
+end