chainlesschain 0.166.45 → 0.166.47

package/src/lib/evolution/evolution-eval-runtime-composition.js

@@ -0,0 +1,255 @@
+import { types as utilTypes } from "node:util";
+
+import {
+  EvolutionEvalChildEvidenceLedgerAdapter,
+  createEvolutionEvalChildEvidenceStorePort,
+} from "./evolution-eval-child-evidence-ledger-adapter.js";
+import {
+  SkillTargetMatrixEvalAggregator,
+  SkillTargetMatrixEvalReceiptVerifier,
+} from "./skill-target-matrix-eval.js";
+import { createSkillEvaluatedPromotionDurabilityAdapter } from "./skill-evaluated-promotion-durability.js";
+
+export const EVOLUTION_EVAL_RUNTIME_COMPOSITION_SCHEMA =
+  "chainlesschain.evolution-eval-runtime-composition/v1";
+export const EVOLUTION_EVAL_COMPOSITION_UNAVAILABLE_CODE =
+  "CC_EVOLUTION_EVAL_COMPOSITION_UNAVAILABLE";
+
+const COMPOSITIONS = new WeakMap();
+const DESCRIPTOR_KEYS = [
+  "tenantId",
+  "runId",
+  "authorityId",
+  "revision",
+  "handlerArtifactDigest",
+];
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+function unavailable(message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = EVOLUTION_EVAL_COMPOSITION_UNAVAILABLE_CODE;
+  return error;
+}
+
+function record(value, keys, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    utilTypes.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  )
+    throw unavailable(`${label} must be a plain data record`);
+  const ownKeys = Reflect.ownKeys(value);
+  if (
+    keys &&
+    (ownKeys.length !== keys.length ||
+      ownKeys.some((key) => !keys.includes(key)))
+  )
+    throw unavailable(`${label} must contain exactly the required ports`);
+  for (const key of ownKeys) {
+    const property = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      typeof key !== "string" ||
+      !property ||
+      !("value" in property) ||
+      !property.enumerable
+    )
+      throw unavailable(`${label}.${String(key)} must be an own data property`);
+  }
+  return value;
+}
+
+function descriptor(input) {
+  record(input, DESCRIPTOR_KEYS, "Eval composition descriptor");
+  for (const key of ["tenantId", "runId", "authorityId"])
+    if (typeof input[key] !== "string" || !ID.test(input[key]))
+      throw unavailable(`Eval composition ${key} is invalid`);
+  if (
+    !Number.isSafeInteger(input.revision) ||
+    input.revision < 1 ||
+    typeof input.handlerArtifactDigest !== "string" ||
+    !DIGEST.test(input.handlerArtifactDigest)
+  )
+    throw unavailable("Eval composition authority revision/digest is invalid");
+  return Object.freeze({ ...input });
+}
+
+/**
+ * Host-authorized construction only: supplies no signing keys, policy defaults,
+ * grader, corpus, reservation service, supervisor, or durability authority.
+ * Receipt verification uses the exact authority pair captured by the aggregator.
+ */
+export function createEvolutionEvalRuntimeComposition(options) {
+  try {
+    record(
+      options,
+      [
+        "descriptor",
+        "aggregatorOptions",
+        "verificationLimits",
+        "durabilityOptions",
+      ],
+      "Eval composition options",
+    );
+    const binding = descriptor(options.descriptor);
+    const matrix = {
+      ...record(options.aggregatorOptions, null, "Eval aggregator options"),
+    };
+    const limits = record(
+      options.verificationLimits,
+      ["maximumReceiptTtlMs", "maximumVerificationMs"],
+      "Eval verification limits",
+    );
+    if (matrix.tenantId !== binding.tenantId)
+      throw unavailable("Eval aggregator belongs to another tenant");
+    const aggregator = new SkillTargetMatrixEvalAggregator(matrix);
+    const receiptVerifier = new SkillTargetMatrixEvalReceiptVerifier({
+      matrixReceiptVerifier: matrix.matrixReceiptVerifier,
+      matrixReceiptSignerDescriptor:
+        matrix.matrixReceiptSigner.authorityDescriptor,
+      matrixReceiptTrust: matrix.matrixReceiptTrust,
+      matrixSupervisor: matrix.matrixSupervisor,
+      supervisorPolicy: matrix.supervisorPolicy,
+      clock: matrix.clock,
+      clockPolicy: matrix.clockPolicy,
+      ...limits,
+    });
+    const durability = createSkillEvaluatedPromotionDurabilityAdapter(
+      options.durabilityOptions,
+    );
+    const composition = Object.freeze({
+      schema: EVOLUTION_EVAL_RUNTIME_COMPOSITION_SCHEMA,
+      descriptor: binding,
+      // Downstream promotion can reuse the same read-only receipt authorities.
+      receiptVerifier,
+      receiptResolver: durability.resolver,
+    });
+    COMPOSITIONS.set(
+      composition,
+      Object.freeze({
+        aggregator,
+        receiptVerifier,
+        durability,
+        childReceiptStore: matrix.childReceiptStore,
+      }),
+    );
+    return composition;
+  } catch (cause) {
+    if (cause?.code === EVOLUTION_EVAL_COMPOSITION_UNAVAILABLE_CODE)
+      throw cause;
+    throw unavailable("Eval production authority construction failed", cause);
+  }
+}
+
+export function captureEvolutionEvalRuntimeComposition(value, expected) {
+  const ports = COMPOSITIONS.get(value);
+  if (!ports)
+    throw unavailable("a branded Eval runtime composition is required");
+  if (expected) {
+    for (const key of DESCRIPTOR_KEYS)
+      if (value.descriptor[key] !== expected.descriptor[key])
+        throw unavailable(`Eval composition differs from runtime ${key}`);
+    if (ports.childReceiptStore !== expected.childReceiptStore)
+      throw unavailable(
+        "Eval composition must use the runtime child evidence store",
+      );
+  }
+  return ports;
+}
+
+/** Root-owned authenticated storage; the host receives no ledger write port. */
+export function createEvolutionEvalRuntimeChildEvidenceStore({
+  descriptor: input,
+  artifactPorts,
+  ledger,
+  ledgerArtifactResolver,
+  audience,
+  now,
+}) {
+  const binding = descriptor(input);
+  const storeDescriptor = Object.freeze({
+    tenantId: binding.tenantId,
+    streamId: binding.runId,
+    authorityId: binding.authorityId,
+    revision: binding.revision,
+    handlerArtifactDigest: binding.handlerArtifactDigest,
+  });
+  const adapter = new EvolutionEvalChildEvidenceLedgerAdapter({
+    descriptor: {
+      ...storeDescriptor,
+      artifactTenantId: binding.tenantId,
+      audience,
+      purpose: "evolution-ledger",
+    },
+    artifactPorts,
+    ledger,
+    ledgerArtifactResolver,
+    now,
+  });
+  return createEvolutionEvalChildEvidenceStorePort({
+    descriptor: storeDescriptor,
+    retain: adapter.retain.bind(adapter),
+    resolve: adapter.resolve.bind(adapter),
+  });
+}
+
+/** Called only by the Agent root after constructing its authenticated backend. */
+export function createEvolutionEvalRuntimeStageConfiguration({
+  configuration,
+  tenantId,
+  runId,
+  ...storage
+}) {
+  try {
+    record(
+      configuration,
+      [
+        "descriptor",
+        "createComposition",
+        "planRef",
+        "expectedReceipt",
+        "usage",
+      ],
+      "releaseTrain.domain.eval",
+    );
+    record(
+      configuration.descriptor,
+      ["authorityId", "revision", "handlerArtifactDigest"],
+      "releaseTrain.domain.eval.descriptor",
+    );
+    const binding = descriptor({
+      ...configuration.descriptor,
+      tenantId,
+      runId,
+    });
+    const factory = configuration.createComposition;
+    if (
+      typeof factory !== "function" ||
+      utilTypes.isProxy(factory) ||
+      utilTypes.isAsyncFunction(factory) ||
+      utilTypes.isGeneratorFunction(factory)
+    )
+      throw unavailable("Eval createComposition must be a synchronous factory");
+    const childReceiptStore = createEvolutionEvalRuntimeChildEvidenceStore({
+      descriptor: binding,
+      ...storage,
+    });
+    const context = Object.freeze({ descriptor: binding, childReceiptStore });
+    const composition = Reflect.apply(factory, undefined, [context]);
+    const { aggregator, receiptVerifier, durability } =
+      captureEvolutionEvalRuntimeComposition(composition, context);
+    return Object.freeze({
+      aggregator,
+      receiptVerifier,
+      durability,
+      planRef: configuration.planRef,
+      expectedReceipt: configuration.expectedReceipt,
+      usage: configuration.usage,
+    });
+  } catch (cause) {
+    if (cause?.code === EVOLUTION_EVAL_COMPOSITION_UNAVAILABLE_CODE)
+      throw cause;
+    throw unavailable("Eval production composition is unavailable", cause);
+  }
+}

