@mandateops/audit 0.4.2 → 0.6.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import type { CapacityReading, HistoryReading, ReadingProfile } from "./reading.js";
+import type { CapacityReading, HistoryReading, ReadingProfile, StatusReading } from "./reading.js";
 import type { ProviderWire, StagedWire } from "./providers/index.js";
 export * from "./providers/index.js";
-export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
-export type { AttemptEnd, AttemptResult, CapacityReading, Flow, HistoryEvent, HistoryReading, Instruction, MinorUnits, Payout, PayoutState, ReadingProfile, HistoryConsistency, CapacityConsistency, } from "./reading.js";
+export { parseCapacityReading, parseHistoryReading, parseStatusReading, ReadingError, requireHistoryFits, } from "./reading.js";
+export type { AttemptEnd, AttemptResult, CapacityReading, Flow, HistoryEvent, HistoryReading, Instruction, MinorUnits, Payout, PayoutState, ReadingProfile, StatusReading, HistoryConsistency, CapacityConsistency, } from "./reading.js";
 /**
  * The largest amount the stand-in holds, the audit core's `u128` maximum.
  * `fixtures/wire/vectors.json` pins it for every reader.
@@ -10,7 +10,7 @@ export type { AttemptEnd, AttemptResult, CapacityReading, Flow, HistoryEvent, Hi
 export declare const SYNTHETIC_MAX_MINOR_UNITS = 340282366920938463463374607431768211455n;
 /** Integer minor units as a decimal string, so no language loses precision. */
 export declare function minorUnits(value: string): string;
-declare const PROPERTIES: readonly ["instruction_binding", "commitment_retention", "retry_identity", "effect_within_authorisation", "reconciliation_consistency", "external_outcome"];
+declare const PROPERTIES: readonly ["instruction_binding", "commitment_retention", "retry_identity", "effect_within_authorisation", "reconciliation_consistency", "external_outcome", "reported_outcome"];
 export type Property = (typeof PROPERTIES)[number];
 declare const PROPERTY_RESULTS: readonly ["satisfied", "violated", "inconclusive", "not_applicable"];
 declare const ASSURANCES: readonly ["backend_and_provider", "backend_and_provider_commitments_not_checked", "money_out_only_commitments_not_checked", "no_assurance"];
@@ -20,11 +20,23 @@ export type ReadContext = Readonly<{
     viewerCredential: string;
     providerPayment: string;
 }>;
