From 4d6952d0ab69f2c9fadbecbb9963f44125d233be Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 23 May 2026 02:15:34 +0800 Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=93=9D=20(verify):=20Add=20F112=20ver?= =?UTF-8?q?ification=20report=20skeleton=20for=20AAASM-1202?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Skeleton report under verification-reports/F112-AAASM-1202.md linking back to the Story, Epic, and the 4 implementation sub-tickets with their PR numbers. Per-AC results appended in follow-up commits. AAASM-1219 --- verification-reports/F112-AAASM-1202.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 verification-reports/F112-AAASM-1202.md diff --git a/verification-reports/F112-AAASM-1202.md b/verification-reports/F112-AAASM-1202.md new file mode 100644 index 0000000..16b7851 --- /dev/null +++ b/verification-reports/F112-AAASM-1202.md @@ -0,0 +1,17 @@ +# F112 — Python SDK platform wheel distribution + +> Story: [AAASM-1202](https://lightning-dust-mite.atlassian.net/browse/AAASM-1202) +> Epic: [AAASM-1199](https://lightning-dust-mite.atlassian.net/browse/AAASM-1199) +> Verification sub-ticket: [AAASM-1219](https://lightning-dust-mite.atlassian.net/browse/AAASM-1219) +> Verified on: 2026-05-23 + +## Sub-ticket map → PRs + +| Sub-ticket | Scope | PR | +| --- | --- | --- | +| [AAASM-1215](https://lightning-dust-mite.atlassian.net/browse/AAASM-1215) | Configure maturin build backend | #53 | +| [AAASM-1216](https://lightning-dust-mite.atlassian.net/browse/AAASM-1216) | Redesign pyproject.toml extras + dependency-groups | #54 | +| [AAASM-1217](https://lightning-dust-mite.atlassian.net/browse/AAASM-1217) | Matrix wheel build + PyPI Trusted Publisher workflow | #55 | +| [AAASM-1218](https://lightning-dust-mite.atlassian.net/browse/AAASM-1218) | `ensure_runtime()` fallback in `_install.py` | #56 | + +Per-AC verification below. From cd9ae7b3c66065722a150d19d9959a3763f65af5 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 23 May 2026 02:15:50 +0800 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=9D=20(verify):=20Record=20AAASM-1?= =?UTF-8?q?215=20maturin=20build-backend=20verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AC1 checklist with pass status for each maturin configuration element. Documents the deferred E2E maturin build (CI-only, depends on upstream agent-assembly's aa-core/aa-proto crates). Captures the pyo3 0.20 / Python 3.13 forward-compat caveat documented in memory — addressed by pinning the CI Python version to 3.12. AAASM-1219 --- verification-reports/F112-AAASM-1202.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/verification-reports/F112-AAASM-1202.md b/verification-reports/F112-AAASM-1202.md index 16b7851..710df33 100644 --- a/verification-reports/F112-AAASM-1202.md +++ b/verification-reports/F112-AAASM-1202.md @@ -15,3 +15,21 @@ | [AAASM-1218](https://lightning-dust-mite.atlassian.net/browse/AAASM-1218) | `ensure_runtime()` fallback in `_install.py` | #56 | Per-AC verification below. + +## AC1 — maturin configured in python-sdk with correct build targets (AAASM-1215, PR #53) + +**Status: ✅ Pass** + +| Check | Result | +| --- | --- | +| `[build-system].build-backend == "maturin"` | ✅ Verified — `python -c "import tomllib; print(tomllib.loads(open('pyproject.toml').read())['build-system']['build-backend'])"` returns `maturin` | +| `[build-system].requires` contains `maturin>=1.7,<2` | ✅ | +| `[tool.maturin].manifest-path == "rust/aa-ffi-python/Cargo.toml"` | ✅ Points at the existing PyO3 binding crate | +| `[tool.maturin].module-name == "agent_assembly._core"` | ✅ Matches `#[pyclass(module = "agent_assembly._core")]` in `rust/aa-ffi-python/src/lib.rs` | +| `[tool.maturin].include` bundles `agent_assembly/bin/aasm` into wheel | ✅ With `format = "wheel"` so the file appears only in the platform wheel, not in sdist | +| `[tool.hatch.build.targets.*]` removed | ✅ — no orphaned hatchling config | + +**Caveats** + +* End-to-end `maturin build --release` execution is deferred to CI (AAASM-1217) — local execution requires the upstream `aa-core` / `aa-proto` crates which the rust binding fetches from `AI-agent-assembly/agent-assembly`. +* Per memory: pyo3 0.20 on a Python 3.13 venv needs `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1`; the CI matrix pins `${{ env.PYTHON_VERSION }} = '3.12'` to sidestep this. From 9b0701338aa7119658e20df142168fa321d9b54a Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 23 May 2026 02:16:05 +0800 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=9D=20(verify):=20Record=20AAASM-1?= =?UTF-8?q?216=20pyproject=20extras=20+=20groups=20verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AC2 checklist with pass results for [runtime]/[all] extras and the PEP 735 lint/test/dev split. All three uv sync --group dry-runs pass; lock stays in sync at 84 packages. Notes the package-name discrepancy with the Story description (real name is agent-assembly, not agent-assembly-python). AAASM-1219 --- verification-reports/F112-AAASM-1202.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/verification-reports/F112-AAASM-1202.md b/verification-reports/F112-AAASM-1202.md index 710df33..645a3f0 100644 --- a/verification-reports/F112-AAASM-1202.md +++ b/verification-reports/F112-AAASM-1202.md @@ -33,3 +33,24 @@ Per-AC verification below. * End-to-end `maturin build --release` execution is deferred to CI (AAASM-1217) — local execution requires the upstream `aa-core` / `aa-proto` crates which the rust binding fetches from `AI-agent-assembly/agent-assembly`. * Per memory: pyo3 0.20 on a Python 3.13 venv needs `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1`; the CI matrix pins `${{ env.PYTHON_VERSION }} = '3.12'` to sidestep this. + +## AC2 — pyproject extras + dependency-groups split (AAASM-1216, PR #54) + +**Status: ✅ Pass** + +| Check | Result | +| --- | --- | +| `[project.optional-dependencies].runtime == []` | ✅ Empty marker extra — selection happens by platform wheel tag, not deps | +| `[project.optional-dependencies].all == ["agent-assembly[runtime]"]` | ✅ Self-reference aggregator | +| `[dependency-groups].lint` contains ruff + mypy | ✅ | +| `[dependency-groups].test` contains pytest + pytest-cov + pytest-rerunfailures + pytest-asyncio + pytest-benchmark | ✅ | +| `[dependency-groups].dev` slimmed via `{include-group = "lint"}` + `{include-group = "test"}` | ✅ No duplication of literals | +| `[dependency-groups].pre-commit-ci` sources mypy via `{include-group = "lint"}` | ✅ | +| `uv lock --check` after restructure | ✅ 84 packages resolved, lock in sync | +| `uv sync --group dev --dry-run` | ✅ resolves cleanly | +| `uv sync --group lint --dry-run` | ✅ resolves cleanly | +| `uv sync --group test --dry-run` | ✅ resolves cleanly | + +**Caveats** + +* Project name is `agent-assembly` (not `agent-assembly-python` as the Story description references); the `all` extra correctly uses the actual package name. From c912697b10ee05b140c3a00b96f72bd9516c1a66 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 23 May 2026 02:16:26 +0800 Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=9D=20(verify):=20Record=20AAASM-1?= =?UTF-8?q?217=20release-python.yml=20structure=20verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AC3 checklist verifying every structural element of the release workflow: triggers, permissions, all 5 build jobs, publish job needs-gating, Trusted Publisher hookup, untrusted-input safety. Explicit "CI-only verifications" section enumerates what cannot be exercised locally (per-platform maturin build, OIDC handshake) and the one-time PyPI/GitHub-Environment setup needed before the first real release. AAASM-1219 --- verification-reports/F112-AAASM-1202.md | 29 +++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/verification-reports/F112-AAASM-1202.md b/verification-reports/F112-AAASM-1202.md index 645a3f0..c16b4ed 100644 --- a/verification-reports/F112-AAASM-1202.md +++ b/verification-reports/F112-AAASM-1202.md @@ -54,3 +54,32 @@ Per-AC verification below. **Caveats** * Project name is `agent-assembly` (not `agent-assembly-python` as the Story description references); the `all` extra correctly uses the actual package name. + +## AC3 — release-python.yml: matrix build + PyPI Trusted Publisher (AAASM-1217, PR #55) + +**Status: ✅ Pass (structure) / ⏳ Deferred to CI (E2E execution)** + +| Check | Result | +| --- | --- | +| Workflow triggers on `v*.*.*` tag push | ✅ | +| Workflow has `workflow_dispatch` for dry-run | ✅ with `dry-run: true` default input | +| Top-level `permissions: id-token: write` set | ✅ Required for PyPI Trusted Publisher OIDC | +| 5 build jobs present | ✅ `build-sdist`, `build-linux-x86_64`, `build-linux-aarch64`, `build-macos-arm64`, `build-macos-x86_64` | +| Per-job: download `aasm` binary before maturin build | ✅ Each platform job uses `gh release download` against `AI-agent-assembly/agent-assembly` | +| Each platform job uses `PyO3/maturin-action@v1` with platform target | ✅ | +| `publish` job has `needs:` listing all 5 build jobs | ✅ Verified via `assert set(d['jobs']['publish']['needs']) == {...}` | +| `publish` job is gated `if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')` | ✅ | +| `publish` step uses `pypa/gh-action-pypi-publish@release/v1` with no `password:` | ✅ Trusted Publisher OIDC, no stored token | +| `publish.environment.name == 'pypi'` | ✅ For Trusted Publisher registration matching | +| Untrusted-input safety: no `${{ github.event.* }}` interpolated into any `run:` shell | ✅ Repo name flows only via workflow-level `env:` | + +**One-time setup required outside the PR** (documented in PR #55's body): + +1. Register Trusted Publisher at https://pypi.org/manage/account/publishing/ for project `agent-assembly` referencing `AI-agent-assembly/python-sdk`, workflow `release-python.yml`, environment `pypi`. +2. Create GitHub Environment `pypi` in the repo settings. + +**CI-only verifications** (cannot run locally — owned by the CI matrix runners): + +* Actual `maturin build --release` per platform with `aasm` binary staged. +* Wheel platform tags inspected post-build (`manylinux_*`, `macosx_*`, not `none-any` except for sdist). +* Trusted Publisher OIDC handshake on dry-run via `workflow_dispatch` once the PyPI registration is in place. From 59b128516f76a8cc30853557e36df7b13fdead24 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 23 May 2026 02:16:45 +0800 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=93=9D=20(verify):=20Record=20AAASM-1?= =?UTF-8?q?218=20ensure=5Fruntime()=20verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AC4 checklist with pass status for all three resolution branches. Full SDK suite (380 passed, 11 skipped) confirms no regression from the new module. Captures a known follow-up: the [project.scripts] aasm Python entry-point would shadow the Rust sidecar on PATH, needs renaming in a separate ticket. AAASM-1219 --- verification-reports/F112-AAASM-1202.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/verification-reports/F112-AAASM-1202.md b/verification-reports/F112-AAASM-1202.md index c16b4ed..f5df8a8 100644 --- a/verification-reports/F112-AAASM-1202.md +++ b/verification-reports/F112-AAASM-1202.md @@ -83,3 +83,24 @@ Per-AC verification below. * Actual `maturin build --release` per platform with `aasm` binary staged. * Wheel platform tags inspected post-build (`manylinux_*`, `macosx_*`, not `none-any` except for sdist). * Trusted Publisher OIDC handshake on dry-run via `workflow_dispatch` once the PyPI registration is in place. + +## AC4 — `ensure_runtime()` install-time fallback (AAASM-1218, PR #56) + +**Status: ✅ Pass** + +| Check | Result | +| --- | --- | +| Module `agent_assembly/_install.py` exists | ✅ | +| `BINARY_NAME == "aasm"` | ✅ | +| `WHEEL_BUNDLED_BIN` resolves to `agent_assembly/bin/aasm` | ✅ — `Path(__file__).resolve().parent / "bin" / BINARY_NAME` | +| `INSTALL_HINT` lists pip [runtime], Homebrew tap, curl installer | ✅ | +| `ensure_runtime()` returns `shutil.which` match when on PATH | ✅ Test `test_ensure_runtime_returns_path_match_first` | +| `ensure_runtime()` returns `WHEEL_BUNDLED_BIN` when not on PATH but file present | ✅ Test `test_ensure_runtime_falls_back_to_wheel_bundled` | +| `ensure_runtime()` raises `RuntimeError(INSTALL_HINT)` when neither found | ✅ Test `test_ensure_runtime_raises_with_install_hint` | +| Lazy-imports compatibility (PEP 562 in `__init__.py`) preserved | ✅ Module is not added to `_LAZY_EXPORTS` — kept as direct-import `from agent_assembly._install import ensure_runtime` | +| Full SDK pytest suite | ✅ 380 passed, 11 skipped (pre-existing env-conditional skips) | + +**Caveats** + +* `_install.ensure_runtime()` is distinct from `runtime.find_aasm_binary()` — the former is a synchronous presence check, the latter manages full lifecycle (port probe + subprocess spawn). Both observe the same `agent_assembly/bin/aasm` wheel-bundled location. +* Known collision risk: `[project.scripts] aasm = "agent_assembly.cli.main:main"` creates a Python entry-point at `.venv/bin/aasm` that would shadow the Rust sidecar on PATH. Tracked as out-of-scope for F112; needs a follow-up to rename one of them (likely the Python CLI → `aasm-py`). From 034a663a3e8160aea89b040aacac2b52d2ebca42 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 23 May 2026 02:17:05 +0800 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=93=9D=20(verify):=20Add=20CI-only=20?= =?UTF-8?q?smoke=20test=20plan=20and=20final=20F112=20sign-off?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the post-merge smoke-test sequence that exercises the parts of F112 that cannot run locally (per-platform wheel installs, OIDC handshake, dry-run + tagged release). Final sign-off table marks all four sub-tickets static-pass and maps each to its corresponding CI smoke-test step. AAASM-1219 --- verification-reports/F112-AAASM-1202.md | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/verification-reports/F112-AAASM-1202.md b/verification-reports/F112-AAASM-1202.md index f5df8a8..dc0b7ff 100644 --- a/verification-reports/F112-AAASM-1202.md +++ b/verification-reports/F112-AAASM-1202.md @@ -104,3 +104,31 @@ Per-AC verification below. * `_install.ensure_runtime()` is distinct from `runtime.find_aasm_binary()` — the former is a synchronous presence check, the latter manages full lifecycle (port probe + subprocess spawn). Both observe the same `agent_assembly/bin/aasm` wheel-bundled location. * Known collision risk: `[project.scripts] aasm = "agent_assembly.cli.main:main"` creates a Python entry-point at `.venv/bin/aasm` that would shadow the Rust sidecar on PATH. Tracked as out-of-scope for F112; needs a follow-up to rename one of them (likely the Python CLI → `aasm-py`). + +## CI-only smoke-test plan (post-merge) + +These exercises run only after PRs #53..#56 land on master and the PyPI Trusted Publisher / GitHub Environment registration is in place. + +1. **Dry-run `workflow_dispatch` on master** of `release-python.yml` with `dry-run: true`. + - Confirm all 5 build jobs produce wheels (sdist `.tar.gz` + 4 platform `.whl`). + - Confirm `publish` job is skipped (because `github.event_name == 'workflow_dispatch'`, not `push`). +2. **Cut a pre-release tag** `v0.0.1-rc1` and push. + - Confirm the `publish` job runs and the OIDC token exchange with PyPI succeeds. + - Confirm wheels appear on PyPI (or TestPyPI if the workflow is wired to test index first). +3. **Sample installations** on each target platform: + - `pip install agent-assembly==0.0.1rc1` — SDK-only, no `agent_assembly/bin/aasm` in site-packages. + - `pip install 'agent-assembly[runtime]'==0.0.1rc1` on Linux x86_64 — wheel includes Linux binary. + - `pip install 'agent-assembly[runtime]'==0.0.1rc1` on macOS arm64 — wheel includes mac arm64 binary. +4. **`ensure_runtime()` end-to-end** inside each install: + - `python -c "from agent_assembly._install import ensure_runtime; print(ensure_runtime())"` returns the bundled binary path with the `[runtime]` install; raises `RuntimeError` with the install hint without it. + +## Final F112 sign-off + +| Sub-ticket | Static structural verification | E2E / smoke (deferred to CI) | +| --- | --- | --- | +| AAASM-1215 | ✅ | Covered by step 1 above | +| AAASM-1216 | ✅ | Covered by steps 3–4 above | +| AAASM-1217 | ✅ | Covered by steps 1–2 above | +| AAASM-1218 | ✅ (unit-tested) | Covered by step 4 above | + +All acceptance criteria pass for the parts that can be verified statically and via local unit tests. The remaining smoke-test items are scoped to CI under the post-merge plan above.