@classytic/primitives 0.18.0 → 0.20.0

package/dist/outbox.mjs

@@ -26,5 +26,68 @@ var InvalidOutboxEventError = class extends Error {
 		super(`Invalid outbox event: ${reason}`);
 	}
 };
+/**
+* Durable storage contract for the transactional outbox pattern.
+*
+* **Required methods**: `save`, `getPending`, `acknowledge`.
+*
+* **Optional capabilities** — stores opt-in to richer semantics:
+*
+*   - `claimPending` — lease-based work claim for multi-worker relay
+*   - `fail` — failure tracking with retry scheduling and dead-letter
+*   - `getDeadLettered` — typed DLQ replay surface
+*   - `purge` — acknowledged event cleanup
+*
+* Arc's runtime detects capabilities at runtime and degrades gracefully for
+* legacy stores that only implement the required methods.
+*
+* ## Required semantics
+*
+* Implementations MUST honor these contracts — arc's relay depends on them
+* for correctness of at-least-once delivery:
+*
+* 1. **`save` must reject invalid events.** If `event.type` or `event.meta.id`
+*    is missing/empty, throw — do not persist. Callers pre-validate but
+*    stores should defend against direct-save code paths.
+*
+* 2. **`claimPending` must be atomic.** Two workers calling `claimPending`
+*    concurrently must never receive the same event. SQL: `SELECT ... FOR
+*    UPDATE SKIP LOCKED`; Mongo: `findOneAndUpdate` with `{ leaseOwner:
+*    null }` in the match condition.
+*
+* 3. **`acknowledge` / `fail` must throw {@link OutboxOwnershipError} on
+*    ownership mismatch.** When `options.consumerId` is provided and does
+*    not match the current lease owner, throw — never silently no-op. The
+*    relay relies on this signal to avoid counting hijacked events as
+*    successfully relayed.
+*
+* 4. **`acknowledge` on an unknown `eventId` is a no-op.** Keeps the relay
+*    idempotent when the store has been purged or the event was manually
+*    removed. Do NOT throw `OutboxOwnershipError` in this case.
+*
+* 5. **`fail` must deterministically update lease/visibility.** On success,
+*    the event MUST become re-claimable (immediately or at `retryAt`) or
+*    transition to dead-letter. Lease owner should be cleared.
+*
+* 6. **Malformed events must never be returned by `getPending` /
+*    `claimPending`.** If the underlying storage has corrupt rows, the
+*    store is responsible for quarantining them.
+*/
+/**
+* The delivery states an outbox row can hold.
+*
+* Named HERE, in the contract, rather than in each store. It went unnamed while every
+* method took an event id and none took a state — `countByStatus` is the first member
+* that makes the vocabulary part of the interface, and two stores had already written
+* the same three strings independently by then.
+*
+* `dead_letter` is terminal until an operator calls `requeue`; it is a durable statement
+* that something is owed, not a deletion.
+*/
+const OUTBOX_STATUSES = [
+	"pending",
+	"delivered",
+	"dead_letter"
+];
 //#endregion
-export { InvalidOutboxEventError, OutboxOwnershipError };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxOwnershipError };

package/dist/payment-events.d.mts

