@econ-v1/domain 6.7.0 → 6.10.0

package/{dist → src}/services/wallet-mirror-service.js

@@ -1,19 +1,95 @@
+// @ts-check
+
+/**
+ * @typedef {import("@econ-v1/ports").HomeNodeClient} HomeNodeClient
+ */
+/**
+ * @typedef {import("@econ-v1/ports").OutboxRecord} OutboxRecord
+ */
+/**
+ * @typedef {import("@econ-v1/ports").OutboxRepository} OutboxRepository
+ */
+/**
+ * @template TPayload
+ * @typedef {import("../models/sync.js").AuthoritativeCommand<TPayload>} AuthoritativeCommand
+ */
+/**
+ * @template TPayload
+ * @typedef {import("../models/sync.js").SyncDelta<TPayload>} SyncDelta
+ */
+/**
+ * @typedef {import("../models/sync.js").SyncApplyResult} SyncApplyResult
+ */
+/**
+ * @typedef {import("../models/wallet.js").CreateInvoiceInput} CreateInvoiceInput
+ */
+/**
+ * @typedef {import("../models/wallet.js").PaymentHistoryView} PaymentHistoryView
+ */
+/**
+ * @typedef {import("../models/wallet.js").PayInvoiceInput} PayInvoiceInput
+ */
+/**
+ * @typedef {import("../models/wallet.js").WalletAuthoritativeSnapshot} WalletAuthoritativeSnapshot
+ */
+/**
+ * @typedef {import("../models/wallet.js").WalletBalanceView} WalletBalanceView
+ */
+/**
+ * @typedef {import("../models/wallet.js").WalletCommand} WalletCommand
+ */
+/**
+ * @typedef {import("../models/wallet.js").WalletMirrorRepository} WalletMirrorRepository
+ */
+/**
+ * @typedef {import("../models/wallet.js").WalletSnapshotPayload} WalletSnapshotPayload
+ */
+/**
+ * @typedef {import("../models/payment.js").WalletCommandResult} WalletCommandResult
+ */
+/**
+ * @typedef {import("../models/l402.js").L402HistoryView} L402HistoryView
+ */
+/**
+ * @typedef {{ readonly id?: () => string; readonly now?: () => string; readonly staleAfterMs: number; }} WalletMirrorServiceOptions
+ */
 import { AuthoritativeMirror, AuthoritativeRevalidationRequiredError, } from "./sync/index.js";
+/**
+ * @extends {Error}
+ */
 export class OfflineWalletCommandError extends Error {
     constructor() {
         super("Wallet commands require an online home node");
         this.name = "OfflineWalletCommandError";
     }
 }
+/**
+ * @extends {Error}
+ */
 export class WalletFreshStateRequiredError extends Error {
     constructor() {
         super("Wallet state could not be freshly revalidated; confirm again when connected");
         this.name = "WalletFreshStateRequiredError";
     }
 }
