hecks 5.0.0 → 6.0.0

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

@@ -0,0 +1,210 @@
+Hecks.bluebook "Sentence" do
+  vision "The plain sentences a business author writes in a .bluebook, declared as data. Each phrase is one row; the Rust parser's sentence front end is generated from them, so what an author may say is a table, not code."
+  core
+
+  aggregate "Phrase" do
+    description "One sentence an author may write, with the block it is legal in and the block it opens. A phrase reaches the parser only while it is admitted."
+
+    identified_by PhraseId, as: :name
+
+    attribute :context, PhraseContext
+    attribute :pattern, PhrasePattern
+
+    value_object "PhraseId" do
+      attribute :value, String
+      invariant("a phrase names itself") { !value.to_s.empty? }
+    end
+
+    value_object "PhraseContext" do
+      attribute :value, String
+      invariant("a phrase says where it is legal") { !value.to_s.empty? }
+    end
+
+    # Literal words and punctuation, `(a|an)` for alternatives, `{slot:kind}` for what the author fills in. A slot kind
+    # is words (a noun phrase), word (one word), text (a quoted string), int, list (nouns joined by `and` or a comma),
+    # rest (the remainder of the line), path (a dotted field path) or event (a CamelCase event name).
+    value_object "PhrasePattern" do
+      attribute :value, String
+      invariant("a phrase says something") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "admitted" do
+      transition "Retire" => "retired", from: "admitted"
+      mark :terminal, "retired"
+    end
+
+    command "Retire" do
+      role "Language"
+      goal "Stop accepting a phrase; files that use it are refused with the nearest phrases"
+
+      reference_to Phrase
+
+      emits "PhraseRetired"
+    end
+
+    # One row per sentence. `opens` names the block the sentence starts ("" when it is a plain line);
+    # `canonical` is the one spelling the formatter writes when several rows say the same thing.
+    value_object "PhraseSeed" do
+      attribute :id,        String
+      attribute :context,   String
+      attribute :pattern,   String
+      attribute :opens,     String
+      attribute :canonical, String, default: "yes"
+      attribute :status,    String, default: "admitted"
+
+      member id: "domain",            context: "File",      pattern: "Domain: {name:words}",                                                  opens: "Domain"
+      member id: "classification",    context: "Vision",    pattern: "This is a {kind:word} domain",                                          opens: ""
+      member id: "namespace",         context: "Vision",    pattern: "Its module is {name:rest}",                                             opens: ""
+      member id: "version",           context: "Vision",    pattern: "Its version is {version:word}",                                       opens: ""
+      member id: "attaches",          context: "Vision",    pattern: "It attaches to {contexts:list}",                                        opens: ""
+      member id: "provides",          context: "Vision",    pattern: "It provides {capability:word}:",                                        opens: "Provides"
+      member id: "provision",         context: "Provides",  pattern: "{key:word} is {verb:rest}",                                             opens: ""
+      member id: "aggregate",         context: "Domain",    pattern: "Aggregate: {name:words}",                                               opens: "Aggregate"
+      member id: "identity",          context: "Aggregate", pattern: "(a|an|the) {owner:words} is identified by (its|their) {fields:list}",  opens: ""
+      member id: "has",               context: "Aggregate", pattern: "It has:",                                                              opens: "Has"
+      member id: "value_object",      context: "Aggregate", pattern: "(a|an|the) {name:words} has a value: {type:words}",                     opens: "ValueObject"
+      member id: "value_object_with", context: "Aggregate", pattern: "(a|an|the) {name:words} has a value: {type:words}, {options:rest}",       opens: "ValueObject"
+      member id: "closed_set",        context: "Aggregate", pattern: "(a|an|the) {name:words} is one of: {values:list}",                       opens: "ValueObject"
+      member id: "closed_set_named",  context: "Aggregate", pattern: "(a|an|the) {name:words} has (a|an) {attr:words} that is one of: {values:list}", opens: "ValueObject"
+      member id: "value_fields",      context: "Aggregate", pattern: "(a|an|the) {name:words} has:",                                           opens: "Fields"
+      member id: "field",             context: "Fields",    pattern: "(a|an|the|some) {name:words}: {type:words}",                                 opens: ""
+      member id: "field_with",        context: "Fields",    pattern: "(a|an|the|some) {name:words}: {type:words}, {options:rest}",                 opens: ""
+      member id: "field_rule",        context: "Fields",    pattern: "Rule {description:text} holds when {condition:rest}",                   opens: ""
+      member id: "field_member",      context: "Fields",    pattern: "Member {pairs:rest}",                                                    opens: ""
+      member id: "lifecycle",         context: "Aggregate", pattern: "Lifecycle: {field:words}, starting as {state:word}",                    opens: "Lifecycle"
+      member id: "command",           context: "Aggregate", pattern: "Command: {name:words}",                                                 opens: "Command"
+      member id: "query",             context: "Aggregate", pattern: "Query: {name:words}",                                                   opens: "Query"
+      member id: "entity",            context: "Aggregate", pattern: "Entity: {name:words}",                                                   opens: "Aggregate"
+      member id: "aggregate_provenance", context: "Aggregate", pattern: "Its provenance is {value:rest}",                                    opens: ""
+      member id: "aggregate_rule",    context: "Aggregate", pattern: "Rule {description:text} holds when {condition:rest}",                   opens: ""
+      member id: "precondition",      context: "Aggregate", pattern: "Precondition {description:text} holds when {condition:rest}",           opens: ""
+      member id: "projected",         context: "Aggregate", pattern: "It shows {name:words} as the {remote:words} of the {reference:words}",  opens: ""
+      member id: "attribute",         context: "Has",       pattern: "(a|an|the|some) {name:words}: {type:words}",                                 opens: ""
+      member id: "attribute_with",    context: "Has",       pattern: "(a|an|the|some) {name:words}: {type:words}, {options:rest}",                 opens: ""
+      member id: "rule",              context: "ValueObject", pattern: "Rule {description:text} holds when {condition:rest}",                 opens: ""
+      member id: "transition",        context: "Lifecycle", pattern: "{command:words} moves (a|an|the) {owner:words} from {from:word} to {to:word}", opens: ""
+      member id: "marks",             context: "Lifecycle", pattern: "Mark {mark:word}: {states:list}",                                       opens: ""
+      member id: "goal",              context: "Command",   pattern: "Goal: {goal:rest}",                                                     opens: ""
+      member id: "role",              context: "Command",   pattern: "Who: {role:words}",                                                     opens: ""
+      member id: "acts_on",           context: "Command",   pattern: "It acts on (a|an) existing {owner:words}",                              opens: ""
+      member id: "arguments",         context: "Command",   pattern: "When {names:list} (is|are) given",                                      opens: ""
+      member id: "given",             context: "Command",   pattern: "Given {description:text} holds when {condition:rest}",                  opens: ""
+      member id: "sets",              context: "Command",   pattern: "(Then|And) {names:list} (is|are) set",                                  opens: ""
+      member id: "set_to",            context: "Command",   pattern: "(Then|And) the {target:words} is set to the {source:words}",             opens: ""
+      member id: "set_to_literal",    context: "Command",   pattern: "(Then|And) the {target:words} is set to {value:rest}",                   opens: ""
+      member id: "set_to_state",      context: "Command",   pattern: "(Then|And) the {target:words} is set to what the {source:words} was",    opens: ""
+      member id: "set_to_result",     context: "Command",   pattern: "(Then|And) the {target:words} is set to the result of {code:rest}",      opens: ""
+      member id: "go_up",             context: "Command",   pattern: "(Then|And) the {target:words} goes up by the {source:words}",            opens: ""
+      member id: "go_up_by",          context: "Command",   pattern: "(Then|And) the {target:words} goes up by {value:rest}",                  opens: ""
+      member id: "go_down",           context: "Command",   pattern: "(Then|And) the {target:words} goes down by the {source:words}",          opens: ""
+      member id: "go_down_by",        context: "Command",   pattern: "(Then|And) the {target:words} goes down by {value:rest}",                opens: ""
+      member id: "multiply",          context: "Command",   pattern: "(Then|And) the {target:words} is multiplied by the {source:words}",      opens: ""
+      member id: "remove",            context: "Command",   pattern: "(Then|And) the {source:words} is removed from the {target:words}",       opens: ""
+      member id: "add_row",           context: "Command",   pattern: "(Then|And) a row is added to the {target:words} with {fields:rest}",    opens: ""
+      member id: "delegates",         context: "Command",   pattern: "(Then|And) the {entity:words} is told to {command:words} with {fields:rest}", opens: ""
+      member id: "corrects",          context: "Command",   pattern: "(Then|And) {event:event} is corrected with {fields:rest}",               opens: ""
+      member id: "clamp",             context: "Command",   pattern: "(Then|And) the {target:words} is kept between {low:int} and {high:int}", opens: ""
+      member id: "from_states",       context: "Command",   pattern: "It can only happen from {states:list}",                                  opens: ""
+      member id: "idempotent",        context: "Command",   pattern: "It is safe to deliver twice",                                           opens: ""
+      member id: "command_provenance", context: "Command", pattern: "Its provenance is {value:rest}",                                        opens: ""
+      member id: "ensures",           context: "Command",   pattern: "Afterwards {description:text} holds when {condition:rest}",              opens: ""
+      member id: "takes",             context: "Command",   pattern: "It takes:",                                                              opens: "Has"
+      member id: "announces",         context: "Command",   pattern: "(Then|And) {event:event} is announced",                                 opens: ""
+      member id: "where_is",          context: "Query",     pattern: "Where the {field:words} is {value:rest}",                         opens: ""
+      member id: "where_is_not",      context: "Query",     pattern: "Where the {field:words} is not {value:rest}",                     opens: ""
+      member id: "where_over",        context: "Query",     pattern: "Where the {field:words} is more than {value:rest}",               opens: ""
+      member id: "where_at_least",    context: "Query",     pattern: "Where the {field:words} is at least {value:rest}",                opens: ""
+      member id: "where_under",       context: "Query",     pattern: "Where the {field:words} is less than {value:rest}",               opens: ""
+      member id: "where_at_most",     context: "Query",     pattern: "Where the {field:words} is at most {value:rest}",                 opens: ""
+      member id: "where_has",         context: "Query",     pattern: "Where the {field:words} contains {value:rest}",                   opens: ""
+      member id: "where_in",          context: "Query",     pattern: "Where the {field:words} is one of {values:list}",                 opens: ""
+      member id: "query_takes",       context: "Query",     pattern: "It takes:",                                                       opens: "Has"
+      member id: "query_limit",       context: "Query",     pattern: "Limited to {n:int}",                                              opens: ""
+      member id: "query_skip",        context: "Query",     pattern: "Skipping the first {n:int}",                                            opens: ""
+      member id: "query_cursor",      context: "Query",     pattern: "A caller walks it a page at a time by the {field:words}",              opens: ""
+      member id: "query_nulls",       context: "Query",     pattern: "Empty values come {position:word}",                                     opens: ""
+      member id: "query_access",      context: "Query",     pattern: "Access is checked by {policy:words}",                                   opens: ""
+      member id: "query_access_for",  context: "Query",     pattern: "Access is checked by {policy:words} for each {tenant:words}",           opens: ""
+      member id: "query_inspect",     context: "Query",     pattern: "It can be inspected as {mode:word}",                                    opens: ""
+      member id: "where_none_in",     context: "Query",     pattern: "Where the {field:words} has no {aggregate:words} in {state:word}",      opens: ""
+      member id: "query_returns",     context: "Query",     pattern: "It returns {type:words}",                                         opens: ""
+      member id: "query_returns_list", context: "Query",    pattern: "It returns list of {type:words}",                                 opens: ""
+      member id: "order",             context: "Query",     pattern: "Ordered by {path:path}, {direction:word}",                              opens: ""
+      member id: "not_empty",         context: "Condition", pattern: "the {field:words} is not empty",                                        opens: ""
+      member id: "at_least",          context: "Condition", pattern: "the {field:words} is at least {n:int}",                                 opens: ""
+      member id: "equals",            context: "Condition", pattern: "the {field:words} is {value:word}",                                     opens: ""
+      member id: "expression",        context: "Condition", pattern: "this is true: {code:rest}",                                             opens: ""
+      member id: "policy",            context: "Domain",    pattern: "Policy: {name:words}",                                                 opens: "Policy"
+      member id: "report",            context: "Domain",    pattern: "Report: {name:words}",                                                   opens: "Report"
+      member id: "process",           context: "Domain",    pattern: "Process: {name:words}",                                                  opens: "Process"
+      member id: "process_matched",   context: "Process",   pattern: "It is matched up by {path:path}",                                       opens: ""
+      member id: "process_starts",    context: "Process",   pattern: "It starts when {event:event} is announced",                             opens: ""
+      member id: "process_ends",      context: "Process",   pattern: "It ends when {event:event} is announced",                               opens: ""
+      member id: "process_when",      context: "Process",   pattern: "When {event:event} is announced and it is {from:word}, it moves to {to:word}", opens: "Handler"
+      member id: "process_when_refused", context: "Process", pattern: "When it is refused and it is {from:word}, it moves to {to:word}",     opens: "Handler"
+      member id: "process_tell",      context: "Handler",   pattern: "Then the {owner:words} is told to {command:words}",                      opens: ""
+      member id: "process_tell_with", context: "Handler",   pattern: "Then the {owner:words} is told to {command:words} with {fields:rest}",  opens: ""
+      member id: "process_undo",      context: "Handler",   pattern: "If that is refused, the {owner:words} is told to {command:words}",       opens: ""
+      member id: "process_undo_with", context: "Handler",   pattern: "If that is refused, the {owner:words} is told to {command:words} with {fields:rest}", opens: ""
+      member id: "includes",          context: "Report",    pattern: "It includes (a|an|the) {name:words}",                                   opens: ""
+      member id: "includes_as",       context: "Report",    pattern: "It includes (a|an|the) {name:words} as (a|an|the) {as:words}",           opens: ""
+      member id: "about",             context: "Report",    pattern: "It is about (a|an|the) {target:words}",                                  opens: ""
+      member id: "about_as",          context: "Report",    pattern: "It is about (a|an|the) {target:words} as (a|an|the) {as:words}",         opens: ""
+      member id: "groups",            context: "Report",    pattern: "It groups by {fields:list}",                                             opens: ""
+      member id: "counts",            context: "Report",    pattern: "It counts them",                                                         opens: ""
+      member id: "sums",              context: "Report",    pattern: "It adds up the {field:words}",                                           opens: ""
+      member id: "averages",          context: "Report",    pattern: "It averages the {field:words}",                                          opens: ""
+      member id: "lowest",            context: "Report",    pattern: "It finds the lowest {field:words}",                                      opens: ""
+      member id: "highest",           context: "Report",    pattern: "It finds the highest {field:words}",                                     opens: ""
+      member id: "median",            context: "Report",    pattern: "It finds the median {field:words}",                                      opens: ""
+      member id: "percentile",        context: "Report",    pattern: "It finds the {at:text} percentile of the {field:words}",                 opens: ""
+      member id: "any_holds",         context: "Report",    pattern: "It checks if any {field:words} holds",                                   opens: ""
+      member id: "all_hold",          context: "Report",    pattern: "It checks if all {field:words} hold",                                    opens: ""
+      member id: "report_where",      context: "Report",    pattern: "Where {condition:rest}",                                                 opens: ""
+      member id: "report_order",      context: "Report",    pattern: "Ordered by {path:path}, {direction:word}",                               opens: ""
+      member id: "report_limit",      context: "Report",    pattern: "Limited to {n:int}",                                                     opens: ""
+      member id: "report_skip",       context: "Report",    pattern: "Skipping the first {n:int}",                                            opens: ""
+      member id: "report_cursor",     context: "Report",    pattern: "A caller walks it a page at a time by the {field:words}",              opens: ""
+      member id: "report_nulls",      context: "Report",    pattern: "Empty values come {position:word}",                                     opens: ""
+      member id: "report_access",     context: "Report",    pattern: "Access is checked by {policy:words}",                                   opens: ""
+      member id: "report_access_for", context: "Report",    pattern: "Access is checked by {policy:words} for each {tenant:words}",           opens: ""
+      member id: "report_inspect",    context: "Report",    pattern: "It can be inspected as {mode:word}",                                    opens: ""
+      member id: "whenever",          context: "Policy",    pattern: "Whenever {event:event} is announced",                                   opens: ""
+      member id: "whenever_by",       context: "Policy",    pattern: "Whenever {event:event} is announced by (a|an) {owner:words}",           opens: ""
+      member id: "whenever_outside",  context: "Policy",    pattern: "Whenever the outside announces {event:event}",                         opens: ""
+      member id: "for_each",          context: "Policy",    pattern: "For each {query:words} of the {owner:words}",                          opens: ""
+      member id: "only_when",         context: "Policy",    pattern: "Only when {condition:rest}",                                            opens: ""
+      member id: "policy_tell",       context: "Policy",    pattern: "Then the {owner:words} is told to {command:words}",                  opens: ""
+      member id: "policy_across",     context: "Policy",    pattern: "It crosses into the {domain:words} domain",                            opens: ""
+      member id: "policy_undelivered", context: "Policy",   pattern: "It is expected to go undelivered",                                      opens: ""
+      member id: "with_same",         context: "Policy",    pattern: "With the {key:words}",                                                  opens: ""
+      member id: "with_from",         context: "Policy",    pattern: "With the {key:words} from the {from:words}",                            opens: ""
+      member id: "with_as",           context: "Policy",    pattern: "With the {key:words} as {value:rest}",                                  opens: ""
+      member id: "runs_with",         context: "Policy",    pattern: "Then {command:words} runs with {fields:list}",                          opens: ""
+      member id: "runs",              context: "Policy",    pattern: "Then {command:words} runs",                                             opens: ""
+      member id: "asked_with",        context: "Policy",    pattern: "Then {need:words} is asked with {fields:list}",                         opens: ""
+      member id: "asked",             context: "Policy",    pattern: "Then {need:words} is asked",                                            opens: ""
+      member id: "examples_for",      context: "ExamplesFile", pattern: "Examples for: {name:words}",                                       opens: "Examples"
+      member id: "background",        context: "Examples",  pattern: "Background:",                                                           opens: "Background"
+      member id: "example",           context: "Examples",  pattern: "Example: {title:rest}",                                                 opens: "Example"
+      member id: "person_role",       context: "Background", pattern: "{person:words} is (a|an) {role:words}",                                opens: ""
+      member id: "given_step",        context: "Example",   pattern: "Given {step:rest}",                                                     opens: ""
+      member id: "when_step",         context: "Example",   pattern: "When {step:rest}",                                                      opens: ""
+      member id: "then_outcome",      context: "Example",   pattern: "Then {outcome:rest}",                                                   opens: ""
+      member id: "and_line",          context: "Example",   pattern: "And {line:rest}",                                                       opens: ""
+      member id: "where_table",       context: "Example",   pattern: "Where:",                                                                opens: "Table"
+      member id: "step_creates",      context: "Step",      pattern: "{who:words} {verb:word} (a|an) {noun:words} with {args:rest}",           opens: ""
+      member id: "step_creates_bare", context: "Step",      pattern: "{who:words} {verb:word} (a|an) {noun:words}",                            opens: ""
+      member id: "step_acts",         context: "Step",      pattern: "{who:words} {verb:word} it with {args:rest}",                            opens: ""
+      member id: "step_acts_bare",    context: "Step",      pattern: "{who:words} {verb:word} it",                                             opens: ""
+      member id: "step_tries_creates", context: "Step",     pattern: "{who:words} tries to {verb:word} (a|an) {noun:words} with {args:rest}",  opens: ""
+      member id: "step_tries_creates_bare", context: "Step", pattern: "{who:words} tries to {verb:word} (a|an) {noun:words}",                  opens: ""
+      member id: "step_tries_acts",   context: "Step",      pattern: "{who:words} tries to {verb:word} it with {args:rest}",                   opens: ""
+      member id: "step_tries_acts_bare", context: "Step",   pattern: "{who:words} tries to {verb:word} it",                                    opens: ""
+      member id: "outcome_state",     context: "Outcome",   pattern: "the {noun:words} is {state:word}",                                      opens: ""
+      member id: "outcome_announced", context: "Outcome",   pattern: "{event:event} is announced",                                            opens: ""
+      member id: "outcome_refused_role", context: "Outcome", pattern: "it is refused because only (a|an) {role:words} may do it",             opens: ""
+      member id: "outcome_refused",   context: "Outcome",   pattern: "it is refused because {reason:rest}",                                   opens: ""
+    end
+  end
+end

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