@@ -1,5 +1,6 @@
-import { Money } from "./money.mjs";
+import { n as Money } from "./money-DPo9fLBi.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
+import { ProviderUnknownCause } from "./payment-gateway.mjs";
 
 //#region src/events/payment-events.d.ts
 /**
@@ -21,6 +22,19 @@ declare const PAYMENT_EVENT_TYPE: {
   readonly DISPUTE_WON: "payment.dispute_won";
   readonly DISPUTE_LOST: "payment.dispute_lost";
   readonly SETTLED: "payment.settled";
+  /**
+   * The provider command produced NO observable outcome — timeout, abort,
+   * network fault, or a provider that holds no record and refuses to guess.
+   *
+   * This member exists because the port contract (`ProviderCommandResult` in
+   * `/payment-gateway`) is three-valued — `confirmed | declined | unknown` —
+   * while this catalogue was two-valued. An adapter that hit the third case had
+   * nowhere to publish it, so the only shapes on the bus were SUCCEEDED and
+   * FAILED, and an unobserved outcome had to be forced into one of them.
+   * Forcing it into FAILED is the one that double-charges: it licenses a retry
+   * for a command that may already have moved money.
+   */
+  readonly UNKNOWN: "payment.unknown";
 };
 type PaymentEventType = (typeof PAYMENT_EVENT_TYPE)[keyof typeof PAYMENT_EVENT_TYPE];
 /**
@@ -30,6 +44,8 @@ type PaymentEventType = (typeof PAYMENT_EVENT_TYPE)[keyof typeof PAYMENT_EVENT_T
  * "money in flight" not "money received".
  */
 interface PaymentInitiatedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.INITIATED;
   /** Stable payment identifier owned by the emitting package. */
   paymentId: string;
   /**
@@ -57,6 +73,8 @@ interface PaymentInitiatedPayload {
  * downstream fulfilment unlocks.
  */
 interface PaymentSucceededPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.SUCCEEDED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -73,6 +91,8 @@ interface PaymentSucceededPayload {
  * overdue.
  */
 interface PaymentFailedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.FAILED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -93,6 +113,8 @@ interface PaymentFailedPayload {
  * itself (pre- or post-clearing, often due to operator error).
  */
 interface PaymentRefundedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.REFUNDED;
   paymentId: string;
   /** Refund identifier (separate from `paymentId`). */
   refundId: string;
@@ -116,6 +138,8 @@ interface PaymentRefundedPayload {
  * state.
  */
 interface PaymentReversedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.REVERSED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -136,6 +160,8 @@ interface PaymentReversedPayload {
  * ledger bridges and closes the audit loop.
  */
 interface PaymentReconciledPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.RECONCILED;
   /** Allocation identifier — NOT the payment id (a payment can have many). */
   allocationId: string;
   paymentId: string;
@@ -156,6 +182,8 @@ interface PaymentReconciledPayload {
  * "hold" from "settle"; consumers should NOT treat this as cleared funds.
  */
 interface PaymentAuthorizedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.AUTHORIZED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -173,6 +201,8 @@ interface PaymentAuthorizedPayload {
  * Pairs with {@link PaymentAuthorizedPayload} for two-phase flows.
  */
 interface PaymentCapturedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.CAPTURED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -191,6 +221,8 @@ interface PaymentCapturedPayload {
  * Authorisation hold released — uncaptured auth voided before settlement.
  */
 interface PaymentAuthVoidedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.AUTH_VOIDED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -205,6 +237,8 @@ interface PaymentAuthVoidedPayload {
  * payment. The merchant typically has a deadline to submit evidence.
  */
 interface PaymentDisputedPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.DISPUTED;
   paymentId: string;
   /** Provider's dispute / chargeback id. */
   disputeId: string;
@@ -223,6 +257,8 @@ interface PaymentDisputedPayload {
 }
 /** Dispute resolved in merchant's favour — funds restored. */
 interface PaymentDisputeWonPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.DISPUTE_WON;
   paymentId: string;
   disputeId: string;
   providerRef?: string;
@@ -234,6 +270,8 @@ interface PaymentDisputeWonPayload {
 }
 /** Dispute resolved against merchant — funds permanently lost plus fee. */
 interface PaymentDisputeLostPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.DISPUTE_LOST;
   paymentId: string;
   disputeId: string;
   providerRef?: string;
@@ -251,6 +289,8 @@ interface PaymentDisputeLostPayload {
  * reconciliation in country-aware ledger bridges.
  */
 interface PaymentSettledPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.SETTLED;
   paymentId: string;
   providerRef?: string;
   providerCode: string;
@@ -265,7 +305,95 @@ interface PaymentSettledPayload {
   occurredAt: Date;
   metadata?: Record<string, unknown>;
 }
-/** Union of all payment event payload types — convenient for exhaustive switches. */
-type PaymentEventPayload = PaymentInitiatedPayload | PaymentSucceededPayload | PaymentFailedPayload | PaymentRefundedPayload | PaymentReversedPayload | PaymentReconciledPayload | PaymentAuthorizedPayload | PaymentCapturedPayload | PaymentAuthVoidedPayload | PaymentDisputedPayload | PaymentDisputeWonPayload | PaymentDisputeLostPayload | PaymentSettledPayload;
+/**
+ * The provider command produced no observable outcome. **This is not a
+ * failure**, and it is not a success — it is the absence of an answer.
+ *
+ * The obligation's state is genuinely unknown: the capture may have landed at
+ * the gateway with the acknowledgement lost in transit. The ONLY correct
+ * reaction is to reconcile the payment's real status before acting. A blind
+ * retry is a double charge; marking it failed and releasing the order is a
+ * shipped-but-unpaid order. Both are silent.
+ *
+ * Consumers MUST NOT treat this as a terminal state. It is a prompt to go and
+ * find out, and it resolves later into `payment.succeeded` or `payment.failed`.
+ */
+interface PaymentUnknownPayload {
+  /** Discriminant — narrows {@link PaymentEventPayload}. */
+  readonly eventType: typeof PAYMENT_EVENT_TYPE.UNKNOWN;
+  paymentId: string;
+  providerRef?: string;
+  providerCode: string;
+  /** Which command went unanswered — the retry policy differs per verb. */
+  operation: 'create_intent' | 'verify' | 'authorize' | 'capture' | 'refund' | 'void';
+  /** The amount at stake, when the command carried one. */
+  amount?: Money;
+  methodKind?: PaymentMethodKind;
+  methodCode?: string;
+  /**
+   * NORMALIZED reason the outcome was not observed — mirrors
+   * `ProviderUnknownCause` from `/payment-gateway`. Never a raw vendor error
+   * string: this value is persisted and displayed, and vendor errors embed
+   * request URLs, tokens and body fragments.
+   */
+  causeCode: ProviderUnknownCause;
+  /** The idempotency key the command carried — what reconciliation asks with. */
+  idempotencyKey?: string;
+  occurredAt: Date;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Union of all payment event payload types.
+ *
+ * DISCRIMINATED on `eventType`. Before the discriminant existed,
+ * `PaymentInitiatedPayload` and `PaymentSucceededPayload` were structurally
+ * IDENTICAL — so a handler typed for "funds received" accepted "money in
+ * flight" with no error anywhere, and TypeScript could not tell them apart even
+ * in principle. Structural identity between two events that mean opposite
+ * things is precisely where a nominal tag has to carry the meaning.
+ */
+type PaymentEventPayload = PaymentInitiatedPayload | PaymentSucceededPayload | PaymentFailedPayload | PaymentRefundedPayload | PaymentReversedPayload | PaymentReconciledPayload | PaymentAuthorizedPayload | PaymentCapturedPayload | PaymentAuthVoidedPayload | PaymentDisputedPayload | PaymentDisputeWonPayload | PaymentDisputeLostPayload | PaymentSettledPayload | PaymentUnknownPayload;
+/** Event type → its payload. The lookup a typed publisher/handler pair needs. */
+interface PaymentEventPayloadMap {
+  'payment.initiated': PaymentInitiatedPayload;
+  'payment.succeeded': PaymentSucceededPayload;
+  'payment.failed': PaymentFailedPayload;
+  'payment.refunded': PaymentRefundedPayload;
+  'payment.reversed': PaymentReversedPayload;
+  'payment.reconciled': PaymentReconciledPayload;
+  'payment.authorized': PaymentAuthorizedPayload;
+  'payment.captured': PaymentCapturedPayload;
+  'payment.auth_voided': PaymentAuthVoidedPayload;
+  'payment.disputed': PaymentDisputedPayload;
+  'payment.dispute_won': PaymentDisputeWonPayload;
+  'payment.dispute_lost': PaymentDisputeLostPayload;
+  'payment.settled': PaymentSettledPayload;
+  'payment.unknown': PaymentUnknownPayload;
+}
+type Assert<T extends true> = T;
+/** Every declared event type has a payload in the map. */
+type _EveryTypeMapped = Assert<PaymentEventType extends keyof PaymentEventPayloadMap ? true : false>;
+/** The map declares no key that is not a real event type. */
+type _NoStrayMapKeys = Assert<keyof PaymentEventPayloadMap extends PaymentEventType ? true : false>;
+/** Each payload's own `eventType` literal matches the key it is filed under. */
+type _DiscriminantMatchesKey = Assert<{ [K in keyof PaymentEventPayloadMap]: PaymentEventPayloadMap[K] extends {
+  eventType: K;
+} ? true : false }[keyof PaymentEventPayloadMap] extends true ? true : false>;
+type PaymentEventContractGuards = [_EveryTypeMapped, _NoStrayMapKeys, _DiscriminantMatchesKey];
+/**
+ * Narrow a payload by event type at RUNTIME, with the compile-time narrowing
+ * to match. `if (isPaymentEvent(PAYMENT_EVENT_TYPE.SUCCEEDED, p)) { … }` —
+ * inside the branch `p` is `PaymentSucceededPayload` and cannot be an
+ * initiated payload, which is the whole point of the discriminant.
+ */
+declare function isPaymentEvent<T extends PaymentEventType>(type: T, payload: PaymentEventPayload): payload is PaymentEventPayloadMap[T];
+/**
+ * Is this payload a CLEARED-FUNDS event?
+ *
+ * The named answer to the question that used to be answerable only by
+ * structural shape — and answered wrong, because `initiated` had the same
+ * shape. `captured` counts; `initiated`, `authorized` and `unknown` do not.
+ */
+declare function isFundsReceived(payload: PaymentEventPayload): boolean;
 //#endregion
-export { PAYMENT_EVENT_TYPE, PaymentAuthVoidedPayload, PaymentAuthorizedPayload, PaymentCapturedPayload, PaymentDisputeLostPayload, PaymentDisputeWonPayload, PaymentDisputedPayload, PaymentEventPayload, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSettledPayload, PaymentSucceededPayload };
+export { PAYMENT_EVENT_TYPE, PaymentAuthVoidedPayload, PaymentAuthorizedPayload, PaymentCapturedPayload, PaymentDisputeLostPayload, PaymentDisputeWonPayload, PaymentDisputedPayload, PaymentEventContractGuards, PaymentEventPayload, PaymentEventPayloadMap, PaymentEventType, PaymentFailedPayload, PaymentInitiatedPayload, PaymentReconciledPayload, PaymentRefundedPayload, PaymentReversedPayload, PaymentSettledPayload, PaymentSucceededPayload, PaymentUnknownPayload, isFundsReceived, isPaymentEvent };

package/dist/payment-events.mjs

@@ -17,7 +17,27 @@ const PAYMENT_EVENT_TYPE = {
 	DISPUTED: "payment.disputed",
 	DISPUTE_WON: "payment.dispute_won",
 	DISPUTE_LOST: "payment.dispute_lost",
-	SETTLED: "payment.settled"
+	SETTLED: "payment.settled",
+	UNKNOWN: "payment.unknown"
 };
+/**
+* Narrow a payload by event type at RUNTIME, with the compile-time narrowing
+* to match. `if (isPaymentEvent(PAYMENT_EVENT_TYPE.SUCCEEDED, p)) { … }` —
+* inside the branch `p` is `PaymentSucceededPayload` and cannot be an
+* initiated payload, which is the whole point of the discriminant.
+*/
+function isPaymentEvent(type, payload) {
+	return payload.eventType === type;
+}
+/**
+* Is this payload a CLEARED-FUNDS event?
+*
+* The named answer to the question that used to be answerable only by
+* structural shape — and answered wrong, because `initiated` had the same
+* shape. `captured` counts; `initiated`, `authorized` and `unknown` do not.
+*/
+function isFundsReceived(payload) {
+	return payload.eventType === PAYMENT_EVENT_TYPE.SUCCEEDED || payload.eventType === PAYMENT_EVENT_TYPE.CAPTURED;
+}
 //#endregion
-export { PAYMENT_EVENT_TYPE };
+export { PAYMENT_EVENT_TYPE, isFundsReceived, isPaymentEvent };

package/dist/payment-gateway.d.mts

@@ -1,4 +1,4 @@
-import { Money } from "./money.mjs";
+import { n as Money } from "./money-DPo9fLBi.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
 
 //#region src/money/payment-gateway.d.ts
@@ -25,7 +25,7 @@ interface ProviderCapabilities {
  * Arguments to `provider.createIntent(...)`. Engine constructs this
  * from the host's checkout payload and the resolved currency. The
  * `metadata` blob is opaque pass-through — providers MAY forward it to
- * the upstream gateway (Stripe attaches it to the PaymentIntent), but
+ * the upstream gateway (Stripe attaches it to its own PaymentIntent), but
  * MUST NOT mutate or interpret it.
  */
 interface CreateIntentParams {
@@ -49,7 +49,7 @@ interface CreateIntentParams {
  * Stripe's PaymentIntent status because every other gateway maps cleanly
  * INTO this set; gateways that lack a state simply never emit it.
  */
-type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
+type ProviderIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
 /** Closed set of refund lifecycle states the engine recognises. */
 type RefundResultStatus = 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled';
 /**
@@ -58,7 +58,17 @@ type RefundResultStatus = 'pending' | 'requires_action' | 'succeeded' | 'failed'
  * `gateway` block so subsequent `verify` / webhook lookups can find
  * the row.
  */
-interface PaymentIntent {
+/**
+ * A PROVIDER-side intent reference — what the gateway calls this payment.
+ *
+ * Named `ProviderIntent`, not `PaymentIntent`, because the domain aggregate that models the
+ * customer's obligation is also called a payment intent, and one name cannot span both layers.
+ * This is the narrow thing: a gateway-scoped id, the provider's own status mapped onto our closed
+ * union, and the amount it locked in. It belongs to ONE attempt against ONE provider account.
+ *
+ * See `spine/docs/payments-architecture.md` §3.3.
+ */
+interface ProviderIntent {
   /** Unique gateway-scoped id for this intent (`pi_xxx`, `ch_xxx`, etc.). */
   id: string;
   /** Lowercase gateway name (`'stripe'`, `'razorpay'`, `'sslcommerz'`, `'bkash'`, `'manual'`). */
@@ -67,7 +77,7 @@ interface PaymentIntent {
    * Lifecycle status — closed union the engine state-machines branch on.
    * Adapters MUST map provider-native strings into this set.
    */
-  status: PaymentIntentStatus;
+  status: ProviderIntentStatus;
   /** Amount + currency that the intent locks in. */
   amount: Money;
   /**
@@ -104,7 +114,7 @@ interface PaymentResult {
   /** Lowercase gateway name. */
   provider: string;
   /**
-   * Closed status set — narrower than `PaymentIntent.status` because
+   * Closed status set — narrower than `ProviderIntent.status` because
    * verification has settled the lifecycle.
    *
    * - `'succeeded'` — payment captured, funds owed to merchant.
@@ -185,5 +195,198 @@ interface WebhookEvent {
   /** Raw provider payload — audit only. */
   raw?: unknown;
 }
+/**
+ * The contract a payment provider must satisfy — declared HERE, in primitives, so an
+ * adapter can be written against it with **no runtime dependency on the engine**.
+ *
+ * ## Why this moved
+ *
+ * `@classytic/revenue-manual` imported the abstract `PaymentProvider` CLASS from
+ * `@classytic/revenue` — a runtime value, not a type. That coupled every adapter to the
+ * engine package: an adapter could not be versioned or published independently, and the
+ * dependency ran adapter → engine while the engine also registers adapters.
+ *
+ * This is the same correction made for `OutboxStore`: primitives owns the CONTRACT, the
+ * engine adapts to it, and a kit or a third party can implement it knowing only this file.
+ *
+ * ## Extending vs implementing
+ *
+ * `revenue`'s abstract `PaymentProvider` class now *implements* this interface and stays
+ * available for the config plumbing it provides (`config`, `defaultCurrency`). Existing
+ * adapters that `extends PaymentProvider` are unaffected. New adapters should `implement
+ * PaymentProviderPort` directly and depend only on primitives.
+ *
+ * See `spine/docs/payments-architecture.md` §3.4.1 and phase 1.
+ */
+/**
+ * How reconciliation asks a provider about a specific REFUND. The refund is identified
+ * by the original `paymentId` plus the refund's `idempotencyKey` (the value the provider
+ * deduped on); `refundRef` is the gateway refund id when the engine observed one.
+ */
+interface RefundStatusQuery {
+  paymentId: string;
+  idempotencyKey: string;
+  refundRef?: string;
+}
+interface PaymentProviderPort {
+  /** Stable lowercase provider name — the registry key. */
+  readonly name: string;
+  /**
+   * Create a provider-side intent for an amount.
+   *
+   * `command` is REQUIRED, not optional. Creating an intent is side-effecting upstream: a
+   * timed-out create can leave a live intent at the gateway with no local record, and a
+   * retry without a stable idempotency key produces a SECOND one. Making the envelope
+   * mandatory is what stops an adapter quietly omitting it.
+   */
+  createIntent(params: CreateIntentParams, command: PaymentCommandContext): Promise<ProviderIntent>;
+  /**
+   * Confirm an intent actually succeeded at the provider.
+   *
+   * A provider that CANNOT know — a stateless manual provider, for instance — must not
+   * answer `succeeded`. Reporting success for something it never observed is how a
+   * reconciliation path gets a false positive.
+   */
+  verifyPayment(intentId: string, command?: PaymentCommandContext): Promise<PaymentResult>;
+  /**
+   * Current provider-side status. Same honesty requirement as `verifyPayment`.
+   *
+   * `command` is OPTIONAL here and on `verifyPayment`: both are reads, so there is nothing
+   * to make idempotent. It is accepted purely for correlation across our logs and the
+   * provider's.
+   */
+  getStatus(intentId: string, command?: PaymentCommandContext): Promise<PaymentResult>;
+  /**
+   * Reverse a payment, in full or in part.
+   *
+   * `command` is REQUIRED and carries the idempotency key. It used to be an optional field
+   * inside `options`, which made the single most dangerous operation on this port the one
+   * where deduplication was easiest to forget. Providers whose gateway supports an
+   * idempotency key MUST forward it; those without may ignore it, and the engine still
+   * guards with its own claim and a unique index.
+   */
+  refund(paymentId: string, amount: number | null | undefined, command: PaymentCommandContext, options?: {
+    reason?: string;
+  }): Promise<RefundResult>;
+  /**
+   * Current status of a REFUND (not the payment). OPTIONAL and feature-detected: only
+   * a provider that can look a refund up implements it. Reconciliation MUST use this,
+   * never `getStatus` (which reports the PAYMENT) — asking the payment about a refund
+   * misclassifies a successful charge as a successful reversal. The query carries the
+   * original `paymentId` and the refund's `idempotencyKey` (and `refundRef` when we
+   * observed one) so the provider can find the specific reversal it deduped. A provider
+   * without this cannot be auto-reconciled — the engine then RETAINS the reservation.
+   */
+  getRefundStatus?(query: RefundStatusQuery, command?: PaymentCommandContext): Promise<PaymentResult>;
+  handleWebhook(payload: unknown, headers?: Record<string, string>): Promise<WebhookEvent>;
+  /**
+   * Reject a forged webhook. Returning `true` unconditionally is only acceptable for a
+   * provider with no webhook transport at all (manual/dev).
+   */
+  verifyWebhookSignature(payload: unknown, signature: string): boolean;
+  /** Declared capabilities. Callers gate on these rather than probing by failing. */
+  getCapabilities(): ProviderCapabilities;
+}
+/**
+ * `setDefaultCurrency` is deliberately NOT on the port.
+ *
+ * A default currency is ENGINE configuration, not part of the provider execution contract,
+ * and every `Money` already carries its own currency. Requiring the mutator would make each
+ * adapter stateful and awkward to share across accounts — the same instance cannot then
+ * serve two accounts with different defaults.
+ *
+ * Adapters that want the convenience expose it and the registry feature-detects it; the
+ * rest simply read the currency off the amount they were handed.
+ */
+interface DefaultCurrencyAware {
+  setDefaultCurrency(currency: string): void;
+}
+/**
+ * The envelope every money-changing provider command carries.
+ *
+ * Idempotency used to be supplied on `refund` alone. It belongs on every command: a
+ * retried authorize or capture double-charges just as readily as a retried refund, and the
+ * retry is usually the client's, not ours.
+ *
+ * Adapters whose gateway supports an idempotency key MUST forward it. The engine still keeps
+ * its own atomic claim/result store, because not every provider offers one and a provider's
+ * word is not a guarantee we control.
+ */
+interface PaymentCommandContext {
+  /**
+   * Caller-supplied, stable across retries of the SAME logical operation. Two different
+   * operations must never share one; one operation retried must never change it.
+   */
+  idempotencyKey: string;
+  /** Correlates this attempt across our logs, the provider's, and the audit trail. */
+  requestId: string;
+  /** Our reference for the thing being paid for — order number, invoice number. */
+  merchantReference: string;
+  /**
+   * Branch / tenant scope. OPTIONAL: a revenue engine can run unscoped
+   * (single-tenant / company-global), where there is no branch id to carry —
+   * so this is absent rather than an empty or asserted string. Scoped engines
+   * always set it; consumers that require scope must check, not cast.
+   */
+  organizationId?: string;
+  /** Cancels an in-flight command (a cashier abandoning a terminal prompt, a shutdown). */
+  signal?: AbortSignal;
+}
+/** Why a provider said no. A DECISION, distinct from an unanswered question. */
+interface PaymentDecline {
+  /** Normalized reason. Adapters map their vendor's vocabulary onto this. */
+  reason: 'insufficient_funds' | 'card_declined' | 'expired' | 'invalid_details' | 'limit_exceeded' | 'duplicate' | 'not_permitted' | 'provider_error' | 'other';
+  /** The provider's own code and message, preserved verbatim for support and reconciliation. */
+  providerCode?: string;
+  providerMessage?: string;
+  /** Whether trying again could plausibly succeed. `false` for a hard decline. */
+  retryable: boolean;
+}
+/**
+ * The outcome of a provider command. **Three-valued, and the third one is the point.**
+ *
+ * A timeout is NOT a failure. When a capture request times out, the money may well have
+ * moved — we simply did not hear back. Treating that as `declined` and retrying is the
+ * canonical way to double-charge a customer, and it is invisible until reconciliation.
+ *
+ * `unknown` also covers a provider that legitimately cannot answer: a stateless manual
+ * provider asked for the status of a payment it never stored. Today's two-valued shape
+ * forces such a provider to invent an answer, and `revenue-manual` invented `succeeded`.
+ *
+ * **The only correct response to `unknown` is to reconcile status before acting** — never
+ * a blind retry.
+ */
+type ProviderCommandResult<T> = {
+  outcome: 'confirmed';
+  value: T;
+} | {
+  outcome: 'declined';
+  error: PaymentDecline;
+} | {
+  outcome: 'unknown'; /** Whatever handle we have for asking again later. */
+  providerReference?: string;
+  /**
+   * NORMALIZED reason we do not know — never a raw exception message.
+   *
+   * Vendor errors routinely embed request URLs, tokens, account identifiers and
+   * fragments of the request body. This value is persisted on the transaction, returned
+   * to callers and read by operators, so it must be safe to store and display. The raw
+   * error belongs in a redacted diagnostic log, not here.
+   */
+  causeCode?: ProviderUnknownCause;
+};
+/** Why an outcome went unobserved. Coarse on purpose — it drives handling, not diagnosis. */
+type ProviderUnknownCause = 'timeout' | 'aborted' | 'network' | 'status_unavailable' | 'unclassified';
+/**
+ * Thrown by a provider that cannot answer a status query, rather than guessing.
+ *
+ * Classified as `unknown`. The engine's correct reaction is to consult the stored record:
+ * for a manual method there is no external money-movement authority, so the record IS the
+ * authority (see `spine/docs/payments-architecture.md` §1).
+ */
+declare class ProviderStatusUnavailableError extends Error {
+  readonly providerName: string;
+  constructor(providerName: string, message?: string);
+}
 //#endregion
-export { CreateIntentParams, PaymentIntent, PaymentIntentStatus, PaymentResult, ProviderCapabilities, RefundResult, RefundResultStatus, WebhookEvent };
+export { CreateIntentParams, DefaultCurrencyAware, PaymentCommandContext, PaymentDecline, PaymentProviderPort, PaymentResult, ProviderCapabilities, ProviderCommandResult, ProviderIntent, ProviderIntentStatus, ProviderStatusUnavailableError, ProviderUnknownCause, RefundResult, RefundResultStatus, RefundStatusQuery, WebhookEvent };

package/dist/payment-gateway.mjs

@@ -1 +1,18 @@
-export {};
+//#region src/money/payment-gateway.ts
+/**
+* Thrown by a provider that cannot answer a status query, rather than guessing.
+*
+* Classified as `unknown`. The engine's correct reaction is to consult the stored record:
+* for a manual method there is no external money-movement authority, so the record IS the
+* authority (see `spine/docs/payments-architecture.md` §1).
+*/
+var ProviderStatusUnavailableError = class extends Error {
+	providerName;
+	constructor(providerName, message) {
+		super(message ?? `provider "${providerName}" cannot report status for this payment — it holds no record of it. Read the stored transaction instead of asking the provider.`);
+		this.name = "ProviderStatusUnavailableError";
+		this.providerName = providerName;
+	}
+};
+//#endregion
+export { ProviderStatusUnavailableError };