@econ-v1/ports 6.7.0 → 6.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@econ-v1/ports",
-  "version": "6.7.0",
+  "version": "6.10.0",
   "description": "Platform-neutral ports for Node client applications",
   "license": "MIT OR Apache-2.0",
   "author": "Node contributors",
@@ -19,28 +19,32 @@
     "typescript"
   ],
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./src/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist && tsc -b --pretty false",
+    "build": "rm -rf dist && tsc -p tsconfig.publish.json --pretty false",
+    "check": "tsc -p jsconfig.json --pretty false && node ../scripts/check-negative-type-contracts.mjs --config jsconfig.tests.json",
     "lint": "eslint src",
-    "prepack": "npm run build",
+    "prepack": "npm run build && node ../scripts/check-public-package.mjs .",
     "test": "vitest run --passWithNoTests",
-    "type-check": "tsc -b --pretty false"
+    "check:consumer": "node ../scripts/check-negative-type-contracts.mjs --config jsconfig.consumer.json",
+    "type-check": "yarn run check && yarn check:consumer"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+      "import": "./src/index.js",
+      "default": "./src/index.js"
     }
   },
   "files": [
+    "src/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
-    "dist/**/*.js",
-    "dist/**/*.js.map",
-    "!dist/**/*.test.*"
+    "!src/**/*.test.js"
   ],
   "sideEffects": false,
   "engines": {

package/src/app-data.js

@@ -0,0 +1,42 @@
+// @ts-check
+/** @import { RepositoryJsonValue } from './repositories/repository-mutation.js' */
+export {};
+/**
+ * @typedef {object} AppDataCacheRecord
+ * @property {string} cachedAt
+ * @property {string} [cursor]
+ * @property {"fresh" | "stale" | "offline" | "unavailable"} freshness
+ * @property {string} key
+ * @property {string} namespace
+ * @property {string} revision
+ * @property {"online" | "offline"} transport
+ * @property {RepositoryJsonValue} value
+ */
+/**
+ * @typedef {object} AppDataCacheWrite
+ * @property {string} key
+ * @property {string} revision
+ * @property {RepositoryJsonValue} value
+ */
+/**
+ * @typedef {object} AppDataCacheCommit
+ * @property {string} cursor
+ * @property {string} cursorKey
+ * @property {string} revision
+ * @property {readonly AppDataCacheWrite[]} rows
+ */
+/** Typed post-commit result from the cache repository. It is intentionally
+ * repository-local; the kernel maps it to the public app-data event payload.
+ * @typedef {object} AppDataCacheCommitEvent
+ * @property {readonly string[]} changedKeys
+ * @property {string} cursor
+ * @property {string} cursorKey
+ * @property {string} namespace
+ * @property {string} revision
+ */
+/**
+ * @typedef {object} AppDataCacheRepository
+ * @property {(namespace: string, key: string) => Promise<AppDataCacheRecord | undefined>} read
+ * @property {(namespace: string, key: string, value: RepositoryJsonValue, revision: string, cursor?: string) => Promise<void>} write
+ * @property {(namespace: string, commit: AppDataCacheCommit) => Promise<AppDataCacheCommitEvent | undefined>} writeBatch
+ */

package/src/client-ui-preference.js

@@ -0,0 +1,23 @@
+// @ts-check
+export {};
+/**
+ * Which UI this browser should land on at the node's root.
+ *
+ * The node backend serves both the Client Node PWA (at `/`) and the legacy `system/ui` SPA
+ * (at `/v1/`). `"pwa"` is the default and is represented by the ABSENCE of any stored value,
+ * so a browser that has never chosen carries no state at all.
+ * @typedef {"pwa" | "v1"} ClientUiChoice
+ */
+/**
+ * Read and change the per-browser UI choice.
+ *
+ * A port rather than direct storage access because `client/ui` may not touch browser globals
+ * (boundary rules B2/B3/N1) — same seam and same reason as `ThemeEnvironmentPort`. `select`
+ * both persists the choice and navigates, because the two are one user-visible action and
+ * splitting them would let a caller leave the preference and the current document
+ * disagreeing.
+ * @typedef {object} ClientUiPreferencePort
+ * @property {() => ClientUiChoice} read
+ * @property {(choice: ClientUiChoice) => void} select
+ * @property {(choice: ClientUiChoice) => void} visit
+ */

package/src/clipboard.js

@@ -0,0 +1,41 @@
+// @ts-check
+export {};
+/**
+ * Boundary port for reading the OS text clipboard, backing the invitation screen's "Paste"
+ * button (`shell/onboarding/screens/identify-invitation.ts`'s `#pasteInto`).
+ *
+ * `client/ui` may never call `navigator.clipboard` directly (boundary rules B2/B3,
+ * `client/scripts/check-boundaries.mjs`) — this is the narrow surface
+ * `client/adapters-web`'s `createBrowserClipboard()` implements against the real global, and
+ * the composition root (`system/pwa/src/main.ts`) registers it (via `client/ui`'s
+ * `configureClipboard`) before the shell's first paint, mirroring `MediaPreferencesPort`'s
+ * registration exactly.
+ *
+ * Deliberately NOT mediated through `@econ-v1/rpc`/the kernel, for the same reason
+ * `MediaPreferencesPort` isn't: the clipboard is browser I/O, not kernel-owned domain
+ * state — there is nothing for the kernel to know about a value that never leaves this tab
+ * and is never persisted, and routing a paste through a `query`/`liveQuery` round trip
+ * would only add latency to a synchronous user gesture (the Paste button click) for no
+ * benefit. Also deliberately a separate port from `MediaPreferencesPort` rather than folded
+ * into it: that port models synchronous, side-effect-free one-shot reads taken during
+ * `connectedCallback`/`mount`; this one models a single asynchronous, fallible operation
+ * triggered by an explicit user action (a button click), with a completely different shape.
+ *
+ * `readText()` resolves to `undefined`, never a rejected promise, on ANY failure —
+ * permission denied, an environment without Clipboard API support, or the user dismissing
+ * the browser's own permission prompt all collapse into the same "nothing to paste"
+ * outcome. This is a deliberate sentinel, not an exception: the call site (`#pasteInto`)
+ * must fail silently by design (today's behavior, preserved exactly here) — a
+ * `Promise<string>` that can reject would force every caller to wrap the call in
+ * try/catch just to reproduce that silence, and a forgotten catch would surface a raw
+ * clipboard permission error as an unhandled rejection instead. The adapter is the only
+ * place that ever sees the real rejection reason; everything past it just sees "got text"
+ * or "didn't."
+ *
+ * The clipboard text itself must never be retained, cached, or logged by this port, its
+ * adapter, or any caller — it is a secret in the invitation-code call site (see
+ * `identify-invitation.ts`'s own security note) and must flow straight from the browser API
+ * into the caller's live `<input>.value`, nowhere else.
+ * @typedef {object} ClipboardPort
+ * @property {() => Promise<string | undefined>} readText
+ */

package/src/clock.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+/** @typedef {{ cancel(): void }} ClockWake */
+
+/**
+ * @typedef {object} ClockPort
+ * @property {() => string} now
+ * @property {(dueAt: string, wake: () => void) => ClockWake} wakeAt
+ */
+
+/** @typedef {{ wait(milliseconds: number): Promise<void> }} DelayPort */
+
+export {};

package/src/credential-handoff.js

@@ -0,0 +1,68 @@
+// @ts-check
+export {};
+/**
+ * @typedef {| "cancelled"
+ *   | "peer-closed"
+ *   | "timed-out"} CredentialHandoffCancellationReason
+ */
+/**
+ * @typedef {| {
+ *       readonly version: 1;
+ *       readonly type: "classic-pending";
+ *       readonly transactionId: string;
+ *       readonly deviceId: string;
+ *       readonly operationHash: string;
+ *     }
+ *   | {
+ *       readonly version: 1;
+ *       readonly type: "classic-ready";
+ *       readonly transactionId: string;
+ *     }
+ *   | {
+ *       readonly version: 1;
+ *       readonly type: "pwa-owner-key";
+ *       readonly transactionId: string;
+ *       readonly ownerPublicKey: string;
+ *     }
+ *   | {
+ *       readonly version: 1;
+ *       readonly type: "pwa-migration-challenge";
+ *       readonly transactionId: string;
+ *       readonly challenge: string;
+ *     }
+ *   | {
+ *       readonly version: 1;
+ *       readonly type: "pwa-owner-signature";
+ *       readonly transactionId: string;
+ *       readonly signature: string;
+ *     }
+ *   | {
+ *       readonly version: 1;
+ *       readonly type: "handoff-cancelled";
+ *       readonly transactionId: string;
+ *       readonly reason: CredentialHandoffCancellationReason;
+ *     }} CredentialHandoffMessage
+ */
+/**
+ * @typedef {| { readonly status: "opened"; readonly connection: CredentialHandoffConnection }
+ *   | { readonly status: "popup-blocked" }} CredentialHandoffOpenResult
+ */
+/**
+ * @typedef {object} CredentialHandoffConnection
+ * @property {string} transactionId
+ * @property {() => void} close
+ * @property {() => void} focusPeer
+ * @property {(message: CredentialHandoffMessage) => void} send
+ * @property {(listener: (message: CredentialHandoffMessage) => void) => () => void} subscribe
+ */
+/**
+ * @typedef {object} CredentialHandoffPort
+ * @property {() => CredentialHandoffOpenResult} openClassicPairing
+ * @property {(transactionId: string) => CredentialHandoffConnection | undefined} connectToClassicOpener
+ */
+/**
+ * Owns the bounded pre-adapter browser message capture for one handoff transaction.
+ * @typedef {object} CredentialHandoffMessageCapturePort
+ * @property {() => void} close
+ * @property {() => void} replay
+ */

package/src/crypto.js

@@ -0,0 +1,9 @@
+// @ts-check
+
+/**
+ * @typedef {object} CryptoPort
+ * @property {(input: Uint8Array) => Promise<string>} digestSha256
+ * @property {(input: Uint8Array, signature: Uint8Array, publicKey: Uint8Array) => Promise<boolean>} verifyEd25519
+ */
+
+export {};

package/src/id.js

@@ -0,0 +1,5 @@
+// @ts-check
+
+/** @typedef {{ generate(): string }} IdPort */
+
+export {};

package/src/identity.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+/** @typedef {import("./offline-readiness.js").OfflineIdentityScope} OfflineIdentityScope */
+
+/** @typedef {{ readonly id: string }} DeviceKeyHandle */
+/** @typedef {"non-extractable" | "wrapped"} KeyCustodyMode */
+/** @typedef {{ readonly custodyMode: KeyCustodyMode, readonly did: string, readonly nodeId: string, readonly publicKeyMultibase: string }} DevicePublicIdentity */
+/** @typedef {{ readonly credential: string, readonly expiresAt: string, readonly issuedAt: string, readonly revocationId: string, readonly scopes: readonly string[] }} DeviceDelegation */
+/** @typedef {{ readonly directAddresses: readonly string[], readonly homeNodeId?: string, readonly lastConnectedAt?: string, readonly relayUrl?: string, readonly wanOrigin?: string }} DeviceConnectionMetadata */
+/** @typedef {DevicePublicIdentity & { readonly keyHandle: DeviceKeyHandle }} DeviceIdentity */
+/** @typedef {{ readonly custodyMode?: KeyCustodyMode, readonly hasDelegation: boolean, readonly keyId?: string }} IdentityDiagnostics */
+/** @typedef {"active" | "revoked"} IdentityLifecycle */
+
+/**
+ * @typedef {object} IdentityPort
+ * @property {() => Promise<DeviceIdentity>} generate
+ * @property {(keyHandle: DeviceKeyHandle, payload: Uint8Array) => Promise<Uint8Array>} sign
+ * @property {() => Promise<DevicePublicIdentity | undefined>} publicIdentity
+ * @property {() => Promise<OfflineIdentityScope | undefined>} readOfflineScope
+ * @property {() => Promise<DeviceDelegation | undefined>} loadDelegation
+ * @property {(delegation: DeviceDelegation) => Promise<void>} storeDelegation
+ * @property {() => Promise<DeviceConnectionMetadata | undefined>} loadConnectionMetadata
+ * @property {(metadata: DeviceConnectionMetadata) => Promise<void>} storeConnectionMetadata
+ * @property {() => Promise<void>} clearDelegation
+ * @property {() => Promise<void>} clear
+ * @property {() => Promise<DeviceIdentity>} recoverAfterRevocation
+ * @property {() => Promise<IdentityDiagnostics>} diagnostics
+ * @property {() => Promise<IdentityLifecycle | undefined>} [loadLifecycle]
+ * @property {() => Promise<string | undefined>} [loadPairingAttemptName]
+ * @property {(name: string) => Promise<void>} [storePairingAttemptName]
+ */
+
+export {};

package/src/index.js

@@ -0,0 +1,250 @@
+// @ts-check
+
+/** @typedef {import("./clock.js").ClockPort} ClockPort */
+/** @typedef {import("./clock.js").ClockWake} ClockWake */
+/** @typedef {import("./clock.js").DelayPort} DelayPort */
+/** @typedef {import("./app-data.js").AppDataCacheCommit} AppDataCacheCommit */
+/** @typedef {import("./app-data.js").AppDataCacheCommitEvent} AppDataCacheCommitEvent */
+/** @typedef {import("./app-data.js").AppDataCacheRecord} AppDataCacheRecord */
+/** @typedef {import("./app-data.js").AppDataCacheRepository} AppDataCacheRepository */
+/** @typedef {import("./app-data.js").AppDataCacheWrite} AppDataCacheWrite */
+/** @typedef {import("./client-ui-preference.js").ClientUiChoice} ClientUiChoice */
+/** @typedef {import("./client-ui-preference.js").ClientUiPreferencePort} ClientUiPreferencePort */
+/** @typedef {import("./clipboard.js").ClipboardPort} ClipboardPort */
+/** @typedef {import("./credential-handoff.js").CredentialHandoffCancellationReason} CredentialHandoffCancellationReason */
+/** @typedef {import("./credential-handoff.js").CredentialHandoffConnection} CredentialHandoffConnection */
+/** @typedef {import("./credential-handoff.js").CredentialHandoffMessage} CredentialHandoffMessage */
+/** @typedef {import("./credential-handoff.js").CredentialHandoffMessageCapturePort} CredentialHandoffMessageCapturePort */
+/** @typedef {import("./credential-handoff.js").CredentialHandoffOpenResult} CredentialHandoffOpenResult */
+/** @typedef {import("./credential-handoff.js").CredentialHandoffPort} CredentialHandoffPort */
+/** @typedef {import("./crypto.js").CryptoPort} CryptoPort */
+/** @typedef {import("./id.js").IdPort} IdPort */
+/** @typedef {import("./identity.js").DeviceConnectionMetadata} DeviceConnectionMetadata */
+/** @typedef {import("./identity.js").DeviceDelegation} DeviceDelegation */
+/** @typedef {import("./identity.js").DeviceIdentity} DeviceIdentity */
+/** @typedef {import("./identity.js").DeviceKeyHandle} DeviceKeyHandle */
+/** @typedef {import("./identity.js").DevicePublicIdentity} DevicePublicIdentity */
+/** @typedef {import("./identity.js").IdentityDiagnostics} IdentityDiagnostics */
+/** @typedef {import("./identity.js").IdentityLifecycle} IdentityLifecycle */
+/** @typedef {import("./identity.js").IdentityPort} IdentityPort */
+/** @typedef {import("./identity.js").KeyCustodyMode} KeyCustodyMode */
+/** @typedef {import("./install-environment.js").InstallEnvironmentPort} InstallEnvironmentPort */
+/** @typedef {import("./install-environment.js").InstallInstructionMode} InstallInstructionMode */
+/** @typedef {import("./network.js").DeltaRequest} DeltaRequest */
+/** @typedef {import("./network.js").AppEventEnvelope} AppEventEnvelope */
+/** @typedef {import("./network.js").AppEventSubscribeOptions} AppEventSubscribeOptions */
+/** @typedef {import("./network.js").AppEventSubscription} AppEventSubscription */
+/** @typedef {import("./network.js").CancellationSignal} CancellationSignal */
+/** @typedef {import("./network.js").DirectHomeNodeCandidate} DirectHomeNodeCandidate */
+/** @typedef {import("./network.js").DirectTransportPath} DirectTransportPath */
+/** @typedef {import("./network.js").HomeNodeClient} HomeNodeClient */
+/** @typedef {import("./network.js").HttpHomeNodeCandidate} HttpHomeNodeCandidate */
+/** @typedef {import("./network.js").HttpTransportPath} HttpTransportPath */
+/** @typedef {import("./network.js").HomeNodeRequest} HomeNodeRequest */
+/** @typedef {import("./network.js").PeerTransportPort} PeerTransportPort */
+/** @typedef {import("./network.js").TransportOfflineReason} TransportOfflineReason */
+/** @typedef {import("./network.js").TransportPath} TransportPath */
+/** @typedef {import("./network.js").TransportState} TransportState */
+/** @typedef {import("./network.js").WebTransportCertificateHashes} WebTransportCertificateHashes */
+/** @typedef {import("./network.js").WebTransportHomeNodeCandidate} WebTransportHomeNodeCandidate */
+/** @typedef {import("./network/home-node-candidate.js").HomeNodeCandidate} HomeNodeCandidate */
+/** @typedef {import("./network/home-node-candidate.js").HomeNodeDialer} HomeNodeDialer */
+/** @typedef {import("./network/home-node-candidate-store.js").HomeNodeCandidateStorePort} HomeNodeCandidateStorePort */
+/** @typedef {import("./network/home-node-candidate-store.js").StoredHomeNodeCandidate} StoredHomeNodeCandidate */
+/** @typedef {import("./network/l402-payment.js").L402PaymentChallenge} L402PaymentChallenge */
+/** @typedef {import("./network/l402-payment.js").L402PaymentHandler} L402PaymentHandler */
+/** @typedef {import("./network/l402-payment.js").L402PaymentResult} L402PaymentResult */
+/** @typedef {import("./network/node-discovery.js").NodeAddressDiscoverer} NodeAddressDiscoverer */
+/** @typedef {import("./network/node-discovery.js").NodeDiscoveryCandidate} NodeDiscoveryCandidate */
+/** @typedef {import("./network/node-discovery.js").NodeDiscoveryResult} NodeDiscoveryResult */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcAnswer} WebRtcAnswer */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcClose} WebRtcClose */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcIceCandidate} WebRtcIceCandidate */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcOffer} WebRtcOffer */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcRestart} WebRtcRestart */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcSignalMessage} WebRtcSignalMessage */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcSignalSetup} WebRtcSignalSetup */
+/** @typedef {import("./network/webrtc-signaling.js").WebRtcSignalingPort} WebRtcSignalingPort */
+/** @typedef {import("./repositories.js").PreparedStageAsset} PreparedStageAsset */
+/** @typedef {import("./repositories.js").AppDataManifest} AppDataManifest */
+/** @typedef {import("./repositories.js").AppDataOfflinePolicy} AppDataOfflinePolicy */
+/** @typedef {import("./repositories.js").AppDataQueryDeclaration} AppDataQueryDeclaration */
+/** @typedef {import("./repositories.js").AppDataQueryKind} AppDataQueryKind */
+/** @typedef {import("./repositories.js").AppDataStreamDeclaration} AppDataStreamDeclaration */
+/** @typedef {import("./repositories.js").AppDataStreamKind} AppDataStreamKind */
+/** @typedef {import("./repositories.js").AppDataSyncKind} AppDataSyncKind */
+/** @typedef {import("./repositories.js").AppDataSyncPolicy} AppDataSyncPolicy */
+/** @typedef {import("./repositories.js").StageAssetPort} StageAssetPort */
+/** @typedef {import("./repositories.js").StageCatalogEntry} StageCatalogEntry */
+/** @typedef {import("./repositories.js").StageManifest} StageManifest */
+/** @typedef {import("./repositories.js").StageUiKind} StageUiKind */
+/** @typedef {import("./repositories.js").StageUiMetadata} StageUiMetadata */
+/** @typedef {import("./repositories.js").StageUiNav} StageUiNav */
+/** @typedef {import("./repositories.js").StageUiRequirements} StageUiRequirements */
+/** @typedef {import("./repositories.js").StageRegistryPort} StageRegistryPort */
+/** @typedef {import("./repositories.js").StageRegistrySnapshot} StageRegistrySnapshot */
+/** @typedef {import("./repositories/conversation-repository.js").Conversation} Conversation */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationListParams} ConversationListParams */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationLogDelta} ConversationLogDelta */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationMessage} ConversationMessage */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationMessageState} ConversationMessageState */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationRepository} ConversationRepository */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationRepositoryEvent} ConversationRepositoryEvent */
+/** @typedef {import("./repositories/conversation-repository.js").MessageListParams} MessageListParams */
+/** @typedef {import("./repositories/conversation-repository.js").Notification} Notification */
+/** @typedef {import("./repositories/conversation-repository.js").NotificationListParams} NotificationListParams */
+/** @typedef {import("./repositories/conversation-repository.js").NotificationRepository} NotificationRepository */
+/** @typedef {import("./repositories/conversation-repository.js").NotificationRepositoryEvent} NotificationRepositoryEvent */
+/** @typedef {import("./repositories/conversation-repository.js").RepositoryEvent} RepositoryEvent */
+/** @typedef {import("./repositories/durable-event.js").DurableEvent} DurableEvent */
+/** @template {DurableEvent} [TEvent=DurableEvent] @typedef {import("./repositories/durable-event.js").DurableRepositoryEvent<TEvent>} DurableRepositoryEvent */
+/** @template {DurableEvent} [TEvent=DurableEvent] @typedef {import("./repositories/durable-event.js").DurableRepositoryEventStore<TEvent>} DurableRepositoryEventStore */
+/** @template {DurableEvent} [TEvent=DurableEvent] @typedef {import("./repositories/durable-event.js").RepositoryWriteResult<TEvent>} RepositoryWriteResult */
+/** @typedef {import("./repositories/outbox.js").OutboxDeletedEvent} OutboxDeletedEvent */
+/** @typedef {import("./repositories/outbox.js").OutboxRecord} OutboxRecord */
+/** @typedef {import("./repositories/outbox.js").OutboxRecordState} OutboxRecordState */
+/** @typedef {import("./repositories/outbox.js").OutboxReplayClaim} OutboxReplayClaim */
+/** @typedef {import("./repositories/outbox.js").OutboxReplayStatus} OutboxReplayStatus */
+/** @typedef {import("./repositories/outbox.js").OutboxRepository} OutboxRepository */
+/** @typedef {import("./repositories/outbox.js").OutboxRepositoryEvent} OutboxRepositoryEvent */
+/** @typedef {import("./repositories/outbox.js").OutboxRepositoryFilter} OutboxRepositoryFilter */
+/** @typedef {import("./repositories/outbox.js").OutboxSettleInput} OutboxSettleInput */
+/** @typedef {import("./repositories/outbox.js").OutboxStateChangedEvent} OutboxStateChangedEvent */
+/** @typedef {import("./repositories/repository-mutation.js").RepositoryJsonPrimitive} RepositoryJsonPrimitive */
+/** @typedef {import("./repositories/repository-mutation.js").RepositoryJsonValue} RepositoryJsonValue */
+/** @typedef {import("./repositories/settings.js").SettingInput} SettingInput */
+/** @typedef {import("./repositories/settings.js").SettingRecord} SettingRecord */
+/** @typedef {import("./repositories/settings.js").SettingsRepository} SettingsRepository */
+/** @typedef {import("./repositories/settings.js").SettingsRepositoryEvent} SettingsRepositoryEvent */
+/** @typedef {import("./repositories/sync-ledger.js").SyncLedgerInput} SyncLedgerInput */
+/** @typedef {import("./repositories/sync-ledger.js").SyncLedgerRecord} SyncLedgerRecord */
+/** @typedef {import("./repositories/sync-ledger.js").SyncLedgerRepository} SyncLedgerRepository */
+/** @typedef {import("./repositories/sync-ledger.js").SyncLedgerRepositoryEvent} SyncLedgerRepositoryEvent */
+/** @typedef {import("./repositories/sync-ledger.js").SyncCursorDeletedEvent} SyncCursorDeletedEvent */
+/** @typedef {import("./repositories/sync-ledger.js").SyncDeltaAppliedEvent} SyncDeltaAppliedEvent */
+/** @typedef {import("./repositories/revisioned-repository.js").AgentRepository} AgentRepository */
+/** @typedef {import("./repositories/revisioned-repository.js").GraphRepository} GraphRepository */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {import("./repositories/revisioned-repository.js").RevisionCommand<TValue>} RevisionCommand */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {import("./repositories/revisioned-repository.js").RevisionCommandResult<TValue>} RevisionCommandResult */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {import("./repositories/revisioned-repository.js").RevisionedEntity<TValue>} RevisionedEntity */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {import("./repositories/revisioned-repository.js").RevisionedRepository<TValue>} RevisionedRepository */
+/** @typedef {import("./repositories/revisioned-repository.js").RevisionedRepositoryDomain} RevisionedRepositoryDomain */
+/** @typedef {import("./repositories/revisioned-repository.js").RevisionedRepositoryEvent} RevisionedRepositoryEvent */
+/** @typedef {import("./repositories/revisioned-repository.js").RevisionedSettingsRepository} RevisionedSettingsRepository */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletAuthoritativeSnapshot} WalletAuthoritativeSnapshot */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletCommandResult} WalletCommandResult */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletL402Receipt} WalletL402Receipt */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletMirrorRepository} WalletMirrorRepository */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletPaymentRecord} WalletPaymentRecord */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletSnapshotValue} WalletSnapshotValue */
+/** @typedef {import("./media-preferences.js").MediaPreferencesPort} MediaPreferencesPort */
+/** @typedef {import("./scheduler.js").ScheduledJob} ScheduledJob */
+/** @typedef {import("./scheduler.js").SchedulerPort} SchedulerPort */
+/** @typedef {import("./theme.js").ThemeEnvironmentPort} ThemeEnvironmentPort */
+/** @typedef {import("./theme.js").ThemePreference} ThemePreference */
+/** @typedef {import("./storage.js").EncryptedStorageDiagnostic} EncryptedStorageDiagnostic */
+/** @typedef {import("./storage.js").IdentityScopedStorageRepositoryPort} IdentityScopedStorageRepositoryPort */
+/** @typedef {import("./storage.js").StorageDatabasePort} StorageDatabasePort */
+/** @typedef {import("./storage.js").StoragePort} StoragePort */
+/** @typedef {import("./storage.js").StorageReadyState} StorageReadyState */
+/** @typedef {import("./storage.js").StorageRecoveryCode} StorageRecoveryCode */
+/** @typedef {import("./storage.js").StorageRecoveryRequiredState} StorageRecoveryRequiredState */
+/** @typedef {import("./storage.js").StorageRecoveryState} StorageRecoveryState */
+/** @typedef {import("./storage.js").StorageRepositoryEvent} StorageRepositoryEvent */
+/** @typedef {import("./storage.js").StorageRepositoryPort} StorageRepositoryPort */
+/** @typedef {import("./storage.js").StorageStartingState} StorageStartingState */
+export { StorageOperationError } from "./storage.js";
+/** @typedef {import("./offline-readiness.js").OfflineIdentityScope} OfflineIdentityScope */
+/** @typedef {import("./offline-readiness.js").OfflineProjectionRepository} OfflineProjectionRepository */
+/** @typedef {import("./offline-readiness.js").OfflineReadinessFailureCode} OfflineReadinessFailureCode */
+/** @typedef {import("./offline-readiness.js").OfflineStageReadiness} OfflineStageReadiness */
+/** @typedef {import("./offline-readiness.js").OfflineStageRepository} OfflineStageRepository */
+/** @typedef {import("./offline-readiness.js").OfflineStageState} OfflineStageState */
+/** @typedef {import("./offline-readiness.js").OfflineStorageEstimatePort} OfflineStorageEstimatePort */
+/** @typedef {import("./offline-readiness.js").StageAssetCandidate} StageAssetCandidate */
+/** @typedef {import("./offline-readiness.js").VerifiedStageAssetPort} VerifiedStageAssetPort */
+/** @typedef {import("./lcd-tree-source.js").LcdScreenStatePatch} LcdScreenStatePatch */
+/** @typedef {import("./lcd-tree-source.js").LcdTreeNode} LcdTreeNode */
+/** @typedef {import("./lcd-tree-source.js").LcdTreeOutcome} LcdTreeOutcome */
+/** @typedef {import("./lcd-tree-source.js").LcdTreeSourcePort} LcdTreeSourcePort */
+/** @typedef {import("./legacy-credential.js").LegacyCredentialProbePort} LegacyCredentialProbePort */
+/** @typedef {import("./legacy-credential.js").LegacyCredentialStatus} LegacyCredentialStatus */
+/** @typedef {import("./network/certificate-trust.js").CertificateTrustPlatform} CertificateTrustPlatform */
+/** @typedef {import("./network/certificate-trust.js").CertificateTrustProbePort} CertificateTrustProbePort */
+/** @typedef {import("./network/certificate-trust.js").CertificateTrustProbeResult} CertificateTrustProbeResult */
+/** @typedef {import("./network/certificate-trust.js").PlatformTrustPort} PlatformTrustPort */
+/** @typedef {import("./onboarding-access-code.js").OnboardingAccessCodeStore} OnboardingAccessCodeStore */
+/** @typedef {import("./onboarding-checkpoint.js").OnboardingCheckpointStoragePort} OnboardingCheckpointStoragePort */
+/** @typedef {import("./onboarding-presence.js").OnboardingPresencePhase} OnboardingPresencePhase */
+/** @typedef {import("./onboarding-presence.js").OnboardingPresencePort} OnboardingPresencePort */
+/** @typedef {import("./owner-claim-session.js").OwnerClaimGenesisDevice} OwnerClaimGenesisDevice */
+/** @typedef {import("./owner-claim-session.js").OwnerClaimSessionPort} OwnerClaimSessionPort */
+/** @typedef {import("./owner-claim-session.js").OwnerClaimSessionTokens} OwnerClaimSessionTokens */
+/** @typedef {import("./owner-claim.js").OwnerClaimCryptoPort} OwnerClaimCryptoPort */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppInstallSource} NodeAppInstallSource */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppBudgetState} NodeAppBudgetState */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppBudgetVerdict} NodeAppBudgetVerdict */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppDeviceMemory} NodeAppDeviceMemory */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppGovernorRow} NodeAppGovernorRow */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppHeapObjectTypeCount} NodeAppHeapObjectTypeCount */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppHeapSnapshot} NodeAppHeapSnapshot */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppHeapSnapshotState} NodeAppHeapSnapshotState */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppHeapSnapshotSummary} NodeAppHeapSnapshotSummary */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppLaneKind} NodeAppLaneKind */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppLifecycleMemoryObservation} NodeAppLifecycleMemoryObservation */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryActivityRollup} NodeAppMemoryActivityRollup */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryApp} NodeAppMemoryApp */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryAttribution} NodeAppMemoryAttribution */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryAvailability} NodeAppMemoryAvailability */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryBudgetBasis} NodeAppMemoryBudgetBasis */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryCapabilityCallCount} NodeAppMemoryCapabilityCallCount */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryDownload} NodeAppMemoryDownload */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryOverview} NodeAppMemoryOverview */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryOverviewApp} NodeAppMemoryOverviewApp */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryReading} NodeAppMemoryReading */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryRepository} NodeAppMemoryRepository */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemorySnapshot} NodeAppMemorySnapshot */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemorySource} NodeAppMemorySource */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryTrend} NodeAppMemoryTrend */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryTrendVerdict} NodeAppMemoryTrendVerdict */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppMemoryUnavailableReason} NodeAppMemoryUnavailableReason */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppPressureState} NodeAppPressureState */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppRuntimeMode} NodeAppRuntimeMode */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppStatus} NodeAppStatus */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppTerminationReason} NodeAppTerminationReason */
+/** @typedef {import("./repositories/node-app-memory-repository.js").NodeAppType} NodeAppType */
+/** @typedef {import("./session-flag.js").SessionFlagPort} SessionFlagPort */
+/** @typedef {import("./shell-cache-reset.js").ShellCacheResetPort} ShellCacheResetPort */
+/** @typedef {import("./shell-version.js").ShellVersionPort} ShellVersionPort */
+/** @typedef {import("./shell-version.js").ShellVersionReport} ShellVersionReport */
+
+export { CONVERSATION_MESSAGE_STATES } from "./repositories/conversation-repository.js";
+export { createNullInstallEnvironment } from "./install-environment.js";
+export { createNullLcdTreeSource } from "./lcd-tree-source.js";
+export { createNullOnboardingPresence } from "./onboarding-presence.js";
+export { createNullOwnerClaimSession } from "./owner-claim-session.js";
+export { CAPABILITY_INVOKE_OPERATION } from "./network.js";
+export { DEFAULT_CLIENT_NODE_ORIGIN } from "./network/client-node-origin.js";
+export { OutboxIdempotencyConflictError } from "./repositories/outbox.js";
+export { REVISIONED_REPOSITORY_DOMAINS } from "./repositories/revisioned-repository.js";
+export {
+  MAX_CLOSE_REASON_BYTES,
+  MAX_DTLS_FINGERPRINT_BYTES,
+  MAX_ICE_CANDIDATE_BYTES,
+  MAX_ICE_CANDIDATES_PER_OFFER,
+  MAX_OFFER_NONCE_BYTES,
+  MAX_SDP_BYTES,
+  MAX_SDP_MID_BYTES,
+  MAX_WEBRTC_SIGNAL_MESSAGE_BYTES,
+  MIN_OFFER_NONCE_BYTES,
+  WEBRTC_SIGNAL_VERSION,
+} from "./network/webrtc-signaling.js";
+export {
+  isWalletAuthoritativeSnapshot,
+  isWalletCommandResult,
+  isWalletSnapshotValue,
+} from "./repositories/wallet-mirror-repository.js";
+export {
+  RESET_LOCAL_STORAGE_CONFIRMATION,
+  STORAGE_RECOVERY_MESSAGES,
+} from "./storage.js";

