@econ-v1/ports 6.7.0 → 6.10.0

package/src/repositories/node-app-memory-repository.js

@@ -0,0 +1,221 @@
+// @ts-check
+export {};
+/** @typedef {"local" | "registry" | "upload"} NodeAppInstallSource */
+/**
+ * @typedef {| "aggregate_shared_host"
+ *   | "exact_cgroup"
+ *   | "exact_isolate"
+ *   | "exact_process"
+ *   | "mapped_partial"
+ *   | "self_reported"
+ *   | "unavailable"} NodeAppMemoryAttribution
+ */
+/** @typedef {"measured" | "stale" | "unavailable"} NodeAppMemoryAvailability */
+/**
+ * @typedef {| "bun_heap_self_report"
+ *   | "cgroup_v2"
+ *   | "main_pid_smaps_rollup"
+ *   | "main_pid_status_vm_rss"
+ *   | "proc_smaps_mappings"
+ *   | "proc_smaps_rollup"
+ *   | "shared_host_residual"} NodeAppMemorySource
+ */
+/**
+ * @typedef {| "cgroup_unavailable"
+ *   | "non_linux"
+ *   | "not_attributable"
+ *   | "not_sampled"
+ *   | "permission_denied"
+ *   | "proc_unavailable"
+ *   | "process_not_running"
+ *   | "systemd_unavailable"} NodeAppMemoryUnavailableReason
+ */
+/** @typedef {"dedicated" | "shared"} NodeAppRuntimeMode */
+/**
+ * @typedef {| "active"
+ *   | "consent_required"
+ *   | "degraded"
+ *   | "error"
+ *   | "installed"
+ *   | "lazy"
+ *   | "restarting"
+ *   | "stopped"} NodeAppStatus
+ */
+/** @typedef {"bun" | "native"} NodeAppType */
+/**
+ * @typedef {object} NodeAppMemoryReading
+ * @property {NodeAppMemoryAttribution} attribution
+ * @property {NodeAppMemoryAvailability} availability
+ * @property {string} observedAt
+ * @property {NodeAppMemoryUnavailableReason} [reason]
+ * @property {NodeAppMemorySource} source
+ * @property {number | null} valueKb
+ */
+/**
+ * @typedef {object} NodeAppMemorySnapshot
+ * @property {NodeAppMemoryReading} heapTotal
+ * @property {NodeAppMemoryReading} heapUsed
+ * @property {NodeAppMemoryReading} external
+ * @property {NodeAppMemoryReading} heapCapacity
+ * @property {NodeAppMemoryReading} pss
+ * @property {NodeAppMemoryReading} rss
+ */
+/**
+ * @typedef {object} NodeAppMemoryApp
+ * @property {NodeAppType} appType
+ * @property {string} author
+ * @property {string} description
+ * @property {string} id
+ * @property {NodeAppInstallSource} installSource
+ * @property {NodeAppMemorySnapshot} [memory]
+ * @property {string} name
+ * @property {NodeAppRuntimeMode} [runtimeMode]
+ * @property {NodeAppStatus} status
+ * @property {string} version
+ */
+/**
+ * @typedef {object} NodeAppMemoryRepository
+ * @property {() => Promise<readonly NodeAppMemoryApp[]>} listApps
+ * @property {(id: string) => Promise<NodeAppMemoryApp | undefined>} readApp
+ * @property {() => Promise<NodeAppMemoryOverview>} readOverview
+ * @property {(id: string) => Promise<NodeAppHeapSnapshot>} captureMemorySnapshot
+ * @property {(id: string) => Promise<NodeAppHeapSnapshot | null>} readMemorySnapshotStatus
+ * @property {(id: string, snapshotId: string) => Promise<NodeAppMemoryDownload>} downloadMemorySnapshot
+ */
+
+/** @typedef {{ arrayBuffer: () => Promise<ArrayBuffer>, readonly size: number, readonly type: string }} NodeAppMemoryDownload */
+
+/** @typedef {"capturing" | "complete" | "failed"} NodeAppHeapSnapshotState */
+/**
+ * @typedef {object} NodeAppHeapObjectTypeCount
+ * @property {number} count
+ * @property {string} objectType
+ * @property {number} sizeBytes
+ */
+/**
+ * @typedef {object} NodeAppHeapSnapshotSummary
+ * @property {number} objectCount
+ * @property {readonly NodeAppHeapObjectTypeCount[]} objectTypes
+ */
+/**
+ * @typedef {object} NodeAppHeapSnapshot
+ * @property {string} appId
+ * @property {string | null} completedAt
+ * @property {string} createdAt
+ * @property {string | null} error
+ * @property {string} id
+ * @property {number | null} sizeBytes
+ * @property {NodeAppHeapSnapshotState} state
+ * @property {NodeAppHeapSnapshotSummary | null} summary
+ */
+/**
+ * @typedef {object} NodeAppLifecycleMemoryObservation
+ * @property {string} appId
+ * @property {string} observedAt
+ * @property {number} releasedKb
+ */
+
+/** @typedef {"heap_used" | "not_attributable" | "pss" | "rss"} NodeAppMemoryBudgetBasis */
+/** @typedef {"flat" | "growing" | "ratcheting" | "sawtooth" | "unknown"} NodeAppMemoryTrendVerdict */
+/**
+ * Growth classification over the trailing sample window. `slopeKbPerHour`,
+ * `fitQuality`, `ratchetRatio`, `heapFloorSlopeKbPerHour`, and
+ * `hoursToBudget` are each omitted (not `null`) when the host did not
+ * compute them — mirroring the Rust `#[serde(skip_serializing_if =
+ * "Option::is_none")]` wire contract.
+ * @typedef {object} NodeAppMemoryTrend
+ * @property {boolean} aggregate
+ * @property {NodeAppMemoryBudgetBasis} basis
+ * @property {string} computedAt
+ * @property {number} [fitQuality]
+ * @property {number} [heapFloorSlopeKbPerHour]
+ * @property {number} [hoursToBudget]
+ * @property {number} [ratchetRatio]
+ * @property {number} sampleCount
+ * @property {number} [slopeKbPerHour]
+ * @property {NodeAppMemoryTrendVerdict} verdict
+ * @property {number} windowHours
+ */
+/**
+ * @typedef {object} NodeAppMemoryCapabilityCallCount
+ * @property {string} capability
+ * @property {number} invocations
+ */
+/**
+ * Capability call load over the same window as {@link NodeAppMemoryTrend}.
+ * @typedef {object} NodeAppMemoryActivityRollup
+ * @property {number} callsPerMinute
+ * @property {string} computedAt
+ * @property {number} errors
+ * @property {number} invocations
+ * @property {readonly NodeAppMemoryCapabilityCallCount[]} topCapabilities
+ * @property {number} windowHours
+ */
+/** @typedef {"not_attributable" | "ok" | "over"} NodeAppBudgetState */
+/** @typedef {"evicted" | "idle_countdown" | "running" | "sleeping" | "warm"} NodeAppLaneKind */
+/** @typedef {"idle" | "pressure"} NodeAppTerminationReason */
+/** @typedef {"evicting" | "ok" | "unknown"} NodeAppPressureState */
+/**
+ * @typedef {object} NodeAppBudgetVerdict
+ * @property {boolean} aggregate
+ * @property {NodeAppMemoryBudgetBasis} basis
+ * @property {number | null} budgetKb
+ * @property {number | null} overByKb
+ * @property {NodeAppBudgetState} state
+ * @property {number | null} valueKb
+ */
+/**
+ * @typedef {object} NodeAppGovernorRow
+ * @property {string} appId
+ * @property {string} appName
+ * @property {string} eligibility
+ * @property {number} idleSecs
+ * @property {number} inFlight
+ * @property {NodeAppLaneKind} lane
+ * @property {string} [lastStopAt]
+ * @property {NodeAppTerminationReason} [lastStopReason]
+ * @property {string} [lastWakeAt]
+ * @property {number} [minIdleSecs]
+ * @property {number} [secsRemaining]
+ * @property {NodeAppTerminationReason} [terminationReason]
+ */
+/**
+ * @typedef {object} NodeAppDeviceMemory
+ * @property {number} highWaterKb
+ * @property {number} lowWaterKb
+ * @property {number | null} memAvailableKb
+ * @property {number | null} memTotalKb
+ * @property {number | null} psiSomeAvg10
+ * @property {number | null} platformRssKb
+ * @property {NodeAppPressureState} pressureState
+ * @property {number | null} swapFreeKb
+ * @property {number | null} swapTotalKb
+ */
+/**
+ * `swapTotalKb`/`swapFreeKb` keep the same unmeasured-is-not-zero contract as
+ * `memAvailableKb`: `0` is a machine with no swap configured, `null` is a
+ * machine that could not be asked. A renderer MUST distinguish them — "no
+ * swap" and "we don't know" are different things to tell an owner. Swap IN USE
+ * is `swapTotalKb - swapFreeKb`, and is only meaningful when both are numbers.
+ */
+/**
+ * @typedef {object} NodeAppMemoryOverviewApp
+ * @property {NodeAppMemoryActivityRollup} [activity]
+ * @property {NodeAppBudgetVerdict} budget
+ * @property {NodeAppGovernorRow} [governor]
+ * @property {string} id
+ * @property {Partial<NodeAppMemorySnapshot>} [memory]
+ * @property {NodeAppHeapSnapshot | null} [capture]
+ * @property {NodeAppLifecycleMemoryObservation | null} [lifecycleObservation]
+ * @property {string} name
+ * @property {NodeAppRuntimeMode} [runtimeMode]
+ * @property {NodeAppStatus} status
+ * @property {NodeAppMemoryTrend} [trend]
+ * @property {string} version
+ */
+/**
+ * @typedef {object} NodeAppMemoryOverview
+ * @property {readonly NodeAppMemoryOverviewApp[]} apps
+ * @property {NodeAppDeviceMemory | null} device
+ * @property {NodeAppMemoryReading} [sharedHostResidual]
+ */

