@econ-v1/ports 6.7.0 → 6.10.0

package/src/lcd-tree-source.js

@@ -0,0 +1,56 @@
+// @ts-check
+/**
+ * The seam through which the LCD pane obtains the widget tree the node's round display is
+ * currently showing (design §8.1).
+ *
+ * The pane is a `client/ui` surface and `client/ui` may never call `fetch` (rule B2, enforced
+ * by `client/scripts/check-boundaries.mjs`), so the two HTTP calls that produce a tree —
+ * `POST /lcd/screens/:id/state` then `GET /lcd/screens/:id/preview` against
+ * `modules/node-app-lcd`'s debug server — live in `client/adapters-web` behind this port.
+ * `client/domain` holds the port and never learns there is a network at all.
+ *
+ * `screen()` returns a CLOSED OUTCOME UNION and never rejects. That is not stylistic: the
+ * only consumer is a live query, and `LiveQueryEngine.#enqueue` does
+ * `void run.catch(() => undefined)` — a rejected `run()` never reaches the subscriber, so a
+ * throwing source would freeze the pane on a stale screen with no error and no retry. The
+ * failure must be data.
+ *
+ * Nothing here carries node error text. `"unreachable"` covers offline, DNS failure, a 5xx,
+ * a malformed body and a missing dev proxy alike; `"not-registered"` is specifically "this
+ * node's LCD app has no screen with that id", which is the normal answer for a screen whose
+ * Rust `build()` has not been written yet.
+ */
+/**
+ * For every composition without a reachable LCD daemon — production (where the pane is not
+ * shipped at all), tests, and any headless kernel. Reporting `"unreachable"` is the honest
+ * answer and drives the pane's §8.4 placeholder; it is also the SAFE direction, because the
+ * pane is never on onboarding's critical path and the device pane continues regardless.
+ * @returns {LcdTreeSourcePort}
+ */
+export function createNullLcdTreeSource() {
+  return { screen: async () => ({ kind: "unreachable" }) };
+}
+/** An RFC-7396 JSON Merge Patch applied to the screen's registry state before its tree is
+ * built. Scalars only: every built-in screen's `initial_state` is a flat scalar map.
+ * @typedef {Readonly<Record<string, number | string>>} LcdScreenStatePatch
+ */
+/**
+ * @typedef {| { readonly kind: "not-registered" }
+ *   | { readonly kind: "tree"; readonly tree: LcdTreeNode }
+ *   | { readonly kind: "unreachable" }} LcdTreeOutcome
+ */
+/**
+ * The serde-flattened `Node` the LCD engine emits: `{ id, type, ...props, children }`, where
+ * the props are spread onto the node itself and `type` is the discriminant
+ * (`modules/node-app-lcd/src/lcd/engine/components/node.rs`). Deliberately loose — a renderer
+ * switches on `type` and reads the props it knows, and a screen growing a field must not
+ * break this seam.
+ * @typedef {Readonly<Record<string, unknown>> & object} LcdTreeNode
+ * @property {readonly LcdTreeNode[]} [children]
+ * @property {string} id
+ * @property {string} type
+ */
+/**
+ * @typedef {object} LcdTreeSourcePort
+ * @property {(screenId: string, state: LcdScreenStatePatch) => Promise<LcdTreeOutcome>} screen
+ */

package/src/legacy-credential.js

@@ -0,0 +1,30 @@
+// @ts-check
+export {};
+/**
+ * Whether this browser holds a credential the LEGACY `system/ui` SPA can sign in with.
+ *
+ * `"unknown"` is a first-class answer, not an error: a storage-partitioned or
+ * privacy-locked browser genuinely cannot be asked. Callers MUST treat it like `"absent"`
+ * for any safety decision — the only consequence of over-warning is one extra click,
+ * whereas under-warning is the failure this port exists to prevent.
+ * @typedef {"absent" | "present" | "unknown"} LegacyCredentialStatus
+ */
+/**
+ * Answers "would the classic UI recognise this browser?" WITHOUT bridging the two
+ * authentication systems.
+ *
+ * The two UIs deliberately do not share an identity: the legacy SPA signs in with a
+ * secp256k1 device key in its own IndexedDB (migrated once from a BIP39 seed —
+ * `system/ui/src/lib/deviceKey.ts`), while the Client Node PWA uses a paired device
+ * identity + device session it never converts back into a seed. `client/kernel`'s
+ * `LegacyStorageReader` imports legacy state INTO the PWA for the v1 cutover and nothing
+ * writes the reverse, so a PWA-onboarded browser has no legacy credential at all.
+ *
+ * This port therefore reports PRESENCE ONLY. It never reads, returns, derives, or
+ * provisions key material — implementations are expected to test for the record's
+ * existence without deserializing its value. Answering this question is what lets the
+ * "Switch to the classic UI" control warn honestly instead of dropping a PWA-onboarded
+ * user onto a sign-in screen they cannot satisfy.
+ * @typedef {object} LegacyCredentialProbePort
+ * @property {() => Promise<LegacyCredentialStatus>} status
+ */

