chainlesschain 0.166.22 → 0.166.25

package/src/lib/evolution/governed-knowledge-dependency-ledger-executor.js

@@ -14,36 +14,37 @@ import {
   GOVERNED_KNOWLEDGE_DEPENDENCY_RESULT_SCHEMA,
   digestGovernedKnowledgeDependencyResult,
   isGovernedKnowledgeDependencyAuthority,
+  captureGovernedKnowledgeDependencyReverifier,
 } from "./governed-knowledge-dependency-authority.js";
 import {
   isGovernedKnowledgeExecutionRecord,
   verifyGovernedKnowledgeRecord,
 } from "./governed-knowledge-sync.js";
 
-export const GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA =
-  "chainlesschain.governed-knowledge-dependencies-prepared/v1";
+import {
+  GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA,
+  GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE,
+  GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT_CODE,
+  digestGovernedKnowledgeDependencyOperation,
+  verifyGovernedKnowledgeDependencyPrepared,
+} from "./governed-knowledge-revocation-record.js";
+export {
+  GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA,
+  GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE,
+  GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT_CODE,
+  digestGovernedKnowledgeDependencyOperation,
+  verifyGovernedKnowledgeDependencyPrepared,
+} from "./governed-knowledge-revocation-record.js";
+
 export const GOVERNED_KNOWLEDGE_DEPENDENCY_SETTLED_SCHEMA =
   "chainlesschain.governed-knowledge-dependencies-settled/v1";
-export const GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE =
-  "knowledge.revocation-dependencies.prepared";
 export const GOVERNED_KNOWLEDGE_DEPENDENCY_SETTLED_EVENT_TYPE =
   "knowledge.revocation-dependencies.settled";
-export const GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT_CODE =
-  "CC_GOVERNED_KNOWLEDGE_DEPENDENCY_LEDGER_CORRUPT";
-
 const EXECUTORS = new WeakSet();
