feat(decorator): support callables on subject and action fields (#45)

[amavashev]

Summary

Closes #45.

Widens the @cycles decorator so every previously-static field — six subject fields (tenant, workspace, app, workflow, agent, toolset), three action fields (action_kind, action_name, action_tags), and dimensions — now accepts a callable in addition to a constant. Callables are invoked with the decorated function's *args, **kwargs at reservation time, enabling per-call budget routing and dynamic action labeling.

@cycles(
    estimate=lambda req, workspace_id: req.tokens * 10,
    workspace=lambda req, workspace_id: workspace_id,        # per-call routing
    action_kind=lambda req, *_: f"llm.{req.provider}",       # dynamic label
    action_name=lambda req, *_: req.model,
    dimensions=lambda req, *_: {"region": req.region},
)
def run_request(req: ResponseRequest, workspace_id: str) -> Response: ...

Mirrors the existing estimate / actual callable contract and re-aligns the Python client with the Java client's SpEL behavior shipped in cycles-spring-boot-starter 0.2.1 (java#50).

Fallback semantics (preserved)

• Subject callables returning None fall through to the client-config default.
• action_kind / action_name returning None fall through to "unknown".
• action_tags / dimensions returning None are omitted from the request.
• Exceptions in user callables propagate fail-fast without creating a reservation.

Implementation

• New _resolve_value(val, args, kwargs) helper in lifecycle.py (mirrors _evaluate_amount).
• DecoratorConfig field types widened to T | Callable[..., T | None] | None.
• _build_reservation_body signature now accepts args / kwargs; threaded through both CyclesLifecycle.execute and AsyncCyclesLifecycle.execute.
• Public cycles(...) parameter types widened; docstring updated.

No protocol or wire-format changes — only the source of each field's value is widened.

Files

• runcycles/lifecycle.py, runcycles/decorator.py — implementation
• tests/test_lifecycle.py — three new test classes (TestCallableSubjectFields, TestCallableActionFields, TestCallableDimensions); existing _build_reservation_body calls updated for the new signature
• tests/test_decorator.py — end-to-end test asserting the captured reservation body
• README.md — new "Dynamic subject and action fields" section
• AUDIT.md — dated entry per project policy
• CHANGELOG.md — 0.4.0 entry
• pyproject.toml — version bump 0.3.0 → 0.4.0

Test plan

• python -m ruff check runcycles tests — clean
• python -m mypy runcycles — no issues
• python -m pytest --cov=runcycles — 382 passed / 5 skipped (live-server)
• Coverage: 99.38% overall; lifecycle.py and decorator.py both 100% (project floor 95%)
• Constant-string regression covered (test_constant_subject_field_regression, test_constant_action_kind_regression, test_constant_dimensions_regression)
• None fallback covered for subject, action, and dimensions paths
• Callable exception propagation covered (test_callable_exception_propagates)
• Parametrized sweep across all five non-workspace subject fields
• End-to-end decorator test asserts captured request body contains per-call values