package/src/media-preferences.js

@@ -0,0 +1,40 @@
+// @ts-check
+
+/**
+ * Boundary port for the two NON-THEME media queries the shell reads (#1687).
+ *
+ * `client/ui` may never call `matchMedia` directly (boundary rule B2,
+ * `client/scripts/check-boundaries.mjs`) — this is the narrow surface
+ * `client/adapters-web`'s `createBrowserMediaPreferences()` implements against the real
+ * global, and the composition root (`system/pwa/src/main.ts`) registers it (via
+ * `client/ui`'s `configureMediaPreferences`) before the shell's first paint.
+ *
+ * Deliberately SEPARATE from `ThemeEnvironmentPort` rather than folded into it, even
+ * though both end up calling `matchMedia` in their adapters:
+ *
+ *   - `ThemeEnvironmentPort` models the *theme preference* as a whole — a value with
+ *     PERSISTENCE (`getStoredTheme`/`setStoredTheme` over `localStorage`) where the media
+ *     query is only the fallback when nothing is stored, plus a live `change`
+ *     subscription because a theme flip must repaint mid-session. Its concern is
+ *     `prefers-color-scheme`.
+ *   - The queries here are neither theme nor persisted nor live: `prefers-reduced-motion`
+ *     (`stages/waves-stage.ts`, `stages/waves-canvas.ts`) is an accessibility/motion
+ *     preference, and `(hover: hover) and (pointer: fine)` (`shell/pmenu.ts`) is a
+ *     pointer-capability probe. Both are read ONCE, at mount/connect time, matching the
+ *     original skin's own one-shot checks — neither has a stored override to consult nor
+ *     a subscription to tear down.
+ *
+ * Folding them into `ThemeEnvironmentPort` would make a port named for theme answer
+ * questions about motion and pointers, and would oblige every fake in the test suite (and
+ * `theme-environment.ts`'s `NOOP_THEME_ENVIRONMENT`) to stub three unrelated concerns to
+ * exercise one. Two narrow ports, one adapter technology.
+ *
+ * Both methods are synchronous and side-effect-free, for the same reason
+ * `ThemeEnvironmentPort`'s are: they are read during `connectedCallback`/`mount`, before
+ * the kernel connection (`KernelRpcClient`, an async `SharedWorker`/leader-tab bridge)
+ * exists, so they can never be mediated through `@econ-v1/rpc` the way ordinary UI
+ * reads are (rule S4).
+ */
+/** @typedef {{ prefersReducedMotion(): boolean, hasFinePointer(): boolean }} MediaPreferencesPort */
+
+export {};

package/src/network/certificate-trust.js

@@ -0,0 +1,25 @@
+// @ts-check
+export {};
+/** @typedef {"android" | "apple-mobile" | "apple-mac" | "firefox" | "windows" | "linux" | "unknown"} CertificateTrustPlatform */
+/**
+ * `untrusted` and `unreachable` are deliberately separate outcomes, not one
+ * failure bucket. They look identical to the probe's caller — neither unlocks
+ * the shell — but they have opposite remedies, and telling a person to install
+ * a certificate authority when the real problem is that their node stopped
+ * answering sends them somewhere they cannot succeed. `untrusted` means the
+ * node answered and the browser refused the chain; `unreachable` means the
+ * request never produced a response at all (DNS failure, connection refused,
+ * a certificate the browser rejects before any HTTP exchange, or a timeout).
+ * @typedef {| { readonly status: "trusted"; readonly origin: string; readonly fingerprint?: string }
+ *   | { readonly status: "untrusted"; readonly origin: string; readonly fingerprint?: string }
+ *   | { readonly status: "unreachable"; readonly origin: string }} CertificateTrustProbeResult
+ */
+/**
+ * @typedef {object} CertificateTrustProbePort
+ * @property {(origin: string, signal?: CancellationSignal) => Promise<CertificateTrustProbeResult>} probe
+ */
+/**
+ * @typedef {object} PlatformTrustPort
+ * @property {() => CertificateTrustPlatform} detect
+ */
+/** @import { CancellationSignal } from '../network.js' */

package/src/network/client-node-origin.js

@@ -0,0 +1,7 @@
+// @ts-check
+
+/**
+ * The Client Node PWA's cloud distribution origin. This static origin is never itself a
+ * dialable home node.
+ */
+export const DEFAULT_CLIENT_NODE_ORIGIN = "https://client-node.economy1.cloud";

package/src/network/home-node-candidate-store.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+/** @typedef {{ readonly address: string, readonly id: string }} StoredHomeNodeCandidate */
+/** @typedef {{ read(): StoredHomeNodeCandidate | undefined, write(candidate: StoredHomeNodeCandidate): void, clear(): void }} HomeNodeCandidateStorePort */
+
+export {};

