refactor(lang): make composition the canonical name; deprecate compose

docs/for-users/language-reference.md

@@ -451,7 +451,7 @@ probabilistic, write down the probability model that justifies the update.
 | Logical hard constraints | `derive`, `compute`, `decompose`, `equal`, `contradict`, `exclusive`, formula claims | If the premises are true, the conclusion or relation should follow as a matter of logic or definition | Yes. Lowered as deterministic factors |
 | Hand-written probabilistic soft constraints | `infer`, `associate` | You are directly committing to conditional probabilities or an association strength | Yes. Lowered as probabilistic factors |
 | Model-based Bayesian soft constraints | `bayes.model`, `bayes.compare` | The probabilities come from a statistical model, distribution, and observed data | Yes. Lowered to likelihood-style probabilistic factors and reviewable relations |
-| Composed workflows | `@compose` | A Python function groups several actions into one named workflow | The child actions enter inference according to their own kinds |
+| Composed workflows | `@composition` | A Python function groups several actions into one named workflow | The child actions enter inference according to their own kinds |
 
 This split exists for a practical reason: reviewers and downstream users need
 to know what kind of commitment each line makes. A scaffold note says "work
@@ -944,7 +944,7 @@ from gaia.engine.lang.compat import (
 | `support([P], C, prior=...)` | `derive(C, given=[P])` (deterministic) or `infer(P, hypothesis=C, p_e_given_h=..., p_e_given_not_h=...)` / `bayes.compare(...)` (probabilistic) | `P` is the evidence; `C` is the hypothesis whose belief gets updated. |
 | `deduction([P], C)` | `derive(C, given=[P])` | Strict logical entailment lowers to a hard conditional implication. |
 | `compare / abduction / induction / analogy / extrapolation / elimination / case_analysis / mathematical_induction` | Author the deterministic skeleton with `derive(...)` + relation verbs, or `bayes.compare(...)` for explicit Bayesian comparisons | Do not use these as shortcuts for uncertainty that hasn't been spelled out as claims. |
-| `composite(..., sub_strategies=[...])` | Plain `derive(...)` chains plus `@compose` for the workflow boundary | Sub-strategy priors are no longer the v0.5 surface for soft leaves; use `infer(...)` / `bayes.compare(...)` instead. |
+| `composite(..., sub_strategies=[...])` | Plain `derive(...)` chains plus `@composition` for the workflow boundary | Sub-strategy priors are no longer the v0.5 surface for soft leaves; use `infer(...)` / `bayes.compare(...)` instead. |
 | `infer([premises], conclusion, ...)` (legacy positional) | `infer(evidence, hypothesis=..., given=..., p_e_given_h=..., p_e_given_not_h=...)` | The legacy positional form is preserved as a deprecated path; the keyword form is the v0.5 contract. |
 | `contradiction(a, b)` / `equivalence(a, b)` / `complement(a, b)` | `contradict(a, b)` / `equal(a, b)` / `exclusive(a, b)` | The relation-verb forms appear in review manifests and emit reviewable warrant helpers. |
 | `disjunction(*claims)` / `and_(...)` / `or_(...)` / `not_(...)` | `claim(..., formula=lor(...))` / `claim(..., formula=land(...))` / `claim(..., formula=lnot(...))`, or the dunder formula sugar `a \| b`, `a & b`, `~a` | Formula AST is the v0.5 way to express structural Boolean expressions; dunders now return Formula nodes, not legacy helper claims. |

docs/foundations/gaia-lang/knowledge-and-reasoning.md

@@ -192,7 +192,7 @@ Scaffold actions compile only into `.gaia/formalization_manifest.json`. They are
 
 ### 3.5 Compose — action-level composition
 
-`@compose(name=..., version=..., warrants=None, ...)` decorates a Python function as a named action workflow. Inside the function the author calls other action verbs; calling the decorated function:
+`@composition(name=..., version=..., warrants=None, ...)` (deprecated alias: `@compose`) decorates a Python function as a named action workflow. Inside the function the author calls other action verbs; calling the decorated function:
 
 1. Captures every action emitted inside the call into a `Compose` runtime object.
 2. Records `inputs` (Knowledge values passed as args, plus claims captured from background and child actions), `actions` (the ordered list of children, by reference or by id), and `conclusion` (the function's return value, which **must** be a `Claim`).
@@ -452,7 +452,7 @@ Operators that emit a relation-result conclusion (`equivalence`, `contradiction`
 | `Infer` / `Associate` action | `Strategy` with explicit CPT + warrant helper `Knowledge` | warrant helper is the primary label resolution target |
 | `Equal` / `Contradict` / `Exclusive` action | `Operator` + helper `Knowledge` | top-level operator gets `lco_*` ID; helper is reviewable |
 | `Decompose` action | formula `Operator`s over `parts` + `Operator(equivalence, [whole, formula_helper])` | enforces atomic-parts match and acyclicity |
-| `@compose`-decorated function | `gaia.engine.ir.Compose` first-class IR node | structure-hashed over inputs, child actions, conclusion, warrants |
+| `@composition`-decorated function | `gaia.engine.ir.Compose` first-class IR node | structure-hashed over inputs, child actions, conclusion, warrants |
 | `DependsOn` action | (not lowered) | authoring metadata only |
 
 Identity assignment:

docs/reference/cli/author.md

@@ -77,8 +77,8 @@ records its metadata in `pyproject.toml`).
 | Scaffold | `depends-on` | `depends_on(conclusion, given, *, rationale="", background=None, label=None)` | yes |
 | Scaffold | `candidate-relation` | `candidate_relation(*, claims, pattern, rationale="", background=None, label=None)` | yes |
 | Scaffold | `materialize` | `materialize(scaffold, *, by, rationale="", label=None)` | yes |
-| Composition | `compose` | `@compose(name=…, version=…)` decorating `def fn(...) -> Claim` | **no — file-based** |
-| Composition | `composition` | alias of `compose` | **no — file-based** |
+| Composition | `composition` | `@composition(name=…, version=…)` decorating `def fn(...) -> Claim` | **no — file-based** |
+| Composition | `compose` | deprecated alias of `composition` | **no — file-based** |
 | Typed terms | `variable` | `Variable(symbol=…, domain=…, value=…)` or `Constant(value, primitive)` | yes |
 
 The 21st verb in this reference, `gaia pkg scaffold`, lives in the `pkg`
@@ -283,7 +283,7 @@ gaia author compute --conclusion-type <ident> --label <ident> [--target <path>]
 | `--given <csv>` | no | Comma-separated input identifiers. |
 
 The decorator form `@compute` stays at Python-source level (same logic as
-`compose` / `composition`).
+`composition` / its deprecated alias `compose`).
 
 ### `infer`
 
@@ -403,16 +403,19 @@ gaia author materialize --scaffold <ident> --by <csv> --label <ident> \
 | `--scaffold <ident>` | yes | Scaffold identifier the materialization targets. |
 | `--by <csv>` | yes | Comma-separated identifiers used as the `by=` arg (single-element scalars and multi-element lists both render as `by=[...]`). |
 
-## File-based verbs — `compose` / `composition`
+## File-based verbs — `composition` (+ deprecated alias `compose`)
 
-The two composition verbs do **not** append a statement to
+`composition` is the canonical verb; `compose` is a deprecated alias kept
+for compatibility (it reads as the inverse of `decompose`, which it is
+not — see issue #759) and surfaces a deprecation warning in the envelope.
+The composition verbs do **not** append a statement to
 `__init__.py`. The composition primitive is a Python-decorator-level
 concept (its body is an arbitrary Python function capturing nested
 `Action` invocations through a ContextVar), so the cli takes the file
 containing the decorated function as input and registers its metadata.
 
 ```
-gaia author <compose|composition> --from-file <path> [--target <pkg-root>]
+gaia author <composition|compose> --from-file <path> [--target <pkg-root>]
     [--check/--no-check] [--human] [--interactive] [--json/--no-json]
 ```
 
@@ -425,7 +428,7 @@ gaia author <compose|composition> --from-file <path> [--target <pkg-root>]
 diagnostic):
 
 * `--from-file` must exist and parse as valid Python.
-* Exactly **one** `@compose` / `@composition`-decorated `FunctionDef` per
+* Exactly **one** `@composition` / `@compose`-decorated `FunctionDef` per
   file (the *one-compose-per-file rule*). Both bare names and
   `<module>.compose` Attribute-shaped references are counted.
 * The decorator must carry `name=` and `version=` string kwargs.
@@ -688,9 +691,10 @@ from "your Python parses but the sandbox does not allow it".
 
 ## Compose validate-and-register
 
-The `compose` / `composition` verbs (see [File-based verbs](#file-based-
-verbs-compose-composition)) extract metadata from a Python file with a
-single `@compose` / `@composition`-decorated `FunctionDef` and record
+The `composition` verb and its deprecated `compose` alias (see
+[File-based verbs](#file-based-verbs-composition-deprecated-alias-compose))
+extract metadata from a Python file with a
+single `@composition` / `@compose`-decorated `FunctionDef` and record
 that metadata in the target package's `pyproject.toml` as a
 `[[tool.gaia.compositions]]` array-of-tables entry. Five string fields:
 `name` / `version` / `file` / `function` / `registered_at`
@@ -704,9 +708,9 @@ file contains zero or more than one decorated function, the verb exits
 The minimal pattern in the file:
 
 ```python
-from gaia.engine.lang import compose
+from gaia.engine.lang import composition
 
-@compose(name="my_strategy", version="0.1.0")
+@composition(name="my_strategy", version="0.1.0")
 def my_strategy(...) -> Claim:
     ...
 ```

gaia/_skills/gaia-formalize-fine/SKILL.md

@@ -52,7 +52,7 @@ gaia run infer .                → .gaia/beliefs.json
 | 1 | Content extraction | Are claims and notes extracted? Atomic? |
 | 2 | Reasoning connections | Are derivations, inferences, observations, computes, and structural relations modelled? |
 | 3 | Content completeness | Any missing premises, orphans, or `@label` errors? |
-| 4 | Strategy precision | Is each author verb the right one (`derive` vs `infer` vs `compute` vs `observe` vs `compose`)? |
+| 4 | Strategy precision | Is each author verb the right one (`derive` vs `infer` vs `compute` vs `observe` vs `composition`)? |
 | 5 | Structural integrity | Is evidence independent? Are `contradict` / `exclusive` semantics correct? |
 | 6 | Standalone readability | Can a reviewer understand everything without the source? |
 
@@ -84,7 +84,7 @@ The methodology below leans on this fixed set of CLI calls. Drill into `gaia <gr
   - `gaia author equal --a ... --b ...` — equate two claims (logical equivalence).
   - `gaia author contradict --a ... --b ...` — assert NOT (A AND B): both cannot be true, but both can be false.
   - `gaia author exclusive --a ... --b ...` — assert A XOR B: exactly one must be true (exhaustive + mutually exclusive).
-  - `gaia author compose --from-file pattern.py` — register a `@compose`-decorated reusable reasoning pattern.
+  - `gaia author composition --from-file pattern.py` — register a `@composition`-decorated reusable reasoning pattern.
   - `gaia author register-prior --claim ... --value ... --justification ... [--file priors.py]` — write a `register_prior(...)` statement; auto-injects the import if the target file is a sibling.
 - `gaia run infer <pkg>` — run BP, emit `.gaia/beliefs.json`. Pass `--depth N` (>0) to merge dependency packages' factor graphs for joint cross-package inference.
 - `gaia run render <pkg> --target github` — generate `.github-output/` README + narrative outline (handoff to `../gaia-publish/SKILL.md`).

gaia/_skills/gaia-formalize-fine/references/pass-2-connect.md

@@ -13,7 +13,7 @@ For each claim "supported by other claims," choose one of these author verbs:
 - `gaia author observe --conclusion C [--value ... --error ...]` — raw measurement: ties a Claim, Variable, or Distribution to an observed value. Use for experimental measurements that anchor the graph in data.
 - `gaia author compute --conclusion-type T --fn f --given P1,P2,...` — deterministic mapping: a named callable produces the result from the premises. Use when the source presents a closed-form computation whose function is captured by code.
 - `gaia author decompose --whole W --parts A,B,... --formula-template and|or|atom` — structural split: composite claim → atomic parts. Use when an aggregate claim is best read as a conjunction (or disjunction) of independently judgeable atoms.
-- `gaia author compose --from-file pattern.py` — register a reusable multi-step pattern as a `@compose`-decorated function. Use Pass 4 to refine flat `derive`/`infer` calls into compositions when meaningful intermediate propositions appear.
+- `gaia author composition --from-file pattern.py` — register a reusable multi-step pattern as a `@composition`-decorated function. Use Pass 4 to refine flat `derive`/`infer` calls into compositions when meaningful intermediate propositions appear.
 
 Plus the structural-relation verbs (no `--given`; these state a logical constraint between claims):
 
@@ -119,6 +119,6 @@ Contradictions and exclusives are especially valuable in BP because they create
 Before moving to Pass 3, verify:
 
 - **Theory-experiment pairs use `infer`?** Every place the source compares a theoretical prediction against an experimental observation should be connected via `infer(evidence=obs, hypothesis=pred, --p-e-given-h ..., --p-e-given-not-h ...)`. The relationship is explanatory ("does the observation support the prediction?"), not a rigid step-by-step derivation.
-- **Multiple observations confirming one law?** If several independent observations all support the same general rule, the conclusion claim (the law) should be a `derive(...)` over those observations — and in Pass 4 you will likely refactor that to a `compose`'d pattern that names the generalisation step explicitly.
+- **Multiple observations confirming one law?** If several independent observations all support the same general rule, the conclusion claim (the law) should be a `derive(...)` over those observations — and in Pass 4 you will likely refactor that to a `composition` that names the generalisation step explicitly.
 - **No missing alternatives?** When the source compares competing hypotheses against one observation, every alternative should be extracted as a claim and either chained as additional `infer` evidence or wired with `exclusive` if the source treats the alternatives as exhaustive.
 - **Contradictions modelled?** Every contradictory claim pair identified in Pass 1 should now have a `contradict(...)` (or `exclusive(...)`) operator. Also check: did any new contradictions emerge while writing relations?