AdminConsole
Stateful journeys/App Widgets & Deep Links
statefulremote visual inspection aggregate
RealView · human observation and review

Entitled RealView remote inspection

Qualify paid RealView entitlement, open one browser-visible-token viewer attempt, handle the documented no-imagery signal safely, and turn human observations into a reviewed business record without inventing panorama metadata.

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
draft

Draft

The host owns an inspection purpose, external asset/site identity, Mappls Pin or coordinate, classification, and policy version.

02
entitlement_pending

Entitlement pending

Paid product access, exact host generation, browser credential class, restrictions, expiry, quota, and permitted use are being approved.

03
ready

Ready

The approved entitlement reference and bounded viewer configuration are current enough to open an attempt.

04
viewing

Viewing

One browser lifecycle owns the iframe, exact origin, location/radius configuration, ephemeral token-handle reference, listener, timeout, and disposal.

05
coverage_unavailable

Coverage unavailable

The exact Auth2 origin emitted the documented schema-valid status 204 for this attempt and configuration.

06
observation_recorded

Observation recorded

An inspector saved a bounded human checklist and notes linked to the viewer attempt, without claiming provider metadata or copying imagery.

07
review_pending

Review pending

An immutable observation set awaits a separately authorized reviewer under the declared purpose and policy.

08
acceptedterminal

Accepted

A named reviewer accepted the observation set for the exact business decision and policy version.

09
rework_required

Rework required

Review retained the prior observation and reason while requiring a new viewer attempt or alternate field evidence.

10
cancelledterminal

Cancelled

An authorized actor ended the inspection with a bounded reason while preserving prior attempts and observations.

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
create_inspectionHost application
new aggregate
draftrealview_inspection.created

One external inspection identity maps to one aggregate across retries.

request_entitlementInspector
draft
entitlement_pendingrealview_inspection.entitlement_requested

The product, environment, and account request identity is stable and contains no credential value.

confirm_entitlementPlatform administrator
entitlement_pending
readyrealview_inspection.entitlement_confirmed

Commit only entitlement reference, exact host, restrictions, and expiry metadata—not the issued token.

open_viewerInspector
readycoverage_unavailablerework_required
viewingrealview_inspection.viewer_opened

One command creates one immutable attempt and one ephemeral token-handle reference.

record_no_coverageHost application
viewing
coverage_unavailablerealview_inspection.coverage_unavailable

Accept one exact-origin, one-field status 204 result for the active attempt only.

record_observationInspector
viewing
observation_recordedrealview_inspection.observation_recorded

Hash the bounded checklist, notes, attempt, actor, and observation time.

submit_reviewInspector
observation_recorded
review_pendingrealview_inspection.review_requested

Freeze one observation set and enqueue review atomically.

acceptInspection reviewer
review_pending
acceptedrealview_inspection.accepted

Bind reviewer, reason, policy version, observation IDs, and command identity.

request_reworkInspection reviewer
review_pending
rework_requiredrealview_inspection.rework_requested

Retain the reviewed evidence and create one attributable rework decision.

record_entitlement_expiredHost application
readyviewing
entitlement_pendingrealview_inspection.entitlement_expired

Invalidate the active attempt once and discard only its ephemeral token handle.

cancelInspector
draftentitlement_pendingreadyviewingcoverage_unavailableobservation_recordedreview_pendingrework_required
cancelledrealview_inspection.cancelled

Commit actor, reason, cleanup, audit, and outbox exactly once.

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.

Inspection aggregate

Current purpose, asset/site and location identity, ownership, policy, state, and optimistic version.

inspectionIdexternalIdassetIdmapplsPinOrCoordinatepurposestateversion

Entitlement reference

Non-secret proof of the approved product generation and credential policy.

entitlementRefproducthostenvironmentcredentialClassexpiresAtrestrictionFingerprint

Viewer attempt

Immutable browser lifecycle and documented no-imagery outcome.

attemptIdconfigFingerprinttokenHandleRefopenedAtdisposedAtcoverageStatus

Observation and review

Human-authored evidence and separately authorized decision without copied imagery.

observationIdattemptIdchecklistnotesobservedAtreviewerdecisionpolicyVersion

Audit and outbox

Append-only transitions and exactly-once-in-effect downstream delivery.

eventIdaggregateVersionactoridempotencyKeyoutboxStatus
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    No server secret, browser token value, or complete token-bearing iframe URL is persisted, logged, analyzed, exported, or sent to a model.

  2. 2

    The exact selected origin and narrow documented schema are checked before any browser message reaches domain state.

  3. 3

    Status 204 proves only no imagery for one attempt and configuration; HTTP 200 and frame load prove only a delivered shell.

  4. 4

    Human observation is distinct from provider imagery, panorama metadata, measurement, currentness, and inspection acceptance.

  5. 5

    Imagery is not copied, screenshotted, exported, or retained without an explicit licensed product contract and purpose-specific policy.

  6. 6

    Every command is idempotent, compares expected version, and commits snapshot, audit, receipt, and outbox atomically.

  7. 7

    Reviewer acceptance is attributable and cannot be performed by the same automated actor that created the observation.

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.

Iframe returns a shell but no usable imagery

Detect

HTTP/frame load occurred without entitled viewing or the documented 204 signal.

Recover

Keep viewing unresolved until a bounded timeout, then record a host technical outcome rather than coverage or completion.

Message uses a lookalike origin or malformed payload

Detect

Exact origin, object shape, field count, or integer status validation fails.

Recover

Reject before domain processing, retain only a safe rejection metric, and never store the opaque payload.

Entitlement expires during viewing

Detect

The entitlement reference is expired/revoked or the account-approved broker reports token expiry.

Recover

Dispose the viewer, remove the ephemeral handle, return to entitlement pending, and retain the incomplete attempt.

Imagery is unavailable for the selected radius

Detect

The active attempt receives the documented exact-origin status 204 message.

Recover

Record configuration-specific no coverage and offer justified radius/location retry or alternate field evidence.

Reviewer cannot rely on the observation

Detect

Checklist is incomplete, limitations are missing, purpose changed, or stronger field evidence is required.

Recover

Request rework without overwriting the observation or prior viewer attempt.

Application restarts after an unknown command outcome

Detect

Client lacks acknowledgement while aggregate, command key, and outbox state are durable.

Recover

Reload and replay the same command key; never create another attempt or review decision to recover transport uncertainty.

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.

  • Entitlement request age, confirmation, expiry, revocation, and renewal without token values
  • Viewer open, time-to-first-useful-state, timeout, disposal, and superseded-attempt count
  • Exact-origin/schema rejection counts without raw payload retention
  • Status 204 rate by bounded configuration fingerprint, not generalized geography
  • Observation completeness, limitation flags, and review duration
  • Rework reason and new-attempt conversion
  • Credential-bearing URL log/screenshot/model-context prevention checks
  • Idempotency replay, optimistic conflict, audit, outbox backlog, retry, and dead-letter age
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.