package/src/repositories/outbox.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+/** @template {import("./durable-event.js").DurableEvent} [TEvent=import("./durable-event.js").DurableEvent] @typedef {import("./durable-event.js").RepositoryWriteResult<TEvent>} RepositoryWriteResult */
+/** @typedef {import("./repository-mutation.js").RepositoryJsonValue} RepositoryJsonValue */
+/** @typedef {"acknowledged" | "conflict" | "failed" | "pending" | "replaying"} OutboxRecordState */
+/** @typedef {{ readonly createdAt: string, readonly domain: string, readonly id: string, readonly idempotencyKey: string, readonly payload: RepositoryJsonValue, readonly state: OutboxRecordState, readonly updatedAt: string }} OutboxRecord */
+/** @typedef {OutboxRecord & { readonly attemptCount: number, readonly leaseExpiresAt: string, readonly leaseToken: string, readonly state: "replaying" }} OutboxReplayClaim */
+/** @typedef {{ readonly attemptCount: number, readonly createdAt: string, readonly domain: string, readonly id: string, readonly lastErrorCode?: string, readonly lastErrorMessage?: string, readonly nextAttemptAt?: string, readonly settledAt?: string, readonly state: OutboxRecordState, readonly terminalErrorCode?: string, readonly terminalErrorMessage?: string, readonly updatedAt: string }} OutboxReplayStatus */
+/** @typedef {{ readonly id: string, readonly leaseToken: string, readonly outcome: "acknowledged" } | { readonly error: { readonly code: string, readonly message: string }, readonly id: string, readonly leaseToken: string, readonly outcome: "conflict" | "failed" } | { readonly error: { readonly code: string, readonly message: string }, readonly id: string, readonly leaseToken: string, readonly outcome: "retry", readonly retryAt: string }} OutboxSettleInput */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly intent: OutboxRecord }, readonly type: "outbox.state-changed" }} OutboxStateChangedEvent */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly action: "deleted", readonly entityId: string, readonly entityType: "outbox-intent" }, readonly type: "domain.entity-changed" }} OutboxDeletedEvent */
+/** @typedef {OutboxDeletedEvent | OutboxStateChangedEvent} OutboxRepositoryEvent */
+/** @typedef {{ readonly domain?: string, readonly state?: OutboxRecordState }} OutboxRepositoryFilter */
+
+export class OutboxIdempotencyConflictError extends Error {
+  /** @readonly @type {string} */
+  idempotencyKey;
+
+  /** @param {string} idempotencyKey */
+  constructor(idempotencyKey) {
+    super("Outbox idempotency key belongs to a different command");
+    this.name = "OutboxIdempotencyConflictError";
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
+/** @typedef {{ claimHead?(input: { readonly domain: string, readonly leaseExpiresAt: string, readonly leaseToken: string }): Promise<OutboxReplayClaim | undefined>, create(input: OutboxRecord): Promise<RepositoryWriteResult<OutboxRepositoryEvent>>, delete(id: string): Promise<RepositoryWriteResult<OutboxRepositoryEvent>>, list(filter?: OutboxRepositoryFilter): Promise<readonly OutboxRecord[]>, read(id: string): Promise<OutboxRecord | undefined>, listStatus?(filter?: { readonly domain?: string }): Promise<readonly OutboxReplayStatus[]>, settle?(input: OutboxSettleInput): Promise<RepositoryWriteResult<OutboxRepositoryEvent>>, updateState(id: string, state: OutboxRecordState): Promise<RepositoryWriteResult<OutboxRepositoryEvent>> }} OutboxRepository */

package/src/repositories/repository-mutation.js

@@ -0,0 +1,8 @@
+// @ts-check
+
+/** @typedef {boolean | null | number | string} RepositoryJsonPrimitive */
+/** @typedef {RepositoryJsonPrimitive | RepositoryJsonArray | RepositoryJsonObject} RepositoryJsonValue */
+/** @typedef {RepositoryJsonValue[]} RepositoryJsonArray */
+/** @typedef {{ readonly [key: string]: RepositoryJsonValue }} RepositoryJsonObject */
+
+export {};

package/src/repositories/revisioned-repository.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+/** @typedef {import("./repository-mutation.js").RepositoryJsonValue} RepositoryJsonValue */
+/** @template {import("./durable-event.js").DurableEvent} [TEvent=import("./durable-event.js").DurableEvent] @typedef {import("./durable-event.js").RepositoryWriteResult<TEvent>} RepositoryWriteResult */
+
+export const REVISIONED_REPOSITORY_DOMAINS = /** @type {const} */ (["agent", "settings", "graph"]);
+/** @typedef {typeof REVISIONED_REPOSITORY_DOMAINS[number]} RevisionedRepositoryDomain */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {{ readonly id: string, readonly rev: number, readonly value: TValue }} RevisionedEntity */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {{ readonly baseRev: number, readonly id: string, readonly idempotencyKey: string, readonly value: TValue }} RevisionCommand */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {{ readonly entity: RevisionedEntity<TValue>, readonly status: "accepted" } | { readonly status: "conflict", readonly theirs: RevisionedEntity<TValue> }} RevisionCommandResult */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly action: "created" | "updated", readonly entityId: string, readonly entityType: "agent" | "graph" | "setting" }, readonly type: "domain.entity-changed" }} RevisionedRepositoryEvent */
+/** @template {RepositoryJsonValue} [TValue=RepositoryJsonValue] @typedef {{ apply(entity: RevisionedEntity<TValue>): Promise<RepositoryWriteResult<RevisionedRepositoryEvent>>, command(input: RevisionCommand<TValue>): Promise<RevisionCommandResult<TValue>>, list(): Promise<readonly RevisionedEntity<TValue>[]>, read(id: string): Promise<RevisionedEntity<TValue> | undefined> }} RevisionedRepository */
+/** @typedef {RevisionedRepository} AgentRepository */
+/** @typedef {RevisionedRepository} RevisionedSettingsRepository */
+/** @typedef {RevisionedRepository} GraphRepository */
+
+export {};