package/src/lib/evolution/evolution-evidence-artifact-adapter.js

@@ -12,9 +12,11 @@ import { types as utilTypes } from "node:util";
 import { ArtifactStore } from "../artifact-store.js";
 import {
   EvolutionArtifactPorts,
+  EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA,
   EVOLUTION_ARTIFACT_DEFAULT_TTL_MS,
   EVOLUTION_ARTIFACT_MAX_TTL_MS,
 } from "./evolution-artifact-ports.js";
+import { EVOLUTION_ARTIFACT_REF_SCHEMA } from "./evolution-ledger.js";
 import {
   EVOLUTION_RAW_STORAGE_RECEIPT_SCHEMA,
   EvolutionEvidenceBundleVerifier,
@@ -340,6 +342,7 @@ export class EvolutionEvidenceArtifactAdapter {
   #projectAgentModel;
   #verify;
   #ports;
+  #resolveManifestRef;
 
   constructor({
     tenantId,
@@ -384,6 +387,10 @@ export class EvolutionEvidenceArtifactAdapter {
     );
     this.#verify = captureMethod(bundleVerifier, "verify", "bundleVerifier");
     this.#ports = artifactPorts;
+    this.#resolveManifestRef =
+      artifactPorts.createEvolutionLedgerArtifactResolver({
+        purpose: this.#purpose,
+      });
     Object.freeze(this);
   }
 
@@ -468,11 +475,60 @@ export class EvolutionEvidenceArtifactAdapter {
       purpose: this.#purpose,
       tenantId: this.#tenantId,
     });
-    const manifest = manifestResolved.value;
+    return this.#resolveManifest(manifestResolved.value, result.evidenceId);
+  }
+
+  /**
+   * Authenticate retained bytes at a Run's manifest locator. This is NOT Run
+   * membership or caller read authorization: the Wiki resolver obtains the
+   * event from its captured Run capability and separately calls readTrusted.
+   */
+  async resolveRunEvidence({ event, ledgerId, epoch } = {}) {
+    if (
+      event?.type !== "raw-event-referenced" ||
+      event.tenantId !== this.#tenantId ||
+      event.data?.derivationManifestDigest !== event.payloadDigest
+    ) {
+      throw new TypeError("Run evidence manifest binding is invalid");
+    }
+    const evidenceId = normalizeId(event.subjectId, "Run evidenceId");
+    const resolved = this.#resolveManifestRef({
+      tenantId: this.#tenantId,
+      ledgerId,
+      epoch,
+      ref: {
+        schema: EVOLUTION_ARTIFACT_REF_SCHEMA,
+        ref: event.artifactRef,
+        digest: event.payloadDigest,
+      },
+    });
+    if (
+      resolved.authenticated !== true ||
+      resolved.found !== true ||
+      resolved.digest !== event.payloadDigest ||
+      resolved.ref !== event.artifactRef ||
+      !Buffer.isBuffer(resolved.bytes)
+    ) {
+      throw new Error("Run evidence manifest resolution is unbound");
+    }
+    const record = JSON.parse(resolved.bytes.toString("utf8"));
+    if (
+      record.schema !== EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA ||
+      record.tenantId !== this.#tenantId ||
+      record.audience !== this.#audience ||
+      record.purpose !== this.#purpose ||
+      record.type !== "evidence"
+    ) {
+      throw new Error("Run evidence manifest record is unbound");
+    }
+    return this.#resolveManifest(record.value, evidenceId);
+  }
+
+  async #resolveManifest(manifest, evidenceId) {
     if (
       manifest.schema !== EVOLUTION_EVIDENCE_DERIVATION_MANIFEST_SCHEMA ||
       manifest.tenantId !== this.#tenantId ||
-      manifest.evidenceId !== result.evidenceId
+      manifest.evidenceId !== evidenceId
     ) {
       throw new Error("evidence derivation manifest is invalid");
     }

