chainlesschain 0.166.21 → 0.166.24

package/src/lib/evolution/structured-memory-agent-control-plane.js

@@ -1,10 +1,12 @@
 import structuredMemory from "@chainlesschain/session-core/structured-evolution-memory";
+import { types as utilTypes } from "node:util";
 import { StructuredMemoryLedgerAdapter } from "./structured-memory-ledger-adapter.js";
 import { StructuredMemoryAuthorityLedgerAdapter } from "./structured-memory-authority-ledger-adapter.js";
 import { captureStructuredMemoryPromotionReceiptWriter } from "./structured-memory-promotion-receipt-writer.js";
 import { captureStructuredMemoryPolicyReceiptWriter } from "./structured-memory-policy-receipt-writer.js";
 import { createStructuredMemorySemanticReviewPipeline } from "./structured-memory-semantic-review-pipeline.js";
 import { createSkillEvaluatedPromotionControlPlane } from "./skill-promotion-controller.js";
+import { SKILL_REVOCATION_DEPENDENCY_RESULT_SCHEMA } from "./skill-revocation-propagation.js";
 
 const { captureStructuredMemoryAuthority } = structuredMemory;
 
@@ -12,6 +14,51 @@ export const STRUCTURED_MEMORY_AGENT_CONTROL_PLANE_SCHEMA =
   "chainlesschain.structured-memory-agent-control-plane/v1";
 
 const CONTROL_PLANES = new WeakSet();