@@ -24,16 +24,16 @@ Hecks.bluebook "World" do
       invariant("a latest version says something") { !value.to_s.empty? }
     end
 
-    # The connection every chapter's database-taking persistence adapter
-    # uses unless that chapter's own world says otherwise — a world's
-    # per-chapter `persisted_by ... database` block, written once.
+    # The connection every bluebook's database-taking persistence adapter
+    # uses unless that bluebook's own world says otherwise — a world's
+    # per-bluebook `persisted_by ... database` block, written once.
     value_object "DefaultDatabase" do
       attribute :value, String
       invariant("a default database says something") { !value.to_s.empty? }
     end
 
     # The persistence adapter every aggregate binds to unless its own
-    # chapter's hecksagon binds it — between an explicit bind and the
+    # bluebook's hecksagon binds it — between an explicit bind and the
     # framework's in-memory fallback.
     value_object "DefaultAdapter" do
       attribute :value, String
@@ -76,8 +76,8 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
-      # The connection string and persistence adapter every chapter of a
-      # project would otherwise repeat, written once here; a chapter's own
+      # The connection string and persistence adapter every bluebook of a
+      # project would otherwise repeat, written once here; a bluebook's own
       # world or hecksagon bind still wins.
       member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
       member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"

data/lib/hecks/literal.rb