-/** Reads the backend, in the shape of `contracts/history-reading.md`. */
-export type Adapter = Readonly<{
+/**
+ * Reads a backend that reserves funds: its lifecycle and capacity, in the
+ * shape of `contracts/history-reading.md`.
+ */
+export type ReadingAdapter = Readonly<{
     history: (context: ReadContext) => Promise<HistoryReading>;
     capacity: (context: ReadContext) => Promise<CapacityReading>;
 }>;
+/**
+ * Reads the outcome a backend without reservations reports for the payout,
+ * judged against the provider's records under `payout-effects-only`.
+ */
+export type StatusAdapter = Readonly<{
+    status: (context: ReadContext) => Promise<StatusReading>;
+}>;
+/** Reads the backend: lifecycle and capacity, or only its reported status. */
+export type Adapter = ReadingAdapter | StatusAdapter;
 export declare const defineAdapter: (adapter: Adapter) => Adapter;
 /** The provider identity every effect must carry. */
 export type ProviderTerms = Readonly<{
@@ -212,7 +224,7 @@ 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 = 3;
+export declare const SESSION_PROTOCOL = 4;
 /** 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. */

package/dist/index.js

@@ -12,10 +12,10 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
-import { parseCapacityReading, parseHistoryReading, requireHistoryFits, } from "./reading.js";
+import { parseCapacityReading, parseHistoryReading, parseStatusReading, requireHistoryFits, } from "./reading.js";
 // Every provider format and its types, from the one list that names them.
 export * from "./providers/index.js";
-export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
+export { parseCapacityReading, parseHistoryReading, parseStatusReading, ReadingError, requireHistoryFits, } from "./reading.js";
 const MINOR_UNITS = /^[1-9][0-9]*$/;
 /**
  * The largest amount the stand-in holds, the audit core's `u128` maximum.
@@ -42,6 +42,7 @@ const PROPERTIES = [
     "effect_within_authorisation",
     "reconciliation_consistency",
     "external_outcome",
+    "reported_outcome",
 ];
 const PROPERTY_RESULTS = [
     "satisfied",
@@ -76,7 +77,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 = 3;
+export const SESSION_PROTOCOL = 4;
 /** Why a host of another protocol is refused, and how to fix it. */
 export function protocolMismatch(announced) {
     const host = announced === undefined
@@ -253,8 +254,15 @@ const readingProfile = (config) => config.financialProfile === "payout-effects-o
  */
 export function requireRunnable(config) {
     const profile = readingProfile(config);
-    if (profile === undefined && config.adapter) {
-        throw new AuditUsageError("payout-effects-only is judged on provider records alone: remove the adapter");
+    if (profile === undefined &&
+        config.adapter &&
+        !("status" in config.adapter)) {
+        throw new AuditUsageError("payout-effects-only reads no lifecycle or capacity: give it a status " +
+            "adapter (contracts/history-reading.md), or none");
+    }
+    if (profile !== undefined && config.adapter && "status" in config.adapter) {
+        throw new AuditUsageError(`${profile} reads lifecycle and capacity, not a status: a status ` +
+            "adapter is for payout-effects-only");
     }
     if (profile !== undefined && !config.adapter) {
         throw new AuditUsageError(`${profile} needs an adapter with history and capacity readings ` +
@@ -391,10 +399,12 @@ async function session(config, body, channel, backend, credentials) {
     const context = () => providerPayment === undefined
         ? undefined
         : { backend, viewerCredential, providerPayment };
+    const readings = config.adapter && "history" in config.adapter ? config.adapter : undefined;
+    const statusAdapter = config.adapter && "status" in config.adapter ? config.adapter : undefined;
     const readHistory = async (slot) => {
         const read = context();
-        if (config.adapter && profile && read && authorised) {
-            const { history } = config.adapter;
+        if (readings && profile && read && authorised) {
+            const { history } = readings;
             const reference = authorised.expected.reference;
             await reading(slot, async () => {
                 const taken = parseHistoryReading(await history(read));
@@ -405,11 +415,27 @@ async function session(config, body, channel, backend, credentials) {
     };
     const readCapacity = async (slot) => {
         const read = context();
-        const capacity = config.adapter?.capacity;
+        const capacity = readings?.capacity;
         if (capacity && read) {
             await reading(slot, async () => parseCapacityReading(await capacity(read)));
         }
     };
+    /**
+     * The backend's reported outcome, after the provider's records. Without a
+     * binding there is nothing to read by, which is reported, never skipped.
+     */
+    const readStatus = async () => {
+        if (!statusAdapter || !authorised)
+            return;
+        const reference = authorised.expected.reference;
+        const read = context();
+        await reading("capture_status", async () => {
+            if (!read) {
+                throw new AuditUsageError("a status adapter reads by the provider payment: call bindProviderPayment");
+            }
+            return parseStatusReading(await statusAdapter.status(read), reference);
+        });
+    };
     const requireBound = (doing) => {
         if (profile && (authorised || competing) && providerPayment === undefined) {
             throw new AuditUsageError(`${doing} under ${profile} needs bindProviderPayment first: adapters read by that identifier`);
@@ -583,6 +609,7 @@ async function session(config, body, channel, backend, credentials) {
     await readCapacity("capture_capacity");
     await channel.send({ type: "read_effects" });
     await readHistory("recapture_history");
+    await readStatus();
     const result = {
         ...parseResult(await channel.send({ type: "seal" })),
         reading_problems: problems,

package/dist/reading.d.ts

@@ -83,6 +83,16 @@ export type CapacityReading = Readonly<{
     committed: MinorUnits;
     consumed: MinorUnits;
 }>;
+/**
+ * The outcome the backend itself reports for one payout, taken once after
+ * the provider's records under `payout-effects-only`.
+ */
+export type StatusReading = Readonly<{
+    source: "adapter";
+    /** The reference given to `expectPayment`. */
+    payment: string;
+    state: PayoutState;
+}>;
 /** The profiles an adapter reading is taken under. */
 export type ReadingProfile = "payout-effects" | "payout-commitment";
 /**
@@ -101,6 +111,13 @@ export declare class ReadingError extends TypeError {
  * @throws {ReadingError} naming the first field that cannot be interpreted.
  */
 export declare function parseHistoryReading(value: unknown): HistoryReading;
+/**
+ * Check an untrusted status reading against the contract, and that it names
+ * the payout the test expects.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export declare function parseStatusReading(value: unknown, reference: string): StatusReading;
 /**
  * Check an untrusted capacity reading against the contract.
  *

package/dist/reading.js

@@ -231,6 +231,22 @@ export function parseHistoryReading(value) {
     });
     return value;
 }
+/**
+ * Check an untrusted status reading against the contract, and that it names
+ * the payout the test expects.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export function parseStatusReading(value, reference) {
+    const found = members(value, "", ["source", "payment", "state"]);
+    requireExactly("adapter", found["source"], "source");
+    requireText(found["payment"], "payment");
+    if (found["payment"] !== reference) {
+        refuse("payment", "the reference given to expectPayment", found["payment"]);
+    }
+    requireOneOf(STATES, found["state"], "state");
+    return value;
+}
 /**
  * Check an untrusted capacity reading against the contract.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandateops/audit",
-  "version": "0.4.2",
+  "version": "0.6.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",