+/**
+ * @extends {Error}
+ */
 export class InsufficientWalletBalanceError extends Error {
+    /**
+   * @readonly
+   * @type {number}
+   */
     amountMsat;
+    /**
+   * @readonly
+   * @type {number}
+   */
     spendableMsat;
+    /**
+   * @param {number} amountMsat
+   * @param {number} spendableMsat
+   */
     constructor(amountMsat, spendableMsat) {
         super("The authoritative wallet balance is insufficient for this payment");
         this.name = "InsufficientWalletBalanceError";
@@ -21,12 +97,18 @@ export class InsufficientWalletBalanceError extends Error {
         this.spendableMsat = spendableMsat;
     }
 }
+/**
+ * @extends {Error}
+ */
 export class ExpiredInvoiceError extends Error {
     constructor() {
         super("The invoice has expired");
         this.name = "ExpiredInvoiceError";
     }
 }
+/**
+ * @extends {Error}
+ */
 export class WalletCommandRejectedError extends Error {
     constructor() {
         super("The authoritative wallet command was rejected");
@@ -34,12 +116,40 @@ export class WalletCommandRejectedError extends Error {
     }
 }
 export class WalletMirrorService {
+    /**
+   * @readonly
+   * @type {() => string}
+   */
     #id;
+    /**
+   * @readonly
+   * @type {WalletMirrorRepository}
+   */
     #mirror;
+    /**
+   * @readonly
+   * @type {() => string}
+   */
     #now;
+    /**
+   * @readonly
+   * @type {OutboxRepository}
+   */
     #outbox;
+    /**
+   * @readonly
+   * @type {AuthoritativeMirror<WalletSnapshotPayload, WalletCommand, WalletCommandResult>}
+   */
     #strategy;
+    /**
+   * @readonly
+   * @type {HomeNodeClient}
+   */
     #homeNode;
+    /**
+   * @param {{ readonly homeNode: HomeNodeClient; readonly mirror: WalletMirrorRepository; readonly outbox: OutboxRepository; }} dependencies
+   * @param {WalletMirrorServiceOptions} options
+   */
     constructor(dependencies, options) {
         if (!Number.isInteger(options.staleAfterMs) || options.staleAfterMs <= 0) {
             throw new RangeError("Wallet mirror staleAfterMs must be a positive integer");
@@ -55,9 +165,16 @@ export class WalletMirrorService {
             staleAfterMs: options.staleAfterMs,
         });
     }
+    /**
+   * @param {SyncDelta<WalletSnapshotPayload>} delta
+   * @returns {Promise<SyncApplyResult>}
+   */
     async applyDelta(delta) {
         return await this.#strategy.applyDelta(delta, { domain: "wallet", now: this.#now() });
     }
+    /**
+   * @returns {Promise<WalletBalanceView>}
+   */
     async readBalance() {
         const snapshot = await this.#mirror.readSnapshot();
         if (snapshot === undefined)
@@ -70,6 +187,9 @@ export class WalletMirrorService {
             staleAt: snapshot.staleAt,
         };
     }
+    /**
+   * @returns {Promise<PaymentHistoryView>}
+   */
     async listPayments() {
         const snapshot = await this.#mirror.readSnapshot();
         if (snapshot === undefined)
@@ -81,6 +201,9 @@ export class WalletMirrorService {
             staleAt: snapshot.staleAt,
         };
     }
+    /**
+   * @returns {Promise<L402HistoryView>}
+   */
     async listL402Receipts() {
         const snapshot = await this.#mirror.readSnapshot();
         if (snapshot === undefined)
@@ -92,25 +215,33 @@ export class WalletMirrorService {
             staleAt: snapshot.staleAt,
         };
     }
+    /**
+   * @param {CreateInvoiceInput} input
+   * @returns {Promise<Extract<WalletCommandResult, { readonly kind: "invoice-created" }>>}
+   */
     async createInvoice(input) {
         requirePositiveMsat(input.amountMsat, "invoice amount");
         requireText(input.idempotencyKey, "invoice idempotency key");
-        return await this.#runCommand({
+        return /** @type {Extract<WalletCommandResult, { readonly kind: "invoice-created" }>} */ (await this.#runCommand({
             amountMsat: input.amountMsat,
             ...(input.description === undefined ? {} : { description: input.description }),
             kind: "create-invoice",
         }, input.idempotencyKey, (snapshot) => {
             if (snapshot.value.balanceMsat < 0)
                 throw new WalletFreshStateRequiredError();
-        });
+        }));
     }
+    /**
+   * @param {PayInvoiceInput} input
+   * @returns {Promise<Extract<WalletCommandResult, { readonly kind: "payment-submitted" }>>}
+   */
     async payInvoice(input) {
         requirePositiveMsat(input.amountMsat, "payment amount");
         requireText(input.idempotencyKey, "payment idempotency key");
         requireText(input.invoiceId, "invoice id");
         if (input.expiresAt !== undefined && isExpired(input.expiresAt, this.#now()))
             throw new ExpiredInvoiceError();
-        return await this.#runCommand({
+        return /** @type {Extract<WalletCommandResult, { readonly kind: "payment-submitted" }>} */ (await this.#runCommand({
             amountMsat: input.amountMsat,
             ...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),
             invoiceId: input.invoiceId,
@@ -119,8 +250,14 @@ export class WalletMirrorService {
             if (input.amountMsat > snapshot.value.spendableMsat) {
                 throw new InsufficientWalletBalanceError(input.amountMsat, snapshot.value.spendableMsat);
             }
-        });
+        }));
     }
+    /**
+   * @param {WalletCommand} command
+   * @param {string} idempotencyKey
+   * @param {(snapshot: WalletAuthoritativeSnapshot) => void} validate
+   * @returns {Promise<WalletCommandResult>}
+   */
     async #runCommand(command, idempotencyKey, validate) {
         const cached = await this.#mirror.readCommandResult(idempotencyKey);
         if (cached !== undefined)
