chainlesschain 0.166.20 → 0.166.22

package/src/lib/evolution/governed-knowledge-artifact-lifecycle.js

@@ -0,0 +1,364 @@
+import { types as utilTypes } from "node:util";
+
+import evolvableArtifactProtocol from "@chainlesschain/session-core/evolvable-artifact";
+
+import {
+  isEvolvableArtifactReleaseResolver,
+  isEvolvableArtifactTransitionReader,
+} from "./evolvable-artifact-ledger-adapter.js";
+import { verifyGovernedKnowledgeRecord } from "./governed-knowledge-sync.js";
+
+const {
+  ARTIFACT_TYPE,
+  createEvolvableArtifactReceipt,
+  digestEvolvableArtifactValue,
+  isEvolvableArtifactCandidateGate,
+  isEvolvableArtifactReleaseGate,
+} = evolvableArtifactProtocol;
+
+export const GOVERNED_KNOWLEDGE_ARTIFACT_LIFECYCLE_SCHEMA =
+  "chainlesschain.governed-knowledge-artifact-lifecycle/v1";
+
+const LIFECYCLES = new WeakSet();
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const OPERATIONS = new Set(["publish", "receive", "merge"]);
+
+function freeze(value) {
+  const result = structuredClone(value);
+  function visit(entry) {
+    if (entry && typeof entry === "object" && !Object.isFrozen(entry)) {
+      Object.freeze(entry);
+      for (const child of Object.values(entry)) visit(child);
+    }
+  }
+  visit(result);
+  return result;
+}
+
+function capture(owner, method, label) {
+  if (
+    !owner ||
+    typeof owner !== "object" ||
+    utilTypes.isProxy(owner) ||
+    typeof owner[method] !== "function"
+  )
+    throw new TypeError(`${label}.${method}() is required`);
+  return (...args) => Reflect.apply(owner[method], owner, args);
+}
+
+function manifest(body) {
+  return freeze({ ...body, digest: digestEvolvableArtifactValue(body) });
+}
+
+function receipt(artifact, kind, issuedAt, operationDigest, claims) {
+  return createEvolvableArtifactReceipt({
+    kind,
+    tenantId: artifact.tenantId,
+    artifactId: artifact.artifactId,
+    candidateId: artifact.candidate.candidateId,
+    contentDigest: artifact.contentDigest,
+    dependencyLockDigest: artifact.dependencyLock.digest,
+    issuerId: `governed-knowledge-lifecycle:${kind}`,
+    issuerRevision: "v1",
+    issuedAt,
+    decision: "allow",
+    claims: { operationDigest, ...claims },
+  });
+}
+
+export function createGovernedKnowledgeArtifactLifecycle({
+  tenantId,
+  artifactCandidateGate,
+  artifactReleaseGate,
+  artifactReleaseResolver,
+  verifierArtifactTransitionReader,
+} = {}) {
+  if (typeof tenantId !== "string" || tenantId.trim() === "")
+    throw new TypeError("tenantId is required");
+  if (
+    !isEvolvableArtifactCandidateGate(
+      artifactCandidateGate,
+      ARTIFACT_TYPE.KNOWLEDGE,
+    ) ||
+    artifactCandidateGate.tenantId !== tenantId
+  )
+    throw new TypeError("a tenant-bound Knowledge candidate gate is required");
+  if (
+    !isEvolvableArtifactReleaseGate(
+      artifactReleaseGate,
+      ARTIFACT_TYPE.KNOWLEDGE,
+    ) ||
+    artifactReleaseGate.tenantId !== tenantId ||
+    artifactReleaseGate.authorityScope !== artifactCandidateGate.authorityScope
+  )
+    throw new TypeError("a same-authority Knowledge release gate is required");
+  if (
+    !isEvolvableArtifactReleaseResolver(artifactReleaseResolver) ||
+    artifactReleaseResolver.tenantId !== tenantId
+  )
+    throw new TypeError("a tenant-bound artifact release resolver is required");
+  if (
+    !isEvolvableArtifactTransitionReader(verifierArtifactTransitionReader) ||
+    verifierArtifactTransitionReader.tenantId !== tenantId ||
+    verifierArtifactTransitionReader.readerScope ===
+      artifactReleaseGate.transitionReaderScope
+  )
+    throw new TypeError(
+      "an independent artifact transition reader is required",
+    );
+
+  const stageCandidate = capture(
+    artifactCandidateGate,
+    "stageCandidate",
+    "artifactCandidateGate",
+  );
+  const preparePromotion = capture(
+    artifactReleaseGate,
+    "preparePromotion",
+    "artifactReleaseGate",
+  );
+  const commitPromotion = capture(
+    artifactReleaseGate,
+    "commitPreparedPromotion",
+    "artifactReleaseGate",
+  );
+  const resolveDependency = capture(
+    artifactReleaseResolver,
+    "resolveDependency",
+    "artifactReleaseResolver",
+  );
+  const readTransition = capture(
+    verifierArtifactTransitionReader,
+    "readTransition",
+    "verifierArtifactTransitionReader",
+  );
+  const preparedHandles = new WeakSet();
+
+  async function resolveOne(dependency) {
+    const resolved = await resolveDependency({ tenantId, ...dependency });
+    if (
+      resolved?.authenticated !== true ||
+      resolved.durable !== true ||
+      resolved.tenantId !== tenantId ||
+      resolved.sourceKind !== dependency.kind ||
+      resolved.sourceDigest !== dependency.digest ||
+      resolved.sourceDisposition !== dependency.disposition ||
+      !DIGEST.test(resolved.artifactDigest ?? "")
+    )
+      throw new Error("Knowledge artifact dependency resolution is invalid");
+    return {
+      artifactId: resolved.artifactId,
+      type: resolved.type,
+      releaseId: resolved.releaseId,
+      contentDigest: resolved.contentDigest,
+    };
+  }
+
+  async function resolveBaseline(currentKnowledge) {
+    if (currentKnowledge === null) return null;
+    const resolved = await resolveOne({
+      kind: "active-knowledge",
+      digest: currentKnowledge.contentDigest,
+      disposition: "baseline",
+    });
+    if (resolved.artifactId !== currentKnowledge.knowledgeId)
+      throw new Error("Knowledge typed baseline resolved another artifact");
+    return resolved;
+  }
+
+  const lifecycle = Object.freeze({
+    schema: GOVERNED_KNOWLEDGE_ARTIFACT_LIFECYCLE_SCHEMA,
+    tenantId,
+    async prepare({
+      knowledge: knowledgeInput,
+      currentKnowledge: currentInput = null,
+      operation,
+      operationId,
+      authorizationReceiptDigest,
+      evidenceDigest = null,
+      issuedAt,
+      activate = true,
+      humanReviewed = false,
+    } = {}) {
+      if (!OPERATIONS.has(operation))
+        throw new TypeError("Knowledge lifecycle operation is invalid");
+      if (!ID.test(operationId ?? ""))
+        throw new TypeError("Knowledge lifecycle operationId is required");
+      if (!DIGEST.test(authorizationReceiptDigest ?? ""))
+        throw new TypeError("authorizationReceiptDigest is invalid");
+      if (!Number.isFinite(Date.parse(issuedAt)))
+        throw new TypeError("Knowledge lifecycle issuedAt is invalid");
+      const boundEvidenceDigest = evidenceDigest ?? authorizationReceiptDigest;
+      if (
+        !DIGEST.test(boundEvidenceDigest) ||
+        typeof humanReviewed !== "boolean"
+      )
+        throw new TypeError("Knowledge lifecycle evidence is invalid");
+      const knowledge = verifyGovernedKnowledgeRecord(knowledgeInput, {
+        tenantId,
+      });
+      const currentKnowledge =
+        currentInput === null
+          ? null
+          : verifyGovernedKnowledgeRecord(currentInput, { tenantId });
+      if (
+        currentKnowledge !== null &&
+        (currentKnowledge.knowledgeId !== knowledge.knowledgeId ||
+          currentKnowledge.scope !== knowledge.scope ||
+          currentKnowledge.scopeId !== knowledge.scopeId)
+      )
+        throw new Error("Knowledge lifecycle baseline boundary changed");
+      const baseline = await resolveBaseline(currentKnowledge);
+      const dependencies = [];
+      if (knowledge.action === "upsert") {
+        for (const dependency of knowledge.dependencies)
+          dependencies.push(await resolveOne(dependency));
+      }
+      dependencies.sort((left, right) =>
+        left.artifactId.localeCompare(right.artifactId),
+      );
+      const dependencyLock = {
+        dependencies,
+        digest: digestEvolvableArtifactValue({ dependencies }),
+      };
+      const operationCore = {
+        tenantId,
+        operation,
+        operationId,
+        knowledgeId: knowledge.knowledgeId,
+        contentDigest: knowledge.contentDigest,
+        currentContentDigest: currentKnowledge?.contentDigest ?? null,
+        authorizationReceiptDigest,
+        evidenceDigest: boundEvidenceDigest,
+        humanReviewed,
+      };
+      const operationDigest = digestEvolvableArtifactValue(operationCore);
+      const staged = await stageCandidate({
+        tenantId,
+        artifactId: knowledge.knowledgeId,
+        type: ARTIFACT_TYPE.KNOWLEDGE,
+        contentDigest: knowledge.contentDigest,
+        parent:
+          baseline === null
+            ? null
+            : {
+                artifactId: baseline.artifactId,
+                releaseId: baseline.releaseId,
+                contentDigest: baseline.contentDigest,
+              },
+        lineage: [
+          ...(currentKnowledge ? [currentKnowledge.contentDigest] : []),
+          knowledge.contentDigest,
+        ],
+        dependencyLock,
+        runtimeManifest: manifest({
+          executable: false,
+          operation,
+          operationId,
+          operationDigest,
+          action: knowledge.action,
+          scope: knowledge.scope,
+          scopeId: knowledge.scopeId,
+          vectorClock: knowledge.vectorClock,
+          dependencyDispositionDigest: digestEvolvableArtifactValue(
+            knowledge.dependencies,
+          ),
+        }),
+        permissionManifest: manifest({
+          authorizationReceiptDigest,
+          approvalReceiptDigest: knowledge.approvalReceiptDigest,
+          revocationReceiptDigest: knowledge.revocationReceiptDigest,
+          capabilities: [`knowledge:${knowledge.scope}:${operation}`],
+        }),
+        candidateId: `knowledge-candidate:${operationDigest.slice(7)}`,
+        activeReleaseId: baseline?.releaseId ?? null,
+        lastKnownGoodReleaseId: null,
+      });
+      const promotion = activate
+        ? preparePromotion({
+            artifact: staged.artifact,
+            candidatePersistenceReceipt: staged.receipt,
+            evaluationReceipt: receipt(
+              staged.artifact,
+              "eval",
+              issuedAt,
+              operationDigest,
+              { authorizationReceiptDigest },
+            ),
+            reviewReceipt: receipt(
+              staged.artifact,
+              "review",
+              issuedAt,
+              operationDigest,
+              {
+                approvalReceiptDigest: knowledge.approvalReceiptDigest,
+                automated: !humanReviewed,
+                evidenceDigest: boundEvidenceDigest,
+              },
+            ),
+            promotionReceipt: receipt(
+              staged.artifact,
+              "promotion",
+              issuedAt,
+              operationDigest,
+              { operationId },
+            ),
+            releaseId: `knowledge-release:${operationDigest.slice(7)}`,
+          })
+        : null;
+      const prepared = Object.freeze({
+        operationDigest,
+        operation,
+        operationId,
+        candidate: staged,
+        promotion,
+        activate,
+      });
+      preparedHandles.add(prepared);
+      return prepared;
+    },
+    async commit(prepared) {
+      if (!preparedHandles.has(prepared))
+        throw new TypeError(
+          "a prepared Knowledge lifecycle handle is required",
+        );
+      if (!prepared.activate)
+        return freeze({
+          candidateOnly: true,
+          artifactCandidateDigest: prepared.candidate.artifact.artifactDigest,
+          operationDigest: prepared.operationDigest,
+        });
+      const committed = await commitPromotion(prepared.promotion);
+      const readback = await readTransition({
+        operationId: committed.receipt.operationId,
+      });
+      if (
+        readback?.request?.previousArtifactDigest !==
+          prepared.candidate.artifact.artifactDigest ||
+        readback.request.nextArtifactDigest !==
+          committed.artifact.artifactDigest ||
+        readback.artifact.artifactDigest !==
+          committed.artifact.artifactDigest ||
+        readback.receipt.receiptDigest !== committed.receipt.receiptDigest ||
+        readback.receipt.durable !== true
+      )
+        throw new Error("Knowledge artifact transition readback is invalid");
+      return freeze({
+        candidateOnly: false,
+        operationDigest: prepared.operationDigest,
+        artifactCandidateDigest: prepared.candidate.artifact.artifactDigest,
+        artifactDigest: committed.artifact.artifactDigest,
+        artifactReleaseId: committed.artifact.activeReleaseId,
+        artifactTransitionOperationId: committed.receipt.operationId,
+        artifactTransitionReceiptDigest: committed.receipt.receiptDigest,
+      });
+    },
+  });
+  LIFECYCLES.add(lifecycle);
+  return lifecycle;
+}
+
+export function isGovernedKnowledgeArtifactLifecycle(value) {
+  return LIFECYCLES.has(value);
+}

