chainlesschain 0.166.21 → 0.166.24

package/src/lib/evolution/evolution-ledger-ports.js

@@ -12,6 +12,7 @@ import {
   EVOLUTION_ARTIFACT_STORE_FAILED_CODE,
   EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA,
   EvolutionArtifactPorts,
+  captureEvolutionLedgerBatchResolver,
 } from "./evolution-artifact-ports.js";
 import {
   EVOLUTION_ARTIFACT_REF_SCHEMA,
@@ -35,18 +36,43 @@ import {
   SKILL_RELEASE_LEDGER_PROJECTION_SCHEMA,
   SKILL_RELEASE_STATE_LEDGER_MIGRATION_SCHEMA,
   SKILL_RELEASE_STATE_MIGRATION_RECEIPT_SCHEMA,
+  verifySkillRelease,
   verifySkillReleaseState,
   verifySkillReleaseStateMigrationPlan,
 } from "./skill-release-registry.js";
+import {
+  GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE,
+  verifyGovernedKnowledgeDependencyPrepared,
+} from "./governed-knowledge-dependency-ledger-executor.js";
+import {
+  WIKI_LEDGER_EVENT_TYPE,
+  WikiMaintainerLedgerAdapter,
+  captureWikiRevisionReader,
+} from "./wiki-maintainer-ledger-adapter.js";
 
 export const EVOLUTION_LEDGER_PORTS_INVALID_CODE =
   "CC_EVOLUTION_LEDGER_PORTS_INVALID";
+const RELEASE_OPERATION_READERS = new WeakMap();
+
+// This read-only recovery surface is minted only alongside real Ledger ports.
+// Matching JSON, inherited methods or a caller-supplied query function cannot
+// establish that a release operation actually committed.
+export function captureSkillReleaseOperationReader(transactionLedger) {
+  const reader = RELEASE_OPERATION_READERS.get(transactionLedger);
+  if (!reader)
+    throw new TypeError("a branded release transaction ledger is required");
+  return reader;
+}
 export const EVOLUTION_LEDGER_PORTS_COLLISION_CODE =
   "CC_EVOLUTION_LEDGER_PORTS_COLLISION";
 export const EVOLUTION_LEDGER_PORTS_CORRUPT_CODE =
   "CC_EVOLUTION_LEDGER_PORTS_CORRUPT";
 export const EVOLUTION_LEDGER_PORTS_UNAVAILABLE_CODE =
   "CC_EVOLUTION_LEDGER_PORTS_UNAVAILABLE";
+export const EVOLUTION_LEDGER_CANDIDATE_REVOKED_CODE =
+  "CC_EVOLUTION_LEDGER_CANDIDATE_REVOKED";
+export const EVOLUTION_LEDGER_SOURCE_REVOKED_CODE =
+  "CC_EVOLUTION_LEDGER_SOURCE_REVOKED";
 export const EVOLUTION_ARTIFACT_DURABILITY_BINDING_SCHEMA =
   "chainlesschain.evolution-artifact-durability-binding/v1";
 export const EVOLUTION_ARTIFACT_DURABILITY_RETAIN_REQUEST_SCHEMA =
@@ -1127,6 +1153,7 @@ class EvolutionLedgerDomainPorts {
   #appendDomainEvent;
   #artifactPut;
   #artifactResolve;
+  #artifactResolveBatch;
   #artifactTenantId;
   #audience;
   #durabilityAuthority;
@@ -1134,6 +1161,7 @@ class EvolutionLedgerDomainPorts {
   #durabilityRetain;
   #ledgerQuery;
   #ledgerRead;
+  #ledgerVerify;
   #ledgerVerifyReceipt;
   #purpose;
 
@@ -1161,6 +1189,9 @@ class EvolutionLedgerDomainPorts {
     this.#ledgerRead = Object.freeze(
       EvolutionLedger.prototype.read.bind(ledger),
     );
+    this.#ledgerVerify = Object.freeze(
+      EvolutionLedger.prototype.verify.bind(ledger),
+    );
     this.#ledgerVerifyReceipt = Object.freeze(
       EvolutionLedger.prototype.verifyReceipt.bind(ledger),
     );
@@ -1172,6 +1203,9 @@ class EvolutionLedgerDomainPorts {
         artifactPorts,
         Object.freeze({ purpose: this.#purpose }),
       );
+    this.#artifactResolveBatch = captureEvolutionLedgerBatchResolver(
+      this.#artifactResolve,
+    );
     Object.freeze(this);
   }
 
@@ -1452,26 +1486,32 @@ class EvolutionLedgerDomainPorts {
     return ref;
   }
 
-  #resolveSubject(event, expectedType, expectedAudience = null) {
+  #resolveSubject(
+    event,
+    expectedType,
+    expectedAudience = null,
+    capturedResolution = null,
+  ) {
     const ref = normalizeArtifactRef(
       event.subjectRef,
       "domain event subjectRef",
       EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
     );
     const durable = this.#resolveDurably(ref, expectedType);
-    let resolution = null;
+    let resolution = capturedResolution;
     try {
-      resolution = assertSynchronous(
-        this.#artifactResolve(
-          deepFreeze({
-            epoch: event.epoch,
-            ledgerId: event.ledgerId,
-            ref,
-            tenantId: this.#artifactTenantId,
-          }),
-        ),
-        "artifact resolver result",
-      );
+      if (resolution === null)
+        resolution = assertSynchronous(
+          this.#artifactResolve(
+            deepFreeze({
+              epoch: event.epoch,
+              ledgerId: event.ledgerId,
+              ref,
+              tenantId: this.#artifactTenantId,
+            }),
+          ),
+          "artifact resolver result",
+        );
     } catch {
       // A removed/corrupt local cache is recoverable only through the trusted
       // durability authority's exact canonical-byte replica above.
@@ -1698,7 +1738,40 @@ class EvolutionLedgerDomainPorts {
   }
 
   #snapshot() {
-    return this.#indexSnapshot(this.#events());
+    const snapshot = this.#indexSnapshot(this.#events());
+    const types = new Set([
+      EVENT_TYPES.prepare,
+      EVENT_TYPES.finalize,
+      EVENT_TYPES.migration,
+      EVENT_TYPES.audit,
+    ]);
+    const subjects = new Map();
+    for (const event of snapshot.events) {
+      if (types.has(event.type)) subjects.set(event.subjectRef.ref, event);
+      // Bound retained byte buffers independently of total ledger size. Larger
+      // histories keep the existing individually verified streaming path.
+      if (subjects.size > 16) return snapshot;
+    }
+    if (subjects.size) {
+      const events = [...subjects.values()];
+      try {
+        const results = this.#artifactResolveBatch(
+          events.map((event) => ({
+            epoch: event.epoch,
+            ledgerId: event.ledgerId,
+            ref: event.subjectRef,
+            tenantId: this.#artifactTenantId,
+          })),
+        );
+        snapshot.localResolutions = new Map(
+          events.map((event, index) => [event.subjectRef.ref, results[index]]),
+        );
+      } catch {
+        // As on individual reads, a missing local cache may recover only from
+        // the independently authenticated exact-byte durability authority.
+      }
+    }
+    return snapshot;
   }
 
   #snapshotWithVerifiedEvent(snapshot, verification) {
