The Action Contract

An Action represents what an owner has done with a Finding: approved it (dispatching an executor), dismissed it, or initiated a drill-down conversation. Approvals write a new row to vsa-{stage}-avx-actions. The Action carries a copy of the Finding’s evidence so its audit record stands independently of subsequent Finding updates.

Field	Type	Semantics
action_id	String (AVX-ACT-{uuid})	Stable UUID, set on creation.
finding_id	String	Foreign key to the originating Finding. Never null.
created_by	String	The identity that created the Action: owner, dealer, fleet operator, or product engineer.
decided_by	Object	Who decided, from the verified token, never from the request body: kind is operator (fleet-operator standing for the Finding’s fleet, or platform-admin), engineer (a product-engineer member, for population-scoped items), user (any other person the approve check admits), or rule (an auto-approval rule); id is the token’s sub or {fleet_id}/{rule_id}. A missing or malformed value counts as "not an operator".
decision	String (enum)	approved, overridden (approved with changed parameters), auto_approved, or declined.
created_at	ISO-8601 UTC	Immutable creation timestamp.
updated_at	ISO-8601 UTC	Set on creation; updated on every status transition. Callers use this to surface staleness.
target_system	String (enum)	Which executor handles this Action: dms, vehicle-command, retail, none, chat, ios-owner, cms, or adp.
target_ref	String	The downstream system’s reference ID, populated by the executor after successful dispatch. For dms, this is the repair-order number.
status	String (state machine)	pending_execution → executed → in_progress → completed. Terminal states: cancelled (owner cancelled after approval, or DMS closed the repair order before the work was done), declined (downstream target refused — a refusal 4xx — or a guardrail blocked it), dismissed (owner tapped Dismiss before approving), failed (executor exhausted retries, or the request itself was malformed). dismissed is distinct from cancelled; declined is distinct from failed. See the failure model in The Executor Pattern.
action_kind	String (enum)	The intent: book_combined_visit, schedule_inspection, update_charging_schedule, file_warranty_pre, surface_recall, acknowledge_only and others for the flywheel agents; apply_cost_action, book_recall_service, ground_vehicle, submit_warranty_claim, book_fleet_service, move_vehicles, record_engineering_decision, issue_recall and issue_software_campaign for the Fleet Intelligence agents. Enum is test-pinned per executor.
parameters	JSON object	Executor-specific payload. For dms: {vin, service_center_id, service_type, customer_availability}. For retail: {model, variant, configuration_id}. For chat: {seed_finding_id}.
evidence[]	Array of objects	Copied from the originating Finding at approval time. Later Finding updates do not modify an approved Action’s evidence.
audit_trail[]	Array of objects	Immutable log of every status transition. Each entry carries at, by, from_status, to_status, optional note, and — on failure transitions — failure_kind (target_refused, executor_exhausted_retries, or executor_terminal_error) and retry_count.

Action lifecycle

1. Approval — An owner, fleet operator or product engineer approves a Finding, or a fleet’s auto-approval rule matches it. The Action row is written at pending_execution with decided_by and decision, then passes through registry.dispatch().

2. Guardrails — dispatch() refuses a guarded action kind that the required person did not decide (an operator for fleet kinds, a product engineer for engineering kinds), and complete_recall without a completed service record. A refused Action is recorded declined with the guardrail named; it never reaches an executor. See Guardrails in the dispatch path.

3. Dispatch — The executor calls the target system, sets target_ref on success, and transitions to executed or in_progress depending on whether the target confirms completion immediately or defers it.

4. Progress — For deferred targets such as a DMS repair order, incoming status events project forward: in_progress → completed. A repair order DMS closes from Draft, InProgress or AwaitingParts projects to cancelled, with the sentence "DMS closed the repair order before the work was done."

5. Terminal failure — A target that refuses the work sets declined. Exhausted retries or a malformed request set failed, which fires the dual escalation described in The Executor Pattern.

6. Dismissal — The owner taps Dismiss before approving. The route transitions a synthetic Action to dismissed, writes feedback to the demotion table, and closes the card.