@@ -81,11 +81,17 @@ module Hecks
 
     ESCAPED = { '"' => '\\"', "\\" => "\\\\" }.freeze
 
+    # A double quote or a backslash: the characters `quote` escapes.
+    NEEDS_ESCAPE = /["\\]/
+
+    # A backslash escape, capturing the character it escapes.
+    ESCAPE_SEQUENCE = /\\(.)/
+
     # Wraps `text` in double quotes, escaping embedded quotes and backslashes.
     #
     # @param text [String] raw text to quote
     # @return [String] the quoted, escaped spelling
-    def quote(text) = "\"#{text.gsub(/["\\]/) { |char| ESCAPED[char] }}\""
+    def quote(text) = "\"#{text.gsub(NEEDS_ESCAPE) { |char| ESCAPED[char] }}\""
 
     # Tells whether `raw` is a double-quoted literal.
     #
@@ -97,7 +103,7 @@ module Hecks
     #
     # @param raw [String] a quoted literal, as `quoted?` would confirm
     # @return [String] the unescaped text inside the quotes
-    def unquote(raw) = raw[1..-2].gsub(/\\(.)/) { ::Regexp.last_match(1) }
+    def unquote(raw) = raw[1..-2].gsub(ESCAPE_SEQUENCE) { ::Regexp.last_match(1) }
 
     # Parses a `{key: value, ...}` wire literal.
     #