@@ -1743,7 +1816,12 @@ class EvolutionLedgerDomainPorts {
     const cacheKey = `${expectedType}\0${expectedAudience ?? ""}\0${ref.ref}\0${ref.digest}`;
     let record = snapshot.subjects.get(cacheKey);
     if (!record) {
-      record = this.#resolveSubject(event, expectedType, expectedAudience);
+      record = this.#resolveSubject(
+        event,
+        expectedType,
+        expectedAudience,
+        snapshot.localResolutions?.get(ref.ref) ?? null,
+      );
       snapshot.subjects.set(cacheKey, record);
     }
     return record;
@@ -2274,7 +2352,7 @@ class EvolutionLedgerDomainPorts {
     return { existing: null, lineages, prepared };
   }
 
-  migrate(input) {
+  migrate(input, releases) {
     const migration = normalizeStateMigration(input);
     const transactionId = migration.plan.stateMigrationDigest;
     const eventId = deterministicEventId("migration", { transactionId });
@@ -2310,6 +2388,29 @@ class EvolutionLedgerDomainPorts {
           "release state migration requires an empty Skill ledger lineage",
         );
       }
+      if (releases !== undefined) {
+        assertAllExactRecord(
+          releases,
+          new Set(["active", "lastKnownGood"]),
+          "migration release evidence",
+        );
+      }
+      for (const [key, releaseDigest] of [
+        ["active", migration.plan.activeReleaseDigest],
+        ["lastKnownGood", migration.plan.lastKnownGoodReleaseDigest],
+      ]) {
+        this.#assertReleaseNotRevoked(
+          snapshot,
+          {
+            tenantId: migration.plan.tenantId,
+            skillName: migration.plan.skillName,
+            audience: this.#audience,
+            releaseDigest,
+            candidateId: null,
+          },
+          releases?.[key],
+        );
+      }
       const subjectRef = this.#putSubject(
         ARTIFACT_TYPES.migration,
         migration,
@@ -2367,65 +2468,365 @@ class EvolutionLedgerDomainPorts {
     );
   }
 