package/src/repositories/settings.js

@@ -0,0 +1,10 @@
+// @ts-check
+
+/** @template {import("./durable-event.js").DurableEvent} [TEvent=import("./durable-event.js").DurableEvent] @typedef {import("./durable-event.js").RepositoryWriteResult<TEvent>} RepositoryWriteResult */
+/** @typedef {import("./repository-mutation.js").RepositoryJsonValue} RepositoryJsonValue */
+/** @typedef {{ readonly key: string, readonly updatedAt: string, readonly value: RepositoryJsonValue }} SettingRecord */
+/** @typedef {{ readonly key: string, readonly value: RepositoryJsonValue }} SettingInput */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly action: "created" | "deleted" | "updated", readonly entityId: string, readonly entityType: "setting" }, readonly type: "domain.entity-changed" }} SettingsRepositoryEvent */
+/** @typedef {{ delete(key: string): Promise<RepositoryWriteResult<SettingsRepositoryEvent>>, list(): Promise<readonly SettingRecord[]>, read(key: string): Promise<SettingRecord | undefined>, set(input: SettingInput): Promise<RepositoryWriteResult<SettingsRepositoryEvent>> }} SettingsRepository */
+
+export {};

package/src/repositories/sync-ledger.js

@@ -0,0 +1,11 @@
+// @ts-check
+
+/** @template {import("./durable-event.js").DurableEvent} [TEvent=import("./durable-event.js").DurableEvent] @typedef {import("./durable-event.js").RepositoryWriteResult<TEvent>} RepositoryWriteResult */
+/** @typedef {{ readonly cursor: string, readonly domain: string }} SyncLedgerInput */
+/** @typedef {SyncLedgerInput & { readonly updatedAt: string }} SyncLedgerRecord */
+/** @typedef {{ readonly occurredAt: string, readonly payload: SyncLedgerInput, readonly type: "sync.delta-applied" }} SyncDeltaAppliedEvent */
+/** @typedef {{ readonly occurredAt: string, readonly payload: { readonly action: "deleted", readonly entityId: string, readonly entityType: "sync-cursor" }, readonly type: "domain.entity-changed" }} SyncCursorDeletedEvent */
+/** @typedef {SyncCursorDeletedEvent | SyncDeltaAppliedEvent} SyncLedgerRepositoryEvent */
+/** @typedef {{ delete(domain: string): Promise<RepositoryWriteResult<SyncLedgerRepositoryEvent>>, list(): Promise<readonly SyncLedgerRecord[]>, read(domain: string): Promise<SyncLedgerRecord | undefined>, setCursor(input: SyncLedgerInput): Promise<RepositoryWriteResult<SyncLedgerRepositoryEvent>> }} SyncLedgerRepository */
+
+export {};

