---
id: STATE-PFM-QRY-005
title: Explorer navigation session
object: DOM-PFM-QRY-002
product_area: platform
module: queries
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: live
    meaning: >-
      For twelve hours the owner can navigate the stored identity window and request edge extension
      or rebuilding.
  - name: expired
    meaning: 'Navigation has expired, but the retained console return state remains readable.'
  - name: purged
    meaning: The owner’s next session start removed the old row after seven additional days.
transitions:
  - from: live
    to: live
    trigger: The owner navigates beyond the retained window edge.
    guard: 'Explorer and dataset checks succeed, with scanning bounded to twenty thousand identities.'
    side_effects:
      - execution rebuilds or extends the window and retains at most two thousand identities
    who: the person who started the session
    provenance: observed
    source: >-
      services-platform:modules/explorer/services/navigation/navigation-sessions.ts:locateInNavigationSession
  - from: live
    to: expired
    trigger: The twelve-hour navigation lifetime ends.
    guard: The recorded expiry has passed.
    side_effects:
      - neighbor movement stops while return state remains available
    who: system (time)
    provenance: observed
    source: 'services-platform:modules/explorer/db/explorer-navigation-sessions.table.ts (expires_at)'
  - from: expired
    to: purged
    trigger: The owner starts another session after the cleanup cutoff.
    guard: The old row belongs to the same owner and is more than seven days past expiry.
    side_effects:
      - old owner-scoped session rows are removed
    who: system (on session creation)
    provenance: observed
    source: 'services-platform:modules/explorer/services/persistence/explorer-navigation-sessions.ts'
invalid:
  - from: expired
    to: live
    why: Expired navigation is not renewed; the caller starts another session from the list.
concurrency: >-
  Sessions are requester-specific. Two tabs for that requester can overwrite an extended window
  without a session version conflict. Stored positions can outlive edits to the records, whose pages
  load their current contents separately.
invariants:
  - INV-DOM-PFM-QRY-002-10
evidence:
  - >-
    services-platform at ad3f6a6: modules/explorer/db/explorer-navigation-sessions.table.ts;
    services/navigation/navigation-sessions.ts;
    services/persistence/explorer-navigation-sessions.ts; docs/explorer.md
---

# Explorer navigation session

## The Lifecycle

```mermaid
stateDiagram-v2
  state "live" as s0
  state "expired" as s1
  state "purged" as s2
  s0 --> s0
  s0 --> s1
  s1 --> s2
```

A navigation session preserves a bounded ordering of identities instead of copying business records or the whole result set.

## Transitions Explained

Interior movement reads stored positions. At an edge, the service executes the saved request again and replaces or extends the window under its scan limits.

## What Cannot Happen

Expiry stops navigation while preserving return state temporarily. Starting a later session performs owner-scoped cleanup.

## Concurrency and Timing

The retained window is stable locally, but edge queries can observe changed data or fail after access is withdrawn.