@@ -161,6 +298,9 @@ export class WalletMirrorService {
             throw error instanceof WalletFreshStateRequiredError ? error : new WalletCommandRejectedError();
         }
     }
+    /**
+   * @returns {Promise<WalletAuthoritativeSnapshot>}
+   */
     async #ensureFresh() {
         const current = await this.#mirror.readSnapshot();
         if (current !== undefined && this.#isFresh(current))
@@ -181,6 +321,10 @@ export class WalletMirrorService {
             throw new WalletFreshStateRequiredError();
         return refreshed;
     }
+    /**
+   * @param {AuthoritativeCommand<WalletCommand>} command
+   * @returns {Promise<WalletCommandResult>}
+   */
     async #execute(command) {
         this.#assertOnline();
         try {
@@ -198,6 +342,11 @@ export class WalletMirrorService {
             throw new WalletCommandRejectedError();
         }
     }
+    /**
+   * @param {WalletCommand} command
+   * @param {string} idempotencyKey
+   * @returns {OutboxRecord}
+   */
     #outboxRecord(command, idempotencyKey) {
         const createdAt = this.#now();
         return {
@@ -210,13 +359,27 @@ export class WalletMirrorService {
             updatedAt: createdAt,
         };
     }
+    /**
+   * @returns {void}
+   */
     #assertOnline() {
         if (!this.#isOnline())
             throw new OfflineWalletCommandError();
     }
+    /**
+   * @returns {boolean}
+   */
     #isOnline() { return this.#homeNode.state.status === "connected"; }
+    /**
+   * @param {WalletAuthoritativeSnapshot} snapshot
+   * @returns {boolean}
+   */
     #isFresh(snapshot) { return Date.parse(this.#now()) < Date.parse(snapshot.staleAt); }
 }
+/**
+ * @param {unknown} value
+ * @returns {WalletSnapshotPayload}
+ */
 function parseSnapshotPayload(value) {
     const record = asRecord(value, "wallet snapshot");
     return {
@@ -226,6 +389,11 @@ function parseSnapshotPayload(value) {
         spendableMsat: positiveOrZero(record.spendableMsat, "wallet spendable balance"),
     };
 }
+/**
+ * @param {unknown} value
+ * @param {number} amountMsat
+ * @returns {Extract<WalletCommandResult, { readonly kind: "invoice-created" }>}
+ */
 function parseInvoiceResult(value, amountMsat) {
     const record = asRecord(value, "invoice result");
     const invoiceId = text(record.invoiceId, "invoice id");
@@ -239,6 +407,11 @@ function parseInvoiceResult(value, amountMsat) {
         status: "created",
     };
 }
+/**
+ * @param {unknown} value
+ * @param {number} amountMsat
+ * @returns {Extract<WalletCommandResult, { readonly kind: "payment-submitted" }>}
+ */
 function parsePaymentResult(value, amountMsat) {
     const record = asRecord(value, "payment result");
     const status = record.status ?? "pending";
@@ -252,6 +425,10 @@ function parsePaymentResult(value, amountMsat) {
         status,
     };
 }
+/**
+ * @param {unknown} value
+ * @returns {WalletSnapshotPayload["payments"]}
+ */
 function parsePayments(value) {
     if (value === undefined)
         return [];
@@ -277,6 +454,10 @@ function parsePayments(value) {
         };
     });
 }
+/**
+ * @param {unknown} value
+ * @returns {WalletSnapshotPayload["l402"]}
+ */
 function parseL402(value) {
     if (value === undefined)
         return [];
@@ -293,42 +474,81 @@ function parseL402(value) {
         };
     });
 }
+/**
+ * @param {unknown} value
+ * @param {string} _label
+ * @returns {Record<string, unknown>}
+ */
 function asRecord(value, _label) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         throw new WalletFreshStateRequiredError();
-    return value;
+    return /** @type {Record<string, unknown>} */ (value);
 }
+/**
+ * @param {unknown} value
+ * @param {string} _label
+ * @returns {string}
+ */
 function text(value, _label) {
     if (typeof value !== "string" || value.trim() === "")
         throw new WalletCommandRejectedError();
     return value;
 }
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {string}
+ */
 function timestamp(value, label) {
     const parsed = text(value, label);
     if (!Number.isFinite(Date.parse(parsed)))
         throw new WalletFreshStateRequiredError();
     return parsed;
 }
