Arrival is a contract, not a distance guess

859. Lesson identity

Module

2.12 — Navigation, maps, and vehicles

Lesson

Arrival is a contract, not a distance guess

Academic type

Integration

Schema type

practical

Order

3

Estimated time

35–45 minutes

This lesson combines map scale, spatial validation, vehicle state, destination-specific prerequisites, and consumer boundaries in one explicit arrival contract.

860. Learning objective

After this lesson, you can specify an arrival contract that names its spatial conditions, applicable navigation conditions, vehicle-state conditions, independently completable prerequisite or confirmation conditions, status transitions, emission rule, and consumers.

861. Why this matters

A distance threshold answers only one question: how near an entity is to a target. It does not prove that the entity entered a usable region, followed a valid approach when the destination requires one, reached an acceptable vehicle state, or satisfied an independent confirmation required before arrival can be accepted.

An arrival contract makes the applicable evidence visible to one evaluator. Other systems consume its result without inventing competing definitions. Dialogue, rewards, loading sequences, camera changes, and similar behaviors initiated by accepted arrival belong after the predicate, on the consumer side. They must not also be prerequisites for the arrival that initiates them.

862. Prior knowledge

You should already be able to distinguish a map representation from current world state, as covered in 2.12 L1 — A map is not the world state. You should also be able to model vehicle possession as an explicit authority handoff, as covered in 2.12 L2 — Vehicle possession is a state handoff. No navigation implementation is required for this lesson.

863. Core concept

Arrival is a predicate over the conditions that apply to a particular destination, not a universal checklist that every destination must satisfy. Every contract should define its instance identity, target identity, spatial acceptance, vehicle requirements, and world validity. It should also state whether navigation or an arrival prerequisite or confirmation event is required or not_applicable.

Use destination-specific rules:

• Contract instance: identify the particular active attempt so a cancelled or superseded attempt cannot later emit arrival.
• Target identity: identify the destination being evaluated.
• Spatial: require the relevant entity or anchor to be inside the accepted region, not merely close to its marker.
• Navigation: require an accepted route or approach only when the destination contract calls for it. Otherwise record not_applicable.
• Vehicle: require the applicable possession, control, movement, or stop state.
• Arrival prerequisite or confirmation event: include an event in the predicate only if it can complete independently of accepted arrival. Examples could include an independently reported gate-clearance confirmation or an approach-validation signal. If the event is initiated by accepted arrival, it is a consumer behavior and cannot be part of the predicate.
• World validity: verify that the target still exists, remains active, and belongs to the contract instance being evaluated.

The arrival evaluator has exclusive responsibility for the shared predicate, status transition, and one-time emission rule. A mission, marker, camera, dialogue, reward, or loading system is a consumer. It may react to the accepted result, but it must not reconstruct arrival with its own distance, trigger, vehicle-state, or completion test.

Predicate prerequisites versus consumers

Use this boundary test:

1. Ask whether the event can complete without an accepted arrival result.
2. If yes, it may be declared as an arrival prerequisite or confirmation when the destination requires it.
3. If no—because accepted arrival starts the event—the event belongs exclusively to a consumer.

For example, a loading sequence started by accepted arrival cannot be required to prove that arrival already occurred. The arrival evaluator emits acceptance first; the loading system then consumes that result and manages loading separately.

864. Status taxonomy

Use the following meanings consistently:

• pending: the active attempt remains valid, and a currently false condition may still become true during that attempt. Examples include approaching the region, slowing the vehicle, or waiting for an independent confirmation.
• rejected: the attempt has completed in a disallowed way or crossed a declared failure boundary, so retry or reset is required. A condition such as being outside the region is not automatically rejected during an ordinary approach; it becomes rejected only if a destination-specific transition rule declares the approach complete or disallowed.
• invalid: the contract cannot be evaluated as the active attempt because it is stale, cancelled, missing required identity, or superseded by another contract or target.
• accepted: all applicable predicate conditions passed for the active contract instance, and its one-time acceptance rule may fire.

The destination contract must declare any context-dependent transition. For example, outside_arrival_region may remain pending while the vehicle is approaching but become rejected after it crosses a one-way exit boundary or explicitly ends the attempt outside the region.

865. Mental model

Use the arrival contract matrix:

