@econ-v1/domain 6.7.0 → 6.11.0

package/src/services/onboarding-flow-service.js

@@ -0,0 +1,1096 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').OnboardingAccessCodeStore} OnboardingAccessCodeStore */
+/** @typedef {import('@econ-v1/ports').OnboardingPresencePhase} OnboardingPresencePhase */
+/** @typedef {import('@econ-v1/ports').OnboardingPresencePort} OnboardingPresencePort */
+/** @typedef {import("./invite-redemption-service.js").InviteRedemptionService} InviteRedemptionService */
+/** @typedef {import("./lcd-decision-service.js").LcdDecisionService} LcdDecisionService */
+/** @typedef {import("./onboarding-checkpoint-store.js").OnboardingCheckpointStore} OnboardingCheckpointStore */
+/** @typedef {import("./owner-claim-service.js").OwnerClaimIdentity} OwnerClaimIdentity */
+/** @typedef {import("./owner-claim-service.js").OwnerClaimService} OwnerClaimService */
+/** @typedef {import("./wifi-provisioning-service.js").WifiProvisioningService} WifiProvisioningService */
+import { createNullOnboardingPresence } from "@econ-v1/ports";
+import { DomainError } from "../errors/index.js";
+/** @type {readonly ["join-qr", "open-browser", "choose-network", "network-password", "handoff", "way-back", "install", "match-code", "invitation", "identity", "trusted"]} */
+export const ONBOARDING_FLOW_STEP_IDS = [
+  "join-qr",
+  "open-browser",
+  "choose-network",
+  "network-password",
+  "handoff",
+  "way-back",
+  "install",
+  "match-code",
+  "invitation",
+  "identity",
+  "trusted",
+];
+/** @type {readonly OnboardingFlowStep[]} */
+/** @type {readonly OnboardingFlowStep[]} */
+const STEP_TABLE = [
+  { id: "join-qr", lcdScreenId: "onboard_qr", phase: "connect" },
+  { id: "open-browser", lcdScreenId: "onboard_open_browser", phase: "connect" },
+  { id: "choose-network", lcdScreenId: "onboard_wifi_setup", phase: "connect" },
+  {
+    id: "network-password",
+    lcdScreenId: "onboard_wifi_setup",
+    phase: "connect",
+  },
+  { id: "handoff", lcdScreenId: "onboard_wifi_joined", phase: "connect" },
+  { id: "way-back", lcdScreenId: "onboard_wifi_joined", phase: "connect" },
+  { id: "install", lcdScreenId: "onboard_working", phase: "install" },
+  { id: "match-code", lcdScreenId: "onboard_code", phase: "secure" },
+  {
+    gate: "invitations",
+    id: "invitation",
+    lcdScreenId: "onboard_working",
+    phase: "identify",
+  },
+  { id: "identity", lcdScreenId: "onboard_working", phase: "identify" },
+  { id: "trusted", lcdScreenId: "onboard_trusted", phase: "ready" },
+];
+/** @type {OnboardingFlowStepId} */
+/** @type {OnboardingFlowStepId} */
+const FIRST_PWA_STEP = "choose-network";
+/** @type {ReadonlySet<OnboardingFlowStepId>} */
+/** @type {ReadonlySet<OnboardingFlowStepId>} */
+const WIFI_SKIPPABLE_STEPS = new Set([
+  "choose-network",
+  "network-password",
+]);
+const CONFIRMATION_WINDOW_MS = 5 * 60 * 1000;
+const HANDOFF_WINDOW_MS = 3 * 60 * 1000;
+/** @type {Readonly<Record<string, "confirm" | "reject">>} */
+/** @type {Readonly<Record<string, "confirm" | "reject">>} */
+const LCD_DECISION_COMPONENTS = {
+  confirm_btn: "confirm",
+  reject_btn: "reject",
+};
+/** @type {Readonly<Record<string, string>>} */
+/** @type {Readonly<Record<string, string>>} */
+const LCD_WORKING_CAPTIONS = {
+  identity: "Naming your node",
+  install: "Installing the app",
+  invitation: "Setting up",
+};
+/** @type {Readonly<Partial<Record<OnboardingFlowStepId, OnboardingPresencePhase>>>} */
+/** @type {Readonly<Partial<Record<OnboardingFlowStepId, OnboardingPresencePhase>>>} */
+const PRESENCE_PHASE_BY_STEP = {
+  "choose-network": "wifi_setup",
+  install: "install",
+};
+export class OnboardingFlowService {
+  /** @readonly @type {OnboardingAccessCodeStore} */
+  #accessCodes;
+  /** @readonly @type {Pick<OnboardingCheckpointStore, "clear" | "read" | "write">} */
+  #checkpoints;
+  /** @readonly @type {OnboardingFlowClaimPort} */
+  #claim;
+  /** @readonly @type {() => boolean} */
+  #invitationRequired;
+  /** @readonly @type {() => boolean} */
+  #invitationsEnabled;
+  /** @readonly @type {OnboardingFlowInvitePort} */
+  #invites;
+  /** @readonly @type {OnboardingFlowLcdPort | undefined} */
+  #lcd;
+  /** @readonly @type {() => string} */
+  #now;
+  /** @readonly @type {OnboardingPresencePort} */
+  #presence;
+  /** @readonly @type {(stepId: OnboardingFlowStepId) => void} */
+  #publish;
+  /** @readonly @type {OnboardingFlowWifiPort} */
+  #wifi;
+  /** Latched ONCE by `start()` from `#accessCodes.read() !== null` and never recomputed
+   * afterward — not from a later `#accessCodes.read()`, not from `cancel()`, not from success
+   * cleanup. Once true, `#activeSteps()` excludes `match-code` for the rest of this instance's
+   * life: a store that later fails to read, or is cleared on success/cancel, must never
+   * silently un-latch the flow back onto the legacy match-code rail mid-attempt.
+   * @default false
+   */
+  #accessCodeMode = false;
+  /** @type {OnboardingFlowApprovalState} */
+  #approvalState = "waiting";
+  /** @default 0 */
+  #claimGeneration = 0;
+  /** @type {string | undefined} */
+  #deadline;
+  /** @default undefined[] */
+  /** @type {readonly string[]} */
+  #digits = [];
+  /** @type {string | undefined} */
+  #lockedDisplayName;
+  /** @default false */
+  #lcdHardware = false;
+  /** @default false */
+  #lcdTapPending = false;
+  /** @default undefined[] */
+  /** @type {readonly OnboardingFlowNetwork[]} */
+  #networks = [];
+  /** @type {string | undefined} */
+  #operationHash;
+  /** @type {OnboardingFlowReasonCode | undefined} */
+  #reasonCode;
+  /** @default 0 */
+  #remainingSeconds = 0;
+  /** @default false */
+  #requiresConfirmation = false;
+  /** @default 0 */
+  #scanGeneration = 0;
+  /** @default false */
+  #scanning = false;
+  /** @default false */
+  #sessionEstablished = false;
+  /** @type {OnboardingFlowStepId} */
+  #stepId = FIRST_PWA_STEP;
+  /** @default false */
+  #submittingIdentity = false;
+  /** @type {OnboardingFlowWifiSecurity} */
+  #targetSecurity = "wpa2";
+  /** @default "" */
+  #targetSsid = "";
+  #reconnectGeneration = 0;
+  /** @default 0 */
+  #wifiGeneration = 0;
+  /** @type {string | undefined} */
+  #wifiOperationId;
+  /**
+   * @param {OnboardingFlowServiceOptions} options
+   */
+  constructor(options) {
+    this.#accessCodes = options.accessCodes;
+    this.#checkpoints = options.checkpoints;
+    this.#claim = options.claim;
+    this.#invitationRequired = options.invitationRequired ?? (() => true);
+    this.#invitationsEnabled = options.invitationsEnabled;
+    this.#invites = options.invites;
+    this.#lcd = options.lcd;
+    this.#now = options.now;
+    this.#presence = options.presence ?? createNullOnboardingPresence();
+    this.#publish = options.publish;
+    this.#wifi = options.wifi;
+  }
+  /**
+   * @returns {OnboardingFlowRow}
+   */
+  view() {
+    const steps = this.#activeSteps();
+    const stepId = this.#stepId;
+    const step = /** @type {OnboardingFlowStep} */ (STEP_TABLE.find((row) => row.id === stepId));
+    /** @type {OnboardingFlowRowBase} */
+    /** @type {OnboardingFlowRowBase} */
+    const base = {
+      lcdScreenId: this.#lcdScreenId(step),
+      phase: step.phase,
+      stepIndex: steps.findIndex((row) => row.id === stepId) + 1,
+      totalSteps: steps.length,
+      ...(this.#reasonCode === undefined
+        ? {}
+        : { reasonCode: this.#reasonCode }),
+    };
+    switch (stepId) {
+      case "choose-network":
+        return {
+          ...base,
+          networks: this.#networks,
+          scanning: this.#scanning,
+          stepId,
+        };
+      case "network-password":
+        return {
+          ...base,
+          security: this.#targetSecurity,
+          ssid: this.#targetSsid,
+          stepId,
+        };
+      case "handoff":
+        return { ...base, ssid: this.#targetSsid, stepId };
+      case "match-code":
+        return {
+          ...base,
+          approvalState: this.#approvalState,
+          digits: this.#digits,
+          remainingSeconds: this.#remainingSeconds,
+          stepId,
+        };
+      case "invitation":
+        return {
+          ...base,
+          inviteRequired: this.#invitationRequired(),
+          stepId,
+        };
+      case "identity":
+        return {
+          ...base,
+          displayName: this.#lockedDisplayName ?? "",
+          displayNameLocked: this.#lockedDisplayName !== undefined,
+          stepId,
+          submitting: this.#submittingIdentity,
+        };
+      case "trusted":
+        return {
+          ...base,
+          sessionEstablished: this.#sessionEstablished,
+          stepId,
+        };
+      default:
+        return { ...base, stepId };
+    }
+  }
+  /**
+   * @returns {void}
+   */
+  start() {
+    // Latched HERE, before anything else — including the checkpoint restore right below, which
+    // consults `#activeSteps()` (and therefore `#accessCodeMode`) to validate a resumed step id.
+    // See `#accessCodeMode`'s own doc comment for why this is the only place it is ever set.
+    this.#accessCodeMode = this.#accessCodes.read() !== null;
+    const checkpoint = this.#checkpoints.read();
+    const restored =
+      checkpoint === undefined
+        ? undefined
+        : this.#asActiveStepId(checkpoint.stepId);
+    this.#approvalState = "waiting";
+    this.#deadline = checkpoint?.deadline;
+    this.#digits = [];
+    // Neither the invitation's name nor the session flag is checkpointed: both are facts about
+    // an in-memory attempt, and a resumed flow must re-earn them rather than assert them.
+    this.#lockedDisplayName = undefined;
+    // Deliberately not restored from the checkpoint: it is an answer about THIS claim attempt,
+    // and a resumed flow re-earns it at the next prepare. Until then the pane offers a real
+    // confirm, which a node with a display simply refuses — the safe direction.
+    this.#lcdHardware = false;
+    this.#lcdTapPending = false;
+    this.#operationHash = checkpoint?.operationHash;
+    this.#reasonCode = undefined;
+    // A checkpointed operation hash exists only because the node issued a gated claim, so a
+    // resume at step 10 is by construction a resume of a confirmation that is still pending.
+    this.#requiresConfirmation = this.#operationHash !== undefined;
+    this.#scanning = false;
+    this.#sessionEstablished = false;
+    this.#stepId = restored ?? FIRST_PWA_STEP;
+    // The security of the checkpointed SSID is deliberately NOT persisted: the password is not
+    // resumable either, so step 5 is re-shown rather than replayed, and WPA2 is the demanding
+    // default (it asks for a secret rather than silently offering to join without one).
+    this.#targetSecurity = "wpa2";
+    this.#targetSsid = checkpoint?.targetSsid ?? "";
+    this.#wifiOperationId = checkpoint?.wifiOperationId;
+    this.#recomputeRemaining();
+    this.#publish(this.#stepId);
+    // Resume re-send (spec §6.3): a reload re-announces the resumed step's phase, the same way
+    // `#moveTo` does for a live transition — the node's beacon-driven screen must not be left
+    // showing a stale phase just because the browser reloaded rather than advanced.
+    const resumedPhase = PRESENCE_PHASE_BY_STEP[this.#stepId];
+    if (resumedPhase) void this.#presence.announce(resumedPhase);
+    // Access-code mode's gate-entry prepare (design §4/§5.4): possession of the code IS the
+    // physical-presence proof, so this fires as soon as the flow starts — the "first device to
+    // access" moment — independent of which step a resumed checkpoint or the Wi-Fi skip-check
+    // below lands on, rather than waiting for a click through the now-absent match-code step.
+    if (this.#accessCodeMode) void this.#prepareCode();
+    if (this.#stepId === "choose-network") {
+      void this.#scan();
+    }
+    // A node whose Wi-Fi was configured on its own captive portal (or any earlier attempt)
+    // needs no credentials from this flow: asking again is the double-prompt this probe
+    // exists to kill, and RESUBMITTING working credentials is worse than redundant — the node
+    // re-runs the join, and a handshake flake in that window strands it back in setup AP mode
+    // (observed live on Pi Zero 2W). Fired for the wifi-skippable steps only; `handoff` keeps
+    // its own watcher.
+    if (WIFI_SKIPPABLE_STEPS.has(this.#stepId)) {
+      void this.#skipWifiIfAlreadyConnected();
+    }
+    if (this.#stepId === "handoff" && this.#wifiOperationId !== undefined) {
+      // A reload during the handoff is EXPECTED — it is often the very act of rejoining the home
+      // network that killed the tab. Resuming the watch is what stops that from restarting the
+      // whole flow. The window restarts from now: the reload itself is evidence the handoff is
+      // still in progress, and the original deadline is deliberately not checkpointed (it would
+      // collide with the claim window's `deadline` slot).
+      this.#wifiGeneration += 1;
+      this.#watchHandoff(this.#wifiOperationId, this.#wifiGeneration);
+    }
+    if (this.#stepId === "match-code" && this.#operationHash !== undefined) {
+      this.#claimGeneration += 1;
+      this.#watchConfirmation(this.#operationHash, this.#claimGeneration);
+    }
+    if (this.#stepId === "way-back") {
+      this.#watchWayBack();
+    }
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async advance() {
+    switch (this.#stepId) {
+      case "join-qr":
+      case "open-browser":
+        this.#moveTo(this.#nextStepAfter(this.#stepId));
+        return;
+      case "way-back":
+        this.#enterInstall();
+        return;
+      case "install":
+        if (this.#reasonCode === "claim-failed") void this.installDecision("continue-in-browser");
+        return;
+      default:
+        // Every other step needs its own command. Silently ignoring a stray `advance` is
+        // deliberate: reinterpreting it as a generic "next" would discard the step's real data.
+        // Step 6 is now explicitly among them — only `awaitHandoff` may end it.
+        return;
+    }
+  }
+  /**
+   * @param {"continue-in-browser" | "installed"} decision
+   * @returns {Promise<void>}
+   */
+  async installDecision(decision) {
+    if (this.#stepId !== "install") return;
+    void decision;
+    if (await this.#prepareCode()) this.#enterMatchCode();
+  }
+  /**
+   * @returns {OnboardingFlowLcdScreen}
+   */
+  lcdScreen() {
+    const step = /** @type {OnboardingFlowStep} */ (STEP_TABLE.find((row) => row.id === this.#stepId));
+    return {
+      awaitingNode: this.#lcdTapPending,
+      physicalTapOnly: this.#lcdHardware,
+      screenId: this.#lcdScreenId(step),
+      state: this.#lcdScreenState(),
+    };
+  }
+  /**
+   * @param {string} componentId
+   * @returns {Promise<void>}
+   */
+  async lcdTap(componentId) {
+    if (this.#stepId !== "match-code") {
+      await this.advance();
+      return;
+    }
+    const decision = LCD_DECISION_COMPONENTS[componentId];
+    const operationHash = this.#operationHash;
+    if (decision === undefined || operationHash === undefined) return;
+    this.#lcdTapPending = true;
+    this.#publish(this.#stepId);
+    if (!this.#lcdHardware && this.#lcd !== undefined) {
+      // The outcome is deliberately discarded: "forwarded" is not approval and "not-accepted"
+      // is not a failure the person can act on differently — either way the instruction is the
+      // same, and the node's own poll is what ends this step.
+      await (decision === "confirm"
+        ? this.#lcd.confirm(operationHash)
+        : this.#lcd.reject(operationHash));
+    }
+    this.#lcdTapPending = false;
+    this.#publish(this.#stepId);
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async rescanNetworks() {
+    if (this.#stepId !== "choose-network") return;
+    await this.#scan();
+  }
+  /**
+   * @param {string} code
+   * @returns {Promise<void>}
+   */
+  async redeemInvitation(code) {
+    if (this.#stepId !== "invitation") return;
+    /** @type {Awaited<ReturnType<OnboardingFlowInvitePort["redeem"]>>} */
+    const outcome = await this.#invites.redeem(code);
+    if (this.#stepId !== "invitation") return;
+    if (outcome.kind === "rejected") {
+      this.#reasonCode = "invitation-invalid";
+      this.#publish(this.#stepId);
+      return;
+    }
+    // The name the INVITER registered wins over anything typed at step 12 — that is what makes
+    // the invitation mean something on the inviter's node rather than being decoration.
+    this.#lockedDisplayName = outcome.receiverName;
+    if (this.#accessCodeMode) {
+      // Keep-alive re-prepare (design §5.4), same idea as `installDecision()`'s: a slow person
+      // on the invitation step can let the operation's confirmed_at freshness window lapse just
+      // as easily as a slow person on step 9 can. UNLIKE `installDecision()`, this is best-effort
+      // — the invitation was already accepted by the node, so a re-prepare failure here must not
+      // strand a successful redemption behind it. `#prepareCode()`'s own error handling still
+      // runs (reason code set + published) but is immediately superseded by the `#moveTo` below,
+      // which always resets the reason code; the completion-failure belt in `submitIdentity()`
+      // remains the backstop if the operation is ALSO stale by the time identity is submitted.
+      await this.#prepareCode();
+      if (this.#stepId !== "invitation") return;
+    }
+    this.#moveTo(this.#nextStepAfter("invitation"));
+  }
+  /**
+   * @param {string} ssid
+   * @param {OnboardingFlowWifiSecurity} security
+   * @returns {Promise<void>}
+   */
+  async selectNetwork(ssid, security) {
+    if (this.#stepId !== "choose-network") return;
+    // Abandon any in-flight scan: its late result must not repaint a picker nobody is on.
+    this.#scanGeneration += 1;
+    this.#scanning = false;
+    this.#targetSecurity = security;
+    this.#targetSsid = ssid;
+    this.#moveTo("network-password");
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async reselectNetwork() {
+    if (this.#stepId !== "network-password") return;
+    this.#enterChooseNetwork();
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async skipInvitation() {
+    if (this.#stepId !== "invitation") return;
+    if (this.#invitationRequired()) {
+      // The node demands a code. Refusing here rather than in the UI is what stops a stale
+      // bundle (or a direct command) from walking past the node's own policy.
+      this.#reasonCode = "invitation-invalid";
+      this.#publish(this.#stepId);
+      return;
+    }
+    this.#moveTo(this.#nextStepAfter("invitation"));
+  }
+  /**
+   * @param {OwnerClaimIdentity} identity
+   * @returns {Promise<void>}
+   */
+  async submitIdentity(identity) {
+    if (this.#stepId !== "identity") return;
+    // Completion does real work on the node (owner record, DID, session mint) and routinely
+    // takes seconds, so the submitting window is a published state: the form renders it as a
+    // disabled "Setting up your node…" button instead of a dead one, and a second submit while
+    // one is in flight is refused rather than racing two owner creations.
+    if (this.#submittingIdentity) return;
+    this.#submittingIdentity = true;
+    this.#reasonCode = undefined;
+    this.#publish(this.#stepId);
+    const displayName = this.#lockedDisplayName ?? identity.displayName;
+    let outcome;
+    try {
+      outcome = await this.#claim.completeClaim({
+        displayName,
+        username: identity.username,
+      });
+    } catch {
+      // A thrown completion (network death mid-request) must not strand the flag: the button
+      // would read "Setting up your node…" forever with no way to retry.
+      outcome = "rejected";
+    }
+    this.#submittingIdentity = false;
+    if (this.#stepId !== "identity") return;
+    if (outcome !== "claimed" && outcome !== "claimed-unpaired") {
+      if (this.#accessCodeMode) {
+        // Belt for the op-expiry case (design §5.4): the node's confirmed_at freshness window
+        // may have lapsed while the person filled in their identity, so re-fire the idempotent
+        // prepare once before giving up — a press of "try again" then lands on a fresh
+        // operation instead of repeating the same expired one. If THIS call fails with its own
+        // specific access-code reason, `#prepareCode()` has already set and published it, which
+        // is more useful than the generic fallback below — so skip straight past it.
+        const reprepared = await this.#prepareCode();
+        if (this.#stepId !== "identity") return;
+        if (!reprepared) return;
+      }
+      this.#reasonCode = "claim-failed";
+      this.#publish(this.#stepId);
+      return;
+    }
+    // PAST THIS LINE THE OWNER EXISTS ON THE NODE (mirrors `OwnerClaimService.completeClaim`'s
+    // own comment) — cleanup of the stored code belongs here alongside the other terminal
+    // states, not gated on `#accessCodeMode`: an empty store's `clear()` is a documented no-op.
+    this.#accessCodes.clear();
+    this.#approvalState = "approved";
+    this.#sessionEstablished = outcome === "claimed";
+    this.#moveTo("trusted");
+  }
+  /**
+   * @param {string} secret
+   * @returns {Promise<void>}
+   */
+  async submitNetworkPassword(secret) {
+    if (this.#stepId !== "network-password") return;
+    // Named `isOpenNetwork`, not `open`: a bare `open` binding reads as the browser global to
+    // `client/scripts/check-boundaries.mjs`, which is exactly the kind of platform reference
+    // domain is not allowed to hold.
+    const isOpenNetwork = this.#targetSecurity === "open";
+    if (!isOpenNetwork && secret.length === 0) {
+      this.#reasonCode = "wifi-credentials-rejected";
+      this.#publish(this.#stepId);
+      return;
+    }
+    const outcome = await this.#wifi.configure(
+      this.#targetSsid,
+      isOpenNetwork ? undefined : secret,
+    );
+    if (this.#stepId !== "network-password") return;
+    if (outcome.kind === "credentials-rejected") {
+      this.#reasonCode = "wifi-credentials-rejected";
+      this.#publish(this.#stepId);
+      return;
+    }
+    if (outcome.kind === "unreachable") {
+      this.#reasonCode = "wifi-unreachable";
+      this.#publish(this.#stepId);
+      return;
+    }
+    this.#wifiGeneration += 1;
+    this.#wifiOperationId = outcome.operationId;
+    this.#moveTo("handoff");
+    this.#watchHandoff(outcome.operationId, this.#wifiGeneration);
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async retryApproval() {
+    if (this.#stepId !== "match-code") return;
+    if (this.#approvalState !== "expired" && this.#approvalState !== "rejected")
+      return;
+    if (await this.#prepareCode()) this.#enterMatchCode();
+  }
+  /**
+   * @returns {void}
+   */
+  cancel() {
+    this.#claimGeneration += 1;
+    this.#claim.cancel();
+    this.#accessCodes.clear();
+    this.#checkpoints.clear();
+    this.#approvalState = "waiting";
+    this.#deadline = undefined;
+    this.#digits = [];
+    this.#lockedDisplayName = undefined;
+    this.#lcdHardware = false;
+    this.#lcdTapPending = false;
+    this.#networks = [];
+    this.#operationHash = undefined;
+    this.#reasonCode = undefined;
+    this.#remainingSeconds = 0;
+    this.#requiresConfirmation = false;
+    this.#scanGeneration += 1;
+    this.#scanning = false;
+    this.#sessionEstablished = false;
+    this.#stepId = FIRST_PWA_STEP;
+    this.#submittingIdentity = false;
+    this.#targetSecurity = "wpa2";
+    this.#targetSsid = "";
+    this.#wifiGeneration += 1;
+    this.#wifiOperationId = undefined;
+    this.#publish(this.#stepId);
+  }
+  /**
+   * @returns {void}
+   */
+  tick() {
+    if (this.#stepId !== "match-code" || this.#approvalState !== "waiting")
+      return;
+    const before = this.#remainingSeconds;
+    this.#recomputeRemaining();
+    if (this.#remainingSeconds === 0 && this.#deadline !== undefined) {
+      this.#approvalState = "expired";
+      this.#reasonCode = "approval-expired";
+    }
+    if (
+      this.#remainingSeconds !== before ||
+      this.#approvalState !== "waiting"
+    ) {
+      this.#publish(this.#stepId);
+    }
+  }
+  /**
+   * @returns {readonly OnboardingFlowStep[]}
+   */
+  #activeSteps() {
+    const invitations = this.#invitationsEnabled();
+    return STEP_TABLE.filter((row) => {
+      if (row.gate === "invitations" && !invitations) return false;
+      // Access-code mode never shows the match-code screen (design §4): the code itself was
+      // this claim's physical-presence proof, so there is no code to display and nothing to
+      // wait for. See `#accessCodeMode`'s doc comment for why this can never flip back.
+      if (row.id === "match-code" && this.#accessCodeMode) return false;
+      return true;
+    });
+  }
+  /**
+   * @param {string} value
+   * @returns {OnboardingFlowStepId | undefined}
+   */
+  #asActiveStepId(value) {
+    return this.#activeSteps().find((row) => row.id === value)?.id;
+  }
+  /**
+   * @param {OnboardingFlowReasonCode} [reasonCode]
+   * @returns {void}
+   */
+  #enterChooseNetwork(reasonCode) {
+    this.#networks = [];
+    this.#scanning = true;
+    this.#wifiOperationId = undefined;
+    this.#moveTo("choose-network", reasonCode);
+    void this.#scan();
+  }
+  /**
+   * @returns {void}
+   */
+  #enterInstall() {
+    this.#moveTo("install");
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async #skipWifiIfAlreadyConnected() {
+    const outcome = await this.#wifi.status();
+    if (outcome.kind !== "connected") return;
+    if (!WIFI_SKIPPABLE_STEPS.has(this.#stepId)) return;
+    if (this.#wifiOperationId !== undefined) return;
+    if (outcome.ssid.length > 0) this.#targetSsid = outcome.ssid;
+    this.#enterInstall();
+  }
+  /**
+   * @returns {Promise<void>}
+   */
+  async #scan() {
+    this.#scanGeneration += 1;
+    const generation = this.#scanGeneration;
+    if (!this.#scanning) {
+      this.#scanning = true;
+      this.#publish(this.#stepId);
+    }
+    const outcome = await this.#wifi.scan();
+    // A superseded scan, or one whose step the person already left, must not repaint anything.
+    if (
+      generation !== this.#scanGeneration ||
+      this.#stepId !== "choose-network"
+    )
+      return;
+    this.#scanning = false;
+    if (outcome.kind === "scan-failed") {
+      this.#networks = [];
+      this.#reasonCode = "wifi-scan-failed";
+    } else {
+      this.#networks = outcome.networks;
+      // Only this scan's own failure is cleared. A `wifi-credentials-rejected` carried in from
+      // step 6 must survive the re-scan — it is the reason the person is back on this screen.
+      if (this.#reasonCode === "wifi-scan-failed") this.#reasonCode = undefined;
+    }
+    this.#publish(this.#stepId);
+  }
+  /**
+   * @returns {Promise<boolean>}
+   */
+  async #prepareCode() {
+    this.#claimGeneration += 1;
+    const generation = this.#claimGeneration;
+    // A retry must not keep showing the error it is retrying: clear the reason and publish so
+    // the step goes back to its working state while the new attempt is in flight. Guarded on
+    // there actually being a reason to clear, so a FIRST prepare still costs exactly one
+    // publish and the "one publish per transition" invariant holds for every ordinary walk.
+    if (this.#reasonCode !== undefined) {
+      this.#reasonCode = undefined;
+      this.#publish(this.#stepId);
+    }
+    // Access-code mode (design §4/§5.4): the stored code is re-read on every call, not cached
+    // from the gate-entry prepare — the MODE itself never un-latches (`#accessCodeMode` is set
+    // once, in `start()`), but the code VALUE sent on the wire always reflects the store's
+    // current answer, including the degenerate case where a later read comes back `null`.
+    const accessCode = this.#accessCodeMode ? this.#accessCodes.read() ?? undefined : undefined;
+    /** @type {Awaited<ReturnType<OnboardingFlowClaimPort["prepareClaim"]>>} */
+    let prepared;
+    try {
+      prepared = await this.#claim.prepareClaim(accessCode);
+    } catch (error) {
+      // No raw node error text ever reaches the view — only a reason code plus the step's own
+      // safe copy. The step holds so the person can retry. A structured access-code refusal
+      // (`code-already-bound` / `access-code-invalid`) gets its own specific reason instead of
+      // the generic `claim-failed` fallback.
+      if (generation !== this.#claimGeneration) return false;
+      this.#reasonCode = accessCodeReasonCode(error) ?? "claim-failed";
+      this.#publish(this.#stepId);
+      return false;
+    }
+    if (generation !== this.#claimGeneration) return false;
+    this.#approvalState = "waiting";
+    this.#deadline = new Date(
+      Date.parse(this.#now()) + CONFIRMATION_WINDOW_MS,
+    ).toISOString();
+    this.#digits = [...prepared.matchCode];
+    this.#lcdHardware = prepared.lcdHardware;
+    this.#operationHash = prepared.operationHash;
+    this.#requiresConfirmation = prepared.requiresConfirmation;
+    this.#recomputeRemaining();
+    return true;
+  }
+  /**
+   * @returns {void}
+   */
+  #enterMatchCode() {
+    const operationHash = this.#operationHash;
+    if (this.#accessCodeMode) {
+      // The code itself already proved physical presence (design §4) — there is no screen to
+      // show and no confirmation left to wait for. `#nextStepAfter("install")`, not
+      // `#nextStepAfter("match-code")`: `match-code` is excluded from `#activeSteps()` in this
+      // mode, so looking its own index up would resolve to -1 and wrap back to the first step.
+      this.#approvalState = "approved";
+      this.#moveTo(this.#nextStepAfter("install"));
+      return;
+    }
+    if (!this.#requiresConfirmation || operationHash === undefined) {
+      // The node's confirmation gate is disabled (no screen): there is nothing to wait for and
+      // nothing to compare, so the flow must not stall on a confirmation that never arrives.
+      this.#approvalState = "approved";
+      this.#moveTo(this.#nextStepAfter("match-code"));
+      return;
+    }
+    this.#moveTo("match-code");
+    this.#watchConfirmation(operationHash, this.#claimGeneration);
+  }
+  /**
+   * @param {OnboardingFlowStep} step
+   * @returns {OnboardingFlowLcdScreenId}
+   */
+  #lcdScreenId(step) {
+    if (
+      step.id === "match-code" &&
+      (this.#approvalState === "expired" || this.#approvalState === "rejected")
+    ) {
+      return "onboard_rejected";
+    }
+    return step.lcdScreenId;
+  }
+  /**
+   * @returns {Readonly<Record<string, number | string>>}
+   */
+  #lcdScreenState() {
+    switch (this.#stepId) {
+      case "handoff":
+        return this.#targetSsid === "" ? {} : { target_ssid: this.#targetSsid };
+      case "match-code":
+        return this.#operationHash === undefined
+          ? {}
+          : {
+              code: this.#digits.join(""),
+              operation_hash: this.#operationHash,
+              remaining_seconds: this.#remainingSeconds,
+              ttl_seconds: Math.round(CONFIRMATION_WINDOW_MS / 1000),
+            };
+      case "install":
+      case "invitation":
+      case "identity":
+        return { caption: LCD_WORKING_CAPTIONS[this.#stepId] ?? "" };
+      default:
+        // Every other screen is either stateless or holds state only the NODE knows (its LAN
+        // address, its AP client count). Sending nothing leaves the node's own value intact.
+        return {};
+    }
+  }
+  /**
+   * @param {OnboardingFlowStepId} stepId
+   * @param {OnboardingFlowReasonCode} [reasonCode]
+   * @returns {void}
+   */
+  #moveTo(stepId, reasonCode) {
+    this.#stepId = stepId;
+    this.#reasonCode = reasonCode;
+    this.#writeCheckpoint();
+    this.#publish(stepId);
+    const phase = PRESENCE_PHASE_BY_STEP[stepId];
+    if (phase) void this.#presence.announce(phase);
+  }
+  /**
+   * @param {OnboardingFlowStepId} stepId
+   * @returns {OnboardingFlowStepId}
+   */
+  #nextStepAfter(stepId) {
+    const steps = this.#activeSteps();
+    const index = steps.findIndex((row) => row.id === stepId);
+    return steps[index + 1]?.id ?? "trusted";
+  }
+  /**
+   * @returns {void}
+   */
+  #recomputeRemaining() {
+    if (this.#deadline === undefined) {
+      this.#remainingSeconds = 0;
+      return;
+    }
+    const remainingMs = Date.parse(this.#deadline) - Date.parse(this.#now());
+    this.#remainingSeconds =
+      remainingMs <= 0 ? 0 : Math.ceil(remainingMs / 1000);
+  }
+  /**
+   * @param {string} operationId
+   * @param {number} generation
+   * @returns {void}
+   */
+  #watchHandoff(operationId, generation) {
+    const deadline = Date.parse(this.#now()) + HANDOFF_WINDOW_MS;
+    const onTransportLost = () => {
+      if (generation !== this.#wifiGeneration) return;
+      if (this.#stepId !== "handoff") return;
+      this.#moveTo("way-back");
+      this.#watchWayBack();
+    };
+    void this.#wifi
+      .awaitHandoff(operationId, deadline, onTransportLost)
+      .then((outcome) => {
+        if (generation !== this.#wifiGeneration) return;
+        this.#wifiOperationId = undefined;
+        if (outcome === "connected") {
+          if (this.#stepId === "handoff") {
+            this.#moveTo("way-back");
+            this.#watchWayBack();
+          }
+          return;
+        }
+        if (outcome === "credentials-rejected") {
+          if (this.#stepId === "handoff" || this.#stepId === "way-back") {
+            this.#enterChooseNetwork("wifi-credentials-rejected");
+          }
+          return;
+        }
+        if (this.#stepId === "handoff") {
+          this.#moveTo("way-back", "wifi-unreachable");
+          this.#watchWayBack();
+        }
+      })
+      .catch(() => {
+        if (generation !== this.#wifiGeneration) return;
+        this.#wifiOperationId = undefined;
+        if (this.#stepId === "handoff") {
+          this.#moveTo("way-back", "wifi-unreachable");
+          this.#watchWayBack();
+        }
+      });
+  }
+  #watchWayBack() {
+    this.#reconnectGeneration += 1;
+    const generation = this.#reconnectGeneration;
+    const live = () => generation === this.#reconnectGeneration && this.#stepId === "way-back";
+    void this.#wifi.awaitReconnect(live).then((outcome) => {
+      if (outcome !== "connected" || !live()) return;
+      this.#enterInstall();
+    }).catch(() => {
+      // A broken probe leaves the scan instruction as the truthful exit.
+    });
+  }
+  /**
+   * @param {string} operationHash
+   * @param {number} generation
+   * @returns {void}
+   */
+  #watchConfirmation(operationHash, generation) {
+    void this.#claim
+      .awaitConfirmation(operationHash)
+      .then((confirmation) => {
+        if (generation !== this.#claimGeneration) return;
+        if (confirmation === "confirmed") {
+          this.#approvalState = "approved";
+          this.#moveTo(this.#nextStepAfter("match-code"));
+          return;
+        }
+        this.#approvalState =
+          confirmation === "rejected" ? "rejected" : "expired";
+        this.#reasonCode =
+          confirmation === "rejected"
+            ? "approval-rejected"
+            : "approval-expired";
+        this.#publish(this.#stepId);
+      })
+      .catch(() => {
+        if (generation !== this.#claimGeneration) return;
+        this.#approvalState = "rejected";
+        this.#reasonCode = "claim-failed";
+        this.#publish(this.#stepId);
+      });
+  }
+  /**
+   * @returns {void}
+   */
+  #writeCheckpoint() {
+    if (this.#stepId === "trusted") {
+      this.#checkpoints.clear();
+      return;
+    }
+    this.#checkpoints.write({
+      stepId: this.#stepId,
+      ...(this.#deadline === undefined ? {} : { deadline: this.#deadline }),
+      ...(this.#operationHash === undefined
+        ? {}
+        : { operationHash: this.#operationHash }),
+      ...(this.#targetSsid === "" ? {} : { targetSsid: this.#targetSsid }),
+      ...(this.#wifiOperationId === undefined
+        ? {}
+        : { wifiOperationId: this.#wifiOperationId }),
+    });
+  }
+}
+/**
+ * Maps a `prepareClaim()` rejection onto the access-code rail's two specific reason codes
+ * (design §5.4), so `#prepareCode()` can surface "the code is bound to another device" or "that
+ * code didn't match" instead of the generic `claim-failed` catch-all. `undefined` for anything
+ * else — a transport failure, a plain thrown `Error`, or a `DomainError` with an unrelated code
+ * — which leaves `#prepareCode()` to fall back to `claim-failed` as it always has.
+ * @param {unknown} error
+ * @returns {OnboardingFlowReasonCode | undefined}
+ */
+function accessCodeReasonCode(error) {
+  if (!(error instanceof DomainError)) return undefined;
+  switch (error.code) {
+    case "code-already-bound":
+      return "code-already-bound";
+    case "access-code-invalid":
+      return "access-code-invalid";
+    default:
+      return undefined;
+  }
+}
+/** @typedef {(typeof ONBOARDING_FLOW_STEP_IDS)[number]} OnboardingFlowStepId */
+/** @typedef {"connect" | "install" | "secure" | "identify" | "ready"} OnboardingFlowPhase */
+/**
+ * @typedef {| "onboard_qr"
+ *   | "onboard_open_browser"
+ *   | "onboard_home_qr"
+ *   | "onboard_wifi_setup"
+ *   | "onboard_wifi_joined"
+ *   | "onboard_working"
+ *   | "onboard_code"
+ *   | "onboard_trusted"
+ *   | "onboard_rejected"} OnboardingFlowLcdScreenId
+ */
+/** @typedef {"open" | "wep" | "wpa2" | "wpa3"} OnboardingFlowWifiSecurity */
+/**
+ * @typedef {| "waiting"
+ *   | "approved"
+ *   | "rejected"
+ *   | "expired"
+ *   | "cancelled"} OnboardingFlowApprovalState
+ */
+/**
+ * Access-code rail (2026-08-10 design): `code-already-bound`/`access-code-invalid` are the
+ * node's outright refusal of this device's claim — the code is already bound to a different
+ * device, or the supplied/missing code did not match.
+ * @typedef {| "approval-expired"
+ *   | "approval-rejected"
+ *   | "wifi-credentials-rejected"
+ *   | "wifi-scan-failed"
+ *   | "wifi-unreachable"
+ *   | "invitation-invalid"
+ *   | "claim-failed"
+ *   | "code-already-bound"
+ *   | "access-code-invalid"} OnboardingFlowReasonCode
+ */
+/**
+ * @typedef {OnboardingFlowRowBase & ({
+ *     readonly networks: readonly OnboardingFlowNetwork[];
+ *     readonly scanning: boolean;
+ *     readonly stepId: "choose-network";
+ *   }
+ *   | {
+ *     readonly security: OnboardingFlowWifiSecurity;
+ *     readonly ssid: string;
+ *     readonly stepId: "network-password";
+ *   }
+ *   | {
+ *     readonly approvalState: OnboardingFlowApprovalState;
+ *     readonly digits: readonly string[];
+ *     readonly remainingSeconds: number;
+ *     readonly stepId: "match-code";
+ *   }
+ *   | {
+ *     readonly inviteRequired: boolean;
+ *     readonly stepId: "invitation";
+ *   }
+ *   | {
+ *     readonly displayName: string;
+ *     readonly displayNameLocked: boolean;
+ *     readonly stepId: "identity";
+ *     readonly submitting: boolean;
+ *   }
+ *   | {
+ *     readonly sessionEstablished: boolean;
+ *     readonly stepId: "trusted";
+ *   }
+ *   | {
+ *     readonly ssid: string;
+ *     readonly stepId: "handoff";
+ *   }
+ *   | {
+ *     readonly stepId: Exclude<
+ *       OnboardingFlowStepId,
+ *       | "choose-network"
+ *       | "handoff"
+ *       | "identity"
+ *       | "invitation"
+ *       | "match-code"
+ *       | "network-password"
+ *       | "trusted"
+ *     >;
+ *   })} OnboardingFlowRow
+ */
+/**
+ * @typedef {Pick<
+ *   OwnerClaimService,
+ *   "awaitConfirmation" | "cancel" | "completeClaim" | "prepareClaim"
+ * >} OnboardingFlowClaimPort
+ */
+/** @typedef {Pick<InviteRedemptionService, "redeem">} OnboardingFlowInvitePort */
+/**
+ * @typedef {Pick<
+ *   WifiProvisioningService,
+ *   "awaitHandoff" | "awaitReconnect" | "configure" | "scan" | "status"
+ * >} OnboardingFlowWifiPort
+ */
+/** @typedef {Pick<LcdDecisionService, "confirm" | "reject">} OnboardingFlowLcdPort */
+/**
+ * @typedef {object} OnboardingFlowNetwork
+ * @property {OnboardingFlowWifiSecurity} security
+ * @property {number} signal
+ * @property {string} ssid
+ */
+/**
+ * @typedef {object} OnboardingFlowRowBase
+ * @property {OnboardingFlowLcdScreenId} lcdScreenId
+ * @property {OnboardingFlowPhase} phase
+ * @property {OnboardingFlowReasonCode} [reasonCode]
+ * @property {number} stepIndex
+ * @property {number} totalSteps
+ */
+/**
+ * @typedef {object} OnboardingFlowLcdScreen
+ * @property {boolean} awaitingNode
+ * @property {boolean} physicalTapOnly
+ * @property {OnboardingFlowLcdScreenId} screenId
+ * @property {Readonly<Record<string, number | string>>} state
+ */
+/**
+ * @typedef {object} OnboardingFlowServiceOptions
+ * @property {OnboardingAccessCodeStore} accessCodes The onboarding access-code rail (2026-08-10 design): scanning the step-6 QR carries a short
+ * code that becomes this claim attempt's physical-presence proof, replacing the match-code
+ * screen entirely. A non-null `read()` at `start()` time LATCHES the flow into access-code
+ * mode for its whole lifetime — see `#accessCodeMode`'s own doc comment. Required, not
+ * optional: every composition must decide explicitly, even if that decision is "wire a store
+ * that never holds a code" (a headless or test composition).
+ * @property {Pick<OnboardingCheckpointStore, "clear" | "read" | "write">} checkpoints
+ * @property {OnboardingFlowClaimPort} claim
+ * @property {() => boolean} [invitationRequired]
+ * @property {() => boolean} invitationsEnabled
+ * @property {OnboardingFlowInvitePort} invites
+ * @property {OnboardingFlowLcdPort} [lcd]
+ * @property {() => string} now
+ * @property {OnboardingPresencePort} [presence]
+ * @property {(stepId: OnboardingFlowStepId) => void} publish
+ * @property {OnboardingFlowWifiPort} wifi
+ */
+/**
+ * @typedef {object} OnboardingFlowStep
+ * @property {"invitations"} [gate]
+ * @property {OnboardingFlowStepId} id
+ * @property {OnboardingFlowLcdScreenId} lcdScreenId
+ * @property {OnboardingFlowPhase} phase
+ */
+// @ts-check