+/**
+ * @param {unknown} value
+ * @param {string} _label
+ * @returns {number}
+ */
 function positiveOrZero(value, _label) {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
         throw new WalletFreshStateRequiredError();
     return value;
 }
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
 function numberOrDefault(value, fallback) {
     return value === undefined ? fallback : positiveOrZero(value, "amount");
 }
+/**
+ * @param {number} value
+ * @param {string} label
+ * @returns {void}
+ */
 function requirePositiveMsat(value, label) {
     if (!Number.isSafeInteger(value) || value <= 0)
         throw new TypeError(`${label} must be a positive integer`);
 }
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {void}
+ */
 function requireText(value, label) {
     if (value.trim() === "")
         throw new TypeError(`${label} must be a non-empty string`);
 }
+/**
+ * @param {string} expiresAt
+ * @param {string} now
+ * @returns {boolean}
+ */
 function isExpired(expiresAt, now) {
     const expiry = Date.parse(expiresAt);
     if (!Number.isFinite(expiry))
         throw new TypeError("invoice expiry must be an ISO timestamp");
     return expiry <= Date.parse(now);
 }
-//# sourceMappingURL=wallet-mirror-service.js.map

package/src/services/wifi-provisioning-service.js

@@ -0,0 +1,278 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').DelayPort} DelayPort */
+/** @typedef {import('@econ-v1/ports').HomeNodeClient} HomeNodeClient */
+import { DomainError } from "../errors/index.js";
+const HANDOFF_POLL_INTERVAL_MS = 3000;
+const HANDOFF_TRANSPORT_LOST_POLLS = 2;
+const RECONNECT_POLL_INTERVAL_MS = 4000;
+export class WifiProvisioningService {
+  /**
+   * @param {() => boolean} [shouldContinue]
+   * @returns {Promise<WifiReconnectOutcome>}
+   */
+  async awaitReconnect(shouldContinue = () => true) {
+    for (;;) {
+      if (!shouldContinue()) return "superseded";
+      const outcome = await this.status();
+      if (outcome.kind === "connected") return "connected";
+      await this.#delay.wait(RECONNECT_POLL_INTERVAL_MS);
+    }
+  }
+  /**
+   * @readonly
+   */
+  #delay;
+  /**
+   * @readonly
+   */
+  #node;
+  /**
+   * @readonly
+   */
+  #now;
+  /**
+   * @param {WifiProvisioningServiceOptions} options
+   */
+  constructor(options) {
+    this.#delay = options.delay;
+    this.#node = options.node;
+    this.#now = options.now;
+  }
+  /**
+   * Whether the node is ALREADY joined to a home network. Asked once at flow entry so a person
+   * who configured Wi-Fi on the node's own captive portal is never marched through the
+   * credential steps a second time — resubmitting working credentials is not idempotent on the
+   * node side (the join tears down and re-adds the connection) and a handshake flake in that
+   * window strands the node back in setup AP mode. The wire values are node-server's
+   * `http_status` PascalCase strings; only an explicit `"Connected"` counts.
+   * @returns {Promise<WifiStatusOutcome>}
+   */
+  async status() {
+    try {
+      const wire = await this.#node.invoke({
+        operation: "GET /api/v2/wifi/status",
+        payload: {},
+      });
+      if (wire.connection_status !== "Connected")
+        return { kind: "not-connected" };
+      return {
+        kind: "connected",
+        ssid: typeof wire.current_ssid === "string" ? wire.current_ssid : "",
+      };
+    } catch {
+      return { kind: "unreachable" };
+    }
+  }
+  /** Lists what the node's radio can currently see. A failure is a first-class outcome, not a
+   * throw: step 4 stays on screen and offers "Scan again".
+   * @returns {Promise<WifiScanOutcome>}
+   */
+  async scan() {
+    try {
+      const wire = await this.#node.invoke({
+        operation: "GET /api/v2/wifi/scan",
+        payload: {},
+      });
+      const rows = Array.isArray(wire.networks) ? wire.networks : [];
+      /** @type {WifiProvisioningNetwork[]} */
+      const networks = [];
+      for (const row of rows) {
+        const ssid = typeof row.ssid === "string" ? row.ssid : "";
+        if (ssid.length === 0) continue;
+        networks.push({
+          security: normaliseSecurity(row.security),
+          signal: clampSignal(row.signal_quality_percent),
+          ssid,
+        });
+      }
+      return { kind: "scanned", networks };
+    } catch {
+      return { kind: "scan-failed" };
+    }
+  }
+  /**
+   * Hands the credentials to the node exactly once. `secret === undefined` means an open
+   * network, in which case the `password` key is omitted rather than sent as an empty string —
+   * the node validates length 8-63 whenever the field is present.
+   * @param {string} ssid
+   * @param {string | undefined} secret
+   * @returns {Promise<WifiConfigureOutcome>}
+   */
+  async configure(ssid, secret) {
+    /** @type {{ auto_connect: boolean, hidden: boolean, password?: string, priority: number, ssid: string }} */
+    /** @type {Record<string, unknown>} */
+    const payload = {
+      auto_connect: true,
+      hidden: false,
+      priority: 100,
+      ssid,
+    };
+    if (secret !== undefined) payload.password = secret;
+    try {
+      const wire = await this.#node.invoke({
+        operation: "POST /api/v2/wifi/configure",
+        payload,
+      });
+      const operationId =
+        typeof wire.operation_id === "string" ? wire.operation_id : "";
+      // No handle means nothing to watch. Reporting "accepted" here would strand step 6 forever.
+      if (operationId.length === 0) return { kind: "unreachable" };
+      return { kind: "accepted", operationId };
+    } catch (error) {
+      // The node validates ssid/password shape before it ever touches the radio, and
+      // `PrePairingHomeNodeClient` maps that envelope onto `invalid_request`. Everything else —
+      // transport, 5xx, unknown envelope — is "we could not tell", never a credential verdict.
+      if (error instanceof DomainError && error.code === "invalid_request") {
+        return { kind: "credentials-rejected" };
+      }
+      return { kind: "unreachable" };
+    }
+  }
+  /**
+   * Watches one configure operation across the network handoff. See the class comment: a
+   * thrown poll is EXPECTED and means "keep waiting".
+   *
+   * `deadline` is an absolute epoch-millisecond value from the same clock as `now`, supplied by
+   * the caller so a resumed flow can keep the ORIGINAL deadline rather than restarting it.
+   * @param {string} operationId
+   * @param {number} deadline
+   * @param {() => void} [onTransportLost]
+   * @returns {Promise<WifiHandoffOutcome>}
+   */
+  async awaitHandoff(operationId, deadline, onTransportLost) {
+    const operation = `GET /api/v2/wifi/operations/${encodeURIComponent(operationId)}`;
+    let consecutiveFailures = 0;
+    let reportedTransportLost = false;
+    for (;;) {
+      try {
+        const wire = await this.#node.invoke({ operation, payload: {} });
+        consecutiveFailures = 0;
+        const status = typeof wire.status === "string" ? wire.status : "";
+        if (status === "Connected") return "connected";
+        if (status === "Failed") return "credentials-rejected";
+      } catch {
+        consecutiveFailures += 1;
+        if (consecutiveFailures >= HANDOFF_TRANSPORT_LOST_POLLS && !reportedTransportLost) {
+          reportedTransportLost = true;
+          try {
+            onTransportLost?.();
+          } catch {
+            // The caller's problem, never this loop's.
+          }
+        }
+      }
+      if (this.#now() >= deadline) return "unreachable";
+      await this.#delay.wait(HANDOFF_POLL_INTERVAL_MS);
+    }
+  }
+}
+/** The node reports whatever its supplicant said. Anything not recognisably open/WEP/WPA3 is
+ * treated as WPA2 — the conservative choice, because it demands a password rather than
+ * silently offering to join without one.
+ * @param {unknown} value
+ * @returns {WifiProvisioningSecurity}
+ */
+function normaliseSecurity(value) {
+  if (typeof value !== "string") return "wpa2";
+  const lowered = value.toLowerCase();
+  if (lowered.includes("wpa3")) return "wpa3";
+  if (lowered.includes("wep")) return "wep";
+  if (lowered === "open" || lowered === "none" || lowered === "") return "open";
+  return "wpa2";
+}
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function clampSignal(value) {
+  if (typeof value !== "number" || Number.isNaN(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 100) return 100;
+  return Math.round(value);
+}
+/**
+ * The node's Wi-Fi provisioning surface, expressed as three operations with CLOSED outcome
+ * unions (design §10). Nothing here throws at its caller and nothing here returns node text:
+ * `OnboardingFlowService` turns these outcomes into `OnboardingReasonCode`s, and the UI turns
+ * those into copy. A raw `DomainError.message` reaching a subscriber would be both a leak and
+ * an unreviewable string in the product.
+ *
+ * THE CENTRAL DIFFICULTY is `awaitHandoff()`. Between `configure()` and the node reporting
+ * `Connected`, the node LEAVES its own access point and joins the home network — the browser
+ * that issued the request is on that access point, so the poll *is expected to fail*, possibly
+ * for the entire operation. A thrown request here therefore means "keep waiting", not "it
+ * broke"; only three things end the wait:
+ *
+ *   - the node answering `Connected`      -> "connected"           (it came back, on the LAN)
+ *   - the node answering `Failed`         -> "credentials-rejected" (it came back to say no)
+ *   - the deadline passing                -> "unreachable"          (step 7's manual way back)
+ *
+ * `Failed` is the ONLY signal that distinguishes a wrong password from a normal handoff, which
+ * is why it must not be collapsed into the generic failure branch: collapsing it would send a
+ * person who mistyped their password to "walk back to your node" instead of to the keyboard.
+ *
+ * The status strings are the node's, verified against
+ * `core/adapters-network/src/http/server/wifi.rs::http_operation_status`, which maps its
+ * internal states onto exactly `"Connected"` / `"Failed"` / `"Connecting"` / `"Pending"`.
+ * (The design doc's "Completed" is wrong; the wire value is "Connected".)
+ *
+ * SECURITY: `configure()` takes the secret as an argument and forwards it in a single request.
+ * It is never assigned to a field, never returned, never logged, and never included in an
+ * outcome — `WifiConfigureOutcome` has no field it could occupy.
+ * @typedef {"open" | "wep" | "wpa2" | "wpa3"} WifiProvisioningSecurity
+ */
+/**
+ * @typedef {| { readonly kind: "scanned"; readonly networks: readonly WifiProvisioningNetwork[] }
+ *   | { readonly kind: "scan-failed" }} WifiScanOutcome
+ */
+/**
+ * @typedef {| { readonly kind: "accepted"; readonly operationId: string }
+ *   | { readonly kind: "credentials-rejected" }
+ *   | { readonly kind: "unreachable" }} WifiConfigureOutcome
+ */
+/** @typedef {"connected" | "credentials-rejected" | "unreachable"} WifiHandoffOutcome */
+/** @typedef {"connected" | "superseded"} WifiReconnectOutcome */
+/** What the node's radio is doing RIGHT NOW, asked once at flow entry. `connected` carries the
+ * joined SSID so the flow can show which network needs no credentials. `unreachable` collapses
+ * every failure — a flow that cannot ask simply walks the ordinary Wi-Fi steps.
+ * @typedef {| { readonly kind: "connected"; readonly ssid: string }
+ *   | { readonly kind: "not-connected" }
+ *   | { readonly kind: "unreachable" }} WifiStatusOutcome
+ */
+/**
+ * @typedef {object} WifiProvisioningNetwork
+ * @property {WifiProvisioningSecurity} security
+ * @property {number} signal 0-100 signal quality. dBm never crosses this boundary.
+ * @property {string} ssid
+ */
+/**
+ * @typedef {object} WifiProvisioningServiceOptions
+ * @property {Pick<DelayPort, "wait">} delay
+ * @property {Pick<HomeNodeClient, "invoke">} node
+ * @property {() => number} now Epoch milliseconds. Injected so the deadline is testable and domain owns no clock.
+ */
+/**
+ * @typedef {object} WifiScanRowWire
+ * @property {unknown} [security]
+ * @property {unknown} [signal_quality_percent]
+ * @property {unknown} [ssid]
+ */
+/**
+ * @typedef {object} WifiScanWire
+ * @property {readonly WifiScanRowWire[]} [networks]
+ */
+/**
+ * @typedef {object} WifiConfigureWire
+ * @property {unknown} [operation_id]
+ * @property {unknown} [success]
+ */
+/**
+ * @typedef {object} WifiOperationStatusWire
+ * @property {unknown} [status]
+ */
+/**
+ * @typedef {object} WifiStatusWire
+ * @property {unknown} [connection_status]
+ * @property {unknown} [current_ssid]
+ */
+// @ts-check