-  prepare(input) {
+  *#knowledgeRevocations(snapshot, tenantId, audience) {
+    // A prepared revocation is already a durable admission fence. Waiting for
+    // every dependency effect to settle would allow promotion while offline
+    // recovery, active rollback or another dependency is still outstanding.
+    // Scan all streams/devices in this tenant; a new controller cannot opt out.
+    for (const event of snapshot.events) {
+      if (
+        event.type !== GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE ||
+        event.tenantId !== tenantId
+      )
+        continue;
+      if (
+        event.schema !== EVOLUTION_LEDGER_DOMAIN_EVENT_SCHEMA ||
+        event.artifactTenantId !== this.#artifactTenantId ||
+        event.decision !== "prepared" ||
+        !Array.isArray(event.sourceRefs) ||
+        event.sourceRefs.length !== 0
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate revocation event binding is invalid",
+        );
+      }
+      const ref = normalizeArtifactRef(
+        event.subjectRef,
+        "candidate revocation subjectRef",
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+      );
+      // Knowledge records use their own durable ArtifactStore, not the release
+      // replica. Missing or corrupt retained bytes must fail closed, never be
+      // interpreted as the absence of a revocation.
+      const resolution = assertSynchronous(
+        this.#artifactResolve(
+          deepFreeze({
+            epoch: event.epoch,
+            ledgerId: event.ledgerId,
+            ref,
+            tenantId: this.#artifactTenantId,
+          }),
+        ),
+        "candidate revocation artifact resolution",
+      );
+      assertAllExactRecord(
+        resolution,
+        LEDGER_RESOLUTION_KEYS,
+        "candidate revocation artifact resolution",
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+      );
+      if (
+        resolution.schema !== EVOLUTION_ARTIFACT_RESOLUTION_SCHEMA ||
+        resolution.authenticated !== true ||
+        resolution.found !== true ||
+        resolution.ref !== ref.ref ||
+        resolution.digest !== ref.digest
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate revocation artifact is not authenticated and exactly bound",
+        );
+      }
+      digest(
+        resolution.receiptDigest,
+        "candidate revocation artifact receiptDigest",
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+      );
+      const bytes = copyBytes(resolution.bytes);
+      if (sha256(bytes) !== ref.digest) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate revocation artifact digest mismatch",
+        );
+      }
+      const json = bufferToString(bytes, "utf8");
+      let record;
+      try {
+        record = JSON.parse(json);
+      } catch (cause) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate revocation artifact is not JSON",
+          { cause },
+        );
+      }
+      assertAllExactRecord(
+        record,
+        ARTIFACT_RECORD_KEYS,
+        "candidate revocation artifact",
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+      );
+      if (
+        canonicalJson(record) !== json ||
+        record.schema !== EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA ||
+        record.tenantId !== this.#artifactTenantId ||
+        record.type !== "governed-knowledge-dependency-operation" ||
+        record.retention !== "ledger" ||
+        record.purpose !== this.#purpose ||
+        record.audience !== audience
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate revocation artifact boundary is invalid",
+        );
+      }
+      const prepared = verifyGovernedKnowledgeDependencyPrepared(record.value, {
+        tenantId: event.tenantId,
+        deviceId: record.value?.deviceId,
+      });
+      if (
+        event.eventId !==
+        `${GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE}.${prepared.operationDigest.slice(7)}`
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate revocation event does not bind its prepared operation",
+        );
+      }
+      yield { event, prepared };
+    }
+  }
+
+  #assertReleaseNotRevoked(snapshot, binding, targetInput) {
+    const assertCandidate = (prepared, candidateId) => {
+      if (
+        prepared.knowledge.dependencies.some(
+          (dependency) =>
+            dependency.kind === "candidate" &&
+            dependency.digest === candidateId &&
+            ["reject-candidate", "quarantine"].includes(dependency.disposition),
+        )
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_CANDIDATE_REVOKED_CODE,
+          "candidate activation is blocked by a durable knowledge revocation",
+          {
+            candidateId,
+            operationDigest: prepared.operationDigest,
+          },
+        );
+      }
+    };
+    let target = null;
+    const readTarget = () => {
+      if (target) return target;
+      let verified;
+      try {
+        verified = verifySkillRelease(targetInput);
+      } catch (cause) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_INVALID_CODE,
+          "release admission requires verified immutable target evidence",
+          { cause },
+        );
+      }
+      if (
+        verified.releaseDigest !== binding.releaseDigest ||
+        verified.tenantId !== binding.tenantId ||
+        verified.skillName !== binding.skillName ||
+        (binding.candidateId !== null &&
+          verified.candidateId !== binding.candidateId)
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_INVALID_CODE,
+          "release admission evidence differs from the intended target",
+        );
+      }
+      target = verified;
+      return target;
+    };
+    // Stream authenticated revocations: do not retain every full Knowledge
+    // artifact in memory or reuse authorization evidence across attempts.
+    for (const { prepared } of this.#knowledgeRevocations(
+      snapshot,
+      binding.tenantId,
+      binding.audience,
+    )) {
+      assertCandidate(prepared, binding.candidateId);
+      readTarget();
+      assertCandidate(prepared, target.candidateId);
+      const knowledge = prepared.knowledge;
+      const wiki = this.#releaseWikiProvenance(
+        snapshot,
+        binding,
+        target,
+        knowledge,
+      );
+      const sourceRef = `knowledge://${encodeURIComponent(binding.tenantId)}/${encodeURIComponent(knowledge.knowledgeId)}`;
+      const revokedRelease = knowledge.dependencies.some(
+        (dependency) =>
+          dependency.kind === "active-skill" &&
+          dependency.digest === target.releaseDigest,
+      );
+      if (
+        revokedRelease ||
+        wiki?.unsafePatternIds.length ||
+        target.candidate.sourceEvidenceRefs.some(
+          (item) =>
+            item.ref === sourceRef || item.digest === knowledge.contentDigest,
+        )
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_SOURCE_REVOKED_CODE,
+          "release activation references a durably revoked Knowledge source or release",
+          {
+            candidateId: target.candidateId,
+            releaseDigest: target.releaseDigest,
+            operationDigest: prepared.operationDigest,
+          },
+        );
+      }
+    }
+    // Bare legacy calls remain compatible only before any Knowledge revocation.
+    // Once a fence exists, missing provenance must not mean unrelated/safe.
+    if (targetInput !== undefined) readTarget();
+  }
+
+  #releaseWikiProvenance(snapshot, binding, target, knowledge) {
+    if (target.candidate.derivationMode === "wiki") {
+      // Discover the original run on the same authenticated ledger. Neither a
+      // configurable reader nor a self-reported safe subset establishes origin.
+      const event = snapshot.byEventId.get(
+        `wiki.revision.${target.candidate.wikiRevision.slice(5)}`,
+      );
+      if (
+        !event ||
+        event.type !== WIKI_LEDGER_EVENT_TYPE ||
+        event.tenantId !== binding.tenantId ||
+        event.artifactTenantId !== this.#artifactTenantId
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "release admission cannot authenticate its original Wiki revision",
+        );
+      }
+      const readOnly = () => {
+        throw new TypeError("admission Wiki reader is read-only");
+      };
+      const adapter = new WikiMaintainerLedgerAdapter({
+        descriptor: {
+          tenantId: binding.tenantId,
+          artifactTenantId: this.#artifactTenantId,
+          evolutionRunId: event.correlationId,
+          audience: binding.audience,
+          purpose: this.#purpose,
+        },
+        artifactPorts: { putCanonical: readOnly },
+        ledger: {
+          read: this.#ledgerRead,
+          verify: this.#ledgerVerify,
+          appendDomainEvent: readOnly,
+        },
+        ledgerArtifactResolver: this.#artifactResolve,
+      });
+      const revision = captureWikiRevisionReader(
+        adapter,
+      ).readKnowledgeProvenance({
+        tenantId: binding.tenantId,
+        revisionId: target.candidate.wikiRevision,
+        knowledgeId: knowledge.knowledgeId,
+        contentDigest: knowledge.contentDigest,
+      });
+      const tail = snapshot.events.at(-1);
+      if (
+        revision.ledgerHead.sequence !== tail.sequence ||
+        revision.ledgerHead.headDigest !== tail.eventDigest ||
+        ["epoch", "ledgerId", "identityDigest"].some(
+          (key) => revision.ledgerHead[key] !== tail[key],
+        )
+      ) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_UNAVAILABLE_CODE,
+          "ledger changed while checking immutable Wiki provenance",
+        );
+      }
+      return revision;
+    }
+    return null;
+  }
+
+  prepare(input, targetRelease) {
     const intent = normalizeIntent(input);
     this.#assertAudience(intent.mutationRequest.audience, "intent audience");
     const eventId = deterministicEventId("prepare", {
       transactionId: intent.transactionId,
     });
-    const snapshot = this.#snapshot();
-    const existing = snapshot.byEventId.get(eventId);
-    if (existing) {
+    for (let attempt = 0; attempt < MAX_FINALIZE_RETRIES; attempt += 1) {
+      const snapshot = this.#snapshot();
+      const existing = snapshot.byEventId.get(eventId);
+      if (existing) {
+        return this.#prepareProjection(
+          this.#prepareFromSnapshot(snapshot, existing, {
+            authorityReceiptDigest: intent.authorityReceiptDigest,
+            intentDigest: intent.intentDigest,
+            transactionId: intent.transactionId,
+          }),
+        );
+      }
+      const audit = this.#auditFromSnapshot(snapshot, intent.authorityReceipt);
+      this.#assertReleaseNotRevoked(
+        snapshot,
+        {
+          tenantId: intent.mutationRequest.tenantId,
+          skillName: intent.skillName,
+          audience: intent.mutationRequest.audience,
+          releaseDigest: intent.targetReleaseDigest,
+          candidateId: intent.candidateId,
+        },
+        targetRelease,
+      );
+      const subjectRef = this.#putSubject(
+        ARTIFACT_TYPES.prepare,
+        intent,
+        intent.intentDigest,
+        intent.mutationRequest.audience,
+      );
+      const eventInput = {
+        artifactTenantId: this.#artifactTenantId,
+        correlationId: intent.transactionId,
+        decision: "prepared",
+        eventId,
+        reason: intent.intentDigest,
+        skillName: intent.skillName,
+        sourceRefs: [audit.event.subjectRef],
+        subjectRef,
+        tenantId: intent.mutationRequest.tenantId,
+        type: EVENT_TYPES.prepare,
+      };
+      let persistedSnapshot;
+      try {
+        const previous = snapshot.events.at(-1) || null;
+        const verification = this.#verifiedAppend(eventInput, {
+          expectedHeadDigest: previous?.eventDigest ?? null,
+          expectedSequence: previous?.sequence ?? 0,
+        });
+        persistedSnapshot =
+          this.#snapshotWithVerifiedEvent(snapshot, verification) ||
+          this.#snapshot();
+      } catch (cause) {
+        if (isHeadConflict(cause)) continue;
+        if (!isCommitUnknown(cause) && !isEventConflict(cause)) throw cause;
+        persistedSnapshot = this.#snapshot();
+      }
+      const persisted = persistedSnapshot.byEventId.get(eventId);
+      if (!persisted) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_UNAVAILABLE_CODE,
+          "release prepare append did not converge to a queryable event",
+        );
+      }
       return this.#prepareProjection(
