AdminConsole
Stateful journeys/Search & Places
statefuladdress verification aggregate
Search & Places · purpose-bound evidence decision

Consented address verification

Normalize a declared service address, capture purpose-bound device evidence, apply an explainable versioned policy, require human review where evidence is weak, and retire precise data without erasing accountability.

Open implementation workshop Run verified appExplore lifecycle
Lifecycle state machine

Every state means something operational

A state is not a UI label. It determines which actor may act, what evidence exists, what may be retried, and how recovery proceeds.

01
entered

Entered

One external business reference, opaque subject reference, declared purpose, and raw address intent are recorded.

02
normalized

Normalized

The declared address maps to a provider-backed Mappls Pin, coordinate, components, confidence, and provenance.

03
capture_authorized

Capture authorized

A specific subject granted one purpose-bound, expiring, accuracy- and retention-governed evidence capture.

04
evidence_captured

Evidence captured

Immutable source identity, event and receipt time, coordinate, accuracy, provider context, and integrity hash are committed.

05
compared

Compared

A versioned policy records distance, effective uncertainty, thresholds, and its verify, reject, or review recommendation.

06
review_required

Review required

Weak, conflicting, or policy-sensitive evidence is assigned to an attributable human decision.

07
verifiedterminal

Verified

A policy or human decision accepted the declared address for the exact recorded purpose.

08
rejectedterminal

Rejected

Evidence did not establish the declared address, with reason, recommendation, actor, and appeal path retained.

09
cancelledterminal

Cancelled

Consent was withdrawn before evidence capture and no precise observation may be accepted.

Command → decision → event

Transitions are attributable and retry-safe

Commands express intent. The aggregate validates current state and invariants, commits one new version, and emits a fact in the same transaction.

Command & actorAllowed fromResultIdempotency strategy
enter_verificationApplication user
new aggregate
enteredaddress_verification.entered

Use the external application or case reference as durable business identity.

normalize_addressPolicy service
entered
normalizedaddress_verification.normalized

Bind normalized provider response to address-input hash and request identity.

authorize_captureApplication user
normalized
capture_authorizedaddress_verification.capture_authorized

Consent identity, text version, subject, purpose, expiry, and retention policy form one grant.

revoke_consentApplication user
capture_authorized
cancelledaddress_verification.consent_revoked

Commit withdrawal once and reject all later evidence under that grant.

capture_evidenceEvidence capture application
capture_authorized
evidence_capturedaddress_verification.evidence_captured

Use a device-generated source-event identity created before transmission.

comparePolicy service
evidence_captured
comparedaddress_verification.compared

Evidence hash, normalized-place version, and policy version identify the exact comparison.

verifyPolicy service
compared
verifiedaddress_verification.verified

Bind the terminal decision to comparison and aggregate version.

rejectPolicy service
compared
rejectedaddress_verification.rejected

Bind the terminal decision to comparison and aggregate version.

deferPolicy service
compared
review_requiredaddress_verification.review_required

Create one review case per comparison version.

review_verifyHuman reviewer
review_required
verifiedaddress_verification.verified

Reviewer decision records reason, independent evidence, and any override under one identity.

review_rejectHuman reviewer
review_required
rejectedaddress_verification.rejected

Reviewer decision records reason, independent evidence, and any override under one identity.

Durable records

Persist enough to recover and explain

Keep provider responses, business identity, state, events, and side-effect delivery distinct so each can be reconciled safely.

Verification aggregate

Business identity, purpose, lifecycle, selected evidence, comparison, decision, and version.

verificationIdexternalReferencesubjectReferencepurposestateversion

Normalized address

Provider-backed place identity and address interpretation.

mapplsPincoordinateformattedAddresscomponentsconfidenceprovenance

Consent grant

Attributable authority and privacy bounds for precise capture.

consentIdsubjectpurposetextVersiongrantedAtexpiresAtretentionUntilstatus

Evidence envelope

Immutable device observation with quality, timing, provenance, and integrity identity.

evidenceIdsourceEventIdeventTimereceivedAtcoordinateaccuracycontentHash

Decision record

Explainable recommendation, human disposition, override, and appeal context.

policyVersionthresholdsrecommendationoutcomeactorreason
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    One external business reference maps to one verification aggregate.

  2. 2

    Precise evidence is accepted only under active consent for the exact declared purpose and time window.

  3. 3

    Provider normalization and application policy are identified separately.

  4. 4

    An automated actor cannot override its own policy recommendation.

  5. 5

    Every terminal outcome retains evidence hash, policy version, actor, and attributable reason.

  6. 6

    Precise evidence can be redacted without erasing the audit trail or claiming that retained hashes can reconstruct it.

Failure and recovery

Know what to do before it breaks

Recovery changes durable truth only through the same rules as normal operation. A timeout is an unknown outcome, not evidence that nothing happened.

Capture arrives after consent expiry or withdrawal

Detect

Receipt or evidence event falls outside the committed grant window or grant status is revoked.

Recover

Reject it without retaining precise payload and require a fresh consent for another attempt.

Device evidence is replayed

Detect

Source-event identity or content hash already belongs to an accepted evidence envelope.

Recover

Return the original result for an idempotent retry or reject conflicting reuse as a security event.

Address candidate is ambiguous or evidence accuracy is weak

Detect

Provider confidence, device accuracy, separation, or policy combination enters the review band.

Recover

Request clarification or independent review; do not transform uncertainty into a definitive match.

Retention deadline passes

Detect

Precise evidence remains present beyond purpose, tenant, or jurisdiction policy.

Recover

Redact coordinate and place payloads, retain the minimum decision and integrity record, and audit completion.

Operational telemetry

Observe the journey, not merely HTTP status

Measure state age, event health, retries, reconciliation, and sensitive-data access alongside latency and error rate.

  • Normalization confidence, ambiguity, latency, and provider failures
  • Consent grant, expiry, withdrawal, and out-of-window capture attempts
  • Evidence accuracy, age, source integrity, replay, and mock-location risk
  • Distance and recommendation distribution by versioned policy
  • Review queue age, outcome, override rate, and supporting-evidence class
  • False-match, false-reject, correction, and appeal outcomes
  • Precise-data access, export, retention expiry, redaction, and legal hold
  • Idempotency conflicts, version conflicts, outbox backlog, and restart recovery
Grounded implementation

Contracts, repositories, workshops, tutorials, and runnable evidence

Only explicitly indexed evidence is linked. Empty sections are not backfilled with invented endpoints or package names.