6.8 KiB
#region AgentInvestigation.Cases [C:5] [TYPE ADR] [SEMANTICS agent,investigation,case,queue,policy,actions] @BRIEF Shared agentic investigation contract consumed by 036–047. @RELATION DEPENDS_ON -> [AgentTestStabilization.DataModel] @RATIONALE Failures, staleness and load findings need an evidence-led workstream, not a collection of isolated forms. Agent reasoning may plan and execute permitted work, while deterministic systems remain the authority for execution, validation and access control. @REJECTED Opening an agent chat for every failure — rejected because transient and duplicate failures create noise. Events enter a queue; an analyst explicitly opens the agentic case. @REJECTED Replacing deterministic runners, validators, schedulers or policy checks with LLM decisions — rejected because execution truth, safety and reproducibility must remain independently verifiable.
Investigation Queue
Deterministic producers emit the idempotent InvestigationSignal; only 047 consumes it to create or update an InvestigationQueueItem from a failed/inconclusive/blocked ScenarioRun, scenario staleness signal, baseline immutability violation, load circuit-breaker/consistency finding, or repeated automation failure.
Fields: id, source_type, source_id, scenario_id?, run_id?, logical_step_id?, severity, fingerprint?, active_episode_id?, evidence_summary, target_snapshot, execution_principal_fingerprint?, suggested_next_action, state, count, first_seen_at, last_seen_at, case_id?.
State: new | acknowledged | case_opened | suppressed | resolved. A matching occurrence updates one queue item only inside the active failure episode; a matching occurrence after the episode is resolved creates a new queue item. Creating a queue item never starts an AgentRun.
InvestigationCase and AgentThread
An analyst opens a queue item into one durable InvestigationCase. Fields: id, queue_item_id, status, source_snapshot, evidence_snapshot, owner_actor_id, agent_thread_id, opened_at, resolved_at?, final_disposition?, resolution_summary?.
Status: open | investigating | awaiting_approval | awaiting_external_change | verifying | resolved | accepted | reopened. A case owns a chat thread and may launch many 036 AgentRun instances; an AgentRun is a recoverable tool-execution session, never the long-lived business case itself.
TriageRecord is the compact audited projection of the current case disposition for Registry, Run Monitor and analytics. It never changes historical run truth.
Delegated AgentAction
Every tool use is an AgentAction with intent, canonical inputs, risk class, policy decision, target/environment, affected entity keys, side_effect_key?, precondition evidence, postcondition evidence, cleanup/reconciliation plan, actor/delegator, agent and tool versions, and linked approval gate if one is required.
Risk classes:
readanddiagnostic_run: agent executes autonomously within ACL and capacity policy.controlled_test_data_mutation: agent executes autonomously only in an authorized fixture scope with a lease, exact record keys, reconciliation plan and postcondition evidence.draft_writeandscenario_revision_write: agent may create WorkingDrafts and save immutable executable revisions after deterministic validation and delegated policy allow it.activate_current_revision,baseline_approval,automation_policy_write, and anyprod_mutation: require the applicable ActionApprovalGate unless an explicitly stronger delegated policy permits the exact operation.
No operation bypasses object ACL, environment policy, ActionRegistry mutation contract, capacity allocation, canonical validation, immutable revision creation, or ActionApprovalGate consumption. Failed cleanup moves the case to awaiting_external_change; it cannot be resolved silently.
DelegatedAuthorityPolicy
DelegatedAuthorityPolicy is server-owned and versioned. Fields: policy_id, scope {scenario_id?, dashboard_id?, team_id?, environment_ids?}, action_class, autonomous, allowed_environment_classes, allowed_fixture_ids?, allowed_record_key_patterns?, max_request_volume?, max_concurrency?, cleanup_required, may_activate_current_revision, required_permission, approval_required, effective_from, effective_to?, version.
Policy evaluation is deterministic and snapshots policy_id + version + decision on every AgentAction. autonomous=true never grants more authority than ACL or the action's mutation contract. approval_required=true always creates a payload-bound ActionApprovalGate. No client or agent may supply a policy decision.
InvestigationSignal
Producers publish one idempotent InvestigationSignal { source_type, source_id, scenario_id?, run_id?, logical_step_id?, severity, canonical_fingerprint?, evidence_refs, target_snapshot?, execution_principal_fingerprint?, occurred_at } through the outbox. Its dedup key is (source_type, source_id, canonical_fingerprint?); 047 maps it to the active Queue item/FailureEpisode. Producers include 037 comparison/immutability, 040 breaker/consistency, 041 impact/deprecation, 042 staleness, 044 terminal run and 046 automation attention events.
Process Boundary Matrix
| Process class | Agent role | Deterministic owner | Approval mode |
|---|---|---|---|
| reasoning, evidence search, hypothesis, plan | leads | case/event storage | delegated read policy |
| authoring verification logic (SQL/DSL/assertion/evaluation proposal) | compiles/proposes | 038 validation + 042 immutable revision | delegated policy; save never activates |
| declared runtime semantic evaluation | may reason inside bounded spec | 044 deterministic orchestration + DecisionPolicy | no mutation, no lifecycle ownership |
| query/compare/validate/index/health/fingerprint | consumes output | 037/038/040/041/044/046/047 engines | never agent-decided |
| diagnostic run and fixture experiment | proposes/executes | runner, capacity, mutation contract | delegated only in exact policy scope |
| revision save | may execute | 038 validation + 042 immutable revision | delegated policy |
| revision activation / automation adoption | may propose | 042/046 lifecycle and eligibility | policy or ActionApprovalGate |
| baseline publish, automation policy, PROD mutation | may propose | bound action consumer | ActionApprovalGate unless exact stronger policy |
| HumanCheckpoint and final case disposition | explains evidence | 044 checkpoint / 047 case CAS | authenticated analyst only |
UX Invariant
Investigation work opens a persistent case workspace with chat, evidence, tool timeline and inline action cards. It MUST NOT use a modal or a confirmation dialog as the primary workflow. An ActionApprovalGate and a RunHumanCheckpoint are inline cards with typed decisions; they remain distinct domain controls.
#endregion AgentInvestigation.Cases