package/src/repositories/wallet-mirror-repository.js

@@ -0,0 +1,73 @@
+// @ts-check
+
+/** @typedef {{ readonly amountMsat: number, readonly createdAt: string, readonly direction: "incoming" | "outgoing", readonly failureCode?: string, readonly id: string, readonly paymentHash?: string, readonly status: "pending" | "succeeded" | "failed" | "expired", readonly updatedAt: string }} WalletPaymentRecord */
+/** @typedef {{ readonly amountMsat: number, readonly paidAt: string, readonly paymentHash?: string, readonly receiptId: string, readonly resource: string }} WalletL402Receipt */
+/** @typedef {{ readonly balanceMsat: number, readonly l402: readonly WalletL402Receipt[], readonly payments: readonly WalletPaymentRecord[], readonly spendableMsat: number }} WalletSnapshotValue */
+/** @typedef {{ readonly observedAt: string, readonly staleAt: string, readonly value: WalletSnapshotValue }} WalletAuthoritativeSnapshot */
+/** @typedef {{ readonly amountMsat: number, readonly invoiceId: string, readonly kind: "invoice-created", readonly paymentHash?: string, readonly paymentRequest: string, readonly status: "created" } | { readonly amountMsat: number, readonly kind: "payment-submitted", readonly paymentHash?: string, readonly paymentId: string, readonly status: "pending" | "succeeded" | "failed" }} WalletCommandResult */
+/** @typedef {{ readCommandResult(idempotencyKey: string): Promise<WalletCommandResult | undefined>, readSnapshot(): Promise<WalletAuthoritativeSnapshot | undefined>, writeCommandResult(idempotencyKey: string, result: WalletCommandResult): Promise<void>, writeSnapshot(snapshot: WalletAuthoritativeSnapshot): Promise<void> }} WalletMirrorRepository */
+
+/** @param {unknown} value @returns {value is WalletSnapshotValue} */
+export function isWalletSnapshotValue(value) {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["balanceMsat", "l402", "payments", "spendableMsat"]) ||
+    !isNonNegativeNumber(value.balanceMsat) || !isNonNegativeNumber(value.spendableMsat)) return false;
+  return Array.isArray(value.payments) && value.payments.every(isWalletPaymentRecord) &&
+    Array.isArray(value.l402) && value.l402.every(isWalletL402Receipt);
+}
+
+/** @param {unknown} value @returns {value is WalletAuthoritativeSnapshot} */
+export function isWalletAuthoritativeSnapshot(value) {
+  return isRecord(value) && hasOnlyKeys(value, ["observedAt", "staleAt", "value"]) &&
+    typeof value.observedAt === "string" && typeof value.staleAt === "string" &&
+    isWalletSnapshotValue(value.value);
+}
+
+/** @param {unknown} value @returns {value is WalletCommandResult} */
+export function isWalletCommandResult(value) {
+  if (!isRecord(value) || !isNonNegativeNumber(value.amountMsat)) return false;
+  if (value.kind === "invoice-created") {
+    return hasOnlyKeys(value, ["amountMsat", "invoiceId", "kind", "paymentHash", "paymentRequest", "status"]) &&
+      value.status === "created" && typeof value.invoiceId === "string" && typeof value.paymentRequest === "string" &&
+      (value.paymentHash === undefined || typeof value.paymentHash === "string");
+  }
+  return hasOnlyKeys(value, ["amountMsat", "kind", "paymentHash", "paymentId", "status"]) &&
+    value.kind === "payment-submitted" &&
+    (value.status === "pending" || value.status === "succeeded" || value.status === "failed") &&
+    typeof value.paymentId === "string" &&
+    (value.paymentHash === undefined || typeof value.paymentHash === "string");
+}
+
+/** @param {unknown} value @returns {value is WalletPaymentRecord} */
+function isWalletPaymentRecord(value) {
+  if (!isRecord(value) || !isNonNegativeNumber(value.amountMsat) || typeof value.createdAt !== "string" ||
+    typeof value.id !== "string" || typeof value.updatedAt !== "string" ||
+    !hasOnlyKeys(value, ["amountMsat", "createdAt", "direction", "failureCode", "id", "paymentHash", "status", "updatedAt"])) return false;
+  return (value.direction === "incoming" || value.direction === "outgoing") &&
+    (value.status === "pending" || value.status === "succeeded" || value.status === "failed" || value.status === "expired") &&
+    (value.failureCode === undefined || typeof value.failureCode === "string") &&
+    (value.paymentHash === undefined || typeof value.paymentHash === "string");
+}
+
+/** @param {unknown} value @returns {value is WalletL402Receipt} */
+function isWalletL402Receipt(value) {
+  return isRecord(value) && hasOnlyKeys(value, ["amountMsat", "paidAt", "paymentHash", "receiptId", "resource"]) &&
+    isNonNegativeNumber(value.amountMsat) && typeof value.paidAt === "string" &&
+    typeof value.receiptId === "string" && typeof value.resource === "string" &&
+    (value.paymentHash === undefined || typeof value.paymentHash === "string");
+}
+
+/** @param {unknown} value @returns {value is number} */
+function isNonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** @param {Record<string, unknown>} value @param {readonly string[]} allowed @returns {boolean} */
+function hasOnlyKeys(value, allowed) {
+  const allowedKeys = new Set(allowed);
+  return Object.keys(value).every((key) => allowedKeys.has(key));
+}

