--- id: WF-PFM-CSH-001 title: Start the console and settle the working context trigger: A browser loads a console destination. product_area: platform module: console-shell revision: 1 status: draft design_intent: confirmed origin: >- services-platform:docs/security/console-authentication.md#Console initialisation (final acceptance 2026-10-10); react-console:docs/url-architecture.md#6. Tenant from the URL and #11 item 24 (decided by Andrew 2026-10-14; final acceptance 2026-10-15) implementation_evidence: observed source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 implements: - CAP-PFM-CSH-001 - CAP-PFM-CSH-004 - CAP-PFM-CSH-009 - CAP-PFM-CSH-010 - CAP-PFM-CSH-013 moves: - STATE-PFM-CSH-001 crosses: - SVC-PFM-CSH-console-shell inference: [] idempotency: >- Boot repeats reads on reload or Retry. Browser memory is replaced, and Security can perform its throttled stamp and grant settlement. concurrency: >- A cancelled boot stops applying its answer; tabs resolve independently and workspace memory follows the latest storage write. hops: - 'n': 1 actor_or_service: console action: Remove legacy browser tokens and verify sign-in configuration. anchor: 'react-console:lib/security-context/provider.tsx:boot' seam: sync on_failure: Stop with the missing-settings screen. left_inconsistent: No workspace content has mounted. observer: Person through setup guidance. provenance: observed source: >- react-console:lib/security-context/provider.tsx:boot (missingConfiguration) - 'n': 2 actor_or_service: console with Security's session endpoint action: Resolve the session using an in-memory token or refresh-cookie exchange. anchor: 'react-console:lib/auth/session.ts:resolveAccessToken' seam: sync on_failure: Navigate to sign-in with the safe return and expired-session reason. left_inconsistent: No console page has mounted. observer: Person through the sign-in destination. provenance: observed source: 'react-console:lib/security-context/provider.tsx:boot (toLogin)' - 'n': 3 actor_or_service: console action: >- Remove parked drafts owned by another person and load the current person’s workspace preference. anchor: >- react-console:lib/security-context/provider.tsx:boot (forgetDraftsNotOwnedBy, rememberedTenantFor) seam: sync on_failure: No local recovery is declared around draft cleanup. left_inconsistent: A thrown cleanup exception has no explicit recovery at this step. observer: No dedicated observer. provenance: observed source: 'react-console:lib/security-context/provider.tsx:boot' - 'n': 4 actor_or_service: 'Security (getMySecurityContext, strict)' action: >- Request the address workspace strictly; retain refusal outcomes for the gate and fall back when no usable context is returned. anchor: 'react-console:lib/security-context/boot.ts:bootSecurityContext' seam: sync on_failure: Continue through the preference-based context request. left_inconsistent: A refusal outcome can be held while boot chooses a presentation context. observer: Workspace gate consumes the retained outcome. provenance: test source: 'react-console:lib/security-context/boot.test.ts' - 'n': 5 actor_or_service: 'Security (getMySecurityContext, preference)' action: >- Request the preferred remembered workspace, retrying without a preference if that workspace is unavailable. anchor: 'react-console:lib/security-context/boot.ts:bootRemembered' seam: sync on_failure: >- Show no access for a final refusal, retry for other failures, or sign-in for session expiry. left_inconsistent: >- Security may already have settled grants or attempted an authentication stamp. observer: Person through boot states; Security logs authentication-stamp failure. provenance: observed source: >- react-console:lib/security-context/boot.ts:bootRemembered; services-platform:modules/security/services/access/security-context.ts:noteAuthentication - 'n': 6 actor_or_service: console action: >- For staff root or HQ arrival, remove the selected workspace while retaining a reachable workspace preference. anchor: >- react-console:lib/security-context/boot.ts:bootRemembered (isLandingPath, withoutStaffDefaultTenant) seam: sync on_failure: This step is a local computation with no failure handler. left_inconsistent: The workspace preference can remain while HQ holds no selected workspace. observer: No dedicated observer. provenance: test source: >- react-console:e2e/mock/staff-landing.mock.spec.ts#a staff member with a remembered tenant and a standing grant lands on /hq in HQ context - 'n': 7 actor_or_service: console action: >- Apply workspace memory and notices, retain the gate outcome and mount the context-keyed frame. anchor: 'react-console:lib/security-context/provider.tsx:boot (setPhase ready)' seam: sync on_failure: This step declares no local failure recovery. left_inconsistent: There is no shell business write to compensate. observer: Person through the mounted frame and notice. provenance: test source: >- react-console:e2e/controlled/tenant-unavailable.controlled.spec.ts#falls back to the default tenant, with a word of explanation, rather than refusing access - 'n': 8 actor_or_service: console (gates under the frame) action: >- Pass workspace addresses to entry, context-free paths to compatibility handling and staff without a workspace to HQ. anchor: >- react-console:app/(console)/layout.tsx:ConsoleLayout; components/console/hq/staff-context-gate.tsx:StaffContextGate seam: sync on_failure: The destination flow handles entry or compatibility failure. left_inconsistent: Hosted pages retain their own effects. observer: Person through the resulting gate or redirect. provenance: observed source: 'react-console:app/(console)/layout.tsx:ConsoleLayout' branches: - >- Demonstration mode can use a fixed context before normal configuration and session work. waits: - Production pages remain unmounted until a usable context is returned. evidence: - >- react-console at baf6dae: lib/security-context/{provider.tsx,boot.ts,boot.test.ts,tenant-id.ts}; lib/auth/session.ts; app/(console)/layout.tsx; components/console/hq/{staff-context-gate,staff-landing-gate}.tsx. - >- services-platform at ad3f6a6: modules/security/aws/api/access.routes.ts; modules/security/services/access/security-context.ts; docs/security/console-authentication.md. controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-PRV-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Start the console and settle the working context ## What It Does Start-up establishes identity and working context before mounting console content. It tries a strict workspace request when the address names one, otherwise using a remembered preference. A refused or failed strict request can require further context reads. ## The Flow ```mermaid sequenceDiagram participant C as Console participant S as Security Note over C: session and settings C->>S: strict address context or remembered preference S-->>C: context or classified refusal Note over C: mount only after usable context ``` ## When Something Fails Configuration problems stop at the setup screen. Missing or expired sessions go to sign-in with a safe return address. A final context refusal shows no access, while other failures offer Retry. An unavailable remembered workspace causes a no-preference fallback. Security may stamp authentication and settle expired grants; a failed stamp is logged without refusing the computed context. ## Open Design Questions The parser accepts unfamiliar contract versions. Security should confirm the bookkeeping effects and write budget of the consumed reads.