@tradejs/cli 3.1.27-beta.248 → 3.1.27-beta.250

package/dist/lib/runtimeEvidenceCompositions.js

@@ -0,0 +1,548 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/runtimeEvidenceCompositions.ts
+var runtimeEvidenceCompositions_exports = {};
+__export(runtimeEvidenceCompositions_exports, {
+  loadRuntimeEvidenceCompositionSnapshots: () => loadRuntimeEvidenceCompositionSnapshots,
+  splitRuntimeEvidenceByComposition: () => splitRuntimeEvidenceByComposition
+});
+module.exports = __toCommonJS(runtimeEvidenceCompositions_exports);
+
+// src/lib/runtimeEvidenceArtifacts.ts
+var import_node_crypto = require("crypto");
+var import_promises = __toESM(require("fs/promises"));
+var import_node_path = __toESM(require("path"));
+
+// src/lib/runtimeEvidenceDeployment.ts
+var import_runtimeStrategies = require("@tradejs/node/runtimeStrategies");
+var isRecord = (value) => value != null && typeof value === "object" && !Array.isArray(value);
+var isNonEmptyString = (value) => typeof value === "string" && value.trim().length > 0;
+var isPackageVersionMap = (value) => isRecord(value) && Object.keys(value).length > 0 && Object.entries(value).every(
+  ([name, version]) => name.startsWith("@tradejs/") && isNonEmptyString(version)
+);
+var INTERVALS = /* @__PURE__ */ new Set([
+  "1",
+  "3",
+  "5",
+  "15",
+  "30",
+  "60",
+  "120",
+  "240",
+  "360",
+  "720",
+  "D",
+  "W",
+  "M"
+]);
+var UNIVERSES = /* @__PURE__ */ new Set(["crypto", "tradfi"]);
+var isRuntimeStrategySelection = (value) => value === void 0 || isRecord(value) && Object.keys(value).length === 1 && Object.keys(value).every((key) => key === "tickers") && Array.isArray(value.tickers) && value.tickers.length > 0 && value.tickers.every((ticker) => isNonEmptyString(ticker));
+var samePackageVersions = (left, right) => {
+  if (!left || !right) return false;
+  const leftEntries = Object.entries(left).sort(
+    ([a], [b]) => a.localeCompare(b)
+  );
+  const rightEntries = Object.entries(right).sort(
+    ([a], [b]) => a.localeCompare(b)
+  );
+  return JSON.stringify(leftEntries) === JSON.stringify(rightEntries);
+};
+var runtimeLineageMatchesStrategySnapshot = ({
+  lineage,
+  deployment,
+  strategy
+}) => lineage?.schemaVersion === 3 && lineage.strategyRevision === strategy.strategyRevision && lineage.deploymentCompositionId === deployment.deploymentCompositionId && lineage.strategyPackageVersion === strategy.strategyPackageVersion && lineage.runtimePackageVersion === strategy.runtimePackageVersion && samePackageVersions(
+  lineage.strategyDependencyVersions,
+  strategy.strategyDependencyVersions
+);
+var parseRuntimeEvidenceDeploymentSnapshot = (value) => {
+  if (!isRecord(value) || value.schemaVersion !== 2 || !isNonEmptyString(value.id) || !isNonEmptyString(value.deploymentCompositionId) || !/^dc1:[a-f0-9]{16}$/.test(value.deploymentCompositionId) || !isNonEmptyString(value.label) || !isNonEmptyString(value.connectorName) || !isNonEmptyString(value.provider) || !isNonEmptyString(value.accountId) || typeof value.enabled !== "boolean" || !Array.isArray(value.strategies)) {
+    throw new Error(
+      "Runtime evidence deployment snapshot is missing or invalid"
+    );
+  }
+  const strategies = value.strategies.map((candidate) => {
+    if (!isRecord(candidate) || !isNonEmptyString(candidate.strategyName) || !isNonEmptyString(candidate.strategyRevision) || !/^sr1:[a-f0-9]{16}$/.test(candidate.strategyRevision) || typeof candidate.enabled !== "boolean" || !["active", "entries_paused"].includes(String(candidate.controlState)) || !INTERVALS.has(String(candidate.interval)) || !UNIVERSES.has(String(candidate.universe)) || !isNonEmptyString(candidate.strategyPackage) || !isNonEmptyString(candidate.strategyPackageVersion) || !isPackageVersionMap(candidate.strategyDependencyVersions) || !isNonEmptyString(candidate.runtimePackageVersion) || !isRecord(candidate.strategyConfig) || !isRuntimeStrategySelection(candidate.selection)) {
+      throw new Error(
+        "Runtime evidence deployment strategy snapshot is invalid"
+      );
+    }
+    if (String(candidate.strategyConfig.INTERVAL) !== String(candidate.interval) || String(candidate.strategyConfig.UNIVERSE) !== String(candidate.universe)) {
+      throw new Error(
+        `Runtime evidence strategy config does not match its scope: ${candidate.strategyName}`
+      );
+    }
+    if (candidate.accountId != null && (!isNonEmptyString(candidate.accountId) || candidate.accountId !== value.accountId)) {
+      throw new Error(
+        `Runtime evidence strategy account does not match deployment: ${candidate.strategyName}`
+      );
+    }
+    return candidate;
+  });
+  const identities = /* @__PURE__ */ new Set();
+  for (const strategy of strategies) {
+    if (identities.has(strategy.strategyName)) {
+      throw new Error(
+        `Duplicate runtime evidence strategy: ${strategy.strategyName}`
+      );
+    }
+    identities.add(strategy.strategyName);
+  }
+  return {
+    ...value,
+    strategies
+  };
+};
+var activeRuntimeEvidenceStrategies = (deployment) => deployment.enabled ? deployment.strategies.filter((strategy) => strategy.enabled) : [];
+var unwrapRuntimeEvidenceRows = (value, field) => (Array.isArray(value) ? value : []).map((candidate) => {
+  const record = isRecord(candidate) ? candidate : null;
+  const nested = record && isRecord(record[field]) ? record[field] : null;
+  return nested ?? record;
+}).filter((record) => record != null);
+var assertCurrentRuntimeEvidenceArtifact = (artifact) => {
+  if (!isRecord(artifact) || artifact.reportType !== "runtime-evidence") {
+    throw new Error("Invalid runtime evidence artifact");
+  }
+  const deployment = parseRuntimeEvidenceDeploymentSnapshot(
+    artifact.deployment
+  );
+  const activeStrategies = activeRuntimeEvidenceStrategies(deployment);
+  if (activeStrategies.length === 0) {
+    throw new Error("Runtime evidence deployment has no enabled strategies");
+  }
+  const runtime = isRecord(artifact.runtime) ? artifact.runtime : null;
+  if (!runtime) {
+    throw new Error("Runtime evidence payload is missing");
+  }
+  if ("strategyConfigs" in runtime) {
+    throw new Error(
+      "Runtime evidence payload contains removed strategyConfigs data"
+    );
+  }
+  if ("evaluationStatsBuckets" in runtime) {
+    throw new Error(
+      "Runtime evidence payload contains removed lineage-less evaluationStatsBuckets data"
+    );
+  }
+  const rowFields = [
+    "trades",
+    "signals",
+    "evaluations",
+    "lineageScopes"
+  ];
+  for (const field of rowFields) {
+    if (!Array.isArray(runtime[field])) {
+      throw new Error(`Runtime evidence payload ${field} must be an array`);
+    }
+  }
+  const snapshots = new Map(
+    activeStrategies.map((strategy) => [strategy.strategyName, strategy])
+  );
+  const assertRows = (label, rows, lineageField) => {
+    for (const row of rows) {
+      const strategyName = String(row.strategy ?? "").trim();
+      const strategy = snapshots.get(strategyName);
+      if (!strategy || row.deploymentId !== deployment.id || row.accountId !== deployment.accountId || !runtimeLineageMatchesStrategySnapshot({
+        lineage: isRecord(row[lineageField]) ? row[lineageField] : void 0,
+        deployment,
+        strategy
+      })) {
+        throw new Error(
+          `Runtime evidence ${label} row is outside the current embedded deployment lineage`
+        );
+      }
+    }
+  };
+  assertRows(
+    "trade",
+    unwrapRuntimeEvidenceRows(runtime.trades, "trade"),
+    "runtimeLineage"
+  );
+  assertRows(
+    "signal",
+    unwrapRuntimeEvidenceRows(runtime.signals, "signal"),
+    "runtimeLineage"
+  );
+  assertRows(
+    "evaluation",
+    unwrapRuntimeEvidenceRows(runtime.evaluations, "evaluation"),
+    "runtimeLineage"
+  );
+  assertRows(
+    "lineage scope",
+    unwrapRuntimeEvidenceRows(runtime.lineageScopes, "lineageScope"),
+    "lineage"
+  );
+  return deployment;
+};
+
+// src/lib/runtimeEvidenceArtifacts.ts
+var RUNTIME_EVIDENCE_MANIFEST_FILE = "manifest.json";
+var RUNTIME_EVIDENCE_PAYLOAD_FILE = "runtime-evidence.json";
+var RUNTIME_EVIDENCE_COMPLETE_FILE = ".complete";
+var asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+var sha256 = (value) => (0, import_node_crypto.createHash)("sha256").update(value).digest("hex");
+var assertFiniteTimestamp = (value, label) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Invalid runtime evidence ${label}`);
+  }
+  return value;
+};
+var parseManifest = (value) => {
+  const manifest = asRecord(value);
+  const window = asRecord(manifest?.window);
+  const payload = asRecord(manifest?.payload);
+  const counts = asRecord(manifest?.counts);
+  if (manifest?.schemaVersion !== 1 || manifest.reportType !== "runtime-evidence" || typeof manifest.artifactId !== "string" || typeof manifest.deploymentId !== "string" || typeof manifest.userName !== "string" || typeof manifest.createdAt !== "number" || payload?.file !== RUNTIME_EVIDENCE_PAYLOAD_FILE || typeof payload.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(payload.sha256) || typeof payload.bytes !== "number" || !Array.isArray(manifest.lineageKeys)) {
+    throw new Error("Invalid runtime evidence manifest");
+  }
+  return {
+    schemaVersion: 1,
+    artifactId: manifest.artifactId,
+    reportType: "runtime-evidence",
+    deploymentId: manifest.deploymentId,
+    userName: manifest.userName,
+    createdAt: manifest.createdAt,
+    window: {
+      startTime: assertFiniteTimestamp(window?.startTime, "window.startTime"),
+      endTime: assertFiniteTimestamp(window?.endTime, "window.endTime")
+    },
+    payload: {
+      file: RUNTIME_EVIDENCE_PAYLOAD_FILE,
+      sha256: payload.sha256,
+      bytes: payload.bytes
+    },
+    counts: Object.fromEntries(
+      Object.entries(counts ?? {}).filter(
+        (entry) => typeof entry[1] === "number" && Number.isFinite(entry[1])
+      )
+    ),
+    lineageKeys: manifest.lineageKeys.filter(
+      (value2) => typeof value2 === "string" && value2.length > 0
+    )
+  };
+};
+var verifyRuntimeEvidenceBundle = async (bundleDir) => {
+  const manifestPath = import_node_path.default.join(bundleDir, RUNTIME_EVIDENCE_MANIFEST_FILE);
+  const payloadPath = import_node_path.default.join(bundleDir, RUNTIME_EVIDENCE_PAYLOAD_FILE);
+  const completePath = import_node_path.default.join(bundleDir, RUNTIME_EVIDENCE_COMPLETE_FILE);
+  const [manifestText, payload, completeText] = await Promise.all([
+    import_promises.default.readFile(manifestPath, "utf8"),
+    import_promises.default.readFile(payloadPath),
+    import_promises.default.readFile(completePath, "utf8")
+  ]);
+  const manifest = parseManifest(JSON.parse(manifestText));
+  if (completeText.trim() !== manifest.artifactId) {
+    throw new Error(`Invalid completion marker in ${bundleDir}`);
+  }
+  if (payload.byteLength !== manifest.payload.bytes) {
+    throw new Error(`Runtime evidence size mismatch in ${bundleDir}`);
+  }
+  if (sha256(payload) !== manifest.payload.sha256) {
+    throw new Error(`Runtime evidence checksum mismatch in ${bundleDir}`);
+  }
+  const artifact = asRecord(JSON.parse(payload.toString("utf8")));
+  const artifactWindow = asRecord(artifact?.window);
+  if (artifact?.reportType !== "runtime-evidence" || artifactWindow?.startTime !== manifest.window.startTime || artifactWindow.endTime !== manifest.window.endTime) {
+    throw new Error(`Runtime evidence payload mismatch in ${bundleDir}`);
+  }
+  const deployment = assertCurrentRuntimeEvidenceArtifact(artifact);
+  if (deployment.id !== manifest.deploymentId) {
+    throw new Error(`Runtime evidence deployment mismatch in ${bundleDir}`);
+  }
+  return {
+    bundleDir,
+    manifestPath,
+    payloadPath,
+    manifest,
+    artifact
+  };
+};
+var discoverRuntimeEvidenceBundles = async (rootDir) => {
+  const bundles = [];
+  const visit = async (directory, depth) => {
+    if (depth > 8) return;
+    let entries;
+    try {
+      entries = await import_promises.default.readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+    const names = new Set(entries.map((entry) => entry.name));
+    if (names.has(RUNTIME_EVIDENCE_MANIFEST_FILE) && names.has(RUNTIME_EVIDENCE_PAYLOAD_FILE) && names.has(RUNTIME_EVIDENCE_COMPLETE_FILE)) {
+      bundles.push(directory);
+      return;
+    }
+    await Promise.all(
+      entries.filter(
+        (entry) => entry.isDirectory() && !entry.name.startsWith(".") && !entry.name.includes(".tmp-")
+      ).map((entry) => visit(import_node_path.default.join(directory, entry.name), depth + 1))
+    );
+  };
+  await visit(rootDir, 0);
+  return bundles.sort();
+};
+
+// src/lib/runtimeEvidenceCompositionSnapshots.ts
+var import_node_crypto3 = require("crypto");
+var import_promises3 = __toESM(require("fs/promises"));
+var import_node_path3 = __toESM(require("path"));
+
+// src/lib/runtimeEvidenceProducer.ts
+var import_node_crypto2 = require("crypto");
+var import_promises2 = __toESM(require("fs/promises"));
+var import_node_path2 = __toESM(require("path"));
+var isRecord2 = (value) => value != null && typeof value === "object" && !Array.isArray(value);
+var parseRuntimeEvidenceProducer = (value) => {
+  const producer = isRecord2(value) ? value : null;
+  const runtimePackageManifest = isRecord2(producer?.runtimePackageManifest) ? producer.runtimePackageManifest : null;
+  if (producer?.schemaVersion !== 1 || typeof producer.projectSha !== "string" || !/^[a-f0-9]{40}$/.test(producer.projectSha) || typeof producer.imageDigest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(producer.imageDigest) || runtimePackageManifest?.file !== "runtime-package-manifest.json" || typeof runtimePackageManifest.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(runtimePackageManifest.sha256)) {
+    throw new Error("Runtime evidence producer image identity is invalid");
+  }
+  return producer;
+};
+
+// src/lib/runtimeEvidenceCompositionSnapshots.ts
+var SNAPSHOT_FILE = "snapshot.json";
+var MANIFEST_FILE = "manifest.json";
+var COMPLETE_FILE = ".complete";
+var isRecord3 = (value) => value != null && typeof value === "object" && !Array.isArray(value);
+var sha2562 = (value) => (0, import_node_crypto3.createHash)("sha256").update(value).digest("hex");
+var parseManifest2 = (value) => {
+  const manifest = isRecord3(value) ? value : null;
+  const payload = isRecord3(manifest?.payload) ? manifest.payload : null;
+  if (manifest?.schemaVersion !== 1 || manifest.reportType !== "runtime-evidence-composition-snapshot" || typeof manifest.createdAt !== "number" || typeof manifest.userName !== "string" || typeof manifest.deploymentId !== "string" || typeof manifest.deploymentCompositionId !== "string" || payload?.file !== SNAPSHOT_FILE || typeof payload.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(payload.sha256) || typeof payload.bytes !== "number") {
+    throw new Error("Invalid runtime evidence composition snapshot manifest");
+  }
+  return manifest;
+};
+var verifyRuntimeEvidenceCompositionSnapshot = async (bundleDir) => {
+  const [manifestText, payload, completeText] = await Promise.all([
+    import_promises3.default.readFile(import_node_path3.default.join(bundleDir, MANIFEST_FILE), "utf8"),
+    import_promises3.default.readFile(import_node_path3.default.join(bundleDir, SNAPSHOT_FILE)),
+    import_promises3.default.readFile(import_node_path3.default.join(bundleDir, COMPLETE_FILE), "utf8")
+  ]);
+  const manifest = parseManifest2(JSON.parse(manifestText));
+  if (completeText.trim() !== manifest.deploymentCompositionId) {
+    throw new Error(`Invalid completion marker in ${bundleDir}`);
+  }
+  if (payload.byteLength !== manifest.payload.bytes || sha2562(payload) !== manifest.payload.sha256) {
+    throw new Error(
+      `Runtime evidence snapshot checksum mismatch in ${bundleDir}`
+    );
+  }
+  const value = JSON.parse(payload.toString("utf8"));
+  const record = isRecord3(value) ? value : null;
+  if (record?.schemaVersion !== 1 || record.reportType !== "runtime-evidence-composition-snapshot" || record.userName !== manifest.userName) {
+    throw new Error(
+      `Invalid runtime evidence snapshot payload in ${bundleDir}`
+    );
+  }
+  const deployment = parseRuntimeEvidenceDeploymentSnapshot(record.deployment);
+  const producer = parseRuntimeEvidenceProducer(record.producer);
+  if (deployment.id !== manifest.deploymentId || deployment.deploymentCompositionId !== manifest.deploymentCompositionId) {
+    throw new Error(
+      `Runtime evidence snapshot identity mismatch in ${bundleDir}`
+    );
+  }
+  return { bundleDir, deployment, producer };
+};
+var discoverRuntimeEvidenceCompositionSnapshots = async (evidenceRoot) => {
+  const rootDir = import_node_path3.default.join(evidenceRoot, "snapshots");
+  const bundleDirs = [];
+  let deployments;
+  try {
+    deployments = await import_promises3.default.readdir(rootDir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  for (const deployment of deployments.filter((entry) => entry.isDirectory())) {
+    const deploymentDir = import_node_path3.default.join(rootDir, deployment.name);
+    const compositions = await import_promises3.default.readdir(deploymentDir, {
+      withFileTypes: true
+    });
+    bundleDirs.push(
+      ...compositions.filter(
+        (entry) => entry.isDirectory() && !entry.name.startsWith(".") && !entry.name.includes(".tmp-")
+      ).map((entry) => import_node_path3.default.join(deploymentDir, entry.name))
+    );
+  }
+  return Promise.all(
+    bundleDirs.sort().map(verifyRuntimeEvidenceCompositionSnapshot)
+  );
+};
+
+// src/lib/runtimeEvidenceCompositions.ts
+var stableSnapshotIdentity = (deployment) => JSON.stringify({ ...deployment, tickers: void 0 });
+var producerIdentity = (producer) => JSON.stringify(producer);
+var loadRuntimeEvidenceCompositionSnapshots = async ({
+  publishRoot,
+  currentDeployment,
+  currentProducer
+}) => {
+  const snapshots = /* @__PURE__ */ new Map();
+  const register = (snapshot) => {
+    const compositionId = snapshot.deployment.deploymentCompositionId;
+    const known = snapshots.get(compositionId);
+    if (known && (stableSnapshotIdentity(known.deployment) !== stableSnapshotIdentity(snapshot.deployment) || producerIdentity(known.producer) !== producerIdentity(snapshot.producer))) {
+      throw new Error(
+        `Conflicting runtime evidence snapshot for composition ${compositionId}`
+      );
+    }
+    snapshots.set(compositionId, snapshot);
+  };
+  const compositionSnapshots = await discoverRuntimeEvidenceCompositionSnapshots(publishRoot);
+  for (const snapshot of compositionSnapshots) {
+    if (snapshot.deployment.id !== currentDeployment.id) continue;
+    register({
+      deployment: { ...snapshot.deployment, tickers: void 0 },
+      producer: snapshot.producer
+    });
+  }
+  const bundleDirs = await discoverRuntimeEvidenceBundles(publishRoot);
+  for (const bundleDir of bundleDirs) {
+    const bundle = await verifyRuntimeEvidenceBundle(bundleDir);
+    const deployment = parseRuntimeEvidenceDeploymentSnapshot(
+      bundle.artifact.deployment
+    );
+    if (deployment.id !== currentDeployment.id) continue;
+    if (bundle.artifact.producer == null) continue;
+    register({
+      deployment: { ...deployment, tickers: void 0 },
+      producer: parseRuntimeEvidenceProducer(bundle.artifact.producer)
+    });
+  }
+  const historicalCurrent = snapshots.get(
+    currentDeployment.deploymentCompositionId
+  );
+  if (historicalCurrent && stableSnapshotIdentity(historicalCurrent.deployment) !== stableSnapshotIdentity(currentDeployment)) {
+    throw new Error(
+      `Current runtime deployment conflicts with stored composition ${currentDeployment.deploymentCompositionId}`
+    );
+  }
+  snapshots.set(currentDeployment.deploymentCompositionId, {
+    deployment: { ...currentDeployment, tickers: void 0 },
+    producer: currentProducer
+  });
+  return snapshots;
+};
+var rowCompositionId = (row) => row.runtimeLineage?.deploymentCompositionId ?? row.lineage?.deploymentCompositionId ?? null;
+var rowTimestamp = (row) => {
+  for (const field of [
+    "firstTimestamp",
+    "entryTimestamp",
+    "timestamp",
+    "lastTimestamp"
+  ]) {
+    const value = row[field];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return Number.POSITIVE_INFINITY;
+};
+var belongsToSnapshot = (row, deployment) => {
+  const strategy = activeRuntimeEvidenceStrategies(deployment).find(
+    (candidate) => candidate.strategyName === row.strategy
+  );
+  return Boolean(
+    strategy && row.deploymentId === deployment.id && row.accountId === deployment.accountId && runtimeLineageMatchesStrategySnapshot({
+      lineage: row.runtimeLineage ?? row.lineage,
+      deployment,
+      strategy
+    })
+  );
+};
+var splitRuntimeEvidenceByComposition = ({
+  evidence,
+  snapshots,
+  includeEmptyCompositionIds = [],
+  ignoreUnknownCompositions = false
+}) => {
+  const observed = /* @__PURE__ */ new Set();
+  for (const row of [
+    ...evidence.trades,
+    ...evidence.signals,
+    ...evidence.evaluations,
+    ...evidence.lineageScopes
+  ]) {
+    const compositionId = rowCompositionId(row);
+    if (compositionId) observed.add(compositionId);
+  }
+  for (const compositionId of includeEmptyCompositionIds) {
+    observed.add(compositionId);
+  }
+  const missing = [...observed].filter(
+    (compositionId) => !snapshots.has(compositionId)
+  );
+  if (missing.length && !ignoreUnknownCompositions) {
+    throw new Error(
+      `Runtime evidence has no verified deployment snapshot for composition(s): ${missing.sort().join(", ")}`
+    );
+  }
+  return [...observed].filter((compositionId) => snapshots.has(compositionId)).map((compositionId) => snapshots.get(compositionId)).map(({ deployment, producer }) => {
+    const trades = evidence.trades.filter(
+      (row) => belongsToSnapshot(row, deployment)
+    );
+    const signals = evidence.signals.filter(
+      (row) => belongsToSnapshot(row, deployment)
+    );
+    const evaluations = evidence.evaluations.filter(
+      (row) => belongsToSnapshot(row, deployment)
+    );
+    const lineageScopes = evidence.lineageScopes.filter(
+      (row) => belongsToSnapshot(row, deployment)
+    );
+    const timestamps = [
+      ...trades,
+      ...signals,
+      ...evaluations,
+      ...lineageScopes
+    ].map((row) => rowTimestamp(row));
+    return {
+      deployment,
+      producer,
+      trades,
+      signals,
+      evaluations,
+      lineageScopes,
+      firstTimestamp: Math.min(...timestamps)
+    };
+  }).sort(
+    (left, right) => left.firstTimestamp - right.firstTimestamp || left.deployment.deploymentCompositionId.localeCompare(
+      right.deployment.deploymentCompositionId
+    )
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadRuntimeEvidenceCompositionSnapshots,
+  splitRuntimeEvidenceByComposition
+});