@pellux/goodvibes-daemon 1.28.20 → 1.28.22

package/src/daemon/handlers/payments/checkout-journal-store.ts

@@ -0,0 +1,162 @@
+/**
+ * checkout-journal-store.ts, the in-flight checkout journal, durable across a
+ * restart.
+ *
+ * ── The defect this closes ────────────────────────────────────────────────
+ *
+ * The composition used to hand `PaymentsGatewayServiceImpl` the SDK's own
+ * `MemoryCheckoutJournal`, documented "durable across nothing". The phase
+ * ladder in checkout-registry.ts exists for exactly one ambiguous moment: a
+ * crash between the `submit-pending` flush and the merchant's response. With
+ * an in-memory journal that flush kept nothing, so a restart could never say
+ * "this purchase may already have been submitted, do not resubmit it". This
+ * file is the durable journal that record was waiting for.
+ *
+ * ── The contract this implements ──────────────────────────────────────────
+ *
+ * The SDK's `CheckoutJournal` (checkout-registry.ts): `put` must not return
+ * until the record would survive a power cut, `remove` drops one by
+ * purchaseId, `list` returns what is held. `put` here writes through
+ * `atomicWriteFileSync` (a synchronous rename-into-place) before resolving,
+ * which is the flush the `submit-pending` guarantee rides on; a `put` whose
+ * write fails THROWS, because a journal that reports durable-and-was-not
+ * turns that guarantee into a comment.
+ *
+ * `remove` is the one deliberate asymmetry: its write failure is logged and
+ * swallowed rather than thrown. By the time `remove` runs the checkout is
+ * finished or abandoned; failing the caller would turn a completed purchase's
+ * report into an error over a cleanup write, and the stale record it leaves
+ * on disk fails in the safe direction, a restart discloses a checkout that
+ * needs checking rather than forgetting one that does. The in-memory removal
+ * stands either way, and the next successful `put`/`remove` rewrites the file
+ * without the stale record.
+ *
+ * ── Unknown fields ride along untouched ───────────────────────────────────
+ *
+ * Records are persisted and reloaded as the objects they arrive as, not
+ * projected through this module's idea of the record shape. Only
+ * `purchaseId` (the removal key) is checked at load; every other field,
+ * including fields added by an SDK this build has never seen, round-trips
+ * byte-for-byte. The repin that teaches
+ * the SDK to recover these records must find everything its writer put here,
+ * not everything this file knew to keep.
+ *
+ * ── Corruption is a warning, not a crash ──────────────────────────────────
+ *
+ * Same conventions as `DurableBudgetLedger` (budget-store.ts): a missing file
+ * starts empty silently; a file that exists but cannot be parsed or does not
+ * hold this shape is logged as a warning naming the file, and the journal
+ * starts empty rather than taking the daemon down. Entries without a string
+ * `purchaseId` are dropped with a warning, since nothing could ever remove
+ * them.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { atomicWriteFileSync } from '@pellux/goodvibes-sdk/platform/config';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { CheckoutJournal, InFlightCheckout } from '@pellux/goodvibes-sdk/platform/payments';
+
+const JOURNAL_FILE_VERSION = 1;
+
+interface JournalFile {
+  readonly version: number;
+  readonly records: readonly Record<string, unknown>[];
+}
+
+/** The two fields this module actually reads; everything else is opaque cargo. */
+function hasJournalKeys(value: unknown): value is Record<string, unknown> & { purchaseId: string } {
+  return typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && typeof (value as Record<string, unknown>)['purchaseId'] === 'string';
+}
+
+/** Read the persisted records, keyed by purchaseId, or empty for "start empty". */
+function loadInitialRecords(filePath: string): Map<string, Record<string, unknown>> {
+  const records = new Map<string, Record<string, unknown>>();
+  if (!existsSync(filePath)) return records;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    logger.warn(
+      'Checkout journal file could not be read; starting with no in-flight checkouts rather than guessing. '
+      + 'If a purchase was mid-submit when this daemon last stopped, check that merchant\'s order history by hand.',
+      { filePath, error: error instanceof Error ? error.message : String(error) },
+    );
+    return records;
+  }
+  if (
+    typeof parsed !== 'object'
+    || parsed === null
+    || !Array.isArray((parsed as Partial<JournalFile>).records)
+  ) {
+    logger.warn(
+      'Checkout journal file does not hold the expected shape; starting with no in-flight checkouts rather than guessing.',
+      { filePath },
+    );
+    return records;
+  }
+  const rows = (parsed as JournalFile).records;
+  for (const row of rows) {
+    if (hasJournalKeys(row)) {
+      records.set(row.purchaseId, row);
+    }
+  }
+  if (records.size !== rows.length) {
+    logger.warn(
+      'Checkout journal file held entries with no purchaseId; those entries were dropped rather than trusted, '
+      + 'since nothing could ever remove them.',
+      { filePath },
+    );
+  }
+  return records;
+}
+
+/**
+ * The durable `CheckoutJournal` this daemon composes. See the module header
+ * for the contract and the conventions.
+ */
+export class DurableCheckoutJournal implements CheckoutJournal {
+  private readonly records: Map<string, Record<string, unknown>>;
+
+  constructor(private readonly filePath: string) {
+    this.records = loadInitialRecords(filePath);
+  }
+
+  /** Durable before it resolves; throws when the write does not land. */
+  async put(record: InFlightCheckout): Promise<void> {
+    const previous = this.records.get(record.purchaseId);
+    this.records.set(record.purchaseId, record as unknown as Record<string, unknown>);
+    try {
+      this.persist();
+    } catch (error) {
+      if (previous === undefined) this.records.delete(record.purchaseId);
+      else this.records.set(record.purchaseId, previous);
+      throw error;
+    }
+  }
+
+  /** Removes in memory always; a failed cleanup write is logged, never thrown. See the header. */
+  async remove(purchaseId: string): Promise<void> {
+    if (!this.records.delete(purchaseId)) return;
+    try {
+      this.persist();
+    } catch (error) {
+      logger.warn(
+        'Checkout journal could not be rewritten after removing a finished checkout. The stale record stays on '
+        + 'disk until the next journal write lands; at worst a restart reports a checkout that needs checking '
+        + 'when it was already complete, never the reverse.',
+        { filePath: this.filePath, purchaseId, error: error instanceof Error ? error.message : String(error) },
+      );
+    }
+  }
+
+  async list(): Promise<readonly InFlightCheckout[]> {
+    return [...this.records.values()] as unknown as readonly InFlightCheckout[];
+  }
+
+  private persist(): void {
+    const contents: JournalFile = { version: JOURNAL_FILE_VERSION, records: [...this.records.values()] };
+    atomicWriteFileSync(this.filePath, `${JSON.stringify(contents, null, 2)}\n`, { mode: 0o600, mkdirp: true });
+  }
+}

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