data/lib/hecks/naming.rb

@@ -6,6 +6,24 @@ module Hecks
     # join the same way, or string-compared references resolve to nothing.
     IDENTITY_JOIN = ":".freeze
 
+    # An uppercase run followed by a capitalised word: the "M|C" in "ATMCard".
+    ACRONYM_BOUNDARY = /([A-Z]+)([A-Z][a-z])/
+
+    # A lowercase letter or digit followed by an uppercase letter: the "y|L" in "dailyLimit".
+    CAMEL_BOUNDARY = /([a-z\d])([A-Z])/
+
+    # The first character of a word, captured.
+    FIRST_CHARACTER = /\A(.)/
+
+    # A word of two or more capitals and nothing else: an acronym such as "ATM".
+    ACRONYM = /\A[A-Z]{2,}\z/
+
+    # A consonant followed by a final "y", as in "category".
+    CONSONANT_Y_ENDING = /[^aeiou]y\z/
+
+    # A final s, x, z, ch or sh: the endings whose plural takes "es".
+    SIBILANT_ENDING = /(s|x|z|ch|sh)\z/
+
     module_function
 
     # Joins the parts of an identity in declaration order.
@@ -25,13 +43,20 @@ module Hecks
       type.to_s.split("::").last.to_s
     end
 
