refactor(compass): align impl vocabulary with the refined ontology

- Rename predecessor → parent across src and tests (helper fns, error strings,
  doc-comments, test names). The JSON already emitted `parents`; this closes the
  gap between the code's internal words and what it produces.
- Rename receipt_json → commit_result_json: the output has no `receipt` key, and
  the ontology no longer defines Receipt — the returned value is the Plan Version.
- Rewrite the readiness "On gates" note: the spec no longer says "dependencies
  and gates"; the ontology states the acceptance predicate *is* the gate.

Frozen example modules under catalog/plans/*/versions/*.ts are untouched — they
keep their period vocabulary, and the acceptance hash oracle
(example_filenames_reproduce_from_source_bytes) confirms none drifted.

cargo test: 15 passed. clippy + fmt clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: schickling-assistant

context/.decisions/0001-compass-is-an-independent-authority.md

@@ -23,9 +23,10 @@ not planning. Every later question — where plans live, how they replicate, wha
 happens when the bus changes shape — inherits that coupling, and none of them
 can be answered on planning's own terms.
 
-Defining opaque references, an idempotent port, and stable receipts before the
-first authoritative write costs boundary work now and avoids an identity
-migration later. Because no live plan state exists, that cost is at its minimum.
+Defining opaque references, an idempotent write path, and stable version
+identities before the first authoritative write costs boundary work now and
+avoids an identity migration later. Because no live plan state exists, that cost
+is at its minimum.
 
 ## Options
 

src/catalog.rs

@@ -15,10 +15,10 @@
 //! an error, never a warning.
 //!
 //! The identity is the hash of the raw bytes as they sit on disk. Because each
-//! version imports its predecessors by filename, and each filename carries a
+//! version imports its parents by filename, and each filename carries a
 //! hash of content, the lineage is walkable from the bytes alone: the parents of
 //! a version are the versions whose hash-prefix appears in its import
-//! specifiers. A prefix that resolves to no local file is a missing predecessor
+//! specifiers. A prefix that resolves to no local file is a missing parent
 //! (an orphan), repaired by waiting.
 
 use crate::event::Event;
@@ -34,9 +34,9 @@ pub struct Admitted {
     pub hash: String,
     pub path: PathBuf,
     pub plan: String,
-    /// A reading aid: one past the longest predecessor. Never a key.
+    /// A reading aid: one past the longest parent. Never a key.
     pub seq: u64,
-    /// Predecessor references: a full hash when the predecessor is present, or
+    /// Parent references: a full hash when the parent is present, or
     /// the raw 12-hex prefix when it has not arrived (an orphan edge).
     pub parents: Vec<String>,
 }
@@ -186,7 +186,7 @@ pub fn load_plan(root: &Path, plan: &str) -> Result<PlanStore, String> {
         }
     }
 
-    // Resolve import-prefixes to full predecessor hashes among the siblings.
+    // Resolve import-prefixes to full parent hashes among the siblings.
     let by_prefix: std::collections::HashMap<&str, &str> = raws
         .iter()
         .map(|r| (&r.hash[..crate::model::HASH_PREFIX_LEN], r.hash.as_str()))
@@ -290,7 +290,7 @@ fn admit_version(path: &Path, expected_plan: &str) -> Result<Raw, String> {
     }
 
     let source = std::str::from_utf8(&bytes).map_err(|e| format!("not valid UTF-8: {e}"))?;
-    let import_prefixes = predecessor_prefixes(source, path, expected_plan)?;
+    let import_prefixes = parent_prefixes(source, path, expected_plan)?;
 
     Ok(Raw {
         hash: actual,
@@ -301,23 +301,19 @@ fn admit_version(path: &Path, expected_plan: &str) -> Result<Raw, String> {
     })
 }
 
-/// The hash-prefixes of the *predecessor* version files a module imports, read
-/// statically. A predecessor is a version of the SAME plan; a version of another
+/// The hash-prefixes of the *parent* version files a module imports, read
+/// statically. A parent is a version of the SAME plan; a version of another
 /// plan is a cross-plan reference (CMP.API-R05), not a parent, and is excluded
-/// from the lineage so it never shows as an orphan predecessor edge.
-fn predecessor_prefixes(
-    source: &str,
-    path: &Path,
-    expected_plan: &str,
-) -> Result<Vec<String>, String> {
+/// from the lineage so it never shows as an orphan parent edge.
+fn parent_prefixes(source: &str, path: &Path, expected_plan: &str) -> Result<Vec<String>, String> {
     let specs = crate::eval::import_specifiers(source, path)
         .map_err(|e| format!("cannot read imports: {}", e.message()))?;
     let mut out = Vec::new();
     for spec in specs {
-        // A predecessor import is a relative path to a version file.
+        // A parent import is a relative path to a version file.
         let file = spec.rsplit('/').next().unwrap_or(&spec);
         if let Some((_seq, prefix)) = parse_filename(file) {
-            // Only a same-plan version is a predecessor. A cross-plan reference
+            // Only a same-plan version is a parent. A cross-plan reference
             // (target plan differs) is not part of this plan's lineage.
             match crate::eval::import_target_plan(path, &spec) {
                 Some(other) if other != expected_plan => continue,
@@ -335,8 +331,8 @@ fn predecessor_prefixes(
 /// rejected — never reinterpreted into the Plan it was filed under — on the same
 /// terms as a version whose content hash disagrees with its own filename.
 ///
-/// The origin is derived by walking resolved predecessor pointers within the
-/// store (no evaluation, no extra IO) to the predecessor-less ancestor. When the
+/// The origin is derived by walking resolved parent pointers within the
+/// store (no evaluation, no extra IO) to the parent-less ancestor. When the
 /// walk reaches an ancestor that is absent locally the version is an orphan, not
 /// a misfiling: its Plan cannot yet be confirmed, so it is left alone.
 fn reject_misfiled(store: &mut PlanStore, plan: &str) {
@@ -388,27 +384,27 @@ fn reject_misfiled(store: &mut PlanStore, plan: &str) {
 /// Derive a version's PlanId from its authored bytes (decision 0017).
 ///
 /// A Plan's identity is the content hash of its origin — the single
-/// predecessor-less version. An origin (a module that imports no predecessor) is
+/// parent-less version. An origin (a module that imports no parent) is
 /// its own PlanId: the hash of its bytes, the same hash its version filename
-/// carries. A revision inherits its Plan from its predecessor: its origin is
-/// found by walking the predecessor imports back to the predecessor-less version,
+/// carries. A revision inherits its Plan from its parent: its origin is
+/// found by walking the parent imports back to the parent-less version,
 /// and hashing that. The operator names nothing; identity is derived, and the
 /// prefix width matches the version filenames' for consistency.
 pub fn derive_planid(path: &Path, source: &[u8]) -> Result<String, String> {
     let src = std::str::from_utf8(source)
         .map_err(|e| format!("{}: not valid UTF-8: {e}", path.display()))?;
-    let origin_bytes = match sibling_predecessor_paths(path, src)?.into_iter().next() {
+    let origin_bytes = match sibling_parent_paths(path, src)?.into_iter().next() {
         None => source.to_vec(),
         Some(pred) => walk_to_origin(&pred)?,
     };
     Ok(crate::sha256::sha256_hex(&origin_bytes)[..crate::model::HASH_PREFIX_LEN].to_string())
 }
 
-/// The resolved paths of the *predecessor* version files a module imports — the
+/// The resolved paths of the *parent* version files a module imports — the
 /// same-plan siblings, sitting in the importer's own directory. A cross-plan
-/// reference resolves elsewhere and is not a predecessor, so it is excluded, as
+/// reference resolves elsewhere and is not a parent, so it is excluded, as
 /// is the `compass` prelude (which is not a version reference).
-fn sibling_predecessor_paths(path: &Path, source: &str) -> Result<Vec<PathBuf>, String> {
+fn sibling_parent_paths(path: &Path, source: &str) -> Result<Vec<PathBuf>, String> {
     let dir = path.parent().unwrap_or_else(|| Path::new("."));
     let specs = crate::eval::import_specifiers(source, path)
         .map_err(|e| format!("cannot read imports: {}", e.message()))?;
@@ -427,28 +423,26 @@ fn sibling_predecessor_paths(path: &Path, source: &str) -> Result<Vec<PathBuf>,
     Ok(out)
 }
 
-/// Walk a predecessor chain to its origin and return the origin's raw bytes.
-/// Any predecessor of a version shares that version's origin, so following one
-/// predecessor at each step suffices.
+/// Walk a parent chain to its origin and return the origin's raw bytes.
+/// Any parent of a version shares that version's origin, so following one
+/// parent at each step suffices.
 fn walk_to_origin(pred: &Path) -> Result<Vec<u8>, String> {
     let mut current = pred.to_path_buf();
     let mut seen = std::collections::HashSet::new();
     loop {
         if !seen.insert(current.clone()) {
-            return Err(
-                "predecessor lineage forms a cycle; a plan's identity cannot be derived".into(),
-            );
+            return Err("parent lineage forms a cycle; a plan's identity cannot be derived".into());
         }
         let bytes = fs::read(&current).map_err(|_| {
             format!(
-                "predecessor {} has not arrived: a plan's identity is its origin, which cannot be \
+                "parent {} has not arrived: a plan's identity is its origin, which cannot be \
                  derived until the origin is present (decision 0017)",
                 current.display()
             )
         })?;
         let src = std::str::from_utf8(&bytes)
             .map_err(|e| format!("{}: not valid UTF-8: {e}", current.display()))?;
-        match sibling_predecessor_paths(&current, src)?.into_iter().next() {
+        match sibling_parent_paths(&current, src)?.into_iter().next() {
             None => return Ok(bytes),
             Some(next) => current = next,
         }

src/chain.rs

@@ -8,9 +8,9 @@
 //! The ontology is explicit and the distinction is the one Compass must not
 //! get wrong:
 //!
-//! - **Divergence** — two or more versions share the same predecessor. Intent
+//! - **Divergence** — two or more versions share the same parent. Intent
 //!   genuinely disagreed. Repaired by authoring a Reconciliation.
-//! - **Orphan** — a version whose predecessor is *absent locally*. Ordinarily
+//! - **Orphan** — a version whose parent is *absent locally*. Ordinarily
 //!   replication is simply incomplete. Repaired by **waiting**.
 //!
 //! Reconciling around a version that is merely in-flight writes permanent
@@ -20,23 +20,23 @@
 //! A version can be both a head member and an orphan: decision 0002
 //! Amendment 1 describes receiving versions 1, 2 and 4, where 4's parent has
 //! not arrived. Head is then `{2, 4}` — and reporting that as divergence would
-//! be a lie, because 2 and 4 share no predecessor.
+//! be a lie, because 2 and 4 share no parent.
 
 use crate::catalog::{Admitted, PlanStore};
 use std::collections::{BTreeMap, HashSet};
 
-/// A version whose predecessor is not present locally.
+/// A version whose parent is not present locally.
 #[derive(Debug, Clone)]
 pub struct Orphan<'a> {
     pub version: &'a Admitted,
     /// Parent hashes that are absent.
     pub missing: Vec<String>,
 }
 
-/// Two or more versions sharing a predecessor.
+/// Two or more versions sharing a parent.
 #[derive(Debug, Clone)]
 pub struct Divergence<'a> {
-    /// The shared predecessor hash, or `None` when several root versions exist.
+    /// The shared parent hash, or `None` when several root versions exist.
     pub parent: Option<String>,
     pub children: Vec<&'a Admitted>,
     /// Whether this divergence is still unresolved.
@@ -137,7 +137,7 @@ pub fn analyze(store: &PlanStore) -> Analysis<'_> {
         })
         .collect();
 
-    // Group by predecessor. Only predecessors that are actually present count:
+    // Group by parent. Only parents that are actually present count:
     // two versions both naming an absent parent are two orphans, not a
     // divergence we can reason about.
     let mut by_parent: BTreeMap<&str, Vec<&Admitted>> = BTreeMap::new();
@@ -274,7 +274,7 @@ pub fn lineage<'a>(store: &'a PlanStore, hash: &str) -> Vec<&'a Admitted> {
     out
 }
 
-/// The `seq` a new version should carry: one past the longest predecessor.
+/// The `seq` a new version should carry: one past the longest parent.
 pub fn next_seq(parents: &[&Admitted]) -> u64 {
     parents.iter().map(|p| p.seq).max().unwrap_or(0) + 1
 }
@@ -340,7 +340,7 @@ mod tests {
     }
 
     #[test]
-    fn a_missing_predecessor_is_an_orphan_not_a_divergence() {
+    fn a_missing_parent_is_an_orphan_not_a_divergence() {
         // Decision 0002 Amendment 1: versions 1, 2 and 4 arrive; 3 has not.
         let a = v("pl_1000000000", 1, "first", vec![]);
         let b = v("pl_1000000000", 2, "second", vec![a.hash.clone()]);
@@ -353,7 +353,7 @@ mod tests {
         assert_eq!(an.head.len(), 2, "2 and 4 both lack a successor");
         assert!(
             !an.diverged(),
-            "2 and 4 share no predecessor, so this is not divergence"
+            "2 and 4 share no parent, so this is not divergence"
         );
         assert_eq!(an.orphans.len(), 1);
         assert_eq!(an.orphans[0].version.hash, d_hash);
@@ -364,7 +364,7 @@ mod tests {
 
     #[test]
     fn two_versions_missing_the_same_parent_are_orphans_not_divergent() {
-        // The shared predecessor is absent, so nothing local proves they
+        // The shared parent is absent, so nothing local proves they
         // disagreed — only that replication is behind.
         let absent = "e".repeat(64);
         let a = v("pl_1000000000", 2, "one", vec![absent.clone()]);
@@ -523,7 +523,7 @@ mod tests {
     }
 
     #[test]
-    fn lineage_stops_at_an_absent_predecessor() {
+    fn lineage_stops_at_an_absent_parent() {
         let absent = "d".repeat(64);
         let a = v("pl_1000000000", 2, "orphaned", vec![absent]);
         let tip = a.hash.clone();
@@ -532,7 +532,7 @@ mod tests {
     }
 
     #[test]
-    fn next_seq_follows_the_longest_predecessor() {
+    fn next_seq_follows_the_longest_parent() {
         let short = v("pl_1000000000", 2, "short", vec![]);
         let long = v("pl_1000000000", 9, "long", vec![]);
         assert_eq!(next_seq(&[&short, &long]), 10);

src/cli.rs

@@ -328,7 +328,7 @@ compass commit <module.ts>
   - Committing content already present is a no-op success.
   - New content that revises nothing is refused, with a distinct message.
   - A module uses plan() for a first version, prior.revise({...}) for a
-    revision, or reconcile({revises:[...]}) for a reconciliation. Predecessors
+    revision, or reconcile({revises:[...]}) for a reconciliation. Parents
     are the version files it imports; the Plan is derived from the origin they
     descend from.
 "

src/cmd.rs

@@ -296,7 +296,7 @@ fn cmd_commit(root: &Path, path: &Path) -> Result<Output, String> {
 
     // A Plan's identity is derived from its origin (decision 0017): the operator
     // names nothing. An origin is its own PlanId; a revision inherits its Plan
-    // from the predecessor it descends from.
+    // from the parent it descends from.
     let plan = catalog::derive_planid(path, &source)?;
 
     // Evaluate the authored module (imports resolve at its location).
@@ -315,11 +315,11 @@ fn cmd_commit(root: &Path, path: &Path) -> Result<Output, String> {
         .ok_or_else(|| "the module did not export a plan".to_string())?;
 
     // Classify each version import (CMP.API-R05). An import of a version of the
-    // SAME plan is a predecessor, resolved against this plan's store and made a
+    // SAME plan is a parent, resolved against this plan's store and made a
     // parent of the new version. An import of ANOTHER plan's version is a
     // cross-plan reference: it must resolve against that plan's store (the other
-    // version must be admitted), but it is not a predecessor and does not make
-    // this commit "have an uncommitted predecessor".
+    // version must be admitted), but it is not a parent and does not make
+    // this commit "have an uncommitted parent".
     let store = catalog::load_plan(root, &plan)?;
     let mut parents: Vec<String> = Vec::new();
     for spec in crate::eval::import_specifiers(&source_str, path)
@@ -331,7 +331,7 @@ fn cmd_commit(root: &Path, path: &Path) -> Result<Output, String> {
         };
         // A target plan that differs from the current one is a cross-plan
         // reference; anything else (a sibling, or a version of this same plan)
-        // is a predecessor.
+        // is a parent.
         match crate::eval::import_target_plan(path, &spec) {
             Some(other) if other != plan => {
                 let other_store = catalog::load_plan(root, &other)?;
@@ -346,7 +346,7 @@ fn cmd_commit(root: &Path, path: &Path) -> Result<Output, String> {
                 Some(a) => parents.push(a.hash.clone()),
                 None => {
                     return Err(format!(
-                        "predecessor {prefix} is not committed in {plan}; nothing was recorded"
+                        "parent {prefix} is not committed in {plan}; nothing was recorded"
                     ))
                 }
             },
@@ -388,7 +388,7 @@ fn cmd_commit(root: &Path, path: &Path) -> Result<Output, String> {
         );
         return Ok(Output::ok(
             text,
-            receipt_json("already-committed", &plan, &hash, seq, &parents),
+            commit_result_json("already-committed", &plan, &hash, seq, &parents),
         ));
     }
 
@@ -434,11 +434,11 @@ fn cmd_commit(root: &Path, path: &Path) -> Result<Output, String> {
     );
     Ok(Output::ok(
         text,
-        receipt_json(kind, &plan, &hash, seq, &parents),
+        commit_result_json(kind, &plan, &hash, seq, &parents),
     ))
 }
 
-fn receipt_json(kind: &str, plan: &str, hash: &str, seq: u64, parents: &[String]) -> Json {
+fn commit_result_json(kind: &str, plan: &str, hash: &str, seq: u64, parents: &[String]) -> Json {
     Json::obj(vec![
         ("command", Json::str("commit")),
         ("result", Json::str(kind)),
@@ -570,7 +570,7 @@ fn divergence_report(an: &Analysis) -> String {
     let mut out = String::new();
     for o in &an.orphans {
         out.push_str(&format!(
-            "{} {} is an orphan: predecessor {} has not arrived — wait\n",
+            "{} {} is an orphan: parent {} has not arrived — wait\n",
             style::warning(),
             style::short(&o.version.hash),
             o.missing
@@ -582,7 +582,7 @@ fn divergence_report(an: &Analysis) -> String {
     }
     for d in an.open_divergences() {
         out.push_str(&format!(
-            "{} open divergence: {} head members share a predecessor — reconcile by authoring \
+            "{} open divergence: {} head members share a parent — reconcile by authoring \
              a version importing both\n",
             style::warning(),
             d.children.len()
@@ -852,7 +852,7 @@ fn cmd_verify(root: &Path, plan: Option<&str>, all: bool) -> Result<Output, Stri
         for o in &an.orphans {
             clean = false;
             let reason = format!(
-                "predecessor {} not present",
+                "parent {} not present",
                 o.missing
                     .iter()
                     .map(|m| style::short(m))
@@ -949,7 +949,7 @@ fn cmd_repair(root: &Path, plan: &str) -> Result<Output, String> {
         ));
     }
 
-    // Identify the last intact predecessor to continue from.
+    // Identify the last intact parent to continue from.
     let intact: Vec<&Admitted> = store
         .versions
         .iter()
@@ -973,7 +973,7 @@ fn cmd_repair(root: &Path, plan: &str) -> Result<Output, String> {
         Some(b) => {
             let rel = crate::model::filename_for(b.seq, &b.hash);
             text.push_str(&format!(
-                "\nAuthor a damage-recording version continuing from the last intact predecessor \
+                "\nAuthor a damage-recording version continuing from the last intact parent \
                  ({}):\n\n  import prior from \"./{}\"\n  export default prior.revise({{\n    \
                  author: \"you\",\n    why: \"Records the damage to <hash> and continues.\",\n  \
                  }})\n\nthen `compass commit` it. Verification stays read-only.\n",
@@ -983,7 +983,7 @@ fn cmd_repair(root: &Path, plan: &str) -> Result<Output, String> {
         }
         None => {
             text.push_str(
-                "\nNo intact predecessor remains; author a fresh plan recording what is known \
+                "\nNo intact parent remains; author a fresh plan recording what is known \
                  of the lost intent.\n",
             );
         }