hecks 5.0.0 → 6.0.0

data/rust/parser/src/parse/{chapter.rs → declaration.rs}

@@ -1,4 +1,4 @@
-//! The `Bluebook` construct and the driver for `hecks-parse chapter`.
+//! The `Bluebook` construct and the driver for `hecks-parse bluebook`.
 //! Parses each `.bluebook` file into one `ir::Bluebook`, then applies `.hecksagon` files onto it.
 
 use super::{aggregate, command, entity, policy, process_manager, read_model};
@@ -10,29 +10,60 @@ pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
     Diagnostic::not_yet_implemented(file, line, format!("Bluebook.{word}"))
 }
 
-/// Parses one chapter across one or more `.bluebook` files plus any `.hecksagon` files.
+/// Parses one bluebook across one or more `.bluebook` files plus any `.hecksagon` files.
 /// Stops at the first diagnostic, whichever file it comes from.
-pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseResult<ir::Bluebook> {
+pub fn parse_bluebook(
+    declaration_name: &str,
+    files: &[(String, String)],
+) -> ParseResult<ir::Bluebook> {
     if files.is_empty() {
         return Err(Diagnostic::new(
             "<none>",
             0,
-            "hecks-parse chapter requires at least one file",
+            "hecks-parse bluebook requires at least one file",
         ));
     }
 
+    // A bluebook written as sentences is read by the sentence front end; the Ruby-shaped grammar
+    // below never sees it. The two forms do not mix inside one bluebook.
+    let sentence_files: Vec<&(String, String)> = files
+        .iter()
+        .filter(|(_, source)| crate::sentence::is_sentence_form(source))
+        .collect();
+    if !sentence_files.is_empty() {
+        if let Some((path, _)) = files.iter().find(|(path, source)| {
+            path.ends_with(".bluebook") && !crate::sentence::is_sentence_form(source)
+        }) {
+            return Err(Diagnostic::new(
+                path,
+                1,
+                "this bluebook is written as sentences elsewhere, so every .bluebook file of it must be; \
+                 this one is written in the Ruby form",
+            ));
+        }
+        if let Some((path, _)) = files.iter().find(|(path, _)| path.ends_with(".hecksagon")) {
+            return Err(Diagnostic::not_yet_implemented(
+                path,
+                1,
+                "a .hecksagon beside a bluebook written as sentences",
+            ));
+        }
+        let owned: Vec<(String, String)> = sentence_files.into_iter().cloned().collect();
+        return crate::sentence::parse_bluebook(declaration_name, &owned);
+    }
+
     let mut bluebook: Option<ir::Bluebook> = None;
     let mut aggregate_policies: Vec<ir::Policy> = Vec::new();
-    let mut chapter_policies: Vec<ir::Policy> = Vec::new();
-    let mut chapter_named_givens: Vec<(String, ir::Given)> = Vec::new();
-    // Bare chapter-givens deferred until every file has loaded.
-    let mut pending_chapter_givens: Vec<(usize, aggregate::PendingChapterGiven)> = Vec::new();
-    // A command's bare reference to a deferred chapter-given, resolved after the aggregate pass.
+    let mut bluebook_policies: Vec<ir::Policy> = Vec::new();
+    let mut bluebook_named_givens: Vec<(String, ir::Given)> = Vec::new();
+    // Bare bluebook-givens deferred until every file has loaded.
+    let mut pending_bluebook_givens: Vec<(usize, aggregate::PendingBluebookGiven)> = Vec::new();
+    // A command's bare reference to a deferred bluebook-given, resolved after the aggregate pass.
     let mut pending_command_givens: Vec<(usize, usize, command::PendingCommandGiven)> = Vec::new();
-    // Chapter-wide pool of entity-scoped givens.
-    let mut chapter_entity_named_givens: Vec<(String, ir::Given)> = Vec::new();
+    // Bluebook-wide pool of entity-scoped givens.
+    let mut bluebook_entity_named_givens: Vec<(String, ir::Given)> = Vec::new();
     // Bare entity-given references deferred until every file has loaded.
-    let mut pending_chapter_entity_givens: Vec<(usize, entity::PendingChapterEntityGiven)> =
+    let mut pending_bluebook_entity_givens: Vec<(usize, entity::PendingBluebookEntityGiven)> =
         Vec::new();
     // Entity-owned commands referencing a deferred entity-given; resolved after the entity pass.
     let mut pending_entity_command_givens: Vec<(usize, entity::PendingEntityCommandGiven)> =
@@ -46,11 +77,11 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
         let (row, call, header_line) = super::file::parse_header(path, &lines, &mut pos)?;
 
         if let Some(declared_name) = super::file::header_name(&call) {
-            if row.inner == "Bluebook" && declared_name != chapter_name {
+            if row.inner == "Bluebook" && declared_name != declaration_name {
                 return Err(Diagnostic::new(
                     path,
                     header_line,
-                    format!("--chapter {chapter_name} was requested, but this file declares '{declared_name}'"),
+                    format!("--bluebook {declaration_name} was requested, but this file declares '{declared_name}'"),
                 ));
             }
         }
@@ -59,7 +90,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
             "Bluebook" => {
                 let declared_version = super::file::header_version(&call);
                 let target = bluebook.get_or_insert_with(|| ir::Bluebook {
-                    name: chapter_name.to_string(),
+                    name: declaration_name.to_string(),
                     version: declared_version.clone(),
                     ..Default::default()
                 });
@@ -69,7 +100,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                             return Err(Diagnostic::new(
                                 path,
                                 header_line,
-                                format!("{chapter_name} declares both version {existing:?} and {version:?}"),
+                                format!("{declaration_name} declares both version {existing:?} and {version:?}"),
                             ));
                         }
                         None => target.version = Some(version),
@@ -82,12 +113,12 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                     &mut pos,
                     target,
                     &mut aggregate_policies,
-                    &mut chapter_policies,
-                    &mut chapter_named_givens,
-                    &mut pending_chapter_givens,
+                    &mut bluebook_policies,
+                    &mut bluebook_named_givens,
+                    &mut pending_bluebook_givens,
                     &mut pending_command_givens,
-                    &mut chapter_entity_named_givens,
-                    &mut pending_chapter_entity_givens,
+                    &mut bluebook_entity_named_givens,
+                    &mut pending_bluebook_entity_givens,
                     &mut pending_entity_command_givens,
                 )?;
             }
@@ -97,7 +128,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                 return Err(Diagnostic::new(
                     path,
                     header_line,
-                    format!("hecks-parse chapter reads .bluebook/.hecksagon files ('bluebook'/'hecksagon'); got '{}' (inner context '{other}')", call.word),
+                    format!("hecks-parse bluebook reads .bluebook/.hecksagon files ('bluebook'/'hecksagon'); got '{}' (inner context '{other}')", call.word),
                 ));
             }
         }
