hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,256 @@
+Hecks.bluebook "Bluebook", version: "1" do
+  vision "The bluebook language, declared in itself. Loading a domain becomes dispatching commands into this meta-domain ; the IR it stores must equal the IR the DSL builder produces. The floor that stays hand-written is the interpreter — evaluating a predicate held as data — and IO."
+  core
+
+  # A WHOLE BLUEBOOK, handed back in one read.
+  #
+  # The twelve `DeclaredIn` queries below can walk the tree a level at a time, and
+  # a caller stitching twelve reads together is a caller reimplementing this. The
+  # language already knows how to say "gather these heads around that spine" —
+  # it is what a read model IS — so the reconstruction is DECLARED rather than
+  # coded, and the shape of what comes back is a fact about the language instead
+  # of a fact about whoever wrote the reader.
+  #
+  # Spined on Bluebook because a bluebook is what you ask for. Everything else
+  # hangs off it, down to a Member's pairs and a Dispatch's bindings.
+  read_model "WholeBluebook" do
+    description "Every declaration of one chapter, gathered around the chapter itself — the way back, in a single read."
+    reference_to Bluebook
+
+    include Bluebook
+    include Aggregate
+    include Command
+    include ValueObject
+    include Query
+    include Entity
+    include Member
+    include Policy
+    include ProcessManager
+    include Handler
+    include Dispatch
+    include ReadModel
+  end
+
+  aggregate "Bluebook" do
+    description "One .bluebook file — the root a domain declaration hangs from."
+
+    # A CHAPTER IS KNOWN BY ITS NAME, which is what anyone would have said.
+    #
+    # It was not, and the reason it was not is worth keeping : the runtime read the
+    # identity out of the payload under its head's own name, so a command that both
+    # REACHED a bluebook and carried a name could not say both, and `Normalise`
+    # could never name what it acts on. The answer at the time was to duck it —
+    # keep `name` a plain field and be reached by a minted `id` like nothing else
+    # in the language.
+    #
+    # The duck is what is gone. A command reaches its root through the REFERENCE it
+    # declares (`bluebook_id`), which is a different key from any argument it
+    # carries, so the two cannot collide however they are spelled. The fallback was
+    # hiding a lookup bug ; removing it made the bug visible, and the bug was the
+    # smaller thing.
+    identified_by BluebookName, as: :name
+
+    attribute :vision,         Vision
+    attribute :classification, Classification
+    # A domain CONTRACT version, pinned per chapter — `Hecks.bluebook "Pizzas",
+    # version: "v2"`. Held here because the language must hold everything the
+    # runtime runs on, and this was the one field it did not: the round trip sliced
+    # its comparison by the reconstruction's own keys, so a version was excluded
+    # from the check rather than failing it, and a chapter assembled purely from
+    # these records would have lost it in silence. Most chapters declare none, and
+    # ABSENT IS NOT EMPTY — an unversioned chapter offers nothing here at all.
+    attribute :version,        Version
+    # A domain's own identity can change — held here so a rename is a
+    # declared fact the language carries, not just a Ruby-side accessor.
+    # Most chapters declare none, and ABSENT IS NOT EMPTY, the same
+    # reading `version` above gives.
+    attribute :formerly_known_as, FormerlyKnownAs
+    attribute :normalisations, list_of(NormalisationRule)
+    # THE SEAM ADR 0026 ADDS. A sub-language chapter (Paging, so far the
+    # only one) names the core contexts its own `Syntax` aggregate
+    # contributes rows for — "Query", "ReadModel" — so SyntaxBoot's own
+    # discovery can find it without the core ever naming it back. Most
+    # chapters attach to nothing, and ABSENT IS NOT EMPTY, the same
+    # reading `version`/`formerly_known_as` above give.
+    attribute :attaches_to, list_of(AttachesToContext)
+
+    value_object "RuleText" do
+      # deliberately permissive : source_token and replacement are legitimately
+      # empty for the collapse_whitespace rule
+      attribute :value, String
+    end
+
+    value_object "NormalisationRule" do
+      attribute :strategy,     String
+      attribute :source_token, String
+      attribute :replacement,  String
+      attribute :boundary,     String
+      attribute :position,     String
+    end
+
+    value_object "BluebookName" do
+      attribute :value, String
+      invariant("a chapter is named") { !value.to_s.empty? }
+    end
+
+    value_object "Vision" do
+      attribute :value, String
+      invariant("a vision says something") { !value.to_s.empty? }
+    end
+
+    value_object "Classification" do
+      attribute :value, String
+      invariant("a chapter is core, supporting, or generic") do
+        value.to_s == "core" || value.to_s == "supporting" || value.to_s == "generic"
+      end
+    end
+
+    value_object "Version" do
+      attribute :value, String
+      invariant("a version says something") { !value.to_s.empty? }
+    end
+
+    value_object "FormerlyKnownAs" do
+      attribute :value, String
+      invariant("a formerly_known_as says something") { !value.to_s.empty? }
+    end
+
+    value_object "AttachesToContext" do
+      attribute :value, String
+      invariant("an attachment names a context") { !value.to_s.empty? }
+    end
+
+    command "Declare" do
+      role "Language"
+      goal "Open a chapter"
+
+      attribute :name,           BluebookName
+      attribute :vision,         Vision, optional: true
+      attribute :classification, Classification, optional: true
+      attribute :version,        Version, optional: true
+      attribute :formerly_known_as, FormerlyKnownAs, optional: true
+
+      sets :name
+      sets :vision
+      sets :classification
+      sets :version
+      sets :formerly_known_as
+
+      emits "ChapterDeclared"
+    end
+
+    # ONE CONTEXT THE CHAPTER ATTACHES TO, appended the way one identity
+    # part is (Aggregate.Identify, above) — `attaches_to "Query",
+    # "ReadModel"` names any number at once, and a list is filled by a
+    # verb of its own here the same reason it is everywhere else in this
+    # language.
+    command "Attach" do
+      role "Language"
+      goal "Name one core context this chapter's own Syntax rows attach to"
+
+      attribute :context, AttachesToContext
+
+      sets :attaches_to, append: { value: :context }
+      # S16, ADR 0026 — the language's own self-use gate: an append is
+      # exactly the shape banking's own ensures already checks ("a
+      # ledger entry was posted") { ledger.size == old.ledger.size + 1
+      # } — one more row than before, never fewer, never the same.
+      ensures("the list grew by exactly one") { attaches_to.size == old.attaches_to.size + 1 }
+      emits "ChapterAttached"
+    end
+
+    # THE WAY BACK.
+    #
+    # Until these existed the meta-domain was write-only: twelve categories, 34
+    # verbs, and not one query. A bluebook could be dispatched in and never read
+    # out, which is exactly as much as JUDGING requires — offer every declaration,
+    # collect the refusals, throw the records away. It is also why the language
+    # could only validate. A store you cannot read cannot be the source of
+    # anything, and "loading a domain becomes dispatching commands into this
+    # meta-domain" — the vision at the top of this file — needs the records to
+    # come back out as the IR the runtime runs.
+    # Named to finish a sentence about the thing, the way every other query in the
+    # corpus is — pizzas COSTING LESS THAN a ceiling, orders PENDING, cards
+    # ACTIVE. So: the bluebook CALLED "Pizzas".
+    query "Called" do
+      attribute :name, BluebookName
+      where(name: :name)
+    end
+
+    command "Normalise" do
+      role "Language"
+      goal "Attach one canonical-form rule to the chapter"
+
+      attribute :strategy,     RuleText
+      attribute :source_token, RuleText
+      attribute :replacement,  RuleText
+      attribute :boundary,     RuleText
+      attribute :position,     RuleText, optional: true
+
+      sets :normalisations, append: {
+        strategy: :strategy, source_token: :source_token,
+        replacement: :replacement, boundary: :boundary, position: :position
+      }
+
+      emits "NormalisationAttached"
+    end
+
+    # HOW BLUEBOOK IS SPELLED. These rows live with the concept
+    # they describe; SyntaxBoot discovers every aggregate-local seed table.
+    # Contexts represented here: File, Bluebook.
+    value_object "KeywordSeed" do
+      attribute :word,          String
+      attribute :context,       String, admits: "Syntax::Context"
+      attribute :body,          String, admits: "Syntax::Body"
+      attribute :inner,         String
+      attribute :opens,         String
+      attribute :fills,         String
+      attribute :status,        String, default: "admitted", admits: "Syntax::Status"
+      attribute :was,           String
+      attribute :resolves_via,  String, default: "", admits: "Syntax::ResolutionScope"
+      attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
+
+      member word: "bluebook",        context: "File",     body: "keywords", inner: "Bluebook",       opens: "Bluebook",       fills: ""
+      member word: "vision", context: "Bluebook", body: "none", inner: "", opens: "", fills: "vision"
+      member word: "formerly_known_as", context: "Bluebook", body: "none",   inner: "",               opens: "",               fills: "formerly_known_as"
+      member word: "attaches_to",     context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "attaches_to", calls: "attaches_to_impl"
+      member word: "core",            context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
+      member word: "supporting",      context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
+      member word: "generic",         context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
+      member word: "aggregate",       context: "Bluebook", body: "keywords", inner: "Aggregate",      opens: "Aggregate",      fills: "", calls: "aggregate_impl"
+      member word: "read_model",      context: "Bluebook", body: "keywords", inner: "ReadModel",      opens: "ReadModel",      fills: "", was: "report"
+      member word: "policy",          context: "Bluebook", body: "keywords", inner: "Policy",         opens: "Policy",         fills: ""
+      member word: "process_manager", context: "Bluebook", body: "keywords", inner: "ProcessManager", opens: "ProcessManager", fills: ""
+
+    end
+
+    value_object "ArgumentSeed" do
+      attribute :keyword,          String
+      attribute :context,          String, admits: "Syntax::Context"
+      attribute :at,               String
+      attribute :named,            String
+      attribute :kind,             String, admits: "Syntax::ArgumentKind"
+      attribute :required,         String
+      attribute :fills,            String
+      attribute :selects,          String
+      attribute :pair_key_fills,   String
+      attribute :pair_value_fills, String
+      attribute :pairs_shape,      String, admits: "Syntax::PairsShape"
+      attribute :status,           String, default: "admitted", admits: "Syntax::Status"
+      attribute :variadic,         String
+      attribute :coerce,           String
+      attribute :blank_message,    String
+
+      member keyword: "bluebook",        context: "File",     at: "1", named: "",        kind: "text",     required: "true",  fills: "name"
+      member keyword: "bluebook",        context: "File",     at: "",  named: "version", kind: "text",     required: "false", fills: "version"
+      member keyword: "vision",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "vision", coerce: "false"
+      member keyword: "formerly_known_as", context: "Bluebook", at: "1", named: "",      kind: "text",     required: "true",  fills: "formerly_known_as"
+      member keyword: "attaches_to",     context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "attaches_to", variadic: "true"
+      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"
+      member keyword: "process_manager", context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"
+
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# THE LANGUAGE IS A DOMAIN LIKE ANY OTHER, and this is the line that
+# says so. `lib/hecks/language/bluebook/` describes what a bluebook
+# IS — nine files, one chapter — and until MetaValidator.defer existed it
+# could not be booted the ordinary way at all: each file was judged
+# before its siblings had been read, so Aggregate's reference to Bluebook
+# dangled and the load refused. It boots now, which means it can also be
+# fuzzed, model-checked and inspected exactly like banking or pizzas.
+#
+# Memory because this chapter is read, never written to a store — nothing
+# dispatches a command against the language in production. A binding
+# still has to be DECLARED rather than defaulted, so that what answers is
+# a stated fact rather than whatever the runtime happened to fall back on.
+Hecks.hecksagon "Bluebook" do
+  # Several constructs here declare `role "Language"` (Aggregate.Declare,
+  # Entity.Declare, ...) — only real access control once Governance can
+  # check it against something (S8).
+  uses_framework "Governance"
+  persisted_by "Memory"
+end
+
+Hecks.hecksagon "Governance" do
+  Governance::RoleAssignment.persisted_by("Memory")
+  Governance::RoleTransition.persisted_by("Memory")
+end