@mandateops/audit 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -181,6 +181,12 @@ export type SealedResult = Readonly<{
         reasons?: readonly unknown[];
     }>;
     record_published: boolean;
+    /**
+     * Why the run cannot pass whatever its properties say, such as
+     * `overlap_not_established` for a race the host could not show in flight
+     * together, or `capacity_exceeded` for competitors accepted past their limit.
+     */
+    reason?: string;
 }>;
 /** A deployment that may have outlived its run, and what removes it. */
 export type TeardownFailure = Readonly<{
@@ -207,12 +213,28 @@ type Credentials = Readonly<Record<ServiceRole, string>>;
  * The session protocol this SDK speaks. The host announces its own when
  * ready; the two must match, as they do for an SDK shipped with its CLI.
  */
-export declare const SESSION_PROTOCOL = 2;
+export declare const SESSION_PROTOCOL = 3;
 /** Why a host of another protocol is refused, and how to fix it. */
 export declare function protocolMismatch(announced: number | undefined): string;
 /** A sealed result, checked before anything reads it. */
 export declare function parseResult(value: unknown): SealedResult;
 export type LossMode = "cut_connection" | "hold_response" | "crash_process";
+/** What the host's gate saw of one race. */
+export type RaceReport = Readonly<{
+    parties: number;
+    /** Every party arrived and all were in flight at the backend at once. */
+    overlap_established: boolean;
+    /** Why overlap was not established, when it was not. */
+    reason?: string;
+}>;
+/** Each party's own result, and whether the race really overlapped. */
+export type RaceResult<T> = Readonly<{
+    settled: readonly PromiseSettledResult<T>[];
+    report: RaceReport;
+}>;
+/** Fewest and most parties one race holds; the host enforces the same. */
+export declare const MIN_RACE_PARTIES = 2;
+export declare const MAX_RACE_PARTIES = 8;
 export type Fixture = Readonly<{
     /** The deployed service's base URL. Optional convenience for `fetch`. */
     app: string;
@@ -220,6 +242,26 @@ export type Fixture = Readonly<{
     credentials: Credentials;
     provider: Readonly<{
         expectPayment: (expected: ExpectedPayment) => Promise<Authorised>;
+        /**
+         * Declares payments that compete for the one capacity limit, in place of
+         * `expectPayment`. Bind each one the backend accepted; the first bound is
+         * the payout judged, and the accepted ones together must stay within
+         * `shared.limitMinor`. `capacityLimitMinor` stays the limit of one
+         * payout's own capacity readings. A competition must be raced through `concurrency.race`.
+         */
+        expectCompetingPayments: (expected: readonly ExpectedPayment[], shared: Readonly<{
+            limitMinor: string;
+        }>) => Promise<readonly Authorised[]>;
+    }>;
+    concurrency: Readonly<{
+        /**
+         * Runs `parties` submissions at once through a host gate in front of the
+         * backend: each `submit` gets the gate's base URL in place of `app`. The
+         * gate releases the requests only when all have arrived, so they meet at
+         * the backend's reservation boundary together. A race the gate cannot
+         * show overlapped does not pass.
+         */
+        race: <T>(parties: number, submit: (url: string, party: number) => Promise<T>) => Promise<RaceResult<T>>;
     }>;
     faults: Readonly<{
         /**

package/dist/index.js

@@ -75,7 +75,7 @@ const isRecord = (value) => typeof value === "object" && value !== null && !Arra
  * The session protocol this SDK speaks. The host announces its own when
  * ready; the two must match, as they do for an SDK shipped with its CLI.
  */
-export const SESSION_PROTOCOL = 2;
+export const SESSION_PROTOCOL = 3;
 /** Why a host of another protocol is refused, and how to fix it. */
 export function protocolMismatch(announced) {
     const host = announced === undefined
@@ -135,7 +135,8 @@ export function parseResult(value) {
         Array.isArray(value["properties"]) &&
         value["properties"].every(isDecision) &&
         isVerdict(value["verdict"]) &&
-        typeof value["record_published"] === "boolean";
+        typeof value["record_published"] === "boolean" &&
+        (value["reason"] === undefined || typeof value["reason"] === "string");
     if (!valid)
         throw new TypeError("audit host sealed a result this SDK cannot read; the @mandateops/audit package and the mandateops CLI are probably different versions: add the SDK shipped with your CLI (its sdk/mandateops-audit-VERSION.tgz)");
     return value;
@@ -225,6 +226,13 @@ class Channel {
         return reply.body;
     }
 }
+/** Fewest and most parties one race holds; the host enforces the same. */
+export const MIN_RACE_PARTIES = 2;
+export const MAX_RACE_PARTIES = 8;
+const isRaceReport = (value) => isRecord(value) &&
+    typeof value["parties"] === "number" &&
+    typeof value["overlap_established"] === "boolean" &&
+    (value["reason"] === undefined || typeof value["reason"] === "string");
 /**
  * The whole run, for a test runner's own timeout: startup, the body, closing
  * work on either side of the longest wait, and teardown, which may take as
@@ -402,7 +410,7 @@ async function session(config, body, channel, backend, credentials) {
         }
     };
     const requireBound = (doing) => {
-        if (profile && authorised && providerPayment === undefined) {
+        if (profile && (authorised || competing) && providerPayment === undefined) {
             throw new AuditUsageError(`${doing} under ${profile} needs bindProviderPayment first: adapters read by that identifier`);
         }
     };
@@ -413,6 +421,18 @@ async function session(config, body, channel, backend, credentials) {
             throw new AuditUsageError(`${doing}: ${FAULT_STAGE_MEANS[fault]}`);
         }
     };
+    const authorisationOf = (expected) => ({
+        instruction: wireInstruction(expected),
+        capacity_limit: minorUnits(config.capacityLimitMinor),
+        provider: {
+            account: config.system.providerTerms.account,
+            operation: config.system.providerTerms.operation,
+            idempotency_scope: config.system.providerTerms.idempotencyScope,
+        },
+        ...(expected.outcome ? { expected_outcome: expected.outcome } : {}),
+    });
+    /** Declared through `expectCompetingPayments`: nothing is judged until one is bound. */
+    let competing = false;
     const budgetSpent = new AbortController();
     const fixture = {
         signal: budgetSpent.signal,
@@ -422,16 +442,7 @@ async function session(config, body, channel, backend, credentials) {
             expectPayment: async (expected) => {
                 await fromBody({
                     type: "authorise",
-                    authorisation: {
-                        instruction: wireInstruction(expected),
-                        capacity_limit: minorUnits(config.capacityLimitMinor),
-                        provider: {
-                            account: config.system.providerTerms.account,
-                            operation: config.system.providerTerms.operation,
-                            idempotency_scope: config.system.providerTerms.idempotencyScope,
-                        },
-                        ...(expected.outcome ? { expected_outcome: expected.outcome } : {}),
-                    },
+                    authorisation: authorisationOf(expected),
                 });
                 authorised = {
                     expected,
@@ -442,6 +453,55 @@ async function session(config, body, channel, backend, credentials) {
                 };
                 return authorised;
             },
+            expectCompetingPayments: async (expected, shared) => {
+                if (expected.length < MIN_RACE_PARTIES ||
+                    expected.length > MAX_RACE_PARTIES) {
+                    throw new AuditUsageError(`expectCompetingPayments takes ${String(MIN_RACE_PARTIES)}-${String(MAX_RACE_PARTIES)} payments`);
+                }
+                if (expected.some((entrant) => entrant.outcome !== undefined)) {
+                    throw new AuditUsageError("expectCompetingPayments is judged on backend readings: declare no outcome");
+                }
+                await fromBody({
+                    type: "authorise_competition",
+                    authorisations: expected.map((entrant) => authorisationOf(entrant)),
+                    shared_limit: minorUnits(shared.limitMinor),
+                });
+                competing = true;
+                const entrants = expected.map((entrant, competitor) => ({
+                    expected: entrant,
+                    bindProviderPayment: async (payment) => {
+                        await fromBody({
+                            type: "bind_provider_payment",
+                            payment,
+                            competitor,
+                        });
+                        // The first one bound is the payout the host judges and adapters read.
+                        if (providerPayment === undefined) {
+                            providerPayment = payment;
+                            authorised = entrants[competitor];
+                        }
+                    },
+                }));
+                return entrants;
+            },
+        },
+        concurrency: {
+            race: async (parties, submit) => {
+                if (!Number.isSafeInteger(parties) ||
+                    parties < MIN_RACE_PARTIES ||
+                    parties > MAX_RACE_PARTIES) {
+                    throw new AuditUsageError(`race takes ${String(MIN_RACE_PARTIES)}-${String(MAX_RACE_PARTIES)} parties`);
+                }
+                const opened = await fromBody({ type: "open_gate", parties });
+                const url = isRecord(opened) ? opened["url"] : undefined;
+                if (typeof url !== "string")
+                    throw new Error("audit host opened a gate without an address");
+                const settled = await Promise.allSettled(Array.from({ length: parties }, (_, party) => submit(url, party)));
+                const report = await fromBody({ type: "close_gate" });
+                if (!isRaceReport(report))
+                    throw new Error("audit host closed a gate without a report");
+                return { settled, report };
+            },
         },
         faults: {
             loseResponseAfterCommit: async ({ payment, mode }) => {

package/dist/providers/fiat.d.ts

@@ -8,7 +8,13 @@ import type { CheckoutTerms, LedgerTerms, MollieTerms, ProviderWire, SourcedTerm
 export declare const paystack: (terms: LedgerTerms) => ProviderWire;
 /** `POST /v1/payouts`. A request without `destination` is refused here. */
 export declare const stripePayouts: (terms: LedgerTerms) => ProviderWire;
-/** `POST /v1/transfers`, to a connected account. */
+/**
+ * `POST /v1/transfers`, to a connected account. Checked against Stripe test
+ * mode on API version 2026-10-28.endive: a first transfer, a replay under the
+ * same key, the same key with another amount (`idempotency_error`), a refusal
+ * for funds (`balance_insufficient`) and its replay agree. Stripe also marks a
+ * replay with `Idempotent-Replayed`, which this format does not send.
+ */
 export declare const stripeTransfers: (terms: LedgerTerms) => ProviderWire;
 /**
  * `POST /v3/transfers`. Keyed on the unique `reference`, as v3 coverage of

package/dist/providers/fiat.js

@@ -88,6 +88,9 @@ const stripe = (path, terms, paid) => ({
         destination: "destination",
     },
     fixed: terms,
+    // Stripe saves a refusal under its key and replays it, as observed in test
+    // mode on API version 2026-10-28.endive.
+    refusals: "final",
     replies: {
         paid: {
             status: 200,
@@ -99,7 +102,7 @@ const stripe = (path, terms, paid) => ({
                 ...paid,
             },
         },
-        // The status of both failures is unverified.
+        // Both statuses were observed for transfers in test mode.
         declined: {
             status: 400,
             body: {
@@ -133,7 +136,13 @@ export const stripePayouts = (terms) => stripe("/v1/payouts", terms, {
     status: "pending",
     type: "bank_account",
 });
-/** `POST /v1/transfers`, to a connected account. */
+/**
+ * `POST /v1/transfers`, to a connected account. Checked against Stripe test
+ * mode on API version 2026-10-28.endive: a first transfer, a replay under the
+ * same key, the same key with another amount (`idempotency_error`), a refusal
+ * for funds (`balance_insufficient`) and its replay agree. Stripe also marks a
+ * replay with `Idempotent-Replayed`, which this format does not send.
+ */
 export const stripeTransfers = (terms) => stripe("/v1/transfers", terms, {
     id: "tr_{{effectId}}",
     object: "transfer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandateops/audit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Write audit tests that check a payout backend keeps one payment identity, money limits and commitments when a provider commits but the reply is lost. Needs the mandateops CLI.",
   "license": "Apache-2.0",
   "homepage": "https://getmandateops.com",