awp-python 0.1.0a1__tar.gz → 0.1.0a3__tar.gz

awp_python-0.1.0a3/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0a3
+
+Targets specification revision `0.1-draft.9`.
+
+- `awp_sim`: standing approvals (AWP-APR-004), declared as `safety_policy.standing_approvals` with the approval feature; a submission within a grant is admitted without approval and its result names the grant's `approval_id`.
+- `awp`: `AsyncClient.advance` returns once every subscribed per-tick channel holds a frame of the new tick, which on a stream connection may follow the result (AWP-TIM-003). A `session.resume` answered `AWP_SESSION_UNKNOWN` closes the session and forgets its actions (AWP-SES-008). `respond_approval` takes `standing`.
+- `awp-sim demo` resumes after a lost connection, or opens a new session if the world no longer holds it.
+- `awp_sim`: an integer beyond 2^53-1 closes the session with reason `protocol_error` and the connection with code 1002 (AWP-CTL-009); a malformed frame on a stream connection closes it with code 1002 and `AWP_MALFORMED` (AWP-DAT-010); after a lockstep resumption every per-tick channel restarts with a resync keyframe at the current tick (AWP-TIM-009); after a reset the fresh frames precede the result (AWP-PRM-006).
+- `awp`: an integer beyond 2^53-1 ends the session with `session.close` and close code 1002; a malformed stream frame is dropped and its stream connection closed and re-established; frames with `resync` but not `keyframe` are malformed. While a lost stream connection is down, `AsyncClient.command` raises instead of sending inline (AWP-TRN-010). `ClientConnection.receive_frame` raises for a malformed frame, and `delivery()` reports each channel's frames and gaps.
+
+## 0.1.0a2
+
+Targets specification revision `0.1-draft.8`.
+
+- `awp_sim`: the world checks the arm against its envelope after every step; leaving it emits `envelope_violation` and fails the executing action with reason `envelope` (AWP-ENV-003). `World.disturb` and `Server.disturb` inject an external disturbance.
+- `awp_sim`: a stop during servo motion ends at the envelope's boundary instead of past it.
+- `conformance/`: reports for Core World in both time models and the evidence for their manual rows, with tests in `tests/test_evidence.py`.
+
+## 0.1.0a1
+
+First release, targeting specification revision `0.1-draft.7`.
+
+- The `ws` stream binding: `awp-sim serve --stream-binding ws` offers frames on a stream connection in the binary envelope, and `AsyncClient` uses it when offered, re-establishing it if only the stream drops (AWP-TRN-010..013).
+- Beyond Core, each enabled with `awp-sim serve --features`: `task`, `approval` (the `park` action; approvers connect with `--approver-token`), `blend`, `transfer`, `sim` (seeding, snapshot and restore, replay bundles with `--replay-dir`, and `awp-sim replay`), and `servo` (a command channel). `ClientConnection` gains `update_task`, `transfer`, `reset`, `snapshot`, `restore`, `respond_approval`, and `command`.
+- The lockstep session clock counts advances, so reset and restore, which now move the tick, never move it backward (AWP-TIM-013). Audit records hash frame payloads, not their base64 text.
+
+- `awp`: `ClientConnection.submit` refuses action types the session was not granted (AWP-AGT-003); `AsyncClient` treats three heartbeat intervals without a message from the world as a lost connection (AWP-SAF-002).
+- `awp_sim`: channels in modalities the agent did not declare are not granted (AWP-AGM-001); granted rates honor the agent's `max_obs_rate_hz` (AWP-AGM-002); a connection without a session is closed after at least 15 s (AWP-SES-012); `--max-duration-ms`. The demo agent does nothing when `move_to_pose` is not granted.
+
+## 0.1.0.dev0 — unreleased
+
+First implementation, targeting specification revision `0.1-draft.5`.
+
+- `awp`: sans-IO `ClientConnection`, asyncio `AsyncClient`, binary and inline frame codec, canonical schema validation (receiver and sender forms), the lifecycle transition table, clock synchronization.
+- `awp_sim`: sans-IO world engine for lockstep and streaming, simulated arm, WebSocket server with bearer authentication, audit log, trace recorder, in-process loopback, twelve scripted scenarios, and the `awp-sim` command.