+    # The last segment of a dotted path: `"Pizzas.Pizza.Created"` -> `"Created"`.
+    #
+    # @param dotted [String, Symbol, #to_s] a `.`-joined path
+    # @return [String, nil] the text after the last `.`, the whole text if there is none, or nil
+    #   for an empty path
+    def last_segment(dotted) = dotted.to_s.split(".").last
+
     # snake_case -> PascalCase. Names a closed-set value object synthesised from an
     # inline attribute; the derivation is part of the IR contract.
     #
     # @param text [String, Symbol, #to_s] a snake_case (or already Pascal) name
     # @return [String] the PascalCase form
     def pascal(text)
-      text.to_s.split("_").map { |part| part.sub(/\A(.)/) { Regexp.last_match(1).upcase } }.join
+      text.to_s.split("_").map { |part| part.sub(FIRST_CHARACTER) { Regexp.last_match(1).upcase } }.join
     end
 
     # PascalCase or camelCase -> snake_case.
@@ -39,10 +64,19 @@ module Hecks
     # @param text [String, Symbol, #to_s] a Pascal-, camel-, or already snake-case name
     # @return [String] the lowercase, underscore-separated form
     def snake(text)
-      text.to_s
-          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-          .downcase
+      split_case(text, "_").downcase
+    end
+
+    # Puts `separator` at every case boundary of an identifier: before the capitalised word
+    # after an acronym, and between a lowercase letter or digit and the capital that follows.
+    #
+    # @param text [String, Symbol, #to_s] a Pascal- or camel-case name
+    # @param separator [String] what to put at each boundary, such as `"_"` or `" "`
+    # @return [String] the name with `separator` at each boundary, case unchanged
+    def split_case(text, separator)
+      replacement = "\\1#{separator}\\2"
+      acronyms_apart = text.to_s.gsub(ACRONYM_BOUNDARY, replacement)
+      acronyms_apart.gsub(CAMEL_BOUNDARY, replacement)
     end
 
     # An identifier as a sentence-cased phrase: `ATMCard` -> "ATM card",
