Jelajahi Sumber

docs: plan strict batch key and scope cleanup

Problem: canonical keys use Python loose equality and released scope generations remain as unbounded tombstones.

Risk: token replacement must preserve concurrent in-flight sharing and late-store invalidation without retaining unique scope references.
zhenyu.hu 2 minggu lalu
induk
melakukan
0afc0062e2

+ 29 - 0
docs/plans/todo-48.3-strict-canonical-types-and-scope-token-cleanup.md

@@ -0,0 +1,29 @@
+# Todo 48.3 Strict Canonical Types and Scope Token Cleanup Plan
+
+**Status:** in_progress
+
+## Goal
+
+Close the final bounded batch findings: canonical identity must use strict JSON type equality, and releasing a scope must retain no permanent generation tombstone.
+
+## Scope
+
+- Compare JSON round-trip values recursively with exact types, matching kernel strictness; `IntEnum(1)`, `True`, `1`, and `1.0` must not be conflated unless a declared normalizer intentionally canonicalizes them.
+- Replace per-scope integer generations with globally unique generation tokens:
+  - first execution for a scope allocates a unique token;
+  - concurrent calls for the active scope share the token;
+  - `release_scope()` removes the scope token and associated maps;
+  - immediate reuse allocates a new token that can never equal an old late task token;
+  - late completion checks token equality and cannot store when the scope is absent or reused.
+- Assert thousands of execute/release cycles leave no scope-token, replay, or in-flight growth.
+
+## Files
+
+- Modify: `src/agent_lab/application/events/batch.py`
+- Modify: `tests/test_event_batch.py`
+
+## Verification
+
+- `UV_CACHE_DIR=.uv-cache uv run pytest tests/test_event_batch.py -q`
+- `UV_CACHE_DIR=.uv-cache uv run pytest`
+- `git diff --check`

+ 1 - 0
docs/plans/todos.md

@@ -91,6 +91,7 @@
 | 48 | in_progress | `docs/plans/todo-48-parallel-event-batches.md` | Execute multiple flat events with bounded parallelism, failure isolation, aggregation, and a terminal barrier. | Runtime tests prove independent concurrency, stable result order, isolated failures, and termination after sibling completion or timeout. |
 | 48.1 | in_progress | `docs/plans/todo-48.1-batch-canonical-replay-and-terminal-safety.md` | Canonicalize batch keys, make replay atomic and bounded, guarantee terminal grace after sibling timeout, enforce async timeout around sync handlers, and ensure termination has a farewell. | Normalized equivalents coalesce safely; in-flight duplicates execute once; scopes release cache; terminal runs after sibling timeout; blocking sync work cannot block the loop; search two-answer and tool-only farewell regressions pass. |
 | 48.2 | in_progress | `docs/plans/todo-48.2-outcome-cache-and-sync-resource-lifecycle.md` | Preserve full replay outcomes, generation-scope cleanup, invalid-key isolation, sync worker resource leases, and deduplicated result correlation/policy cardinality. | Invalid requests never inherit success; released scopes cannot late-store; timed-out sync work retains locks/slots until completion; terminal deadline flags replay exactly; duplicate payload IDs/messages stay correct and singular. |
+| 48.3 | in_progress | `docs/plans/todo-48.3-strict-canonical-types-and-scope-token-cleanup.md` | Align canonical-key equality with strict JSON types and replace retained generation tombstones with unique releasable scope tokens. | Enum/bool-like values never coalesce with integers; released scopes leave no retained token while late tasks still cannot store into a reused scope. |
 | 49 | pending | `docs/plans/todo-49-tool-mode-ui-session-restore.md` | Add UI mode selection, workspace/session restoration, and clear EventAgent applicability feedback. | Static/WebSocket tests prove requests, snapshots, loaded sessions, and audit context preserve the selected mode. |
 | 50 | pending | `docs/plans/todo-50-comparable-model-tool-metrics.md` | Record mode-aware model/tool spans and include EventAgent usage so both architectures can be compared fairly. | Persistence/API tests report agent, call kind, tokens, TTFT, tool latency, fallback usage, and total turn wall time without double counting. |
 | 51 | pending | `docs/plans/todo-51-comparison-matrix-closeout.md` | Add repeatable comparison fixtures, update project documentation, and close the experimental implementation. | Both modes pass the same scenario matrix; full tests, JS syntax, app import, and documentation checks pass. |