@peac/audit 0.12.2 → 0.12.4

package/dist/commerce-bundle-types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Commerce evidence bundle types (experimental, DD-192).
+ *
+ * Cross-ecosystem commerce evidence correlation without aggregating
+ * or asserting settlement totals. Non-aggregating by default.
+ *
+ * Promotion gate (must be met before removing -experimental suffix):
+ * - At least 2 independent producers
+ * - At least 1 independent verifier path
+ * - Documented in a versioned spec
+ */
+/** Bundle format version */
+export declare const COMMERCE_BUNDLE_VERSION: "peac.commerce-bundle/0.1-experimental";
+/** Source discriminant for protocol-specific evidence */
+export interface ProtocolEvidence {
+    /** Protocol source identifier */
+    source: string;
+    /** Timestamp of the evidence capture */
+    captured_at: string;
+    /** Protocol-specific evidence data */
+    data: Record<string, unknown>;
+}
+/** Timeline entry for chronological event tracking */
+export interface TimelineEntry {
+    /** Timestamp of the event */
+    timestamp: string;
+    /** Protocol source */
+    source: string;
+    /** Event description */
+    event: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Individual observed amount (non-aggregated) */
+export interface ObservedAmount {
+    /** Protocol source that reported this amount */
+    source: string;
+    /** Amount in minor units (string for arbitrary precision) */
+    amount: string;
+    /** Currency code */
+    currency: string;
+    /** Semantic stage if known (e.g., "authorization", "settlement") */
+    semantic_stage?: string;
+}
+/** Commerce summary: observation-set, NOT aggregation */
+export interface CommerceSummary {
+    /** Individual observed amounts from each source (not rolled up) */
+    observed_amounts: ObservedAmount[];
+    /** Currencies observed across all sources */
+    currencies_observed: string[];
+    /** Payment rails observed */
+    rails_observed: string[];
+    /** Count of protocol evidence snapshots */
+    evidence_count: number;
+}
+/** Commerce evidence bundle */
+export interface CommerceEvidenceBundle {
+    /** Format version (includes -experimental suffix) */
+    version: typeof COMMERCE_BUNDLE_VERSION;
+    /** Cross-system transaction correlation ID */
+    transaction_ref: string;
+    /** Payment rails observed in this transaction */
+    rails_observed: string[];
+    /** Protocol-specific evidence snapshots */
+    protocol_evidence: ProtocolEvidence[];
+    /** Chronological event sequence */
+    timeline: TimelineEntry[];
+    /** Associated PEAC receipt references (receipt_ref hashes) */
+    receipts: string[];
+    /** Non-aggregating observation summary */
+    summary: CommerceSummary;
+    /** Bundle creation timestamp */
+    created_at: string;
+}
+/** Options for creating a commerce evidence bundle */
+export interface CreateCommerceBundleOptions {
+    /** Cross-system transaction correlation ID */
+    transaction_ref: string;
+    /** Optional initial protocol evidence */
+    evidence?: ProtocolEvidence[];
+    /** Optional initial timeline entries */
+    timeline?: TimelineEntry[];
+    /** Optional initial receipt references */
+    receipts?: string[];
+    /** Optional creation timestamp (for deterministic output; defaults to now) */
+    created_at?: string;
+}
+//# sourceMappingURL=commerce-bundle-types.d.ts.map

package/dist/commerce-bundle-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce-bundle-types.d.ts","sourceRoot":"","sources":["../src/commerce-bundle-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4BAA4B;AAC5B,eAAO,MAAM,uBAAuB,EAAG,uCAAgD,CAAC;AAExF,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACnC,6CAA6C;IAC7C,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,6BAA6B;IAC7B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,+BAA+B;AAC/B,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,OAAO,EAAE,OAAO,uBAAuB,CAAC;IACxC,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2CAA2C;IAC3C,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,mCAAmC;IACnC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,eAAe,CAAC;IACzB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/commerce-bundle.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Commerce evidence bundle (experimental, DD-192).
+ *
+ * Cross-ecosystem commerce evidence correlation. Correlates receipts
+ * across payment rails without aggregating or asserting settlement totals.
+ *
+ * Summary is non-aggregating by default: observed_amounts lists each
+ * source's observation independently. A canonical total may only be
+ * derived when same currency, same semantic stage, and an explicit
+ * authoritative-winner rule is documented and tested.
+ */
+import type { CommerceEvidenceBundle, CommerceSummary, CreateCommerceBundleOptions, ProtocolEvidence, TimelineEntry } from './commerce-bundle-types.js';
+/**
+ * Create a new commerce evidence bundle.
+ */
+export declare function createCommerceEvidenceBundle(options: CreateCommerceBundleOptions): CommerceEvidenceBundle;
+/**
+ * Add protocol evidence to an existing bundle.
+ * Returns a new bundle (immutable pattern).
+ */
+export declare function addProtocolEvidence(bundle: CommerceEvidenceBundle, evidence: ProtocolEvidence): CommerceEvidenceBundle;
+/**
+ * Add a timeline entry to an existing bundle.
+ * Returns a new bundle with sorted timeline.
+ */
+export declare function addTimelineEntry(bundle: CommerceEvidenceBundle, entry: TimelineEntry): CommerceEvidenceBundle;
+/**
+ * Add a receipt reference to an existing bundle.
+ */
+export declare function addReceiptRef(bundle: CommerceEvidenceBundle, receiptRef: string): CommerceEvidenceBundle;
+/**
+ * Compute a non-aggregating commerce summary from protocol evidence.
+ *
+ * Lists each source's observed amounts independently. Does NOT compute
+ * a rolled-up transaction total. A canonical total requires same currency,
+ * same semantic stage, and an explicit authoritative-winner rule.
+ */
+export declare function computeCommerceSummary(evidence: ProtocolEvidence[]): CommerceSummary;
+/**
+ * Serialize a commerce bundle to deterministic JSON.
+ *
+ * Uses recursive key sorting so nested objects (protocol evidence,
+ * timeline metadata, summary) are also serialized deterministically.
+ * Arrays are preserved in-order. No nested fields are omitted.
+ */
+export declare function serializeCommerceBundle(bundle: CommerceEvidenceBundle): string;
+//# sourceMappingURL=commerce-bundle.d.ts.map

package/dist/commerce-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce-bundle.d.ts","sourceRoot":"","sources":["../src/commerce-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,2BAA2B,EAE3B,gBAAgB,EAChB,aAAa,EACd,MAAM,4BAA4B,CAAC;AAGpC;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,sBAAsB,CAiBxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,gBAAgB,GACzB,sBAAsB,CAQxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,aAAa,GACnB,sBAAsB,CAKxB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,sBAAsB,EAC9B,UAAU,EAAE,MAAM,GACjB,sBAAsB,CAKxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,eAAe,CA8CpF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAE9E"}

package/dist/index.cjs

@@ -1548,6 +1548,103 @@ function formatReportText(report) {
   return lines.join("\n");
 }
 
+// src/commerce-bundle-types.ts
+var COMMERCE_BUNDLE_VERSION = "peac.commerce-bundle/0.1-experimental";
+
+// src/commerce-bundle.ts
+function createCommerceEvidenceBundle(options) {
+  const evidence = options.evidence ?? [];
+  const timeline = options.timeline ?? [];
+  const receipts = options.receipts ?? [];
+  const bundle = {
+    version: COMMERCE_BUNDLE_VERSION,
+    transaction_ref: options.transaction_ref,
+    rails_observed: extractRails(evidence),
+    protocol_evidence: evidence,
+    timeline: sortTimeline(timeline),
+    receipts,
+    summary: computeCommerceSummary(evidence),
+    created_at: options.created_at ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return bundle;
+}
+function addProtocolEvidence(bundle, evidence) {
+  const newEvidence = [...bundle.protocol_evidence, evidence];
+  return {
+    ...bundle,
+    protocol_evidence: newEvidence,
+    rails_observed: extractRails(newEvidence),
+    summary: computeCommerceSummary(newEvidence)
+  };
+}
+function addTimelineEntry(bundle, entry) {
+  return {
+    ...bundle,
+    timeline: sortTimeline([...bundle.timeline, entry])
+  };
+}
+function addReceiptRef(bundle, receiptRef) {
+  return {
+    ...bundle,
+    receipts: [...bundle.receipts, receiptRef]
+  };
+}
+function computeCommerceSummary(evidence) {
+  const observedAmounts = [];
+  const currencies = /* @__PURE__ */ new Set();
+  const rails = /* @__PURE__ */ new Set();
+  for (const ev of evidence) {
+    const data = ev.data;
+    const amount = typeof data.amount_minor === "string" ? data.amount_minor : typeof data.amount === "string" ? data.amount : typeof data.amount === "number" ? String(data.amount) : void 0;
+    const currency = typeof data.currency === "string" ? data.currency : void 0;
+    const rail = typeof data.payment_rail === "string" ? data.payment_rail : void 0;
+    const stage = typeof data.commerce_event === "string" ? data.commerce_event : typeof data.semantic_stage === "string" ? data.semantic_stage : void 0;
+    if (amount && currency) {
+      observedAmounts.push({
+        source: ev.source,
+        amount,
+        currency: currency.toUpperCase(),
+        semantic_stage: stage
+      });
+      currencies.add(currency.toUpperCase());
+    }
+    if (rail) rails.add(rail);
+  }
+  return {
+    observed_amounts: observedAmounts,
+    currencies_observed: [...currencies].sort(),
+    rails_observed: [...rails].sort(),
+    evidence_count: evidence.length
+  };
+}
+function serializeCommerceBundle(bundle) {
+  return JSON.stringify(stableSort(bundle), null, 2);
+}
+function stableSort(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(stableSort);
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = stableSort(value[key]);
+  }
+  return sorted;
+}
+function extractRails(evidence) {
+  const rails = /* @__PURE__ */ new Set();
+  for (const ev of evidence) {
+    if (typeof ev.data.payment_rail === "string") {
+      rails.add(ev.data.payment_rail);
+    }
+  }
+  return [...rails].sort();
+}
+function sortTimeline(entries) {
+  return [...entries].sort(
+    (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+  );
+}
+
 // src/index.ts
 var AUDIT_PACKAGE_VERSION = "0.9.27";
 
@@ -1556,12 +1653,18 @@ exports.AUDIT_PACKAGE_VERSION = AUDIT_PACKAGE_VERSION;
 exports.AUDIT_SEVERITIES = AUDIT_SEVERITIES;
 exports.AUDIT_VERSION = AUDIT_VERSION;
 exports.BUNDLE_VERSION = BUNDLE_VERSION;
+exports.COMMERCE_BUNDLE_VERSION = COMMERCE_BUNDLE_VERSION;
 exports.DISPUTE_BUNDLE_VERSION = DISPUTE_BUNDLE_VERSION;
 exports.DISPUTE_BUNDLE_VERSION_v2 = BUNDLE_VERSION2;
 exports.VERIFICATION_REPORT_VERSION = VERIFICATION_REPORT_VERSION;
+exports.addProtocolEvidence = addProtocolEvidence;
+exports.addReceiptRef = addReceiptRef;
+exports.addTimelineEntry = addTimelineEntry;
+exports.computeCommerceSummary = computeCommerceSummary;
 exports.correlateByTrace = correlateByTrace;
 exports.createAuditEntry = createAuditEntry;
 exports.createCaseBundle = createCaseBundle;
+exports.createCommerceEvidenceBundle = createCommerceEvidenceBundle;
 exports.createDisputeBundle = createDisputeBundle;
 exports.createJsonlAppender = createJsonlAppender;
 exports.filterByDispute = filterByDispute;
@@ -1581,6 +1684,7 @@ exports.parseJsonl = parseJsonl;
 exports.parseJsonlLine = parseJsonlLine;
 exports.readDisputeBundle = readDisputeBundle;
 exports.serializeBundle = serializeBundle;
+exports.serializeCommerceBundle = serializeCommerceBundle;
 exports.serializeReport = serializeReport;
 exports.validateAuditEntry = validateAuditEntry;
 exports.verifyBundle = verifyBundle;