chainlesschain 0.166.22 → 0.166.25

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

@@ -3,22 +3,28 @@ import { types as utilTypes } from "node:util";
 
 import { isGovernedKnowledgeDependencyExecutor } from "./governed-knowledge-dependency-ledger-executor.js";
 import { isGovernedKnowledgeArtifactLifecycle } from "./governed-knowledge-artifact-lifecycle.js";
+import {
+  captureGovernedKnowledgeDependencyInventoryPlan,
+  isGovernedKnowledgeDependencyInventoryPlanner,
+} from "./governed-knowledge-dependency-inventory.js";
+
+import {
+  GOVERNED_KNOWLEDGE_SCOPE,
+  verifyGovernedKnowledgeRecord,
+  normalizeGovernedKnowledgeVectorClock as vectorClock,
+} from "./governed-knowledge-record.js";
+export {
+  GOVERNED_KNOWLEDGE_SYNC_SCHEMA,
+  GOVERNED_KNOWLEDGE_SCOPE,
+  verifyGovernedKnowledgeRecord,
+} from "./governed-knowledge-record.js";
 
-export const GOVERNED_KNOWLEDGE_SYNC_SCHEMA =
-  "chainlesschain.governed-evolution-knowledge-sync/v1";
 export const GOVERNED_KNOWLEDGE_ENVELOPE_SCHEMA =
   "chainlesschain.governed-evolution-knowledge-envelope/v1";
 export const GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_SCHEMA =
   "chainlesschain.governed-knowledge-artifact-binding/v2";
 export const GOVERNED_KNOWLEDGE_ARTIFACT_BINDING_LEGACY_SCHEMA =
   "chainlesschain.governed-knowledge-artifact-binding/v1";
-export const GOVERNED_KNOWLEDGE_SCOPE = Object.freeze({
-  PERSONAL: "personal",
-  PROJECT: "project",
-  TEAM: "team",
-  ORG: "org",
-});
-
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
 const SCOPES = new Set(Object.values(GOVERNED_KNOWLEDGE_SCOPE));
@@ -26,6 +32,7 @@ const ACTIONS = new Set(["upsert", "tombstone", "revoke"]);
 const MAX_CIPHERTEXT_BYTES = 12 * 1024 * 1024;
 const EXECUTION_RECORDS = new WeakSet();
 const SYNCHRONIZERS = new WeakSet();
+const PLANNED_REVOCATIONS = new WeakMap();
 const ENVELOPE_KEYS = new Set([
   "action",
   "ciphertext",
@@ -97,6 +104,11 @@ function record(value, label) {
     ![Object.prototype, null].includes(Object.getPrototypeOf(value))
   )
     throw new TypeError(`${label} must be a plain object`);
+  for (const key of Reflect.ownKeys(value)) {
+    const property = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !Object.hasOwn(property, "value"))
+      throw new TypeError(`${label} must contain only data properties`);
+  }
   return value;
 }
 
@@ -106,12 +118,6 @@ function id(value, label) {
   return value;
 }
 
