chainlesschain 0.166.18 → 0.166.21

package/src/lib/evolution/evolution-artifact-ports.js

@@ -71,6 +71,12 @@ export const EVOLUTION_ARTIFACT_LEDGER_RETENTION_TYPES = Object.freeze([
   "skill-registry-transition-request",
   "skill-registry-transition-settlement",
   "evolution-run-event",
+  "evolution-workbench-metrics-receipt-retention",
+  "evolution-workbench-metrics-snapshot",
+  "governed-knowledge-sync-record",
+  "governed-knowledge-merge-operation",
+  "governed-knowledge-dependency-operation",
+  "governed-knowledge-trust-record",
   "structured-memory-authority-receipt",
   "structured-memory-event",
   "structured-memory-snapshot",
@@ -100,6 +106,12 @@ export const EVOLUTION_ARTIFACT_TYPES = Object.freeze([
   "evaluation",
   "evaluation-result",
   "evolution-run-event",
+  "evolution-workbench-metrics-receipt-retention",
+  "evolution-workbench-metrics-snapshot",
+  "governed-knowledge-sync-record",
+  "governed-knowledge-merge-operation",
+  "governed-knowledge-dependency-operation",
+  "governed-knowledge-trust-record",
   "evidence",
   "model-projection",
   "policy",
@@ -307,6 +319,15 @@ const LEDGER_RETENTION_PURPOSES_BY_TYPE = new Map([
   ["skill-registry-transition-request", new Set(["evolution-ledger"])],
   ["skill-registry-transition-settlement", new Set(["evolution-ledger"])],
   ["evolution-run-event", new Set(["evolution-ledger"])],
+  [
+    "evolution-workbench-metrics-receipt-retention",
+    new Set(["evolution-ledger"]),
+  ],
+  ["evolution-workbench-metrics-snapshot", new Set(["evolution-ledger"])],
+  ["governed-knowledge-sync-record", new Set(["evolution-ledger"])],
+  ["governed-knowledge-merge-operation", new Set(["evolution-ledger"])],
+  ["governed-knowledge-dependency-operation", new Set(["evolution-ledger"])],
+  ["governed-knowledge-trust-record", new Set(["evolution-ledger"])],
   ["wiki-revision", new Set(["evolution-ledger"])],
   ["structured-memory-authority-receipt", new Set(["evolution-ledger"])],
   ["structured-memory-event", new Set(["evolution-ledger"])],

package/src/lib/evolution/evolution-raw-crypto-shred.js

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+
+export const EVOLUTION_RAW_CRYPTO_SHRED_SCHEMA =
+  "chainlesschain.evolution-raw-crypto-shred/v1";
+export const EVOLUTION_RAW_DELETION_TOMBSTONE_SCHEMA =
+  "chainlesschain.evolution-raw-deletion-tombstone/v1";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+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 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 capture(ports, name) {
+  if (typeof ports?.[name] !== "function")
+    throw new TypeError(`Raw crypto-shred port ${name} is required`);
+  return ports[name].bind(ports);
+}
+
+function string(value, name) {
+  if (typeof value !== "string" || value.trim() === "")
+    throw new TypeError(`${name} is required`);
+  return value;
+}
+
+function digest(value, name) {
+  if (!DIGEST.test(value ?? "")) throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function verifyPruningCall(call, tenantId) {
+  const request = call?.request;
+  if (
+    request?.tenantId !== tenantId ||
+    request.operation !== "crypto-shred" ||
+    !DIGEST.test(call?.requestDigest ?? "") ||
+    call.requestDigest !==
+      hash("chainlesschain.governed-wiki-pruning-operation/v1", request)
+  )
+    throw new Error("Raw crypto-shred request is not pruning-plan-bound");
+  const payload = request.payload;
+  if (
+    typeof payload?.rawArtifactRef !== "string" ||
+    !payload.rawArtifactRef.startsWith(`artifact://${tenantId}/raw/`) ||
+    typeof payload.keyRef !== "string" ||
+    !payload.keyRef.startsWith(`kms://${tenantId}/`)
+  )
+    throw new Error("Raw crypto-shred target is cross-tenant or incomplete");
+  for (const [value, name] of [
+    [request.planDigest, "planDigest"],
+    [request.wikiStateDigest, "wikiStateDigest"],
+    [payload.sourceDigest, "sourceDigest"],
+    [payload.rawCipherDigest, "rawCipherDigest"],
+    [payload.receiptDigest, "deletionReceiptDigest"],
+  ])
+    digest(value, name);
+  string(payload.evidenceRef, "evidenceRef");
+  string(payload.artifactRef, "artifactRef");
+  return request;
+}
+
+export class EvolutionRawCryptoShred {
+  constructor({ tenantId, ports } = {}) {
+    this.tenantId = string(tenantId, "tenantId");
+    this._verifyDeletionReceipt = capture(ports, "verifyDeletionReceipt");
+    this._destroyKey = capture(ports, "destroyKey");
+    this._confirmKeyDestroyed = capture(ports, "confirmKeyDestroyed");
+    this._retainTombstone = capture(ports, "retainTombstone");
+  }
+
+  async shred(call) {
+    const request = verifyPruningCall(call, this.tenantId);
+    const target = request.payload;
+    const deletion = await this._verifyDeletionReceipt({
+      tenantId: this.tenantId,
+      receiptDigest: target.receiptDigest,
+    });
+    if (
+      deletion?.authenticated !== true ||
+      deletion.decision !== "delete" ||
+      deletion.tenantId !== this.tenantId ||
+      deletion.receiptDigest !== target.receiptDigest ||
+      deletion.evidenceRef !== target.evidenceRef ||
+      deletion.sourceDigest !== target.sourceDigest ||
+      deletion.artifactRef !== target.artifactRef ||
+      deletion.rawArtifactRef !== target.rawArtifactRef ||
+      deletion.rawCipherDigest !== target.rawCipherDigest ||
+      deletion.keyRef !== target.keyRef
+    )
+      throw new Error("Raw deletion receipt was substituted");
+    const destructionCore = {
+      schema: EVOLUTION_RAW_CRYPTO_SHRED_SCHEMA,
+      tenantId: this.tenantId,
+      planDigest: request.planDigest,
+      wikiStateDigest: request.wikiStateDigest,
+      evidenceRef: target.evidenceRef,
+      rawArtifactRef: target.rawArtifactRef,
+      rawCipherDigest: target.rawCipherDigest,
+      keyRef: target.keyRef,
+      deletionReceiptDigest: target.receiptDigest,
+    };
+    const destructionRequest = freeze({
+      ...destructionCore,
+      requestDigest: hash(EVOLUTION_RAW_CRYPTO_SHRED_SCHEMA, destructionCore),
+    });
+    const destroyed = await this._destroyKey(destructionRequest);
+    if (
+      destroyed?.authenticated !== true ||
+      destroyed.durable !== true ||
+      destroyed.destroyed !== true ||
+      destroyed.keyRef !== target.keyRef ||
+      destroyed.requestDigest !== destructionRequest.requestDigest ||
+      !DIGEST.test(destroyed.receiptDigest ?? "")
+    )
+      throw new Error("Raw encryption key destruction was not durable");
+    const confirmation = await this._confirmKeyDestroyed({
+      tenantId: this.tenantId,
+      keyRef: target.keyRef,
+      destructionReceiptDigest: destroyed.receiptDigest,
+    });
+    if (
+      confirmation?.authenticated !== true ||
+      confirmation.destroyed !== true ||
+      confirmation.keyRef !== target.keyRef ||
+      confirmation.destructionReceiptDigest !== destroyed.receiptDigest ||
+      !DIGEST.test(confirmation.receiptDigest ?? "")
+    )
+      throw new Error("Raw encryption key destruction could not be confirmed");
+    const tombstoneCore = {
+      schema: EVOLUTION_RAW_DELETION_TOMBSTONE_SCHEMA,
+      tenantId: this.tenantId,
+      pruningRequestDigest: call.requestDigest,
+      destructionRequestDigest: destructionRequest.requestDigest,
+      destructionReceiptDigest: destroyed.receiptDigest,
+      confirmationReceiptDigest: confirmation.receiptDigest,
+      evidenceRef: target.evidenceRef,
+      rawArtifactRef: target.rawArtifactRef,
+      rawCipherDigest: target.rawCipherDigest,
+      deletionReceiptDigest: target.receiptDigest,
+    };
+    const tombstone = freeze({
+      ...tombstoneCore,
+      tombstoneDigest: hash(
+        EVOLUTION_RAW_DELETION_TOMBSTONE_SCHEMA,
+        tombstoneCore,
+      ),
+    });
+    const retained = await this._retainTombstone({ tombstone });
+    if (
+      retained?.authenticated !== true ||
+      retained.durable !== true ||
+      retained.tombstoneDigest !== tombstone.tombstoneDigest ||
+      !DIGEST.test(retained.receiptDigest ?? "")
+    )
+      throw new Error("Raw deletion tombstone was not durably retained");
+    return freeze({
+      authenticated: true,
+      durable: true,
+      requestDigest: call.requestDigest,
+      receiptDigest: retained.receiptDigest,
+      tombstoneDigest: tombstone.tombstoneDigest,
+    });
+  }
+}

package/src/lib/evolution/evolution-workbench-batch-executor.js

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+
+import {
+  EVOLUTION_WORKBENCH_BATCH_PLAN_SCHEMA,
+  filterEvolutionWorkbenchProjection,
+} from "./evolution-workbench-projection.js";
+import { verifySkillPromotionReviewPacketArtifact } from "./skill-promotion-review.js";
+
+export const EVOLUTION_WORKBENCH_BATCH_ITEM_REQUEST_SCHEMA =
+  "chainlesschain.evolution-workbench-batch-item-request/v1";
+export const EVOLUTION_WORKBENCH_BATCH_EXECUTION_SCHEMA =
+  "chainlesschain.evolution-workbench-batch-execution/v1";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+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 value == null ? value : 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 verifyPlan(input, tenantId) {
+  if (
+    input?.schema !== EVOLUTION_WORKBENCH_BATCH_PLAN_SCHEMA ||
+    input.tenantId !== tenantId ||
+    !DIGEST.test(input?.planDigest ?? "")
+  )
+    throw new TypeError("Workbench batch plan is invalid");
+  const core = clone(input);
+  delete core.planDigest;
+  if (hash(EVOLUTION_WORKBENCH_BATCH_PLAN_SCHEMA, core) !== input.planDigest)
+    throw new Error("Workbench batch plan digest is invalid");
+  return freeze(clone(input));
+}
+
+function itemRequest(plan, packet) {
+  const core = {
+    schema: EVOLUTION_WORKBENCH_BATCH_ITEM_REQUEST_SCHEMA,
+    tenantId: plan.tenantId,
+    planDigest: plan.planDigest,
+    sourceProjectionDigest: plan.sourceProjectionDigest,
+    packetDigest: packet.packetDigest,
+    candidateId: packet.candidateId,
+    candidateContentDigest: packet.candidateContentDigest,
+    decision: plan.decision,
+    reason: plan.reason,
+    requestedBy: plan.requestedBy,
+    requiredHumanQuorum: packet.requiredHumanQuorum,
+    contentRiskDigest: packet.contentRisk.contentRiskDigest,
+    contentRiskDetected: packet.contentRisk.detected,
+  };
+  return freeze({
+    ...core,
+    requestDigest: hash(EVOLUTION_WORKBENCH_BATCH_ITEM_REQUEST_SCHEMA, core),
+  });
+}
+
+export class EvolutionWorkbenchBatchExecutor {
+  constructor({ tenantId, ports } = {}) {
+    if (typeof tenantId !== "string" || tenantId.trim() === "")
+      throw new TypeError("tenantId is required");
+    this.tenantId = tenantId;
+    for (const name of [
+      "loadProjection",
+      "resolvePacket",
+      "requestHumanDecision",
+      "retainDecision",
+      "commitExecutionItem",
+    ]) {
+      if (typeof ports?.[name] !== "function")
+        throw new TypeError(
+          `Workbench batch executor port ${name} is required`,
+        );
+      this[`_${name}`] = ports[name].bind(ports);
+    }
+  }
+
+  async execute(input) {
+    const plan = verifyPlan(input, this.tenantId);
+    const projection = await this._loadProjection({
+      tenantId: this.tenantId,
+      projectionDigest: plan.sourceProjectionDigest,
+    });
+    filterEvolutionWorkbenchProjection(projection, { limit: 1 });
+    if (
+      projection.tenantId !== plan.tenantId ||
+      projection.runId !== plan.runId ||
+      projection.skillName !== plan.skillName ||
+      projection.projectionDigest !== plan.sourceProjectionDigest
+    )
+      throw new Error("Workbench batch source projection changed");
+    const pending = new Map(
+      projection.candidates
+        .filter(({ status }) => status === "pending")
+        .map((candidate) => [candidate.packetDigest, candidate]),
+    );
+    const items = [];
+    for (const packetDigest of plan.packetDigests) {
+      if (!pending.has(packetDigest))
+        throw new Error("Workbench batch packet is no longer pending");
+      const packet = verifySkillPromotionReviewPacketArtifact(
+        await this._resolvePacket({ tenantId: this.tenantId, packetDigest }),
+      );
+      if (
+        packet.packetDigest !== packetDigest ||
+        packet.candidateId !== pending.get(packetDigest).candidateId
+      )
+        throw new Error("Workbench batch packet was substituted");
+      const request = itemRequest(plan, packet);
+      const decision = await this._requestHumanDecision(request);
+      const expectedDecision =
+        plan.decision === "approve" ? "approved" : "rejected";
+      if (
+        decision?.tenantId !== this.tenantId ||
+        decision.packetDigest !== packetDigest ||
+        decision.candidateId !== packet.candidateId ||
+        decision.decision !== expectedDecision ||
+        decision.automated !== false ||
+        decision.reason !== plan.reason ||
+        decision.requestDigest !== request.requestDigest ||
+        !DIGEST.test(decision.receiptDigest ?? "") ||
+        typeof decision.signature !== "string" ||
+        decision.signature.length < 32
+      )
+        throw new Error("Workbench batch human decision is not exactly bound");
+      const retained = await this._retainDecision({
+        packetDigest,
+        decision,
+      });
+      if (
+        retained?.persisted !== true ||
+        retained.receiptDigest !== decision.receiptDigest
+      )
+        throw new Error("Workbench batch decision was not durably retained");
+      const itemCore = {
+        packetDigest,
+        requestDigest: request.requestDigest,
+        decisionReceiptDigest: decision.receiptDigest,
+      };
+      const item = freeze({
+        ...itemCore,
+        itemDigest: hash(
+          "chainlesschain.evolution-workbench-batch-execution-item/v1",
+          itemCore,
+        ),
+      });
+      const committed = await this._commitExecutionItem({
+        tenantId: this.tenantId,
+        planDigest: plan.planDigest,
+        item,
+      });
+      if (
+        committed?.authenticated !== true ||
+        committed.durable !== true ||
+        committed.itemDigest !== item.itemDigest
+      )
+        throw new Error("Workbench batch execution item was not committed");
+      items.push(item);
+    }
+    const core = {
+      schema: EVOLUTION_WORKBENCH_BATCH_EXECUTION_SCHEMA,
+      tenantId: this.tenantId,
+      planDigest: plan.planDigest,
+      sourceProjectionDigest: plan.sourceProjectionDigest,
+      items,
+    };
+    return freeze({
+      ...core,
+      executionDigest: hash(EVOLUTION_WORKBENCH_BATCH_EXECUTION_SCHEMA, core),
+    });
+  }
+}

package/src/lib/evolution/evolution-workbench-cli-host.js

@@ -0,0 +1,169 @@
+import { types as utilTypes } from "node:util";
+
+import {
+  buildEvolutionWorkbenchBatchPlan,
+  filterEvolutionWorkbenchProjection,
+} from "./evolution-workbench-projection.js";
+import {
+  buildEvolutionWorkbenchRollbackPlan,
+  compareEvolutionWorkbenchVersions,
+} from "./evolution-workbench-version-control.js";
+
+const HOSTS = new WeakSet();
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+
+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 text(value, label) {
+  if (typeof value !== "string" || value.trim() !== value || value === "") {
+    throw new TypeError(`${label} is required`);
+  }
+  return value;
+}
+
+function digest(value, label) {
+  if (!DIGEST.test(value ?? "")) throw new TypeError(`${label} is invalid`);
+  return value;
+}
+
+function identity(value, tenantId) {
+  if (
+    value?.authenticated !== true ||
+    value.durable !== true ||
+    value.automated !== false ||
+    value.tenantId !== tenantId ||
+    typeof value.subjectId !== "string" ||
+    value.subjectId.trim() === "" ||
+    !DIGEST.test(value.receiptDigest ?? "")
+  ) {
+    throw new Error("Workbench CLI requires a durable human identity");
+  }
+  return value;
+}
+
+async function retainProjection(retain, projection) {
+  const result = await retain({
+    tenantId: projection.tenantId,
+    projection,
+  });
+  if (
+    result?.authenticated !== true ||
+    result.durable !== true ||
+    result.projectionDigest !== projection.projectionDigest
+  ) {
+    throw new Error("Workbench projection was not durably retained");
+  }
+}
+
+export function createEvolutionWorkbenchCliHost({
+  tenantId: tenantIdInput,
+  projectionLoader,
+  projectionAuthority,
+  identityProvider,
+  activeStateReader,
+  batchExecutor,
+  rollbackExecutor,
+} = {}) {
+  const tenantId = text(tenantIdInput, "tenantId");
+  const loadProjection = capture(projectionLoader, "load", "projectionLoader");
+  const retain = capture(projectionAuthority, "retain", "projectionAuthority");
+  const resolveIdentity = capture(
+    identityProvider,
+    "current",
+    "identityProvider",
+  );
+  const readActiveState = capture(
+    activeStateReader,
+    "read",
+    "activeStateReader",
+  );
+  const executeBatch = capture(batchExecutor, "execute", "batchExecutor");
+  const executeRollback = capture(
+    rollbackExecutor,
+    "execute",
+    "rollbackExecutor",
+  );
+
+  async function projection() {
+    const value = await loadProjection({ tenantId });
+    filterEvolutionWorkbenchProjection(value, { limit: 1 });
+    if (value.tenantId !== tenantId) {
+      throw new Error("Workbench projection crossed its tenant boundary");
+    }
+    return value;
+  }
+
+  const host = Object.freeze({
+    tenantId,
+    async list(options = {}) {
+      return filterEvolutionWorkbenchProjection(await projection(), options);
+    },
+    async compare(leftPacketDigest, rightPacketDigest) {
+      return compareEvolutionWorkbenchVersions(await projection(), {
+        leftPacketDigest: digest(leftPacketDigest, "left packet digest"),
+        rightPacketDigest: digest(rightPacketDigest, "right packet digest"),
+      });
+    },
+    async review({ packetDigests, decision, reason } = {}) {
+      const current = await projection();
+      const actor = identity(await resolveIdentity({ tenantId }), tenantId);
+      const plan = buildEvolutionWorkbenchBatchPlan(current, {
+        packetDigests,
+        decision,
+        reason,
+        requestedBy: actor.subjectId,
+      });
+      await retainProjection(retain, current);
+      return executeBatch(plan);
+    },
+    async rollback({ fromPacketDigest, toPacketDigest, reason } = {}) {
+      const current = await projection();
+      const actor = identity(await resolveIdentity({ tenantId }), tenantId);
+      const from = current.candidates.find(
+        ({ packetDigest }) => packetDigest === fromPacketDigest,
+      );
+      if (!from || from.actualUsage.active !== true) {
+        throw new Error("Workbench rollback source is not active");
+      }
+      const active = await readActiveState({
+        tenantId,
+        skillName: current.skillName,
+      });
+      if (
+        active?.authenticated !== true ||
+        active.durable !== true ||
+        active.tenantId !== tenantId ||
+        active.skillName !== current.skillName ||
+        active.contentDigest !== from.candidateContentDigest ||
+        !DIGEST.test(active.stateDigest ?? "")
+      ) {
+        throw new Error("Workbench active state does not match the projection");
+      }
+      const plan = buildEvolutionWorkbenchRollbackPlan(current, {
+        fromPacketDigest: digest(fromPacketDigest, "from packet digest"),
+        toPacketDigest: digest(toPacketDigest, "to packet digest"),
+        expectedActiveStateDigest: active.stateDigest,
+        requestedBy: actor.subjectId,
+        reason,
+      });
+      await retainProjection(retain, current);
+      return executeRollback(plan);
+    },
+  });
+  HOSTS.add(host);
+  return host;
+}
+
+export function isEvolutionWorkbenchCliHost(value) {
+  return HOSTS.has(value);
+}