{awp_python-0.1.0a1 → awp_python-0.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: awp-python
-Version: 0.1.0a1
+Version: 0.1.0a3
 Summary: Agent World Protocol client protocol layer and reference world for Python.
 Project-URL: Specification, https://www.agentworldprotocol.com
 Project-URL: Source, https://github.com/Hyperduality/awp-python
@@ -26,21 +26,24 @@ Python implementation of the [Agent World Protocol](https://www.agentworldprotoc
 - **`awp`** — the client protocol layer. `ClientConnection` is the agent side of AWP as a sans-IO state machine; `awp.aio.AsyncClient` drives it over a WebSocket.
 - **`awp_sim`** — the reference world. A sans-IO world engine with a simulated arm, a WebSocket server, an audit log, and a scenario suite that records wire traces.
 
-It targets specification revision **`0.1-draft.7`**, pinned as the `spec/` submodule. This is an alpha: the API will change with the draft.
+It targets specification revision **`0.1-draft.9`**, pinned as the `spec/` submodule. This is an alpha: the API will change with the draft.
 
 ## Status
 
-The world and client target **Core World** and **Core Agent** for both time models, and the world the **sim** profile in lockstep, *self-assessed against 0.1-draft.7*: [awp-conformance](https://github.com/Hyperduality/awp-conformance) reports no failure against any configuration and leaves a few requirements untested. Every recorded trace also passes the spec's own checker, which verifies schemas, the action lifecycle table, idempotency, replay, and frame sequencing.
+![AWP: Core World, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_World%2C_conformant_0.1--draft.9-555)
+![AWP: Core Agent, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_Agent%2C_conformant_0.1--draft.9-555)
+
+The world is **Core World: AWP-conformant against 0.1-draft.9**, and the client, through its demo agent, **Core Agent: AWP-conformant against 0.1-draft.9**, each in both time models: [awp-conformance](https://github.com/Hyperduality/awp-conformance) reports no failure and nothing untested, and [`conformance/`](conformance/README.md) holds the reports and the evidence for their manual rows. The **sim** profile in lockstep is *self-assessed against 0.1-draft.9*: the suite reports no failure and leaves a few requirements untested. Every recorded trace also passes the spec's own checker, which verifies schemas, the action lifecycle table, idempotency, replay, and frame sequencing.
 
 | Implemented | Not implemented |
 |---|---|
 | Lockstep (`on_tick`, `any_session`) and streaming | `barrier` tick authority |
 | Inline and `ws` stream bindings; binary frame codec (all spec vectors) | Other stream bindings (`webrtc`, `webtransport`, `shm`, `grpc`) |
-| Full action lifecycle; preemption (`replace`, `queue`, `reject`, `blend`); idempotency | Standing approvals, grant expiry |
+| Full action lifecycle; preemption (`replace`, `queue`, `reject`, `blend`); idempotency | Grant expiry |
 | Watchdog and safe state, heartbeats, resumption with replay and acknowledgement | Multi-bind and shared control (one embodiment) |
-| Spatial, velocity, and rate envelopes (`command_check`) | Robotics profile (a simulated arm proves nothing physical) |
+| Spatial, velocity, and rate envelopes (`command_check`), monitored during execution | Robotics profile (a simulated arm proves nothing physical) |
 | Audit log with redaction and hash chain; e-stop; `world.reset` | |
-| Beyond Core (`--features`): task, approval, transfer, seeding, snapshots, replay bundles, a servo command channel | |
+| Beyond Core (`--features`): task, approval and standing approvals, transfer, seeding, snapshots, replay bundles, a servo command channel | |
 
 ## Quickstart
 
@@ -107,7 +110,7 @@ The connection tracks the action lifecycle against the spec's transition table,
 src/awp/            client protocol layer (sans-IO), asyncio adapter, frame codec, schemas
 src/awp/_spec/      schemas and lifecycle table bundled from spec/ (scripts/sync_spec.py)
 src/awp_sim/        world engine, arm, server, audit log, loopback, scenarios, CLI
-spec/               agent-world-protocol, pinned at spec-v0.1-draft.7
+spec/               agent-world-protocol, pinned at spec-v0.1-draft.9
 scripts/            spec sync and trace checking
 ```
 

{awp_python-0.1.0a1 → awp_python-0.1.0a3}/README.md

@@ -5,21 +5,24 @@ Python implementation of the [Agent World Protocol](https://www.agentworldprotoc
 - **`awp`** — the client protocol layer. `ClientConnection` is the agent side of AWP as a sans-IO state machine; `awp.aio.AsyncClient` drives it over a WebSocket.
 - **`awp_sim`** — the reference world. A sans-IO world engine with a simulated arm, a WebSocket server, an audit log, and a scenario suite that records wire traces.
 
-It targets specification revision **`0.1-draft.7`**, pinned as the `spec/` submodule. This is an alpha: the API will change with the draft.
+It targets specification revision **`0.1-draft.9`**, pinned as the `spec/` submodule. This is an alpha: the API will change with the draft.
 
 ## Status
 
-The world and client target **Core World** and **Core Agent** for both time models, and the world the **sim** profile in lockstep, *self-assessed against 0.1-draft.7*: [awp-conformance](https://github.com/Hyperduality/awp-conformance) reports no failure against any configuration and leaves a few requirements untested. Every recorded trace also passes the spec's own checker, which verifies schemas, the action lifecycle table, idempotency, replay, and frame sequencing.
+![AWP: Core World, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_World%2C_conformant_0.1--draft.9-555)
+![AWP: Core Agent, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_Agent%2C_conformant_0.1--draft.9-555)
+
+The world is **Core World: AWP-conformant against 0.1-draft.9**, and the client, through its demo agent, **Core Agent: AWP-conformant against 0.1-draft.9**, each in both time models: [awp-conformance](https://github.com/Hyperduality/awp-conformance) reports no failure and nothing untested, and [`conformance/`](conformance/README.md) holds the reports and the evidence for their manual rows. The **sim** profile in lockstep is *self-assessed against 0.1-draft.9*: the suite reports no failure and leaves a few requirements untested. Every recorded trace also passes the spec's own checker, which verifies schemas, the action lifecycle table, idempotency, replay, and frame sequencing.
 
 | Implemented | Not implemented |
 |---|---|
 | Lockstep (`on_tick`, `any_session`) and streaming | `barrier` tick authority |
 | Inline and `ws` stream bindings; binary frame codec (all spec vectors) | Other stream bindings (`webrtc`, `webtransport`, `shm`, `grpc`) |
-| Full action lifecycle; preemption (`replace`, `queue`, `reject`, `blend`); idempotency | Standing approvals, grant expiry |
+| Full action lifecycle; preemption (`replace`, `queue`, `reject`, `blend`); idempotency | Grant expiry |
 | Watchdog and safe state, heartbeats, resumption with replay and acknowledgement | Multi-bind and shared control (one embodiment) |
-| Spatial, velocity, and rate envelopes (`command_check`) | Robotics profile (a simulated arm proves nothing physical) |
+| Spatial, velocity, and rate envelopes (`command_check`), monitored during execution | Robotics profile (a simulated arm proves nothing physical) |
 | Audit log with redaction and hash chain; e-stop; `world.reset` | |
-| Beyond Core (`--features`): task, approval, transfer, seeding, snapshots, replay bundles, a servo command channel | |
+| Beyond Core (`--features`): task, approval and standing approvals, transfer, seeding, snapshots, replay bundles, a servo command channel | |
 
 ## Quickstart
 
@@ -86,7 +89,7 @@ The connection tracks the action lifecycle against the spec's transition table,
 src/awp/            client protocol layer (sans-IO), asyncio adapter, frame codec, schemas
 src/awp/_spec/      schemas and lifecycle table bundled from spec/ (scripts/sync_spec.py)
 src/awp_sim/        world engine, arm, server, audit log, loopback, scenarios, CLI
-spec/               agent-world-protocol, pinned at spec-v0.1-draft.7
+spec/               agent-world-protocol, pinned at spec-v0.1-draft.9
 scripts/            spec sync and trace checking
 ```
 

awp_python-0.1.0a3/conformance/README.md

@@ -0,0 +1,86 @@
+# Conformance
+
+![AWP: Core World, AWP-conformant against 0.1-draft.9](https://img.shields.io/badge/AWP-Core_World%2C_conformant_0.1--draft.9-555)
+
+| Class | Configuration | Claim | Report |
+|---|---|---|---|
+| Core World | `awp-sim serve --mode lockstep` | Core World (lockstep): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`core-world-lockstep.json`](core-world-lockstep.json) |
+| Core World | `awp-sim serve` | Core World (streaming): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`core-world-streaming.json`](core-world-streaming.json) |
+| Core World + sim | `awp-sim serve --mode lockstep --features task,approval,blend,transfer,sim --approver-token awp-sim-approver` | Core World + sim (lockstep): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`features-lockstep.json`](features-lockstep.json) |
+| Core World | `awp-sim serve --features task,approval,blend,transfer,servo --stream-binding ws --approver-token awp-sim-approver --approval-timeout-ms 5000` | Core World (streaming): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`features-streaming.json`](features-streaming.json) |
+| Core Agent | `awp-sim demo`, lockstep manifest | Core Agent (lockstep): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`core-agent-lockstep.json`](core-agent-lockstep.json) |
+| Core Agent | `awp-sim demo`, streaming manifest | Core Agent (streaming): AWP-conformant against 0.1-draft.9 (awp-conformance 0.1.0a3) | [`core-agent-streaming.json`](core-agent-streaming.json) |
+
+Each report, from awp-conformance 0.1.0a3 against awp-python 0.1.0a3, has no failure and nothing untested; the evidence for its `manual` rows follows (AWP-CNF-005). The feature configurations cover every feature awp-sim offers; `sim` and `servo` need separate runs, since `sim` is lockstep-only and `servo` streaming-only. The streaming one shortens `approval_timeout_ms` so the suite can wait out a timeout (AWP-APR-003).
+
+## Reproduce
+
+```bash
+pip install --pre awp-python awp-conformance
+curl -LO https://raw.githubusercontent.com/Hyperduality/awp-conformance/v0.1.0a3/fixtures/awp-sim.json
+awp-sim serve --mode lockstep &          # or `awp-sim serve` for streaming
+export AWP_SIM_PID=$!
+awp-conformance world ws://127.0.0.1:8710 --fixture awp-sim.json --out report/
+```
+
+For the feature configurations, serve with the flags in the table and use `fixtures/awp-sim-features.json` (and `--profile sim` in lockstep). The fixture's e-stop hooks signal `$AWP_SIM_PID`; without it the e-stop test is skipped and AWP-EVT-002 is reported untested. The agent claims test the demo agent, which is written on the `awp` client, against the suite's harness world:
+
+```bash
+awp-sim manifest --mode lockstep > manifest.json        # or --mode streaming
+echo '{"proprio": {"p_m": [0, 0, 0.4], "v_mps": [0, 0, 0]}, "arm_state": {"phase": "idle", "target_m": null, "action_id": null}}' > frames.json
+awp-conformance agent --manifest manifest.json --frames frames.json --out report/ -- awp-sim demo --url '{url}' --token '{token}'
+```
+
+The tests cited below run in this repository's CI:
+
+```bash
+uv run pytest tests/test_frames.py tests/test_evidence.py
+```
+
+## Manual evidence
+
+### AWP-DAT-002, AWP-TRN-009 — latest-wins delivery (streaming)
+
+- **Drop policy.** Each connection's send queue (`_Outbox`, [`src/awp_sim/server.py`](../src/awp_sim/server.py)) holds at most one unsent frame per latest-wins channel and replaces it when a newer one is produced; control messages and reliable frames queue in order, so a stalled latest-wins channel delays them by at most its one pending frame. A peer that stops reading is disconnected at 10,000 pending items rather than buffered without limit.
+- **Stalled-receiver test.** `test_a_stalled_receiver_holds_one_frame_per_latest_wins_channel`: 1,000 `proprio` frames and 10 `arm_state` frames are produced while nothing drains the queue; one `proprio` frame, the newest, and all 10 `arm_state` frames remain, in order.
+
+### AWP-DAT-001, AWP-DAT-009 — loss accounting at the receiver (Core Agent, lockstep)
+
+In streaming the suite reads the agent's loss accounting from its `obs.report`; lockstep sessions send none, so the rows are `manual` there.
+
+- `test_the_receiver_counts_seq_gaps_as_loss_but_not_the_gap_before_a_resync`: in each time model, frames skipping two `seq` values on one channel count two missing frames in `ClientConnection.delivery()`, and a resync frame after a gap of five on another counts none.
+- The client holds no delta state: each frame reaches the application whole, with its `keyframe` and `resync` flags.
+
+### AWP-AUD-005 — replay bundles (Core World + sim)
+
+`test_a_replay_bundle_reproduces_its_session` (`tests/test_features.py`) records a seeded lockstep session with a cancel and a second move as a replay bundle, replays it with `awp-sim replay`'s engine, and reproduces every transition and more than 80 frame hashes; a bundle with one tampered frame hash does not reproduce. `awp-sim serve --replay-dir DIR --mode lockstep --features sim` writes bundles, and `awp-sim replay BUNDLE` checks one.
+
+### AWP-DAT-008 — frame test vectors
+
+World and agent share one decoder, `awp.frames`. `test_vectors` (`tests/test_frames.py`) decodes every vector in `schemas/test-vectors/frames.json` of the `spec/` submodule, pinned at `spec-v0.1-draft.9`: the 10 valid vectors to the listed fields, and the 7 marked `expect_error` rejected with the listed error. `test_roundtrip_without_vendor` re-encodes the 8 valid vectors without an unknown extension or reserved bits byte for byte.
+
+### AWP-ENV-003 — envelope violations during execution
+
+After every simulation step the world checks the arm against its envelope: position within `aabb_m`, speed within `max_velocity_mps`. On leaving it, the world stops the arm, emits `world.event: envelope_violation` to every session, and fails the executing action with reason `envelope` once its safe abort completes. An external disturbance is injected with `World.disturb(offset_m)` (or `Server.disturb`).
+
+- `test_a_disturbance_during_execution_fails_the_action`: in each time model, a move is executing when the arm is pushed out of the envelope; the world emits `envelope_violation` and the move ends `failed` with reason `envelope`.
+- `test_commanded_motion_never_leaves_the_envelope`: 400 seeded random submissions, replacements, queued moves, stops, and cancels in each time model, checked after every advance; no violation is reported.
+- `test_servo_motion_never_leaves_the_envelope`: servo setpoints toward the walls, and stops during them.
+
+### AWP-UNI-001 — SI units and unit suffixes
+
+The fields awp-sim defines, reviewed:
+
+| Field | Where | Unit |
+|---|---|---|
+| `p_m` | `proprio` payload | m |
+| `v_mps` | `proprio` payload; `servo_arm` setpoints | m/s |
+| `target_m` | `arm_state` payload | m |
+| `max_velocity_mps` | `move_to_pose` params | m/s |
+| `phase`, `action_id` | `arm_state` payload | not physical |
+
+Every other field is defined by the specification's schemas. `test_world_defined_fields_carry_si_suffixes` collects every action parameter, channel schema field, and payload field across every feature, and fails on any field not reviewed as non-physical that lacks a unit suffix.
+
+### AWP-VER-009 — the draft revision is named
+
+The [README](../README.md) and the [awp-sim page](https://www.agentworldprotocol.com/adapters/awp-sim) name `0.1-draft.9`; `awp.SPEC_REVISION` is `"0.1-draft.9"`; the `spec/` submodule is pinned at the tag `spec-v0.1-draft.9`; each report records `"specification": "0.1-draft.9"` and its claim names the revision.