package/src/repositories.js

@@ -0,0 +1,22 @@
+// @ts-check
+
+/** @typedef {{ readonly entry: string, readonly integrity: Readonly<Record<string, string>>, readonly requires: readonly string[], readonly version: string }} StageManifest */
+/** @typedef {"last-known" | "online-only"} AppDataOfflinePolicy */
+/** @typedef {"collection" | "detail" | "snapshot"} AppDataQueryKind */
+/** @typedef {"changes" | "events"} AppDataStreamKind */
+/** @typedef {"cursor" | "snapshot"} AppDataSyncKind */
+/** @typedef {{ readonly cursorTtlSecs?: number, readonly fullRefreshIntervalSecs?: number, readonly kind: AppDataSyncKind, readonly retentionSecs?: number }} AppDataSyncPolicy */
+/** @typedef {{ readonly capability: string, readonly kind: AppDataQueryKind, readonly name: string }} AppDataQueryDeclaration */
+/** @typedef {{ readonly kind: AppDataStreamKind, readonly name: string }} AppDataStreamDeclaration */
+/** @typedef {{ readonly namespace: string, readonly offline: AppDataOfflinePolicy, readonly queries: readonly AppDataQueryDeclaration[], readonly streams: readonly AppDataStreamDeclaration[], readonly sync: AppDataSyncPolicy }} AppDataManifest */
+/** @typedef {"stage" | "widget"} StageUiKind */
+/** @typedef {{ readonly order: number, readonly section: string }} StageUiNav */
+/** @typedef {{ readonly capabilities: readonly string[], readonly queries: readonly string[], readonly streams: readonly string[] }} StageUiRequirements */
+/** @typedef {{ readonly composes: readonly string[], readonly icon?: string, readonly kind: StageUiKind, readonly nav?: StageUiNav, readonly requires?: StageUiRequirements, readonly title: string, readonly uiApi: 1 | 2 }} StageUiMetadata */
+/** @typedef {{ readonly appName: string, readonly assetBase: string, readonly data?: AppDataManifest, readonly description?: string, readonly keywords?: readonly string[], readonly manifest: StageManifest, readonly manifestSha256: string, readonly ui: StageUiMetadata }} StageCatalogEntry */
+/** @typedef {{ readonly entries: readonly StageCatalogEntry[], readonly revision: string }} StageRegistrySnapshot */
+/** @typedef {{ read(): Promise<StageRegistrySnapshot | undefined>, write(snapshot: StageRegistrySnapshot): Promise<void> }} StageRegistryPort */
+/** @typedef {{ readonly appName: string, readonly entryUrl: string, readonly manifestSha256: string, readonly version: string }} PreparedStageAsset */
+/** @typedef {{ prepare(appName: string, manifest: StageManifest): Promise<PreparedStageAsset> }} StageAssetPort */
+
+export {};

