@pellux/goodvibes-daemon 1.28.19 → 1.28.21

package/src/daemon/handlers/inbox/aggregator.ts

@@ -8,7 +8,7 @@
 //
 //   * The mirror is already live. Each adapter polls its provider on that
 //     provider's own cadence (Slack/Discord 30s, email 60s) and writes what it
-//     pulls straight into the store — that is what the triage pipeline scores.
+//     pulls straight into the store, that is what the triage pipeline scores.
 //     Reading it IS reading what has arrived.
 //   * A fetch-per-call would put a third-party rate limit behind a read verb
 //     any client may call at any rate, so one impatient UI could get every
@@ -16,7 +16,7 @@
 //   * The cluster hands FETCHING for each inbox account to one elected node
 //     (runtime/cluster-composition.ts). A read that fetched would make every
 //     standby node fetch too, which is exactly the double-read the election
-//     exists to prevent — while the READ is deliberately ungated so a standby
+//     exists to prevent, while the READ is deliberately ungated so a standby
 //     still answers.
 //   * Triage scores are applied as items are persisted. Items fetched inline
 //     would arrive unscored, so the verb would answer two different shapes
@@ -26,7 +26,7 @@
 //
 // The cost of serving a mirror is that its age is not visible in the items. So
 // the aggregator does not leave it implicit: `providers` reports every provider
-// this node knows about on EVERY call — its state, when it last synced, how
+// this node knows about on EVERY call, its state, when it last synced, how
 // much of the mirror is its, and whether this node is the one fetching it.
 //
 // ── Honest partial results ────────────────────────────────────────────────
