feat: classifier with Decision dataclass

classify(tool_call, manifest) -> Decision is a pure function: same
input, same output, every time. ToolCall and Decision are frozen +
slotted + kw-only dataclasses. The Decision carries the tool name, a
canonical effects tuple (PRECEDENCE-ordered, byte-stable), the dominant
class, and a deterministic rationale string.

Tool not declared → ManifestError. Tool declared → Decision with the
manifest's stored effects. Phase 2 doesn't refine on the tool call's
arguments — manifest is the spec; argument-aware classification is a
later phase if needed.

ToolCall, Decision, classify added to __all__. Tests cover the happy
paths, dominance, canonical ordering, byte-stable rationale, frozen
immutability, and the undeclared-tool error path. Module remains pure;
Manifest import is TYPE_CHECKING-only to keep the import graph clean.

Author: claude

src/spine_lite/__init__.py

@@ -8,6 +8,7 @@
 
 import logging
 
+from spine_lite.classifier import Decision, ToolCall, classify
 from spine_lite.effects import PRECEDENCE, Effect, most_restrictive
 from spine_lite.exceptions import (
     ClassificationError,
@@ -24,15 +25,18 @@
 __all__ = [
     "PRECEDENCE",
     "ClassificationError",
+    "Decision",
     "Effect",
     "HookError",
     "Manifest",
     "ManifestError",
     "Posture",
     "PostureError",
     "SpineLiteError",
+    "ToolCall",
     "ToolDefinition",
     "__version__",
+    "classify",
     "most_restrictive",
     "parse_manifest",
 ]

src/spine_lite/classifier.py

@@ -1,11 +1,113 @@
-"""Effect classifier (Phase 2).
+"""Effect classifier.
 
-``classify(tool_call, manifest) -> Decision`` is a pure function that lands
-in Phase 2. It returns the set of effects implied by a tool call against a
-validated manifest, plus the dominating effect under
-:data:`spine_lite.effects.PRECEDENCE`.
+The :func:`classify` function maps a :class:`ToolCall` and a validated
+:class:`spine_lite.manifest.Manifest` to a :class:`Decision`.
 
-Pure module: deterministic, no I/O, no clocks, no randomness.
+Pure module: deterministic, no I/O, no clocks, no randomness. Identical
+inputs produce identical decisions every time. The decision's
+``rationale`` is the only string-formatted field, and it is built from
+fields in canonical order so two calls with the same inputs produce the
+same byte-for-byte rationale.
 """
 
 from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from spine_lite.effects import Effect, most_restrictive
+
+if TYPE_CHECKING:
+    from spine_lite.manifest import Manifest
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolCall:
+    """A planned tool invocation to classify.
+
+    Attributes:
+        tool: Tool name as declared in the manifest.
+        arguments: Free-form key/value arguments. Currently informational
+            only; future phases may use them to refine classification
+            beyond the manifest's declared effects.
+    """
+
+    tool: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Decision:
+    """The result of classifying a :class:`ToolCall`.
+
+    Attributes:
+        tool: Echoed from the input call.
+        effects: The full set of effect classes the call can produce, as a
+            canonically-ordered tuple (sorted by ``PRECEDENCE``). Tuple
+            rather than frozenset so equality and serialisation are
+            byte-stable.
+        most_restrictive: The dominant effect under
+            :data:`spine_lite.PRECEDENCE`. Always a member of ``effects``.
+        rationale: Human-readable explanation of why this effect set was
+            chosen. Format is canonical so byte-stable across runs.
+    """
+
+    tool: str
+    effects: tuple[Effect, ...]
+    most_restrictive: Effect
+    rationale: str
+
+
+def classify(tool_call: ToolCall, manifest: Manifest) -> Decision:
+    """Classify ``tool_call`` against ``manifest``.
+
+    Args:
+        tool_call: The planned invocation.
+        manifest: A validated :class:`Manifest` declaring the tool.
+
+    Returns:
+        A :class:`Decision` carrying the effect set, the dominant effect,
+        and a deterministic rationale.
+
+    Raises:
+        ManifestError: If the tool isn't declared in the manifest.
+
+    Examples:
+        >>> from spine_lite import Effect, Manifest, ToolDefinition
+        >>> manifest = Manifest(tools={
+        ...     "fetch": ToolDefinition(
+        ...         name="fetch",
+        ...         effects=(Effect.NETWORK, Effect.READ),
+        ...     ),
+        ... })
+        >>> decision = classify(ToolCall(tool="fetch"), manifest)
+        >>> decision.most_restrictive
+        <Effect.NETWORK: 'network'>
+        >>> decision.effects
+        (<Effect.NETWORK: 'network'>, <Effect.READ: 'read'>)
+    """
+    definition = manifest.get(tool_call.tool)
+
+    dominant = most_restrictive(definition.effects)
+    return Decision(
+        tool=tool_call.tool,
+        effects=definition.effects,
+        most_restrictive=dominant,
+        rationale=_rationale(tool_call.tool, definition.effects, dominant),
+    )
+
+
+def _rationale(
+    tool: str,
+    effects: tuple[Effect, ...],
+    dominant: Effect,
+) -> str:
+    """Format a deterministic rationale string."""
+    classes = ", ".join(sorted(e.value for e in effects))
+    return (
+        f"tool {tool!r} declares effects [{classes}]; "
+        f"dominant under PRECEDENCE is {dominant.value!r}"
+    )
+
+
+__all__ = ["Decision", "ToolCall", "classify"]

tests/unit/test_classifier.py

@@ -0,0 +1,180 @@
+"""Tests for the classifier (basic / unit).
+
+Property-based tests with hypothesis live in commit 5 alongside the
+authored fixtures. This file covers the core behaviour and the error
+paths.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from spine_lite import (
+    Decision,
+    Effect,
+    Manifest,
+    ManifestError,
+    Posture,
+    ToolCall,
+    ToolDefinition,
+    classify,
+)
+
+
+def _manifest(**tools: ToolDefinition) -> Manifest:
+    return Manifest(tools=dict(tools))
+
+
+# ---------- happy path ----------
+
+
+def test_classify_returns_declared_effects() -> None:
+    manifest = _manifest(
+        read_file=ToolDefinition(name="read_file", effects=(Effect.READ,)),
+    )
+    decision = classify(ToolCall(tool="read_file"), manifest)
+
+    assert decision.tool == "read_file"
+    assert decision.effects == (Effect.READ,)
+    assert decision.most_restrictive is Effect.READ
+
+
+def test_classify_collapses_to_dominant_effect() -> None:
+    manifest = _manifest(
+        fetch=ToolDefinition(
+            name="fetch",
+            effects=(Effect.NETWORK, Effect.READ),
+        ),
+    )
+    decision = classify(ToolCall(tool="fetch"), manifest)
+
+    assert decision.most_restrictive is Effect.NETWORK
+    assert set(decision.effects) == {Effect.NETWORK, Effect.READ}
+
+
+def test_classify_destructive_dominates() -> None:
+    manifest = _manifest(
+        nuke=ToolDefinition(
+            name="nuke",
+            effects=(
+                Effect.READ,
+                Effect.WRITE,
+                Effect.NETWORK,
+                Effect.DESTRUCTIVE,
+            ),
+        ),
+    )
+    decision = classify(ToolCall(tool="nuke"), manifest)
+    assert decision.most_restrictive is Effect.DESTRUCTIVE
+
+
+def test_classify_returns_canonical_effect_order() -> None:
+    """Decision.effects always uses PRECEDENCE order, not author order."""
+    manifest = _manifest(
+        t=ToolDefinition(
+            name="t",
+            effects=(Effect.READ, Effect.NETWORK, Effect.DESTRUCTIVE),
+        ),
+    )
+    decision = classify(ToolCall(tool="t"), manifest)
+    assert decision.effects == (Effect.DESTRUCTIVE, Effect.NETWORK, Effect.READ)
+
+
+def test_classify_rationale_is_human_readable() -> None:
+    manifest = _manifest(
+        t=ToolDefinition(name="t", effects=(Effect.NETWORK, Effect.READ)),
+    )
+    decision = classify(ToolCall(tool="t"), manifest)
+
+    assert "'t'" in decision.rationale
+    assert "network" in decision.rationale
+    assert "read" in decision.rationale
+
+
+def test_classify_rationale_is_byte_stable() -> None:
+    """Same inputs produce identical rationale strings."""
+    manifest = _manifest(
+        t=ToolDefinition(name="t", effects=(Effect.WRITE, Effect.READ)),
+    )
+    a = classify(ToolCall(tool="t"), manifest).rationale
+    b = classify(ToolCall(tool="t"), manifest).rationale
+    assert a == b
+
+
+def test_classify_ignores_arguments_in_phase_2() -> None:
+    """Phase 2 classifier doesn't refine on arguments; manifest is the spec."""
+    manifest = _manifest(
+        t=ToolDefinition(name="t", effects=(Effect.READ,)),
+    )
+    a = classify(ToolCall(tool="t", arguments={}), manifest)
+    b = classify(ToolCall(tool="t", arguments={"path": "/etc/passwd"}), manifest)
+    assert a.effects == b.effects
+    assert a.most_restrictive == b.most_restrictive
+
+
+def test_classify_with_posture_constrained_tool() -> None:
+    """Permitted_postures is stored on the definition; Phase 2 doesn't gate on it."""
+    manifest = _manifest(
+        write_file=ToolDefinition(
+            name="write_file",
+            effects=(Effect.WRITE,),
+            permitted_postures=(Posture.INTERACTIVE, Posture.AUTONOMOUS),
+        ),
+    )
+    decision = classify(ToolCall(tool="write_file"), manifest)
+    assert decision.most_restrictive is Effect.WRITE
+
+
+# ---------- error paths ----------
+
+
+def test_classify_raises_manifest_error_for_undeclared_tool() -> None:
+    manifest = Manifest(tools={})
+    with pytest.raises(ManifestError, match="not declared"):
+        classify(ToolCall(tool="ghost"), manifest)
+
+
+def test_classify_undeclared_tool_carries_name_in_message() -> None:
+    manifest = Manifest(tools={})
+    with pytest.raises(ManifestError) as exc_info:
+        classify(ToolCall(tool="missing_tool"), manifest)
+    assert "missing_tool" in str(exc_info.value)
+
+
+# ---------- determinism ----------
+
+
+def test_classify_is_deterministic_within_one_call() -> None:
+    manifest = _manifest(
+        t=ToolDefinition(name="t", effects=(Effect.SPAWN, Effect.NETWORK)),
+    )
+    call = ToolCall(tool="t")
+    decisions = [classify(call, manifest) for _ in range(10)]
+    assert all(d == decisions[0] for d in decisions)
+
+
+def test_decision_is_frozen() -> None:
+    decision = Decision(
+        tool="t",
+        effects=(Effect.READ,),
+        most_restrictive=Effect.READ,
+        rationale="example",
+    )
+    with pytest.raises(AttributeError):
+        decision.tool = "u"  # type: ignore[misc]
+
+
+def test_tool_call_is_frozen() -> None:
+    call = ToolCall(tool="t")
+    with pytest.raises(AttributeError):
+        call.tool = "u"  # type: ignore[misc]
+
+
+# ---------- public API ----------
+
+
+def test_decision_classify_toolcall_in_public_api() -> None:
+    import spine_lite
+
+    for name in ("Decision", "ToolCall", "classify"):
+        assert name in spine_lite.__all__