Work queue and concurrency

---

Purpose#

L3 EvidenceLayer contract for detector output (direction; as built: Finding finding.json 1.2.0) (as built: Findings), PSMPlant Situation Model events, shift sweeps, Ask sweeps, and backlog promotes arrive together. Without one queue architecture, L4 double-spends dual-family calls, races supersede, or silently drops work. This doc is the scheduler contract implementers must build.

---

Decision#

---

Priority (high → low)#

Exception attention exemption (09-portfolio.md) applies to emitted cards, not to skipping the queue — P0 still goes through kernel.

---

In-flight and dedupe rules#

enqueue(item)
  if item.kind == finding OR discovery candidate:
    if open DecisionCase for same condition_key in {running, awaiting_ports}:
      attach as supersede_candidate or drop (idempotent) — do not start second case
    if open L5 proposal for same condition_key (not accepted):
      new case may supersede only under kernel supersede rules
  if item.kind == shift_sweep:
    if shift_sweep for same shift_id already running or queued:
      drop duplicate (idempotent)
    if previous shift_sweep still in LLM stages:
      queue behind; do not start second LLM-heavy sweep
  if item.kind == discovery_event:
    coalesce events for same footprint neighbourhood within coalesce_window_ms

Coalesce window — registry soft knob (illustrative default 30s until site-locked).

---

Parallelism caps (registry, plant-scoped)#

Scanner-only work for a queued shift sweepOnce-per-shift whole-plant discovery pass may prepare shortlists while a FindingAs-built L3 detector output admitted to L4 (finding.json 1.2.0) runs LLM stages. LLM stages still respect max_concurrent_llm_stages.

---

Starvation and aging#

If a P5/P6 item waits longer than queue_aging_threshold (registry), bump one priority step once. Never bump above P1. Log queue_aged=true on the work item.

---

Fairness vs attention#

The queue decides what runs. Portfolio attention budget decides what emits to L5. A shift sweep may produce many ranked candidates; only max_candidates_to_runtime enter DecisionCases (08-discovery.md); over-budget results → hold / opportunity ledgerStore of every blocked candidate with gate id and later outcome if known, not silent discard without a ledger row.

---

Observability (required)#

Every enqueue / dequeue / merge / drop emits:

• work_item_id, kind, priority, plant_id, condition_key or shift_id
• correlation_id (propagates into DecisionCaseOne run unit: intake + snapshot + obligations + candidates + terminal and DecisionTraceAlways-on record: observed, context, action, policy, approval, outcome (and seam decisions))
• reason if dropped or merged

On-call watches: queue depth by priority, age of oldest P0/P1, shift-sweep miss rate (16-operations.md).

---

Rejected alternatives#

---

What would change this#

• Measured queue wait showing P0 starved → raise Finding parallelism or lower sweep LLM share.
• Plants need mid-shift full sweeps as P4 → registry; replay attention impact.

---

v1 slice vs later#

---

Change class#

Queue priorities and caps: data (registry). Changing “queue may skip a hard gateNever tunable, never backlog, never explored”: forbidden. Adding a new work-item kind: registry + this doc + replay of concurrency suites.