A conceptual evaluation might be:

if contract_missing OR contract_cancelled OR contract_superseded:
    status = invalid
else if target_missing OR target_does_not_match_contract:
    status = invalid
else if declared_failure_boundary_crossed:
    status = rejected
else:
    predicate = spatial_condition
                AND vehicle_condition

    if navigation_required:
        predicate = predicate AND navigation_condition

    if independent_confirmation_required:
        predicate = predicate AND independent_confirmation_complete

    if predicate:
        status = accepted
        emit_once_for_this_contract_instance()
    else:
        status = pending

This is a reasoning model, not a universal implementation. Each destination must declare its own failure boundaries and transition rules. Consumers own their responses to the result, not the definition of the result.

866. Concrete example

Suppose a destination marker identifies a loading area. The player drives toward it and comes within a small distance of the marker. Proximity alone is insufficient: the vehicle may be beside the loading region instead of inside it, may still be moving, may have the wrong control state, or may be approaching from a disallowed direction.

For this destination, the arrival contract might specify:

• the active contract instance and target identify the loading area;
• the vehicle anchor is inside the accepted loading region;
• a valid approach is required because the area has a defined entry direction;
• the player remains in VehicleControlled;
• vehicle speed is below the declared stop threshold;
• no additional independent confirmation is required, so that field is not_applicable;
• the target has not been cancelled or replaced;
• acceptance is emitted once for the active contract instance.

The loading interaction is not part of this predicate. It begins only after the loading system consumes the accepted arrival result. Dialogue, rewards, camera behavior, and any loading sequence remain consumer behavior for the same reason.

A different destination could require an independent gate-clearance confirmation produced by an access system before arrival is accepted. That confirmation is a valid prerequisite only if it does not depend on the arrival acceptance event. Another destination, such as an open parking region, could mark navigation and independent confirmation as not_applicable.

During an ordinary approach, a vehicle outside the accepted region is pending: outside_arrival_region because it can still enter. If the destination defines a one-way attempt and the vehicle crosses its exit boundary without entering correctly, the contract becomes rejected: approach_completed_outside_region. If the target is replaced, it becomes invalid: superseded_contract. If all applicable conditions pass, it becomes accepted, emits once, and its consumers may respond.

867. CONTRABAND

The verified CONTRABAND theme for this lesson is Keros arrival-distance. Use it only as a focused case-study slice: examine how an arrival decision can fail when distance is treated as the complete definition of arrival. Do not infer unprovided incident details, implementation history, dates, metrics, or production outcomes.

Ask of the Keros slice: What is the target? What spatial evidence is sufficient? Which vehicle or possession conditions matter? Is navigation required? Is there evidence of an independently completable prerequisite? Which systems consume the result? If the available evidence does not answer a field, record it as unspecified or not_applicable rather than inventing a rule. Do not classify an arrival-triggered behavior as a prerequisite.

868. Common mistakes

Letting consumers redefine arrival

A mission checks distance, a camera checks a trigger, and a vehicle system checks whether the vehicle stopped. These systems can disagree. The arrival evaluator must own the shared predicate; consumers own only their responses.

Creating a circular dependency

A loading sequence, dialogue, reward, or other behavior begins after accepted arrival, but the contract also requires that behavior to finish before accepting arrival. Neither side can proceed coherently. Keep arrival-triggered behavior on the consumer side. Include only independently completable prerequisites in the predicate.

Treating every false condition as rejected

Being outside the accepted region during an active approach is usually recoverable and therefore pending. Use rejected only after a declared disallowed completion or failure boundary that requires retry or reset. State the destination-specific transition instead of relying on the label alone.

Requiring the same conditions everywhere

A route condition may matter for a one-way entrance but not for an open area. An independent confirmation may matter at a controlled gate but not at a simple waypoint. Mark each optional field as required or not_applicable.

Using one unexplained radius

Map scale and destination geometry affect appropriate spatial evidence. Name the accepted region and relevant anchor instead of hiding the decision inside a universal radius.

Emitting acceptance every frame

Acceptance is a transition for one contract instance. The emission rule prevents dialogue, rewards, loading, camera behavior, or other consumers from restarting while the entity remains in place.

869. Guided practice

