chainlesschain 0.166.16 → 0.166.18

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

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import structuredMemory from "@chainlesschain/session-core/structured-evolution-memory";
+
+const { createStructuredMemoryAuthorityReceipt } = structuredMemory;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const HOST_DIGEST = /^[a-f0-9]{64}$/u;
+const WRITERS = new WeakSet();
+
+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(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function requiredString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${name} is required`);
+  }
+  return value;
+}
+
+function requiredDigest(value, name) {
+  if (!DIGEST.test(value || "")) {
+    throw new TypeError(`${name} must be sha256-bound`);
+  }
+  return value;
+}
+
+function capture(owner, name) {
+  if (typeof owner?.[name] !== "function") {
+    throw new TypeError(`${name} port is required`);
+  }
+  return (...args) => Reflect.apply(owner[name], owner, args);
+}
+
+function normalizeDescriptor(input) {
+  if (
+    !Number.isSafeInteger(input?.issuerRevision) ||
+    input.issuerRevision < 1
+  ) {
+    throw new TypeError("issuerRevision must be a positive integer");
+  }
+  return Object.freeze({
+    tenantId: requiredString(input.tenantId, "tenantId"),
+    issuerId: requiredString(input.issuerId, "issuerId"),
+    issuerRevision: input.issuerRevision,
+    issuerHandlerDigest: requiredDigest(
+      input.issuerHandlerDigest,
+      "issuerHandlerDigest",
+    ),
+  });
+}
+
+function verifyConsumedApproval(adopted, operation) {
+  const payload = adopted?.payload;
+  if (
+    !(
+      (adopted?.adopted === true && adopted.replayed === false) ||
+      (adopted?.adopted === false && adopted.replayed === true)
+    ) ||
+    !HOST_DIGEST.test(adopted.statementDigest || "") ||
+    !HOST_DIGEST.test(adopted.receiptHash || "") ||
+    payload?.status !== "consumed" ||
+    payload.requestId !== operation.requestId ||
+    payload.fingerprint !== operation.fingerprint ||
+    payload.binding !== operation.binding
+  ) {
+    throw new Error(
+      "policy receipt requires a durably adopted consumed approval",
+    );
+  }
+  return payload;
+}
+
+export function createStructuredMemoryPolicyReceiptWriter({
+  descriptor: input,
+  authorityStore,
+  attestor,
+  clock = () => new Date().toISOString(),
+} = {}) {
+  const descriptor = normalizeDescriptor(input);
+  const retainReceipt = capture(authorityStore, "retainReceipt");
+  const attest = capture(attestor, "attest");
+  if (typeof clock !== "function")
+    throw new TypeError("clock must be a function");
+
+  const writer = Object.freeze({
+    descriptor,
+    async retainConsumedApproval({ adopted, operation } = {}) {
+      const payload = verifyConsumedApproval(adopted, operation || {});
+      const issuedAt = requiredString(clock(), "issuedAt");
+      if (!Number.isFinite(Date.parse(issuedAt))) {
+        throw new TypeError("issuedAt must be an ISO timestamp");
+      }
+      const operationCore = Object.freeze({
+        requestId: payload.requestId,
+        fingerprint: payload.fingerprint,
+        binding: payload.binding,
+        toolName: operation.toolName ?? null,
+        action: operation.action ?? null,
+        workspace: operation.workspace ?? null,
+        session: operation.session ?? null,
+        targetEnv: operation.targetEnv ?? null,
+        policyVersion: operation.policyVersion ?? null,
+      });
+      const receipt = createStructuredMemoryAuthorityReceipt({
+        tenantId: descriptor.tenantId,
+        kind: "policy",
+        decision: "accepted",
+        memoryId: `remote-approval:${payload.requestId}:${adopted.statementDigest}`,
+        layer: "policy",
+        action: "accept",
+        contentDigest: hash(canonical(operationCore)),
+        artifactRef: adopted.statementDigest,
+        evidenceRefs: [adopted.receiptHash, adopted.statementDigest].sort(),
+        issuerId: descriptor.issuerId,
+        issuerRevision: descriptor.issuerRevision,
+        issuerHandlerDigest: descriptor.issuerHandlerDigest,
+        issuedAt,
+      });
+      const attestation = await attest({
+        purpose: "structured-memory-policy-receipt",
+        payloadDigest: receipt.receiptDigest,
+        receipt,
+        operation: operationCore,
+      });
+      if (attestation === null || attestation === undefined) {
+        throw new Error("policy 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("policy receipt was not durably acknowledged");
+      }
+      return signed;
+    },
+  });
+  WRITERS.add(writer);
+  return writer;
+}
+
+export function captureStructuredMemoryPolicyReceiptWriter(value) {
+  if (!WRITERS.has(value)) {
+    throw new TypeError(
+      "a branded structured memory policy writer is required",
+    );
+  }
+  const captured = Object.freeze({
+    descriptor: value.descriptor,
+    retainConsumedApproval: capture(value, "retainConsumedApproval"),
+  });
+  WRITERS.add(captured);
+  return captured;
+}

package/src/lib/evolution/structured-memory-post-compact-hook.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import structuredMemory from "@chainlesschain/session-core/structured-evolution-memory";
+import { executeHooksV2Event } from "../hooks-v2-producers.js";
+
+const {
+  STRUCTURED_MEMORY_POST_COMPACT_VERIFICATION_SCHEMA,
+  createStructuredMemoryPostCompactVerifier,
+} = structuredMemory;
+
+const ATTESTATION_DOMAIN = "chainlesschain.structured-memory-post-compact-hook/v1\0";
+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(value) {
+  return `sha256:${createHash("sha256").update(canonical(value)).digest("hex")}`;
+}
+
+function requiredString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} is required`);
+  return value;
+}
+
+function capture(owner, name) {
+  if (typeof owner?.[name] !== "function") throw new TypeError(`${name} port is required`);
+  return (...args) => Reflect.apply(owner[name], owner, args);
+}
+
+function descriptor(input) {
+  if (!Number.isSafeInteger(input?.authorityRevision) || input.authorityRevision <= 0) {
+    throw new TypeError("authorityRevision must be a positive integer");
+  }
+  if (!DIGEST.test(input?.handlerDigest || "")) throw new TypeError("handlerDigest must be sha256-bound");
+  return Object.freeze({ tenantId: requiredString(input.tenantId, "tenantId"),
+    authorityId: requiredString(input.authorityId, "authorityId"), authorityRevision: input.authorityRevision,
+    handlerDigest: input.handlerDigest });
+}
+
+function outcomeSummary(outcome) {
+  const results = Array.isArray(outcome?.results) ? outcome.results : [];
+  return Object.freeze({ success: outcome?.success === true, blocked: outcome?.blocked === true,
+    decision: typeof outcome?.decision === "string" ? outcome.decision : null,
+    resultCount: results.length,
+    statuses: Object.freeze(results.map((result) => String(result?.status || "unknown")).sort()) });
+}
+
+function attestationMessage(result) {
+  const core = Object.fromEntries(Object.entries(result).filter(([key]) => key !== "signature"));
+  return `${ATTESTATION_DOMAIN}${canonical(core)}`;
+}
+
+export function createCliStructuredMemoryPostCompactVerifier({ descriptor: input,
+  hookExecutor = executeHooksV2Event, attestor, clock = Date.now } = {}) {
+  const identity = descriptor(input);
+  if (typeof hookExecutor !== "function") throw new TypeError("hookExecutor must be a function");
+  if (typeof clock !== "function") throw new TypeError("clock must be a function");
+  const sign = capture(attestor, "sign");
+  const verify = capture(attestor, "verify");
+  const hook = { run: async (request) => {
+    const outcome = await hookExecutor("PostCompact", { schema_version: 1, trigger: "structured-memory",
+      tenant_id: identity.tenantId, snapshot_digest: request.snapshotDigest,
+      projection_digest: request.projectionDigest, previous_snapshot_digest: request.previousSnapshotDigest,
+      candidate: request.candidate }, { failClosed: true });
+    const summary = outcomeSummary(outcome);
+    const accepted = summary.success && !summary.blocked && summary.decision !== "block" &&
+      summary.resultCount > 0 && summary.statuses.every((status) => status === "success");
+    const unsigned = { schema: STRUCTURED_MEMORY_POST_COMPACT_VERIFICATION_SCHEMA, authenticated: true,
+      ...identity, snapshotDigest: request.snapshotDigest, projectionDigest: request.projectionDigest,
+      previousSnapshotDigest: request.previousSnapshotDigest, decision: accepted ? "accepted" : "rejected",
+      checkedAt: new Date(clock()).toISOString(), hookOutcomeDigest: hash(summary) };
+    const receiptDigest = hash({ domain: ATTESTATION_DOMAIN, result: unsigned });
+    const result = { ...unsigned, receiptDigest };
+    const signature = await sign({ message: attestationMessage(result), identity, result: Object.freeze({ ...result }) });
+    return Object.freeze({ ...result, signature });
+  } };
+  return createStructuredMemoryPostCompactVerifier({ descriptor: identity, hook,
+    verifier: { verify: async ({ result }) => {
+      const expectedDigest = hash({ domain: ATTESTATION_DOMAIN,
+        result: Object.fromEntries(Object.entries(result).filter(([key]) => !["receiptDigest", "signature"].includes(key))) });
+      if (result.receiptDigest !== expectedDigest) return false;
+      return await verify({ message: attestationMessage(result), identity, result });
+    } } });
+}

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