-        this.#prepareFromSnapshot(snapshot, existing, {
+        this.#prepareFromSnapshot(persistedSnapshot, persisted, {
           authorityReceiptDigest: intent.authorityReceiptDigest,
           intentDigest: intent.intentDigest,
           transactionId: intent.transactionId,
         }),
       );
     }
-    const audit = this.#auditFromSnapshot(snapshot, intent.authorityReceipt);
-    const subjectRef = this.#putSubject(
-      ARTIFACT_TYPES.prepare,
-      intent,
-      intent.intentDigest,
-      intent.mutationRequest.audience,
-    );
-    const eventInput = {
-      artifactTenantId: this.#artifactTenantId,
-      correlationId: intent.transactionId,
-      decision: "prepared",
-      eventId,
-      reason: intent.intentDigest,
-      skillName: intent.skillName,
-      sourceRefs: [audit.event.subjectRef],
-      subjectRef,
-      tenantId: intent.mutationRequest.tenantId,
-      type: EVENT_TYPES.prepare,
-    };
-    let persistedSnapshot;
-    try {
-      const verification = this.#verifiedAppend(eventInput);
-      persistedSnapshot =
-        this.#snapshotWithVerifiedEvent(snapshot, verification) ||
-        this.#snapshot();
-    } catch (cause) {
-      if (!isCommitUnknown(cause) && !isEventConflict(cause)) throw cause;
-      persistedSnapshot = this.#snapshot();
-    }
-    const persisted = persistedSnapshot.byEventId.get(eventId);
-    if (!persisted) {
-      throw portsError(
-        EVOLUTION_LEDGER_PORTS_UNAVAILABLE_CODE,
-        "release prepare append did not converge to a queryable event",
-      );
-    }
-    return this.#prepareProjection(
-      this.#prepareFromSnapshot(persistedSnapshot, persisted, {
-        authorityReceiptDigest: intent.authorityReceiptDigest,
-        intentDigest: intent.intentDigest,
-        transactionId: intent.transactionId,
-      }),
+    throw portsError(
+      EVOLUTION_LEDGER_PORTS_UNAVAILABLE_CODE,
+      "release prepare could not acquire a stable ledger head",
     );
   }
 
