xytara 3.1.0 → 3.1.2

package/lib/activity_audit_contract.js

@@ -1,322 +1,322 @@
-"use strict";
-
-function toArrayFromMap(mapValue) {
-  if (!(mapValue instanceof Map)) return [];
-  return Array.from(mapValue.values());
-}
-
-function normalizeTimestamp(value) {
-  if (typeof value !== "string" || !value.trim()) return null;
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
-}
-
-function firstTimestamp(record, fieldNames) {
-  for (const fieldName of fieldNames) {
-    const timestamp = normalizeTimestamp(record && record[fieldName]);
-    if (timestamp) return timestamp;
-  }
-  return null;
-}
-
-function sortByTimestampDescending(items) {
-  return [...items].sort((left, right) => {
-    const leftTime = left && left.at_iso ? Date.parse(left.at_iso) : 0;
-    const rightTime = right && right.at_iso ? Date.parse(right.at_iso) : 0;
-    return rightTime - leftTime;
-  });
-}
-
-function buildQuoteActivities(state, accountId) {
-  return toArrayFromMap(state.quotes)
-    .filter((quote) => !accountId || quote.account_id === accountId)
-    .map((quote) => ({
-      activity_id: `quote.${quote.quote_id}`,
-      activity_kind: "quote",
-      activity_family: "commercial_admission",
-      at_iso: firstTimestamp(quote, ["executed_at_iso", "payment_recorded_at_iso", "created_at_iso"]),
-      account_id: quote.account_id || null,
-      actor_ref: quote.account_id || null,
-      action: quote.status === "executed" ? "quoted_and_executed" : "quoted",
-      status: quote.status || null,
-      amount_minor: quote.amount_minor || null,
-      currency: quote.currency || null,
-      settlement_mode: quote.settlement_mode || null,
-      payment_protocol: quote.payment_protocol || null,
-      route_ref: "/v1/payment-quotes",
-      linked_refs: {
-        quote_ref: quote.quote_id ? `/v1/quotes/${encodeURIComponent(quote.quote_id)}` : null
-      }
-    }));
-}
-
-function buildTransactionActivities(state, accountId) {
-  return toArrayFromMap(state.transactions)
-    .map((entry) => entry && entry.transaction ? entry.transaction : null)
-    .filter(Boolean)
-    .filter((transaction) => !accountId || transaction.account_id === accountId)
-    .map((transaction) => ({
-      activity_id: `transaction.${transaction.transaction_id}`,
-      activity_kind: "transaction",
-      activity_family: "runtime_execution",
-      at_iso: firstTimestamp(transaction, ["completed_at_iso", "created_at_iso"]),
-      account_id: transaction.account_id || null,
-      actor_ref: transaction.account_id || null,
-      action: "executed_runtime_work",
-      status: transaction.status || null,
-      amount_minor: transaction.payment && transaction.payment.amount_minor ? transaction.payment.amount_minor : null,
-      currency: transaction.payment && transaction.payment.currency ? transaction.payment.currency : null,
-      settlement_mode: transaction.settlement && transaction.settlement.mode ? transaction.settlement.mode : null,
-      payment_protocol: transaction.payment && transaction.payment.protocol ? transaction.payment.protocol : null,
-      delivery_target_kind: transaction.callback_url ? "callback" : "direct",
-      route_ref: "/v1/commands/execute",
-      linked_refs: {
-        transaction_ref: transaction.transaction_id ? `/v1/transactions/${encodeURIComponent(transaction.transaction_id)}` : null,
-        proof_ref: transaction.proof_ref || null
-      }
-    }));
-}
-
-function buildReceiptActivities(state, accountId) {
-  return toArrayFromMap(state.receipts)
-    .map((entry) => entry && entry.receipt ? entry.receipt : null)
-    .filter(Boolean)
-    .filter((receipt) => !accountId || receipt.account_id === accountId)
-    .map((receipt) => ({
-      activity_id: `receipt.${receipt.receipt_id}`,
-      activity_kind: "receipt",
-      activity_family: "delivery_proof",
-      at_iso: firstTimestamp(receipt, ["created_at_iso", "completed_at_iso"]),
-      account_id: receipt.account_id || null,
-      actor_ref: receipt.account_id || null,
-      action: "receipt_issued",
-      status: receipt.status || null,
-      proof_ref: receipt.proof_ref || null,
-      route_ref: receipt.receipt_id ? `/v1/receipts/${encodeURIComponent(receipt.receipt_id)}` : "/v1/receipts",
-      linked_refs: {
-        receipt_ref: receipt.receipt_id ? `/v1/receipts/${encodeURIComponent(receipt.receipt_id)}` : null
-      }
-    }));
-}
-
-function buildPaymentActivities(state, accountId) {
-  const ledger = Array.isArray(state.paymentLedger) ? state.paymentLedger : [];
-  return ledger
-    .filter((payment) => !accountId || payment.account_id === accountId)
-    .map((payment) => ({
-      activity_id: `payment.${payment.payment_id}`,
-      activity_kind: "payment",
-      activity_family: "funds_in",
-      at_iso: firstTimestamp(payment, ["recorded_at_iso"]),
-      account_id: payment.account_id || null,
-      actor_ref: payment.account_id || null,
-      action: "payment_recorded",
-      status: payment.payment && payment.payment.status ? payment.payment.status : null,
-      amount_minor: payment.amount_minor || null,
-      currency: payment.currency || null,
-      settlement_mode: payment.settlement && payment.settlement.mode ? payment.settlement.mode : null,
-      settlement_adapter: payment.settlement_adapter || null,
-      settlement_integration_id: payment.settlement_integration_id || null,
-      payment_protocol: payment.payment && payment.payment.protocol ? payment.payment.protocol : null,
-      treasury_destination_id: payment.treasury && payment.treasury.destination_id ? payment.treasury.destination_id : null,
-      treasury_external_ref: payment.treasury && payment.treasury.custody_external_ref ? payment.treasury.custody_external_ref : null,
-      route_ref: payment.payment_id ? `/v1/payment-ledger/${encodeURIComponent(payment.payment_id)}` : "/v1/payment-ledger",
-      linked_refs: {
-        payment_ref: payment.payment_id ? `/v1/payment-ledger/${encodeURIComponent(payment.payment_id)}` : null,
-        operator_pack_ref: payment.payment_id ? `/v1/payment-ledger/${encodeURIComponent(payment.payment_id)}/operator-pack` : null
-      }
-    }));
-}
-
-function buildDeliveryActivities(state, accountId) {
-  return toArrayFromMap(state.deliveries)
-    .filter((delivery) => !accountId || delivery.account_id === accountId)
-    .map((delivery) => ({
-      activity_id: `delivery.${delivery.delivery_id}`,
-      activity_kind: "delivery",
-      activity_family: "delivery_proof",
-      at_iso: firstTimestamp(delivery, ["delivered_at_iso", "last_attempt_at_iso", "created_at_iso"]),
-      account_id: delivery.account_id || null,
-      actor_ref: delivery.account_id || null,
-      action: delivery.status === "delivered" ? "delivered_result" : "delivery_pending",
-      status: delivery.status || null,
-      output_ref: delivery.output_ref || null,
-      proof_ref: delivery.proof_ref || null,
-      payment_id: delivery.payment_id || null,
-      delivery_target_kind: delivery.delivery_target_kind || null,
-      route_ref: delivery.transaction_id ? `/v1/transactions/${encodeURIComponent(delivery.transaction_id)}` : null,
-      linked_refs: {
-        transaction_ref: delivery.transaction_id ? `/v1/transactions/${encodeURIComponent(delivery.transaction_id)}` : null,
-        receipt_ref: delivery.receipt_id ? `/v1/receipts/${encodeURIComponent(delivery.receipt_id)}` : null
-      }
-    }));
-}
-
-function buildHistoryActivities(records, accountId, config) {
-  return records.flatMap((record) => {
-    const history = Array.isArray(record && record.history) ? record.history : [];
-    return history
-      .filter((entry) => {
-        const recordAccountId = record && record.account_id ? record.account_id : null;
-        const transactionId = record && record.transaction_id ? record.transaction_id : null;
-        if (!accountId) return true;
-        return recordAccountId === accountId || transactionId === accountId || record && record.requested_by === accountId;
-      })
-      .map((entry, index) => ({
-        activity_id: `${config.prefix}.${record[config.idField]}.${index}`,
-        activity_kind: config.kind,
-        activity_family: config.family,
-        at_iso: firstTimestamp(entry, ["at_iso"]) || firstTimestamp(record, ["updated_at_iso", "created_at_iso"]),
-        account_id: record && record.account_id ? record.account_id : null,
-        actor_ref: entry && entry.actor ? `${entry.actor.type || "actor"}:${entry.actor.role || "unknown"}` : null,
-        action: entry && entry.event ? entry.event : config.defaultAction,
-        status: entry && entry.next_status ? entry.next_status : record.status || null,
-        reason_code: entry && entry.reason_code ? entry.reason_code : record.reason_code || null,
-        note: entry && entry.note ? entry.note : null,
-        route_ref: config.routeTemplate(record[config.idField]),
-        linked_refs: {
-          transaction_ref: record && record.transaction_id ? `/v1/transactions/${encodeURIComponent(record.transaction_id)}` : null,
-          receipt_ref: record && record.receipt_id ? `/v1/receipts/${encodeURIComponent(record.receipt_id)}` : null
-        }
-      }));
-  });
-}
-
-function buildCreditGrantActivities(state, accountId) {
-  return toArrayFromMap(state.externalCreditGrants)
-    .filter((grant) => !accountId || grant.account_id === accountId)
-    .map((grant) => ({
-      activity_id: `credit_grant.${grant.grant_id || grant.credit_grant_id || grant.account_id || "unknown"}`,
-      activity_kind: "credit_grant",
-      activity_family: "funding",
-      at_iso: firstTimestamp(grant, ["created_at_iso", "granted_at_iso", "recorded_at_iso"]),
-      account_id: grant.account_id || null,
-      actor_ref: grant.account_id || null,
-      action: "credit_granted",
-      status: grant.status || null,
-      amount_minor: grant.amount_minor || grant.credit_amount_minor || null,
-      currency: grant.currency || null,
-      route_ref: "/v1/credit-bridge/grants",
-      linked_refs: {}
-    }));
-}
-
-function buildBridgeActivities(state, accountId) {
-  return toArrayFromMap(state.runtimeBridgeDispatches)
-    .filter((dispatch) => !accountId || dispatch.account_id === accountId)
-    .map((dispatch) => ({
-      activity_id: `bridge.${dispatch.dispatch_id || dispatch.bridge_dispatch_id || "unknown"}`,
-      activity_kind: "bridge_dispatch",
-      activity_family: "runtime_proof_handoff",
-      at_iso: firstTimestamp(dispatch, ["created_at_iso", "dispatched_at_iso", "recorded_at_iso"]),
-      account_id: dispatch.account_id || null,
-      actor_ref: dispatch.account_id || null,
-      action: "bridge_dispatched",
-      status: dispatch.status || null,
-      route_ref: "/v1/proof-bridge",
-      linked_refs: {
-        proof_ref: dispatch.proof_ref || null,
-        receipt_ref: dispatch.receipt_id ? `/v1/receipts/${encodeURIComponent(dispatch.receipt_id)}` : null
-      }
-    }));
-}
-
-function buildParticipantActivities(records, kind, routeRef) {
-  return records.map((participant) => ({
-    activity_id: `${kind}.${participant.participant_id || participant.operator_id || participant.network_participant_id || "unknown"}`,
-    activity_kind: kind,
-    activity_family: "third_party_participation",
-    at_iso: firstTimestamp(participant, ["created_at_iso", "updated_at_iso", "admitted_at_iso"]),
-    account_id: participant.account_id || null,
-    actor_ref: participant.account_id || null,
-    action: `registered_${kind}`,
-    status: participant.status || null,
-    route_ref: routeRef,
-    linked_refs: {}
-  }));
-}
-
-function buildActivityLedger(state, options) {
-  const accountId = options && options.account_id ? options.account_id : null;
-  const activities = sortByTimestampDescending([
-    ...buildQuoteActivities(state, accountId),
-    ...buildTransactionActivities(state, accountId),
-    ...buildReceiptActivities(state, accountId),
-    ...buildPaymentActivities(state, accountId),
-    ...buildDeliveryActivities(state, accountId),
-    ...buildHistoryActivities(toArrayFromMap(state.refunds), accountId, {
-      prefix: "refund",
-      idField: "refund_id",
-      kind: "refund",
-      family: "remediation",
-      defaultAction: "refund_review",
-      routeTemplate: (id) => `/v1/refunds/${encodeURIComponent(id)}`
-    }),
-    ...buildHistoryActivities(toArrayFromMap(state.disputes), accountId, {
-      prefix: "dispute",
-      idField: "dispute_id",
-      kind: "dispute",
-      family: "remediation",
-      defaultAction: "dispute_review",
-      routeTemplate: (id) => `/v1/disputes/${encodeURIComponent(id)}`
-    }),
-    ...buildHistoryActivities(toArrayFromMap(state.remediationTickets), accountId, {
-      prefix: "remediation_ticket",
-      idField: "ticket_id",
-      kind: "remediation_ticket",
-      family: "remediation",
-      defaultAction: "remediation_review",
-      routeTemplate: (id) => `/v1/remediation-tickets/${encodeURIComponent(id)}`
-    }),
-    ...buildCreditGrantActivities(state, accountId),
-    ...buildBridgeActivities(state, accountId),
-    ...buildParticipantActivities(toArrayFromMap(state.operatorParticipants), "operator_participant", "/v1/multi-operator"),
-    ...buildParticipantActivities(toArrayFromMap(state.networkParticipants), "network_participant", "/v1/network-participation")
-  ]).slice(0, 300);
-
-  return {
-    product: "xytara",
-    category: "machine-commerce-activity-ledger",
-    pack_version: "xytara-activity-ledger-v1",
-    posture: "operator_facing_runtime_and_funds_activity_visibility",
-    audit_posture: "operator_visibility_first",
-    account_scope: accountId || "all_accounts",
-    counts: {
-      activity_count: activities.length,
-      payment_count: activities.filter((entry) => entry.activity_kind === "payment").length,
-      transaction_count: activities.filter((entry) => entry.activity_kind === "transaction").length,
-      delivery_count: activities.filter((entry) => entry.activity_kind === "delivery").length,
-      remediation_count: activities.filter((entry) => entry.activity_family === "remediation").length,
-      participation_count: activities.filter((entry) => entry.activity_family === "third_party_participation").length
-    },
-    activities,
-    linked_surfaces: {
-      payment_ledger_ref: "/v1/payment-ledger",
-      reconciliation_report_ref: "/v1/reconciliation-report",
-      integration_registry_ref: "/v1/integrations",
-      treasury_summary_ref_template: "/v1/economics/accounts/:account_id/treasury-summary",
-      rail_summary_ref_template: "/v1/economics/accounts/:account_id/rail-summary",
-      proof_bridge_ref: "/v1/proof-bridge",
-      activity_summary_ref: "/v1/activity-ledger/summary"
-    },
-    operator_note: "use this ledger to inspect who did what, what was paid, what was delivered, and how funds and consequence moved through the runtime"
-  };
-}
-
-function summarizeActivityLedger(state, options) {
-  const pack = buildActivityLedger(state, options);
-  return {
-    product: "xytara",
-    category: "machine-commerce-activity-ledger-summary",
-    summary_version: "xytara-activity-ledger-summary-v1",
-    activity_count: pack.counts.activity_count,
-    account_scope: pack.account_scope,
-    counts: pack.counts,
-    linked_surfaces: pack.linked_surfaces
-  };
-}
-
-module.exports = {
-  buildActivityLedger,
-  summarizeActivityLedger
-};
+"use strict";
+
+function toArrayFromMap(mapValue) {
+  if (!(mapValue instanceof Map)) return [];
+  return Array.from(mapValue.values());
+}
+
+function normalizeTimestamp(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+function firstTimestamp(record, fieldNames) {
+  for (const fieldName of fieldNames) {
+    const timestamp = normalizeTimestamp(record && record[fieldName]);
+    if (timestamp) return timestamp;
+  }
+  return null;
+}
+
+function sortByTimestampDescending(items) {
+  return [...items].sort((left, right) => {
+    const leftTime = left && left.at_iso ? Date.parse(left.at_iso) : 0;
+    const rightTime = right && right.at_iso ? Date.parse(right.at_iso) : 0;
+    return rightTime - leftTime;
+  });
+}
+
+function buildQuoteActivities(state, accountId) {
+  return toArrayFromMap(state.quotes)
+    .filter((quote) => !accountId || quote.account_id === accountId)
+    .map((quote) => ({
+      activity_id: `quote.${quote.quote_id}`,
+      activity_kind: "quote",
+      activity_family: "commercial_admission",
+      at_iso: firstTimestamp(quote, ["executed_at_iso", "payment_recorded_at_iso", "created_at_iso"]),
+      account_id: quote.account_id || null,
+      actor_ref: quote.account_id || null,
+      action: quote.status === "executed" ? "quoted_and_executed" : "quoted",
+      status: quote.status || null,
+      amount_minor: quote.amount_minor || null,
+      currency: quote.currency || null,
+      settlement_mode: quote.settlement_mode || null,
+      payment_protocol: quote.payment_protocol || null,
+      route_ref: "/v1/payment-quotes",
+      linked_refs: {
+        quote_ref: quote.quote_id ? `/v1/quotes/${encodeURIComponent(quote.quote_id)}` : null
+      }
+    }));
+}
+
+function buildTransactionActivities(state, accountId) {
+  return toArrayFromMap(state.transactions)
+    .map((entry) => entry && entry.transaction ? entry.transaction : null)
+    .filter(Boolean)
+    .filter((transaction) => !accountId || transaction.account_id === accountId)
+    .map((transaction) => ({
+      activity_id: `transaction.${transaction.transaction_id}`,
+      activity_kind: "transaction",
+      activity_family: "runtime_execution",
+      at_iso: firstTimestamp(transaction, ["completed_at_iso", "created_at_iso"]),
+      account_id: transaction.account_id || null,
+      actor_ref: transaction.account_id || null,
+      action: "executed_runtime_work",
+      status: transaction.status || null,
+      amount_minor: transaction.payment && transaction.payment.amount_minor ? transaction.payment.amount_minor : null,
+      currency: transaction.payment && transaction.payment.currency ? transaction.payment.currency : null,
+      settlement_mode: transaction.settlement && transaction.settlement.mode ? transaction.settlement.mode : null,
+      payment_protocol: transaction.payment && transaction.payment.protocol ? transaction.payment.protocol : null,
+      delivery_target_kind: transaction.callback_url ? "callback" : "direct",
+      route_ref: "/v1/commands/execute",
+      linked_refs: {
+        transaction_ref: transaction.transaction_id ? `/v1/transactions/${encodeURIComponent(transaction.transaction_id)}` : null,
+        proof_ref: transaction.proof_ref || null
+      }
+    }));
+}
+
+function buildReceiptActivities(state, accountId) {
+  return toArrayFromMap(state.receipts)
+    .map((entry) => entry && entry.receipt ? entry.receipt : null)
+    .filter(Boolean)
+    .filter((receipt) => !accountId || receipt.account_id === accountId)
+    .map((receipt) => ({
+      activity_id: `receipt.${receipt.receipt_id}`,
+      activity_kind: "receipt",
+      activity_family: "delivery_proof",
+      at_iso: firstTimestamp(receipt, ["created_at_iso", "completed_at_iso"]),
+      account_id: receipt.account_id || null,
+      actor_ref: receipt.account_id || null,
+      action: "receipt_issued",
+      status: receipt.status || null,
+      proof_ref: receipt.proof_ref || null,
+      route_ref: receipt.receipt_id ? `/v1/receipts/${encodeURIComponent(receipt.receipt_id)}` : "/v1/receipts",
+      linked_refs: {
+        receipt_ref: receipt.receipt_id ? `/v1/receipts/${encodeURIComponent(receipt.receipt_id)}` : null
+      }
+    }));
+}
+
+function buildPaymentActivities(state, accountId) {
+  const ledger = Array.isArray(state.paymentLedger) ? state.paymentLedger : [];
+  return ledger
+    .filter((payment) => !accountId || payment.account_id === accountId)
+    .map((payment) => ({
+      activity_id: `payment.${payment.payment_id}`,
+      activity_kind: "payment",
+      activity_family: "funds_in",
+      at_iso: firstTimestamp(payment, ["recorded_at_iso"]),
+      account_id: payment.account_id || null,
+      actor_ref: payment.account_id || null,
+      action: "payment_recorded",
+      status: payment.payment && payment.payment.status ? payment.payment.status : null,
+      amount_minor: payment.amount_minor || null,
+      currency: payment.currency || null,
+      settlement_mode: payment.settlement && payment.settlement.mode ? payment.settlement.mode : null,
+      settlement_adapter: payment.settlement_adapter || null,
+      settlement_integration_id: payment.settlement_integration_id || null,
+      payment_protocol: payment.payment && payment.payment.protocol ? payment.payment.protocol : null,
+      treasury_destination_id: payment.treasury && payment.treasury.destination_id ? payment.treasury.destination_id : null,
+      treasury_external_ref: payment.treasury && payment.treasury.custody_external_ref ? payment.treasury.custody_external_ref : null,
+      route_ref: payment.payment_id ? `/v1/payment-ledger/${encodeURIComponent(payment.payment_id)}` : "/v1/payment-ledger",
+      linked_refs: {
+        payment_ref: payment.payment_id ? `/v1/payment-ledger/${encodeURIComponent(payment.payment_id)}` : null,
+        operator_pack_ref: payment.payment_id ? `/v1/payment-ledger/${encodeURIComponent(payment.payment_id)}/operator-pack` : null
+      }
+    }));
+}
+
+function buildDeliveryActivities(state, accountId) {
+  return toArrayFromMap(state.deliveries)
+    .filter((delivery) => !accountId || delivery.account_id === accountId)
+    .map((delivery) => ({
+      activity_id: `delivery.${delivery.delivery_id}`,
+      activity_kind: "delivery",
+      activity_family: "delivery_proof",
+      at_iso: firstTimestamp(delivery, ["delivered_at_iso", "last_attempt_at_iso", "created_at_iso"]),
+      account_id: delivery.account_id || null,
+      actor_ref: delivery.account_id || null,
+      action: delivery.status === "delivered" ? "delivered_result" : "delivery_pending",
+      status: delivery.status || null,
+      output_ref: delivery.output_ref || null,
+      proof_ref: delivery.proof_ref || null,
+      payment_id: delivery.payment_id || null,
+      delivery_target_kind: delivery.delivery_target_kind || null,
+      route_ref: delivery.transaction_id ? `/v1/transactions/${encodeURIComponent(delivery.transaction_id)}` : null,
+      linked_refs: {
+        transaction_ref: delivery.transaction_id ? `/v1/transactions/${encodeURIComponent(delivery.transaction_id)}` : null,
+        receipt_ref: delivery.receipt_id ? `/v1/receipts/${encodeURIComponent(delivery.receipt_id)}` : null
+      }
+    }));
+}
+
+function buildHistoryActivities(records, accountId, config) {
+  return records.flatMap((record) => {
+    const history = Array.isArray(record && record.history) ? record.history : [];
+    return history
+      .filter((entry) => {
+        const recordAccountId = record && record.account_id ? record.account_id : null;
+        const transactionId = record && record.transaction_id ? record.transaction_id : null;
+        if (!accountId) return true;
+        return recordAccountId === accountId || transactionId === accountId || record && record.requested_by === accountId;
+      })
+      .map((entry, index) => ({
+        activity_id: `${config.prefix}.${record[config.idField]}.${index}`,
+        activity_kind: config.kind,
+        activity_family: config.family,
+        at_iso: firstTimestamp(entry, ["at_iso"]) || firstTimestamp(record, ["updated_at_iso", "created_at_iso"]),
+        account_id: record && record.account_id ? record.account_id : null,
+        actor_ref: entry && entry.actor ? `${entry.actor.type || "actor"}:${entry.actor.role || "unknown"}` : null,
+        action: entry && entry.event ? entry.event : config.defaultAction,
+        status: entry && entry.next_status ? entry.next_status : record.status || null,
+        reason_code: entry && entry.reason_code ? entry.reason_code : record.reason_code || null,
+        note: entry && entry.note ? entry.note : null,
+        route_ref: config.routeTemplate(record[config.idField]),
+        linked_refs: {
+          transaction_ref: record && record.transaction_id ? `/v1/transactions/${encodeURIComponent(record.transaction_id)}` : null,
+          receipt_ref: record && record.receipt_id ? `/v1/receipts/${encodeURIComponent(record.receipt_id)}` : null
+        }
+      }));
+  });
+}
+
+function buildCreditGrantActivities(state, accountId) {
+  return toArrayFromMap(state.externalCreditGrants)
+    .filter((grant) => !accountId || grant.account_id === accountId)
+    .map((grant) => ({
+      activity_id: `credit_grant.${grant.grant_id || grant.credit_grant_id || grant.account_id || "unknown"}`,
+      activity_kind: "credit_grant",
+      activity_family: "funding",
+      at_iso: firstTimestamp(grant, ["created_at_iso", "granted_at_iso", "recorded_at_iso"]),
+      account_id: grant.account_id || null,
+      actor_ref: grant.account_id || null,
+      action: "credit_granted",
+      status: grant.status || null,
+      amount_minor: grant.amount_minor || grant.credit_amount_minor || null,
+      currency: grant.currency || null,
+      route_ref: "/v1/credit-bridge/grants",
+      linked_refs: {}
+    }));
+}
+
+function buildBridgeActivities(state, accountId) {
+  return toArrayFromMap(state.runtimeBridgeDispatches)
+    .filter((dispatch) => !accountId || dispatch.account_id === accountId)
+    .map((dispatch) => ({
+      activity_id: `bridge.${dispatch.dispatch_id || dispatch.bridge_dispatch_id || "unknown"}`,
+      activity_kind: "bridge_dispatch",
+      activity_family: "runtime_proof_handoff",
+      at_iso: firstTimestamp(dispatch, ["created_at_iso", "dispatched_at_iso", "recorded_at_iso"]),
+      account_id: dispatch.account_id || null,
+      actor_ref: dispatch.account_id || null,
+      action: "bridge_dispatched",
+      status: dispatch.status || null,
+      route_ref: "/v1/proof-bridge",
+      linked_refs: {
+        proof_ref: dispatch.proof_ref || null,
+        receipt_ref: dispatch.receipt_id ? `/v1/receipts/${encodeURIComponent(dispatch.receipt_id)}` : null
+      }
+    }));
+}
+
+function buildParticipantActivities(records, kind, routeRef) {
+  return records.map((participant) => ({
+    activity_id: `${kind}.${participant.participant_id || participant.operator_id || participant.network_participant_id || "unknown"}`,
+    activity_kind: kind,
+    activity_family: "third_party_participation",
+    at_iso: firstTimestamp(participant, ["created_at_iso", "updated_at_iso", "admitted_at_iso"]),
+    account_id: participant.account_id || null,
+    actor_ref: participant.account_id || null,
+    action: `registered_${kind}`,
+    status: participant.status || null,
+    route_ref: routeRef,
+    linked_refs: {}
+  }));
+}
+
+function buildActivityLedger(state, options) {
+  const accountId = options && options.account_id ? options.account_id : null;
+  const activities = sortByTimestampDescending([
+    ...buildQuoteActivities(state, accountId),
+    ...buildTransactionActivities(state, accountId),
+    ...buildReceiptActivities(state, accountId),
+    ...buildPaymentActivities(state, accountId),
+    ...buildDeliveryActivities(state, accountId),
+    ...buildHistoryActivities(toArrayFromMap(state.refunds), accountId, {
+      prefix: "refund",
+      idField: "refund_id",
+      kind: "refund",
+      family: "remediation",
+      defaultAction: "refund_review",
+      routeTemplate: (id) => `/v1/refunds/${encodeURIComponent(id)}`
+    }),
+    ...buildHistoryActivities(toArrayFromMap(state.disputes), accountId, {
+      prefix: "dispute",
+      idField: "dispute_id",
+      kind: "dispute",
+      family: "remediation",
+      defaultAction: "dispute_review",
+      routeTemplate: (id) => `/v1/disputes/${encodeURIComponent(id)}`
+    }),
+    ...buildHistoryActivities(toArrayFromMap(state.remediationTickets), accountId, {
+      prefix: "remediation_ticket",
+      idField: "ticket_id",
+      kind: "remediation_ticket",
+      family: "remediation",
+      defaultAction: "remediation_review",
+      routeTemplate: (id) => `/v1/remediation-tickets/${encodeURIComponent(id)}`
+    }),
+    ...buildCreditGrantActivities(state, accountId),
+    ...buildBridgeActivities(state, accountId),
+    ...buildParticipantActivities(toArrayFromMap(state.operatorParticipants), "operator_participant", "/v1/multi-operator"),
+    ...buildParticipantActivities(toArrayFromMap(state.networkParticipants), "network_participant", "/v1/network-participation")
+  ]).slice(0, 300);
+
+  return {
+    product: "xytara",
+    category: "machine-commerce-activity-ledger",
+    pack_version: "xytara-activity-ledger-v1",
+    posture: "operator_facing_runtime_and_funds_activity_visibility",
+    audit_posture: "operator_visibility_first",
+    account_scope: accountId || "all_accounts",
+    counts: {
+      activity_count: activities.length,
+      payment_count: activities.filter((entry) => entry.activity_kind === "payment").length,
+      transaction_count: activities.filter((entry) => entry.activity_kind === "transaction").length,
+      delivery_count: activities.filter((entry) => entry.activity_kind === "delivery").length,
+      remediation_count: activities.filter((entry) => entry.activity_family === "remediation").length,
+      participation_count: activities.filter((entry) => entry.activity_family === "third_party_participation").length
+    },
+    activities,
+    linked_surfaces: {
+      payment_ledger_ref: "/v1/payment-ledger",
+      reconciliation_report_ref: "/v1/reconciliation-report",
+      integration_registry_ref: "/v1/integrations",
+      treasury_summary_ref_template: "/v1/economics/accounts/:account_id/treasury-summary",
+      rail_summary_ref_template: "/v1/economics/accounts/:account_id/rail-summary",
+      proof_bridge_ref: "/v1/proof-bridge",
+      activity_summary_ref: "/v1/activity-ledger/summary"
+    },
+    operator_note: "use this ledger to inspect who did what, what was paid, what was delivered, and how funds and consequence moved through the runtime"
+  };
+}
+
+function summarizeActivityLedger(state, options) {
+  const pack = buildActivityLedger(state, options);
+  return {
+    product: "xytara",
+    category: "machine-commerce-activity-ledger-summary",
+    summary_version: "xytara-activity-ledger-summary-v1",
+    activity_count: pack.counts.activity_count,
+    account_scope: pack.account_scope,
+    counts: pack.counts,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildActivityLedger,
+  summarizeActivityLedger
+};