[AUTO-SPEC] Proposal: Document LockService concurrency protection in plan lifecycle spec #8096

New issue

Closed

opened 2026-04-13 03:30:45 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-13 03:30:45 +00:00

Owner

Spec Update Proposal

Discrepancy Type: Implementation details not reflected in spec → update spec to match (pending PR #8067 merge)

Context

PR #8067 (fix(concurrency): wire LockService into plan lifecycle — guard execute_plan and apply_plan) is currently open and awaiting merge. It fixes a critical race condition where LockService was implemented but never integrated into the plan execution path.

What's Being Implemented (PR #8067)

container.py:

Added _build_lock_service(database_url) factory function
Registered LockService as a providers.Singleton (shared advisory-lock state per process)
Injected lock_service into the plan_lifecycle_service Factory provider

plan_lifecycle_service.py:

Added lock_service: LockService | None = None parameter to __init__
execute_plan(): acquires plan-level advisory lock before critical work; releases in finally block
apply_plan(): same acquire/release pattern
Both methods raise LockConflictError if a concurrent session already holds the lock

What's Missing from the Spec

The spec documents the Plan Lifecycle (Action → Strategize → Execute → Apply) but does not document:

LockService as a concurrency protection mechanism — the spec should document that execute_plan() and apply_plan() are protected by advisory locks
LockConflictError — the error raised when concurrent execution is attempted on the same plan_id
LockService DI registration — its singleton lifecycle in the DI container
Concurrency semantics — that only one session can execute or apply a given plan at a time

Proposed Spec Changes

Location: Plan Lifecycle section → Execute phase and Apply phase subsections

Add a "Concurrency Protection" note to both the Execute and Apply phase descriptions:

Document that execute_plan() acquires a plan-level advisory lock
Document LockConflictError as the error raised on lock contention
Document that the lock is released in a finally block (guaranteed cleanup)
Add LockService to the DI Container documentation

Location: Architecture → DI Container section

Add LockService as a Singleton provider
Document its role in preventing concurrent plan execution/application

Timing

This proposal is contingent on PR #8067 being merged. Once merged, a spec PR should be created to document these concurrency semantics.

Impact

Milestone: v3.8.0 (concurrency fix)
Spec sections: Plan Lifecycle → Execute, Plan Lifecycle → Apply, Architecture → DI Container
Priority: Medium (important for implementors to understand concurrency model)

Approval

This proposal is pre-emptive — it will be acted upon once PR #8067 is merged. Please approve this proposal by commenting "Approved" or "LGTM" to authorize the spec PR creation upon merge.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor

## Spec Update Proposal **Discrepancy Type**: Implementation details not reflected in spec → update spec to match (pending PR #8067 merge) ### Context PR #8067 (`fix(concurrency): wire LockService into plan lifecycle — guard execute_plan and apply_plan`) is currently open and awaiting merge. It fixes a critical race condition where `LockService` was implemented but never integrated into the plan execution path. ### What's Being Implemented (PR #8067) **`container.py`**: - Added `_build_lock_service(database_url)` factory function - Registered `LockService` as a `providers.Singleton` (shared advisory-lock state per process) - Injected `lock_service` into the `plan_lifecycle_service` Factory provider **`plan_lifecycle_service.py`**: - Added `lock_service: LockService | None = None` parameter to `__init__` - `execute_plan()`: acquires plan-level advisory lock before critical work; releases in `finally` block - `apply_plan()`: same acquire/release pattern - Both methods raise `LockConflictError` if a concurrent session already holds the lock ### What's Missing from the Spec The spec documents the Plan Lifecycle (Action → Strategize → Execute → Apply) but does not document: 1. **`LockService` as a concurrency protection mechanism** — the spec should document that `execute_plan()` and `apply_plan()` are protected by advisory locks 2. **`LockConflictError`** — the error raised when concurrent execution is attempted on the same `plan_id` 3. **`LockService` DI registration** — its singleton lifecycle in the DI container 4. **Concurrency semantics** — that only one session can execute or apply a given plan at a time ### Proposed Spec Changes **Location**: Plan Lifecycle section → Execute phase and Apply phase subsections Add a "Concurrency Protection" note to both the Execute and Apply phase descriptions: - Document that `execute_plan()` acquires a plan-level advisory lock - Document `LockConflictError` as the error raised on lock contention - Document that the lock is released in a `finally` block (guaranteed cleanup) - Add `LockService` to the DI Container documentation **Location**: Architecture → DI Container section - Add `LockService` as a `Singleton` provider - Document its role in preventing concurrent plan execution/application ### Timing This proposal is **contingent on PR #8067 being merged**. Once merged, a spec PR should be created to document these concurrency semantics. ### Impact - Milestone: v3.8.0 (concurrency fix) - Spec sections: Plan Lifecycle → Execute, Plan Lifecycle → Apply, Architecture → DI Container - Priority: Medium (important for implementors to understand concurrency model) ### Approval This proposal is pre-emptive — it will be acted upon once PR #8067 is merged. Please approve this proposal by commenting "Approved" or "LGTM" to authorize the spec PR creation upon merge. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor

HAL9000 referenced this issue

2026-04-13 03:31:06 +00:00

[AUTO-SPEC] Status: Specification Update (Cycle 2) #8088

HAL9000 referenced this issue

2026-04-13 03:31:46 +00:00

[AUTO-HUMAN] Status: Human Liaison Report (Cycle 1) #8076