@peac/adapter-x402 0.12.9 → 0.12.11

package/dist/index.d.ts

@@ -35,4 +35,6 @@ export type { X402HeaderMap, X402ResponseLike, X402ExtractResult, X402ExtractAsy
 export { X402_CARRIER_LIMITS, extractReceiptArtifactFromHeaders, fromOfferResponse, fromOfferResponseAsync, fromSettlementResponse, fromSettlementResponseAsync, X402CarrierAdapter, } from './carrier.js';
 export type { ChallengeType } from './challenge.js';
 export { mapX402ToChallengeType } from './challenge.js';
+export { extractSettlementProofFromHeaders, fromX402SettlementObservation } from './settlement.js';
+export type { HeaderBag, SettlementProofSource, ExtractedSettlementProof, X402SettlementObservationInput, X402SettlementEvidence, X402SettlementOptions, } from './settlement.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -14,7 +14,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mapX402ToChallengeType = exports.X402CarrierAdapter = exports.fromSettlementResponseAsync = exports.fromSettlementResponse = exports.fromOfferResponseAsync = exports.fromOfferResponse = exports.extractReceiptArtifactFromHeaders = exports.X402_CARRIER_LIMITS = exports.toPeacCarrier = exports.toPeacRecordV2 = exports.toPeacRecord = exports.selectAccept = exports.matchAcceptTerms = exports.verifyOfferReceiptConsistency = exports.verifyReceiptWire = exports.verifyOfferWire = exports.verifyReceiptUnified = exports.verifyOfferUnified = exports.verifyReceiptV2 = exports.verifyOfferV2 = exports.verifyReceipt = exports.verifyOffer = exports.X402Error = exports.defaultAddressComparator = exports.MAX_AMOUNT_LENGTH = exports.MAX_TOTAL_ACCEPTS_BYTES = exports.MAX_ACCEPT_ENTRIES = exports.X402_OFFER_RECEIPT_PROFILE = exports.normalizeV2Receipt = exports.normalizeV2Offers = exports.normalizeV2Offer = exports.normalizeReceiptPayload = exports.normalizeOfferPayload = exports.detectX402VersionFromSource = exports.detectX402Version = exports.X402_V2_HEADERS = exports.extractReceiptFromHeaders = exports.extractExtensionInfo = exports.extractReceiptPayload = exports.extractOfferPayload = exports.parseCompactJWS = exports.X402_RECEIPT_HEADERS = exports.MAX_COMPACT_JWS_BYTES = exports.OFFER_RECEIPT = void 0;
+exports.fromX402SettlementObservation = exports.extractSettlementProofFromHeaders = exports.mapX402ToChallengeType = exports.X402CarrierAdapter = exports.fromSettlementResponseAsync = exports.fromSettlementResponse = exports.fromOfferResponseAsync = exports.fromOfferResponse = exports.extractReceiptArtifactFromHeaders = exports.X402_CARRIER_LIMITS = exports.toPeacCarrier = exports.toPeacRecordV2 = exports.toPeacRecord = exports.selectAccept = exports.matchAcceptTerms = exports.verifyOfferReceiptConsistency = exports.verifyReceiptWire = exports.verifyOfferWire = exports.verifyReceiptUnified = exports.verifyOfferUnified = exports.verifyReceiptV2 = exports.verifyOfferV2 = exports.verifyReceipt = exports.verifyOffer = exports.X402Error = exports.defaultAddressComparator = exports.MAX_AMOUNT_LENGTH = exports.MAX_TOTAL_ACCEPTS_BYTES = exports.MAX_ACCEPT_ENTRIES = exports.X402_OFFER_RECEIPT_PROFILE = exports.normalizeV2Receipt = exports.normalizeV2Offers = exports.normalizeV2Offer = exports.normalizeReceiptPayload = exports.normalizeOfferPayload = exports.detectX402VersionFromSource = exports.detectX402Version = exports.X402_V2_HEADERS = exports.extractReceiptFromHeaders = exports.extractExtensionInfo = exports.extractReceiptPayload = exports.extractOfferPayload = exports.parseCompactJWS = exports.X402_RECEIPT_HEADERS = exports.MAX_COMPACT_JWS_BYTES = exports.OFFER_RECEIPT = void 0;
 var raw_js_1 = require("./raw.js");
 Object.defineProperty(exports, "OFFER_RECEIPT", { enumerable: true, get: function () { return raw_js_1.OFFER_RECEIPT; } });
 Object.defineProperty(exports, "MAX_COMPACT_JWS_BYTES", { enumerable: true, get: function () { return raw_js_1.MAX_COMPACT_JWS_BYTES; } });
@@ -74,4 +74,8 @@ Object.defineProperty(exports, "fromSettlementResponseAsync", { enumerable: true
 Object.defineProperty(exports, "X402CarrierAdapter", { enumerable: true, get: function () { return carrier_js_1.X402CarrierAdapter; } });
 var challenge_js_1 = require("./challenge.js");
 Object.defineProperty(exports, "mapX402ToChallengeType", { enumerable: true, get: function () { return challenge_js_1.mapX402ToChallengeType; } });
+// x402 settlement-proof extraction and observation evidence (v0.12.11)
+var settlement_js_1 = require("./settlement.js");
+Object.defineProperty(exports, "extractSettlementProofFromHeaders", { enumerable: true, get: function () { return settlement_js_1.extractSettlementProofFromHeaders; } });
+Object.defineProperty(exports, "fromX402SettlementObservation", { enumerable: true, get: function () { return settlement_js_1.fromX402SettlementObservation; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAgBH,mCASkB;AARhB,uGAAA,aAAa,OAAA;AACb,+GAAA,qBAAqB,OAAA;AACrB,8GAAA,oBAAoB,OAAA;AACpB,yGAAA,eAAe,OAAA;AACf,6GAAA,mBAAmB,OAAA;AACnB,+GAAA,qBAAqB,OAAA;AACrB,8GAAA,oBAAoB,OAAA;AACpB,mHAAA,yBAAyB,OAAA;AAgB3B,yCAA8C;AAArC,4GAAA,eAAe,OAAA;AAIxB,2CAA8E;AAArE,+GAAA,iBAAiB,OAAA;AAAE,yHAAA,2BAA2B,OAAA;AAKvD,+CAAgF;AAAvE,qHAAA,qBAAqB,OAAA;AAAE,uHAAA,uBAAuB,OAAA;AAIvD,qDAA4F;AAAnF,mHAAA,gBAAgB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAAE,qHAAA,kBAAkB,OAAA;AA+BhE,qCAAqC;AACrC,uCAMoB;AALlB,sHAAA,0BAA0B,OAAA;AAC1B,8GAAA,kBAAkB,OAAA;AAClB,mHAAA,uBAAuB,OAAA;AACvB,6GAAA,iBAAiB,OAAA;AACjB,oHAAA,wBAAwB,OAAA;AAM1B,SAAS;AACT,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,eAAe;AACf,yCAYqB;AAXnB,wGAAA,WAAW,OAAA;AACX,0GAAA,aAAa,OAAA;AACb,0GAAA,aAAa,OAAA;AACb,4GAAA,eAAe,OAAA;AACf,+GAAA,kBAAkB,OAAA;AAClB,iHAAA,oBAAoB,OAAA;AACpB,4GAAA,eAAe,OAAA;AACf,8GAAA,iBAAiB,OAAA;AACjB,0HAAA,6BAA6B,OAAA;AAC7B,6GAAA,gBAAgB,OAAA;AAChB,yGAAA,YAAY,OAAA;AAId,UAAU;AACV,mCAAuE;AAA9D,sGAAA,YAAY,OAAA;AAAE,wGAAA,cAAc,OAAA;AAAE,uGAAA,aAAa,OAAA;AAepD,2CAQsB;AAPpB,iHAAA,mBAAmB,OAAA;AACnB,+HAAA,iCAAiC,OAAA;AACjC,+GAAA,iBAAiB,OAAA;AACjB,oHAAA,sBAAsB,OAAA;AACtB,oHAAA,sBAAsB,OAAA;AACtB,yHAAA,2BAA2B,OAAA;AAC3B,gHAAA,kBAAkB,OAAA;AAKpB,+CAAwD;AAA/C,sHAAA,sBAAsB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAgBH,mCASkB;AARhB,uGAAA,aAAa,OAAA;AACb,+GAAA,qBAAqB,OAAA;AACrB,8GAAA,oBAAoB,OAAA;AACpB,yGAAA,eAAe,OAAA;AACf,6GAAA,mBAAmB,OAAA;AACnB,+GAAA,qBAAqB,OAAA;AACrB,8GAAA,oBAAoB,OAAA;AACpB,mHAAA,yBAAyB,OAAA;AAgB3B,yCAA8C;AAArC,4GAAA,eAAe,OAAA;AAIxB,2CAA8E;AAArE,+GAAA,iBAAiB,OAAA;AAAE,yHAAA,2BAA2B,OAAA;AAKvD,+CAAgF;AAAvE,qHAAA,qBAAqB,OAAA;AAAE,uHAAA,uBAAuB,OAAA;AAIvD,qDAA4F;AAAnF,mHAAA,gBAAgB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAAE,qHAAA,kBAAkB,OAAA;AA+BhE,qCAAqC;AACrC,uCAMoB;AALlB,sHAAA,0BAA0B,OAAA;AAC1B,8GAAA,kBAAkB,OAAA;AAClB,mHAAA,uBAAuB,OAAA;AACvB,6GAAA,iBAAiB,OAAA;AACjB,oHAAA,wBAAwB,OAAA;AAM1B,SAAS;AACT,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,eAAe;AACf,yCAYqB;AAXnB,wGAAA,WAAW,OAAA;AACX,0GAAA,aAAa,OAAA;AACb,0GAAA,aAAa,OAAA;AACb,4GAAA,eAAe,OAAA;AACf,+GAAA,kBAAkB,OAAA;AAClB,iHAAA,oBAAoB,OAAA;AACpB,4GAAA,eAAe,OAAA;AACf,8GAAA,iBAAiB,OAAA;AACjB,0HAAA,6BAA6B,OAAA;AAC7B,6GAAA,gBAAgB,OAAA;AAChB,yGAAA,YAAY,OAAA;AAId,UAAU;AACV,mCAAuE;AAA9D,sGAAA,YAAY,OAAA;AAAE,wGAAA,cAAc,OAAA;AAAE,uGAAA,aAAa,OAAA;AAepD,2CAQsB;AAPpB,iHAAA,mBAAmB,OAAA;AACnB,+HAAA,iCAAiC,OAAA;AACjC,+GAAA,iBAAiB,OAAA;AACjB,oHAAA,sBAAsB,OAAA;AACtB,oHAAA,sBAAsB,OAAA;AACtB,yHAAA,2BAA2B,OAAA;AAC3B,gHAAA,kBAAkB,OAAA;AAKpB,+CAAwD;AAA/C,sHAAA,sBAAsB,OAAA;AAE/B,uEAAuE;AACvE,iDAAmG;AAA1F,kIAAA,iCAAiC,OAAA;AAAE,8HAAA,6BAA6B,OAAA"}

package/dist/settlement.d.ts

@@ -0,0 +1,120 @@
+/**
+ * x402 settlement-proof extraction and observation evidence (v0.12.11).
+ *
+ * Observational only: PEAC reads what the upstream x402 settlement proof
+ * attested when present. PEAC does NOT verify scheme-specific invariants
+ * (single-use, time bounds, recipient binding, facilitator binding, max-
+ * vs-actual settlement correctness). Those remain the responsibility of
+ * the upstream x402 protocol and the per-operator facilitator surfaces;
+ * see docs/compatibility/x402-scheme-coverage.md for the three-truth-
+ * surface separation.
+ *
+ * Header read precedence (matches the existing carrier reader at
+ * src/carrier.ts):
+ *   1. PEAC-Receipt           (PEAC carrier contract)
+ *   2. PAYMENT-RESPONSE       (x402 v2)
+ *   3. X-PAYMENT-RESPONSE     (x402 v1)
+ *
+ * If multiple proofs are present, all are returned in precedence order so
+ * callers can record duplicates without losing fidelity.
+ */
+import { type StrictnessMode, type FinalityGuardOptions } from '@peac/adapter-core';
+/** Header-bag accepted by the extractor. Lower-case keys are tried first. */
+export type HeaderBag = Record<string, string | string[] | undefined>;
+/** Source identifier for an extracted settlement proof. */
+export type SettlementProofSource = 'PEAC-Receipt' | 'PAYMENT-RESPONSE' | 'X-PAYMENT-RESPONSE';
+/** A single settlement-proof artifact extracted from response headers. */
+export interface ExtractedSettlementProof {
+    source: SettlementProofSource;
+    /**
+     * Wire version implied by the source header. PEAC-Receipt is wire-
+     * neutral and reports `'peac'`; v2 reports `'v2'`; v1 reports `'v1'`.
+     */
+    wire_version: 'peac' | 'v2' | 'v1';
+    /** The raw header value, byte-preserved. */
+    raw_value: string;
+}
+/**
+ * Extract any x402 settlement-proof artifacts from the supplied response
+ * headers. Returns artifacts in dual-header precedence order (PEAC-Receipt
+ * first, then PAYMENT-RESPONSE v2, then X-PAYMENT-RESPONSE v1). An empty
+ * array means no settlement proof was supplied; callers MUST NOT treat
+ * absence as evidence of settlement.
+ *
+ * Observation only: this function does not parse or verify the artifacts.
+ * Scheme-specific invariants remain upstream responsibility.
+ */
+export declare function extractSettlementProofFromHeaders(headers: HeaderBag): ExtractedSettlementProof[];
+/**
+ * Input for fromX402SettlementObservation.
+ *
+ * Models a single explicit x402 settlement observation. Callers supply
+ * the raw extracted proof plus the upstream-asserted offer / settlement
+ * fields; the mapper performs no scheme-specific verification. PEAC will
+ * reject any attempt to produce settlement evidence from offer-only data.
+ */
+export interface X402SettlementObservationInput {
+    /** Settlement-proof artifact, e.g. one element of extractSettlementProofFromHeaders. */
+    proof: ExtractedSettlementProof;
+    /** x402 scheme identifier as asserted by upstream. Preserved verbatim. */
+    scheme: string;
+    /** Network identifier as asserted by upstream. Preserved verbatim. */
+    network: string;
+    /** Asset identifier as asserted by upstream. */
+    asset: string;
+    /** Currency code as asserted by upstream. Required in strict mode. */
+    currency: string;
+    /** Settled amount in minor units (smallest currency unit). */
+    amount_minor: string;
+    /** Environment as asserted by upstream. */
+    env: 'live' | 'test';
+    /** Recipient (payTo) address from the proof. Preserved verbatim. */
+    pay_to?: string;
+    /** Optional facilitator identifier; PEAC does not bind facilitators. */
+    facilitator?: string;
+    /** Optional offer reference for correlation. Observation only. */
+    offer_reference?: string;
+}
+/** Output of fromX402SettlementObservation. */
+export interface X402SettlementEvidence {
+    rail: 'x402';
+    reference: string;
+    amount: number;
+    currency: string;
+    asset: string;
+    env: 'live' | 'test';
+    evidence: {
+        commerce_event: 'settlement';
+        x402_scheme: string;
+        x402_network: string;
+        x402_pay_to?: string;
+        x402_facilitator?: string;
+        x402_offer_reference?: string;
+        proofs: {
+            x402: {
+                settlement: {
+                    source: SettlementProofSource;
+                    wire_version: 'peac' | 'v2' | 'v1';
+                    raw_value: string;
+                };
+            };
+        };
+    };
+}
+export interface X402SettlementOptions {
+    mode?: StrictnessMode;
+    warn?: FinalityGuardOptions['warn'];
+}
+/**
+ * Map an explicit x402 settlement observation to PEAC commerce evidence
+ * with commerce.event = 'settlement'. Routes through the mapper-boundary
+ * finality-synthesis guard. Refuses synthesis from offer-only data: the
+ * caller MUST supply an extracted settlement-proof artifact whose
+ * wire_version is one of 'peac' | 'v2' | 'v1'. Empty input rejects in
+ * all strictness modes (rule 1).
+ *
+ * Observation only: PEAC does not verify scheme invariants; the proof is
+ * preserved verbatim under proofs.x402.settlement.
+ */
+export declare function fromX402SettlementObservation(input: X402SettlementObservationInput, options?: X402SettlementOptions): X402SettlementEvidence;
+//# sourceMappingURL=settlement.d.ts.map

package/dist/settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAEtE,2DAA2D;AAC3D,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAE/F,0EAA0E;AAC1E,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,qBAAqB,CAAC;IAC9B;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACnC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,SAAS,GAAG,wBAAwB,EAAE,CAiBhG;AAgBD;;;;;;;GAOG;AACH,MAAM,WAAW,8BAA8B;IAC7C,wFAAwF;IACxF,KAAK,EAAE,wBAAwB,CAAC;IAChC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,QAAQ,EAAE;QACR,cAAc,EAAE,YAAY,CAAC;QAC7B,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,MAAM,EAAE;YACN,IAAI,EAAE;gBACJ,UAAU,EAAE;oBACV,MAAM,EAAE,qBAAqB,CAAC;oBAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;oBACnC,SAAS,EAAE,MAAM,CAAC;iBACnB,CAAC;aACH,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,IAAI,CAAC,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,8BAA8B,EACrC,OAAO,GAAE,qBAA0B,GAClC,sBAAsB,CA2DxB"}

package/dist/settlement.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * x402 settlement-proof extraction and observation evidence (v0.12.11).
+ *
+ * Observational only: PEAC reads what the upstream x402 settlement proof
+ * attested when present. PEAC does NOT verify scheme-specific invariants
+ * (single-use, time bounds, recipient binding, facilitator binding, max-
+ * vs-actual settlement correctness). Those remain the responsibility of
+ * the upstream x402 protocol and the per-operator facilitator surfaces;
+ * see docs/compatibility/x402-scheme-coverage.md for the three-truth-
+ * surface separation.
+ *
+ * Header read precedence (matches the existing carrier reader at
+ * src/carrier.ts):
+ *   1. PEAC-Receipt           (PEAC carrier contract)
+ *   2. PAYMENT-RESPONSE       (x402 v2)
+ *   3. X-PAYMENT-RESPONSE     (x402 v1)
+ *
+ * If multiple proofs are present, all are returned in precedence order so
+ * callers can record duplicates without losing fidelity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSettlementProofFromHeaders = extractSettlementProofFromHeaders;
+exports.fromX402SettlementObservation = fromX402SettlementObservation;
+const adapter_core_1 = require("@peac/adapter-core");
+/**
+ * Extract any x402 settlement-proof artifacts from the supplied response
+ * headers. Returns artifacts in dual-header precedence order (PEAC-Receipt
+ * first, then PAYMENT-RESPONSE v2, then X-PAYMENT-RESPONSE v1). An empty
+ * array means no settlement proof was supplied; callers MUST NOT treat
+ * absence as evidence of settlement.
+ *
+ * Observation only: this function does not parse or verify the artifacts.
+ * Scheme-specific invariants remain upstream responsibility.
+ */
+function extractSettlementProofFromHeaders(headers) {
+    const out = [];
+    const lower = normalizeHeaders(headers);
+    const peac = lower['peac-receipt'];
+    if (peac !== undefined) {
+        out.push({ source: 'PEAC-Receipt', wire_version: 'peac', raw_value: peac });
+    }
+    const v2 = lower['payment-response'];
+    if (v2 !== undefined) {
+        out.push({ source: 'PAYMENT-RESPONSE', wire_version: 'v2', raw_value: v2 });
+    }
+    const v1 = lower['x-payment-response'];
+    if (v1 !== undefined) {
+        out.push({ source: 'X-PAYMENT-RESPONSE', wire_version: 'v1', raw_value: v1 });
+    }
+    return out;
+}
+function normalizeHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v === undefined)
+            continue;
+        const key = k.toLowerCase();
+        if (Array.isArray(v)) {
+            out[key] = v.join(', ');
+        }
+        else {
+            out[key] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Map an explicit x402 settlement observation to PEAC commerce evidence
+ * with commerce.event = 'settlement'. Routes through the mapper-boundary
+ * finality-synthesis guard. Refuses synthesis from offer-only data: the
+ * caller MUST supply an extracted settlement-proof artifact whose
+ * wire_version is one of 'peac' | 'v2' | 'v1'. Empty input rejects in
+ * all strictness modes (rule 1).
+ *
+ * Observation only: PEAC does not verify scheme invariants; the proof is
+ * preserved verbatim under proofs.x402.settlement.
+ */
+function fromX402SettlementObservation(input, options = {}) {
+    if (!input.scheme) {
+        throw new Error('x402 settlement observation missing scheme');
+    }
+    if (!input.network) {
+        throw new Error('x402 settlement observation missing network');
+    }
+    if (!/^-?[0-9]+$/.test(input.amount_minor)) {
+        throw new Error('x402 settlement observation amount_minor must be a base-10 integer string');
+    }
+    const hasExplicitUpstreamArtifact = input.proof !== undefined &&
+        typeof input.proof.raw_value === 'string' &&
+        input.proof.raw_value.length > 0;
+    (0, adapter_core_1.assertExplicitFinality)({
+        event: 'settlement',
+        hasExplicitUpstreamArtifact,
+        currency: input.currency,
+        env: input.env,
+        envExplicit: input.env === 'live' || input.env === 'test',
+    }, {
+        mode: options.mode,
+        warn: options.warn,
+        pointer: '/proofs/x402/settlement',
+    });
+    const amount = parseInt(input.amount_minor, 10);
+    return {
+        rail: 'x402',
+        reference: input.offer_reference ?? input.proof.source,
+        amount,
+        currency: input.currency.toUpperCase(),
+        asset: input.asset,
+        env: input.env,
+        evidence: {
+            commerce_event: 'settlement',
+            x402_scheme: input.scheme,
+            x402_network: input.network,
+            ...(input.pay_to !== undefined ? { x402_pay_to: input.pay_to } : {}),
+            ...(input.facilitator !== undefined ? { x402_facilitator: input.facilitator } : {}),
+            ...(input.offer_reference !== undefined
+                ? { x402_offer_reference: input.offer_reference }
+                : {}),
+            proofs: {
+                x402: {
+                    settlement: {
+                        source: input.proof.source,
+                        wire_version: input.proof.wire_version,
+                        raw_value: input.proof.raw_value,
+                    },
+                },
+            },
+        },
+    };
+}
+//# sourceMappingURL=settlement.js.map

package/dist/settlement.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/adapter-x402",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "description": "x402 offer/receipt verification, term-matching, and PEAC record mapping",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,10 +19,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@peac/adapter-core": "0.12.9",
-    "@peac/kernel": "0.12.9",
-    "@peac/crypto": "0.12.9",
-    "@peac/schema": "0.12.9"
+    "@peac/adapter-core": "0.12.11",
+    "@peac/crypto": "0.12.11",
+    "@peac/kernel": "0.12.11",
+    "@peac/schema": "0.12.11"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",