@@ -51,13 +85,9 @@ module Hecks
     # @param text [String, Symbol, #to_s] a Pascal-, camel-, or snake-case identifier
     # @return [String] the space-separated, sentence-cased phrase
     def words(text)
-      parts = text.to_s
-                  .tr("_", " ")
-                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
-                  .gsub(/([a-z\d])([A-Z])/, '\1 \2')
-                  .split
+      parts = split_case(text.to_s.tr("_", " "), " ").split
       parts.each_with_index.map do |part, index|
-        next part if part.match?(/\A[A-Z]{2,}\z/)
+        next part if part.match?(ACRONYM)
 
         index.zero? ? part.capitalize : part.downcase
       end.join(" ")
@@ -94,8 +124,8 @@ module Hecks
     # @return [String] the pluralised name
     def plural(text)
       word = text.to_s
-      return "#{word[0..-2]}ies" if word.match?(/[^aeiou]y\z/)
-      return "#{word}es"         if word.match?(/(s|x|z|ch|sh)\z/)
+      return "#{word[0..-2]}ies" if word.match?(CONSONANT_Y_ENDING)
+      return "#{word}es"         if word.match?(SIBILANT_ENDING)
 
       "#{word}s"
     end
@@ -122,7 +152,7 @@ module Hecks
     # @param word [String] a plural name
     # @return [Boolean] whether it is a sibilant stem plus `plural`'s "es"
     def sibilant_es?(word)