package/src/lib/evolution/evolution-ledger-file-backend.js

@@ -1,7 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createEvolutionFileWitness } from "./evolution-file-witness.js";
-import { EvolutionLedger } from "./evolution-ledger.js";
+import {
+  EvolutionLedger,
+  captureEvolutionLedgerMigrationSource,
+} from "./evolution-ledger.js";
+import { createEvolutionLedgerV2JournalFromFactory } from "./evolution-ledger-v2-journal.js";
 
 export const EVOLUTION_LEDGER_FILE_BACKEND_SCHEMA =
   "chainlesschain.evolution-ledger-file-backend/v1";
@@ -110,6 +114,7 @@ export function createEvolutionLedgerFileBackend({
   crashHook = null,
   witnessMaximumBytes,
   witnessMaximumHistoryBytes,
+  manifestV2 = null,
 } = {}) {
   if (typeof artifactResolver !== "function") {
     throw new TypeError("artifactResolver port is required");
@@ -151,7 +156,7 @@ export function createEvolutionLedgerFileBackend({
       : { maximumHistoryBytes: witnessMaximumHistoryBytes }),
   };
   const witness = createEvolutionFileWitness(witnessOptions);
-  const ledger = new EvolutionLedger({
+  const sourceLedger = new EvolutionLedger({
     rootDir: paths.eventRoot,
     authorityRootDir: paths.authorityRoot,
     secure,
@@ -170,6 +175,22 @@ export function createEvolutionLedgerFileBackend({
     ...(lockTimeoutMs === undefined ? {} : { lockTimeoutMs }),
     crashHook,
   });
+  if (
+    manifestV2 === null &&
+    captureEvolutionLedgerMigrationSource(sourceLedger).requiresV2()
+  ) {
+    throw Object.assign(
+      new Error("migrated ledger requires its authenticated v2 composition"),
+      { code: "CC_EVOLUTION_LEDGER_V2_REQUIRED" },
+    );
+  }
+  const ledger =
+    manifestV2 === null
+      ? sourceLedger
+      : createEvolutionLedgerV2JournalFromFactory(sourceLedger, manifestV2, {
+          ...(lock === undefined ? {} : { lock }),
+          ...(lockTimeoutMs === undefined ? {} : { lockTimeoutMs }),
+        });
   const backend = Object.freeze({
     schema: EVOLUTION_LEDGER_FILE_BACKEND_SCHEMA,
     descriptor: Object.freeze({

package/src/lib/evolution/evolution-ledger-manifest-chain.js

@@ -11,6 +11,8 @@ export const EVOLUTION_LEDGER_MANIFEST_CHAIN_SCHEMA =
   "chainlesschain.evolution-ledger-manifest-chain/v2";
 export const EVOLUTION_LEDGER_SEGMENT_PAYLOAD_SCHEMA =
   "chainlesschain.evolution-ledger-segment-payload/v2";
+export const EVOLUTION_LEDGER_EVENT_PAYLOAD_SCHEMA =
+  "chainlesschain.evolution-ledger-event-payload/v2";
 export const EVOLUTION_LEDGER_SEGMENT_MANIFEST_SCHEMA =
   "chainlesschain.evolution-ledger-segment-manifest/v2";
 export const EVOLUTION_LEDGER_MANIFEST_HEAD_SCHEMA =
@@ -336,8 +338,163 @@ function payload(sequenceStart, eventDigests) {
   });
 }
 
+// Snapshot only bounded canonical JSON. Do not invoke getters, toJSON or Proxy
+// traps while capturing signed event bytes supplied to the storage boundary.
+function snapshotEvent(
+  value,
+  depth = 0,
+  seen = new Set(),
+  budget = { bytes: 64 * 1024 * 1024, nodes: 1_000_000 },
+) {
+  rejectProxy(value, "event payload");
+  budget.bytes -=
+    typeof value === "string" ? Buffer.byteLength(value, "utf8") : 8;
+  if (--budget.nodes < 0 || budget.bytes < 0)
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event payload exceeds bounded capacity",
+    );
+  if (depth > 32 || seen.has(value))
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event payload is cyclic or too deep",
+    );
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (
+    !value ||
+    typeof value !== "object" ||
+    ![Array.isArray(value) ? Array.prototype : Object.prototype, null].includes(
+      Object.getPrototypeOf(value),
+    )
+  )
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event payload must be JSON data",
+    );
+  seen.add(value);
+  const array = Array.isArray(value);
+  const result = array ? [] : Object.create(null);
+  const keys = Reflect.ownKeys(value).filter(
+    (key) => !(array && key === "length"),
+  );
+  if (array && keys.length !== value.length)
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event payload array must be dense",
+    );
+  for (const key of keys) {
+    const property = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      typeof key !== "string" ||
+      !property.enumerable ||
+      !("value" in property) ||
+      (array &&
+        (!/^(0|[1-9][0-9]*)$/u.test(key) || Number(key) >= value.length))
+    )
+      throw failure(
+        EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+        "event payload must contain own data properties",
+      );
+    budget.bytes -= Buffer.byteLength(key, "utf8");
+    result[key] = snapshotEvent(property.value, depth + 1, seen, budget);
+  }
+  seen.delete(value);
+  return Object.freeze(result);
+}
+
+function eventPayload(sequenceStart, input, expected = {}) {
+  rejectProxy(input, "event payload");
+  if (
+    !Array.isArray(input) ||
+    input.length < 1 ||
+    input.length > MAX_EVENTS_PER_SEGMENT
+  )
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event payload count is invalid",
+    );
+  const events = snapshotEvent(input);
+  if (
+    !Array.isArray(events) ||
+    events.length < 1 ||
+    events.length > MAX_EVENTS_PER_SEGMENT
+  )
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event payload count is invalid",
+    );
+  let previous = expected.previousDigest;
+  for (const [index, event] of events.entries()) {
+    if (
+      !event ||
+      ![
+        "chainlesschain.evolution-event/v2",
+        "chainlesschain.evolution-domain-event/v1",
+      ].includes(event.schema)
+    )
+      throw failure(
+        EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
+        "event payload schema is invalid",
+      );
+    const { eventDigest, signature, ...core } = event;
+    const signatureFields = exactRecord(
+      signature,
+      new Set(["algorithm", "keyId", "trustPolicyDigest", "value"]),
+      "event payload signature",
+      EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
+    );
+    if (
+      ["algorithm", "keyId", "trustPolicyDigest"].some(
+        (field) => data(signatureFields, field) !== event[field],
+      ) ||
+      typeof signature.value !== "string" ||
+      signature.value.length < 1 ||
+      signature.value.length > 16_384
+    )
+      throw failure(
+        EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
+        "event signature binding differs",
+      );
+    if (
+      !signature ||
+      event.sequence !== sequenceStart + index ||
+      eventDigest !==
+        sha256(Buffer.from(`${event.schema}\0${canonical(core)}`, "utf8")) ||
+      (previous !== undefined && event.prevDigest !== previous) ||
+      (expected.epoch !== undefined && event.epoch !== expected.epoch) ||
+      (expected.ledgerId !== undefined &&
+        event.ledgerId !== expected.ledgerId) ||
+      (expected.tenantId !== undefined && event.tenantId !== expected.tenantId)
+    )
+      throw failure(
+        EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
+        "event payload digest, sequence or scope is invalid",
+      );
+    if (Buffer.byteLength(canonical(event), "utf8") > 1024 * 1024)
+      throw failure(
+        EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+        "event payload exceeds the event byte limit",
+      );
+    previous = eventDigest;
+  }
+  return Object.freeze({
+    events,
+    schema: EVOLUTION_LEDGER_EVENT_PAYLOAD_SCHEMA,
+    sequenceStart,
+    sequenceEnd: sequenceStart + events.length - 1,
+  });
+}
+
 function payloadBytes(value) {
-  return Buffer.from(canonical(value), "utf8");
+  const bytes = Buffer.from(canonical(value), "utf8");
+  if (bytes.length > 64 * 1024 * 1024)
+    throw failure(
+      EVOLUTION_LEDGER_MANIFEST_INVALID_CODE,
+      "event segment exceeds byte capacity",
+    );
+  return bytes;
 }
 
 function parsePayload(bytes, expected) {
@@ -356,6 +513,28 @@ function parsePayload(bytes, expected) {
       "manifest segment payload is not JSON",
     );
   }
+  if (raw.schema === EVOLUTION_LEDGER_EVENT_PAYLOAD_SCHEMA) {
+    exactRecord(
+      raw,
+      new Set(["events", "schema", "sequenceStart", "sequenceEnd"]),
+      "event segment payload",
+    );
+    const parsed = eventPayload(expected.sequenceStart, raw.events, expected);
+    if (
+      !payloadBytes(parsed).equals(bytes) ||
+      raw.sequenceEnd !== expected.sequenceEnd
+    )
+      throw failure(
+        EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
+        "event segment payload range differs",
+      );
+    return Object.freeze({
+      ...parsed,
+      eventDigests: Object.freeze(
+        parsed.events.map((event) => event.eventDigest),
+      ),
+    });
+  }
   const fields = exactRecord(
     raw,
     PAYLOAD_KEYS,
@@ -798,9 +977,17 @@ export function captureEvolutionLedgerManifestAuthority(value) {
 }
 
 export function sealEvolutionLedgerManifestSegment(options = undefined) {
+  const fullEvents =
+    options && !utilTypes.isProxy(options) && Object.hasOwn(options, "events");
   const fields = exactRecord(
     options,
-    SEAL_CONFIG_KEYS,
+    fullEvents
+      ? new Set(
+          [...SEAL_CONFIG_KEYS]
+            .filter((key) => key !== "eventDigests")
+            .concat("events"),
+        )
+      : SEAL_CONFIG_KEYS,
     "manifest segment seal configuration",
   );
   const descriptorValue = descriptor(data(fields, "descriptor"));
@@ -818,8 +1005,17 @@ export function sealEvolutionLedgerManifestSegment(options = undefined) {
     descriptorValue,
     authority,
   );
+  const sequenceStart = (previous?.sequence || 0) + 1;
+  const fullPayload = fullEvents
+    ? eventPayload(sequenceStart, data(fields, "events"), {
+        ...descriptorValue,
+        previousDigest: previous?.eventDigest ?? null,
+      })
+    : null;
   const eventDigests = normalizeDigests(
-    data(fields, "eventDigests"),
+    fullPayload
+      ? fullPayload.events.map((event) => event.eventDigest)
+      : data(fields, "eventDigests"),
     "eventDigests",
     descriptorValue.maximumEventsPerSegment,
   );
@@ -841,8 +1037,7 @@ export function sealEvolutionLedgerManifestSegment(options = undefined) {
     new Date(nowMs).toISOString(),
     "manifest issuedAt",
   ).value;
-  const sequenceStart = (previous?.sequence || 0) + 1;
-  const segmentPayload = payload(sequenceStart, eventDigests);
+  const segmentPayload = fullPayload ?? payload(sequenceStart, eventDigests);
   let receipt;
   try {
     receipt = store.retain({
@@ -958,7 +1153,7 @@ export function verifyEvolutionLedgerSegmentManifest(options = undefined) {
   );
 }
 
-export function verifyEvolutionLedgerManifestChain(options = undefined) {
+function verifyChain(options, includeEvents) {
   const fields = exactRecord(
     options,
     VERIFY_CONFIG_KEYS,
@@ -987,6 +1182,7 @@ export function verifyEvolutionLedgerManifestChain(options = undefined) {
     );
   }
   let previous = null;
+  const events = [];
   for (const rawManifest of manifests) {
     const manifest = normalizeManifest(rawManifest, descriptorValue, authority);
     if (
@@ -1023,7 +1219,18 @@ export function verifyEvolutionLedgerManifestChain(options = undefined) {
         "manifest segment resolution is not authenticated immutable storage",
       );
     }
-    const parsed = parsePayload(resolution.bytes, manifest);
+    const parsed = parsePayload(resolution.bytes, {
+      ...manifest,
+      previousDigest: previous?.eventDigests.at(-1) ?? null,
+    });
+    if (includeEvents) {
+      if (!parsed.events)
+        throw failure(
+          EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
+          "digest-only segments cannot recover event payloads",
+        );
+      events.push(...parsed.events);
+    }
     if (canonical(parsed.eventDigests) !== canonical(manifest.eventDigests)) {
       throw failure(
         EVOLUTION_LEDGER_MANIFEST_CORRUPT_CODE,
@@ -1049,5 +1256,14 @@ export function verifyEvolutionLedgerManifestChain(options = undefined) {
     head,
     manifestCount: manifests.length,
     sequence: head.sequence,
+    ...(includeEvents ? { events: Object.freeze(events) } : {}),
   });
 }
+
+export function verifyEvolutionLedgerManifestChain(options = undefined) {
+  return verifyChain(options, false);
+}
+
+export function readEvolutionLedgerManifestEvents(options = undefined) {
+  return verifyChain(options, true);
+}