-function digest(value, label) {
-  if (typeof value !== "string" || !DIGEST.test(value))
-    throw new TypeError(`${label} must be sha256-bound`);
-  return value;
-}
-
 function capture(owner, method) {
   if (
     !owner ||
@@ -123,23 +129,6 @@ function capture(owner, method) {
   return (...args) => Reflect.apply(owner[method], owner, args);
 }
 
-function vectorClock(value) {
-  record(value, "vectorClock");
-  const entries = Object.entries(value);
-  if (entries.length < 1 || entries.length > 64)
-    throw new TypeError("vectorClock is empty or unbounded");
-  const result = {};
-  for (const [deviceId, revision] of entries.sort(([a], [b]) =>
-    a.localeCompare(b),
-  )) {
-    id(deviceId, "vectorClock device");
-    if (!Number.isSafeInteger(revision) || revision < 0)
-      throw new TypeError("vectorClock revision is invalid");
-    result[deviceId] = revision;
-  }
-  return result;
-}
-
 function relation(left, right) {
   const devices = new Set([...Object.keys(left), ...Object.keys(right)]);
   let before = false;
@@ -156,75 +145,14 @@ function relation(left, right) {
   return "equal";
 }
 
-function normalizeDependencies(value, action) {
-  if (!Array.isArray(value) || value.length > 256)
-    throw new TypeError("dependency dispositions are unbounded");
-  const seen = new Set();
-  return value.map((entry) => {
-    record(entry, "dependency disposition");
-    const normalized = {
-      kind: id(entry.kind, "dependency kind"),
-      digest: digest(entry.digest, "dependency digest"),
-      disposition: id(entry.disposition, "dependency disposition"),
-    };
-    const key = `${normalized.kind}:${normalized.digest}`;
-    if (seen.has(key)) throw new TypeError("duplicate dependency disposition");
-    seen.add(key);
-    if (
-      ["tombstone", "revoke"].includes(action) &&
-      ![
-        "tombstone",
-        "quarantine",
-        "reject-candidate",
-        "rollback-active",
-      ].includes(normalized.disposition)
-    )
-      throw new TypeError("revocation dependency disposition is unsafe");
-    return normalized;
-  });
-}
-
 function normalizeRecord(input, descriptor, { executionRecord = false } = {}) {
-  record(input, "knowledge record");
-  const action = ACTIONS.has(input.action) ? input.action : null;
-  const scope = SCOPES.has(input.scope) ? input.scope : null;
-  if (!action || !scope || input.tenantId !== descriptor.tenantId)
-    throw new TypeError("knowledge record boundary is invalid");
-  const dependencies = normalizeDependencies(input.dependencies || [], action);
-  if (
-    ["team", "org"].includes(scope) &&
-    !DIGEST.test(input.approvalReceiptDigest || "")
-  )
-    throw new TypeError("shared knowledge requires approval");
-  if (
-    ["tombstone", "revoke"].includes(action) &&
-    (!DIGEST.test(input.revocationReceiptDigest || "") ||
-      dependencies.length < 1)
-  )
-    throw new TypeError(
-      "revocation must bind its receipt and dependency graph",
-    );
-  const normalized = freeze({
-    schema: GOVERNED_KNOWLEDGE_SYNC_SCHEMA,
+  const normalized = verifyGovernedKnowledgeRecord(input, {
     tenantId: descriptor.tenantId,
-    knowledgeId: id(input.knowledgeId, "knowledgeId"),
-    scope,
-    scopeId: id(input.scopeId, "scopeId"),
-    action,
-    contentDigest: digest(input.contentDigest, "contentDigest"),
-    vectorClock: vectorClock(input.vectorClock),
-    approvalReceiptDigest: input.approvalReceiptDigest || null,
-    revocationReceiptDigest: input.revocationReceiptDigest || null,
-    dependencies,
   });
   if (executionRecord) EXECUTION_RECORDS.add(normalized);
   return normalized;
 }
 
-export function verifyGovernedKnowledgeRecord(input, { tenantId } = {}) {
-  return normalizeRecord(input, { tenantId: id(tenantId, "tenantId") });
-}
-
 export function verifyGovernedKnowledgeArtifactBinding(
   input,
   { tenantId, knowledge, authorizationReceiptDigest } = {},
@@ -321,6 +249,7 @@ export class GovernedKnowledgeSync {
     deviceId,
     ports,
     dependencyExecutor = null,
+    dependencyPlanner = null,
     artifactLifecycle,
     clock = () => Date.now(),
   } = {}) {
@@ -359,9 +288,106 @@ export class GovernedKnowledgeSync {
     this._executeDependencies = dependencyExecutor
       ? capture(dependencyExecutor, "execute")
       : null;
+    if (
+      dependencyPlanner !== null &&
+      (!isGovernedKnowledgeDependencyInventoryPlanner(dependencyPlanner) ||
+        dependencyExecutor === null)
+    ) {
+      throw new TypeError(
+        "dependencyPlanner requires a branded inventory planner and executor",
+      );
+    }
+    this._dependencyPlanner = dependencyPlanner;
+    this._planDependencies = dependencyPlanner
+      ? capture(dependencyPlanner, "plan")
+      : null;
+    this._prepareDependencies = dependencyPlanner
+      ? capture(dependencyExecutor, "prepare")
+      : null;
+    this._readPreparedDependencies = dependencyPlanner
+      ? capture(dependencyExecutor, "readPrepared")
+      : null;
+    this._readPreparedDependenciesForKnowledge = dependencyPlanner
+      ? capture(dependencyExecutor, "readPreparedForKnowledge")
+      : null;
     SYNCHRONIZERS.add(this);
   }
 
+  async planRevocation(input) {
+    if (!this._planDependencies) {
+      throw new Error("knowledge dependency inventory planner is unavailable");
+    }
+    const planned = this._planDependencies(input);
+    captureGovernedKnowledgeDependencyInventoryPlan(
+      this._dependencyPlanner,
+      planned,
+    );
+    const knowledge = normalizeRecord(planned.knowledge, this, {
+      executionRecord: true,
+    });
+    if (knowledge.scope === "personal") {
+      throw new Error("personal knowledge cannot enter a shared sync channel");
+    }
+    await this._admit("publish", knowledge);
+    const prepared = await this._prepareDependencies(knowledge);
+    if (
+      prepared?.authenticated !== true ||
+      prepared.durable !== true ||
+      !DIGEST.test(prepared.operationDigest ?? "") ||
+      canonical(prepared.knowledge) !== canonical(knowledge)
+    ) {
+      throw new Error("knowledge dependency plan was not durably prepared");
+    }
+    const result = freeze({
+      inventory: planned.inventory,
+      knowledge,
+      operationDigest: prepared.operationDigest,
+      recovered: false,
+    });
+    PLANNED_REVOCATIONS.set(result, this);
+    return result;
+  }
+
+  async recoverPlannedRevocation({ operationDigest } = {}) {
+    if (
+      !this._readPreparedDependencies ||
+      !DIGEST.test(operationDigest ?? "")
+    ) {
+      throw new TypeError(
+        "planned revocation recovery is unavailable or invalid",
+      );
+    }
+    const prepared = this._readPreparedDependencies({ operationDigest });
+    if (
+      prepared?.authenticated !== true ||
+      prepared.durable !== true ||
+      prepared.operationDigest !== operationDigest
+    ) {
+      throw new Error("prepared knowledge revocation was not found");
+    }
+    const knowledge = normalizeRecord(prepared.knowledge, this, {
+      executionRecord: true,
+    });
+    await this._admit("publish", knowledge);
+    const result = freeze({
+      inventory: null,
+      knowledge,
+      operationDigest,
+      recovered: true,
+    });
+    PLANNED_REVOCATIONS.set(result, this);
+    return result;
+  }
+
+  async publishPlanned(plan, options = {}) {
+    if (PLANNED_REVOCATIONS.get(plan) !== this) {
+      throw new TypeError(
+        "a revocation plan prepared by this sync is required",
+      );
+    }
+    return this.publishWithArtifactEvidence(plan.knowledge, options);
+  }
+
   async publish(input, options = {}) {
     const result = await this.publishWithArtifactEvidence(input, options);
     return result.envelope;
@@ -679,7 +705,8 @@ export class GovernedKnowledgeSync {
       activate: binding.activate,
       humanReviewed: binding.humanReviewed,
     });
-    await this._applyRevocationDependencies(knowledge);
+    const dependencyKnowledge = await this._receivedDependencyPlan(knowledge);
+    await this._applyRevocationDependencies(dependencyKnowledge);
     await this._persist(
       knowledge,
       envelope,
@@ -788,6 +815,65 @@ export class GovernedKnowledgeSync {
       throw new Error("revocation dependencies were not durably applied");
     }
   }
+
+  async _receivedDependencyPlan(remoteKnowledge) {
+    if (
+      !["tombstone", "revoke"].includes(remoteKnowledge.action) ||
+      !this._planDependencies
+    ) {
+      return remoteKnowledge;
+    }
+    const portable = (value) => {
+      const copy = clone(value);
+      delete copy.dependencies;
+      return copy;
+    };
+    const recovered =
+      this._readPreparedDependenciesForKnowledge(remoteKnowledge);
+    let localKnowledge;
+    if (recovered) {
+      if (
+        recovered.authenticated !== true ||
+        recovered.durable !== true ||
+        !DIGEST.test(recovered.operationDigest ?? "")
+      ) {
+        throw new Error("received revocation local plan is unauthenticated");
+      }
+      localKnowledge = normalizeRecord(recovered.knowledge, this, {
+        executionRecord: true,
+      });
+    } else {
+      const draft = portable(remoteKnowledge);
+      delete draft.schema;
+      const planned = this._planDependencies(draft);
+      captureGovernedKnowledgeDependencyInventoryPlan(
+        this._dependencyPlanner,
+        planned,
+      );
+      localKnowledge = normalizeRecord(planned.knowledge, this, {
+        executionRecord: true,
+      });
+    }
+    if (
+      canonical(portable(localKnowledge)) !==
+      canonical(portable(remoteKnowledge))
+    ) {
+      throw new Error(
+        "received revocation local plan changed signed knowledge",
+      );
+    }
+    const prepared = await this._prepareDependencies(localKnowledge);
+    if (
+      prepared?.authenticated !== true ||
+      prepared.durable !== true ||
+      canonical(prepared.knowledge) !== canonical(localKnowledge)
+    ) {
+      throw new Error(
+        "received revocation local plan was not durably prepared",
+      );
+    }
+    return localKnowledge;
+  }
 }
 
 export function isGovernedKnowledgeSync(value) {