@tabai/sdk 0.2.0

package/dist/server/index.js

@@ -0,0 +1,30 @@
+/**
+ * The server-side surface: the post-paid plugin, the metering seam, and the three
+ * framework adapters.
+ *
+ * `tabPostPaid` is the whole product claim in one function. A Service installs it,
+ * keeps writing handlers the way it already does, and its Open Tab accrues behind
+ * each delivered response. No caller prepays, no response waits on a payment, and
+ * the one status this surface adds is a `402` on `LimitExceeded`, a credit
+ * decision, not a prepayment demand (R23.3, R12.1).
+ *
+ * The adapters are thin by design and carry no dependency on the framework they
+ * adapt: every framework type in here is structural, so a Service on Hono installs
+ * nothing for Express and nothing for Next.js.
+ *
+ * The wire format is not defined here. `src/http/headers.ts` owns it, this surface
+ * is its emitting half, and the 402 client of R23.2 is its reading half, so a
+ * disagreement about a header is a test failure in one file rather than a silent
+ * mis-parse between two.
+ *
+ * Nothing exported here throws, with one named exception: the Hono and Next.js
+ * adapters re-raise a handler's own thrown value, because a framework's contract
+ * for a failed handler is an exception and the adapter is the boundary where a
+ * `Result` becomes whatever the host expects.
+ */
+export * from "./metering.js";
+export * from "./post-paid.js";
+export * from "./adapters/hono.js";
+export * from "./adapters/express.js";
+export * from "./adapters/next.js";
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC","sourcesContent":["/**\n * The server-side surface: the post-paid plugin, the metering seam, and the three\n * framework adapters.\n *\n * `tabPostPaid` is the whole product claim in one function. A Service installs it,\n * keeps writing handlers the way it already does, and its Open Tab accrues behind\n * each delivered response. No caller prepays, no response waits on a payment, and\n * the one status this surface adds is a `402` on `LimitExceeded`, a credit\n * decision, not a prepayment demand (R23.3, R12.1).\n *\n * The adapters are thin by design and carry no dependency on the framework they\n * adapt: every framework type in here is structural, so a Service on Hono installs\n * nothing for Express and nothing for Next.js.\n *\n * The wire format is not defined here. `src/http/headers.ts` owns it, this surface\n * is its emitting half, and the 402 client of R23.2 is its reading half, so a\n * disagreement about a header is a test failure in one file rather than a silent\n * mis-parse between two.\n *\n * Nothing exported here throws, with one named exception: the Hono and Next.js\n * adapters re-raise a handler's own thrown value, because a framework's contract\n * for a failed handler is an exception and the adapter is the boundary where a\n * `Result` becomes whatever the host expects.\n */\n\nexport * from \"./metering.js\";\nexport * from \"./post-paid.js\";\nexport * from \"./adapters/hono.js\";\nexport * from \"./adapters/express.js\";\nexport * from \"./adapters/next.js\";\n"]}