@@ -0,0 +1,221 @@
+import { createHash } from "node:crypto";
+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";
+
+const { createStructuredMemoryAuthorityReceipt } = structuredMemory;
+const SKILL_RELEASE_RECEIPT_SCHEMA =
+  "chainlesschain.skill-release-transition-receipt/v4";
+const SKILL_PROMOTION_REVIEW_ENVELOPE_SCHEMA =
+  "chainlesschain.skill-promotion-review-envelope/v1";
+const RELEASE_RECEIPT_DOMAIN = `${SKILL_RELEASE_RECEIPT_SCHEMA}\0`;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const WRITERS = new WeakSet();
+
+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(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function requiredString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${name} is required`);
+  }
+  return value;
+}
+
+function requiredDigest(value, name) {
+  if (!DIGEST.test(value || "")) {
+    throw new TypeError(`${name} must be sha256-bound`);
+  }
+  return value;
+}
+
+function capture(owner, name) {
+  if (typeof owner?.[name] !== "function") {
+    throw new TypeError(`${name} port is required`);
+  }
+  return (...args) => Reflect.apply(owner[name], owner, args);
+}
+
+function normalizeDescriptor(input) {
+  if (
+    !Number.isSafeInteger(input?.issuerRevision) ||
+    input.issuerRevision < 1
+  ) {
+    throw new TypeError("issuerRevision must be a positive integer");
+  }
+  return Object.freeze({
+    tenantId: requiredString(input.tenantId, "tenantId"),
+    issuerId: requiredString(input.issuerId, "issuerId"),
+    issuerRevision: input.issuerRevision,
+    issuerHandlerDigest: requiredDigest(
+      input.issuerHandlerDigest,
+      "issuerHandlerDigest",
+    ),
+  });
+}
+
+function verifyPromotion(result, matrixBinding, reviewBinding, tenantId) {
+  const release = result?.release;
+  const state = result?.state;
+  const receipt = result?.receipt;
+  if (
+    receipt?.schema !== SKILL_RELEASE_RECEIPT_SCHEMA ||
+    receipt.operation !== "promote" ||
+    receipt.tenantId !== tenantId ||
+    release?.tenantId !== tenantId ||
+    state?.tenantId !== tenantId ||
+    receipt.skillName !== release.skillName ||
+    state.skillName !== release.skillName ||
+    receipt.activeReleaseDigest !== release.releaseDigest ||
+    state.activeReleaseDigest !== release.releaseDigest ||
+    !DIGEST.test(release.releaseDigest || "") ||
+    !DIGEST.test(release.contentDigest || "") ||
+    !DIGEST.test(receipt.receiptDigest || "")
+  ) {
+    throw new Error("promotion result is not a committed release transition");
+  }
+  const core = structuredClone(receipt);
+  delete core.receiptDigest;
+  if (
+    hash(`${RELEASE_RECEIPT_DOMAIN}${canonical(core)}`) !==
+    receipt.receiptDigest
+  ) {
+    throw new Error("promotion transition receipt digest is invalid");
+  }
+  const evidenceRefs = [receipt.receiptDigest];
+  if (matrixBinding !== null) {
+    const expectedEvalReceiptDigest = digestSkillMutationReceiptEnvelope(
+      buildSkillEvaluatedPromotionReceiptEnvelope({
+        schema: SKILL_TARGET_MATRIX_EVAL_RECEIPT_SCHEMA,
+        receiptDigest: matrixBinding.matrixReceiptDigest,
+      }),
+    );
+    if (
+      matrixBinding?.tenantId !== tenantId ||
+      matrixBinding.skillName !== release.skillName ||
+      matrixBinding.candidateContentDigest !== release.contentDigest ||
+      !DIGEST.test(matrixBinding.matrixReceiptDigest || "") ||
+      receipt.receiptDigests?.eval !== expectedEvalReceiptDigest
+    ) {
+      throw new Error(
+        "matrix binding does not authorize the committed release",
+      );
+    }
+    evidenceRefs.push(matrixBinding.matrixReceiptDigest);
+  }
+  if (reviewBinding !== null) {
+    const reviewEnvelope = canonical({
+      schema: SKILL_PROMOTION_REVIEW_ENVELOPE_SCHEMA,
+      receiptDigest: reviewBinding.reviewReceiptDigest,
+    });
+    const expectedPolicyReceiptDigest =
+      digestSkillMutationReceiptEnvelope(reviewEnvelope);
+    if (
+      reviewBinding?.tenantId !== tenantId ||
+      reviewBinding.skillName !== release.skillName ||
+      reviewBinding.candidateId !== release.candidateId ||
+      !DIGEST.test(reviewBinding.reviewReceiptDigest || "") ||
+      !DIGEST.test(reviewBinding.packetDigest || "") ||
+      !DIGEST.test(reviewBinding.capabilityDiffDigest || "") ||
+      !DIGEST.test(reviewBinding.candidateDiffDigest || "") ||
+      !DIGEST.test(reviewBinding.contentRiskDigest || "") ||
+      reviewBinding.matrixReceiptDigest !==
+        matrixBinding?.matrixReceiptDigest ||
+      receipt.receiptDigests?.policy !== expectedPolicyReceiptDigest
+    ) {
+      throw new Error(
+        "human review binding does not authorize the committed release",
+      );
+    }
+    evidenceRefs.push(reviewBinding.reviewReceiptDigest);
+  }
+  return { release, receipt, evidenceRefs: [...new Set(evidenceRefs)].sort() };
+}
+
+export function createStructuredMemoryPromotionReceiptWriter({
+  descriptor: input,
+  authorityStore,
+  attestor,
+  clock = () => new Date().toISOString(),
+} = {}) {
+  const descriptor = normalizeDescriptor(input);
+  const retainReceipt = capture(authorityStore, "retainReceipt");
+  const attest = capture(attestor, "attest");
+  if (typeof clock !== "function")
+    throw new TypeError("clock must be a function");
+
+  const writer = Object.freeze({
+    descriptor,
+    async retainPromotion(result, matrixBinding = null, reviewBinding = null) {
+      const verified = verifyPromotion(
+        result,
+        matrixBinding,
+        reviewBinding,
+        descriptor.tenantId,
+      );
+      const issuedAt = requiredString(clock(), "issuedAt");
+      if (!Number.isFinite(Date.parse(issuedAt))) {
+        throw new TypeError("issuedAt must be an ISO timestamp");
+      }
+      const receipt = createStructuredMemoryAuthorityReceipt({
+        tenantId: descriptor.tenantId,
+        kind: "promotion",
+        decision: "accepted",
+        memoryId: `skill-release:${verified.release.skillName}:${verified.release.releaseDigest}`,
+        layer: "procedural",
+        action: "accept",
+        contentDigest: verified.release.contentDigest,
+        artifactRef: verified.release.releaseDigest,
+        evidenceRefs: verified.evidenceRefs,
+        issuerId: descriptor.issuerId,
+        issuerRevision: descriptor.issuerRevision,
+        issuerHandlerDigest: descriptor.issuerHandlerDigest,
+        issuedAt,
+      });
+      const attestation = await attest({
+        purpose: "structured-memory-promotion-receipt",
+        payloadDigest: receipt.receiptDigest,
+        receipt,
+      });
+      if (attestation === null || attestation === undefined) {
+        throw new Error("promotion 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("promotion receipt was not durably acknowledged");
+      }
+      return signed;
+    },
+  });
+  WRITERS.add(writer);
+  return writer;
+}
+
+export function captureStructuredMemoryPromotionReceiptWriter(value) {
+  if (!WRITERS.has(value)) {
+    throw new TypeError(
+      "a branded structured memory promotion writer is required",
+    );
+  }
+  const captured = Object.freeze({
+    descriptor: value.descriptor,
+    retainPromotion: capture(value, "retainPromotion"),
+  });
+  WRITERS.add(captured);
+  return captured;
+}