chainlesschain 0.166.21 → 0.166.22

package/src/lib/evolution/governed-knowledge-sync-ledger-adapter.js

@@ -11,11 +11,16 @@ import {
 } from "./evolution-ledger.js";
 import {
   GOVERNED_KNOWLEDGE_ENVELOPE_SCHEMA,
+  verifyGovernedKnowledgeArtifactBinding,
   verifyGovernedKnowledgeEnvelopeIntegrity,
   verifyGovernedKnowledgeRecord,
 } from "./governed-knowledge-sync.js";
 
 export const GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA =
+  "chainlesschain.governed-evolution-knowledge-ledger-record/v4";
+export const GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V3_SCHEMA =
+  "chainlesschain.governed-evolution-knowledge-ledger-record/v3";
+export const GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V2_SCHEMA =
   "chainlesschain.governed-evolution-knowledge-ledger-record/v2";
 export const GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_LEGACY_SCHEMA =
   "chainlesschain.governed-evolution-knowledge-ledger-record/v1";
@@ -32,6 +37,7 @@ const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
 const DISPOSITIONS = new Set(["conflict", "local", "remote"]);
 const MAX_CONFLICT_PAGE = 256;
 const RECORD_KEYS = new Set([
+  "artifactBinding",
   "committedAt",
   "authorizationReceiptDigest",
   "conflictWithDigest",
@@ -45,8 +51,11 @@ const RECORD_KEYS = new Set([
   "schema",
   "tenantId",
 ]);
+const V2_RECORD_KEYS = new Set(
+  [...RECORD_KEYS].filter((key) => key !== "artifactBinding"),
+);
 const LEGACY_RECORD_KEYS = new Set(
-  [...RECORD_KEYS].filter((key) => key !== "operationId"),
+  [...V2_RECORD_KEYS].filter((key) => key !== "operationId"),
 );
 
 function canonical(value) {
@@ -132,9 +141,23 @@ function recordCore(value) {
     authorizationReceiptDigest: value.authorizationReceiptDigest,
     committedAt: value.committedAt,
   };
-  if (value.schema === GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA) {
+  if (
+    [
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA,
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V3_SCHEMA,
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V2_SCHEMA,
+    ].includes(value.schema)
+  ) {
     core.operationId = value.operationId;
   }
+  if (
+    [
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA,
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V3_SCHEMA,
+    ].includes(value.schema)
+  ) {
+    core.artifactBinding = value.artifactBinding;
+  }
   return core;
 }
 
@@ -208,14 +231,24 @@ function validateEnvelope(value, knowledge, descriptor, disposition) {
 function validateLedgerRecord(value, descriptor) {
   const current =
     value?.schema === GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA;
+  const version3 =
+    value?.schema === GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V3_SCHEMA;
+  const version2 =
+    value?.schema === GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V2_SCHEMA;
   exact(
     value,
-    current ? RECORD_KEYS : LEGACY_RECORD_KEYS,
+    current || version3
+      ? RECORD_KEYS
+      : version2
+        ? V2_RECORD_KEYS
+        : LEGACY_RECORD_KEYS,
     "knowledge sync ledger record",
   );
   if (
     ![
       GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA,
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V3_SCHEMA,
+      GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V2_SCHEMA,
       GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_LEGACY_SCHEMA,
     ].includes(value.schema) ||
     value.tenantId !== descriptor.tenantId ||
@@ -231,10 +264,10 @@ function validateLedgerRecord(value, descriptor) {
     corrupt("knowledge sync ledger record binding is invalid");
   }
   if (
-    (current &&
+    ((current || version3 || version2) &&
       value.operationId !== null &&
       !SAFE_ID.test(value.operationId ?? "")) ||
-    (!current && Object.hasOwn(value, "operationId"))
+    (!current && !version3 && !version2 && Object.hasOwn(value, "operationId"))
   ) {
     corrupt("knowledge sync operation binding is invalid");
   }
@@ -246,6 +279,33 @@ function validateLedgerRecord(value, descriptor) {
   if (value.conflictWithDigest !== conflictWithDigest) {
     corrupt("knowledge sync conflict digest was substituted");
   }
+  if (current || version3) {
+    if (current || value.disposition === "local") {
+      try {
+        const binding = verifyGovernedKnowledgeArtifactBinding(
+          value.artifactBinding,
+          {
+            tenantId: descriptor.tenantId,
+            knowledge: value.knowledge,
+            authorizationReceiptDigest: value.authorizationReceiptDigest,
+          },
+        );
+        if (
+          current &&
+          (binding.activate !== (value.disposition !== "conflict") ||
+            (value.disposition === "local"
+              ? !["publish", "merge"].includes(binding.operation)
+              : binding.operation !== "receive"))
+        ) {
+          corrupt("knowledge sync artifact activation binding is invalid");
+        }
+      } catch {
+        corrupt("knowledge sync artifact binding is invalid");
+      }
+    } else if (value.artifactBinding !== null) {
+      corrupt("remote knowledge sync cannot claim an artifact binding");
+    }
+  }
   validateEnvelope(
     value.envelope,
     value.knowledge,
@@ -398,6 +458,7 @@ export class GovernedKnowledgeSyncLedgerAdapter {
     disposition,
     authorizationReceiptDigest,
     operationId = null,
+    artifactBinding = null,
   } = {}) => {
     if (!DISPOSITIONS.has(disposition)) {
       throw new TypeError("knowledge sync disposition is invalid");
@@ -451,6 +512,7 @@ export class GovernedKnowledgeSyncLedgerAdapter {
         conflictWithDigest,
         authorizationReceiptDigest,
         operationId,
+        artifactBinding,
       };
       if (canonical(stableExisting) !== canonical(stableRequest)) {
         corrupt("knowledge sync event identity resolved different content");
@@ -479,6 +541,7 @@ export class GovernedKnowledgeSyncLedgerAdapter {
       conflictWithDigest,
       authorizationReceiptDigest,
       operationId,
+      artifactBinding: clone(artifactBinding),
       committedAt,
     };
     const record = Object.freeze({
@@ -556,7 +619,11 @@ export class GovernedKnowledgeSyncLedgerAdapter {
       )
     ).filter(
       (record) =>
-        record.schema === GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA &&
+        [
+          GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA,
+          GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V3_SCHEMA,
+          GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_V2_SCHEMA,
+        ].includes(record.schema) &&
         record.disposition === "local" &&
         record.operationId === normalizedId,
     );
@@ -566,6 +633,24 @@ export class GovernedKnowledgeSyncLedgerAdapter {
     return matches[0] ?? null;
   };
 
+  getReception = async ({ envelopeDigest } = {}) => {
+    if (!DIGEST.test(envelopeDigest ?? "")) {
+      throw new TypeError("knowledge reception envelope digest is invalid");
+    }
+    const matches = (
+      await Promise.all(
+        this._events().map((event) => this._resolveEvent(event)),
+      )
+    ).filter(
+      (record) =>
+        record.schema === GOVERNED_KNOWLEDGE_SYNC_LEDGER_RECORD_SCHEMA &&
+        ["remote", "conflict"].includes(record.disposition) &&
+        record.envelopeDigest === envelopeDigest,
+    );
+    if (matches.length > 1) corrupt("knowledge reception is ambiguous");
+    return matches[0] ?? null;
+  };
+
   listConflicts = async ({ cursor = 0, limit = 50 } = {}) => {
     if (
       !Number.isSafeInteger(cursor) ||
@@ -629,6 +714,7 @@ export class GovernedKnowledgeSyncLedgerAdapter {
       send: capture(send, "send", "send"),
       load: this.load,
       loadPublication: this.getPublication,
+      loadReception: this.getReception,
       commit: this.commit,
     });
   }

package/src/lib/evolution/governed-knowledge-sync-merge-publisher.js

@@ -8,6 +8,7 @@ import {
 } from "./governed-knowledge-merge-publisher-authority.js";
 import { isGovernedKnowledgeSync } from "./governed-knowledge-sync.js";
 import { isGovernedKnowledgePublicationReader } from "./governed-knowledge-sync-ledger-adapter.js";
+import { isEvolvableArtifactTransitionReader } from "./evolvable-artifact-ledger-adapter.js";
 
 export const GOVERNED_KNOWLEDGE_SYNC_MERGE_VERIFICATION_SCHEMA =
   "chainlesschain.governed-knowledge-sync-merge-verification/v1";
@@ -121,6 +122,7 @@ function verifyStoredPublication(record, request, envelope = null) {
 
 export function createGovernedKnowledgeSyncMergePublisherAuthority({
   sync,
+  verifierArtifactTransitionReader,
   providerPublicationReader,
   verifierPublicationReader,
   providerDescriptor,
@@ -142,9 +144,22 @@ export function createGovernedKnowledgeSyncMergePublisherAuthority({
   }
   const tenantId = sync.tenantId;
   const deviceId = sync.deviceId;
+  if (
+    !isEvolvableArtifactTransitionReader(verifierArtifactTransitionReader) ||
+    verifierArtifactTransitionReader.tenantId !== tenantId
+  ) {
+    throw new TypeError(
+      "an independent tenant-bound artifact transition reader is required",
+    );
+  }
+  const readArtifactTransition = capture(
+    verifierArtifactTransitionReader,
+    "readTransition",
+    "verifierArtifactTransitionReader",
+  );
   const providerIdentity = descriptor(providerDescriptor, "provider");
   const verifierIdentity = descriptor(verifierDescriptor, "verifier");
-  const publish = capture(sync, "publish", "sync");
+  const publish = capture(sync, "publishWithArtifactEvidence", "sync");
   const readProviderPublication = bindReader(
     providerPublicationReader,
     tenantId,
@@ -158,10 +173,14 @@ export function createGovernedKnowledgeSyncMergePublisherAuthority({
     "verifierPublicationReader",
   );
   const provider = Object.freeze({
-    async publish(request) {
-      const envelope = await publish(request.mergedKnowledge, {
+    async publish(request, plan) {
+      const published = await publish(request.mergedKnowledge, {
         operationId: request.operationId,
+        artifactOperation: "merge",
+        artifactEvidenceDigest: plan.humanReceiptDigest,
+        artifactHumanReviewed: true,
       });
+      const { envelope, artifact } = published;
       const stored = verifyStoredPublication(
         await readProviderPublication({ operationId: request.operationId }),
         request,
@@ -184,6 +203,12 @@ export function createGovernedKnowledgeSyncMergePublisherAuthority({
         knowledgeId: request.knowledgeId,
         mergedContentDigest: request.mergedContentDigest,
         envelopeDigest: stored.envelopeDigest,
+        artifactCandidateDigest: artifact.artifactCandidateDigest,
+        artifactDigest: artifact.artifactDigest,
+        artifactReleaseId: artifact.artifactReleaseId,
+        artifactTransitionOperationId: artifact.artifactTransitionOperationId,
+        artifactTransitionReceiptDigest:
+          artifact.artifactTransitionReceiptDigest,
         providerAuthorityId: providerIdentity.authorityId,
         providerRevision: providerIdentity.revision,
         providerHandlerArtifactDigest: providerIdentity.handlerArtifactDigest,
@@ -204,13 +229,30 @@ export function createGovernedKnowledgeSyncMergePublisherAuthority({
         await readVerifierPublication({ operationId: request.operationId }),
         request,
       );
+      const transition = await readArtifactTransition({
+        operationId: result.artifactTransitionOperationId,
+      });
       if (
         result.envelopeDigest !== stored.envelopeDigest ||
         Date.parse(result.publishedAt) < Date.parse(stored.committedAt) ||
         canonical(result.attestation) !==
           canonical(stored.envelope.signature) ||
         result.resultDigest !==
-          digestGovernedKnowledgeMergePublishResult(result)
+          digestGovernedKnowledgeMergePublishResult(result) ||
+        transition?.request?.previousArtifactDigest !==
+          result.artifactCandidateDigest ||
+        transition.request.nextArtifactDigest !== result.artifactDigest ||
+        transition.artifact.artifactDigest !== result.artifactDigest ||
+        transition.artifact.activeReleaseId !== result.artifactReleaseId ||
+        transition.artifact.contentDigest !== request.mergedContentDigest ||
+        transition.artifact.runtimeManifest.operation !== "merge" ||
+        transition.artifact.runtimeManifest.operationId !==
+          request.operationId ||
+        transition.receipt.operationId !==
+          result.artifactTransitionOperationId ||
+        transition.receipt.receiptDigest !==
+          result.artifactTransitionReceiptDigest ||
+        transition.receipt.durable !== true
       ) {
         throw new Error("merge publication result differs from durable state");
       }
@@ -224,6 +266,12 @@ export function createGovernedKnowledgeSyncMergePublisherAuthority({
           resultDigest: result.resultDigest,
           envelopeDigest: stored.envelopeDigest,
           publicationRecordDigest: stored.recordDigest,
+          artifactCandidateDigest: result.artifactCandidateDigest,
+          artifactDigest: result.artifactDigest,
+          artifactReleaseId: result.artifactReleaseId,
+          artifactTransitionOperationId: result.artifactTransitionOperationId,
+          artifactTransitionReceiptDigest:
+            result.artifactTransitionReceiptDigest,
           verifierAuthorityId: verifierIdentity.authorityId,
           verifierRevision: verifierIdentity.revision,
           verifierHandlerArtifactDigest: verifierIdentity.handlerArtifactDigest,
@@ -239,6 +287,11 @@ export function createGovernedKnowledgeSyncMergePublisherAuthority({
         planDigest: request.planDigest,
         resultDigest: result.resultDigest,
         envelopeDigest: stored.envelopeDigest,
+        artifactCandidateDigest: result.artifactCandidateDigest,
+        artifactDigest: result.artifactDigest,
+        artifactReleaseId: result.artifactReleaseId,
+        artifactTransitionOperationId: result.artifactTransitionOperationId,
+        artifactTransitionReceiptDigest: result.artifactTransitionReceiptDigest,
         providerAuthorityId: providerIdentity.authorityId,
         providerRevision: providerIdentity.revision,
         verifierAuthorityId: verifierIdentity.authorityId,