feat(sdk): rootsign.init() facade + ambient session context (ADR-012 W3)

[oabolade]

Workstream 3 of Pre-Phase-2 Sprint A. Implements ADR-012: a three-call public
surface (init() → session() → wrap_tools()/@trace) with the explicit
API unchanged underneath. Explicit ctx=/client= always win; no existing
call site breaks.

Stacked after #20 (packaging split) and #22 (JSONL backend).

What's in it

• rootsign/sdk/facade.py — init() is synchronous and does no I/O, so
  it's safe at module scope and inside a running loop (notebooks, FastAPI
  startup). It validates args and stores a frozen _InitConfig singleton;
  identical re-init is a no-op, conflicting re-init raises. Zero-arg
  rootsign.init() resolves to script name / development / medium / jsonl.
• Ambient context in a ContextVar, set on session() entry and reset in
  its finally. _resolve_ctx_client() (explicit → ContextVar →
  RootSignNotInitializedError, new in errors.py carrying the two-line fix)
  is used by wrap_tools, @trace, both framework tracers, MCPProxyTracer,
  and decision capture. Resolution is deferred to invocation — decoration
  and tool wrapping normally happen at import time, before any session exists.
• rootsign.session() — agent_id/client are now optional. First entry
  performs the lazy agent get-or-create and builds the backend's client,
  closing it on exit only when it built it.
• get_or_register_agent (registration.py), backend-dispatched: jsonl →
  jsonl_registry; postgres → INSERT ... ON CONFLICT (name, environment) DO NOTHING + SELECT. Attribute drift logs WARNING and keeps the stored
  values — mutating a registered agent is an admin operation, not a side
  effect of init().
• Migration 0005_agents_name_env_unique (the sprint's only schema
  change): drop uq_agents_name, add uq_agents_name_environment. Safe with
  no backfill — name is globally unique today, so every existing row already
  satisfies the strictly weaker composite key. The revision id is abbreviated
  because alembic_version.version_num is varchar(32).
• ManagedLocalIngestClient (client.py) — the postgres facade path has
  no caller-supplied AsyncSession, and LocalIngestClient never commits
  (its callers do). This opens a short-lived AsyncSessionLocal per
  handle() and commits, the same per-call-session pattern as the HiTL poll
  loop. Every record is durable on return, which is what keeps
  rootsign approve and cross-process HiTL working under the facade.

Testing

479 passed, coverage 91% (facade.py 96%). New tests:

• tests/unit/test_facade.py — init validation/idempotency/zero-arg defaults,
  no-I/O assertion, loop-safety, resolution order, ContextVar reset (including
  on exception), quickstart→VALID, get-or-create across sessions, drift
  warning, HiTL-on-jsonl raising at first invocation, two concurrent
  sessions isolated, 8 parallel calls keeping monotonic sequences.
• tests/integration/test_facade_postgres.py — get-or-register idempotency,
  same name across environments, drift, the constraint swap asserted against
  pg_constraint, per-record commit visible from another connection, and
  init→session→trace→verify_session end-to-end on Postgres.
• tests/integration/test_facade_implicit_tracers.py — LangGraph, CrewAI, and
  MCPProxyTracer each driven with no ctx=/client= (ADR-012 exit
  criterion 6).

Two existing tests changed for the intended contract change: agent uniqueness
is now per (name, environment) (test_relationships.py, split into
same-env-rejected + cross-env-allowed), and CrewAITracer no longer rejects a
missing ctx at wrap time (test_crewai_tracer.py).

Note for reviewers

Existing deployments need rootsign-admin init to pick up migration 0005.

W4 (README quickstart, examples/quickstart-jsonl, demo.gif, the
docs/framework-support.md frozen-surface note, version bump to 0.2.0) is
deliberately not in this PR.

🤖 Generated with Claude Code