package/src/scheduler.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+/** @typedef {{ readonly cadenceMs?: number, readonly dueAt: string, readonly name: string, run(): Promise<void> }} ScheduledJob */
+/** @typedef {{ cancel(name: string): void, register(job: ScheduledJob): void, shutdown(): Promise<void> }} SchedulerPort */
+
+export {};

package/src/session-flag.js

@@ -0,0 +1,48 @@
+// @ts-check
+export {};
+/**
+ * Boundary port for the one boolean flag `system/pwa/src/main.ts` needs out of
+ * `sessionStorage` before the shell exists: the "Continue in browser" escape hatch
+ * (`CONTINUE_IN_BROWSER_KEY`, `system/pwa/src/boot-gate.ts`) that the install landing's
+ * "Continue in browser" button sets, and that the top-level boot-gate computation reads back
+ * on the next navigation this session.
+ *
+ * The composition root (`system/pwa/src/main.ts`) may not name `sessionStorage` directly
+ * (boundary rules B3/B4, `client/scripts/check-boundaries.mjs`) — this is the narrow surface
+ * `client/adapters-web`'s `createBrowserSessionFlag()` implements against the real global,
+ * constructed and called directly from `main.ts`, mirroring `ClipboardPort`'s and
+ * `MediaPreferencesPort`'s seams.
+ *
+ * Deliberately NOT routed through one of `client/ui`'s `configureX`/`currentX()` module-level
+ * slots the way `ClipboardPort`/`MediaPreferencesPort` are: those ports back calls made FROM
+ * `client/ui` (an onboarding screen's paste button, the shell's hover/motion checks), so
+ * `client/ui` needs somewhere to read an injected implementation from. Both call sites for
+ * this flag — `renderInstallLanding()`'s `onContinue` handler and the top-level
+ * `bootShellNow` computation — live in `main.ts` itself, before `<node-app-shell>` or
+ * `<node-install-landing>` ever mounts, so there is no `client/ui` consumer to inject into;
+ * the composition root simply constructs the adapter and calls it directly, the same way it
+ * already does for `InstallEnvironmentPort`'s `installEnv.isStandalone()`.
+ *
+ * Deliberately synchronous: the read backs `bootShellNow`, a top-level, synchronous
+ * computation in `main.ts` made before the kernel/RPC bridge exists (see `boot-gate.ts`'s own
+ * doc comment on `BootGateInputs`) — turning it async would restructure the whole boot path
+ * for a nicer port shape, which is not this port's job. `MediaPreferencesPort`'s two methods
+ * are synchronous for the identical reason: both are read before any RPC bridge exists.
+ *
+ * Both methods degrade to the SAME safe default the pre-extraction inline `try`/`catch`
+ * blocks in `main.ts` documented — reading or writing `sessionStorage` can throw under
+ * strict privacy modes (Safari private browsing, some content blockers), AND merely
+ * accessing the `sessionStorage` property itself can throw a `SecurityError` in other
+ * locked-down embedders (Firefox/Chrome "block all cookies", an `<iframe sandbox>` without
+ * `allow-same-origin`) — the adapter constructor guards the latter the same way its
+ * `getItem`/`setItem` calls guard the former, so losing the flag must never block booting
+ * the shell, nor may it ever throw and abort evaluation of the composition root:
+ *  - `read()` returns `false` both when the flag was never set AND when the read itself
+ *    failed — the "the flag never stuck" outcome, which simply shows the install landing
+ *    again next time, exactly the pre-existing behavior.
+ *  - `set()` swallows a failed write silently; the visitor already asked to continue in the
+ *    browser and a storage failure must not stand in the way of that.
+ * @typedef {object} SessionFlagPort
+ * @property {(key: string) => boolean} read
+ * @property {(key: string) => void} set
+ */

package/src/shell-cache-reset.js

