AdminConsole
Event catalog/iOS direction planning and navigation handoff
Application blueprint · event v1

route_plan.navigation_handed_off

Application-owned route planning session fact emitted after confirm_handoff reaches handed_off.

No provider event payload is claimed.

This versioned envelope is an application architecture contract derived from the published iOS direction planning and navigation handoff transition model. Keep provider request and response bodies behind their separately sourced API contracts.

Producer contract

One fact, 1 producing transition

The application accepts a command, checks its expected aggregate version and invariant set, commits exactly one new version, and records this fact in the same transaction.

CommandActorAllowed fromResultIdempotency
confirm_handoffNavigation adapterhandoff_pendinghanded_off

Persist the target acknowledgement once and let its separate lifecycle own later progress.

Envelope v1

Small, strict, and operationally complete

The outer envelope is closed to unknown fields. The data object is intentionally application-owned and must be versioned deliberately for real consumers.

eventIdstring

Globally unique immutable identity used to deduplicate delivery and replay.

required
eventTypestring

Names the application-owned fact. Consumers must reject or quarantine unknown values.

required
eventVersioninteger

Version of this event contract. Version 1 is the only published version in this catalog.

required
aggregateTypestring

Application aggregate that owns the transition.

required
aggregateIdstring

Stable application identity; do not substitute a mutable display label.

required
aggregateVersioninteger

Monotonically increasing aggregate version after the transition.

required
tenantIdstring

Application tenant boundary used for authorization and routing.

required
actorobject

Attributable actor type and application identity that caused or recorded the fact.

required
occurredAtstring · date-time

UTC time at which the underlying action occurred.

required
recordedAtstring · date-time

UTC time at which the application durably committed the event.

required
idempotencyKeystring

Stable key supplied by the producing command and retained across retries.

required
correlationIdstring

Identity shared by events and calls in one business journey.

required
causationIdstring | null

Event or command that directly caused this fact; null only for a root event.

required
dataobject

Application-owned, event-specific data. This catalog does not claim a Mappls provider payload shape.

required
Deterministic example

Fictional data, production-shaped controls

Examples contain no credential, precise real-world location, media, or personal identity. Replace the event-specific data only after defining its compatibility policy.

route_plan.navigation_handed_off · example
{
  "eventId": "evt_example_ios_direction_planning_handoff_route_plan_navigation_handed_off",
  "eventType": "route_plan.navigation_handed_off",
  "eventVersion": 1,
  "aggregateType": "route planning session",
  "aggregateId": "example-ios-direction-planning-handoff-001",
  "aggregateVersion": 1,
  "tenantId": "tenant_example",
  "actor": {
    "type": "Navigation adapter",
    "id": "actor_example"
  },
  "occurredAt": "2026-01-01T10:00:00.000Z",
  "recordedAt": "2026-01-01T10:00:00.125Z",
  "idempotencyKey": "cmd_example_0001",
  "correlationId": "corr_example_0001",
  "causationId": null,
  "data": {
    "resultingState": "handed_off",
    "command": "confirm_handoff",
    "evidenceBoundary": "application-owned-example"
  }
}
Consumer adapters

Deduplicate before side effects

These compact adapters show the mandatory type, version, aggregate-version, and event-ID gates. Store the projection and deduplication record atomically.

Idempotent consumer
export function consumeRoutePlanNavigationHandedOff(event, seen) {
  if (event.eventType !== "route_plan.navigation_handed_off" || event.eventVersion !== 1) return;
  if (seen.has(event.eventId)) return;
  if (!Number.isInteger(event.aggregateVersion) || event.aggregateVersion < 1) throw new Error("Invalid aggregateVersion");
  // Apply one idempotent application-side projection here.
  seen.add(event.eventId);
}
Delivery and replay

At-least-once delivery without duplicate business effects

01

Publish

Commit the aggregate transition and a transactional outbox row together; publish from the outbox after commit.

02

Order

Partition and serialize by aggregateId; reject stale aggregate versions at the projection boundary.

03

Deduplicate

Commit the consumer side effect and eventId receipt together.

04

Replay

Replay the immutable event with the same eventId. A consumer must not repeat its side effect when that eventId was already committed.

05

Unknown outcome

After a timeout, reconcile the aggregate and outbox before retrying the same idempotencyKey; do not mint a replacement command identity.

06

Privacy

Keep credentials, raw precise-location traces, media, and unnecessary personal data out of the envelope. Put governed references in data only when the application policy permits them.

Adjacent evidence

Trace the journey to sources and runnable behavior

These links ground adjacent Mappls capabilities. They do not promote this application envelope into a provider contract.