@@ -119,7 +119,7 @@ export interface InboxAggregatorSources {
 /**
  * A page cursor is the position of the last item handed out, base64url-encoded
  * so it reads as opaque and callers do not build one by hand. It is NOT the
- * `cursor` field in the answer — that one is the freshness watermark a caller
+ * `cursor` field in the answer, that one is the freshness watermark a caller
  * feeds back as `since`. Two different questions ("what is new" vs "the next
  * page down"), so two different values; collapsing them is how a paging client
  * ends up silently re-reading page one forever.
@@ -234,7 +234,7 @@ export function toWireItem(item: InboundChannelItem): ChannelInboxItem {
  *
  * The merge itself is the store's ordering (receivedAt DESC, id ASC across all
  * providers), so items interleave by arrival rather than being grouped by
- * provider — an inbox is a timeline, and each item carries its own `provider`
+ * provider, an inbox is a timeline, and each item carries its own `provider`
  * so attribution survives the merge.
  */
 export function aggregateInbox(
@@ -300,7 +300,7 @@ export function aggregateInbox(
  * Turn the poller's per-provider record into the wire statuses.
  *
  * Every provider the node has an adapter for appears, including ones that
- * contributed nothing and ones nobody has configured — a provider missing from
+ * contributed nothing and ones nobody has configured, a provider missing from
  * this list would be a hole the caller could not even see.
  */
 function describeProviders(input: {
@@ -313,7 +313,7 @@ function describeProviders(input: {
   const known = poller.snapshotStatuses(requested);
 
   // A `?provider=` filter naming something this node has no adapter for gets an
-  // empty list and no status, which reads as "we have nothing" — so it is
+  // empty list and no status, which reads as "we have nothing", so it is
   // reported explicitly instead.
   const reported = new Set(known.map((status) => status.id));
   const unknownRequested = (requested ?? []).filter((id) => !reported.has(id));
@@ -354,7 +354,7 @@ function describeProviders(input: {
  * Map the poller's internal state onto the wire vocabulary.
  *
  * The internal 'unavailable' covers two situations the wire deliberately keeps
- * apart — nothing configured, versus configured and failing — because a caller
+ * apart, nothing configured, versus configured and failing, because a caller
  * does something different about each.
  *
  * ready-vs-empty is decided by the MIRROR, not by the last poll. The poller's

package/src/daemon/handlers/inbox/cursor-store.ts

@@ -15,11 +15,11 @@
 // separate store, so this feed store carries only the raw inbound fields.
 //
 // RETENTION. The items table is bounded by BOTH an age TTL and a count cap, and
-// the sweep runs at init() — the recovery point, right after the database file
-// is opened — and then on a timer for the life of the store, so a daemon that
+// the sweep runs at init(), the recovery point, right after the database file
+// is opened, and then on a timer for the life of the store, so a daemon that
 // stays up for weeks keeps reclaiming. `pruneOlderThan` used to exist with no
 // production caller at all, which meant the table grew without bound in
-// practice. Reclaimed counts are handed to the `onSweep` hook (counts only —
+// practice. Reclaimed counts are handed to the `onSweep` hook (counts only,
 // message previews and sender ids never reach a log line).
 //
 // Cursors are deliberately NOT reaped: they are monotonic watermarks, so
@@ -28,7 +28,7 @@
 // Idempotence/concurrency: a sweep re-run immediately reclaims nothing (the
 // DELETEs are set-based over the current contents). Two processes opening the
 // same file each hold their own sql.js snapshot and `save()` writes the whole
-// file via temp+rename, so the last writer wins — that whole-file model is
+// file via temp+rename, so the last writer wins, that whole-file model is
 // HandlerSqliteStore's, and deletion converging on the same surviving set is
 // what makes concurrent sweeps safe rather than corrupting.
 // ---------------------------------------------------------------------------
@@ -45,7 +45,7 @@ export const INBOX_ITEM_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 
 /**
  * Count cap for feed items: the newest this many rows survive a sweep, older
- * ones are dropped. Guards the case the TTL cannot — a very chatty month.
+ * ones are dropped. Guards the case the TTL cannot, a very chatty month.
  */
 export const INBOX_ITEM_CAP = 5_000;
 
@@ -57,7 +57,7 @@ export const INBOX_SWEEP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 
 const DEFAULT_STORE_FILE_NAME = 'inbox.sqlite';
 
-/** Result of one retention sweep. Counts only — never item content. */
+/** Result of one retention sweep. Counts only, never item content. */
 export interface InboxSweepSummary {
   /** Unix ms of the sweep. */
   readonly at: number;
@@ -202,7 +202,7 @@ export class InboxCursorStore {
   /**
    * One retention pass: age TTL first, then the count cap over what is left.
    * Returns counts only. Running it twice in a row reclaims nothing the second
-   * time — the pass is a function of the table's current contents.
+   * time, the pass is a function of the table's current contents.
    */
   sweepRetention(): InboxSweepSummary {
     const at = this.now();
@@ -240,7 +240,7 @@ export class InboxCursorStore {
   }
 
   /**
-   * Count cap: keep the newest `itemCap` rows (receivedAt DESC, id ASC — the
+   * Count cap: keep the newest `itemCap` rows (receivedAt DESC, id ASC, the
    * same order listItems() uses), delete the rest. Returns rows removed.
    */
   private enforceItemCap(): number {
@@ -266,7 +266,7 @@ export class InboxCursorStore {
     if (items.length === 0) return 0;
     let inserted = 0;
     // Only the ids in THIS batch can collide, so probe for exactly those rather
-    // than loading the whole table — bounds the lookup to the poll size instead
+    // than loading the whole table, bounds the lookup to the poll size instead
     // of growing O(n) with the (unbounded) feed.
     const batchIds = [...new Set(items.map((i) => i.id))];
     const placeholders = batchIds.map(() => '?').join(', ');
@@ -364,7 +364,7 @@ export class InboxCursorStore {
     if (query.after && Number.isFinite(query.after.receivedAt)) {
       // Strictly after the cursor row in (receivedAt DESC, id ASC) order: an
       // older timestamp, or the same timestamp with a higher id. Both halves
-      // are needed — several items can share a receivedAt, and comparing on
+      // are needed, several items can share a receivedAt, and comparing on
       // the timestamp alone would drop every one of its ties.
       clauses.push('(receivedAt < ? OR (receivedAt = ? AND id > ?))');
       const at = Math.floor(query.after.receivedAt);

package/src/daemon/handlers/inbox/index.ts

@@ -4,7 +4,7 @@
 //
 // The SDK already declares the method id, input schema, output schema, scopes
 // (read:channels) and HTTP binding (GET /api/channels/inbox). This module does
-// NOT re-declare any of that — it looks the descriptor up via the catalog and
+// NOT re-declare any of that, it looks the descriptor up via the catalog and
 // attaches an implementation with `registerCatalogHandler` ({ replace: true }).
 //
 // register(ctx, routing) =>
@@ -17,7 +17,7 @@
 //   6. returns an Unregister that detaches the handler, stops the poller, and
 //      closes the store.
 //
-// The handler composes the answer in ./aggregator.ts — the merged, paginated
+// The handler composes the answer in ./aggregator.ts, the merged, paginated
 // page plus every provider's standing. Read that file's header for WHY the
 // answer comes from the synced mirror rather than a fresh remote fetch. The
 // redacted `fromDigest` is the only sender value emitted (as `from`); raw
@@ -78,13 +78,13 @@ export interface RegisterInboxOptions {
    * relies on.
    *
    * The READ path is never gated. `channels.inbox.list` serves the persisted
-   * feed on every node — a node that is not fetching still answers questions
+   * feed on every node, a node that is not fetching still answers questions
    * about what has already arrived.
    *
    * Called once PER PROVIDER, with that provider's id and a control that
    * starts and stops only its loop. Each inbox account is its own surface in
    * the LAN election, so the machine reading the work Slack account need not
-   * be the machine reading the mailbox — and handing one account over must not
+   * be the machine reading the mailbox, and handing one account over must not
    * take the others down with it.
    */
   gatePolling?: (providerId: string, control: InboxPollingControl) => void;
@@ -132,7 +132,7 @@ export function registerInboxMethods(
   };
   const adapters = buildAdapters(adapterContext);
   // Retention runs inside the store (age TTL + count cap, at init and then on a
-  // timer). Both hooks carry COUNTS ONLY — no sender ids, subjects or bodies.
+  // timer). Both hooks carry COUNTS ONLY, no sender ids, subjects or bodies.
   const store = new InboxCursorStore(ctx.workingDirectory, options.storeFileName, {
     onSweep: (summary) => {
       ctx.logger.info('inbox retention sweep reclaimed items', {
@@ -150,7 +150,7 @@ export function registerInboxMethods(
   const gated = options.gatePolling !== undefined;
 
   // Async bootstrap: init store, and (ungated) seed one poll and start loops.
-  // Failures are logged but never thrown out of register() — the handler still
+  // Failures are logged but never thrown out of register(), the handler still
   // serves the (possibly empty) persisted feed.
   const ready: Promise<void> = (async () => {
     await store.init();
@@ -169,7 +169,7 @@ export function registerInboxMethods(
   if (gate) {
     // One gate per provider, not one for the poller. Leadership is decided per
     // inbox account, so each account's loop has to be startable and stoppable
-    // on its own — otherwise handing one account to another machine would stop
+    // on its own, otherwise handing one account to another machine would stop
     // fetching for every account this node reads.
     for (const providerId of poller.providerIds()) {
       gate(providerId, {

package/src/daemon/handlers/inbox/mapping.ts

@@ -54,7 +54,7 @@ const PREFIXED_KEY_RE =
 const KV_SECRET_RE =
   /\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|secret|token|password|passwd|pwd|authorization|auth)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[A-Za-z0-9._~+/=-]{6,})/gi;
 // Generic high-entropy opaque blobs (>=24 chars of base64url/hex) not already
-// caught above — catches raw API keys pasted without a recognizable prefix.
+// caught above, catches raw API keys pasted without a recognizable prefix.
 const OPAQUE_SECRET_RE = /\b[A-Za-z0-9_-]{24,}\b/g;
 
 /**
@@ -169,7 +169,7 @@ export function stripMarkup(input: string): string {
   return decodeEntities(text);
 }
 
-/** Collapse whitespace and trim — keeps previews single-line and tidy. */
+/** Collapse whitespace and trim, keeps previews single-line and tidy. */
 export function normalizeWhitespace(input: string): string {
   return input.replace(/\s+/g, ' ').trim();
 }

package/src/daemon/handlers/inbox/poller.ts

@@ -68,7 +68,7 @@ export class InboundPoller {
   private readonly inFlight = new Set<string>();
   private started = false;
   /**
-   * Set by stop(), which the surface teardown calls and nothing else — unlike
+   * Set by stop(), which the surface teardown calls and nothing else, unlike
    * stopProvider(), which a leadership handover uses and which must stay
    * resumable. Once the surface is released no interval may be armed again,
    * including by work that was already in flight: registerInboxMethods() starts
@@ -85,7 +85,7 @@ export class InboundPoller {
     this.setIntervalImpl = options.setIntervalImpl ?? setInterval;
     this.clearIntervalImpl = options.clearIntervalImpl ?? clearInterval;
     for (const id of this.adapters.keys()) {
-      // `polled: false` until a poll actually completes — see ProviderStatus.
+      // `polled: false` until a poll actually completes, see ProviderStatus.
       this.statuses.set(id, { id, state: 'empty', itemCount: 0, polled: false });
     }
   }
@@ -121,8 +121,8 @@ export class InboundPoller {
   /**
    * Stop ONE provider's interval loop. Idempotent.
    *
-   * Synchronous underneath — clearing the interval means no further tick can
-   * be scheduled — which is what lets the RESIGN that follows a handoff be an
+   * Synchronous underneath, clearing the interval means no further tick can
+   * be scheduled, which is what lets the RESIGN that follows a handoff be an
    * honest claim that this node has stopped reading that account.
    */
   stopProvider(id: string): void {
@@ -195,7 +195,7 @@ export class InboundPoller {
       const message = summarizeError(error);
       this.logger.warn('inbound poll failed', { provider: id, error: message });
       // A THROW rather than an honest 'unavailable' result. The adapter got far
-      // enough to run, so the credentials are not the thing that failed —
+      // enough to run, so the credentials are not the thing that failed,
       // reporting it as configured is what keeps this out of the
       // "you never set this up" bucket.
       this.setStatus(id, {

package/src/daemon/handlers/inbox/provider-adapter.ts

@@ -4,11 +4,11 @@
 // Each adapter owns ONE provider (slack, discord, email, ...). The poller calls
 // adapter.poll() on a cadence, dedups by item.id, and persists into the cursor
 // store. Adapters resolve credentials ONLY through the daemon credential store
-// and NEVER return raw sender ids or unredacted bodies — mapping/redaction is
+// and NEVER return raw sender ids or unredacted bodies, mapping/redaction is
 // the adapter's responsibility (see mapping helpers in `./mapping.ts`).
 //
 // CRITICAL: when a credential is missing/misconfigured an adapter returns
-// state 'unavailable' WITH an error string. It is NEVER silently omitted — the
+// state 'unavailable' WITH an error string. It is NEVER silently omitted, the
 // caller must be able to distinguish "configured-but-empty" from "not wired".
 // ---------------------------------------------------------------------------
 
@@ -16,7 +16,7 @@ import type { DaemonCredentialStore } from '../credentials.ts';
 import type { HandlerLogger } from '../context.ts';
 
 /**
- * Daemon-internal inbound item. This is NOT the SDK wire shape — the inbox
+ * Daemon-internal inbound item. This is NOT the SDK wire shape, the inbox
  * surface maps it onto the SDK `CHANNEL_INBOX_ITEM_SCHEMA` shape
  * (`from`/`subject`/`bodyPreview`/...) before returning. `fromDigest` is the
  * redacted sender (the only sender value that ever leaves the daemon).
@@ -27,7 +27,7 @@ export interface InboundChannelItem {
   provider: string;
   kind: 'dm' | 'thread' | 'mention' | 'reaction';
   /**
-   * sha256First(senderExternalId, 16) — NEVER the raw id. 16 hex chars == the
+   * sha256First(senderExternalId, 16), NEVER the raw id. 16 hex chars == the
    * first 8 bytes of the SHA-256 digest.
    */
   fromDigest: string;
@@ -61,9 +61,9 @@ export interface ProviderPollResult {
    * is an outage hiding items that exist, and `channels.inbox.list` reports
    * them as different states because a caller acts on them differently.
    *
-   * `false` — no credential (or an unusable one), so nothing was even asked.
-   * `true`  — credentials resolved; whatever happened next happened WITH them.
-   * absent  — the adapter could not find out (the credential store itself
+   * `false`, no credential (or an unusable one), so nothing was even asked.
+   * `true` , credentials resolved; whatever happened next happened WITH them.
+   * absent , the adapter could not find out (the credential store itself
    *           failed), which is neither claim and is reported as neither.
    */
   configured?: boolean;
@@ -108,7 +108,7 @@ export interface InboundProviderAdapter {
    */
   readonly pollIntervalMs: number;
   /**
-   * Pull recent DMs/threads/mentions. MUST resolve (never reject) — failures
+   * Pull recent DMs/threads/mentions. MUST resolve (never reject), failures
    * are reported via state:'unavailable' + error so one bad provider cannot
    * crash the aggregate feed.
    */

package/src/daemon/handlers/inbox/providers/discord.ts

@@ -5,10 +5,10 @@
 // Discord Gateway for DM polling. The Gateway is a persistent websocket push
 // transport and cannot be driven by the inbound poller, whose contract is a
 // stateless, cadence-driven adapter.poll() that MUST resolve each call (see
-// provider-adapter.ts) — a long-lived socket the poller neither owns nor
+// provider-adapter.ts), a long-lived socket the poller neither owns nor
 // supervises is out of scope for that contract. We therefore satisfy the
 // DM-polling goal over Discord's supported request/response surface, the REST
-// API — the same DM data the Gateway streams, fetched on the poll cadence and
+// API, the same DM data the Gateway streams, fetched on the poll cadence and
 // paged so a busy DM is never truncated:
 //   GET /users/@me/channels        -> list DM channels the bot participates in
 //   GET /channels/{id}/messages    -> recent messages per DM channel (paged via
@@ -66,7 +66,7 @@ interface DiscordMessage {
 
 /**
  * Classify a Discord message into the InboundChannelItem `kind`.
- *   - reaction: someone reacted to OUR OWN message — a genuine inbound reaction
+ *   - reaction: someone reacted to OUR OWN message, a genuine inbound reaction
  *               event. Requires the message to be authored by us (its author id
  *               is selfId) AND to carry a non-empty reactions[]. A message
  *               authored by someone else that merely carries reactions[] is a
@@ -244,7 +244,7 @@ function msToSnowflake(ms: number): string {
 }
 
 /**
- * The provider is wired up but this attempt failed — an outage, a refusal, a
+ * The provider is wired up but this attempt failed, an outage, a refusal, a
  * bad response. Items that exist are missing from the feed, which is what
  * `configured: true` here tells the aggregator to report as a partial answer
  * rather than as an empty one.
@@ -255,7 +255,7 @@ function failed(error: string): ProviderPollResult {
 
 /**
  * Nothing to poll with: no credential, or an unusable one. Normal on a fresh
- * install, and deliberately NOT a partial answer — nothing is missing from a
+ * install, and deliberately NOT a partial answer, nothing is missing from a
  * provider nobody asked us to read.
  */
 function notConfigured(error: string): ProviderPollResult {
@@ -264,7 +264,7 @@ function notConfigured(error: string): ProviderPollResult {
 
 /**
  * The credential store itself failed, so we do not know whether this provider
- * is configured. Neither claim is made — reporting a guess here is how a
+ * is configured. Neither claim is made, reporting a guess here is how a
  * transient store fault would get read as "you never set this up".
  */
 function unavailable(error: string): ProviderPollResult {

package/src/daemon/handlers/inbox/providers/email.ts

@@ -144,7 +144,7 @@ function normalizeAddress(from: string): string {
 }
 
 /**
- * The provider is wired up but this attempt failed — an outage, a refusal, a
+ * The provider is wired up but this attempt failed, an outage, a refusal, a
  * bad response. Items that exist are missing from the feed, which is what
  * `configured: true` here tells the aggregator to report as a partial answer
  * rather than as an empty one.
@@ -155,7 +155,7 @@ function failed(error: string): ProviderPollResult {
 
 /**
  * Nothing to poll with: no credential, or an unusable one. Normal on a fresh
- * install, and deliberately NOT a partial answer — nothing is missing from a
+ * install, and deliberately NOT a partial answer, nothing is missing from a
  * provider nobody asked us to read.
  */
 function notConfigured(error: string): ProviderPollResult {
@@ -164,7 +164,7 @@ function notConfigured(error: string): ProviderPollResult {
 
 /**
  * The credential store itself failed, so we do not know whether this provider
- * is configured. Neither claim is made — reporting a guess here is how a
+ * is configured. Neither claim is made, reporting a guess here is how a
  * transient store fault would get read as "you never set this up".
  */
 function unavailable(error: string): ProviderPollResult {

package/src/daemon/handlers/inbox/providers/imap-client.ts

@@ -3,7 +3,7 @@
 //
 // Implements exactly what the inbound poller needs:
 //   LOGIN, SELECT, UID SEARCH (SINCE / ALL), UID FETCH (ENVELOPE + body peek),
-//   LOGOUT. No external npm dependency — uses node:tls (Bun-compatible).
+//   LOGOUT. No external npm dependency, uses node:tls (Bun-compatible).
 //
 // This is intentionally conservative: line-buffered tagged-command protocol,
 // per-command timeout, and a hard cap on response size to avoid unbounded

package/src/daemon/handlers/inbox/providers/slack.ts

@@ -76,7 +76,7 @@ interface SlackHistoryResponse {
 
 /**
  * Classify a Slack message into the InboundChannelItem `kind`.
- *   - reaction: someone reacted to OUR OWN message — a genuine inbound reaction
+ *   - reaction: someone reacted to OUR OWN message, a genuine inbound reaction
  *               event. Requires the message to be authored by us (its user id
  *               is selfUserId) AND to carry a non-empty reactions[]. A message
  *               authored by someone else that merely carries reactions[] is a
@@ -255,7 +255,7 @@ export function createSlackAdapter(ctx: AdapterContext): InboundProviderAdapter
 }
 
 /**
- * The provider is wired up but this attempt failed — an outage, a refusal, a
+ * The provider is wired up but this attempt failed, an outage, a refusal, a
  * bad response. Items that exist are missing from the feed, which is what
  * `configured: true` here tells the aggregator to report as a partial answer
  * rather than as an empty one.
@@ -266,7 +266,7 @@ function failed(error: string): ProviderPollResult {
 
 /**
  * Nothing to poll with: no credential, or an unusable one. Normal on a fresh
- * install, and deliberately NOT a partial answer — nothing is missing from a
+ * install, and deliberately NOT a partial answer, nothing is missing from a
  * provider nobody asked us to read.
  */
 function notConfigured(error: string): ProviderPollResult {
@@ -275,7 +275,7 @@ function notConfigured(error: string): ProviderPollResult {
 
 /**
  * The credential store itself failed, so we do not know whether this provider
- * is configured. Neither claim is made — reporting a guess here is how a
+ * is configured. Neither claim is made, reporting a guess here is how a
  * transient store fault would get read as "you never set this up".
  */
 function unavailable(error: string): ProviderPollResult {

package/src/daemon/handlers/index.ts

@@ -1,7 +1,7 @@
 /**
- * Composition root for the daemon handler layer — the only module that
+ * Composition root for the daemon handler layer, the only module that
  * `src/runtime/services.ts` imports. It assembles every surface (routing,
- * inbox+triage, drafts, calendar, email, remote) onto the SDK gateway catalog
+ * inbox+triage, drafts, payments, remote) onto the SDK gateway catalog
  * and returns a single teardown plus the cross-surface handles the runtime
  * needs (routing resolver, the remote `DistributedRuntimeRouteService` the SDK
  * facade injects, and the `remote.peers.invoke` dispatch adapter).
@@ -46,17 +46,26 @@ export interface DaemonHandlerSurfaces {
  * attaches handlers to the SDK catalog via `registerCatalogHandler(s)`.
  *
  * Order of composition (and reverse teardown) is enforced by
- * `registerDaemonHandlers`: routing → inbox(+triage) → drafts → calendar →
- * email → remote.
+ * `registerDaemonHandlers`: routing → inbox(+triage) → drafts → payments →
+ * remote.
  */
 export interface DaemonHandlerSurfaceProviders {
-  /** channels.routing.* — returns the resolver consumed by the inbox surface. */
+  /** channels.routing.*, returns the resolver consumed by the inbox surface. */
   readonly registerRouting: (ctx: HandlerContext) => RoutingRegistration;
   /** channels.inbox.list (triage-decorated) + inbox.triage.* (daemon-internal). */
   readonly registerInbox: (ctx: HandlerContext, routing: RoutingRegistration) => Unregister;
   /** channels.drafts.* */
   readonly registerDrafts: SurfaceRegister;
-  /** remote.peers.* — supplies the host DistributedRuntimeRouteService + dispatch adapter. */
+  /**
+   * payments.budget.status / cards.* / purchases.list / checkout.begin / checkout.fillCard.
+   *
+   * Its stores need a shell-path resolver and a scoped secret writer, neither of
+   * which is on `HandlerContext`, so the composition root builds them and hands
+   * this provider the closed-over registration; the provider signature is the
+   * ordinary one so teardown ordering stays uniform across every surface.
+   */
+  readonly registerPayments: SurfaceRegister;
+  /** remote.peers.*, supplies the host DistributedRuntimeRouteService + dispatch adapter. */
   readonly registerRemote: (ctx: HandlerContext) => RemoteSurfaceRegistration;
 }
 
@@ -78,12 +87,13 @@ export function registerDaemonHandlers(
 
   teardowns.push(providers.registerInbox(ctx, routing));
   teardowns.push(providers.registerDrafts(ctx));
+  teardowns.push(providers.registerPayments(ctx));
   // calendar.* and email.* are NOT registered here any more. Both are served
   // by the SDK (control-plane/routes/{calendar,email}.ts over the platform
   // CalDAV/Google and IMAP/SMTP implementations), registered through
   // registerGatewayVerbGroups in runtime/services.ts. This product used to
   // carry its own handlers for the same descriptor ids and, registering later,
-  // won — two implementations behind one path, which is the drift the hoist
+  // won, two implementations behind one path, which is the drift the hoist
   // exists to end.
 
   const remote = providers.registerRemote(ctx);
@@ -91,7 +101,7 @@ export function registerDaemonHandlers(
 
   // Idempotent: teardown is reachable from more than one shutdown path now that
   // the runtime disposal scope owns it, and the surfaces underneath are not all
-  // safe to unwind twice — the inbox surface closes a SQLite handle, which a
+  // safe to unwind twice, the inbox surface closes a SQLite handle, which a
   // second pass would close again inside a floating promise (an unhandled
   // rejection, not a caught one). Running once is also simply the honest
   // meaning of "release these surfaces".

package/src/daemon/handlers/payments/address-store.ts

@@ -0,0 +1,54 @@
+/**
+ * address-store.ts, the stored shipping and billing addresses, read from
+ * config.
+ *
+ * The SDK's `platform/config/schema-domain-payments.ts` already declares flat
+ * `payments.shippingAddress.*` / `payments.billingAddress.*` keys (name,
+ * line1, line2, city, region, postalCode, country each), settable through the
+ * owner profile and the settings surfaces; address.ts's own header names the
+ * defect this closes: "nothing in the checkout path read either." This is
+ * that read path, the daemon-owned counterpart to `DaemonCardStore` for the
+ * OTHER thing a checkout needs supplied rather than typed by the model.
+ *
+ * A field that is present but blank reads as absent (`''` is not a value any
+ * of these fields can honestly hold), so a half-set address is reported the
+ * same way a wholly-unset one is: `AddressStore.read` returns the address with
+ * whatever is there, and `checkAddress` (address.ts) is what decides whether
+ * that is complete enough to ship to, exactly as it already does for the SDK's
+ * own test doubles. Nothing here validates completeness; this module only
+ * reads what config holds.
+ */
+import type { AddressKind, AddressStore, PostalAddress, PaymentsConfigReader } from '@pellux/goodvibes-sdk/platform/payments';
+
+function readAddressField(config: PaymentsConfigReader, kind: AddressKind, field: string): string {
+  const value = config.get(`payments.${kind}Address.${field}`);
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** Every field blank means "nothing stored", read back as `null` rather than an all-empty address. */
+function isEntirelyBlank(address: PostalAddress): boolean {
+  return address.name === ''
+    && address.line1 === ''
+    && address.line2 === ''
+    && address.city === ''
+    && address.region === ''
+    && address.postalCode === ''
+    && address.country === '';
+}
+
+export function configBackedAddressStore(config: PaymentsConfigReader): AddressStore {
+  return {
+    async read(kind: AddressKind): Promise<PostalAddress | null> {
+      const address: PostalAddress = {
+        name: readAddressField(config, kind, 'name'),
+        line1: readAddressField(config, kind, 'line1'),
+        line2: readAddressField(config, kind, 'line2'),
+        city: readAddressField(config, kind, 'city'),
+        region: readAddressField(config, kind, 'region'),
+        postalCode: readAddressField(config, kind, 'postalCode'),
+        country: readAddressField(config, kind, 'country'),
+      };
+      return isEntirelyBlank(address) ? null : address;
+    },
+  };
+}