@@ -0,0 +1,3 @@
+// @ts-check
+/** @typedef {{ reset(): void }} ShellCacheResetPort */
+export {};

package/src/shell-version.js

@@ -0,0 +1,4 @@
+// @ts-check
+/** @typedef {{ readonly available: string | undefined, readonly running: string | undefined }} ShellVersionReport */
+/** @typedef {{ read(): Promise<ShellVersionReport> }} ShellVersionPort */
+export {};

package/src/storage.js

@@ -0,0 +1,60 @@
+// @ts-check
+
+/** @typedef {import("./repositories.js").StageRegistryPort} StageRegistryPort */
+/** @typedef {import("./repositories/conversation-repository.js").ConversationRepository} ConversationRepository */
+/** @typedef {import("./repositories/conversation-repository.js").NotificationRepository} NotificationRepository */
+/** @typedef {import("./repositories/conversation-repository.js").RepositoryEvent} RepositoryEvent */
+/** @typedef {import("./repositories/outbox.js").OutboxRepository} OutboxRepository */
+/** @typedef {import("./repositories/outbox.js").OutboxRepositoryEvent} OutboxRepositoryEvent */
+/** @typedef {import("./repositories/settings.js").SettingsRepository} SettingsRepository */
+/** @typedef {import("./repositories/settings.js").SettingsRepositoryEvent} SettingsRepositoryEvent */
+/** @typedef {import("./repositories/sync-ledger.js").SyncLedgerRepository} SyncLedgerRepository */
+/** @typedef {import("./repositories/sync-ledger.js").SyncLedgerRepositoryEvent} SyncLedgerRepositoryEvent */
+/** @typedef {import("./repositories/revisioned-repository.js").AgentRepository} AgentRepository */
+/** @typedef {import("./repositories/revisioned-repository.js").GraphRepository} GraphRepository */
+/** @typedef {import("./repositories/revisioned-repository.js").RevisionedRepositoryEvent} RevisionedRepositoryEvent */
+/** @typedef {import("./repositories/revisioned-repository.js").RevisionedSettingsRepository} RevisionedSettingsRepository */
+/** @typedef {import("./repositories/wallet-mirror-repository.js").WalletMirrorRepository} WalletMirrorRepository */
+/** @typedef {import("./offline-readiness.js").OfflineProjectionRepository} OfflineProjectionRepository */
+/** @typedef {import("./offline-readiness.js").OfflineIdentityScope} OfflineIdentityScope */
+/** @typedef {import("./offline-readiness.js").OfflineStageRepository} OfflineStageRepository */
+
+export const RESET_LOCAL_STORAGE_CONFIRMATION = "RESET LOCAL CLIENT DATA";
+/** @typedef {"checksum-drift" | "corrupt" | "diagnostic-failed" | "identity-source-unavailable" | "migration-failed" | "opfs-unavailable" | "quota-exceeded" | "worker-operation-timeout" | "worker-preparation-timeout" | "writer-conflict"} StorageRecoveryCode */
+
+/** @satisfies {Readonly<Record<StorageRecoveryCode, string>>} */
+export const STORAGE_RECOVERY_MESSAGES = /** @type {const} */ ({
+  "checksum-drift": "Local schema history does not match this client build",
+  corrupt: "Local SQLite data failed its integrity check",
+  "diagnostic-failed": "Encrypted storage diagnostic creation failed",
+  "identity-source-unavailable": "Protected identity metadata is temporarily unavailable",
+  "migration-failed": "Local SQLite schema migration failed",
+  "opfs-unavailable": "Persistent browser storage is unavailable",
+  "quota-exceeded": "Persistent browser storage quota is exhausted",
+  "worker-operation-timeout": "Persistent storage operation timed out",
+  "worker-preparation-timeout": "Protected storage request preparation timed out",
+  "writer-conflict": "Another client-node storage writer is active",
+});
+
+export class StorageOperationError extends Error {
+  /**
+   * @param {StorageRecoveryCode} code
+   */
+  constructor(code) {
+    super("Persistent storage operation failed");
+    this.name = "StorageOperationError";
+    /** @readonly */
+    this.code = code;
+  }
+}
+
+/** @typedef {{ readonly schemaVersion: number, readonly storageGeneration?: number, readonly status: "ready" }} StorageReadyState */
+/** @typedef {{ readonly schemaVersion: number, readonly storageGeneration?: number, readonly status: "starting" }} StorageStartingState */
+/** @typedef {{ readonly actions: { readonly exportDiagnostic: boolean, readonly reset: true, readonly retry: true }, readonly code: StorageRecoveryCode, readonly message: string, readonly schemaVersion: number, readonly storageGeneration?: number, readonly status: "recovery-required" }} StorageRecoveryRequiredState */
+/** @typedef {StorageReadyState | StorageRecoveryRequiredState | StorageStartingState} StorageRecoveryState */
+/** @typedef {{ readonly algorithm: "AES-GCM", readonly ciphertextBase64: string, readonly createdAt: string, readonly format: "node-client-sqlite-diagnostic-v1", readonly ivBase64: string, readonly kdf: { readonly hash: "SHA-256", readonly iterations: 310000, readonly name: "PBKDF2", readonly saltBase64: string } }} EncryptedStorageDiagnostic */
+/** @typedef {{ readonly offlineProjections: OfflineProjectionRepository, readonly offlineStages: OfflineStageRepository, readonly outbox: OutboxRepository, readonly syncLedger: SyncLedgerRepository }} IdentityScopedStorageRepositoryPort */
+/** @typedef {{ readonly repositories: StorageRepositoryPort, clearActiveIdentityProjections(): Promise<void>, clearScope(scope: OfflineIdentityScope): Promise<void>, close(): Promise<void>, exportEncryptedDiagnostic(options: { readonly passphrase: string }): Promise<EncryptedStorageDiagnostic>, initialize(): Promise<StorageRecoveryState>, reactivateEmptyScope(scope: OfflineIdentityScope): Promise<boolean>, referencedAssetRevisions(): Promise<readonly string[]>, refreshIdentityMetadata(): Promise<void>, recoveryState(): Promise<StorageRecoveryState>, reset(options: { readonly confirmation: string }): Promise<StorageRecoveryState>, retry(): Promise<StorageRecoveryState>, scopedRepositories(scope: OfflineIdentityScope): IdentityScopedStorageRepositoryPort, subscribeRecoveryState(listener: (state: StorageRecoveryState) => void): () => void }} StorageDatabasePort */
+/** @typedef {OutboxRepositoryEvent | RepositoryEvent | RevisionedRepositoryEvent | SettingsRepositoryEvent | SyncLedgerRepositoryEvent} StorageRepositoryEvent */
+/** @typedef {{ readonly conversations?: ConversationRepository, readonly events: import("./repositories/durable-event.js").DurableRepositoryEventStore<StorageRepositoryEvent>, readonly notifications?: NotificationRepository, readonly agents?: AgentRepository, readonly graphs?: GraphRepository, readonly outbox: OutboxRepository, readonly revisionedSettings?: RevisionedSettingsRepository, readonly wallet?: WalletMirrorRepository, readonly settings: SettingsRepository, readonly syncLedger: SyncLedgerRepository }} StorageRepositoryPort */
+/** @typedef {StorageDatabasePort & { readonly stages: StageRegistryPort }} StoragePort */