@@ -2560,6 +2961,513 @@ class EvolutionLedgerDomainPorts {
     return this.#committedProjection(finalized, lineages);
   }
 
+  resolveReleaseOperation(inputValue) {
+    return this.#resolveRelease(inputValue, false);
+  }
+
+  resolveReleaseOrigin(inputValue) {
+    return this.#resolveRelease(inputValue, true);
+  }
+
+  readReleaseHistory(inputValue) {
+    return this.#resolveRelease(inputValue, false, true);
+  }
+
+  resolveKnowledgeRevocation(inputValue) {
+    if (this.#audience === null)
+      throw new TypeError(
+        "Knowledge revocation proof requires audience-bound ledger ports",
+      );
+    const input = frozenCanonicalClone(inputValue);
+    assertAllExactRecord(
+      input,
+      new Set(["tenantId", "operationDigest", "context"]),
+      "Knowledge revocation query",
+    );
+    const tenantId = identifier(input.tenantId, "tenantId");
+    const operationDigest = digest(input.operationDigest, "operationDigest");
+    const keys = [
+      "epoch",
+      "ledgerId",
+      "identityDigest",
+      "sequence",
+      "headDigest",
+    ];
+    assertAllExactRecord(
+      input.context,
+      new Set(["mode", "checkpoint"]),
+      "Knowledge revocation context",
+    );
+    assertAllExactRecord(
+      input.context.checkpoint,
+      new Set(keys),
+      "Knowledge revocation checkpoint",
+    );
+    const head = this.#ledgerVerify();
+    if (
+      input.context.mode !== "current" ||
+      keys.some((key) => input.context.checkpoint[key] !== head[key])
+    )
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "Knowledge revocation requires the current authenticated head",
+      );
+    const snapshot = this.#snapshot();
+    if (
+      snapshot.events.length !== head.sequence ||
+      (snapshot.events.at(-1)?.eventDigest ?? null) !== head.headDigest
+    )
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "Knowledge revocation snapshot changed",
+      );
+    let fence = null;
+    for (const entry of this.#knowledgeRevocations(
+      snapshot,
+      tenantId,
+      this.#audience,
+    )) {
+      if (entry.prepared.operationDigest !== operationDigest) continue;
+      fence = {
+        record: entry.prepared,
+        sequence: entry.event.sequence,
+        evidence: {
+          timestamp: entry.event.timestamp,
+          signature: entry.event.signature,
+          eventDigest: entry.event.eventDigest,
+        },
+      };
+    }
+    const fresh = this.#ledgerVerify();
+    if (keys.some((key) => fresh[key] !== head[key]))
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "Knowledge revocation changed during verification",
+      );
+    return deepFreeze({
+      authenticated: true,
+      durable: true,
+      tenantId,
+      operationDigest,
+      checkpoint: { ...input.context.checkpoint },
+      fence,
+    });
+  }
+
+  resolveCandidateRevocation(inputValue) {
+    return this.#resolveCandidateDisposition(inputValue, "reject-candidate");
+  }
+
+  resolveCandidateQuarantine(inputValue) {
+    return this.#resolveCandidateDisposition(inputValue, "quarantine");
+  }
+
+  #resolveCandidateDisposition(inputValue, disposition) {
+    if (this.#audience === null)
+      throw new TypeError(
+        "candidate revocation proof requires audience-bound ledger ports",
+      );
+    const input = frozenCanonicalClone(inputValue);
+    assertAllExactRecord(
+      input,
+      new Set([
+        "tenantId",
+        "skillName",
+        "candidateId",
+        "operationDigest",
+        "context",
+      ]),
+      "candidate revocation query",
+    );
+    const tenantId = identifier(input.tenantId, "tenantId");
+    const name = skillName(input.skillName, "skillName");
+    const candidateId = digest(input.candidateId, "candidateId");
+    const operationDigest = digest(input.operationDigest, "operationDigest");
+    const keys = [
+      "epoch",
+      "ledgerId",
+      "identityDigest",
+      "sequence",
+      "headDigest",
+    ];
+    assertAllExactRecord(
+      input.context,
+      new Set(["mode", "checkpoint"]),
+      "candidate revocation context",
+    );
+    assertAllExactRecord(
+      input.context.checkpoint,
+      new Set(keys),
+      "candidate revocation checkpoint",
+    );
+    if (input.context.mode !== "current")
+      throw new TypeError("candidate revocation requires a current context");
+    const head = this.#ledgerVerify();
+    if (keys.some((key) => input.context.checkpoint[key] !== head[key])) {
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "candidate revocation checkpoint is stale",
+      );
+    }
+    const snapshot = this.#snapshot();
+    if (
+      snapshot.events.length !== head.sequence ||
+      (snapshot.events.at(-1)?.eventDigest ?? null) !== head.headDigest
+    ) {
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "candidate revocation snapshot changed",
+      );
+    }
+    let fence = null;
+    // This is the exact same authenticated parser as mandatory prepare, not a
+    // separate provider's assertion that admission has supposedly been denied.
+    for (const entry of this.#knowledgeRevocations(
+      snapshot,
+      tenantId,
+      this.#audience,
+    )) {
+      if (entry.prepared.operationDigest !== operationDigest) continue;
+      const dependency = entry.prepared.knowledge.dependencies.find(
+        (item) =>
+          item.kind === "candidate" &&
+          item.digest === candidateId &&
+          item.disposition === disposition,
+      );
+      if (dependency) fence = entry;
+    }
+    const cache = new Map();
+    const lineages = this.#lineages(snapshot, cache);
+    const history = [];
+    const pendingTransactions = [];
+    for (const event of snapshot.events) {
+      if (event.type !== EVENT_TYPES.prepare || event.tenantId !== tenantId)
+        continue;
+      const entry =
+        cache.get(event.eventId) ?? this.#prepareFromSnapshot(snapshot, event);
+      const intent = entry.intent;
+      if (intent.candidateId === candidateId && intent.skillName !== name) {
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "candidate history belongs to another Skill",
+        );
+      }
+      if (intent.skillName !== name) continue;
+      const finalized = lineages.byTransaction.get(intent.transactionId);
+      if (!finalized) pendingTransactions.push(intent.transactionId);
+      if (intent.candidateId !== candidateId) continue;
+      history.push({
+        transactionId: intent.transactionId,
+        releaseDigest: intent.targetReleaseDigest,
+        preparationSequence: event.sequence,
+        committed: Boolean(finalized),
+      });
+    }
+    const groupKey = `${tenantId}\0${name}`;
+    const latest = lineages.groups.get(groupKey)?.at(-1);
+    const migrated = lineages.migrations.get(groupKey);
+    const current = latest
+      ? {
+          releaseDigest: latest.prepared.intent.targetReleaseDigest,
+          revision: latest.finalization.revision,
+          stateDigest: latest.finalization.stateDigest,
+          projection: this.#committedProjection(latest, lineages),
+        }
+      : migrated
+        ? {
+            releaseDigest: migrated.migration.state.activeReleaseDigest,
+            revision: migrated.migration.state.revision,
+            stateDigest: migrated.migration.state.stateDigest,
+            projection: this.#migrationProjection(migrated, true),
+          }
+        : null;
+    const fresh = this.#ledgerVerify();
+    if (keys.some((key) => fresh[key] !== head[key])) {
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "candidate revocation ledger changed during verification",
+      );
+    }
+    return deepFreeze({
+      authenticated: true,
+      durable: true,
+      tenantId,
+      skillName: name,
+      candidateId,
+      operationDigest,
+      checkpoint: { ...input.context.checkpoint },
+      fence: fence
+        ? {
+            record: fence.prepared,
+            sequence: fence.event.sequence,
+            evidence: {
+              timestamp: fence.event.timestamp,
+              signature: fence.event.signature,
+              eventDigest: fence.event.eventDigest,
+            },
+          }
+        : null,
+      pendingTransactions,
+      history,
+      current,
+    });
+  }
+
+  #resolveRelease(inputValue, origin, history = false) {
+    const input = frozenCanonicalClone(inputValue);
+    assertAllExactRecord(
+      input,
+      new Set([
+        "tenantId",
+        "skillName",
+        ...(history ? [] : [origin ? "releaseDigest" : "operationId"]),
+        "context",
+      ]),
+      "release operation query",
+    );
+    const tenantId = identifier(input.tenantId, "tenantId");
+    const name = skillName(input.skillName, "skillName");
+    const operationId =
+      origin || history ? null : identifier(input.operationId, "operationId");
+    const releaseDigest = origin
+      ? digest(
+          input.releaseDigest,
+          "releaseDigest",
+          EVOLUTION_LEDGER_PORTS_INVALID_CODE,
+        )
+      : null;
+    const context = input.context;
+    assertAllExactRecord(
+      context,
+      new Set(["mode", "checkpoint"]),
+      "release operation context",
+    );
+    const keys = [
+      "epoch",
+      "ledgerId",
+      "identityDigest",
+      "sequence",
+      "headDigest",
+    ];
+    assertAllExactRecord(
+      context.checkpoint,
+      new Set(keys),
+      "release operation checkpoint",
+    );
+    if (!["current", "checkpoint"].includes(context.mode))
+      throw new TypeError("invalid release operation mode");
+    const snapshot = this.#snapshot();
+    const tail = snapshot.events.at(-1);
+    const head = tail
+      ? { ...tail, headDigest: tail.eventDigest }
+      : this.#ledgerVerify();
+    if (
+      snapshot.events.length !== head.sequence ||
+      snapshot.events.some((event) =>
+        ["epoch", "ledgerId", "identityDigest"].some(
+          (key) => event[key] !== head[key],
+        ),
+      )
+    )
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "release operation snapshot is not the full current ledger",
+      );
+    const checkpoint = context.checkpoint;
+    const historical =
+      checkpoint.sequence === 0
+        ? null
+        : snapshot.bySequence.get(checkpoint.sequence);
+    if (
+      !Number.isSafeInteger(checkpoint.sequence) ||
+      checkpoint.sequence < 0 ||
+      checkpoint.sequence > head.sequence ||
+      ["epoch", "ledgerId", "identityDigest"].some(
+        (key) => checkpoint[key] !== head[key],
+      ) ||
+      checkpoint.headDigest !== (historical?.eventDigest ?? null) ||
+      (context.mode === "current" &&
+        keys.some((key) => checkpoint[key] !== head[key]))
+    ) {
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "release operation checkpoint differs from the authenticated ledger",
+      );
+    }
+    // Authenticate the whole present lineage even for a historical query, then
+    // derive the exact as-of prefix. A later finalize cannot prove an earlier ack.
+    const prepareCache = new Map();
+    const presentLineages = this.#lineages(snapshot, prepareCache);
+    const prefix = this.#indexSnapshot(
+      snapshot.events.slice(0, checkpoint.sequence),
+      snapshot.subjects,
+    );
+    // Reuse only work authenticated in THIS read, and only when all release
+    // events and their consumed authority precede the requested checkpoint.
+    // Unrelated later Wiki/journal events do not change the release lineage.
+    // A later prepare/finalize/migration still forces exact prefix replay.
+    const unchangedReleaseHistory =
+      !snapshot.events
+        .slice(checkpoint.sequence)
+        .some((event) =>
+          [
+            EVENT_TYPES.prepare,
+            EVENT_TYPES.finalize,
+            EVENT_TYPES.migration,
+          ].includes(event.type),
+        ) &&
+      [...prepareCache.values()].every((entry) =>
+        prefix.byEventId.has(entry.consumeAudit.event.eventId),
+      );
+    const lineages = unchangedReleaseHistory
+      ? presentLineages
+      : this.#lineages(prefix);
+    const prepared = [];
+    for (const event of prefix.events) {
+      if (event.type !== EVENT_TYPES.prepare) continue;
+      const cached = prepareCache.get(event.eventId);
+      const entry =
+        cached && prefix.byEventId.has(cached.consumeAudit.event.eventId)
+          ? cached
+          : this.#prepareFromSnapshot(prefix, event);
+      if (
+        entry.intent.mutationRequest.tenantId === tenantId &&
+        entry.intent.skillName === name &&
+        (history ||
+          (origin
+            ? entry.intent.operation === "promote" &&
+              entry.intent.targetReleaseDigest === releaseDigest
+            : entry.intent.operationId === operationId))
+      )
+        prepared.push(entry);
+    }
+    if (!history && prepared.length > 1)
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "release operation has multiple transaction intents",
+      );
+    if (history && prepared.length > 10_000)
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "release history exceeds its bounded budget",
+      );
+    if (
+      history &&
+      new Set(prepared.map((entry) => entry.intent.operationId)).size !==
+        prepared.length
+    )
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "release operation has multiple transaction intents",
+      );
+    const groupKey = `${tenantId}\0${name}`;
+    const baseline = lineages.migrations.get(groupKey)?.migration.state;
+    let previous = baseline
+      ? {
+          revision: baseline.revision,
+          stateDigest: baseline.stateDigest,
+          activeReleaseDigest: baseline.activeReleaseDigest,
+          lastKnownGoodReleaseDigest: baseline.lastKnownGoodReleaseDigest,
+        }
+      : {
+          revision: 0,
+          stateDigest: null,
+          activeReleaseDigest: null,
+          lastKnownGoodReleaseDigest: null,
+        };
+    const predecessors = new Map([[previous.revision, previous]]);
+    for (const prior of lineages.groups.get(groupKey) ?? []) {
+      const intent = prior.prepared.intent;
+      if (
+        intent.operation === "rollback" &&
+        intent.targetReleaseDigest !== previous.lastKnownGoodReleaseDigest
+      )
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "historical rollback does not target the last-known-good release",
+        );
+      previous = {
+        revision: prior.finalization.revision,
+        stateDigest: prior.finalization.stateDigest,
+        activeReleaseDigest: intent.targetReleaseDigest,
+        lastKnownGoodReleaseDigest:
+          intent.operation === "promote"
+            ? (previous.activeReleaseDigest ?? intent.targetReleaseDigest)
+            : intent.targetReleaseDigest,
+      };
+      predecessors.set(previous.revision, previous);
+    }
+    const results = prepared.map((entry) => {
+      const previous = predecessors.get(entry.intent.expectedRevision);
+      if (
+        !previous ||
+        previous.revision !== entry.intent.expectedRevision ||
+        previous.stateDigest !== entry.intent.previousStateDigest
+      )
+        throw portsError(
+          EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+          "release operation has no exact predecessor",
+        );
+      const finalized = lineages.byTransaction.get(entry.intent.transactionId);
+      return {
+        intent: entry.intent,
+        previous,
+        preparationCheckpoint: {
+          epoch: entry.event.epoch,
+          ledgerId: entry.event.ledgerId,
+          identityDigest: entry.event.identityDigest,
+          sequence: entry.event.sequence,
+          headDigest: entry.event.eventDigest,
+        },
+        projection: finalized
+          ? this.#committedProjection(finalized, lineages)
+          : this.#prepareProjection(entry),
+        finalizationEvidence: finalized
+          ? {
+              timestamp: finalized.event.timestamp,
+              signature: finalized.event.signature,
+              eventDigest: finalized.event.eventDigest,
+            }
+          : null,
+      };
+    });
+    const result = results[0] ?? null;
+    const fresh = this.#ledgerVerify();
+    if (keys.some((key) => fresh[key] !== head[key]))
+      throw portsError(
+        EVOLUTION_LEDGER_PORTS_CORRUPT_CODE,
+        "release operation ledger changed during verification",
+      );
+    if (history) {
+      const migration = lineages.migrations.get(`${tenantId}\0${name}`);
+      return deepFreeze({
+        authenticated: true,
+        durable: true,
+        tenantId,
+        skillName: name,
+        checkpoint: { ...checkpoint },
+        migration: migration
+          ? {
+              value: migration.migration,
+              artifactRef: migration.event.subjectRef,
+              sequence: migration.event.sequence,
+              eventDigest: migration.event.eventDigest,
+            }
+          : null,
+        operations: results,
+      });
+    }
+    return deepFreeze({
+      authenticated: true,
+      durable: true,
+      tenantId,
+      skillName: name,
+      operationId: origin ? (result?.intent.operationId ?? null) : operationId,
+      checkpoint: { ...checkpoint },
+      result,
+    });
+  }
+
   appendAudit(input) {
     const value = frozenCanonicalClone(input);
     const audit = verifySkillMutationAuditEvent(value);
@@ -3009,16 +3917,69 @@ export function createEvolutionLedgerPorts(options = {}) {
         )
       : "evolution-ledger",
   });