+const EXECUTION_REQUESTS = new WeakMap();
 const ARTIFACT_TYPE = "governed-knowledge-dependency-operation";
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}$/u;
-const PREPARED_KEYS = new Set([
-  "deviceId",
-  "knowledge",
-  "operationDigest",
-  "preparedAt",
-  "recordDigest",
-  "schema",
-  "tenantId",
-]);
 const SETTLED_KEYS = new Set([
   "deviceId",
   "operationDigest",
@@ -138,16 +139,34 @@ function identifier(value, label) {
   return value;
 }
 
+function portableKnowledge(value, tenantId) {
+  const knowledge = verifyGovernedKnowledgeRecord(value, { tenantId });
+  const portable = clone(knowledge);
+  delete portable.dependencies;
+  return portable;
+}
+
 function capture(owner, method, label) {
+  if (!owner || typeof owner !== "object" || utilTypes.isProxy(owner)) {
+    throw new TypeError(`${label}.${method}() is required`);
+  }
+  const implementation = owner[method];
   if (
-    !owner ||
-    typeof owner !== "object" ||
-    utilTypes.isProxy(owner) ||
-    typeof owner[method] !== "function"
+    typeof implementation !== "function" ||
+    utilTypes.isProxy(implementation)
   ) {
-    throw new TypeError(`${label}.${method}() is required`);
+    throw new TypeError(`${label}.${method}() must be a non-proxy function`);
   }
-  return (...args) => Reflect.apply(owner[method], owner, args);
+  return (...args) => Reflect.apply(implementation, owner, args);
+}
+
+export function isGovernedKnowledgeDependencyExecutionRequest(
+  value,
+  authority,
+) {
+  return (
+    EXECUTION_REQUESTS.has(value) && EXECUTION_REQUESTS.get(value) === authority
+  );
 }
 
 function descriptor(input) {
@@ -161,29 +180,6 @@ function descriptor(input) {
   });
 }
 
-export function digestGovernedKnowledgeDependencyOperation({
-  tenantId,
-  deviceId,
-  knowledge,
-}) {
-  return hash(GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA, {
-    tenantId,
-    deviceId,
-    knowledge,
-  });
-}
-
-function preparedCore(value) {
-  return {
-    schema: value.schema,
-    tenantId: value.tenantId,
-    deviceId: value.deviceId,
-    operationDigest: value.operationDigest,
-    knowledge: value.knowledge,
-    preparedAt: value.preparedAt,
-  };
-}
-
 function settledCore(value) {
   return {
     schema: value.schema,
@@ -243,31 +239,6 @@ function validateResult(
   return freeze(clone(value));
 }
 
-function validatePrepared(value, descriptorValue) {
-  exact(value, PREPARED_KEYS, "dependency prepared record");
-  const knowledge = verifyGovernedKnowledgeRecord(value.knowledge, {
-    tenantId: descriptorValue.tenantId,
-  });
-  const operationDigest = digestGovernedKnowledgeDependencyOperation({
-    tenantId: descriptorValue.tenantId,
-    deviceId: descriptorValue.deviceId,
-    knowledge,
-  });
-  if (
-    value.schema !== GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA ||
-    value.tenantId !== descriptorValue.tenantId ||
-    value.deviceId !== descriptorValue.deviceId ||
-    !["tombstone", "revoke"].includes(knowledge.action) ||
-    value.operationDigest !== operationDigest ||
-    !Number.isFinite(Date.parse(value.preparedAt)) ||
-    value.recordDigest !==
-      hash(GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_SCHEMA, preparedCore(value))
-  ) {
-    corrupt("dependency prepared record is invalid");
-  }
-  return freeze(clone(value));
-}
-
 function validateSettled(value, prepared, descriptorValue) {
   exact(value, SETTLED_KEYS, "dependency settled record");
   const { knowledge, operationDigest } = prepared;
@@ -305,6 +276,9 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
     dependencyAuthority,
     now = Date.now,
   } = {}) {
+    if (new.target !== GovernedKnowledgeDependencyLedgerExecutor) {
+      throw new TypeError("dependency executors cannot be subclassed");
+    }
     this.descriptor = descriptor(descriptorInput);
     this._put = capture(artifactPorts, "putCanonical", "artifactPorts");
     this._read = capture(ledger, "read", "ledger");
@@ -331,6 +305,9 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
     }
     this._resolveArtifact = ledgerArtifactResolver;
     this._apply = capture(dependencyAuthority, "apply", "dependencyAuthority");
+    this._reverify =
+      captureGovernedKnowledgeDependencyReverifier(dependencyAuthority);
+    this._dependencyAuthority = dependencyAuthority;
     this._now = now;
     Object.freeze(this);
     EXECUTORS.add(this);
@@ -401,7 +378,10 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
       GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE,
     );
     if (!event) return null;
-    const record = validatePrepared(this._resolve(event), this.descriptor);
+    const record = verifyGovernedKnowledgeDependencyPrepared(
+      this._resolve(event),
+      this.descriptor,
+    );
     if (
       record.operationDigest !== operationDigest ||
       event.decision !== "prepared" ||
@@ -528,7 +508,7 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
     return this._prepared(operationDigest);
   }
 
-  async _settle(prepared, results) {
+  async _settle(prepared, results, verifiedHead) {
     const existing = this._settled(prepared);
     if (existing) return existing;
     const settledAt = this._timestamp();
@@ -547,6 +527,13 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
     const preparedEntry = this._prepared(prepared.operationDigest);
     if (!preparedEntry) corrupt("cannot settle unprepared dependencies");
     const head = this._verifyLedger();
+    if (
+      !verifiedHead ||
+      ["epoch", "ledgerId", "identityDigest", "sequence", "headDigest"].some(
+        (key) => verifiedHead[key] !== head[key],
+      )
+    )
+      corrupt("dependency effects changed before settlement authorization");
     const ref = this._publishArtifact(record);
     const eventId = `${GOVERNED_KNOWLEDGE_DEPENDENCY_SETTLED_EVENT_TYPE}.${prepared.operationDigest.slice(7)}`;
     try {
@@ -585,6 +572,9 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
   }
 
   async execute(knowledgeInput) {
+    if (!EXECUTORS.has(this)) {
+      throw new TypeError("dependency execution requires its branded executor");
+    }
     const knowledge = verifyGovernedKnowledgeRecord(knowledgeInput, {
       tenantId: this.descriptor.tenantId,
     });
@@ -599,24 +589,167 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
     const prepared = this._prepared(operationDigest);
     const completed = prepared ? this._settled(prepared.record) : null;
     if (completed) return this._result(completed.record, knowledge, true);
-    await this._prepare(knowledgeInput, knowledge, operationDigest);
+    const durablePrepare = await this._prepare(
+      knowledgeInput,
+      knowledge,
+      operationDigest,
+    );
+    if (
+      !durablePrepare ||
+      durablePrepare.record.operationDigest !== operationDigest ||
+      canonical(durablePrepare.record.knowledge) !== canonical(knowledge)
+    ) {
+      corrupt("dependency prepare was not durably read back");
+    }
     const results = [];
+    const requests = [];
     for (const dependency of knowledge.dependencies) {
-      results.push(
-        await this._apply({
-          tenantId: this.descriptor.tenantId,
-          deviceId: this.descriptor.deviceId,
+      const request = freeze({
+        tenantId: this.descriptor.tenantId,
+        deviceId: this.descriptor.deviceId,
+        operationDigest,
+        knowledge,
+        dependency,
+      });
+      EXECUTION_REQUESTS.set(request, this._dependencyAuthority);
+      requests.push(request);
+      results.push(await this._apply(request));
+    }
+    // All effects must still hold together at one authenticated head. Earlier
+    // per-effect checks may predate later dependencies or a concurrent writer.
+    // This path only rereads/verifies; it never repeats provider side effects.
+    const verifiedHead = this._verifyLedger();
+    const verifiedResults = [];
+    for (const [index, request] of requests.entries())
+      verifiedResults.push(await this._reverify(request, results[index]));
+    const settled = await this._settle(
+      { operationDigest, knowledge },
+      verifiedResults,
+      verifiedHead,
+    );
+    return this._result(settled.record, knowledge, prepared !== null);
+  }
+
+  async prepare(knowledgeInput) {
+    if (!EXECUTORS.has(this)) {
+      throw new TypeError(
+        "dependency preparation requires its branded executor",
+      );
+    }
+    const knowledge = verifyGovernedKnowledgeRecord(knowledgeInput, {
+      tenantId: this.descriptor.tenantId,
+    });
+    if (
+      !["tombstone", "revoke"].includes(knowledge.action) ||
+      !isGovernedKnowledgeExecutionRecord(knowledgeInput)
+    ) {
+      throw new TypeError(
+        "dependency preparation requires a governed revocation record",
+      );
+    }
+    const operationDigest = digestGovernedKnowledgeDependencyOperation({
+      tenantId: this.descriptor.tenantId,
+      deviceId: this.descriptor.deviceId,
+      knowledge,
+    });
+    const prepared = await this._prepare(
+      knowledgeInput,
+      knowledge,
+      operationDigest,
+    );
+    if (
+      !prepared ||
+      canonical(prepared.record.knowledge) !== canonical(knowledge)
+    ) {
+      corrupt("dependency prepare was not durably read back");
+    }
+    return freeze({
+      authenticated: true,
+      durable: true,
+      operationDigest,
+      knowledge: clone(prepared.record.knowledge),
+    });
+  }
+
+  readPrepared({ operationDigest } = {}) {
+    if (!EXECUTORS.has(this) || !DIGEST.test(operationDigest ?? "")) {
+      throw new TypeError("prepared dependency operation identity is invalid");
+    }
+    const prepared = this._prepared(operationDigest);
+    return prepared === null
+      ? null
+      : freeze({
+          authenticated: true,
+          durable: true,
           operationDigest,
-          knowledge,
-          dependency,
-        }),
+          preparedRecordDigest: prepared.record.recordDigest,
+          knowledge: clone(prepared.record.knowledge),
+        });
+  }
+
+  readPreparedForKnowledge(knowledgeInput) {
+    if (!EXECUTORS.has(this)) {
+      throw new TypeError(
+        "prepared dependency lookup requires its branded executor",
       );
     }
-    const settled = await this._settle({ operationDigest, knowledge }, results);
-    return this._result(settled.record, knowledge, prepared !== null);
+    const target = portableKnowledge(knowledgeInput, this.descriptor.tenantId);
+    const matches = [];
+    for (const event of this._events(
+      GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE,
+    )) {
+      const record = verifyGovernedKnowledgeDependencyPrepared(
+        this._resolve(event),
+        this.descriptor,
+      );
+      if (
+        canonical(
+          portableKnowledge(record.knowledge, this.descriptor.tenantId),
+        ) !== canonical(target)
+      ) {
+        continue;
+      }
+      const prepared = this._prepared(record.operationDigest);
+      if (!prepared || prepared.event.eventDigest !== event.eventDigest) {
+        corrupt("prepared dependency lookup event binding differs");
+      }
+      matches.push(prepared.record);
+    }
+    if (matches.length > 1) {
+      corrupt("prepared dependency lookup is ambiguous");
+    }
+    return matches.length === 0
+      ? null
+      : freeze({
+          authenticated: true,
+          durable: true,
+          operationDigest: matches[0].operationDigest,
+          preparedRecordDigest: matches[0].recordDigest,
+          knowledge: clone(matches[0].knowledge),
+        });
+  }
+
+  readSettlement({ operationDigest } = {}) {
+    if (!EXECUTORS.has(this) || !DIGEST.test(operationDigest ?? "")) {
+      throw new TypeError("dependency settlement identity is invalid");
+    }
+    const prepared = this._prepared(operationDigest);
+    if (!prepared) return null;
+    const settled = this._settled(prepared.record);
+    return settled === null
+      ? null
+      : freeze({
+          authenticated: true,
+          durable: true,
+          operationDigest,
+          record: clone(settled.record),
+        });
   }
 
   async resume({ operationDigest } = {}) {
+    if (!EXECUTORS.has(this)) {
+      throw new TypeError("dependency recovery requires its branded executor");
+    }
     if (!DIGEST.test(operationDigest ?? "")) {
       throw new TypeError("operationDigest is invalid");
     }
@@ -641,6 +774,8 @@ export class GovernedKnowledgeDependencyLedgerExecutor {
   }
 }
 
+Object.freeze(GovernedKnowledgeDependencyLedgerExecutor.prototype);
+
 export function isGovernedKnowledgeDependencyExecutor(value) {
   return EXECUTORS.has(value);
 }