-      word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+      word.length > 3 && word.end_with?("es") && word[0..-3].match?(SIBILANT_ENDING)
     end
 
     # Derives the attribute name a reference to `type` is stored under.

data/lib/hecks/persistence_legacy_fixture/postgres_stores.rb

@@ -35,9 +35,10 @@ module Hecks
         end
 
         def postgres_rows(instance)
-          adapter = Hecks::Adapters::Postgres.new(aggregate: instance.aggregate, settings: { database: SCRATCH[:postgres] })
+          aggregate = instance.aggregate
+          adapter = Hecks::Adapters::Postgres.new(aggregate: aggregate, settings: { database: SCRATCH[:postgres] })
           adapter.save(instance)
-          name = instance.aggregate.storage_name
+          name = aggregate.storage_name
           [name, stored_rows(adapter.instance_variable_get(:@db), name)]
         end
 
@@ -52,19 +53,19 @@ module Hecks
 
         def write_postgres_era(instances)
           reset_dir("postgres_era")
-          rows = instances.to_h { |instance| [instance.aggregate.storage_name, era_rows(instance)] }
+          rows = instances.to_h { |instance| [stored_as(instance.aggregate), era_rows(instance)] }
           write_json("postgres_era/rows.json", rows)
         end
 
         def era_rows(instance)
-          adapter = Hecks::Adapters::PostgresEra.new(aggregate: instance.aggregate,
-                                                     settings:  { database: SCRATCH[:postgres_era] })
+          aggregate = instance.aggregate
+          adapter = Hecks::Adapters::PostgresEra.new(aggregate: aggregate, settings: { database: SCRATCH[:postgres_era] })
           adapter.save(instance)
           db = adapter.instance_variable_get(:@db)
           snapshot = adapter.send(:quoted_head_snapshot)
           {
             "journal"       => journal_rows(db, adapter.instance_variable_get(:@lineage).quoted_journal,
-                                            instance.aggregate.storage_name),
+                                            aggregate.storage_name),
             "head_snapshot" => db.exec("SELECT id, ordinal, operation, state FROM #{snapshot} ORDER BY id").to_a
           }
         end

data/lib/hecks/persistence_legacy_fixture/regenerate.rb

@@ -76,7 +76,7 @@ module Hecks
           instances.each do |instance|
             Hecks::Adapters::Heki.new(aggregate: instance.aggregate, settings: { dir: "." }, root: tmp).save(instance)
             %w[heki heki.journal].each do |ext|
-              FileUtils.cp(File.join(tmp, "#{instance.aggregate.storage_name}.#{ext}"), out)
+              FileUtils.cp(File.join(tmp, "#{stored_as(instance.aggregate)}.#{ext}"), out)
             end
           end
         end
@@ -114,8 +114,12 @@ module Hecks
           Hecks::Adapters::D1.new(aggregate: instance.aggregate,
                                   settings:  { account_id: "acc", database_id: "db", api_token: "tok" }).save(instance)
         end
-        [instance.aggregate.storage_name, "#{instance.aggregate.storage_name}_entries"]
+        name = stored_as(instance.aggregate)
+        [name, "#{name}_entries"]
       end
+
+      # The table or file stem an aggregate's records are stored under.
+      def stored_as(aggregate) = aggregate.storage_name
     end
   end
 end

data/lib/hecks/ports/access_control.rb

@@ -26,8 +26,8 @@ module Hecks
 
       # Admits a new person, in whatever way this domain's adapter defines admission.
       #
-      # The keywords carry the names of a verified OIDC sign-in, but nothing here wires
-      # one to this port, so their shapes are adapter-defined.
+      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`),
+      # but nothing here wires the two together, so their shapes are adapter-defined.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param email [Object] adapter-defined, forwarded unchanged; the person's email

data/lib/hecks/ports/agent/answers.rb

@@ -103,14 +103,14 @@ module Hecks
         # `Interview::Session#offer`'s call.
         #
         # @param row [Hash{String => Object}] one proposal row of the adapter's answer
-        # @return [String] the row's `"verb"`, shaped `Chapter::Aggregate.Command`
+        # @return [String] the row's `"verb"`, shaped `Bluebook::Aggregate.Command`
         # @raise [Ports::Agent::ValidationError] if the verb is missing or does not match
         #   `VERB_PATTERN`
         def verb!(row)
           verb = row["verb"].to_s
           return verb if VERB_PATTERN.match?(verb)
 
-          raise ValidationError, "#{verb.inspect} is not a fully-qualified verb (Chapter::Aggregate.Command)"
+          raise ValidationError, "#{verb.inspect} is not a fully-qualified verb (Bluebook::Aggregate.Command)"
         end
 
         # Reads a finding row's kind, refusing one outside the closed critique vocabulary.

