Rephrase residual spec-authority citations in docstrings

chris-colinsky · chris-colinsky · commit e191500dac73 · 2026-06-18T15:08:26.000-07:00
The first sweep stripped structured spec references (section markers,
proposal numbers, versions) but left prose that still cited the spec
as the authority for a rule ("The spec defines/permits/mandates",
"spec-mandated", "spec-normative", "per spec"). State the behavior
directly, or move the basis to a nearby comment where load-bearing.

Structural mentions are kept: the spec/ conformance directories, the
spec parameter in the harness, spec-version reads, and descriptions of
what the conformance suite covers.
diff --git a/src/openarmature/graph/compiled.py b/src/openarmature/graph/compiled.py
@@ -372,18 +372,17 @@ def _restore_fan_out_progress_state(
     into the mutable per-fan-out tracking dict that ``FanOutNode``
     consults to decide which instances to skip vs re-run.
 
-    Extra-output state isn't preserved across resume — the spec models
-    ``result`` as a single accumulator entry and is silent on
+    Extra-output state isn't preserved across resume: ``result`` is
+    modeled as a single accumulator entry, with nothing recorded for
     ``extra_outputs``. Reconstructing them would require either
-    serializing them on the record (a spec change) or recomputing them
+    serializing them on the record (a record-format change) or recomputing them
     (defeating the point of skip-on-resume). Fixtures don't exercise
     ``extra_outputs`` on the resume path; if a future workload needs
     them, surface as a follow-on.
 
     ``result_is_error`` is read verbatim from the saved record's
-    explicit field. The earlier structural-pattern heuristic is gone
-    — the spec mandates the
-    explicit field as the authoritative discriminator because the
+    explicit field. The earlier structural-pattern heuristic is gone:
+    the explicit field is the authoritative discriminator because the
     user's state schema can legitimately contain values that match
     the engine's canonical error-record shape, and a heuristic would
     misclassify them.
@@ -1412,7 +1411,7 @@ async def _step_function_node(
         (``node_exception`` / ``reducer_error`` /
         ``state_validation_error``) stay inline in ``innermost`` —
         those errors short-circuit before edge eval can run, so the
-        spec's "before the failure propagates" MUST is preserved by
+        "before the failure propagates" requirement is preserved by
         the inline dispatch.
 
         Returns a :class:`_StepResult` carrying the merged state +
@@ -2375,7 +2374,7 @@ async def _maybe_save_checkpoint(
 
         Atomicity contract: the save-call site below
         completes the "produce contribution + record into accumulator
-        + save" sequence the spec mandates. ``FanOutNode.run_with_context``
+        + save" sequence. ``FanOutNode.run_with_context``
         flips an instance's state to ``completed`` and stashes its
         ``result`` BEFORE invoking the save that durably records the
         transition. A crash between that state mutation and the save
diff --git a/src/openarmature/graph/events.py b/src/openarmature/graph/events.py
@@ -536,8 +536,8 @@ class LlmCompletionEvent:
       lifetime, unique within the run. Distinct from
       ``response_id``.
     - ``caller_invocation_metadata``: optional snapshot of caller-
-      supplied invocation metadata at LLM-call time. Spec-defined as
-      OPTIONAL; the python OpenAIProvider populates it by default so
+      supplied invocation metadata at LLM-call time. OPTIONAL; the
+      python OpenAIProvider populates it by default so
       the bundled OTel/Langfuse observers can emit the
       ``openarmature.user.<key>`` span-attribute family without an
       extra opt-in. Pass ``populate_caller_metadata=False`` to suppress
@@ -625,7 +625,7 @@ class LlmFailedEvent:
       ``provider_unsupported_content_block``,
       ``structured_output_invalid``). Always present.
     - ``error_type``: OPTIONAL impl-level / vendor-specific error
-      type or code. Two acceptable styles per spec:
+      type or code. Two acceptable styles:
       vendor error code (e.g. ``"rate_limit_exceeded"``) OR
       upstream exception class name (e.g. ``"RateLimitError"``).
       ``None`` when no impl-side type is available.
diff --git a/src/openarmature/graph/observer.py b/src/openarmature/graph/observer.py
@@ -22,7 +22,7 @@
 - `_dispatch`: enqueues an event for the worker to deliver.
 - `deliver_loop`: the worker coroutine. Reads items from the queue and
   calls each observer in order, filtering by subscribed phase and
-  isolating exceptions via `warnings.warn` per spec.
+  isolating exceptions via `warnings.warn`.
 """
 
 from __future__ import annotations
@@ -344,7 +344,7 @@ class DrainSummary:
     delivered to every subscribed observer before cancellation, and
     `timeout_reached is True`.
 
-    The spec-mandated minimum is these two fields. Implementations MAY
+    These two fields are the required minimum. Implementations MAY
     extend the shape with diagnostic detail (per-observer counts,
     sampled event metadata) in subsequent versions; this version ships
     the minimum.
@@ -376,17 +376,17 @@ class _FanOutInstanceState:
     - ``result_is_error`` distinguishes success contributions
       (``False``) from collect-mode error contributions (``True``).
       Internal flag — not exposed on the public
-      ``FanOutInstanceProgress`` shape because the spec presents
-      ``result`` as a single typed entry per the parent state schema.
+      ``FanOutInstanceProgress`` shape because ``result`` is exposed
+      as a single typed entry per the parent state schema.
       ``FanOutNode.run_with_context`` consults this on resume to
       route the rolled-forward contribution through the
       ``errors_field`` bucket rather than ``target_field``.
     - ``extra_outputs`` holds the per-instance values for the fan-out's
       ``extra_outputs`` mapping (parent-field -> sub-field) so that
       per-instance resume preserves the FULL per-instance contribution
       (not just the ``target_field`` slice). Internal — not exposed on
-      the public ``FanOutInstanceProgress`` shape because the spec
-      describes ``result`` as a single accumulator entry.
+      the public ``FanOutInstanceProgress`` shape because ``result``
+      is a single accumulator entry.
     - ``completed_inner_positions`` accumulates ``NodePosition`` entries
       from inner nodes that complete inside this instance's subgraph
       execution. Captures the instance's progress for observational
diff --git a/src/openarmature/graph/parallel_branches.py b/src/openarmature/graph/parallel_branches.py
@@ -62,7 +62,7 @@
 class BranchSpec[ChildT: State]:
     """One entry in a :class:`ParallelBranchesNode`'s branch mapping.
 
-    Branches are heterogeneous: each spec MAY reference a different
+    Branches are heterogeneous: each branch may reference a different
     compiled subgraph with a different state schema. ``inputs`` /
     ``outputs`` follow the same shape as subgraph projection
     mappings.
diff --git a/src/openarmature/llm/messages.py b/src/openarmature/llm/messages.py
@@ -79,7 +79,7 @@ class ForceTool(BaseModel):
 
     Use the record form of the `tool_choice` discriminated union when
     you need the model to call a specific tool by name. ``type`` is the
-    spec-level discriminator (``"tool"``); the wire mapping renames it
+    discriminator (``"tool"``); the wire mapping renames it
     to ``"function"`` for the OpenAI body. The
     ``name`` MUST match a ``Tool.name`` in the supplied ``tools``
     list; ``validate_tool_choice`` enforces this at pre-send time and
diff --git a/src/openarmature/observability/langfuse/observer.py b/src/openarmature/observability/langfuse/observer.py
@@ -164,9 +164,9 @@ def _subgraph_identity_at(event: NodeEvent, depth: int) -> str:
     given 1-based namespace depth, or the empty string when no
     identity is tracked at that depth.
 
-    The empty-string fallback matches the spec's "if the
-    implementation tracks one" clause for implementations / direct
-    ``SubgraphNode(...)`` callers that don't wire an identity through.
+    The empty-string fallback is the "no identity tracked" case, for
+    implementations / direct ``SubgraphNode(...)`` callers that don't
+    wire an identity through.
     Conformance fixtures 031/032/033 lock identity as the required
     value; the empty-string path keeps direct callers conformant but
     failing those fixtures.
diff --git a/src/openarmature/observability/metadata.py b/src/openarmature/observability/metadata.py
@@ -27,7 +27,7 @@
 
 - Keys MUST be strings.
 - Keys MUST NOT start with ``openarmature.`` or ``gen_ai.`` (reserved
-  for spec-normative attribute namespaces; collisions would silently
+  attribute namespaces; collisions would silently
   overwrite OA-emitted state at the observer layer).
 - Keys MUST NOT exactly match a reserved OA-emitted top-level metadata
   key name (the Langfuse set plus ``invocation_id``) for the same
diff --git a/src/openarmature/observability/otel/observer.py b/src/openarmature/observability/otel/observer.py
@@ -186,10 +186,9 @@ def _subgraph_identity_at(event: NodeEvent, depth: int) -> str:
     given 1-based namespace depth, or the empty string when no
     identity is tracked at that depth.
 
-    The empty-string fallback matches the spec's "if the implementation
-    tracks one" clause for callers using
-    ``SubgraphNode(name=..., compiled=...)`` without supplying
-    ``subgraph_identity``.
+    The empty-string fallback is the "no identity tracked" case, for
+    callers using ``SubgraphNode(name=..., compiled=...)`` without
+    supplying ``subgraph_identity``.
     """
     # Spec observability §5.3 (coord thread
     # clarify-subgraph-name-semantics).
diff --git a/src/openarmature/prompts/backends/filesystem.py b/src/openarmature/prompts/backends/filesystem.py
@@ -21,9 +21,9 @@ class FilesystemPromptBackend:
     - ``layout="per-label"`` (default): ``<root>/<label>/<name>.j2``.
       The ``label`` subdirectory keeps name-collisions across labels
       distinct (e.g., ``prompts/production/greeting.j2`` and
-      ``prompts/staging/greeting.j2``). The spec permits filesystem
-      backends to interpret label as "a subdirectory or filename
-      suffix"; this is the subdirectory variant.
+      ``prompts/staging/greeting.j2``). A filesystem backend may
+      interpret label as a subdirectory or filename suffix; this is
+      the subdirectory variant.
     - ``layout="flat"``: ``<root>/<name>.j2``. The same template
       is returned regardless of which label was requested; the
       Prompt's ``label`` field is the requested label verbatim.
diff --git a/src/openarmature/prompts/group.py b/src/openarmature/prompts/group.py
@@ -21,7 +21,7 @@ class PromptGroup(BaseModel):
         group_name: Stable identifier for this group pattern.
         members: Ordered sequence of at least two PromptResult
             instances. Order matches the application's intended call
-            sequence; the spec does not require sequential execution.
+            sequence; sequential execution is not required.
     """
 
     model_config = ConfigDict(extra="forbid")
diff --git a/src/openarmature/prompts/prompt.py b/src/openarmature/prompts/prompt.py
@@ -183,7 +183,7 @@ class _PromptBase(BaseModel):
             into ``provider.complete(config=...)`` without translation.
         observability_entities: Optional backend-keyed references to
             first-class entities the prompt has been registered as in
-            observability backends.  Spec-normative key:
+            observability backends.  Recognized key:
             ``langfuse_prompt`` (the Langfuse SDK Prompt-entity ref).
         metadata: Optional backend-supplied metadata.
     """
diff --git a/tests/conformance/adapter.py b/tests/conformance/adapter.py
@@ -504,7 +504,7 @@ def _make_flaky_fn(
       031): the engine's first invoke aborts on this node; the
       resumed invoke succeeds. No retry middleware is wrapped around
       these nodes (any wrapping would bypass the resume path), so
-      "fail-once-then-succeed" matches the spec contract directly.
+      "fail-once-then-succeed" matches the resume contract directly.
     """
     sequence = list(flaky.get("failure_sequence", []))
     success_update = dict(flaky.get("success_update", {}))
@@ -694,7 +694,7 @@ def _projection_for(node_spec: Mapping[str, Any]) -> ProjectionStrategy[State, S
     """Pick the projection strategy declared on a subgraph node spec.
 
     `inputs:` and/or `outputs:` in the YAML → `ExplicitMapping`. Both absent →
-    the spec's default `FieldNameMatching`.
+    the default `FieldNameMatching`.
     """
 
     inputs = node_spec.get("inputs")
diff --git a/tests/conformance/harness/directives.py b/tests/conformance/harness/directives.py
@@ -28,16 +28,16 @@
 class _ForbidExtras(BaseModel):
     """Strict — used for the structural skeleton (state schema, node primary
     directive set, edges, observer registration, middleware config split).
-    Catches new directives the spec adds at the load-bearing places."""
+    Catches new fixture directives at the load-bearing places."""
 
     model_config = ConfigDict(extra="forbid")
 
 
 class _AllowExtras(BaseModel):
     """Permissive — used for payload-shape models (mock LLM responses,
     middleware-specific params, flaky/fan-out config). Validates KNOWN
-    keys' types but doesn't reject unknown ones — the spec evolves these
-    payloads frequently and modelling every parameter exhaustively
+    keys' types but doesn't reject unknown ones — these payloads evolve
+    frequently and modelling every parameter exhaustively
     creates churn without proportional value. The strictness
     contract sits at the directive STRUCTURE level (above), not the
     parameter-bag level (here)."""
@@ -87,8 +87,8 @@ class StateSchema(_ForbidExtras):
 class EdgeSpec(_AllowExtras):
     """One edge in a graph definition.
 
-    The spec defines static (``from``/``to``) and conditional
-    (``from``/``condition``) edges; observability/011 also uses a
+    Edges come in static (``from``/``to``) and conditional
+    (``from``/``condition``) forms; observability/011 also uses a
     ``when``-shaped predicate. Schema is permissive here so all forms
     parse — the engine retrofit interprets each shape against
     the engine's edge model.
@@ -576,8 +576,8 @@ class MockResponse(_AllowExtras):
 
     Permissive shape because the body's content mirrors OpenAI's wire
     format which is wide and evolving; modelling every field would
-    duplicate the OpenAI schema. The ``llm-provider`` capability's
-    spec is the authoritative shape.
+    duplicate the OpenAI schema. The OpenAI wire format is the
+    authoritative shape.
     """
 
     status: int | None = None
diff --git a/tests/conformance/harness/expectations.py b/tests/conformance/harness/expectations.py
@@ -8,7 +8,7 @@
 in :mod:`runtime` typed access to the assertion payload it needs.
 
 Typing depth: TOP-LEVEL keys per capability are exhaustively
-typed (catches new directives the spec adds). The nested payload values
+typed (catches new fixture directives). The nested payload values
 underneath (e.g., individual span tree entries, observer event details)
 are kept loose as ``list[Any]`` / ``dict[str, Any]`` because the runtime
 code that consumes them is the right place to tighten.
diff --git a/tests/conformance/test_pipeline_utilities.py b/tests/conformance/test_pipeline_utilities.py
@@ -850,10 +850,10 @@ def _collect_parallel_branches_errors_fields(spec: Mapping[str, Any]) -> set[str
     ``errors_field`` on any parallel_branches node in ``spec``.
 
     The ``errors_field`` carries an implementation-defined
-    record shape; the spec only mandates ``branch_name`` + category. The
+    record shape; only ``branch_name`` + category are required. The
     engine's record carries additional engine-defined keys (``message``,
     ``cause_type``). Fixtures asserting against ``errors_field`` records
-    use subset semantics — assert the spec-mandated keys are present
+    use subset semantics — assert the required keys are present
     with the expected values, ignore the rest.
     """
     out: set[str] = set()
diff --git a/tests/conformance/test_prompt_management.py b/tests/conformance/test_prompt_management.py
@@ -72,7 +72,7 @@ def _segment_from_fixture(entry: dict[str, Any]) -> Any:
     validators — the harness exists to test render-time behavior,
     including fixtures that intentionally build prompts violating
     construction-time invariants (placeholder regex, role-block
-    compat).  Render-time enforcement (the spec-normative trigger)
+    compat).  Render-time enforcement (the normative trigger)
     still runs; only the construction-time ergonomic-only check is
     bypassed.
 
@@ -546,7 +546,7 @@ def _assert_capture_attrs(capture_name: str, actual: Any, expected: dict[str, An
 
 def _message_to_dict_for_compare(message: Message) -> dict[str, Any]:
     """Dump a Message to a plain dict for structural equality against
-    a fixture YAML expected value.  Mirrors the spec's documented
+    a fixture YAML expected value.  Mirrors the documented
     Message shape: ``{role, content}`` with optional extras."""
     dumped = message.model_dump(exclude_none=True)
     # Normalize content-blocks shape: drop pydantic internal
diff --git a/tests/unit/test_correlation.py b/tests/unit/test_correlation.py
@@ -34,8 +34,8 @@ async def _read_correlation(state: _S) -> dict[str, str]:
 
 async def test_caller_supplied_correlation_id_visible_inside_node() -> None:
     """User code in a node body can read the supplied correlation_id
-    via :func:`current_correlation_id` — the spec's mandated
-    cross-backend join key surface."""
+    via :func:`current_correlation_id`, the cross-backend join key
+    surface."""
     g = GraphBuilder(_S).add_node("read", _read_correlation).add_edge("read", END).set_entry("read").compile()
     final = await g.invoke(_S(), correlation_id="my-business-request-42")
     assert final.captured == "my-business-request-42"
diff --git a/tests/unit/test_fan_out.py b/tests/unit/test_fan_out.py
@@ -1,6 +1,6 @@
 """Unit tests for the fan-out runtime.
 
-Covers the spec-corner cases the conformance fixtures exercise only
+Covers the edge cases the conformance fixtures exercise only
 implicitly:
 
 - items_field projection
diff --git a/tests/unit/test_parallel_branches.py b/tests/unit/test_parallel_branches.py
@@ -1,6 +1,6 @@
 """Unit tests for the parallel-branches runtime.
 
-Covers spec corner cases the conformance fixtures exercise only
+Covers edge cases the conformance fixtures exercise only
 implicitly:
 
 - compile-time empty-branches rejection
diff --git a/tests/unit/test_projection.py b/tests/unit/test_projection.py
@@ -106,7 +106,7 @@ def test_explicit_mapping_outputs_projects_only_named_pairs() -> None:
 
 
 def test_explicit_mapping_outputs_absent_falls_back_to_field_name_matching() -> None:
-    """`outputs=None` (absent) falls back to spec default field-name matching;
+    """`outputs=None` (absent) falls back to the default field-name matching;
     `outputs={}` (present, empty) projects nothing."""
 
     sub_final = ChildEM(input=1, result=2, note="from-child")
diff --git a/tests/unit/test_runtime_errors.py b/tests/unit/test_runtime_errors.py
@@ -1,6 +1,6 @@
 """Runtime-error categories not exercised by the conformance suite.
 
-The spec defines five runtime categories. The conformance fixtures cover
+There are five runtime-error categories. The conformance fixtures cover
 `node_exception` (009) and `routing_error` (008) directly and reach the
 others incidentally via 001–006. These tests target the three categories no
 fixture triggers: `edge_exception`, `reducer_error`, and