package/dist/server/metering.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The metering seam: what the post-paid plugin calls to record one Metered
+ * Delivery, and how a `recordDelivery` revert becomes a `TabError`.
+ *
+ * Two things live here and they are deliberately separate. {@link TabBookClient}
+ * is the interface the plugin depends on, so the plugin has no opinion about
+ * `ethers`, an RPC endpoint, a signer, or a witness. {@link RECORD_DELIVERY_REVERTS}
+ * is the mapping table from `TabBook.recordDelivery`'s revert set to the
+ * `TabError` each one becomes, so every implementation of that interface, the
+ * gateway or a Service operator's own client, classifies a refusal the same way
+ * rather than each inventing its own status codes.
+ *
+ * ## The revert set is the real one, read off the contract
+ *
+ * `recordDelivery(agent, serviceId, asset, tool, units, expectedUnitPrice,
+ * witness)` runs six steps in a fixed order, and each step has its own refusals.
+ * In call order: the registry read (`UnknownService`), the operator check
+ * (`NotServiceOperator`), the delinquency check (`TabIsDelinquent`), pricing
+ * (`ZeroUnits`, `UnknownTool`, `PriceListChangedMidCall`, `AmountOutOfRange`),
+ * the authorisation (`AuthorisationMissing`, `AuthorisationExpired`,
+ * `AuthorisationExceeded`), and the headroom check (`LimitExceeded`, plus the
+ * witness-validation errors the Credit Limit computation raises). Every name in
+ * {@link RECORD_DELIVERY_REVERTS} is one of those; nothing in the table was
+ * guessed from the design.
+ *
+ * ## Whose fault it is decides who sees it
+ *
+ * Each row carries a {@link RefusalDisposition}, and that field is the whole
+ * policy of this module:
+ *
+ * - `refuse-request`, the refusal is the Agent's to fix. Its Credit Limit has no
+ *   headroom, its spending authorisation is missing, lapsed, or spent, or its tab
+ *   went past its Settlement Window. The Agent is told, with the figures it needs
+ *   to act on.
+ * - `deliver-anyway`, the refusal is the Service's to fix, or ours. A wrong
+ *   operator key, a tool that is not in the applied price list, a price that
+ *   moved under the call, a witness the Service assembled wrongly. The Agent did
+ *   nothing, so the Agent's response is delivered and the Service is told through
+ *   its own failure channel. A Service whose billing is broken eats the cost of
+ *   the delivery; it does not hand the cost to the caller.
+ *
+ * `refuse-request` is the smaller set on purpose. The plugin exists to accrue, not
+ * to gate.
+ *
+ * ## Amounts
+ *
+ * Every amount here is an integer count of Asset base units as a `bigint`. USDC
+ * is 6 decimals, and nothing in this module converts, scales, or rounds.
+ *
+ * Requirements: 23.3, 12.1, 12.2, 12.3, 21.5
+ */
+import { type Address, type Bytes32, type ErrorCategory, type Hex, type Result, type TabError } from "../_shared/index.js";
+import type { AssetRef } from "../payments/strategy.js";
+/**
+ * The one delivery a Service is charging for.
+ *
+ * The fields are `recordDelivery`'s own parameters minus the witness, because the
+ * witness is not the plugin's to build: it is the full ordered
+ * Settlement history plus one Bond entry per counterparty, validated on chain
+ * against the rolling commitment, and assembling it needs chain reads the plugin
+ * does not make. A {@link TabBookClient} owns that.
+ */
+export interface MeteredDelivery {
+    /** The Agent's Monad address. Identified from the request, never from a session. */
+    readonly agent: Address;
+    readonly serviceId: Bytes32;
+    readonly asset: AssetRef;
+    /** The named priced unit, as the 32-byte word the applied price list is keyed by. */
+    readonly tool: Bytes32;
+    /** Count of priced units. A `uint32` on chain, and zero reverts `ZeroUnits`. */
+    readonly units: number;
+    /**
+     * The unit price the Service quoted, in Asset base units.
+     *
+     * Compared for exact equality against the applied price list, so a price that
+     * moved between the quote and the charge reverts `PriceListChangedMidCall`
+     * rather than charging a figure the Agent never saw. Per unit rather than
+     * total, so the count cannot be adjusted to match a total already committed to.
+     */
+    readonly expectedUnitPrice: bigint;
+}
+/** What `recordDelivery` returned, in the order the contract returns it. */
+export interface DeliveryReceipt {
+    /** `units * expectedUnitPrice`, in Asset base units. */
+    readonly charged: bigint;
+    /** The Open Tab for this Agent, Service, and Asset after the charge. */
+    readonly openAfter: bigint;
+    /** Headroom left for this Agent across every Service in this Asset. */
+    readonly headroomAfter: bigint;
+    /** The Monad transaction the delivery was recorded in, when the client knows it. */
+    readonly monadTxHash?: Hex;
+    /** Milliseconds since the epoch, on the recording client's clock. */
+    readonly recordedAt: number;
+}
+/**
+ * The two calls the post-paid plugin makes.
+ *
+ * Narrow on purpose: this is what lets a Service meter against a real signer in
+ * production and against a stub in a test without the plugin knowing the
+ * difference. Both methods return a `Result` and neither throws (design section
+ * 13.1). On a revert, `recordDelivery` returns the `TabError`
+ * {@link classifyRecordDeliveryRevert} produces, so the plugin reads the
+ * disposition off `details.disposition` rather than re-decoding contract data.
+ */
+export interface TabBookClient {
+    recordDelivery(delivery: MeteredDelivery): Promise<Result<DeliveryReceipt>>;
+    /**
+     * The Open Tab for this Agent, Service, and Asset, read without metering.
+     *
+     * A second method rather than one, because the `402` needs a figure a revert
+     * does not carry. `LimitExceeded` reverts with the requested amount and the
+     * headroom and says nothing about the Open Tab, and the charge block on the wire
+     * is all six headers or none of them, so a 402 that could not name the Open Tab
+     * would reach the 402 client as a malformed charge block instead of as the credit
+     * decision it is. The call is a view, no witness, no signature, and the figure
+     * is truthful precisely because the metering transaction reverted and moved
+     * nothing.
+     *
+     * Called on the refusal path alone. It is never on the path of a successful
+     * delivery, which reads its figures off `recordDelivery`'s own return.
+     */
+    openTabOf(delivery: MeteredDelivery): Promise<Result<bigint>>;
+}
+/**
+ * The human-readable ABI fragment of the real entrypoint, field for field.
+ *
+ * Carried here so a {@link TabBookClient} implementation encodes against the
+ * deployed signature rather than a remembered one. The witness is one tuple of
+ * two arrays: `LimitLib.SettlementRecord[]` and `LimitLib.BondEntry[]`, in that
+ * order.
+ */
+export declare const TAB_BOOK_RECORD_DELIVERY_ABI: readonly ["function recordDelivery(address agent, bytes32 serviceId, address asset, bytes32 tool, uint32 units, uint256 expectedUnitPrice, ((bytes32 serviceId, address asset, uint128 amount, uint64 settledAt, uint64 firstDeliveryAt, bool curated, bool bonded)[] history, (bytes32 serviceId, address asset, uint128 amount)[] bonds) witness) returns (uint256 charged, uint128 openAfter, uint256 headroomAfter)"];
+/**
+ * Whether a refusal changes what the caller receives.
+ *
+ * `refuse-request` replaces the handler's response. `deliver-anyway` does not:
+ * the response goes out, and the Service learns about the refusal through
+ * `onMeteringFailed`.
+ */
+export type RefusalDisposition = "refuse-request" | "deliver-anyway";
+/** One row of the revert mapping table. */
+export interface RevertMapping {
+    /** The `TabError` category, which is also what fixes the HTTP status (design section 13.1). */
+    readonly category: ErrorCategory;
+    /** Stable and machine-readable, for example `LIMIT_EXCEEDED`. */
+    readonly code: string;
+    readonly disposition: RefusalDisposition;
+    readonly retryable: boolean;
+    /**
+     * The revert's argument names, positionally. Decoded arguments are attached to
+     * `TabError.details` under these names, so the 402 body can carry the required
+     * amount and the headroom without this module knowing which row it is on.
+     */
+    readonly args: readonly string[];
+    /** What the Agent or the Service operator is supposed to do about it. */
+    readonly action: string;
+}
+/**
+ * Every revert `recordDelivery` can produce, and what each one becomes.
+ *
+ * The status each row maps to is not stored: it is `httpStatusOf(category)`, so
+ * `LIMIT` is 402 and nothing else is, which is the whole of design section 9.5's
+ * rule expressed as a lookup rather than as a comment.
+ */
+export declare const RECORD_DELIVERY_REVERTS: Readonly<Record<string, RevertMapping>>;
+/** The revert name and decoded arguments, as `ethers` v6 reports them. */
+export interface DecodedRevert {
+    readonly name: string;
+    readonly args?: readonly unknown[];
+}
+/**
+ * Pulls a decoded revert out of whatever a client caught.
+ *
+ * `ethers` v6 attaches `error.revert` as `{ name, signature, args }` when it can
+ * match the returndata against the contract's ABI; older shapes carry
+ * `errorName` and `errorArgs`; and a plain object with a `name` is what a test
+ * or a non-`ethers` client hands over. All three are read, and anything else
+ * yields undefined rather than a guess.
+ */
+export declare function decodeRevert(thrown: unknown): DecodedRevert | undefined;
+/** The mapping row for one revert name, or undefined when the name is not one of them. */
+export declare const revertMappingFor: (name: string) => RevertMapping | undefined;
+/**
+ * Turns a `recordDelivery` revert into the `TabError` the plugin acts on.
+ *
+ * `details` always carries `revert` and `disposition`, and carries each decoded
+ * argument under the name the row gives it. That is how the plugin builds a 402
+ * body naming the required amount and the current headroom without a special
+ * case for `LimitExceeded`: it reads `details.requested` and `details.headroom`,
+ * which the table put there.
+ *
+ * A revert this table does not name is `CHAIN`/`RECORD_DELIVERY_REVERTED` with
+ * `deliver-anyway`, because an unclassified refusal is not something to charge an
+ * Agent for and not something to refuse a delivered response over either.
+ */
+export declare function classifyRecordDeliveryRevert(thrown: unknown): TabError;
+/** The disposition carried on a classified error, defaulting to the safe one. */
+export declare const dispositionOf: (error: TabError) => RefusalDisposition;
+/** The HTTP status a refusal is served with, taken from its category alone. */
+export declare const refusalStatusOf: (error: TabError) => number;
+/**
+ * Reads one decoded argument off a classified error as a `bigint`.
+ *
+ * Arguments land in `details` as decimal strings, because `TabError.details`
+ * holds no `bigint`. This reads one back, and returns undefined rather than
+ * `0n` when it is absent, a headroom nobody reported is not a headroom of zero.
+ */
+export declare function detailAmount(error: TabError, name: string): bigint | undefined;
+//# sourceMappingURL=metering.d.ts.map

package/dist/server/metering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering.d.ts","sourceRoot":"","sources":["../../src/server/metering.ts"],"names":[],"mappings":"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"}

package/dist/server/metering.js

@@ -0,0 +1,365 @@
+/**
+ * The metering seam: what the post-paid plugin calls to record one Metered
+ * Delivery, and how a `recordDelivery` revert becomes a `TabError`.
+ *
+ * Two things live here and they are deliberately separate. {@link TabBookClient}
+ * is the interface the plugin depends on, so the plugin has no opinion about
+ * `ethers`, an RPC endpoint, a signer, or a witness. {@link RECORD_DELIVERY_REVERTS}
+ * is the mapping table from `TabBook.recordDelivery`'s revert set to the
+ * `TabError` each one becomes, so every implementation of that interface, the
+ * gateway or a Service operator's own client, classifies a refusal the same way
+ * rather than each inventing its own status codes.
+ *
+ * ## The revert set is the real one, read off the contract
+ *
+ * `recordDelivery(agent, serviceId, asset, tool, units, expectedUnitPrice,
+ * witness)` runs six steps in a fixed order, and each step has its own refusals.
+ * In call order: the registry read (`UnknownService`), the operator check
+ * (`NotServiceOperator`), the delinquency check (`TabIsDelinquent`), pricing
+ * (`ZeroUnits`, `UnknownTool`, `PriceListChangedMidCall`, `AmountOutOfRange`),
+ * the authorisation (`AuthorisationMissing`, `AuthorisationExpired`,
+ * `AuthorisationExceeded`), and the headroom check (`LimitExceeded`, plus the
+ * witness-validation errors the Credit Limit computation raises). Every name in
+ * {@link RECORD_DELIVERY_REVERTS} is one of those; nothing in the table was
+ * guessed from the design.
+ *
+ * ## Whose fault it is decides who sees it
+ *
+ * Each row carries a {@link RefusalDisposition}, and that field is the whole
+ * policy of this module:
+ *
+ * - `refuse-request`, the refusal is the Agent's to fix. Its Credit Limit has no
+ *   headroom, its spending authorisation is missing, lapsed, or spent, or its tab
+ *   went past its Settlement Window. The Agent is told, with the figures it needs
+ *   to act on.
+ * - `deliver-anyway`, the refusal is the Service's to fix, or ours. A wrong
+ *   operator key, a tool that is not in the applied price list, a price that
+ *   moved under the call, a witness the Service assembled wrongly. The Agent did
+ *   nothing, so the Agent's response is delivered and the Service is told through
+ *   its own failure channel. A Service whose billing is broken eats the cost of
+ *   the delivery; it does not hand the cost to the caller.
+ *
+ * `refuse-request` is the smaller set on purpose. The plugin exists to accrue, not
+ * to gate.
+ *
+ * ## Amounts
+ *
+ * Every amount here is an integer count of Asset base units as a `bigint`. USDC
+ * is 6 decimals, and nothing in this module converts, scales, or rounds.
+ *
+ * Requirements: 23.3, 12.1, 12.2, 12.3, 21.5
+ */
+import { httpStatusOf, } from "../_shared/index.js";
+import { tabError } from "../errors.js";
+/**
+ * The human-readable ABI fragment of the real entrypoint, field for field.
+ *
+ * Carried here so a {@link TabBookClient} implementation encodes against the
+ * deployed signature rather than a remembered one. The witness is one tuple of
+ * two arrays: `LimitLib.SettlementRecord[]` and `LimitLib.BondEntry[]`, in that
+ * order.
+ */
+export const TAB_BOOK_RECORD_DELIVERY_ABI = [
+    "function recordDelivery(address agent, bytes32 serviceId, address asset, bytes32 tool, uint32 units, uint256 expectedUnitPrice, ((bytes32 serviceId, address asset, uint128 amount, uint64 settledAt, uint64 firstDeliveryAt, bool curated, bool bonded)[] history, (bytes32 serviceId, address asset, uint128 amount)[] bonds) witness) returns (uint256 charged, uint128 openAfter, uint256 headroomAfter)",
+];
+/**
+ * Every revert `recordDelivery` can produce, and what each one becomes.
+ *
+ * The status each row maps to is not stored: it is `httpStatusOf(category)`, so
+ * `LIMIT` is 402 and nothing else is, which is the whole of design section 9.5's
+ * rule expressed as a lookup rather than as a comment.
+ */
+export const RECORD_DELIVERY_REVERTS = {
+    // --- the Agent's to fix: these replace the response -----------------------
+    /** The one 402. The Agent's Open Tab for the Asset has no room for this charge. */
+    LimitExceeded: {
+        category: "LIMIT",
+        code: "LIMIT_EXCEEDED",
+        disposition: "refuse-request",
+        retryable: false,
+        args: ["agent", "asset", "requested", "headroom"],
+        action: "settle the Open Tab, or raise the Credit Limit by growing proven settlement history, then repeat the request",
+    },
+    AuthorisationMissing: {
+        category: "AUTHORISATION",
+        code: "AUTHORISATION_MISSING",
+        disposition: "refuse-request",
+        retryable: false,
+        args: ["agent", "serviceId", "asset"],
+        action: "the Agent must call TabBook.authorise for this Service and Asset before any delivery is metered",
+    },
+    AuthorisationExpired: {
+        category: "AUTHORISATION",
+        code: "AUTHORISATION_EXPIRED",
+        disposition: "refuse-request",
+        retryable: false,
+        args: ["expiry", "nowTs"],
+        action: "the Agent must call TabBook.authorise again with a later expiry",
+    },
+    AuthorisationExceeded: {
+        category: "AUTHORISATION",
+        code: "AUTHORISATION_EXCEEDED",
+        disposition: "refuse-request",
+        retryable: false,
+        args: ["maxCumulative", "spent", "requested"],
+        action: "the Agent must raise maxCumulative on its authorisation",
+    },
+    /**
+     * Past the Settlement Window, so the tab is delinquent and the Agent's Credit
+     * Limit for the Asset is zero.
+     *
+     * A 409 rather than a 402, deliberately. Design section 9.5 fixes 402 to
+     * `LimitExceeded` alone on this surface, and delinquency is a different fact
+     * from a full tab: the state of the tab conflicts with metering at all, and no
+     * headroom figure would make this request succeed. The Agent settles the named
+     * tab and the state clears.
+     */
+    TabIsDelinquent: {
+        category: "CONFLICT",
+        code: "TAB_DELINQUENT",
+        disposition: "refuse-request",
+        retryable: false,
+        args: ["tabId"],
+        action: "the Agent must settle the named tab; its Credit Limit for this Asset is zero until it does",
+    },
+    // --- the Service's to fix, or ours: the response is delivered anyway ------
+    /**
+     * The applied price moved between the Service's quote and the charge.
+     *
+     * The Service's problem, not the Agent's: the Agent was quoted a price and the
+     * work was delivered at it. Retryable once with the price the registry now
+     * serves.
+     */
+    PriceListChangedMidCall: {
+        category: "CONFLICT",
+        code: "PRICE_LIST_CHANGED_MID_CALL",
+        disposition: "deliver-anyway",
+        retryable: true,
+        args: ["serviceId", "asset", "tool", "quoted", "applied"],
+        action: "re-quote from the applied price list and record the delivery again",
+    },
+    UnknownTool: {
+        category: "NOT_FOUND",
+        code: "UNKNOWN_TOOL",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["serviceId", "asset", "tool"],
+        action: "register the tool in the Service's price list; a priced unit that is not listed cannot be charged",
+    },
+    UnknownService: {
+        category: "NOT_FOUND",
+        code: "UNKNOWN_SERVICE",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["serviceId"],
+        action: "register the Service before metering into it",
+    },
+    NotServiceOperator: {
+        category: "AUTHORISATION",
+        code: "NOT_SERVICE_OPERATOR",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["serviceId", "caller"],
+        action: "meter with the Service operator's own Monad key",
+    },
+    ZeroUnits: {
+        category: "VALIDATION",
+        code: "ZERO_UNITS",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: [],
+        action: "price the delivery at one unit or more, or treat it as unbillable and record nothing",
+    },
+    AmountOutOfRange: {
+        category: "VALIDATION",
+        code: "AMOUNT_OUT_OF_RANGE",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["amount"],
+        action: "reduce the unit count; the Open Tab is kept in uint128 base units",
+    },
+    HistoryCommitmentMismatch: {
+        category: "CONFLICT",
+        code: "HISTORY_COMMITMENT_MISMATCH",
+        disposition: "deliver-anyway",
+        retryable: true,
+        args: ["expected", "provided"],
+        action: "refresh the witness from chain state and record the delivery again",
+    },
+    HistoryLengthMismatch: {
+        category: "CONFLICT",
+        code: "HISTORY_LENGTH_MISMATCH",
+        disposition: "deliver-anyway",
+        retryable: true,
+        args: ["expected", "provided"],
+        action: "refresh the witness from chain state and record the delivery again",
+    },
+    DuplicateBondEntry: {
+        category: "INTERNAL",
+        code: "DUPLICATE_BOND_ENTRY",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["serviceId"],
+        action: "fix the witness builder: one Bond entry per counterparty Service",
+    },
+    IneligibleBondEntry: {
+        category: "INTERNAL",
+        code: "INELIGIBLE_BOND_ENTRY",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["serviceId", "asset"],
+        action: "fix the witness builder: every Bond entry must name a counterparty from the history",
+    },
+    TooManyBondEntries: {
+        category: "INTERNAL",
+        code: "TOO_MANY_BOND_ENTRIES",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["count", "maximum"],
+        action: "compact the history; this is the documented scaling limit of the pure computation",
+    },
+    HistoryTooLong: {
+        category: "INTERNAL",
+        code: "HISTORY_TOO_LONG",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["count", "maximum"],
+        action: "compact the history; this is the documented scaling limit of the pure computation",
+    },
+    TooManyCounterparties: {
+        category: "INTERNAL",
+        code: "TOO_MANY_COUNTERPARTIES",
+        disposition: "deliver-anyway",
+        retryable: false,
+        args: ["count", "maximum"],
+        action: "compact the history; this is the documented scaling limit of the pure computation",
+    },
+};
+/**
+ * Pulls a decoded revert out of whatever a client caught.
+ *
+ * `ethers` v6 attaches `error.revert` as `{ name, signature, args }` when it can
+ * match the returndata against the contract's ABI; older shapes carry
+ * `errorName` and `errorArgs`; and a plain object with a `name` is what a test
+ * or a non-`ethers` client hands over. All three are read, and anything else
+ * yields undefined rather than a guess.
+ */
+export function decodeRevert(thrown) {
+    if (typeof thrown !== "object" || thrown === null)
+        return undefined;
+    const candidate = thrown;
+    const revert = candidate.revert;
+    if (revert !== undefined && revert !== null && typeof revert.name === "string") {
+        return { name: revert.name, ...(Array.isArray(revert.args) ? { args: revert.args } : {}) };
+    }
+    if (typeof candidate.errorName === "string") {
+        return {
+            name: candidate.errorName,
+            ...(Array.isArray(candidate.errorArgs) ? { args: candidate.errorArgs } : {}),
+        };
+    }
+    if (typeof candidate.name === "string" && RECORD_DELIVERY_REVERTS[candidate.name] !== undefined) {
+        return { name: candidate.name, ...(Array.isArray(candidate.args) ? { args: candidate.args } : {}) };
+    }
+    return undefined;
+}
+/** The mapping row for one revert name, or undefined when the name is not one of them. */
+export const revertMappingFor = (name) => RECORD_DELIVERY_REVERTS[name];
+/**
+ * Turns a `recordDelivery` revert into the `TabError` the plugin acts on.
+ *
+ * `details` always carries `revert` and `disposition`, and carries each decoded
+ * argument under the name the row gives it. That is how the plugin builds a 402
+ * body naming the required amount and the current headroom without a special
+ * case for `LimitExceeded`: it reads `details.requested` and `details.headroom`,
+ * which the table put there.
+ *
+ * A revert this table does not name is `CHAIN`/`RECORD_DELIVERY_REVERTED` with
+ * `deliver-anyway`, because an unclassified refusal is not something to charge an
+ * Agent for and not something to refuse a delivered response over either.
+ */
+export function classifyRecordDeliveryRevert(thrown) {
+    const decoded = decodeRevert(thrown);
+    const mapping = decoded === undefined ? undefined : revertMappingFor(decoded.name);
+    const cause = causeFrom(thrown);
+    const carriedCause = cause === undefined ? {} : { cause };
+    if (decoded === undefined || mapping === undefined) {
+        return tabError("CHAIN", "RECORD_DELIVERY_REVERTED", decoded === undefined
+            ? "recordDelivery failed and the returndata matched no known revert"
+            : `recordDelivery reverted \`${decoded.name}\`, which is not a revert this SDK version classifies`, {
+            retryable: false,
+            details: {
+                disposition: "deliver-anyway",
+                ...(decoded === undefined ? {} : { revert: decoded.name }),
+            },
+            ...carriedCause,
+        });
+    }
+    return tabError(mapping.category, mapping.code, `recordDelivery reverted \`${decoded.name}\`: ${mapping.action}`, {
+        retryable: mapping.retryable,
+        details: {
+            revert: decoded.name,
+            disposition: mapping.disposition,
+            ...namedArgs(mapping.args, decoded.args),
+        },
+        ...carriedCause,
+    });
+}
+/** The disposition carried on a classified error, defaulting to the safe one. */
+export const dispositionOf = (error) => error.details?.["disposition"] === "refuse-request" ? "refuse-request" : "deliver-anyway";
+/** The HTTP status a refusal is served with, taken from its category alone. */
+export const refusalStatusOf = (error) => httpStatusOf(error);
+/**
+ * Reads one decoded argument off a classified error as a `bigint`.
+ *
+ * Arguments land in `details` as decimal strings, because `TabError.details`
+ * holds no `bigint`. This reads one back, and returns undefined rather than
+ * `0n` when it is absent, a headroom nobody reported is not a headroom of zero.
+ */
+export function detailAmount(error, name) {
+    const raw = error.details?.[name];
+    if (typeof raw === "bigint")
+        return raw;
+    if (typeof raw === "number" && Number.isSafeInteger(raw))
+        return BigInt(raw);
+    if (typeof raw !== "string" || !/^\d+$/.test(raw))
+        return undefined;
+    return BigInt(raw);
+}
+/** Names the positional revert arguments and renders each into `details`. */
+function namedArgs(names, args) {
+    if (args === undefined)
+        return {};
+    const named = {};
+    for (const [index, name] of names.entries()) {
+        if (index >= args.length)
+            break;
+        const value = args[index];
+        if (typeof value === "bigint")
+            named[name] = value.toString(10);
+        else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            named[name] = value;
+        }
+        else if (value !== undefined && value !== null)
+            named[name] = String(value);
+    }
+    return named;
+}
+/** Narrows a caught value into the `cause` shape a `TabError` accepts. */
+function causeFrom(thrown) {
+    if (thrown instanceof Error)
+        return { code: thrown.name, message: thrown.message };
+    if (typeof thrown === "object" && thrown !== null) {
+        const candidate = thrown;
+        const message = typeof candidate.shortMessage === "string"
+            ? candidate.shortMessage
+            : typeof candidate.message === "string"
+                ? candidate.message
+                : undefined;
+        if (message === undefined)
+            return undefined;
+        return { code: typeof candidate.code === "string" ? candidate.code : "UNKNOWN", message };
+    }
+    return undefined;
+}
+//# sourceMappingURL=metering.js.map