mirror of
https://github.com/firestar5683/StarPilot.git
synced 2026-11-08 13:33:42 +08:00
firestar5683
58427d61d9
Select qualified speed-limit sources, preserve acceptance and override decisions, and publish distinct control and display coordinates. Carry accepted and pending source identity with each displayed decision. Co-authored-by: firestarsdog <229254897+firestarsdog@users.noreply.github.com>
75 lines
4.5 KiB
Markdown
75 lines
4.5 KiB
Markdown
# Causal cruise-action contract
|
|
|
|
`action_arbitration` preserves the relationship between an input action and its
|
|
later cruise-speed effects. It does not infer a button press from a scalar speed
|
|
change, authorize control, read messages or change cruise speed. The runtime
|
|
adapter connects it to physical receipts, UI requests and the override policy.
|
|
|
|
The input adapter must establish real action identities and final ownership.
|
|
If a vehicle exposes only a scalar change without a reliable button/effect
|
|
association, this capability remains unresolved. A guessed frame window is not
|
|
a substitute for causal evidence.
|
|
|
|
## Lifecycle
|
|
|
|
1. Create `new_ledger(unique_session_id)` once for a session. Use that same session
|
|
for acceptance and action sequencing; never reuse it across drives.
|
|
2. `BeginAction` records a monotonically increasing action ID, its observed origin
|
|
and an explicit `context_id`. Origins distinguish a driver cruise action, another
|
|
driver action and an automatic operation. The context must bind the adapter's
|
|
accepted-limit and authority/policy episode. This ledger carries it unchanged;
|
|
the override policy must check current applicability independently.
|
|
3. `ResolveAction` supplies a final disposition after arbitration: unconsumed
|
|
driver intent, consumed by SLC, automatic or unrelated. `resolve_acceptance`
|
|
instead binds a matching final receipt from the actual acceptance reducer.
|
|
It checks session, action ID, action/decision timing and receipt consumption.
|
|
An acknowledgment, replay, missing receipt or errored decision cannot establish
|
|
final ownership. A final unconsumed receipt does not swallow a real cruise action.
|
|
4. `CruiseChange` supplies its own increasing effect ID, causal action ID, and
|
|
normalized previous/selected speeds. It emits immutable classification data,
|
|
including the original action time and context. Multiple effects can refer to
|
|
one action until explicitly completed. Effects may arrive after other actions
|
|
have begun or resolved; they keep their own origin.
|
|
5. `CompleteAction` releases the transaction after its effects have been resolved
|
|
or explicitly abandoned. Button release alone does not prove completion.
|
|
Effects arriving after completion are unresolved and cannot recreate intent.
|
|
|
|
Consumed confirmation/adoption transactions remain consumed regardless of delay;
|
|
there is no one-frame Boolean or elapsed-time guess. Automatic and unrelated
|
|
effects likewise cannot become driver intent. A first scalar sample, an unchanged
|
|
speed or an unknown origin never establishes a new driver selection. An effect
|
|
received before ownership resolution is explicitly unresolved and watermarked;
|
|
it is not retroactively emitted as fresh intent when resolution arrives later.
|
|
|
|
## Bounds and failure behavior
|
|
|
|
The ledger holds at most 128 active transactions. Explicit completion frees
|
|
capacity. Exhaustion latches `reset_required` without forgetting consumed actions.
|
|
Conflicting final dispositions, impossible origin/disposition pairs, malformed
|
|
events and reversed clocks also require a fresh session. Duplicate action/effect
|
|
IDs are acknowledged by status without reopening transactions or emitting an
|
|
effect twice. Foreign sessions cannot advance current watermarks or close actions.
|
|
|
|
Invalid state is inert and remains unchanged for diagnosis. A latched ledger emits
|
|
no classified changes. Callers must inspect `status`/`errors` and clear any pending
|
|
interpretation; lack of new data must not be treated as a retained control target.
|
|
The ledger has no actuator output or persistence proposal.
|
|
|
|
## Separate policy and adapter obligations
|
|
|
|
`DRIVER_INTENT` means a supplied, positively associated, unconsumed cruise change;
|
|
it does **not** mean that an SLC override is currently eligible. Both increases
|
|
and decreases remain visible. The ordinary above-limit override and qualified
|
|
stock-setpoint policies have different rules and must retain that distinction.
|
|
They must check current longitudinal authority, mode, display-only state, source
|
|
freshness, accepted/effective target, action context and origin eligibility before
|
|
using a classified change. Context changes must invalidate old applicability;
|
|
an action begun while inactive cannot become eligible merely because its effect
|
|
arrived after re-enable.
|
|
|
|
Offsets, cluster conversions, pedal behavior, suspension/rearm policy and vehicle
|
|
button handling are not implemented by this ledger. All speeds at this boundary
|
|
must use one documented normalized coordinate. The acceptance helper and tests
|
|
establish pure composition, not a complete physical causal association or a fix
|
|
deployed in the current controller.
|