Pārlūkot izejas kodu

docs: plan sync resolution completeness fix

Problem: execute_sync can run a handler after an explicitly incomplete structured resolution when the schema has no required fields.

Risk: the fix must preserve complete and legacy resolver behavior while keeping synchronous fallback unsupported.
zhenyu.hu 2 nedēļas atpakaļ
vecāks
revīzija
f6bb11e699

+ 48 - 0
docs/plans/todo-45.3-sync-resolution-completeness.md

@@ -0,0 +1,48 @@
+# Todo 45.3 Sync Resolution Completeness Plan
+
+**Status:** in_progress
+
+## Goal
+
+Keep synchronous and asynchronous event execution semantically aligned by rejecting a structured deterministic resolution that explicitly reports `complete=False`, even when the schema has no required fields.
+
+## Scope
+
+- Add a regression test for `execute_sync()` with an optional-only schema and an explicitly incomplete structured resolver result.
+- Return `INVALID_ARGUMENTS` with a stable incomplete-arguments error before invoking the handler.
+- Preserve complete structured results and legacy plain-dict resolver compatibility.
+- Do not add synchronous LLM fallback support in this fix.
+
+## Files
+
+- Modify: `src/agent_lab/application/events/kernel.py`
+- Modify: `tests/test_event_kernel.py`
+
+## Requirement Execution Loop
+
+### Plan
+
+1. Write a failing test proving the current sync path executes the handler for an explicitly incomplete result.
+2. Capture the completeness flag in `execute_sync()` and normalize it to the same invalid result used by the async path when no fallback can run.
+3. Run focused kernel tests, the full suite, and `git diff --check`.
+
+### Act
+
+- Use `EventArgumentResolution(arguments={}, complete=False)` with a schema whose fields are optional.
+- Track handler calls and assert the count remains zero.
+- Assert status is `INVALID_ARGUMENTS` and the error is `event arguments incomplete`.
+
+### Observe
+
+Confirm sync execution no longer treats schema-valid-but-incomplete resolution as executable, while complete and plain-dict resolvers remain unchanged.
+
+### Update
+
+- Re-run Todo 45 specification and quality reviews.
+- Mark Todos 45 through 45.3 done only after review and fresh verification.
+
+## Verification
+
+- `uv run pytest tests/test_event_kernel.py -q`
+- `uv run pytest`
+- `git diff --check`

+ 1 - 0
docs/plans/todos.md

@@ -77,6 +77,7 @@
 | 45 | in_progress | `docs/plans/todo-45-generic-event-kernel.md` | Build a generic event kernel with definition metadata, deterministic-first resolution, policies, execution ports, and result aggregation. | Kernel contract tests prove orchestration contains no built-in event-name branches and plugins share one pipeline. |
 | 45.1 | in_progress | `docs/plans/todo-45.1-event-kernel-boundary-hardening.md` | Harden JSON Schema validation, normalized failures, fallback raw arguments, async handlers, and existing EventAgent concurrency. | Standard schema tests and failure-path regressions pass; async handlers work through the kernel without sync-facade warnings. |
 | 45.2 | in_progress | `docs/plans/todo-45.2-event-fallback-semantics.md` | Restrict fallback to incomplete resolution, enforce JSON-type-sensitive raw consistency, and distinguish definition failures. | Complete-invalid arguments skip LLM; raw/parsed mismatch and broken schema references produce stable non-user-error results. |
+| 45.3 | in_progress | `docs/plans/todo-45.3-sync-resolution-completeness.md` | Make synchronous kernel execution reject explicitly incomplete deterministic resolution instead of invoking the handler. | A structured incomplete result with an optional-only schema returns `INVALID_ARGUMENTS`; the handler is not called and async behavior remains aligned. |
 | 46 | pending | `docs/plans/todo-46-configurable-tool-invocation-mode.md` | Add `dual_agent` and `chat_agent_tools` runtime modes on the shared event kernel. | Runtime tests prove mode-specific requests, direct execution, valid provider history, and dual-mode regression safety. |
 | 47 | pending | `docs/plans/todo-47-built-in-event-plugins.md` | Add terminate-session, device-volume, schedule, and web-search as built-in plugins on the generic event kernel. | Plugin contract tests cover valid, ambiguous, invalid, idempotent, and failure results for all four events. |
 | 48 | pending | `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. |