-  const prepare = Object.freeze((input) => adapter.prepare(input));
+  const prepare = Object.freeze((input, targetRelease) =>
+    adapter.prepare(input, targetRelease),
+  );
   const finalize = Object.freeze((input) => adapter.finalize(input));
-  const migrate = Object.freeze((input) => adapter.migrate(input));
+  const migrate = Object.freeze((input, releases) =>
+    adapter.migrate(input, releases),
+  );
   const query = Object.freeze((transactionId) => adapter.query(transactionId));
   const append = Object.freeze((event) => adapter.appendAudit(event));
   const claim = Object.freeze((nonce) => adapter.claimNonce(nonce));
+  const transactionLedger = Object.freeze({
+    finalize,
+    migrate,
+    prepare,
+    query,
+  });
+  const readCurrentHead = ledger.verify.bind(ledger);
+  RELEASE_OPERATION_READERS.set(
+    transactionLedger,
+    Object.freeze({
+      currentContext: Object.freeze(() => {
+        const head = readCurrentHead();
+        return deepFreeze({
+          mode: "current",
+          checkpoint: Object.fromEntries(
+            [
+              "epoch",
+              "ledgerId",
+              "identityDigest",
+              "sequence",
+              "headDigest",
+            ].map((key) => [key, head[key]]),
+          ),
+        });
+      }),
+      matchesWikiAdapter: Object.freeze((wikiAdapter) =>
+        captureWikiRevisionReader(wikiAdapter).matchesLedger(ledger),
+      ),
+      matchesLedger: Object.freeze((value) => value === ledger),
+      resolveOperation: Object.freeze((input) =>
+        adapter.resolveReleaseOperation(input),
+      ),
+      resolveReleaseOrigin: Object.freeze((input) =>
+        adapter.resolveReleaseOrigin(input),
+      ),
+      readReleaseHistory: Object.freeze((input) =>
+        adapter.readReleaseHistory(input),
+      ),
+      resolveCandidateRevocation: Object.freeze((input) =>
+        adapter.resolveCandidateRevocation(input),
+      ),
+      resolveCandidateQuarantine: Object.freeze((input) =>
+        adapter.resolveCandidateQuarantine(input),
+      ),
+      resolveKnowledgeRevocation: Object.freeze((input) =>
+        adapter.resolveKnowledgeRevocation(input),
+      ),
+    }),
+  );
   return Object.freeze({
     auditSink: Object.freeze({ append }),
     nonceStore: Object.freeze({ claim }),
-    transactionLedger: Object.freeze({ finalize, migrate, prepare, query }),
+    transactionLedger,
   });
 }