Commit Envelopes

Errors from the commit_envelopes: block — the two-phase-commit macro used to coordinate atomic changes across multiple entities.

21 error codes in this section.

`VERR_ENVELOPE_MISSING_START_ACTION`

Commit envelope missing start_action. A commit_envelopes entry has no start_action — the compiler cannot tell which action begins the two-phase-commit flow.

Impact: Compilation aborts; the envelope’s lifecycle rules are never generated.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    # start_action missing
    envelope_state: transfer

✓ Fixed

commit_envelopes:
  wallet_transfer:
    start_action: TRANSFER_START
    envelope_state: transfer

`VERR_ENVELOPE_INVALID_START_ACTION`

start_action does not exist. The start_action named in a commit envelope does not match any key under the top-level actions: block.

Impact: Compilation aborts — the referenced action doesn’t exist, so the envelope has nothing to trigger it.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    start_action: TRANFER_START   # typo — not declared under actions:

✓ Fixed

commit_envelopes:
  wallet_transfer:
    start_action: TRANSFER_START   # matches actions.TRANSFER_START

`VERR_ENVELOPE_MISSING_STATE`

Commit envelope missing envelope_state. A commit_envelopes entry has no envelope_state — the compiler doesn’t know which entity type tracks the envelope’s own prepare/commit/abort status.

Impact: Compilation aborts; the envelope has nowhere to record its own lifecycle state.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    start_action: TRANSFER_START
    # envelope_state missing

✓ Fixed

commit_envelopes:
  wallet_transfer:
    start_action: TRANSFER_START
    envelope_state: transfer

`VERR_ENVELOPE_INVALID_STATE`

envelope_state does not exist. The envelope_state named in a commit envelope does not match any key under the top-level state: block.

Impact: Compilation aborts — the envelope has no schema to store its lifecycle state in.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    envelope_state: trasfer   # typo — not declared under state:

✓ Fixed

commit_envelopes:
  wallet_transfer:
    envelope_state: transfer   # matches state.transfer

`VERR_ENVELOPE_MISSING_LIFECYCLE`

Commit envelope missing lifecycle section. A commit_envelopes entry has no lifecycle: block, so the compiler has no prepare/prepared/commit/abort events to wire the two-phase-commit flow to.

Impact: Compilation aborts; no lifecycle rules are generated for this envelope.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    start_action: TRANSFER_START
    envelope_state: transfer
    # lifecycle block missing

✓ Fixed

commit_envelopes:
  wallet_transfer:
    start_action: TRANSFER_START
    envelope_state: transfer
    lifecycle:
      prepare_event: TRANSFER_PREPARE
      prepared_event: TRANSFER_PREPARED
      commit_event: TRANSFER_COMMIT
      abort_event: TRANSFER_ABORT

`VERR_ENVELOPE_MISSING_LIFECYCLE_EVENT`

Required lifecycle event is missing. One of lifecycle.prepare_event, prepared_event, commit_event, abort_event, or timeout.tick_event is blank. All five are required once a lifecycle/timeout block is present.

Impact: Compilation aborts — the envelope can’t complete its state machine without every lifecycle event wired.

✗ Won't compile

lifecycle:
  prepare_event: TRANSFER_PREPARE
  prepared_event: TRANSFER_PREPARED
  commit_event: TRANSFER_COMMIT
  # abort_event missing

✓ Fixed

lifecycle:
  prepare_event: TRANSFER_PREPARE
  prepared_event: TRANSFER_PREPARED
  commit_event: TRANSFER_COMMIT
  abort_event: TRANSFER_ABORT

`VERR_ENVELOPE_EVENT_NOT_IN_REGISTRY`

Lifecycle event not declared in events:. A lifecycle.prepare_event / prepared_event / commit_event / abort_event / timeout.tick_event value doesn’t match any key under the top-level events: block.

Impact: Compilation aborts — the envelope references an event the compiler has never heard of.

✗ Won't compile

lifecycle:
  prepare_event: TRANSFER_PREPAR   # typo — not in events:
  prepared_event: TRANSFER_PREPARED
  commit_event: TRANSFER_COMMIT
  abort_event: TRANSFER_ABORT