@@ -24,9 +24,22 @@ export type {
 export { DaemonPurchaseLedger, MAX_PURCHASE_LIST_LIMIT } from './purchase-ledger.ts';
 export type { DaemonPurchaseLedgerOptions, PurchaseListQuery, StoredPurchase } from './purchase-ledger.ts';
 
+export { DurableBudgetLedger } from './budget-store.ts';
+
+export { DaemonApprovalStore } from './approval-store.ts';
+export type { ApprovalTakeHit, ApprovalTakeMiss } from './approval-store.ts';
+
+export { DurableCheckoutJournal } from './checkout-journal-store.ts';
+
+export { CHECKOUT_APPROVAL_ACTION, checkoutApprovalContent } from './checkout-handlers.ts';
+
+export { configBackedAddressStore } from './address-store.ts';
+export { channelBackedPaymentNotifier } from './notifier.ts';
+export { createProviderBackedMerchantJudgeModel } from './merchant-judge.ts';
+
 export {
   ATTACHED_PAYMENTS_METHOD_IDS,
   UNATTACHED_PAYMENTS_METHOD_IDS,
   registerPaymentsMethods,
 } from './register.ts';
-export type { PaymentsHandlerDeps } from './register.ts';
+export type { CheckoutComposition, PaymentsHandlerDeps } from './register.ts';

package/src/daemon/handlers/payments/merchant-judge.ts

@@ -0,0 +1,57 @@
+/**
+ * merchant-judge.ts, the merchant-recourse judgement, answered by this
+ * daemon's own configured model.
+ *
+ * `createModelMerchantJudge` (platform/payments) wants a `MerchantJudgeModel`,
+ * one method, `chat(task, prompt, options)`. This adapts the daemon's
+ * `ProviderRegistry` to that shape, the same pattern
+ * `createProviderBackedCheckinJudge` (platform/checkin) already uses for the
+ * proactive check-in judge: resolve the currently configured model, ask its
+ * provider, and treat any failure as "no judgement available" rather than as a
+ * thrown error, because `createModelMerchantJudge` already reads a null/failed
+ * chat as an honest "I could not judge this merchant" verdict (unqualified,
+ * unconfident), never as a reason to fail the purchase in some OTHER way.
+ */
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import type { MerchantJudgeModel } from '@pellux/goodvibes-sdk/platform/payments';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+
+/** How long the merchant judge waits for the model before giving up. */
+const MERCHANT_JUDGE_TIMEOUT_MS = 20_000;
+
+export function createProviderBackedMerchantJudgeModel(
+  providerRegistry: Pick<ProviderRegistry, 'getCurrentModel' | 'getForModel'>,
+): MerchantJudgeModel {
+  return {
+    async chat(task, prompt, options) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), MERCHANT_JUDGE_TIMEOUT_MS);
+      timer.unref?.();
+      try {
+        const current = providerRegistry.getCurrentModel();
+        const provider = providerRegistry.getForModel(current.registryKey, current.provider);
+        const response = await provider.chat({
+          model: current.id,
+          messages: [{ role: 'user', content: prompt }],
+          ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),
+          ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+          reasoningEffort: 'low',
+          signal: controller.signal,
+        });
+        return response.content ?? null;
+      } catch (error) {
+        // `createModelMerchantJudge` treats a null answer as "I could not judge
+        // this merchant", the safe direction (see merchant-judge-model.ts's
+        // header: an unjudgeable domain must never make spending MORE
+        // automatic). The task name rides along only for the operator log.
+        logger.warn('Merchant judge model call failed; the purchase proceeds as unjudged', {
+          task,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}

package/src/daemon/handlers/payments/notifier.ts

@@ -0,0 +1,112 @@
+/**
+ * notifier.ts, sending a purchase notice over this daemon's channels.
+ *
+ * `createChannelPaymentNotifier` (platform/payments/notice-delivery.ts) wants
+ * a router, a target per configured channel, and a `PaymentReplySource`. The
+ * first two are real: `payments.notifyChannels` names which
+ * `CommandAuthorityChannel`s to notify, and delivery goes out over this
+ * daemon's own `ChannelDeliveryRouter`, the SAME router every other channel
+ * send in this daemon uses (see services.ts's comment on why there is exactly
+ * one).
+ *
+ * ── What is deliberately NOT wired in this pass ───────────────────────────
+ *
+ * `PaymentReplySource.waitForAnswer` always resolves `null`. That is not a
+ * stub standing in for something broken, it is the documented meaning of
+ * SILENCE (platform/payments/windows.ts): an approval window's silence DENIES
+ * and a veto window's silence PROCEEDS, both already correct, tested behaviors
+ * the decision layer exercises with no reply source at all. What is missing is
+ * the OTHER path, an inbound reply on a channel resolving the window before its
+ * deadline, "approve"/"yes"/"stop" arriving back from wherever the notice went.
+ * Building that needs an inbound-message correlation path this daemon does not
+ * have yet (there is no `payments.*` counterpart to
+ * `tryResolveApprovalReplyFromChannel`/`tryResolveWorkProposalReplyFromChannel`
+ * in `platform/daemon/surface-actions.ts`, which resolve DIFFERENT kinds of
+ * reply against a DIFFERENT store). Wiring it is a distinct, sizeable piece of
+ * work and is left for a later pass, exactly like `describeSubmission` above
+ * it; every purchase in the meantime is decided by budget and by the windows'
+ * own silence rules, with the notice actually reaching the owner's configured
+ * channels.
+ */
+import type { ChannelDeliveryRouter, ChannelDeliveryTarget } from '@pellux/goodvibes-sdk/platform/channels';
+import {
+  createChannelPaymentNotifier,
+  parseCommandAuthorityChannel,
+  readNotifyChannels,
+} from '@pellux/goodvibes-sdk/platform/payments';
+import type {
+  PaymentNotifier,
+  PaymentNoticeRouter,
+  PaymentNoticeTarget,
+  PaymentReplySource,
+  PaymentsConfigReader,
+} from '@pellux/goodvibes-sdk/platform/payments';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+
+const PAYMENTS_NOTICE_JOB_ID = 'payments-notice';
+
+/**
+ * The channel name (`payments.notifyChannels` entry) turned into the router's
+ * own addressing shape. `parseChannelDeliveryTarget` (platform/channels'
+ * internal delivery/types.ts) is not on the published subpath, so this mirrors
+ * its `surface` construction for the plain channel names `readNotifyChannels`
+ * produces (no `kind:address` suffix, `CommandAuthorityChannel` carries none).
+ */
+function surfaceTarget(surfaceKind: string): ChannelDeliveryTarget {
+  return { kind: 'surface', surfaceKind: surfaceKind as ChannelDeliveryTarget['surfaceKind'] };
+}
+
+/** Adapts this daemon's router to the notifier's narrow, opaque-`request` shape. */
+function daemonNoticeRouter(router: Pick<ChannelDeliveryRouter, 'deliver'>): PaymentNoticeRouter {
+  return {
+    deliver: async (request) => {
+      const merged = request as unknown as Record<string, unknown> & { readonly content: string };
+      return router.deliver({
+        target: merged['target'] as ChannelDeliveryTarget,
+        body: merged.content,
+        title: 'Purchase',
+        jobId: PAYMENTS_NOTICE_JOB_ID,
+        runId: `${PAYMENTS_NOTICE_JOB_ID}-${String(Date.now())}`,
+        includeLinks: false,
+      });
+    },
+  };
+}
+
+/** No live reply integration yet; see this module's header for why silence is still correct. */
+const NO_REPLIES: PaymentReplySource = {
+  async waitForAnswer() {
+    return null;
+  },
+};
+
+export function channelBackedPaymentNotifier(
+  config: PaymentsConfigReader,
+  router: Pick<ChannelDeliveryRouter, 'deliver'>,
+): PaymentNotifier {
+  const targets: PaymentNoticeTarget[] = [];
+  for (const name of readNotifyChannels(config)) {
+    const channel = parseCommandAuthorityChannel(name);
+    if (channel === null) {
+      logger.warn('payments.notifyChannels names a channel this daemon does not recognise; it will not be notified', { channel: name });
+      continue;
+    }
+    targets.push({
+      channel,
+      request: { target: surfaceTarget(name) },
+      // No backfill path is wired (see this module's header): a notice missed
+      // while the daemon was down cannot be recovered by re-reading history it
+      // never asked this router to keep.
+      backfillable: false,
+    });
+  }
+
+  return createChannelPaymentNotifier({
+    router: daemonNoticeRouter(router),
+    targets,
+    replies: NO_REPLIES,
+    onDeliveryFailure: ({ channel, reason }) => {
+      logger.warn('A payments notice could not be delivered on a configured channel', { channel, reason });
+    },
+  });
+}