+const REVOCATION_REQUEST_KEYS = new Set([
+  "schema",
+  "tenantId",
+  "streamId",
+  "operationId",
+  "transitionDigest",
+  "candidateId",
+  "skillName",
+  "occurredAt",
+  "sourceReceiptDigest",
+  "resolutionDigest",
+  "dependency",
+  "requestDigest",
+]);
+const REVOCATION_DEPENDENCY_KEYS = new Set([
+  "kind",
+  "ref",
+  "digest",
+  "disposition",
+]);
+
+function exactDataRecord(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 record`);
+  }
+  const own = Reflect.ownKeys(value);
+  if (
+    own.length !== keys.size ||
+    own.some((key) => typeof key !== "string" || !keys.has(key))
+  ) {
+    throw new TypeError(`${label} has an invalid shape`);
+  }
+  for (const key of own) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`${label}.${String(key)} is not a data field`);
+    }
+  }
+}
 
 function sameStorage(left, right) {
   return (
@@ -143,6 +190,78 @@ export function createStructuredMemoryAgentControlPlane({
       projection: memory.projection(),
     });
   };
+  const quarantineMemory = async (input) => {
+    exactDataRecord(
+      input,
+      REVOCATION_REQUEST_KEYS,
+      "Memory revocation request",
+    );
+    exactDataRecord(
+      input.dependency,
+      REVOCATION_DEPENDENCY_KEYS,
+      "Memory revocation dependency",
+    );
+    const request = structuredClone(input);
+    const projection = memory.projection();
+    const active = projection.memories[request?.dependency?.ref];
+    const quarantined = projection.quarantines?.[request?.dependency?.ref];
+    const subject =
+      active ??
+      (quarantined
+        ? {
+            ...quarantined,
+            memoryId: request.dependency.ref,
+            status: "active",
+          }
+        : null);
+    if (!subject) {
+      throw new Error("procedural Memory dependency is missing");
+    }
+    const authorityReceipt = await promotion.retainRevocation(request, subject);
+    if (quarantined) {
+      if (
+        quarantined.metadata?.revocationPropagationRequestDigest !==
+          request.requestDigest ||
+        quarantined.receipts?.revocation !== authorityReceipt.receiptDigest
+      ) {
+        throw new Error("quarantined Memory conflicts with the rollback");
+      }
+    } else {
+      await memory.append({
+        eventId: `revocation-${request.requestDigest.slice("sha256:".length)}`,
+        memoryId: subject.memoryId,
+        layer: "procedural",
+        action: "quarantine",
+        authority: promotionActor,
+        automatic: true,
+        contentDigest: subject.contentDigest,
+        artifactRef: subject.artifactRef,
+        evidenceRefs: authorityReceipt.evidenceRefs,
+        supersedes: [],
+        receiptRefs: { revocation: authorityReceipt.receiptDigest },
+        timestamp: request.occurredAt,
+        metadata: {
+          revocationPropagationRequestDigest: request.requestDigest,
+          transitionDigest: request.transitionDigest,
+        },
+      });
+    }
+    return Object.freeze({
+      schema: SKILL_REVOCATION_DEPENDENCY_RESULT_SCHEMA,
+      authenticated: true,
+      durable: true,
+      applied: true,
+      idempotent: true,
+      tenantId,
+      operationId: request.operationId,
+      requestDigest: request.requestDigest,
+      dependencyKind: request.dependency.kind,
+      dependencyRef: request.dependency.ref,
+      dependencyDigest: request.dependency.digest,
+      disposition: request.dependency.disposition,
+      receiptDigest: memory.projection().projectionDigest,
+    });
+  };
   const controlPlane = Object.freeze({
     schema: STRUCTURED_MEMORY_AGENT_CONTROL_PLANE_SCHEMA,
     tenantId,
@@ -152,6 +271,7 @@ export function createStructuredMemoryAgentControlPlane({
     promotionReceiptWriter: promotion,
     policyReceiptWriter: policy,
     reconcilePromotionMemories: Object.freeze(reconcilePromotionMemories),
+    quarantineMemory: Object.freeze(quarantineMemory),
     createEvaluatedPromotionControlPlane(options = {}) {
       if (
         !options ||

package/src/lib/evolution/structured-memory-authority-ledger-adapter.js

@@ -258,7 +258,11 @@ export class StructuredMemoryAuthorityLedgerAdapter {
   }
 
   async listReceipts(kind) {
-    if (!["critic", "evaluator", "promotion", "policy"].includes(kind)) {
+    if (
+      !["critic", "evaluator", "promotion", "revocation", "policy"].includes(
+        kind,
+      )
+    ) {
       throw new TypeError(
         "a structured memory authority receipt kind is required",
       );

package/src/lib/evolution/structured-memory-promotion-receipt-writer.js

@@ -1,8 +1,13 @@
 import { createHash } from "node:crypto";
+import { types as utilTypes } from "node:util";
 import structuredMemory from "@chainlesschain/session-core/structured-evolution-memory";
 import { buildSkillEvaluatedPromotionReceiptEnvelope } from "./skill-evaluated-promotion.js";
 import { digestSkillMutationReceiptEnvelope } from "./skill-mutation-authority.js";
 import { SKILL_TARGET_MATRIX_EVAL_RECEIPT_SCHEMA } from "./skill-target-matrix-eval.js";
+import {
+  SKILL_REVOCATION_DEPENDENCY_REQUEST_SCHEMA,
+  digestSkillRevocationDependencyRequest,
+} from "./skill-revocation-propagation.js";
 
 const { createStructuredMemoryAuthorityReceipt } = structuredMemory;
 const SKILL_RELEASE_RECEIPT_SCHEMA =
@@ -12,6 +17,26 @@ const SKILL_PROMOTION_REVIEW_ENVELOPE_SCHEMA =
 const RELEASE_RECEIPT_DOMAIN = `${SKILL_RELEASE_RECEIPT_SCHEMA}\0`;
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const WRITERS = new WeakSet();
+const REVOCATION_REQUEST_KEYS = new Set([
+  "schema",
+  "tenantId",
+  "streamId",
+  "operationId",
+  "transitionDigest",
+  "candidateId",
+  "skillName",
+  "occurredAt",
+  "sourceReceiptDigest",
+  "resolutionDigest",
+  "dependency",
+  "requestDigest",
+]);
+const REVOCATION_DEPENDENCY_KEYS = new Set([
+  "kind",
+  "ref",
+  "digest",
+  "disposition",
+]);
 
 function canonical(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
@@ -40,6 +65,31 @@ function requiredDigest(value, name) {
   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 record`);