✓ Fixed

lifecycle:
  prepare_event: TRANSFER_PREPARE   # matches events.TRANSFER_PREPARE
  prepared_event: TRANSFER_PREPARED
  commit_event: TRANSFER_COMMIT
  abort_event: TRANSFER_ABORT

`VERR_ENVELOPE_MISSING_TIMEOUT`

Commit envelope missing timeout section. A commit_envelopes entry has no timeout: block — the compiler doesn’t know how long to wait before auto-aborting a stuck prepare phase.

Impact: Compilation aborts; a two-phase-commit flow without a timeout could hang a participant’s shadow state forever.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    lifecycle: { ... }
    # timeout block missing

✓ Fixed

commit_envelopes:
  wallet_transfer:
    lifecycle: { ... }
    timeout:
      abort_after_seconds: 30
      tick_event: CLOCK_TICK

`VERR_ENVELOPE_INVALID_TIMEOUT`

timeout.abort_after_seconds must be > 0. timeout.abort_after_seconds is zero, negative, or missing/non-numeric (which parses as 0).

Impact: Compilation aborts — a zero-or-negative timeout would abort every envelope immediately.

✗ Won't compile

timeout:
  abort_after_seconds: 0   # or omitted entirely
  tick_event: CLOCK_TICK

✓ Fixed

timeout:
  abort_after_seconds: 30
  tick_event: CLOCK_TICK

`VERR_ENVELOPE_INVALID_CAUSAL_MODE`

causal_ordering.mode must be per_entity or none. causal_ordering.mode is set to a value other than the two supported modes, per_entity and none.

Impact: Compilation aborts — the runtime only knows how to enforce these two ordering modes.

✗ Won't compile

causal_ordering:
  mode: strict   # not a valid mode

✓ Fixed

causal_ordering:
  mode: per_entity
  cursor_field: /visible/causal/last_envelope_seq

`VERR_ENVELOPE_MISSING_CURSOR_FIELD`

cursor_field required when mode: per_entity. causal_ordering.mode is per_entity but no cursor_field is given — the runtime needs a field to track the last-seen envelope sequence per entity.

Impact: Compilation aborts — per-entity causal ordering can’t be enforced without a cursor field.

✗ Won't compile

causal_ordering:
  mode: per_entity
  # cursor_field missing

✓ Fixed

causal_ordering:
  mode: per_entity
  cursor_field: /visible/causal/last_envelope_seq

`VERR_ENVELOPE_NO_PARTICIPANTS`

Commit envelope has no participants. A commit_envelopes entry has an empty or missing participants: list — there’s nothing for the two-phase commit to coordinate.

Impact: Compilation aborts; an envelope with no participants has no work to prepare, commit, or abort.

✗ Won't compile

commit_envelopes:
  wallet_transfer:
    participants: []

✓ Fixed

commit_envelopes:
  wallet_transfer:
    participants:
      - name: source_wallet
        state: wallet
        entity_expr: intent.from_wallet_id

`VERR_ENVELOPE_PARTICIPANT_NO_NAME`

Participant missing name. A participant entry in a commit envelope has no name field.

Impact: Compilation aborts — participants are referenced by name elsewhere (error messages, staging/apply blocks); an unnamed participant can’t be identified.

✗ Won't compile

participants:
  - state: wallet
    entity_expr: intent.from_wallet_id

✓ Fixed

participants:
  - name: source_wallet
    state: wallet
    entity_expr: intent.from_wallet_id

`VERR_ENVELOPE_PARTICIPANT_DUPLICATE_NAME`

Duplicate participant name. Two participants in the same commit envelope use the same name.

Impact: Compilation aborts — the runtime can’t tell the two participants apart when tracking prepare/commit status.

✗ Won't compile

participants:
  - name: wallet
    state: wallet
    entity_expr: intent.from_wallet_id
  - name: wallet   # duplicate
    state: wallet
    entity_expr: intent.to_wallet_id