package/src/theme.js

@@ -0,0 +1,21 @@
+// @ts-check
+
+/** @typedef {"light" | "dark"} ThemePreference */
+
+/**
+ * Boundary port for the shell's dark-mode plumbing (`client/ui/src/shell/theme-init.ts`).
+ *
+ * `client/ui` may never call `localStorage` or `matchMedia` directly (boundary rules
+ * B2/B3, `client/scripts/check-boundaries.mjs`) — this is the narrow surface
+ * `client/adapters-web`'s `createBrowserThemeEnvironment()` implements against the real
+ * globals, and the composition root (`system/pwa/src/main.ts`) registers it (via
+ * `client/ui`'s `configureThemeEnvironment`) before the shell's first paint. Every method is
+ * synchronous and side-effect-free beyond the read/write it names — `theme-init.ts`'s
+ * anti-FOUC contract requires resolving the initial theme before the shadow tree's first
+ * paint, which is before the kernel connection (`KernelRpcClient`, itself an async
+ * `SharedWorker`/leader-tab bridge) even exists, so this can never be mediated through
+ * `@econ-v1/rpc` the way ordinary UI reads/writes are (rule S4).
+ */
+/** @typedef {{ getStoredTheme(): ThemePreference | undefined, setStoredTheme(preference: ThemePreference): void, prefersDarkColorScheme(): boolean, watchDarkColorScheme(onChange: (matches: boolean) => void): (() => void) | undefined }} ThemeEnvironmentPort */
+
+export {};

package/dist/clock.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":""}

package/dist/crypto.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":""}

package/dist/id.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=id.js.map

package/dist/id.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":""}

package/dist/identity.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -1,9 +0,0 @@
-export { createNullInstallEnvironment, } from "./install-environment.js";
-export { DEFAULT_CLIENT_NODE_ORIGIN } from "./network/client-node-origin.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 { CONVERSATION_MESSAGE_STATES } from "./repositories/conversation-repository.js";
-export { OutboxIdempotencyConflictError } from "./repositories/outbox.js";
-export { REVISIONED_REPOSITORY_DOMAINS, } from "./repositories/revisioned-repository.js";
-export { isWalletAuthoritativeSnapshot, isWalletCommandResult, isWalletSnapshotValue, } from "./repositories/wallet-mirror-repository.js";
-export { RESET_LOCAL_STORAGE_CONFIRMATION, STORAGE_RECOVERY_MESSAGES } from "./storage.js";
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAqBlC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAW7E,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,4BAA4B,EAC5B,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,+BAA+B,EAC/B,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAsBvC,OAAO,EAAE,2BAA2B,EAAE,MAAM,2CAA2C,CAAC;AAsBxF,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AA+B1E,OAAO,EACL,6BAA6B,GAC9B,MAAM,yCAAyC,CAAC;AAYjD,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,4CAA4C,CAAC;AAYpD,OAAO,EAAE,gCAAgC,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}