+  }
+  const own = Reflect.ownKeys(value);
+  if (
+    own.length !== keys.size ||
+    own.some((key) => typeof key !== "string" || !keys.has(key))
+  ) {
+    throw new TypeError(`${label} has an invalid shape`);
+  }
+  for (const key of own) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`${label}.${String(key)} is not a data field`);
+    }
+  }
+}
+
 function capture(owner, name) {
   if (typeof owner?.[name] !== "function") {
     throw new TypeError(`${name} port is required`);
@@ -143,6 +193,45 @@ function verifyPromotion(result, matrixBinding, reviewBinding, tenantId) {
   return { release, receipt, evidenceRefs: [...new Set(evidenceRefs)].sort() };
 }
 
+function verifyRevocation(request, memory, tenantId) {
+  exact(request, REVOCATION_REQUEST_KEYS, "Memory revocation request");
+  exact(
+    request.dependency,
+    REVOCATION_DEPENDENCY_KEYS,
+    "Memory revocation dependency",
+  );
+  if (
+    request?.schema !== SKILL_REVOCATION_DEPENDENCY_REQUEST_SCHEMA ||
+    request.tenantId !== tenantId ||
+    request.dependency?.kind !== "memory" ||
+    request.dependency.disposition !== "quarantine" ||
+    request.dependency.ref !== memory?.memoryId ||
+    request.dependency.digest !== memory?.contentDigest ||
+    request.requestDigest !== digestSkillRevocationDependencyRequest(request) ||
+    memory.layer !== "procedural" ||
+    !DIGEST.test(request.transitionDigest ?? "") ||
+    !DIGEST.test(request.sourceReceiptDigest ?? "") ||
+    !DIGEST.test(request.resolutionDigest ?? "") ||
+    !Number.isFinite(Date.parse(request.occurredAt ?? "")) ||
+    new Date(request.occurredAt).toISOString() !== request.occurredAt ||
+    typeof memory.artifactRef !== "string" ||
+    !Array.isArray(memory.evidenceRefs)
+  ) {
+    throw new Error("Memory revocation request is not exactly bound");
+  }
+  return {
+    evidenceRefs: [
+      ...new Set([
+        ...memory.evidenceRefs,
+        request.transitionDigest,
+        request.sourceReceiptDigest,
+        request.resolutionDigest,
+        request.requestDigest,
+      ]),
+    ].sort(),
+  };
+}
+
 export function createStructuredMemoryPromotionReceiptWriter({
   descriptor: input,
   authorityStore,
@@ -201,6 +290,42 @@ export function createStructuredMemoryPromotionReceiptWriter({
       }
       return signed;
     },
+    async retainRevocation(request, memory) {
+      const verified = verifyRevocation(request, memory, descriptor.tenantId);
+      const receipt = createStructuredMemoryAuthorityReceipt({
+        tenantId: descriptor.tenantId,
+        kind: "revocation",
+        decision: "accepted",
+        memoryId: memory.memoryId,
+        layer: "procedural",
+        action: "quarantine",
+        contentDigest: memory.contentDigest,
+        artifactRef: memory.artifactRef,
+        evidenceRefs: verified.evidenceRefs,
+        issuerId: descriptor.issuerId,
+        issuerRevision: descriptor.issuerRevision,
+        issuerHandlerDigest: descriptor.issuerHandlerDigest,
+        issuedAt: request.occurredAt,
+      });
+      const attestation = await attest({
+        purpose: "structured-memory-revocation-receipt",
+        payloadDigest: receipt.receiptDigest,
+        receipt,
+        propagationRequestDigest: request.requestDigest,
+      });
+      if (attestation === null || attestation === undefined) {
+        throw new Error("revocation receipt attestor returned no attestation");
+      }
+      const signed = Object.freeze({ ...receipt, attestation });
+      const retained = await retainReceipt(signed);
+      if (
+        retained?.persisted !== true ||
+        retained.receiptDigest !== receipt.receiptDigest
+      ) {
+        throw new Error("revocation receipt was not durably acknowledged");
+      }
+      return signed;
+    },
   });
   WRITERS.add(writer);
   return writer;
@@ -215,6 +340,7 @@ export function captureStructuredMemoryPromotionReceiptWriter(value) {
   const captured = Object.freeze({
     descriptor: value.descriptor,
     retainPromotion: capture(value, "retainPromotion"),
+    retainRevocation: capture(value, "retainRevocation"),
   });
   WRITERS.add(captured);
   return captured;

package/src/lib/evolution/wiki-informed-skill-proposer.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 
 export const WIKI_SKILL_PROPOSAL_SCHEMA =
-  "chainlesschain.wiki-informed-skill-proposal/v1";
+  "chainlesschain.wiki-informed-skill-proposal/v2";
 export const WIKI_PROPOSAL_STATUS = Object.freeze({
   PROPOSAL: "proposal",
   NO_PROPOSAL: "no-proposal",
@@ -38,6 +38,10 @@ function hash(value) {
   return `sha256:${createHash("sha256").update(canonical(value)).digest("hex")}`;
 }
 
+export function computeWikiSkillProposalDigest(proposal) {
+  return hash(proposal);
+}
+
 function deepFreeze(value) {
   if (value && typeof value === "object" && !Object.isFrozen(value)) {
     Object.freeze(value);
@@ -53,6 +57,24 @@ function requiredString(value, name) {
   return value;
 }
 
+function normalizeProposerModel(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+    canonical(Object.keys(value).sort()) !==
+      canonical(["model", "provider", "version"])
+  ) {
+    throw new TypeError("proposerModel must be an exact plain object");
+  }
+  return {
+    provider: requiredString(value.provider, "proposerModel.provider"),
+    model: requiredString(value.model, "proposerModel.model"),
+    version: requiredString(value.version, "proposerModel.version"),
+  };
+}
+
 function stringList(value, name, { allowEmpty = false, max = 64 } = {}) {
   if (
     !Array.isArray(value) ||
@@ -76,7 +98,9 @@ function verifyEnvelope(value, expectedKind) {
     !DIGEST.test(value.digest ?? "") ||
     value.digest !== hash(value.data)
   ) {
-    const error = new Error(`${expectedKind} evidence is not digest-bound and trusted`);
+    const error = new Error(
+      `${expectedKind} evidence is not digest-bound and trusted`,
+    );
     error.code = "WIKI_PROPOSAL_UNTRUSTED_EVIDENCE";
     throw error;
   }
@@ -94,7 +118,7 @@ function normalizeDescriptor(input) {
     evolutionRunId: requiredString(input?.evolutionRunId, "evolutionRunId"),
     targetSkillName: requiredString(input?.targetSkillName, "targetSkillName"),
     wikiRevision: requiredString(input?.wikiRevision, "wikiRevision"),
-    proposerModel: requiredString(input?.proposerModel, "proposerModel"),
+    proposerModel: normalizeProposerModel(input?.proposerModel),
     minEvidenceSamples: Math.max(1, Number(input?.minEvidenceSamples) || 1),
     maxSelectiveEvidence: Math.min(
       16,
@@ -115,7 +139,10 @@ function validateDiff(diff) {
     if (!entry || !["add", "replace", "remove"].includes(entry.op)) {
       throw new TypeError("machineDiff operation is invalid");
     }
-    const path = requiredString(entry.path, "machineDiff.path").replaceAll("\\", "/");
+    const path = requiredString(entry.path, "machineDiff.path").replaceAll(
+      "\\",
+      "/",
+    );
     const parts = path.split("/");
     if (
       path.startsWith("/") ||
@@ -141,7 +168,9 @@ function validateProposal(output, descriptor, evidence) {
     throw new TypeError("proposal output status is invalid");
   }
   if (output.skillName !== descriptor.targetSkillName) {
-    const error = new Error("proposer attempted to change more than the fixed Skill");
+    const error = new Error(
+      "proposer attempted to change more than the fixed Skill",
+    );
     error.code = "WIKI_PROPOSAL_MULTI_SKILL";
     throw error;
   }
@@ -156,7 +185,9 @@ function validateProposal(output, descriptor, evidence) {
   };
   for (const ref of [...purpose.patternRefs, ...purpose.sourceEvidenceRefs]) {
     if (!knownRefs.has(ref)) {
-      const error = new Error("PURPOSE references evidence outside the resolved set");
+      const error = new Error(
+        "PURPOSE references evidence outside the resolved set",
+      );
       error.code = "WIKI_PROPOSAL_UNKNOWN_LINEAGE";
       throw error;
     }
@@ -181,22 +212,38 @@ function validateProposal(output, descriptor, evidence) {
     skillName: descriptor.targetSkillName,
     purpose,
     applicableWhen: stringList(output.applicableWhen, "applicableWhen"),
-    notApplicableWhen: stringList(output.notApplicableWhen, "notApplicableWhen"),
+    notApplicableWhen: stringList(
+      output.notApplicableWhen,
+      "notApplicableWhen",
+    ),
     failureCounterexamples: stringList(
       output.failureCounterexamples,
       "failureCounterexamples",
     ),
     rollbackSteps: stringList(output.rollbackSteps, "rollbackSteps"),
-    validationMethods: stringList(output.validationMethods, "validationMethods"),
+    validationMethods: stringList(
+      output.validationMethods,
+      "validationMethods",
+    ),
     requestedCapabilities: stringList(
       output.requestedCapabilities,
       "requestedCapabilities",
       { allowEmpty: true },
-    ),
-    targetRuntimes: stringList(output.targetRuntimes, "targetRuntimes"),
+    ).sort(),
+    targetRuntimes: stringList(output.targetRuntimes, "targetRuntimes").sort(),
     contextCost,
     machineDiff: validateDiff(output.machineDiff),
-    sourceEvidenceRefs: evidence.map(({ ref, digest }) => ({ ref, digest })),
+    sourceEvidenceRefs: evidence
+      .map(({ ref, digest }) => ({ ref, digest }))
+      .sort(
+        (left, right) =>
+          (left.ref < right.ref ? -1 : left.ref > right.ref ? 1 : 0) ||
+          (left.digest < right.digest
+            ? -1
+            : left.digest > right.digest
+              ? 1
+              : 0),
+      ),
     wikiRevision: descriptor.wikiRevision,
     proposerModel: descriptor.proposerModel,
   });
@@ -214,8 +261,13 @@ function abstention(status, reason, evidence = []) {
 export class WikiInformedSkillProposer {
   constructor({ descriptor, policy, ports } = {}) {
     this.descriptor = normalizeDescriptor(descriptor);
-    if (policy?.proposerWikiRead !== true || policy?.executionAgentWikiRead === true) {
-      throw new Error("capability policy must isolate Wiki reads to the proposer");
+    if (
+      policy?.proposerWikiRead !== true ||
+      policy?.executionAgentWikiRead === true
+    ) {
+      throw new Error(
+        "capability policy must isolate Wiki reads to the proposer",
+      );
     }
     if (typeof ports?.readInitial !== "function")
       throw new TypeError("readInitial port is required");
@@ -229,7 +281,7 @@ export class WikiInformedSkillProposer {
     Object.freeze(this);
   }
 
-  async propose() {
+  async draft() {
     const initial = [];
     for (const kind of INITIAL_SOURCES) {
       initial.push(verifyEnvelope(await this._ports.readInitial(kind), kind));
@@ -243,7 +295,9 @@ export class WikiInformedSkillProposer {
         initial,
       );
     }
-    if (Number(training.data?.sampleCount) < this.descriptor.minEvidenceSamples) {
+    if (
+      Number(training.data?.sampleCount) < this.descriptor.minEvidenceSamples
+    ) {
       return abstention(
         WIKI_PROPOSAL_STATUS.NEEDS_EVIDENCE,
         "training evidence sample is insufficient",
@@ -257,7 +311,11 @@ export class WikiInformedSkillProposer {
       evidence: deepFreeze([...evidence]),
     });
     if (output?.status === WIKI_PROPOSAL_STATUS.NO_PROPOSAL) {
-      return abstention(output.status, requiredString(output.reason, "reason"), evidence);
+      return abstention(
+        output.status,
+        requiredString(output.reason, "reason"),
+        evidence,
+      );
     }
     if (output?.status === WIKI_PROPOSAL_STATUS.NEEDS_EVIDENCE) {
       const requests = output.requests;
@@ -266,11 +324,19 @@ export class WikiInformedSkillProposer {
         requests.length === 0 ||
         requests.length > this.descriptor.maxSelectiveEvidence
       ) {
-        return abstention(output.status, "selective evidence request is invalid", evidence);
+        return abstention(
+          output.status,
+          "selective evidence request is invalid",
+          evidence,
+        );
       }
       for (const request of requests) {
         if (!SELECTIVE_SOURCES.has(request?.kind)) {
-          return abstention(output.status, "requested evidence scope is not allowed", evidence);
+          return abstention(
+            output.status,
+            "requested evidence scope is not allowed",
+            evidence,
+          );
         }
         evidence.push(
           verifyEnvelope(
@@ -295,7 +361,45 @@ export class WikiInformedSkillProposer {
     }
 
     const proposal = validateProposal(output, this.descriptor, evidence);
-    const proposalDigest = hash(proposal);
+    const proposalDigest = computeWikiSkillProposalDigest(proposal);
+    return deepFreeze({
+      status: WIKI_PROPOSAL_STATUS.PROPOSAL,
+      proposal,
+      proposalDigest,
+    });
+  }
+
+  async propose() {
+    const drafted = await this.draft();
+    if (drafted.status !== WIKI_PROPOSAL_STATUS.PROPOSAL) return drafted;
+    return this.createCandidateFromDraft(drafted);
+  }
+
+  async createCandidateFromDraft(drafted) {
+    const proposal = drafted?.proposal;
+    const sourceEvidenceRefs = Array.isArray(proposal?.sourceEvidenceRefs)
+      ? proposal.sourceEvidenceRefs
+      : [];
+    const normalized = validateProposal(
+      proposal,
+      this.descriptor,
+      sourceEvidenceRefs,
+    );
+    if (
+      drafted?.status !== WIKI_PROPOSAL_STATUS.PROPOSAL ||
+      proposal?.schema !== WIKI_SKILL_PROPOSAL_SCHEMA ||
+      proposal?.tenantId !== this.descriptor.tenantId ||
+      proposal?.evolutionRunId !== this.descriptor.evolutionRunId ||
+      canonical(normalized) !== canonical(proposal) ||
+      drafted?.proposalDigest !== computeWikiSkillProposalDigest(proposal)
+    ) {
+      const error = new Error(
+        "draft is not an exact proposal bound to this proposer",
+      );
+      error.code = "WIKI_PROPOSAL_DRAFT_UNCONFIRMED";
+      throw error;
+    }
+    const { proposalDigest } = drafted;
     const candidateInput = deepFreeze({
       tenantId: proposal.tenantId,
       skillName: proposal.skillName,
@@ -315,10 +419,12 @@ export class WikiInformedSkillProposer {
       candidate.content !== candidateInput.content ||
       candidate.derivationMode !== "wiki" ||
       candidate.wikiRevision !== proposal.wikiRevision ||
-      candidate.proposerModel !== proposal.proposerModel ||
+      canonical(candidate.proposerModel) !==
+        canonical(proposal.proposerModel) ||
       canonical(candidate.requestedCapabilities) !==
         canonical(proposal.requestedCapabilities) ||
-      canonical(candidate.targetRuntimes) !== canonical(proposal.targetRuntimes) ||
+      canonical(candidate.targetRuntimes) !==
+        canonical(proposal.targetRuntimes) ||
       canonical(candidate.sourceEvidenceRefs) !==
         canonical(proposal.sourceEvidenceRefs)
     ) {