@@ -107,21 +138,21 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
         Diagnostic::new(
             "<none>",
             0,
-            format!("no .bluebook file given for chapter '{chapter_name}'"),
+            format!("no .bluebook file given for bluebook '{declaration_name}'"),
         )
     })?;
 
-    // Aggregate policies first, then chapter-level ones, as `BluebookBuilder#build` orders them.
+    // Aggregate policies first, then bluebook-level ones, as `BluebookBuilder#build` orders them.
     bluebook.policies = aggregate_policies;
-    bluebook.policies.extend(chapter_policies);
+    bluebook.policies.extend(bluebook_policies);
 
     // Reference-hop query tails resolve only once the whole aggregate graph exists.
     crate::build::query_inference::apply(&files[0].0, &mut bluebook)?;
 
-    // Resolves deferred chapter-given references now that every file's declarations are known.
+    // Resolves deferred bluebook-given references now that every file's declarations are known.
     // Patches by index; a command's own copy is resolved in the next pass.
-    for (aggregate_index, pending) in pending_chapter_givens {
-        let candidates: Vec<&(String, ir::Given)> = chapter_named_givens
+    for (aggregate_index, pending) in pending_bluebook_givens {
+        let candidates: Vec<&(String, ir::Given)> = bluebook_named_givens
             .iter()
             .filter(|(_, given)| given.description.as_deref() == Some(pending.description.as_str()))
             .collect();
@@ -136,7 +167,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                         &pending.file,
                         pending.line,
                         format!(
-                            "'{}' names no precondition {owner} declares in this chapter — {owner} \
+                            "'{}' names no precondition {owner} declares in this bluebook — {owner} \
                              either hasn't declared '{}', or declared_by: named the wrong aggregate",
                             pending.description, pending.description
                         ),
@@ -149,7 +180,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                         &pending.file,
                         pending.line,
                         format!(
-                        "'{}' names no precondition any aggregate in this chapter ever declares \
+                        "'{}' names no precondition any aggregate in this bluebook ever declares \
                              — declare it once with a block",
                         pending.description
                     ),
@@ -163,7 +194,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                         &pending.file,
                         pending.line,
                         format!(
-                            "'{}' is ambiguous in this chapter — {} each declare a DIFFERENT \
+                            "'{}' is ambiguous in this bluebook — {} each declare a DIFFERENT \
                              predicate under this same description; name which one with declared_by:",
                             pending.description,
                             owners.join(", ")
@@ -185,8 +216,8 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
     }
 
     // Entity-scoped analogue of the pass above; `entity_at_path_mut` finds the nested entity.
-    for (aggregate_index, pending) in pending_chapter_entity_givens {
-        let candidates: Vec<&(String, ir::Given)> = chapter_entity_named_givens
+    for (aggregate_index, pending) in pending_bluebook_entity_givens {
+        let candidates: Vec<&(String, ir::Given)> = bluebook_entity_named_givens
             .iter()
             .filter(|(_, given)| given.description.as_deref() == Some(pending.description.as_str()))
             .collect();
@@ -201,7 +232,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                         &pending.file,
                         pending.line,
                         format!(
-                            "'{}' names no precondition {owner} declares in this chapter — {owner} \
+                            "'{}' names no precondition {owner} declares in this bluebook — {owner} \
                              either hasn't declared '{}', or declared_by: named the wrong piece",
                             pending.description, pending.description
                         ),
@@ -214,7 +245,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                         &pending.file,
                         pending.line,
                         format!(
-                            "'{}' names no precondition any piece in this chapter ever declares \
+                            "'{}' names no precondition any piece in this bluebook ever declares \
                              — declare it once with a block",
                             pending.description
                         ),
@@ -228,7 +259,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                         &pending.file,
                         pending.line,
                         format!(
-                            "'{}' is ambiguous across the chapter's own pieces — {} each declare \
+                            "'{}' is ambiguous across the bluebook's own pieces — {} each declare \
                              a DIFFERENT predicate under this same description; name which one \
                              with declared_by:",
                             pending.description,
@@ -273,7 +304,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
             }
 
             let declared_name = super::file::header_name(&call);
-            if declared_name.as_deref() == Some(chapter_name) {
+            if declared_name.as_deref() == Some(declaration_name) {
                 super::hecksagon::apply(
                     path,
                     &lines,
@@ -284,7 +315,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
                     true,
                 )?;
             } else {
-                // Sibling block for another chapter: gated so syntax errors refuse; then dropped.
+                // Sibling block for another bluebook: gated so syntax errors refuse; then dropped.
                 let mut discarded = ir::Bluebook::default();
                 super::hecksagon::apply(
                     path,
@@ -302,10 +333,10 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
     Ok(bluebook)
 }
 
-/// Lists the chapters `<Name>`'s block pulls in via `attaches` (or its deprecated spellings).
+/// Lists the bluebooks `<Name>`'s block pulls in via `attaches` (or its deprecated spellings).
 /// Every block is still gated; the IR accumulator is a throwaway.
 pub fn resolve_hecksagon_dependencies(
-    chapter_name: &str,
+    declaration_name: &str,
     path: &str,
     source: &str,
 ) -> ParseResult<(Vec<String>, Vec<String>)> {
@@ -330,7 +361,7 @@ pub fn resolve_hecksagon_dependencies(
         }
 
         let declared_name = super::file::header_name(&call);
-        if declared_name.as_deref() == Some(chapter_name) {
+        if declared_name.as_deref() == Some(declaration_name) {
             found = true;
             let mut discarded = ir::Bluebook::default();
             super::hecksagon::apply(
@@ -360,7 +391,7 @@ pub fn resolve_hecksagon_dependencies(
         return Err(Diagnostic::new(
             path,
             0,
-            format!("no 'Hecks.hecksagon \"{chapter_name}\"' block found in {path}"),
+            format!("no 'Hecks.hecksagon \"{declaration_name}\"' block found in {path}"),
         ));
     }
 
@@ -368,7 +399,7 @@ pub fn resolve_hecksagon_dependencies(
 }
 
 /// Parses a `Hecks.bluebook "Name" do ... end` body into an existing accumulator.
-/// Policies bubble as in `BluebookBuilder#build`: aggregate policies first, then chapter-level.
+/// Policies bubble as in `BluebookBuilder#build`: aggregate policies first, then bluebook-level.
 #[allow(clippy::too_many_arguments)] // established signature
 fn parse_body_into(
     file: &str,
@@ -376,15 +407,15 @@ fn parse_body_into(
     pos: &mut usize,
     bluebook: &mut ir::Bluebook,
     aggregate_policies: &mut Vec<ir::Policy>,
-    chapter_policies: &mut Vec<ir::Policy>,
-    chapter_named_givens: &mut Vec<(String, ir::Given)>,
-    pending_chapter_givens: &mut Vec<(usize, aggregate::PendingChapterGiven)>,
+    bluebook_policies: &mut Vec<ir::Policy>,
+    bluebook_named_givens: &mut Vec<(String, ir::Given)>,
+    pending_bluebook_givens: &mut Vec<(usize, aggregate::PendingBluebookGiven)>,
     pending_command_givens: &mut Vec<(usize, usize, command::PendingCommandGiven)>,
-    chapter_entity_named_givens: &mut Vec<(String, ir::Given)>,
-    pending_chapter_entity_givens: &mut Vec<(usize, entity::PendingChapterEntityGiven)>,
+    bluebook_entity_named_givens: &mut Vec<(String, ir::Given)>,
+    pending_bluebook_entity_givens: &mut Vec<(usize, entity::PendingBluebookEntityGiven)>,
     pending_entity_command_givens: &mut Vec<(usize, entity::PendingEntityCommandGiven)>,
 ) -> ParseResult<()> {
-    // The given pool spans the whole chapter, not one file: a later concept file may reference
+    // The given pool spans the whole bluebook, not one file: a later concept file may reference
     // a named given an earlier one declared. Entries are (owner aggregate name, `Given`).
     while let Some(gated) = super::next_line(file, lines, pos, "Bluebook")? {
         let line = gated.line.number;
@@ -459,20 +490,20 @@ fn parse_body_into(
                     lines,
                     pos,
                     &agg_name,
-                    chapter_named_givens,
-                    chapter_entity_named_givens,
+                    bluebook_named_givens,
+                    bluebook_entity_named_givens,
                 )?;
                 let aggregate_index = bluebook.aggregates.len();
                 bluebook.aggregates.push(built);
                 aggregate_policies.extend(policies);
-                pending_chapter_givens
+                pending_bluebook_givens
                     .extend(pending.into_iter().map(|entry| (aggregate_index, entry)));
                 pending_command_givens.extend(
                     command_pending
                         .into_iter()
                         .map(|(command_index, entry)| (aggregate_index, command_index, entry)),
                 );
-                pending_chapter_entity_givens.extend(
+                pending_bluebook_entity_givens.extend(
                     entity_given_pending
                         .into_iter()
                         .map(|entry| (aggregate_index, entry)),
@@ -485,7 +516,7 @@ fn parse_body_into(
             }
             "policy" => {
                 let pol_name = super::positional_text(file, line, "policy", &gated.args, 1)?;
-                chapter_policies.push(policy::parse_body(file, lines, pos, &pol_name)?);
+                bluebook_policies.push(policy::parse_body(file, lines, pos, &pol_name)?);
             }
             "read_model" => {
                 let rm_name = super::positional_text(file, line, "read_model", &gated.args, 1)?;

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

@@ -11,8 +11,8 @@ pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
     Diagnostic::not_yet_implemented(file, line, format!("DomainPort.{word}"))
 }
 
-/// Parses a `port "Name" do ... end` body: `operation` entries only.
-/// Any other word, including `verb`, falls through to `not_built_yet`.
+/// Parses a `port "Name" do ... end` body: `operation`/`tells` (inbound) and `asks` (outbound)
+/// entries. Any other word, including `verb`, falls through to `not_built_yet`.
 pub fn parse_body(
     file: &str,
     lines: &[SourceLine],
@@ -32,11 +32,12 @@ pub fn parse_body(
         let line = gated.line.number;
 
         match gated.row.word {
-            "operation" => {
-                let op_name = super::positional_text(file, line, "operation", &gated.args, 1)?;
+            word @ ("operation" | "tells" | "asks") => {
+                let op_name = super::positional_text(file, line, word, &gated.args, 1)?;
                 let to = super::named_constant(&gated.args, "to").map(naming::demodulise);
-                port.operations
-                    .push(parse_operation_body(file, lines, pos, &op_name, to)?);
+                let operation =
+                    parse_operation_body(file, lines, pos, &op_name, to, word == "asks")?;
+                port.operations.push(operation);
             }
             _ => {
                 return Err(super::not_built_yet(
@@ -58,11 +59,15 @@ fn parse_operation_body(
     pos: &mut usize,
     name: &str,
     to: Option<String>,
+    outbound: bool,
 ) -> ParseResult<ir::PortOperation> {
     let mut operation = ir::PortOperation {
         name: name.to_string(),
         attributes: Vec::new(),
         emits: Vec::new(),
+        outbound,
+        answers: None,
+        refuses: None,
         to,
     };
 
@@ -84,6 +89,24 @@ fn parse_operation_body(
                     .emits
                     .push(super::positional_text(file, line, "emits", &gated.args, 1)?);
             }
+            "answers" => {
+                operation.answers = Some(super::positional_text(
+                    file,
+                    line,
+                    "answers",
+                    &gated.args,
+                    1,
+                )?);
+            }
+            "refuses" => {
+                operation.refuses = Some(super::positional_text(
+                    file,
+                    line,
+                    "refuses",
+                    &gated.args,
+                    1,
+                )?);
+            }
             "reference_to" => {
                 let target_raw =
                     super::positional_constant(file, line, "reference_to", &gated.args, 1)?;
@@ -113,11 +136,39 @@ fn pos_line(lines: &[SourceLine], pos: usize) -> usize {
     lines.get(pos.saturating_sub(1)).map_or(0, |l| l.number)
 }
 
-/// An inbound operation must emit something. The receiver comes from the routing envelope,
-/// so it is not validated as an attribute.
+/// An inbound operation must emit something and name no return channel; an outbound one names
+/// both endings and emits nothing, as `PortOperationBuilder#build` refuses. The receiver comes
+/// from the routing envelope, so it is not validated as an attribute.
 fn validate_operation(file: &str, line: usize, operation: &ir::PortOperation) -> ParseResult<()> {
+    let name = &operation.name;
+    if operation.outbound {
+        return validate_outbound(file, line, operation);
+    }
     if operation.emits.is_empty() {
-        return Err(Diagnostic::new(file, line, format!("'{}' declares no emits — an operation with nothing to say afterward is a call into nothing", operation.name)));
+        return Err(Diagnostic::new(file, line, format!("'{name}' declares no emits — an operation with nothing to say afterward is a call into nothing")));
+    }
+    if operation.answers.is_some() || operation.refuses.is_some() {
+        let word = if operation.answers.is_some() {
+            "answers"
+        } else {
+            "refuses"
+        };
+        return Err(Diagnostic::new(file, line, format!("{name} is a tells and declares {word} — an inbound fact has no channel back to whoever sent it")));
+    }
+
+    Ok(())
+}
+
+fn validate_outbound(file: &str, line: usize, operation: &ir::PortOperation) -> ParseResult<()> {
+    let name = &operation.name;
+    if !operation.emits.is_empty() {
+        return Err(Diagnostic::new(file, line, format!("{name} is an asks and declares emits — name its two endings with answers and refuses instead")));
+    }
+    if operation.answers.is_none() {
+        return Err(Diagnostic::new(file, line, format!("{name} declares no answers — an ask with no word for what came back cannot be reacted to")));
+    }
+    if operation.refuses.is_none() {
+        return Err(Diagnostic::new(file, line, format!("{name} declares no refuses — an ask that cannot fail is a call into a system you do not control, pretending otherwise")));
     }
 
     Ok(())

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)