data/lib/hecks/ports/agent.rb

@@ -63,7 +63,7 @@ module Hecks
       # @param state [Hash] declaration plus gaps
       # @return [Array<Ports::Agent::Proposal>]
       # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"proposals"`
-      #   rows have a `Chapter::Aggregate.Command` verb, a rationale and named arguments
+      #   rows have a `Bluebook::Aggregate.Command` verb, a rationale and named arguments
       # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
       # @raise [Runtime::WiringError] unless exactly one adapter implements the port
       def interpret(registry, prose:, state:)
@@ -73,7 +73,7 @@ module Hecks
       # Asks the adapter to judge a declared model on taste.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param declared [Hash] the chapter as declared so far
+      # @param declared [Hash] the bluebook as declared so far
       # @param refusals [Array<Object>] refusals the language already raised
       # @param findings [Array<Object>] `Session#gaps` findings; both are passed so the
       #   adapter spends its judgement on what neither can see

data/lib/hecks/ports/authentication.port

@@ -0,0 +1,6 @@
+Hecks.port "authentication" do
+  verb    "authenticated_by"
+  signal  :reply
+  answers :authorization_url
+  answers :verify
+end

data/lib/hecks/ports/authentication.rb

@@ -0,0 +1,67 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # The OIDC handshake: builds the provider URL and turns the returned code into verified claims.
+    # One adapter registry-wide answers it; it never touches the registry's Identity data.
+    module Authentication
+      NAME = "authentication".freeze
+
+      # A sign-in that could not be verified (state mismatch, failed code exchange, bad ID token).
+      class ValidationError < StandardError
+      end
+
+      module_function
+
+      # Builds the provider URL that starts a sign-in, with the CSRF state minted for it.
+      #
+      # The caller keeps the state and hands it back to `verify` as `expected_state`.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @return [Array(String, String)] the URL to send the browser to, then the fresh
+      #   `state` value embedded in it
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      # @raise [KeyError] if the adapter's required configuration is unset
+      def authorization_url(registry)
+        adapter(registry).authorization_url
+      end
+
+      # Exchanges the authorization code a provider sent back for a Hash of verified claims.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param code [String] the authorization code the provider sent back
+      # @param state [String, nil] the state parameter the provider returned; nil is refused
+      # @param expected_state [String, nil] the state `authorization_url` returned; nil is refused
+      # @return [Hash{Symbol => Object}] the verified claims: `issuer:`, `subject:`, `email:`
+      #   (nil if the token carries none) and `email_verified:` -- never the raw token
+      # @raise [Ports::Authentication::ValidationError] if a state is nil or they differ, the
+      #   code exchange fails, or the ID token is missing or does not verify
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      # @raise [KeyError] if required configuration is unset, or the token lacks `iss`/`sub`
+      def verify(registry, code:, state:, expected_state:)
+        adapter(registry).verify(code: code, state: state, expected_state: expected_state)
+      end
+
+      # Finds the single adapter bound to this port.
+      #
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
+
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can authenticate a sign-in" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
+      end
+    end
+  end
+end

data/lib/hecks/ports/authorization.rb

@@ -19,7 +19,7 @@ module Hecks
       # @param scope [String, nil] only a grant made for this scope counts; nil counts any scope
       # @return [Boolean] true if at least one live grant of `role` to `actor_id` passes
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
-      #   or the governance-backed adapter finds no single chapter providing `"authorization"`
+      #   or the governance-backed adapter finds no single bluebook providing `"authorization"`
       def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
         adapter(registry).holds_role?(registry, actor_id: actor_id, role: role, as_of: as_of, scope: scope)
       end
@@ -33,7 +33,7 @@ module Hecks
       # @return [Boolean] true if a live (not ended) allowance lets `from_role` act as
       #   `to_role`
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
-      #   or the governance-backed adapter finds no single loaded chapter providing
+      #   or the governance-backed adapter finds no single loaded bluebook providing
       #   `"authorization"`
       def authorized_as?(registry, from_role:, to_role:)
         adapter(registry).authorized_as?(registry, from_role: from_role, to_role: to_role)
@@ -46,7 +46,7 @@ module Hecks
       # @return [String, nil] the role name of the actor's first live (not ended) grant, or
       #   nil if it has none; the caller supplies any fallback
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
-      #   or the governance-backed adapter finds no single loaded chapter providing
+      #   or the governance-backed adapter finds no single loaded bluebook providing
       #   `"authorization"`
       def live_role_for(registry, actor_id:)
         adapter(registry).live_role_for(registry, actor_id: actor_id)

data/lib/hecks/ports/dispatch.port

@@ -0,0 +1,5 @@
+Hecks.port "dispatch" do
+  verb    "dispatched_by"
+  signal  :reply
+  answers :dispatcher
+end