package/src/install-environment.js

@@ -0,0 +1,44 @@
+// @ts-check
+
+/** @typedef {"installable" | "ios" | "safari-desktop" | "unsupported"} InstallInstructionMode */
+
+/**
+ * Boundary port for PWA install detection.
+ *
+ * @typedef {{
+ *   isStandalone(): boolean,
+ *   instructionMode(): InstallInstructionMode,
+ *   onInstallAvailable(listener: () => void): () => void,
+ *   promptInstall(): Promise<"accepted" | "dismissed" | "unavailable">,
+ *   onAppInstalled(listener: () => void): () => void,
+ *   checkAlreadyInstalled(): Promise<boolean>
+ * }} InstallEnvironmentPort
+ */
+
+/**
+ * A no-op install environment for SSR, tests, and platforms without browser install support.
+ *
+ * @returns {InstallEnvironmentPort}
+ */
+export function createNullInstallEnvironment() {
+  return {
+    isStandalone() {
+      return false;
+    },
+    instructionMode() {
+      return "unsupported";
+    },
+    onInstallAvailable() {
+      return () => undefined;
+    },
+    async promptInstall() {
+      return "unavailable";
+    },
+    onAppInstalled() {
+      return () => undefined;
+    },
+    async checkAlreadyInstalled() {
+      return false;
+    },
+  };
+}