package/src/network/home-node-candidate.js

@@ -0,0 +1,9 @@
+// @ts-check
+
+/** @typedef {import("../network.js").CancellationSignal} CancellationSignal */
+/** @typedef {import("../network.js").HomeNodeClient} HomeNodeClient */
+/** @typedef {Exclude<import("../network.js").TransportPath, "offline">} HomeNodePath */
+/** @typedef {{ readonly address: string, readonly id: string, readonly path: HomeNodePath }} HomeNodeCandidate */
+/** @typedef {{ dial(candidate: HomeNodeCandidate, signal: CancellationSignal): Promise<HomeNodeClient> }} HomeNodeDialer */
+
+export {};

package/src/network/l402-payment.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+/**
+ * The domain-level shape of an L402 payment challenge. Never log `macaroon`
+ * or `invoice`: both are credential/payment-secret material.
+ *
+ * @typedef {{ readonly amountSats: number, readonly description: string, readonly invoice: string, readonly macaroon: string }} L402PaymentChallenge
+ */
+
+/** @typedef {{ readonly preimage: string }} L402PaymentResult */
+
+/**
+ * Pluggable port supplied by the kernel or composition root to pay an L402
+ * challenge surfaced by a client-RPC carrier.
+ *
+ * @typedef {object} L402PaymentHandler
+ * @property {(challenge: L402PaymentChallenge) => Promise<L402PaymentResult>} pay
+ */
+
+export {};

package/src/network/node-discovery.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+/** @typedef {{ readonly address: string, readonly id: string, readonly path: "lan-direct" }} NodeDiscoveryCandidate */
+/**
+ * @typedef {
+ *   | { readonly status: "verified", readonly candidate: NodeDiscoveryCandidate }
+ *   | { readonly status: "reached-but-invalid", readonly reason: string }
+ *   | { readonly status: "unreachable-or-untrusted" }
+ * } NodeDiscoveryResult
+ */
+/** @typedef {{ discover(rawAddress: string): Promise<NodeDiscoveryResult> }} NodeAddressDiscoverer */
+
+export {};

package/src/network/webrtc-signaling.js

@@ -0,0 +1,40 @@
+// @ts-check
+
+/** @typedef {import("../network.js").CancellationSignal} CancellationSignal */
+
+export const WEBRTC_SIGNAL_VERSION = 1;
+
+/** Maximum serialized size of one signaling WebSocket text frame. */
+export const MAX_WEBRTC_SIGNAL_MESSAGE_BYTES = 32 * 1024;
+/** Maximum SDP body size (offer, answer, or restart). */
+export const MAX_SDP_BYTES = 16 * 1024;
+export const MIN_OFFER_NONCE_BYTES = 16;
+export const MAX_OFFER_NONCE_BYTES = 128;
+/** Maximum DTLS fingerprint size: `<algorithm> <hex-pairs>`. */
+export const MAX_DTLS_FINGERPRINT_BYTES = 200;
+/** Maximum size of one trickle-ICE candidate line. */
+export const MAX_ICE_CANDIDATE_BYTES = 1024;
+export const MAX_SDP_MID_BYTES = 64;
+/** Maximum number of trickle-ICE candidates accepted for one bound offer. */
+export const MAX_ICE_CANDIDATES_PER_OFFER = 32;
+export const MAX_CLOSE_REASON_BYTES = 256;
+
+/** @typedef {{ readonly headers: Readonly<Record<string, string>>, readonly type: "setup", readonly version: number }} WebRtcSignalSetup */
+/** @typedef {{ readonly dtls_fingerprint: string, readonly offer_nonce: string, readonly sdp: string, readonly type: "offer", readonly version: number }} WebRtcOffer */
+/** @typedef {{ readonly dtls_fingerprint: string, readonly offer_nonce: string, readonly sdp: string, readonly type: "answer" }} WebRtcAnswer */
+/** @typedef {{ readonly candidate: string, readonly offer_nonce: string, readonly sdp_mid?: string, readonly sdp_mline_index?: number, readonly type: "candidate" }} WebRtcIceCandidate */
+/** @typedef {{ readonly dtls_fingerprint: string, readonly offer_nonce: string, readonly previous_offer_nonce: string, readonly sdp: string, readonly type: "restart", readonly version: number }} WebRtcRestart */
+/** @typedef {{ readonly offer_nonce?: string, readonly reason?: string, readonly type: "close" }} WebRtcClose */
+/** @typedef {WebRtcAnswer | WebRtcClose | WebRtcIceCandidate | WebRtcOffer | WebRtcRestart | WebRtcSignalSetup} WebRtcSignalMessage */
+
+/**
+ * Browser-side signaling transport contract. No peer connection or
+ * DataChannel is created here.
+ *
+ * @typedef {object} WebRtcSignalingPort
+ * @property {(close?: { readonly offer_nonce?: string, readonly reason?: string }) => Promise<void>} close
+ * @property {(setupHeaders: Readonly<Record<string, string>>, signal?: CancellationSignal) => Promise<void>} connect
+ * @property {(candidate: { readonly candidate: string, readonly offer_nonce: string, readonly sdp_mid?: string, readonly sdp_mline_index?: number }) => Promise<void>} sendCandidate
+ * @property {(offer: { readonly dtls_fingerprint: string, readonly offer_nonce: string, readonly sdp: string }) => Promise<WebRtcAnswer>} sendOffer
+ * @property {(restart: { readonly dtls_fingerprint: string, readonly offer_nonce: string, readonly previous_offer_nonce: string, readonly sdp: string }) => Promise<WebRtcAnswer>} sendRestart
+ */

package/src/network.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+/** @typedef {import("./network/home-node-candidate.js").HomeNodeCandidate} HomeNodeCandidate */
+/** @typedef {import("./repositories/repository-mutation.js").RepositoryJsonValue} RepositoryJsonValue */
+
+/** @typedef {"iroh-relay" | "lan-direct" | "lan-webtransport" | "offline" | "wan-direct" | "webrtc-direct"} TransportPath */
+/** @typedef {"lan-direct" | "wan-direct"} HttpTransportPath */
+/** @typedef {"lan-direct" | "lan-webtransport" | "wan-direct"} DirectTransportPath */
+/** @typedef {HomeNodeCandidate & { readonly identityBinding?: "bootstrap", readonly path: HttpTransportPath }} HttpHomeNodeCandidate */
+/** @typedef {{ readonly algorithm: "sha-256", readonly current: string, readonly next: string }} WebTransportCertificateHashes */
+/** @typedef {HomeNodeCandidate & { readonly certificateHashes?: WebTransportCertificateHashes, readonly path: "lan-webtransport" }} WebTransportHomeNodeCandidate */
+/** @typedef {HttpHomeNodeCandidate | WebTransportHomeNodeCandidate} DirectHomeNodeCandidate */
+/** @typedef {"no-network" | "node-unreachable" | "session-required"} TransportOfflineReason */
+/** @typedef {{ readonly changedAt: string, readonly path: "lan-direct" | "lan-webtransport" | "wan-direct" | "iroh-relay" | "webrtc-direct", readonly status: "connected" } | { readonly attempt: number, readonly changedAt: string, readonly path: "offline", readonly status: "connecting" } | { readonly attempt: number, readonly changedAt: string, readonly nextRetryAt: string, readonly path: "offline", readonly status: "reconnecting" } | { readonly changedAt: string, readonly path: "offline", readonly reason?: TransportOfflineReason, readonly status: "offline" }} TransportState */
+/** @typedef {{ readonly headers?: Readonly<Record<string, string>>, readonly operation: string, readonly payload: unknown, readonly responseType?: "blob" | "json" }} HomeNodeRequest */
+/** @typedef {{ readonly cursor?: string, readonly domain: string }} DeltaRequest */
+/** @typedef {{ readonly aborted: boolean }} CancellationSignal */
+
+export const CAPABILITY_INVOKE_OPERATION = "POST /api/v2/system/capabilities/invoke";
+
+/** @typedef {{ readonly data: Readonly<Record<string, RepositoryJsonValue>>, readonly instance?: string, readonly resource: string, readonly type: string }} AppEventEnvelope */
+/** @typedef {{ readonly resourceId?: string }} AppEventSubscribeOptions */
+/** @typedef {() => void} AppEventSubscription */
+/** @typedef {{ deltas: <T>(request: DeltaRequest) => AsyncIterable<T>, invoke: <T>(request: HomeNodeRequest) => Promise<T>, subscribeAppEvents?: (resource: string, listener: (event: AppEventEnvelope) => void, options?: AppEventSubscribeOptions) => AppEventSubscription, readonly state: TransportState }} HomeNodeClient */
+
+/**
+ * @typedef {object} PeerTransportPort
+ * @property {(peer: string, payload: Uint8Array, signal?: CancellationSignal) => Promise<void>} send
+ * @property {(topic: string, payload: Uint8Array) => Promise<void>} publish
+ * @property {(topic: string, signal?: CancellationSignal) => AsyncIterable<Uint8Array>} subscribe
+ */
+
+export {};

package/src/offline-readiness.js

@@ -0,0 +1,65 @@
+// @ts-check
+
+/** @typedef {import("./repositories.js").StageCatalogEntry} StageCatalogEntry */
+/** @typedef {import("./repositories.js").StageManifest} StageManifest */
+/** @typedef {import("./repositories.js").StageRegistrySnapshot} StageRegistrySnapshot */
+/** @typedef {import("./repositories/repository-mutation.js").RepositoryJsonValue} RepositoryJsonValue */
+
+/** @typedef {{ readonly deviceDid: string, readonly homeNodeId: string }} OfflineIdentityScope */
+/** @typedef {"caching-assets" | "needs-first-sync" | "offline-ready" | "update-available" | "failed" | "removing"} OfflineStageState */
+/** @typedef {"asset-fetch-failed" | "asset-integrity-failed" | "projection-seed-failed" | "schema-incompatible" | "quota-exceeded" | "identity-mismatch" | "active-resource-corrupt"} OfflineReadinessFailureCode */
+/** @typedef {{ readonly appName: string, readonly activeManifestSha256?: string, readonly candidateManifestSha256?: string, readonly failureCode?: OfflineReadinessFailureCode, readonly state: OfflineStageState, readonly updatedAt: string }} OfflineStageReadiness */
+/** @typedef {{ readonly assetRevision: string, readonly appName: string, readonly entryUrl: string, readonly manifestSha256: string, readonly version: string }} StageAssetCandidate */
+/** @typedef {{ prepareCandidate(entry: StageCatalogEntry, catalogRevision: string): Promise<StageAssetCandidate>, validateCandidate(candidate: StageAssetCandidate, manifest: StageManifest): Promise<void>, discardCandidate(candidate: StageAssetCandidate): Promise<void>, deleteUnreferenced(keepAssetRevisions: readonly string[]): Promise<void> }} VerifiedStageAssetPort */
+/** @typedef {{ estimate(): Promise<{ readonly quota?: number, readonly usage?: number }> }} OfflineStorageEstimatePort */
+
+/** @typedef {{ readonly appName: string, readonly candidateManifestSha256: string, readonly sourceRevision: string, readonly state: "caching-assets" | "update-available", readonly updatedAt: string }} OfflineStagePreparationRecord */
+/** @typedef {{ readonly assetRevision: string, readonly entry: StageCatalogEntry, readonly projectionRevision?: string, readonly sourceRevision: string }} OfflineStageCommit */
+/** @typedef {{ readonly active: OfflineStageCommit, readonly rollback?: OfflineStageCommit }} OfflineStageCommitRecord */
+/** @typedef {{ readonly candidate: StageAssetCandidate, readonly entry: StageCatalogEntry, readonly sourceRevision: string }} OfflineStageBundleCommitInput */
+/** @typedef {{ readonly candidate: StageAssetCandidate, readonly entry: StageCatalogEntry, readonly projectionRevision: string, readonly requiredProjectionKeys: readonly string[], readonly sourceRevision: string }} OfflineStagePromotionInput */
+/** @typedef {{ readonly appName: string, readonly candidateManifestSha256?: string, readonly failureCode: OfflineReadinessFailureCode, readonly updatedAt: string }} OfflineStageFailureInput */
+/** @typedef {{ readonly cursor?: string, readonly updatedAt: string, readonly value: RepositoryJsonValue }} OfflineProjectionRecord */
+/** @typedef {{ readonly key: string, readonly record: OfflineProjectionRecord }} OfflineProjectionBatchRecord */
+/** @typedef {{ readonly cursor?: string, readonly records: readonly OfflineProjectionBatchRecord[], readonly updatedAt: string }} OfflineProjectionBatchCommit */
+
+/**
+ * Durable installed-stage entries, preparation journals, active/rollback
+ * references, and readiness state. Every operation requires an explicit
+ * identity scope.
+ *
+ * Catalog mutations are confined to bundle commit/promotion, rollback
+ * activation, and removal state-machine operations.
+ *
+ * @typedef {{
+ *   readCatalog(scope: OfflineIdentityScope): Promise<StageRegistrySnapshot | undefined>,
+ *   readCommit(scope: OfflineIdentityScope, appName: string): Promise<OfflineStageCommitRecord | undefined>,
+ *   listReadiness(scope: OfflineIdentityScope): Promise<readonly OfflineStageReadiness[]>,
+ *   recordPreparation(scope: OfflineIdentityScope, record: OfflineStagePreparationRecord): Promise<void>,
+ *   commitNewBundle(scope: OfflineIdentityScope, input: OfflineStageBundleCommitInput): Promise<void>,
+ *   confirmBootHealth(scope: OfflineIdentityScope, appName: string, manifestSha256: string): Promise<OfflineStageCommit | undefined>,
+ *   activateRollback(scope: OfflineIdentityScope, appName: string, activeManifestSha256: string, rollbackManifestSha256: string): Promise<OfflineStageCommit | undefined>,
+ *   promoteOfflineReady(scope: OfflineIdentityScope, input: OfflineStagePromotionInput): Promise<void>,
+ *   markFailed(scope: OfflineIdentityScope, input: OfflineStageFailureInput): Promise<void>,
+ *   removeStage(scope: OfflineIdentityScope, appName: string, sourceRevision: string): Promise<void>,
+ *   finalizeRemoval(scope: OfflineIdentityScope, appName: string): Promise<void>,
+ *   invalidateScope(scope: OfflineIdentityScope): Promise<void>,
+ *   clearScope(scope: OfflineIdentityScope): Promise<void>
+ * }} OfflineStageRepository
+ */
+
+/**
+ * Identity-scoped versioned projection records and revision heads. Every
+ * operation requires an explicit identity scope.
+ *
+ * @typedef {{
+ *   read(scope: OfflineIdentityScope, namespace: string, projectionRevision: string, key: string): Promise<OfflineProjectionRecord | undefined>,
+ *   write(scope: OfflineIdentityScope, namespace: string, projectionRevision: string, key: string, record: OfflineProjectionRecord): Promise<void>,
+ *   writeBatch(scope: OfflineIdentityScope, namespace: string, projectionRevision: string, commit: OfflineProjectionBatchCommit): Promise<void>,
+ *   hasKeys(scope: OfflineIdentityScope, namespace: string, projectionRevision: string, keys: readonly string[]): Promise<boolean>,
+ *   deleteRevision(scope: OfflineIdentityScope, namespace: string, projectionRevision: string): Promise<void>,
+ *   clearScope(scope: OfflineIdentityScope): Promise<void>
+ * }} OfflineProjectionRepository
+ */
+
+export {};

package/src/onboarding-access-code.js

@@ -0,0 +1,21 @@
+// @ts-check
+export {};
+/**
+ * The access code a person types (or scans via the step-9 QR) to claim this node — the
+ * shared secret `OwnerClaimService.prepareClaim(accessCode)` sends as `access_code` on
+ * `POST /api/v2/node/onboarding-prepare`.
+ *
+ * Deliberately `localStorage`-shaped, exactly like `OnboardingCheckpointStoragePort`: step 7
+ * destroys the tab the owner was working in, and a code re-typed by hand before that
+ * navigation must still be there afterwards rather than forcing a second entry. Not
+ * `sessionStorage` for the same reason — the owner may land in a brand-new tab.
+ *
+ * Every method degrades silently. Reading or writing `localStorage` — and even *touching*
+ * the property — can throw in locked-down embedders, and losing this code must never abort
+ * onboarding; the person simply gets asked to type it again.
+ * @typedef {object} OnboardingAccessCodeStore
+ * @property {() => string | null} read Returns the stored code, or `null` for "never saved" AND for "the read itself failed"
+ * alike — the caller must not (and cannot) tell those two cases apart.
+ * @property {(code: string) => void} save Stores `code`. A failed write is swallowed; the flow continues without persistence.
+ * @property {() => void} clear Empties the slot. Never throws.
+ */

package/src/onboarding-checkpoint.js

@@ -0,0 +1,26 @@
+// @ts-check
+export {};
+/**
+ * The one string slot the onboarding flow needs to survive a full navigation.
+ *
+ * Step 7 deliberately destroys the tab the owner was working in (the node's AP closes and the
+ * browser must be pointed at the home-LAN address), and the kernel is an elected leader tab —
+ * not a SharedWorker — so its in-memory service state dies with that tab. Without a slot that
+ * outlives the navigation the flow restarts at step 3.
+ *
+ * Deliberately `localStorage`-shaped rather than OPFS-backed: OPFS is gated pre-claim
+ * (`requiresDurableStorage`), which is exactly the window this must work in. Deliberately
+ * NOT `sessionStorage` (`SessionFlagPort`): the owner may be handed a brand-new tab.
+ *
+ * Deliberately synchronous and string-typed: `OnboardingCheckpointStore` owns the schema, the
+ * allow-list and the staleness rule, so this port cannot be handed a structured object that
+ * happens to carry a Wi-Fi password.
+ *
+ * Every method degrades silently, exactly like `SessionFlagPort`: reading or writing
+ * `localStorage` — and even *touching* the property — can throw in locked-down embedders, and
+ * losing a resume point must never abort onboarding.
+ * @typedef {object} OnboardingCheckpointStoragePort
+ * @property {() => void} clear
+ * @property {() => string | undefined} read
+ * @property {(value: string) => void} write
+ */

package/src/onboarding-presence.js

@@ -0,0 +1,15 @@
+// @ts-check
+/**
+ * @returns {OnboardingPresencePort}
+ */
+export function createNullOnboardingPresence() {
+  return { announce: () => Promise.resolve() };
+}
+/**
+ * Phases the node's onboarding FSM understands. Fire-and-forget hints (spec §3.2).
+ * @typedef {"portal" | "wifi_setup" | "register" | "install"} OnboardingPresencePhase
+ */
+/**
+ * @typedef {object} OnboardingPresencePort
+ * @property {(phase: OnboardingPresencePhase) => Promise<void>} announce
+ */

package/src/owner-claim-session.js

@@ -0,0 +1,55 @@
+// @ts-check
+/** For compositions with no browser session client (tests, headless kernels): every claim is
+ * reported as unpaired, which is the safe direction — the shell runs its pairing flow.
+ * @returns {OwnerClaimSessionPort}
+ */
+export function createNullOwnerClaimSession() {
+  return { adopt: async () => false };
+}
+/**
+ * The seam through which a successful first-owner claim becomes a REAL browser session
+ * (design §7.1).
+ *
+ * `POST /api/auth/complete-onboarding` answers with `token` / `refresh_token` /
+ * `token_expires_at` (`core/adapters-network/src/transport/auth/handlers.rs`), but
+ * `client/domain` cannot do anything with them: turning an owner JWT into a client-device
+ * session means talking to `/api/v2/client-devices/*` with browser-held key material, which is
+ * `client/adapters-web`'s job. Hence a port.
+ *
+ * `adopt` returns a BOOLEAN rather than throwing or returning void, and that is the whole
+ * design: a `false` means "the claim succeeded but this browser is not paired", and the flow
+ * then falls back to the shell's ordinary pairing screen. Nothing here may assert a trust
+ * relationship the browser does not hold — whether the node auto-approves the owner's first
+ * device is the node's decision, not this client's assumption.
+ *
+ * SECURITY: only the access token and its expiry cross this boundary. The refresh token is
+ * deliberately NOT part of `OwnerClaimSessionTokens` — no client code today can spend it, and a
+ * long-lived credential held with no consumer is pure downside.
+ * @typedef {object} OwnerClaimSessionTokens
+ * @property {string} accessToken
+ * @property {string} expiresAt ISO instant. An already-expired value must be refused rather than adopted.
+ */
+/**
+ * Wire-shaped, snake_case: `genesis_device` crosses to the node verbatim as a field of
+ * `POST /api/auth/complete-onboarding`'s payload (`core/domain/src/services/
+ * onboarding_completion_service.rs`'s `GenesisDeviceDescriptor`), so this typedef mirrors the
+ * Rust struct field-for-field rather than the camelCase this package otherwise prefers — the
+ * same precedent as `OwnerClaimSessionTokens` staying JS-shaped for values that stay client-side
+ * while wire payloads built for direct forwarding stay wire-shaped.
+ * @typedef {object} OwnerClaimGenesisDevice
+ * @property {string} public_key_multibase
+ * @property {string} device_name
+ * @property {string} device_type
+ * @property {string} signature
+ */
+/**
+ * @typedef {object} OwnerClaimSessionPort
+ * @property {(tokens: OwnerClaimSessionTokens) => Promise<boolean>} adopt
+ * @property {(challenge: string) => Promise<OwnerClaimGenesisDevice | undefined>} [describeGenesisDevice] OPTIONAL: builds the signed
+ * `genesis_device` proof-of-possession descriptor for the given onboarding-challenge string, so
+ * the node can mint the genesis DID device with this browser's real pairing identity instead of
+ * a synthetic fallback. `undefined` — from an implementation that omits the member entirely, or
+ * from any failure to build the descriptor — means the claim proceeds without one; `adopt` must
+ * never depend on this having been called. `createNullOwnerClaimSession()` deliberately leaves
+ * this unimplemented (adopt-only) since it is optional.
+ */

package/src/owner-claim.js

@@ -0,0 +1,22 @@
+// @ts-check
+export {};
+/**
+ * Ephemeral secp256k1 identity used ONLY for the legacy BIP39-shaped first-owner
+ * onboarding contract (`POST /api/v2/node/onboarding-prepare` /
+ * `POST /api/auth/{onboarding-challenge,complete-onboarding}` —
+ * verified server-side by `core/auth/src/crypto.rs`'s `CryptoService`).
+ *
+ * Deliberately separate from `IdentityPort` (Ed25519, used for client-device
+ * pairing/session, `./identity.ts`): the host's owner-onboarding endpoints verify
+ * secp256k1 ECDSA signatures over a hex-encoded uncompressed public key — a different
+ * scheme from the device identity this browser establishes afterwards to pair as a
+ * client device. One browser session generates and holds exactly one such key per
+ * onboarding attempt (mirrors the legacy `system/ui` flow's "ONE device keypair for
+ * the whole onboarding attempt" invariant — the node's physical-confirmation gate binds
+ * approval to the exact public key sent to `onboarding-prepare`).
+ * @typedef {object} OwnerClaimCryptoPort
+ * @property {() => Promise<string>} publicKey
+ * @property {(challenge: string) => Promise<string>} sign
+ * @property {() => string} deviceInfo
+ * @property {() => void} reset
+ */

package/src/repositories/conversation-repository.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+/** @template {import("./durable-event.js").DurableEvent} [TEvent=import("./durable-event.js").DurableEvent] @typedef {import("./durable-event.js").RepositoryWriteResult<TEvent>} RepositoryWriteResult */
+
+export const CONVERSATION_MESSAGE_STATES = /** @type {const} */ (["pending", "confirmed", "failed"]);
+/** @typedef {typeof CONVERSATION_MESSAGE_STATES[number]} ConversationMessageState */
+/** @typedef {{ readonly id: string, readonly lastMessagePreview?: string, readonly lastMessageAt?: string, readonly participantIds: readonly string[], readonly title: string, readonly unreadCount: number, readonly updatedAt: string }} Conversation */
+/** @typedef {{ readonly body: string, readonly clientMessageId?: string, readonly conversationId: string, readonly createdAt: string, readonly failureReason?: string, readonly id: string, readonly senderId: string, readonly serverMessageId?: string, readonly state: ConversationMessageState }} ConversationMessage */
+/** @typedef {{ readonly body: string, readonly createdAt: string, readonly id: string, readonly readAt?: string, readonly referenceId?: string, readonly title: string, readonly type: string }} Notification */
+/** @typedef {{ readonly conversation: Conversation, readonly kind: "conversation.upsert" } | { readonly kind: "message.append", readonly message: ConversationMessage } | { readonly acknowledgedAt: string, readonly kind: "message.ack", readonly messageId: string, readonly serverMessageId?: string } | { readonly failedAt: string, readonly kind: "message.fail", readonly messageId: string, readonly reason: string } | { readonly kind: "notification.upsert", readonly notification: Notification } | { readonly kind: "notification.read", readonly notificationId: string, readonly readAt: string }} ConversationLogDelta */
+/** @typedef {{ readonly before?: string, readonly limit?: number }} ConversationListParams */
+/** @typedef {{ readonly before?: string, readonly limit?: number }} MessageListParams */
+/** @typedef {{ readonly limit?: number, readonly unreadOnly?: boolean }} NotificationListParams */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly action: "created" | "updated", readonly entityId: string, readonly entityType: "conversation" | "message" }, readonly type: "domain.entity-changed" }} ConversationRepositoryEvent */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly action: "created" | "updated", readonly entityId: string, readonly entityType: "notification" }, readonly type: "domain.entity-changed" }} NotificationRepositoryEvent */
+/** @typedef {ConversationRepositoryEvent | NotificationRepositoryEvent} RepositoryEvent */
+/** @typedef {{ acknowledgeMessage(input: { readonly acknowledgedAt: string, readonly messageId: string, readonly serverMessageId?: string }): Promise<RepositoryWriteResult<ConversationRepositoryEvent>>, appendPendingMessage(input: { readonly message: ConversationMessage }): { commit(): Promise<RepositoryWriteResult<ConversationRepositoryEvent>> }, applyDelta(delta: ConversationLogDelta): { commit(): Promise<RepositoryWriteResult<RepositoryEvent>> }, failMessage(input: { readonly failedAt: string, readonly messageId: string, readonly reason: string }): Promise<RepositoryWriteResult<ConversationRepositoryEvent>>, listConversations(params?: ConversationListParams): Promise<readonly Conversation[]>, listMessages(conversationId: string, params?: MessageListParams): Promise<readonly ConversationMessage[]> }} ConversationRepository */
+/** @typedef {{ applyDelta(delta: ConversationLogDelta): { commit(): Promise<RepositoryWriteResult<RepositoryEvent>> }, listNotifications(params?: NotificationListParams): Promise<readonly Notification[]>, markRead(input: { readonly notificationId: string, readonly readAt: string }): { commit(): Promise<RepositoryWriteResult<NotificationRepositoryEvent>> } }} NotificationRepository */
+
+export {};

package/src/repositories/durable-event.js

@@ -0,0 +1,8 @@
+// @ts-check
+
+/** @typedef {{ readonly occurredAt: string, readonly payload: unknown, readonly type: string }} DurableEvent */
+/** @template {DurableEvent} [TEvent=DurableEvent] @typedef {{ readonly deliveredAt: string | undefined, readonly deliveryAttempts: number, readonly event: TEvent, readonly sequence: number }} DurableRepositoryEvent */
+/** @template {DurableEvent} [TEvent=DurableEvent] @typedef {{ listUndelivered(): Promise<readonly DurableRepositoryEvent<TEvent>[]>, markDelivered(sequence: number, deliveredAt: string): Promise<void>, markDeliveryAttempt(sequence: number): Promise<void> }} DurableRepositoryEventStore */
+/** @template {DurableEvent} [TEvent=DurableEvent] @typedef {{ readonly eventSequences: readonly number[], readonly events: readonly TEvent[] }} RepositoryWriteResult */
+
+export {};