package/src/lib/evolution/governed-knowledge-conflict-merge.js

@@ -0,0 +1,352 @@
+import { createHash } from "node:crypto";
+import { types as utilTypes } from "node:util";
+
+import { isGovernedKnowledgeConflictReader } from "./governed-knowledge-sync-ledger-adapter.js";
+import { verifyGovernedKnowledgeRecord } from "./governed-knowledge-sync.js";
+
+export const GOVERNED_KNOWLEDGE_HUMAN_MERGE_RECEIPT_SCHEMA =
+  "chainlesschain.governed-knowledge-human-merge-receipt/v1";
+export const GOVERNED_KNOWLEDGE_MERGE_PLAN_SCHEMA =
+  "chainlesschain.governed-knowledge-merge-plan/v1";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
+const MAX_REASON_LENGTH = 2048;
+const MAX_RECEIPT_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const MERGE_PLANS = new WeakSet();
+const RECEIPT_KEYS = new Set([
+  "attestation",
+  "automated",
+  "conflictEnvelopeDigest",
+  "decidedAt",
+  "knowledgeId",
+  "localContentDigest",
+  "mergedContentDigest",
+  "mergedVectorClock",
+  "reason",
+  "receiptDigest",
+  "remoteContentDigest",
+  "reviewerId",
+  "schema",
+  "tenantId",
+]);
+const ATTESTATION_KEYS = new Set(["algorithm", "keyId", "value"]);
+const PLAN_KEYS = new Set([
+  "conflictEnvelopeDigest",
+  "decidedAt",
+  "deviceId",
+  "humanReceiptDigest",
+  "knowledgeId",
+  "localContentDigest",
+  "mergedKnowledge",
+  "planDigest",
+  "remoteContentDigest",
+  "requestedBy",
+  "schema",
+  "scope",
+  "scopeId",
+  "tenantId",
+]);
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function hash(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(domain)
+    .update("\0")
+    .update(canonical(value))
+    .digest("hex")}`;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function freeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freeze(child);
+  }
+  return value;
+}
+
+function exact(value, keys, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  const actual = Reflect.ownKeys(value);
+  if (
+    actual.length !== keys.size ||
+    actual.some((key) => typeof key !== "string" || !keys.has(key))
+  ) {
+    throw new TypeError(`${label} has an invalid shape`);
+  }
+  return value;
+}
+
+function identifier(value, label) {
+  if (typeof value !== "string" || !ID.test(value)) {
+    throw new TypeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function capture(owner, method, label) {
+  if (
+    !owner ||
+    typeof owner !== "object" ||
+    utilTypes.isProxy(owner) ||
+    typeof owner[method] !== "function"
+  ) {
+    throw new TypeError(`${label}.${method}() is required`);
+  }
+  return (...args) => Reflect.apply(owner[method], owner, args);
+}
+
+function receiptCore(receipt) {
+  const core = clone(receipt);
+  delete core.receiptDigest;
+  delete core.attestation;
+  return core;
+}
+
+export function digestGovernedKnowledgeHumanMergeReceipt(receipt) {
+  return hash(
+    GOVERNED_KNOWLEDGE_HUMAN_MERGE_RECEIPT_SCHEMA,
+    receiptCore(receipt),
+  );
+}
+
+export function verifyGovernedKnowledgeMergePlan(input) {
+  const plan = exact(input, PLAN_KEYS, "governed knowledge merge plan");
+  const merged = verifyGovernedKnowledgeRecord(plan.mergedKnowledge, {
+    tenantId: plan.tenantId,
+  });
+  const core = clone(plan);
+  delete core.planDigest;
+  if (
+    plan.schema !== GOVERNED_KNOWLEDGE_MERGE_PLAN_SCHEMA ||
+    !identifier(plan.tenantId, "tenantId") ||
+    !identifier(plan.deviceId, "deviceId") ||
+    !identifier(plan.knowledgeId, "knowledgeId") ||
+    !identifier(plan.scopeId, "scopeId") ||
+    !identifier(plan.requestedBy, "requestedBy") ||
+    plan.knowledgeId !== merged.knowledgeId ||
+    plan.scope !== merged.scope ||
+    plan.scopeId !== merged.scopeId ||
+    !DIGEST.test(plan.conflictEnvelopeDigest ?? "") ||
+    !DIGEST.test(plan.localContentDigest ?? "") ||
+    !DIGEST.test(plan.remoteContentDigest ?? "") ||
+    !DIGEST.test(plan.humanReceiptDigest ?? "") ||
+    !DIGEST.test(plan.planDigest ?? "") ||
+    !Number.isFinite(Date.parse(plan.decidedAt)) ||
+    plan.planDigest !== hash(GOVERNED_KNOWLEDGE_MERGE_PLAN_SCHEMA, core)
+  ) {
+    throw new Error("governed knowledge merge plan is invalid");
+  }
+  return freeze(clone(plan));
+}
+
+export function isGovernedKnowledgeMergePlan(value) {
+  return MERGE_PLANS.has(value);
+}
+
+function normalizeReceipt(input, context, now) {
+  const receipt = exact(input, RECEIPT_KEYS, "human merge receipt");
+  const attestation = exact(
+    receipt.attestation,
+    ATTESTATION_KEYS,
+    "human merge attestation",
+  );
+  const decidedAt = Date.parse(receipt.decidedAt);
+  if (
+    receipt.schema !== GOVERNED_KNOWLEDGE_HUMAN_MERGE_RECEIPT_SCHEMA ||
+    receipt.tenantId !== context.tenantId ||
+    receipt.automated !== false ||
+    receipt.knowledgeId !== context.knowledgeId ||
+    receipt.conflictEnvelopeDigest !== context.conflictEnvelopeDigest ||
+    receipt.localContentDigest !== context.localContentDigest ||
+    receipt.remoteContentDigest !== context.remoteContentDigest ||
+    receipt.mergedContentDigest !== context.mergedContentDigest ||
+    canonical(receipt.mergedVectorClock) !==
+      canonical(context.mergedVectorClock) ||
+    !identifier(receipt.reviewerId, "reviewerId") ||
+    typeof receipt.reason !== "string" ||
+    receipt.reason.trim() !== receipt.reason ||
+    receipt.reason.length < 1 ||
+    receipt.reason.length > MAX_REASON_LENGTH ||
+    !Number.isFinite(decidedAt) ||
+    decidedAt < now - MAX_RECEIPT_AGE_MS ||
+    decidedAt > now + MAX_FUTURE_SKEW_MS ||
+    !DIGEST.test(receipt.receiptDigest ?? "") ||
+    receipt.receiptDigest !== digestGovernedKnowledgeHumanMergeReceipt(receipt)
+  ) {
+    throw new Error("human merge receipt is not exactly bound");
+  }
+  for (const [key, value] of Object.entries(attestation)) {
+    if (
+      typeof value !== "string" ||
+      value.trim() !== value ||
+      value.length < 1 ||
+      value.length > (key === "value" ? 4096 : 256)
+    ) {
+      throw new TypeError("human merge attestation is invalid");
+    }
+  }
+  return freeze(clone(receipt));
+}
+
+function exactMergeClock(local, remote, merged, deviceId) {
+  const devices = new Set([...Object.keys(local), ...Object.keys(remote)]);
+  devices.add(deviceId);
+  if (
+    Object.keys(merged).length !== devices.size ||
+    Object.keys(merged).some((device) => !devices.has(device))
+  ) {
+    return false;
+  }
+  for (const device of devices) {
+    const joined = Math.max(local[device] ?? 0, remote[device] ?? 0);
+    const expected = device === deviceId ? joined + 1 : joined;
+    if (merged[device] !== expected) return false;
+  }
+  return true;
+}
+
+export class GovernedKnowledgeConflictMergePlanner {
+  constructor({ conflictReader, receiptVerifier, now = Date.now } = {}) {
+    if (!isGovernedKnowledgeConflictReader(conflictReader)) {
+      throw new TypeError(
+        "a branded governed knowledge conflict reader is required",
+      );
+    }
+    if (typeof now !== "function" || utilTypes.isProxy(now)) {
+      throw new TypeError("now must be a non-proxy function");
+    }
+    this.tenantId = conflictReader.tenantId;
+    this.deviceId = conflictReader.deviceId;
+    this._getConflict = capture(
+      conflictReader,
+      "getConflict",
+      "conflictReader",
+    );
+    this._load = capture(conflictReader, "load", "conflictReader");
+    this._verifyReceipt = capture(receiptVerifier, "verify", "receiptVerifier");
+    this._now = now;
+    Object.freeze(this);
+  }
+
+  async plan({ conflictEnvelopeDigest, mergedKnowledge, humanReceipt } = {}) {
+    if (!DIGEST.test(conflictEnvelopeDigest ?? "")) {
+      throw new TypeError("conflictEnvelopeDigest is invalid");
+    }
+    const conflict = await this._getConflict({
+      envelopeDigest: conflictEnvelopeDigest,
+    });
+    if (
+      conflict?.disposition !== "conflict" ||
+      conflict.tenantId !== this.tenantId ||
+      conflict.deviceId !== this.deviceId ||
+      conflict.envelopeDigest !== conflictEnvelopeDigest ||
+      !DIGEST.test(conflict.conflictWithDigest ?? "")
+    ) {
+      throw new Error("governed knowledge conflict is missing or invalid");
+    }
+    const current = await this._load({
+      knowledgeId: conflict.knowledge.knowledgeId,
+    });
+    if (
+      !current ||
+      current.contentDigest !== conflict.conflictWithDigest ||
+      current.knowledgeId !== conflict.knowledge.knowledgeId
+    ) {
+      throw new Error("governed knowledge conflict baseline has advanced");
+    }
+    const merged = verifyGovernedKnowledgeRecord(mergedKnowledge, {
+      tenantId: this.tenantId,
+    });
+    if (
+      merged.knowledgeId !== current.knowledgeId ||
+      merged.scope !== current.scope ||
+      merged.scopeId !== current.scopeId ||
+      merged.scope !== conflict.knowledge.scope ||
+      merged.scopeId !== conflict.knowledge.scopeId ||
+      merged.action !== "upsert" ||
+      !exactMergeClock(
+        current.vectorClock,
+        conflict.knowledge.vectorClock,
+        merged.vectorClock,
+        this.deviceId,
+      )
+    ) {
+      throw new Error("merged knowledge does not exactly join both histories");
+    }
+    const now = Number(this._now());
+    if (!Number.isFinite(now)) throw new TypeError("merge clock is invalid");
+    const context = {
+      tenantId: this.tenantId,
+      knowledgeId: merged.knowledgeId,
+      conflictEnvelopeDigest,
+      localContentDigest: current.contentDigest,
+      remoteContentDigest: conflict.knowledge.contentDigest,
+      mergedContentDigest: merged.contentDigest,
+      mergedVectorClock: merged.vectorClock,
+    };
+    const receipt = normalizeReceipt(humanReceipt, context, now);
+    const verified = await this._verifyReceipt({
+      receipt,
+      conflict,
+      currentKnowledge: current,
+      mergedKnowledge: merged,
+    });
+    if (
+      verified?.authenticated !== true ||
+      verified.durable !== true ||
+      verified.automated !== false ||
+      verified.tenantId !== this.tenantId ||
+      verified.reviewerId !== receipt.reviewerId ||
+      verified.knowledgeId !== merged.knowledgeId ||
+      verified.conflictEnvelopeDigest !== conflictEnvelopeDigest ||
+      verified.receiptDigest !== receipt.receiptDigest
+    ) {
+      throw new Error(
+        "human merge receipt authority did not authenticate the decision",
+      );
+    }
+    const core = {
+      schema: GOVERNED_KNOWLEDGE_MERGE_PLAN_SCHEMA,
+      tenantId: this.tenantId,
+      deviceId: this.deviceId,
+      knowledgeId: merged.knowledgeId,
+      scope: merged.scope,
+      scopeId: merged.scopeId,
+      conflictEnvelopeDigest,
+      localContentDigest: current.contentDigest,
+      remoteContentDigest: conflict.knowledge.contentDigest,
+      mergedKnowledge: merged,
+      humanReceiptDigest: receipt.receiptDigest,
+      requestedBy: receipt.reviewerId,
+      decidedAt: receipt.decidedAt,
+    };
+    const plan = freeze({
+      ...core,
+      planDigest: hash(GOVERNED_KNOWLEDGE_MERGE_PLAN_SCHEMA, core),
+    });
+    MERGE_PLANS.add(plan);
+    return plan;
+  }
+}