[AAASM-2641] ♻️ (python-sdk): Align _core exports + native tests to the thin shim

[Chisanan232]

Description

Python-side alignment to the thin pyo3 shim (Story AAASM-2561). Stacked on #79 (AAASM-2640), which delegates the native RuntimeClient to aa-sdk-client and removes the native synchronous query_policy round-trip.

• agent_assembly/__init__.py: drop PolicyResult / PolicyTimeoutError from the lazy export map, the optional-core __all__ list, and the TYPE_CHECKING block. The native _core surface is now RuntimeClient + GovernanceEvent.
• test/unit/test_init_exports.py: stub _core exposes only RuntimeClient / GovernanceEvent; assert the dropped symbols are not in agent_assembly.__all__.
• test/integration/test_native_core_runtime.py (opt-in, AAASM_RUN_NATIVE_CORE_TESTS=1): remove the query_policy timeout test and the query_policy call in the concurrency test; send_event / close still exercise the delegation. The mock runtime server keeps modelling the full wire protocol.
• Docs: README import example, architecture overview (two _core symbols; RuntimeClient is a thin shim that ships events), and the exceptions reference no longer mention the removed symbols. (ADR 0001-hook-architecture.md is left as a historical record.)

Note (stacked PR): the diff shows #79's commits until that PR merges; this PR's own change is the Python/docs alignment above. Base branch is master per repo convention.

Type of Change

• ♻️ Refactoring

Breaking Changes

• Yes (please describe below)

agent_assembly.PolicyResult and agent_assembly.PolicyTimeoutError (native _core symbols) are removed. They had no pure-Python callers; documented policy checks use the httpx gateway client.

Related Issues

• Related JIRA ticket: AAASM-2641 (Story AAASM-2561, Epic AAASM-2552)

Testing

• uv sync + pytest green (418 passed, 10 skipped — native + optional-framework tests skip in a pure-Python install).
• ruff / mypy introduce no new findings vs master (changes only remove code + edit Markdown).

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated if needed
• All tests passing

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Chisanan232]

🤖 Claude Code — review result

CI: ✅ green (23 pass / 4 skip; unit + integration across macОS & Ubuntu, SonarCloud, codecov, benchmarks, PEP 561). BLOCKED is solely REVIEW_REQUIRED. Stacked on #79 — the diff shows #79's commits until it merges.

Scope vs AAASM-2641: ✅ complete — Python-side alignment to the thin shim.

• agent_assembly/__init__.py: PolicyResult/PolicyTimeoutError removed from the lazy export map, _OPTIONAL_CORE, and the TYPE_CHECKING block. Native _core surface is now RuntimeClient + GovernanceEvent.
• test_init_exports.py: now asserts the dropped symbols are absent from __all__ (positive guard, not just removal).
• Gated test_native_core_runtime.py: query_policy cases removed; send_event/close delegation retained.
• Docs (README / architecture / exceptions) no longer reference the removed symbols; ADR 0001 left as a historical record.
• FFI benchmark fixed to use a valid aa_core::AuditEntry payload (c0972d1) — it previously errored whenever the native module was built (skipped in CI hid it). With the native module built locally: construction ≈ 13.6 µs, enqueue ≈ 41.7 µs (target < 2 ms).

Notes: the Story line "preserve the sdk_bench criterion benchmark" has no direct analog here — python-sdk/rust/aa-ffi-python has no [[bench]]; the pytest FFI benchmark is the equivalent and is preserved + fixed. The criterion bench likely refers to the monorepo binding (Story 9, AAASM-2562).

Verdict: ✅ Ready to approve & merge after #79 (rebase onto master once #79 lands).

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud