@integraledger/agent-guard 0.9.0

package/src/mechanical.ts

@@ -0,0 +1,71 @@
+import type { Assurance } from "@integraledger/lcp-authority";
+import type {
+  SettlementRef,
+  VerifierPorts,
+  WeldAdapter,
+} from "@integraledger/lcp-binding-core";
+import {
+  type RecordIdentity,
+  type TransactionClass,
+  type VerificationReport,
+  verify,
+} from "@integraledger/lcp-verify";
+
+/** Inputs for the post-settlement mechanical verify. `verifierPorts` (chain + artifacts) is INJECTED, which is
+ *  what keeps the gate viem-free. `atrBytes` is the fetched ATR; `coverage` matches verify's shape. */
+export interface MechanicalPorts {
+  readonly verifierPorts: VerifierPorts;
+  readonly atrBytes: Uint8Array;
+  readonly asOf: string;
+  readonly coverage: { ports: string[]; bindings: string[] };
+  readonly claimedClass?: TransactionClass;
+  /**
+   * The parties as the buyer resolved them (IDN-1/3). TC-1 and up require the attribution rung, so a
+   * record verified without this reads honestly as unverified — the gate KNOWS both sides at this point
+   * (it holds the seller's stated assurance from the proposal and it is itself the payer), so it says so.
+   */
+  readonly identity: {
+    readonly sellerAssurance: Assurance;
+    readonly payer: string;
+  };
+}
+
+/** Turn a settled receipt into a TC-2/TC-3 *transaction* record: recover the on-chain atrHash via the injected
+ *  binding adapter, then run `verify({depth:"mechanical"})` — `verified` is raised honestly iff the ATR bytes
+ *  hash to the recovered atrHash (and the class-required steps hold). A refused recovery leaves settledAtrHash
+ *  absent → the fingerprint is indeterminate → verified stays false. */
+export async function verifySettled(
+  ref: SettlementRef,
+  adapter: Pick<WeldAdapter, "recover">,
+  ports: MechanicalPorts,
+): Promise<VerificationReport> {
+  const recovered = await adapter.recover(ref, ports.verifierPorts);
+  // The buyer resolves the seller at the assurance the proposal stated, and itself at the level the rail
+  // actually supports: a wallet signature. Stating the low level honestly is conformant (IDN-3); claiming
+  // a level the rail cannot support would not be.
+  const identity: RecordIdentity = {
+    seller: {
+      subject: "seller",
+      assurance: ports.identity.sellerAssurance,
+      chain: [{ via: "domain-control" }],
+    },
+    buyer: {
+      subject: ports.identity.payer,
+      assurance: "wallet-signature-only",
+      chain: [{ via: "key" }],
+    },
+  };
+  const base = {
+    depth: "mechanical" as const,
+    atrBytes: ports.atrBytes,
+    coverage: ports.coverage,
+    claimedClass: ports.claimedClass ?? ("TC-2" as TransactionClass),
+    asOf: ports.asOf,
+    // The settlement the buyer just made IS the enumeration it can honestly attest to (PAY).
+    settlements: [ref],
+    identity,
+  };
+  return verify(
+    "ok" in recovered ? { ...base, settledAtrHash: recovered.value } : base,
+  );
+}

package/src/policy.ts

@@ -0,0 +1,135 @@
+import type { Assurance } from "@integraledger/lcp-authority";
+import type { LegalContextJson } from "@integraledger/lcp-discovery";
+import type { Disposition } from "./decision.js";
+
+/**
+ * The buyer's stated policy.
+ *
+ * **`onNotAttempted` is the only gap disposition here, and its absent sibling is the point.** An earlier
+ * shape also required `onIndeterminate`, which `evaluate` never read — and could not have, because no step
+ * it runs yields `indeterminate`: the fingerprint proves or fails, and the record parses or does not. A
+ * required field promising a disposition the gate cannot reach is worse than no field, because a buyer
+ * reads it as a control. Consumers folding their own step ladders use `decideOutcome`, which carries its
+ * own four-valued gaps shape and does handle `indeterminate`.
+ */
+export interface BuyerPolicy {
+  readonly requiredLevel: 1 | 2 | 3 | 4;
+  readonly acceptableJurisdictions: readonly string[] | "any";
+  readonly acceptableDisputeMethods: readonly string[] | "any";
+  readonly maxCommitment: Readonly<Record<string, string>>;
+  readonly forbiddenClauseCategories: readonly string[];
+  readonly requiredAssurance: Assurance | "any";
+  readonly onNotAttempted: Disposition;
+}
+export type PolicyResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: string; readonly detail: string };
+
+const accepts = (
+  allow: readonly string[] | "any",
+  v: string | undefined,
+): boolean => (allow === "any" ? true : v !== undefined && allow.includes(v));
+
+/** Evaluate the buyer policy on the TYPED legal-context envelope + the typed offer — NEVER on prose (LCP §12.7).
+ *  Every check reads a structured field; the function's inputs cannot carry the natural-language body. */
+export function evaluatePolicy(
+  policy: BuyerPolicy,
+  terms: LegalContextJson,
+  offer: { amount: string; unit: string },
+): PolicyResult {
+  // NARROWED, not cast — the same treatment `clauseCategories` gets below, and for the same reason. The
+  // cast that stood here asserted `{ jurisdiction?: string; method?: string }` about a value the discovery
+  // parser never checked, which made the two fields policy actually reads the two the type system was not
+  // checking. It failed closed, so this was never a bypass: a seller publishing `"disputeResolution":
+  // "arbitration"` yielded `undefined` for both members and declined. It declined for the WRONG REASON —
+  // "jurisdiction (none) not acceptable" tells a seller its jurisdiction is unacceptable when its actual
+  // defect is that the field is a string. A gate whose refusals misdescribe the defect cannot be acted on,
+  // and being right by accident is not the same as being right.
+  const rawDr = (terms as { disputeResolution?: unknown }).disputeResolution;
+  if (
+    rawDr !== undefined &&
+    (typeof rawDr !== "object" || rawDr === null || Array.isArray(rawDr))
+  )
+    return {
+      ok: false,
+      code: "policy/malformed-dispute-resolution",
+      detail: `seller's disputeResolution is ${Array.isArray(rawDr) ? "an array" : rawDr === null ? "null" : typeof rawDr}, not an object`,
+    };
+  const drRecord = (rawDr ?? {}) as Readonly<Record<string, unknown>>;
+  // A member that is present and not a string is the seller's defect too, named rather than silently read
+  // as absent. Absent stays absent: that is the ordinary "no jurisdiction declared" path, and it is the
+  // buyer's stated policy that decides whether absence is acceptable.
+  for (const member of ["jurisdiction", "method"] as const) {
+    const v = drRecord[member];
+    if (v !== undefined && typeof v !== "string")
+      return {
+        ok: false,
+        code: "policy/malformed-dispute-resolution",
+        detail: `seller's disputeResolution.${member} is ${typeof v}, not a string`,
+      };
+  }
+  // NOT optionally chained, and the narrowing above is why. The cast that stood here produced a possibly
+  // absent object, so every read was `dr?.member`; the loop has now proved both members are a string or
+  // absent, so the object is always there and `?.` could never short-circuit. Mutation testing is what
+  // surfaced it — four optional-chaining mutants survived because no input could reach the branch they
+  // removed, which is the signature of a branch that cannot happen.
+  const jurisdiction = drRecord["jurisdiction"] as string | undefined;
+  const method = drRecord["method"] as string | undefined;
+  if (!accepts(policy.acceptableJurisdictions, jurisdiction))
+    return {
+      ok: false,
+      code: "policy/jurisdiction",
+      detail: `jurisdiction ${jurisdiction ?? "(none)"} not acceptable`,
+    };
+  if (!accepts(policy.acceptableDisputeMethods, method))
+    return {
+      ok: false,
+      code: "policy/dispute-method",
+      detail: `dispute method ${method ?? "(none)"} not acceptable`,
+    };
+  // `Object.hasOwn`, never a bare index read. `offer.unit` is SELLER-DERIVED — on the ACP path it is the
+  // session's `currency`, an unconstrained string — so a bare read answers from `Object.prototype` for
+  // `constructor`, `toString`, `valueOf`, `hasOwnProperty` or `__proto__`. Each returns a non-undefined
+  // non-string, slips past the `undefined` check below, and reaches `BigInt()`, which throws a SyntaxError
+  // out of `evaluate` naming nothing a buyer can act on. An own-property read makes every one of them the
+  // ordinary "no cap declared" decline.
+  const cap = Object.hasOwn(policy.maxCommitment, offer.unit)
+    ? policy.maxCommitment[offer.unit]
+    : undefined;
+  if (typeof cap !== "string")
+    return {
+      ok: false,
+      code: "policy/unit",
+      detail: `no cap declared for unit ${offer.unit}`,
+    };
+  if (BigInt(offer.amount) > BigInt(cap))
+    return {
+      ok: false,
+      code: "policy/over-cap",
+      detail: `offer ${offer.amount} exceeds cap ${cap} (${offer.unit})`,
+    };
+  // NARROWED, not cast. `clauseCategories` is not in the discovery schema at all — it arrives through the
+  // record's loose index signature as `unknown`, so it is whatever the SELLER wrote. A cast asserting
+  // `readonly string[]` was a claim about a hostile value: a seller publishing `"clauseCategories":
+  // "arbitration"` made `cats.find` a TypeError that escaped `evaluate` entirely, past its contract to
+  // RETURN a GateDecision. A malformed field is now the seller's defect, named as such and declined.
+  const raw = (terms as { clauseCategories?: unknown }).clauseCategories;
+  if (raw !== undefined && !Array.isArray(raw))
+    return {
+      ok: false,
+      code: "policy/malformed-clause-categories",
+      detail: `seller's clauseCategories is ${typeof raw}, not an array of category strings`,
+    };
+  const cats: readonly unknown[] = raw ?? [];
+  const forbidden = cats.find(
+    (c): c is string =>
+      typeof c === "string" && policy.forbiddenClauseCategories.includes(c),
+  );
+  if (forbidden !== undefined)
+    return {
+      ok: false,
+      code: "policy/forbidden-clause",
+      detail: `forbidden clause category: ${forbidden}`,
+    };
+  return { ok: true };
+}

package/src/proposal-ack.ts

@@ -0,0 +1,216 @@
+/**
+ * The ACK buyer surface: read an ACK-Pay `PaymentReceiptCredential` and say which rung of the record each
+ * half of it feeds.
+ *
+ * **There is deliberately no `GateProposal` here, and that is a finding about ACK rather than a gap.** Every
+ * other parser in this package turns a PROPOSAL into the typed inputs a buyer decides on. ACK has no
+ * proposal-time carrier to turn: read live at `agentcommercekit/ack@main` on 2026-07-30,
+ * `packages/ack-pay/src/schemas/valibot.ts` declares `paymentRequestSchema` as
+ * `{ id, description?, serviceCallback?, expiresAt?, paymentOptions }` — no `metadata`, no open field, no
+ * extension point anywhere on the request. The open map (`v.optional(v.record(v.string(), v.unknown()))`)
+ * exists on `paymentReceiptClaimSchema` ALONE. So an LCP reference reaches an ACK document only at receipt
+ * time, and manufacturing a `GateProposal` from a receipt would name a decision the buyer no longer has:
+ * the payment has already settled. What the receipt genuinely supports is post-settlement verification, and
+ * that is what this module produces.
+ *
+ * An ACK buyer that wants a decision BEFORE paying gets it the same way any Level 1–2 buyer does: from the
+ * seller's `/.well-known/legal-context.json` (LCP §2), which is out of band from ACK entirely.
+ */
+
+import { readAtPath } from "@integraledger/lcp-binding-core";
+import type { Artifact } from "@integraledger/lcp-evidence";
+import { ACK_PLACEMENT, ackPlacement } from "@integraledger/lcp-placement-ack";
+
+/**
+ * The DID methods ACK's own resolver registers — `packages/did/src/did-resolvers/get-did-resolver.ts`
+ * composes exactly four (`key-did-resolver`, `./web-did-resolver`, `jwks-did-resolver`,
+ * `./pkh-did-resolver`), read live 2026-07-30. A receipt naming any other method is one ACK's own chain
+ * could not have verified, so it is refused here rather than carried into a record as an identity nobody
+ * can resolve. `did:jwks` was still pending when earlier surveys of ACK were written and has since landed,
+ * which is why this list is cut from ACK's own resolver code rather than from any survey of it.
+ */
+export const ACK_DID_METHODS: readonly string[] = ["key", "web", "jwks", "pkh"];
+
+/**
+ * The leaf key names the LCP placement owns — DERIVED from the manifest so the two cannot drift.
+ *
+ * `readAlso` is OPTIONAL on `PlacementManifest` and manifests legitimately omit it, so `[]` is the CORRECT
+ * value for "this placement owns no alias keys" — under it `siblingRefKeys` rightly reports the un-owned key
+ * as one of ACK's own. Total handling of an optional field, not a fallback path: there is nothing here to
+ * fail loudly about. `ACK_PLACEMENT` declares an alias today, which is why the arm is unreached.
+ */
+function lcpKeys(): string[] {
+  const leaf = (path: string): string => path.slice(path.lastIndexOf(".") + 1);
+  return [
+    leaf(ACK_PLACEMENT.field),
+    ...(ACK_PLACEMENT.readAlso ?? []).map((alias) => leaf(alias.path)),
+  ];
+}
+
+function requireString(value: unknown, what: string): string {
+  if (typeof value !== "string" || value === "")
+    throw new Error(`ACK receipt: ${what} is absent or not a non-empty string`);
+  return value;
+}
+
+/** What an issued ACK receipt yields, before anything is decided about it. */
+export interface AckReceiptFacts {
+  /** The reference recovered from `credentialSubject.metadata`, through the placement's own manifest. */
+  readonly atrHash: `0x${string}`;
+  /** ACK's join key: the signed payment request this receipt attests, and no other. */
+  readonly paymentRequestToken: string;
+  /** Which of the request's `paymentOptions` was taken. */
+  readonly paymentOptionId: string;
+  /** `credentialSubject.id` — the payer DID the receipt attributes the payment to. */
+  readonly payerDid: string;
+  /** The payer DID's method, narrowed to `ACK_DID_METHODS`. */
+  readonly payerDidMethod: string;
+  /** `issuer.id` — the receipt service that signed. Recorded; never mistaken for the payer. */
+  readonly issuerDid: string;
+  /**
+   * The other keys ACK's own audit trail put in the same map, in wire order — `policyRef`, `mandateRef`,
+   * `executionRef`, `executionReceiptHash`, `settlementNetwork`, `settlementReference` and whatever else a
+   * deployment added. Reported because a record composer wants to know what else this receipt
+   * cross-references, and because naming them is the honest form of "we are a guest in this map": we read
+   * exactly one key and own none of the rest.
+   */
+  readonly siblingRefKeys: readonly string[];
+}
+
+/**
+ * Parse an ISSUED `PaymentReceiptCredential` into its facts. Fail-fast on every departure from what ACK's
+ * own code emits — a receipt this cannot read is one ACK's verification chain could not have produced.
+ *
+ * **The unissued receipt is refused, and it is the mirror of the seller's rule.**
+ * `placement-ack.place` refuses a credential that ALREADY carries a `proof`, because a field added after
+ * issuance either breaks the embedded signature or falls outside the JWT payload ACK treats as
+ * authoritative. This refuses one that does NOT YET carry one, because a credential nobody signed attests
+ * nothing and must not reach a record as evidence of a payment. Between the two rules the reference can
+ * only ever ride a receipt the issuer signed over. The predicate is ACK's own — `isDecodedCredential`
+ * accepts a value iff `"proof" in value && value.proof != null` — mirrored, so a `null` proof is unissued
+ * by the host's rule and is unissued here.
+ */
+export function parseAckReceipt(credential: unknown): AckReceiptFacts {
+  const proof = readAtPath(credential, "proof");
+  if (proof === undefined || proof === null)
+    throw new Error(
+      "ack/receipt-not-issued: this credential carries no proof — a receipt nobody signed attests nothing, " +
+        "and the reference it carries is outside anything ACK's verification chain would return",
+    );
+
+  const issuerDid = requireString(
+    readAtPath(credential, "issuer.id"),
+    "issuer.id (ACK's own createCredential emits `issuer: { id: issuer }`, never a bare string)",
+  );
+  const payerDid = requireString(
+    readAtPath(credential, "credentialSubject.id"),
+    "credentialSubject.id",
+  );
+  const [scheme, method] = payerDid.split(":");
+  if (
+    scheme !== "did" ||
+    method === undefined ||
+    !ACK_DID_METHODS.includes(method)
+  )
+    throw new Error(
+      `ACK receipt: "${payerDid}" is not a did uri in a did method ACK resolves (${ACK_DID_METHODS.join(", ")})`,
+    );
+  const paymentRequestToken = requireString(
+    readAtPath(credential, "credentialSubject.paymentRequestToken"),
+    "credentialSubject.paymentRequestToken",
+  );
+  const paymentOptionId = requireString(
+    readAtPath(credential, "credentialSubject.paymentOptionId"),
+    "credentialSubject.paymentOptionId",
+  );
+
+  const extracted = ackPlacement.extract(credential);
+  if (!("ok" in extracted))
+    throw new Error(
+      `ACK receipt carries no readable LCP reference (${extracted.haltClass}/${extracted.code})`,
+    );
+  if (extracted.value.type !== "sha256")
+    throw new Error(
+      `ACK legalContext must be a sha256 carrier, got "${extracted.value.type}" — a locator commits to nothing`,
+    );
+
+  const owned = lcpKeys();
+  // `extract` above read the LCP key out of THIS map, so the map is an object and the narrowing cannot
+  // fail. Asserted rather than branched: a defensive `typeof` ternary here would ship an else-arm no input
+  // can reach, and its silent `[]` would under-report ACK's own refs on a receipt that has them.
+  const metadata = readAtPath(
+    credential,
+    "credentialSubject.metadata",
+  ) as Record<string, unknown>;
+  const siblingRefKeys = Object.keys(metadata).filter(
+    (k) => !owned.includes(k),
+  );
+
+  return {
+    atrHash: extracted.value.value as `0x${string}`,
+    paymentRequestToken,
+    paymentOptionId,
+    payerDid,
+    payerDidMethod: method,
+    issuerDid,
+    siblingRefKeys,
+  };
+}
+
+/**
+ * The receipt's contribution to a post-settlement `verify` call, with each field naming the rung it feeds.
+ *
+ * The first of ACK's two hard edges, answered in code rather than in prose: the `PaymentReceiptCredential` is
+ * **both** an evidence artifact and an identity input, and the split is here.
+ */
+export interface AckReceiptContribution {
+  /** Feeds `VerifyInput.placement` — the reference recovered from the host protocol's OWN document. */
+  readonly placement: { readonly extracted: unknown };
+  /**
+   * RCS-4 → one `evidence.Artifact` under the `settlement` role.
+   *
+   * `settlement` rather than `attestation`: an ACK receipt IS ACK's settlement artifact — the credential
+   * that attests the payment happened, carrying the `paymentRequestToken` it settled and, by convention,
+   * ACK's own `settlementNetwork`/`settlementReference`. `settlement` is one of `RCS4_REQUIRED_ROLES`, so
+   * filing it correctly is what lets an ACK record's evidence package be complete; filing it under
+   * `attestation` would leave the settlement role empty while double-filling one that is already occupied
+   * by the identity attestation.
+   */
+  readonly artifact: Artifact;
+  /** IDN-1 → the payer `resolve-party` attributes the payment to. */
+  readonly payerDid: string;
+  /**
+   * The payer DID's method — and NOT an assurance level.
+   *
+   * ACK's second hard edge: `did:web` / `did:jwks` resolution reuses the existing identity path rather than
+   * minting a second one, and that path authors identity SELLER-side — the record's IDN content is
+   * seller-authored. A buyer verifying a record reads the assurance the record already states; restating it
+   * here would be a second authority on the same fact. The mapping from ACK's four DID methods to an
+   * `authority.Assurance` therefore lives once, on the seller side, and this surface stops at the method.
+   */
+  readonly payerDidMethod: string;
+  /** The receipt service that signed. Recorded on the record; never the payer. */
+  readonly issuerDid: string;
+  /** ACK's join key — the guard against reading a receipt against a payment request it never attested. */
+  readonly paymentRequestToken: string;
+}
+
+/**
+ * Split an issued receipt into its two rungs. `receiptBytes` are the retained credential exactly as it was
+ * received — the artifact is the bytes, not a re-serialization of the parse, because what the evidence
+ * package must hold is what the issuer signed.
+ */
+export function ackReceiptContribution(
+  credential: unknown,
+  receiptBytes: Uint8Array,
+): AckReceiptContribution {
+  const facts = parseAckReceipt(credential);
+  return {
+    placement: { extracted: { type: "sha256", value: facts.atrHash } },
+    artifact: { role: "settlement", bytes: receiptBytes },
+    payerDid: facts.payerDid,
+    payerDidMethod: facts.payerDidMethod,
+    issuerDid: facts.issuerDid,
+    paymentRequestToken: facts.paymentRequestToken,
+  };
+}

