@peac/audit 0.12.11 → 0.12.13

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

@@ -85,4 +85,51 @@ export interface CreateCommerceBundleOptions {
     /** Optional creation timestamp (for deterministic output; defaults to now) */
     created_at?: string;
 }
+/**
+ * Input record accepted by `groupByLifecycle`.
+ *
+ * Observational-only shape: callers provide the fields necessary for
+ * grouping without passing the full signed record. `session_ref` is the
+ * value the grouper keys on; records with the same `session_ref` end up
+ * in the same `LifecycleBundle`.
+ */
+export interface LifecycleInputRecord {
+    /** Session or transaction identifier shared across a lifecycle. */
+    session_ref: string;
+    /**
+     * Observed commerce event name, per the upstream attestation. An
+     * empty, missing, null, or non-string value routes the record to the
+     * `unclassified` bucket; no event is synthesized.
+     */
+    commerce_event?: string | null;
+    /** Issued-at time (RFC 3339 string or unix seconds). */
+    iat: string | number;
+    /** SHA-256 hash of the JWS (used for deterministic tie-breaking). */
+    receipt_ref: string;
+    /** Optional opaque passthrough so callers can carry the full record. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Reserved bucket name for records whose `commerce_event` is absent,
+ * null, empty, or not a string. No lifecycle semantics are inferred;
+ * `unclassified` preserves the record as observed and never promotes
+ * it into an interpreted bucket.
+ */
+export declare const UNCLASSIFIED_LIFECYCLE_BUCKET: "unclassified";
+/**
+ * One session's records grouped by the event name each record carries,
+ * observational only. `buckets` keys are the literal `commerce_event`
+ * values the upstream attested (or `'unclassified'` for records with
+ * no event). Buckets with zero records are omitted.
+ */
+export interface LifecycleBundle {
+    /** Session or transaction identifier shared by every record in the bundle. */
+    session_ref: string;
+    /** Per-event record lists, keyed by the upstream event name. */
+    buckets: Record<string, LifecycleInputRecord[]>;
+    /** Total number of records in the bundle (sum across buckets). */
+    record_count: number;
+    /** Bundle format version (same experimental constant as commerce bundles). */
+    version: typeof COMMERCE_BUNDLE_VERSION;
+}
 //# sourceMappingURL=commerce-bundle-types.d.ts.map

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

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

package/dist/commerce-bundle.d.ts

@@ -9,7 +9,7 @@
  * 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';
+import type { CommerceEvidenceBundle, CommerceSummary, CreateCommerceBundleOptions, LifecycleBundle, LifecycleInputRecord, ProtocolEvidence, TimelineEntry } from './commerce-bundle-types.js';
 /**
  * Create a new commerce evidence bundle.
  */
@@ -44,4 +44,27 @@ export declare function computeCommerceSummary(evidence: ProtocolEvidence[]): Co
  * Arrays are preserved in-order. No nested fields are omitted.
  */
 export declare function serializeCommerceBundle(bundle: CommerceEvidenceBundle): string;
+/**
+ * Group records by their session identifier and then by the literal
+ * `commerce_event` value each record carries.
+ *
+ * Observational only. The returned `buckets` map keys are the exact
+ * event names attested by the upstream; no lifecycle semantics are
+ * inferred. Records with a missing, null, empty, or non-string
+ * `commerce_event` are routed to the reserved
+ * `UNCLASSIFIED_LIFECYCLE_BUCKET` key. Combinations of records in the
+ * same session never synthesize a new bucket name; there is no
+ * `settled`, `completed`, or `finalized` outcome derived from record
+ * pairs.
+ *
+ * Deterministic ordering:
+ * - Within each bucket: primary sort by `iat` ascending, tie-break by
+ *   `receipt_ref` lex ascending.
+ * - Across the returned array: `session_ref` lex ascending.
+ *
+ * @experimental The API shape may change before the `-experimental`
+ *   suffix is removed. Callers should pin the `COMMERCE_BUNDLE_VERSION`
+ *   constant when persisting the result.
+ */
+export declare function groupByLifecycle(records: LifecycleInputRecord[]): LifecycleBundle[];
 //# sourceMappingURL=commerce-bundle.d.ts.map

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

@@ -1 +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"}
+{"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,EAC3B,eAAe,EACf,oBAAoB,EAEpB,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;AA+CD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,eAAe,EAAE,CAgCnF"}

package/dist/index.cjs

@@ -1550,6 +1550,7 @@ function formatReportText(report) {
 
 // src/commerce-bundle-types.ts
 var COMMERCE_BUNDLE_VERSION = "peac.commerce-bundle/0.1-experimental";
+var UNCLASSIFIED_LIFECYCLE_BUCKET = "unclassified";
 
 // src/commerce-bundle.ts
 function createCommerceEvidenceBundle(options) {
@@ -1644,6 +1645,60 @@ function sortTimeline(entries) {
     (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
   );
 }
+function groupByLifecycle(records) {
+  const bySession = /* @__PURE__ */ new Map();
+  for (const rec of records) {
+    const list = bySession.get(rec.session_ref);
+    if (list) list.push(rec);
+    else bySession.set(rec.session_ref, [rec]);
+  }
+  const bundles = [];
+  for (const [session_ref, rs] of bySession) {
+    const buckets = {};
+    for (const rec of rs) {
+      const key = resolveBucketKey(rec.commerce_event);
+      const list = buckets[key];
+      if (list) list.push(rec);
+      else buckets[key] = [rec];
+    }
+    for (const key of Object.keys(buckets)) {
+      buckets[key] = [...buckets[key]].sort(compareLifecycleRecords);
+    }
+    bundles.push({
+      session_ref,
+      buckets,
+      record_count: rs.length,
+      version: COMMERCE_BUNDLE_VERSION
+    });
+  }
+  bundles.sort(
+    (a, b) => a.session_ref < b.session_ref ? -1 : a.session_ref > b.session_ref ? 1 : 0
+  );
+  return bundles;
+}
+function resolveBucketKey(event) {
+  if (typeof event !== "string") return UNCLASSIFIED_LIFECYCLE_BUCKET;
+  const trimmed = event.trim();
+  if (trimmed === "") return UNCLASSIFIED_LIFECYCLE_BUCKET;
+  return trimmed;
+}
+function compareLifecycleRecords(a, b) {
+  const aTs = normalizeIat(a.iat);
+  const bTs = normalizeIat(b.iat);
+  if (aTs < bTs) return -1;
+  if (aTs > bTs) return 1;
+  if (a.receipt_ref < b.receipt_ref) return -1;
+  if (a.receipt_ref > b.receipt_ref) return 1;
+  return 0;
+}
+function normalizeIat(iat) {
+  if (typeof iat === "number") return iat;
+  const asNumber = Number(iat);
+  if (!Number.isNaN(asNumber)) return asNumber;
+  const parsed = Date.parse(iat);
+  if (!Number.isNaN(parsed)) return parsed;
+  return 0;
+}
 
 // src/index.ts
 var AUDIT_PACKAGE_VERSION = "0.9.27";
@@ -1656,6 +1711,7 @@ 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.UNCLASSIFIED_LIFECYCLE_BUCKET = UNCLASSIFIED_LIFECYCLE_BUCKET;
 exports.VERIFICATION_REPORT_VERSION = VERIFICATION_REPORT_VERSION;
 exports.addProtocolEvidence = addProtocolEvidence;
 exports.addReceiptRef = addReceiptRef;
@@ -1677,6 +1733,7 @@ exports.formatReportText = formatReportText;
 exports.generateAuditId = generateAuditId;
 exports.generateBundleSummary = generateBundleSummary;
 exports.getBundleContentHash = getBundleContentHash;
+exports.groupByLifecycle = groupByLifecycle;
 exports.isValidAuditEntry = isValidAuditEntry;
 exports.isValidTraceContext = isValidTraceContext;
 exports.isValidUlid = isValidUlid;