✓ Fixed

participants:
  - name: source_wallet
    state: wallet
    entity_expr: intent.from_wallet_id
  - name: dest_wallet
    state: wallet
    entity_expr: intent.to_wallet_id

`VERR_ENVELOPE_PARTICIPANT_NO_STATE`

Participant missing state. A participant entry has no state field — the compiler doesn’t know which entity type this participant mutates.

Impact: Compilation aborts; the participant’s staging/apply rules have no schema to validate against.

✗ Won't compile

participants:
  - name: source_wallet
    entity_expr: intent.from_wallet_id

✓ Fixed

participants:
  - name: source_wallet
    state: wallet
    entity_expr: intent.from_wallet_id

`VERR_ENVELOPE_PARTICIPANT_INVALID_STATE`

Participant state does not exist. A participant’s state value doesn’t match any key under the top-level state: block.

Impact: Compilation aborts — the participant references an entity type the compiler has never heard of.

✗ Won't compile

participants:
  - name: source_wallet
    state: wallett   # typo — not declared under state:

✓ Fixed

participants:
  - name: source_wallet
    state: wallet   # matches state.wallet

`VERR_ENVELOPE_PARTICIPANT_NO_ENTITY_EXPR`

Participant missing entity_expr. A participant entry has no entity_expr — the compiler doesn’t know which entity instance this participant resolves to at runtime.

Impact: Compilation aborts; the runtime has no expression to compute which entity ID to prepare/commit/abort.

✗ Won't compile

participants:
  - name: source_wallet
    state: wallet

✓ Fixed

participants:
  - name: source_wallet
    state: wallet
    entity_expr: intent.from_wallet_id

`VERR_ENVELOPE_PARTICIPANT_NO_STRATEGY`

visibility_gate missing strategy. A participant declares a visibility_gate: block but doesn’t set strategy. (Omitting visibility_gate entirely is valid — this only fires once the block is present.)

Impact: Compilation aborts — the runtime doesn’t know which visibility strategy to apply during the prepare phase.

✗ Won't compile

participants:
  - name: source_wallet
    visibility_gate: {}   # present but no strategy

✓ Fixed

participants:
  - name: source_wallet
    visibility_gate:
      strategy: shadow_state
      visible_path: /visible
      pending_path: /pending_envelopes

`VERR_ENVELOPE_PARTICIPANT_INVALID_STRATEGY`

visibility_gate.strategy must be shadow_state. A participant’s visibility_gate.strategy is set to something other than shadow_state — the only visibility strategy supported today.

Impact: Compilation aborts; the runtime has no implementation for any other strategy value.

✗ Won't compile

visibility_gate:
  strategy: all_fields   # not supported

✓ Fixed

visibility_gate:
  strategy: shadow_state
  visible_path: /visible
  pending_path: /pending_envelopes

`VERR_ENVELOPE_PARTICIPANT_NO_VISIBLE_PATH`

shadow_state requires visible_path. A participant uses visibility_gate.strategy: shadow_state but doesn’t declare visible_path — the field that holds the entity’s externally-visible (committed) state.

Impact: Compilation aborts — shadow_state has nowhere to publish committed values.

✗ Won't compile

visibility_gate:
  strategy: shadow_state
  pending_path: /pending_envelopes
  # visible_path missing

✓ Fixed

visibility_gate:
  strategy: shadow_state
  visible_path: /visible
  pending_path: /pending_envelopes

`VERR_ENVELOPE_PARTICIPANT_NO_PENDING_PATH`

shadow_state requires pending_path. A participant uses visibility_gate.strategy: shadow_state but doesn’t declare pending_path — the field that holds in-flight, not-yet-committed envelope changes.

Impact: Compilation aborts — shadow_state has nowhere to stage uncommitted values during the prepare phase.

✗ Won't compile

visibility_gate:
  strategy: shadow_state
  visible_path: /visible
  # pending_path missing

✓ Fixed

visibility_gate:
  strategy: shadow_state
  visible_path: /visible
  pending_path: /pending_envelopes

Scope & Execution Plan Projections