package/src/proposal-acp.ts

@@ -0,0 +1,89 @@
+import { decodeLegalContextString } from "@integraledger/lcp-binding-core";
+import { z } from "zod";
+import type { GateProposal, ProposalContext } from "./proposal.js";
+
+// Module-internal structural view of the ACP checkout session (NOT the seller's type — buyer ≠ seller).
+// The session object is TOP-LEVEL and `totals` is an ARRAY (stable 2026-04-17); there is no `checkout`
+// wrapper and no `total` string. z.object strips unknown keys, so a real session's many other fields are
+// harmlessly ignored. Kept internal and not z.infer-exported (isolatedDeclarations), exactly as
+// X402ChallengeSchema is in proposal.ts.
+const AcpSessionSchema = z.object({
+  currency: z.string(),
+  totals: z.array(z.object({ type: z.string(), amount: z.number() })),
+  metadata: z.object({
+    legal_context: z.string(),
+    legal_context_url: z.string(),
+  }),
+});
+
+/**
+ * Parse an ACP checkout session into the SAME typed `GateProposal` the x402 parser produces (the LCP §12.7
+ * boundary — no prose field on the type). Fail-fast (throws) on a malformed session, a reference that is not
+ * a canonical `lcp:sha256:0x…` 32-byte carrier, a non-HTTPS terms URL, a missing `total` row, or a
+ * non-integer minor-unit amount.
+ *
+ * `legal_context_url` is required, and the ACP placement manifest DECLARES it as
+ * `termsUrlField: "metadata.legal_context_url"` — the field this parser demands is a field the placement
+ * names, which is what makes the round-trip compose. It is deliberately NOT read from ACP's native
+ * `links[type=terms_of_use]`: that link is the merchant's standing policy page, while this names the ATR
+ * terms document for this transaction, and falling back to it would substitute one for the other.
+ *
+ * `GateProposal` and `ProposalContext` are IMPORTED, never redefined — one type for every wire is the whole
+ * point of a single typed proposal, and a second copy would let the two drift.
+ */
+export function parseProposalFromAcpCheckout(
+  session: unknown,
+  ctx: ProposalContext,
+): GateProposal {
+  const parsed = AcpSessionSchema.parse(session);
+  const { legal_context, legal_context_url } = parsed.metadata;
+
+  // Decoded through binding-core's codec, never by slicing a prefix. The codec enforces the canonical
+  // sha256 carrier form (0x-prefixed 32-byte hex) — a bare-digits value throws here rather than being
+  // silently re-prefixed into something that looks valid. An earlier draft did `0x${slice(...)}`, which
+  // turned a CONFORMANT 0x-carrying reference into `0x0x…` and accepted the non-canonical form instead.
+  const ref = decodeLegalContextString(legal_context);
+  if (ref === undefined)
+    throw new Error(
+      `ACP legal_context is not a parseable lcp: reference: ${legal_context}`,
+    );
+  if (ref.type !== "sha256")
+    throw new Error(
+      `ACP legal_context must be an lcp:sha256: reference, got lcp:${ref.type}:`,
+    );
+  // No 0x-32-byte re-check here. `decodeLegalContextString` runs `assertValidValue`, which for `sha256`
+  // IS `kernel.isAtrHash` — the identical `/^0x[0-9a-fA-F]{64}$/`. A second copy of that regex could not
+  // reject anything the decode admitted: it would be a branch no input reaches, permanently unkillable by
+  // any test, and it would tell a reader there is a case here that there is not. The x402 parser carries
+  // its own check because it reads a RAW `extra.atrHash` string that no codec has validated; this one
+  // does not, and that asymmetry is the point rather than an oversight.
+
+  if (!legal_context_url.startsWith("https://"))
+    throw new Error(`legalContextUrl must be HTTPS: ${legal_context_url}`);
+
+  // The `total` ROW, never the first row and never a sum. ACP's `totals` carries several typed rows
+  // (`items_base_amount`, `tax`, `fee`, `discount`, …) and only the one typed `total` is the amount the
+  // buyer is being asked to authorize. There is deliberately no fallback: a session with no `total` row is
+  // malformed, and picking another row would gate the buyer against a number nobody quoted.
+  const total = parsed.totals.find((t) => t.type === "total");
+  if (total === undefined)
+    throw new Error(
+      "ACP session carries no row typed `total` — nothing to authorize against",
+    );
+  if (!Number.isSafeInteger(total.amount) || total.amount < 0)
+    throw new Error(
+      `offer amount must be a non-negative minor-unit integer: ${total.amount}`,
+    );
+
+  return {
+    advertisedAtrHash: ref.value as `0x${string}`,
+    legalContextUrl: legal_context_url,
+    level: ctx.level,
+    offer: {
+      amount: String(total.amount),
+      // ACP settles in a fiat currency code, not a network:asset pair — the unit string says which.
+      unit: parsed.currency,
+    },
+    sellerAssurance: ctx.sellerAssurance,
+  };
+}