Create an arrival contract for one invented destination involving a player and a vehicle. Produce an arrival contract matrix and a six-case decision table. A field may be required, not_applicable, or unspecified, but every such choice needs a reason.

Step 1: Define identity and space

Name the contract instance, target, accepted region, and relevant player, vehicle, anchor, or interaction volume. Explain why distance to the marker alone is insufficient or what additional evidence would make a distance test meaningful.

Step 2: Specify predicate conditions

Write one testable rule for each applicable group:

• target identity and world validity;
• spatial acceptance;
• navigation or approach validity;
• possession and vehicle state;
• arrival prerequisite or confirmation.

For the prerequisite field, state whether the event can complete independently of accepted arrival. If accepted arrival initiates it, remove it from the predicate and list it later as consumer behavior. Do not invent a prerequisite merely to fill the matrix.

Step 3: Declare status transitions

Define at least four non-arrival outcomes, including:

• one recoverable spatial or approach condition that remains pending;
• one vehicle-state condition that remains pending or becomes rejected under a declared rule;
• one completed or disallowed attempt that becomes rejected and requires retry or reset;
• one stale, cancelled, missing, or superseded case that becomes invalid.

If an independent prerequisite applies, include its incomplete state as pending unless the destination declares a separate failure boundary. For every context-dependent classification, state the transition that changes the status.

Step 4: Define acceptance and consumers

State when the active contract instance becomes accepted and how the evaluator emits that result exactly once. List at least three consumers. For each consumer, identify what it may do after reading the result and what part of the arrival predicate it must not recreate. Place dialogue, rewards, loading sequences, and similar arrival-triggered events exclusively in this consumer section.

Step 5: Test edge cases

Evaluate these cases:

1. the vehicle is near the marker but still outside the accepted region during an active approach;
2. the vehicle is inside the region but still moving;
3. the player is outside the required vehicle possession state;
4. the target or contract instance is replaced during the approach;
5. an independently completable prerequisite is still incomplete, or the field is not_applicable;
6. all applicable conditions remain true for several consecutive frames.

Add one destination-specific failure boundary that converts an otherwise recoverable condition from pending to rejected. Revise the contract until each case has one explicit result and no consumer behavior appears inside the predicate.

870. Validation / evidence

Your evidence is an arrival contract matrix and a six-case decision table. It is complete when:

• the active contract instance, target identity, and world-validity conditions are explicit;
• the spatial region and relevant anchor are defined independently of a vague distance guess;
• navigation is required only where the destination calls for it, or is marked not_applicable;
• possession and vehicle-state requirements are testable;
• every arrival prerequisite can complete independently of accepted arrival, or is marked not_applicable;
• dialogue, rewards, loading sequences, and other arrival-triggered behaviors appear only as consumers;
• pending, rejected, invalid, and accepted follow the stated taxonomy;
• destination-specific boundaries explain any transition from pending to rejected;
• stale, cancelled, missing, or superseded contracts cannot produce accepted arrival;
• the evaluator has exclusive responsibility for the predicate and emission rule;
• at least three consumers read the shared result without duplicating the predicate;
• acceptance is emitted once per contract instance;
• all six edge cases can be evaluated without an unstated rule.

A reviewer should be able to answer: Which attempt and destination are active? What proves spatial acceptance? Which conditions may still recover? What requires retry? What invalidates the contract? Can every prerequisite finish without accepted arrival? Which behaviors occur only after acceptance? If any answer relies only on proximity or on an arrival-triggered event completing first, the contract is incomplete.

871. Key takeaways

• Arrival is a destination-specific contract, not a universal distance threshold.
• Only independently completable prerequisites may participate in the arrival predicate.
• Dialogue, rewards, loading sequences, and similar arrival-triggered behaviors belong exclusively to consumers.
• pending means the active attempt may still succeed; rejected requires retry or reset after a declared failure; invalid identifies a stale, cancelled, missing, or superseded contract.
• The arrival evaluator owns the predicate and one-time emission rule; consumers own their responses.
• Contract instance identity prevents stale attempts from producing accepted arrival.

872. Next lesson

Continue to 2.13 — Save and load. Carry the contract instance identity, current status, target identity, and one-time-emission state forward as candidates to evaluate in the next lesson's save-state inventory; do not assume that every candidate must be persisted.

873. Knowledge check