hecks 5.0.0 → 7.0.0

data/rust/parser/src/parse/entity.rs

@@ -12,11 +12,11 @@ pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
     Diagnostic::not_yet_implemented(file, line, format!("Entity.{word}"))
 }
 
-/// Outcome of looking up a bare `given(desc)` among the chapter's entity-scoped givens.
+/// Outcome of looking up a bare `given(desc)` among the bluebook's entity-scoped givens.
 ///
-/// `Pending` defers to the final pass in `parse::chapter::parse_chapter`, since a chapter may be
+/// `Pending` defers to the final pass in `parse::bluebook::parse_bluebook`, since a bluebook may be
 /// split across files. `declared_by:` is plain text: a piece has no addressable constant.
-pub enum ChapterEntityGivenLookup {
+pub enum BluebookEntityGivenLookup {
     Resolved(ir::Given),
     Pending {
         description: String,
@@ -26,12 +26,12 @@ pub enum ChapterEntityGivenLookup {
     },
 }
 
-fn try_reference_named_chapter_entity_given(
+fn try_reference_named_bluebook_entity_given(
     file: &str,
     lines: &[SourceLine],
     pos: &mut usize,
-    chapter_entity_named_givens: &[(String, ir::Given)],
-) -> ParseResult<Option<ChapterEntityGivenLookup>> {
+    bluebook_entity_named_givens: &[(String, ir::Given)],
+) -> ParseResult<Option<BluebookEntityGivenLookup>> {
     let Some(&line) = lines.get(*pos) else {
         return Ok(None);
     };
@@ -48,7 +48,7 @@ fn try_reference_named_chapter_entity_given(
     let description = super::positional_text(file, line.number, "given", &args, 1)?;
     let declared_by = super::named_text(&args, "declared_by");
 
-    let candidates: Vec<&(String, ir::Given)> = chapter_entity_named_givens
+    let candidates: Vec<&(String, ir::Given)> = bluebook_entity_named_givens
         .iter()
         .filter(|(_, given)| given.description.as_deref() == Some(description.as_str()))
         .collect();
@@ -58,8 +58,8 @@ fn try_reference_named_chapter_entity_given(
             .iter()
             .find(|(candidate_owner, _)| candidate_owner == &owner)
         {
-            Some((_, given)) => ChapterEntityGivenLookup::Resolved(given.clone()),
-            None => ChapterEntityGivenLookup::Pending {
+            Some((_, given)) => BluebookEntityGivenLookup::Resolved(given.clone()),
+            None => BluebookEntityGivenLookup::Pending {
                 description,
                 declared_by: Some(owner),
                 file: file.to_string(),
@@ -68,13 +68,13 @@ fn try_reference_named_chapter_entity_given(
         }
     } else {
         match candidates.as_slice() {
-            [] => ChapterEntityGivenLookup::Pending {
+            [] => BluebookEntityGivenLookup::Pending {
                 description,
                 declared_by: None,
                 file: file.to_string(),
                 line: line.number,
             },
-            [(_, given)] => ChapterEntityGivenLookup::Resolved(given.clone()),
+            [(_, given)] => BluebookEntityGivenLookup::Resolved(given.clone()),
             _ => {
                 let owners: Vec<&str> =
                     candidates.iter().map(|(owner, _)| owner.as_str()).collect();
@@ -82,7 +82,7 @@ fn try_reference_named_chapter_entity_given(
                     file,
                     line.number,
                     format!(
-                        "'{description}' is ambiguous across the chapter's own pieces — {} \
+                        "'{description}' is ambiguous across the bluebook's own pieces — {} \
                          each declare a DIFFERENT predicate under this same description; name \
                          which one with declared_by:",
                         owners.join(", ")
@@ -96,9 +96,9 @@ fn try_reference_named_chapter_entity_given(
     Ok(Some(resolved))
 }
 
-/// A bare chapter-entity-given left unresolved. `entity_path` indexes down through nested
+/// A bare bluebook-entity-given left unresolved. `entity_path` indexes down through nested
 /// entities; each enclosing level prepends its own index as the entry bubbles up.
-pub struct PendingChapterEntityGiven {
+pub struct PendingBluebookEntityGiven {
     pub entity_path: Vec<usize>,
     pub precondition_index: usize,
     pub description: String,
@@ -107,8 +107,8 @@ pub struct PendingChapterEntityGiven {
     pub line: usize,
 }
 
-/// A command's bare reference to a still-pending chapter-entity-given, resolved after every
-/// `PendingChapterEntityGiven` has patched its owning entity's `preconditions`.
+/// A command's bare reference to a still-pending bluebook-entity-given, resolved after every
+/// `PendingBluebookEntityGiven` has patched its owning entity's `preconditions`.
 pub struct PendingEntityCommandGiven {
     pub entity_path: Vec<usize>,
     pub command_index: usize,
@@ -152,13 +152,13 @@ pub fn parse_body(
     owner_value_objects: &mut Vec<ir::ValueObject>,
     identity_value_object_insert_at: &mut usize,
     entity_named_givens: &mut Vec<ir::Given>,
-    // `aggregate_name` keys chapter-wide givens as "Aggregate.Entity"; the pool is threaded
+    // `aggregate_name` keys bluebook-wide givens as "Aggregate.Entity"; the pool is threaded
     // unchanged through every nested piece.
     aggregate_name: &str,
-    chapter_entity_named_givens: &mut Vec<(String, ir::Given)>,
+    bluebook_entity_named_givens: &mut Vec<(String, ir::Given)>,
 ) -> ParseResult<(
     ir::Entity,
-    Vec<PendingChapterEntityGiven>,
+    Vec<PendingBluebookEntityGiven>,
     Vec<PendingEntityCommandGiven>,
 )> {
     let mut entity = ir::Entity {
@@ -166,7 +166,7 @@ pub fn parse_body(
         ..Default::default()
     };
     let mut pending_identity: Option<super::PendingIdentity> = None;
-    let mut pending_chapter_entity_givens: Vec<PendingChapterEntityGiven> = Vec::new();
+    let mut pending_bluebook_entity_givens: Vec<PendingBluebookEntityGiven> = Vec::new();
     let mut pending_entity_command_givens: Vec<PendingEntityCommandGiven> = Vec::new();
     // Bodies are queued and built after the walk so a nested command can resolve against
     // a sibling piece regardless of declaration order. (ADR 0026)
@@ -178,11 +178,14 @@ pub fn parse_body(
     loop {
         // Peeked before `next_line`: the grammar row still requires a block for `given`, so a
         // bare reference must be consumed here.
-        if let Some(outcome) =
-            try_reference_named_chapter_entity_given(file, lines, pos, chapter_entity_named_givens)?
-        {
+        if let Some(outcome) = try_reference_named_bluebook_entity_given(
+            file,
+            lines,
+            pos,
+            bluebook_entity_named_givens,
+        )? {
             match outcome {
-                ChapterEntityGivenLookup::Resolved(given) => {
+                BluebookEntityGivenLookup::Resolved(given) => {
                     entity.preconditions.push(given.clone());
                     if !entity_named_givens
                         .iter()
@@ -191,7 +194,7 @@ pub fn parse_body(
                         entity_named_givens.push(given);
                     }
                 }
-                ChapterEntityGivenLookup::Pending {
+                BluebookEntityGivenLookup::Pending {
                     description,
                     declared_by,
                     file,
@@ -204,7 +207,7 @@ pub fn parse_body(
                         description: Some(description.clone()),
                         canonical: String::new(),
                     });
-                    pending_chapter_entity_givens.push(PendingChapterEntityGiven {
+                    pending_bluebook_entity_givens.push(PendingBluebookEntityGiven {
                         entity_path: Vec::new(),
                         precondition_index,
                         description,
@@ -357,16 +360,16 @@ pub fn parse_body(
                 {
                     entity_named_givens.push(built.clone());
                 }
-                // Chapter-wide pool, keyed by "Aggregate.Entity" plus description.
+                // Bluebook-wide pool, keyed by "Aggregate.Entity" plus description.
                 let owner = format!("{aggregate_name}.{name}");
-                if !chapter_entity_named_givens
+                if !bluebook_entity_named_givens
                     .iter()
                     .any(|(candidate_owner, g)| {
                         candidate_owner == &owner
                             && g.description.as_deref() == Some(description.as_str())
                     })
                 {
-                    chapter_entity_named_givens.push((owner, built));
+                    bluebook_entity_named_givens.push((owner, built));
                 }
             }
             // Block required; no reference-by-name form, as no corpus case shares an invariant.
@@ -426,11 +429,11 @@ pub fn parse_body(
                     identity_value_object_insert_at,
                     entity_named_givens,
                     aggregate_name,
-                    chapter_entity_named_givens,
+                    bluebook_entity_named_givens,
                 )
             })?;
         nested_entities.push(built);
-        pending_chapter_entity_givens.extend(child_pending_given.into_iter().map(|mut entry| {
+        pending_bluebook_entity_givens.extend(child_pending_given.into_iter().map(|mut entry| {
             entry.entity_path.insert(0, nested_index);
             entry
         }));
@@ -531,7 +534,7 @@ pub fn parse_body(
 
     Ok((
         entity,
-        pending_chapter_entity_givens,
+        pending_bluebook_entity_givens,
         pending_entity_command_givens,
     ))
 }

data/rust/parser/src/parse/file.rs

@@ -49,7 +49,7 @@ pub fn header_name(call: &Call) -> Option<String> {
 /// The header's own optional `version:` named argument — `Hecks.bluebook
 /// "Banking", version: "v1" do`, `bluebook`'s own `named: "version"` row
 /// (`context: "File"`). Not exercised by pizzas.bluebook/the framework
-/// trio/the grammar chapters (none pins a version) — confirmed real by
+/// trio/the grammar bluebooks (none pins a version) — confirmed real by
 /// banking.bluebook, the first real corpus member to.
 pub fn header_version(call: &Call) -> Option<String> {
     ruby_value::split_items(&call.args)

data/rust/parser/src/parse/hecksagon.rs

@@ -15,7 +15,7 @@ pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
 /// Applies a `.hecksagon` body onto an already-built `ir::Bluebook`, attaching
 /// aggregate-scoped ports to the aggregates the sibling `.bluebook` registered.
 ///
-/// `gem_chapter_names` collects each `attaches "Name"` and
+/// `gem_bluebook_names` collects each `attaches "Name"` and
 /// `vendored_bluebook_names` each `attaches "name", from: :vendor`, in file order, for `hecks-parse resolve`; `ir.json` itself
 /// carries neither.
 ///
@@ -26,7 +26,7 @@ pub fn apply(
     lines: &[SourceLine],
     pos: &mut usize,
     bluebook: &mut ir::Bluebook,
-    gem_chapter_names: &mut Vec<String>,
+    gem_bluebook_names: &mut Vec<String>,
     vendored_bluebook_names: &mut Vec<String>,
     require_matching_aggregate: bool,
 ) -> ParseResult<()> {
@@ -67,6 +67,16 @@ pub fn apply(
                 call.word.as_str(),
                 "port" | "subscribe" | "attaches" | "translates" | "bounded" | "driven_by" | "end"
             ) {
+                if matches!(call.word.as_str(), "capabilities" | "concerns" | "annotate") {
+                    return Err(Diagnostic::new(
+                        file,
+                        line.number,
+                        format!(
+                            "`{}` is not a hecksagon word and nothing reads it; delete the line",
+                            call.word
+                        ),
+                    ));
+                }
                 let instead = match call.word.as_str() {
                     "uses_framework" => Some("attaches \"Name\""),
                     "uses_embryonaut_bluebook" => Some("attaches \"name\", from: :vendor"),
@@ -90,7 +100,7 @@ pub fn apply(
         match super::next_line(file, lines, pos, "Hecksagon")? {
             None => return Ok(()),
             Some(gated) => match gated.row.word {
-                // A bare root port belongs to the chapter, not an aggregate; validated, then
+                // A bare root port belongs to the bluebook, not an aggregate; validated, then
                 // discarded (`IR::Bluebook#to_h` has no `ports:` key).
                 "port" => {
                     let name =
@@ -111,7 +121,7 @@ pub fn apply(
                     bluebook.policies.push(built);
                 }
                 "subscribe" => {}
-                // One word for a chapter the gem carries and for a vendored package; a binding
+                // One word for a bluebook the gem carries and for a vendored package; a binding
                 // fact collected for `resolve`, absent from `ir.json`. Only `from: :vendor`
                 // is admitted as a source, and anything else is refused.
                 "attaches" => {
@@ -123,7 +133,7 @@ pub fn apply(
                         1,
                     )?;
                     match super::named_symbol(&gated.args, "from").as_deref() {
-                        None => gem_chapter_names.push(name),
+                        None => gem_bluebook_names.push(name),
                         Some("vendor") => vendored_bluebook_names.push(name),
                         Some(other) => {
                             return Err(Diagnostic::new(

data/rust/parser/src/parse/mod.rs

@@ -3,8 +3,9 @@
 
 pub mod adapter;
 pub mod aggregate;
-pub mod chapter;
+pub mod audience;
 pub mod command;
+pub mod declaration;
 pub mod domain_port;
 pub mod entity;
 pub mod file;
@@ -572,6 +573,12 @@ fn rocket_key_name(file: &str, word: &str, key_text: &str, line: usize) -> Parse
     Ok(rest.to_string())
 }
 
+/// A `pairs` row with neither a position nor a name: it admits every named argument the
+/// keyword's specific rows do not.
+fn is_open_pairs_row(row: &ArgumentRow) -> bool {
+    row.kind == "pairs" && row.at.is_empty() && row.named.is_empty()
+}
+
 fn validate_named(
     file: &str,
     word: &str,
@@ -581,6 +588,20 @@ fn validate_named(
     line: usize,
 ) -> ParseResult<()> {
     let candidates: Vec<&&ArgumentRow> = rows.iter().filter(|r| r.named == name).collect();
+    // An open `pairs` row (no position, no name) takes any key the specific rows leave over, as
+    // `provides` does for a capability its package declares; each value is text.
+    if candidates.is_empty() && rows.iter().any(|r| is_open_pairs_row(r)) {
+        let kind = classify_lexical_kind(value);
+        if kind == "text" {
+            return Ok(());
+        }
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!("'{word}'s '{name}:' ('{value}') reads as {kind}"),
+        )
+        .with_expected(vec!["text".to_string()]));
+    }
     if candidates.is_empty() {
         let expected: Vec<String> = rows
             .iter()
@@ -613,7 +634,7 @@ pub(crate) fn dispatch_stub(
     word: &str,
 ) -> Diagnostic {
     match inner_context {
-        "Bluebook" => chapter::not_implemented(file, line, word),
+        "Bluebook" => declaration::not_implemented(file, line, word),
         "Hecksagon" => hecksagon::not_implemented(file, line, word),
         "Aggregate" => aggregate::not_implemented(file, line, word),
         "Entity" => entity::not_implemented(file, line, word),
@@ -780,6 +801,24 @@ pub(crate) fn positional_symbol(
     })
 }
 
+/// A field name Ruby takes as a symbol or a string: `order_by :position`, `order_by "slug.value"`.
+pub(crate) fn positional_field_name(
+    file: &str,
+    line: usize,
+    word: &str,
+    args: &ArgumentGateResult,
+    at: usize,
+) -> ParseResult<String> {
+    if positional_raw(file, line, word, args, at)?
+        .trim()
+        .starts_with('"')
+    {
+        positional_text(file, line, word, args, at)
+    } else {
+        positional_symbol(file, line, word, args, at)
+    }
+}
+
 /// The name in a source symbol token: `:name` -> `name`, `:"a.b"` -> `a.b`.
 /// Not `ruby_value::read`, which reads rendered wire values rather than source syntax.
 fn symbol_text(raw: &str) -> Option<String> {
@@ -1182,6 +1221,50 @@ pub(crate) fn build_attribute(
     ))
 }
 
+/// Reads `reference_to one_of(A, B), as: :subject` into its tagged-reference shapes (ADR 0127),
+/// refusing a union with no `as:` or fewer than two distinct aggregates, as Ruby does.
+pub(crate) fn one_of_reference(
+    file: &str,
+    line: usize,
+    aggregate: &str,
+    raw: &str,
+    args: &ArgumentGateResult,
+) -> ParseResult<crate::build::references::OneOfReference> {
+    let inner = raw
+        .find('(')
+        .map_or("", |open| &raw[open + 1..raw.len() - 1]);
+    let variants: Vec<String> = ruby_value::split_items(inner)
+        .into_iter()
+        .map(|segment| crate::build::naming::demodulise(segment.trim()))
+        .collect();
+    let listed = variants.join(", ");
+    let Some(as_name) = named_symbol(args, "as") else {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{aggregate}'s reference_to one_of({listed}) needs as: — a union has no one name"
+            ),
+        ));
+    };
+    let mut distinct = variants.clone();
+    distinct.sort();
+    distinct.dedup();
+    if variants.len() < 2 || distinct.len() != variants.len() {
+        return Err(Diagnostic::new(
+            file,
+            line,
+            format!("{aggregate}.{as_name}'s one_of names {listed} — a union names two or more distinct aggregates"),
+        ));
+    }
+    Ok(crate::build::references::one_of_reference(
+        aggregate,
+        &variants,
+        &as_name,
+        named_flag(args, "optional"),
+    ))
+}
+
 /// Resolves an attribute's type: a bare constant, `list_of(T)`, or an inline `one_of(...)`.
 ///
 /// `list_of` unwraps to `(inner, true)`. `one_of` synthesizes a closed-set value object named

data/rust/parser/src/parse/process_manager.rs

@@ -31,10 +31,12 @@ pub fn parse_body(
         let line = gated.line.number;
 
         match gated.row.word {
-            // A dotted symbol (`:"reference.value"`), which only `positional_symbol` can spell.
+            // A dotted symbol (`:"reference.value"`), or a bare aggregate name (`Message`), which
+            // `build::correlation_keys` resolves once every aggregate is known.
             "correlates_by" => {
-                pm.correlates_by =
-                    super::positional_symbol(file, line, "correlates_by", &gated.args, 1)?;
+                let raw =
+                    super::positional_raw(file, line, "correlates_by", &gated.args, 1)?.trim();
+                pm.correlates_by = super::symbol_text(raw).unwrap_or_else(|| raw.to_string());
             }
             // Event references keep only the bare final segment (`Naming.event_name_ref`);
             // `SagaInterpreter` matches them against a bare `event.name`.
@@ -48,13 +50,18 @@ pub fn parse_body(
                 )?);
             }
             "ends_on" => {
-                pm.ends_on = Some(super::positional_event_name_ref(
-                    file,
-                    line,
-                    "ends_on",
-                    &gated.args,
-                    1,
-                )?);
+                // A process manager can end on several events: `ends_on` is the first, as the
+                // Ruby builder's `ends_on` reads `endings.first`.
+                let event =
+                    super::positional_event_name_ref(file, line, "ends_on", &gated.args, 1)?;
+                pm.ends_on.get_or_insert_with(|| event.clone());
+                pm.endings.push(event);
+            }
+            // Each `resumes` is one `stage=command` entry, kept in declaration order; the
+            // runtime does not read the stage map yet.
+            "resumes" => {
+                let entry = super::positional_text(file, line, "resumes", &gated.args, 1)?;
+                pm.resumes.push(entry);
             }
             "transition" => {
                 for handler in parse_transition(file, lines, pos, line, &gated)? {
@@ -94,7 +101,7 @@ pub fn parse_body(
 
 /// Every state named by a handler's `from_state` or `to_state`, in first-seen order.
 /// Order matters: `begin_saga` starts a fresh instance in `pm.states.first`.
-fn derived_states(handlers: &[ir::ProcessManagerHandler]) -> Vec<String> {
+pub(crate) fn derived_states(handlers: &[ir::ProcessManagerHandler]) -> Vec<String> {
     let mut states = Vec::new();
     for handler in handlers {
         for state in [&handler.from_state, &handler.to_state] {

data/rust/parser/src/parse/query.rs

@@ -1,6 +1,6 @@
-//! The `Query` construct: `where`, `order_by`, `limit` and the open-map option words.
+//! The `Query` construct: `reference_to`, `where`, `order_by`, `limit` and the open-map option words.
 
-use crate::build::{query_derive, query_options};
+use crate::build::{naming, query_derive, query_options, references};
 use crate::diag::{Diagnostic, ParseResult};
 use crate::ir;
 use crate::lex::SourceLine;
@@ -44,6 +44,16 @@ pub fn parse_body(
             "attribute" => query
                 .attributes
                 .push(super::build_attribute(file, line, "attribute", &gated.args)?.0),
+            // A query has no root of its own, so a reference is always a parameter, as in Ruby.
+            "reference_to" => {
+                let target_raw =
+                    super::positional_constant(file, line, "reference_to", &gated.args, 1)?;
+                query.attributes.push(references::reference_attribute(
+                    &naming::demodulise(target_raw),
+                    super::named_symbol(&gated.args, "as").as_deref(),
+                    super::named_flag(&gated.args, "optional"),
+                ));
+            }
             "where" => {
                 query_derive::refuse_on_target(file, line, "where", &gated.args.named)?;
                 query
@@ -52,7 +62,7 @@ pub fn parse_body(
             }
             "order_by" => {
                 // The gate already refuses an undeclared `on:`; only `where` needs a check.
-                let field = super::positional_symbol(file, line, "order_by", &gated.args, 1)?;
+                let field = super::positional_field_name(file, line, "order_by", &gated.args, 1)?;
                 let direction = match gated.args.positional.iter().find(|(idx, _)| *idx == 2) {
                     Some((_, text)) => text.trim().trim_start_matches(':').to_string(),
                     None => "asc".to_string(),

data/rust/parser/src/parse/read_model.rs

@@ -178,7 +178,8 @@ pub fn parse_body(
                 wheres.extend(query_derive::where_clauses(&field_pairs, target.as_deref()));
             }
             "order_by" => {
-                let field = super::positional_symbol(file, last_line, "order_by", &gated.args, 1)?;
+                let field =
+                    super::positional_field_name(file, last_line, "order_by", &gated.args, 1)?;
                 let direction = match gated.args.positional.iter().find(|(idx, _)| *idx == 2) {
                     Some((_, text)) => text.trim().trim_start_matches(':').to_string(),
                     None => "asc".to_string(),

data/rust/parser/src/parse/world.rs

@@ -202,7 +202,8 @@ fn default_database_set(file: &str, line: usize, call: &lex::Call) -> ParseResul
     Ok(true)
 }
 
-/// One binding call: `verb("Adapter") do ... end`, or `verb "Adapter", k: v, ...` with no block.
+/// One binding call: `verb("Adapter") do ... end`, or `verb "Adapter", k: v, ...` with no block;
+/// the adapter may be left out when keyword settings are given.
 /// Records the verb, the first positional string, the keyword names, then the body's top-level
 /// keys. A verb that is a grammar word elsewhere is refused, as Ruby's word gate refuses it.
 fn parse_binding(
@@ -256,13 +257,6 @@ fn parse_binding(
             ));
         }
     }
-    let adapter = adapter.ok_or_else(|| {
-        Diagnostic::new(
-            file,
-            number,
-            format!("'{}' needs a quoted adapter name", call.word),
-        )
-    })?;
     match call.opener {
         Opener::None => {}
         Opener::DoBlock { .. } => body_keys(file, lines, pos, &mut settings)?,
@@ -274,6 +268,16 @@ fn parse_binding(
             ))
         }
     }
+    // A verb that names no adapter but gives settings (`stored_as Revision: "commit"`,
+    // `minting commands: [...]`) binds under the empty adapter, as Ruby's world builder does.
+    let adapter = adapter.or_else(|| (!settings.is_empty()).then(String::new));
+    let adapter = adapter.ok_or_else(|| {
+        Diagnostic::new(
+            file,
+            number,
+            format!("'{}' needs a quoted adapter name", call.word),
+        )
+    })?;
     Ok(ir::Binding {
         verb: call.word.clone(),
         adapter,