chainlesschain 0.166.16 → 0.166.18

package/src/lib/evolution/structured-memory-semantic-review-pipeline.js

@@ -0,0 +1,313 @@
+import structuredMemory from "@chainlesschain/session-core/structured-evolution-memory";
+
+const { StructuredEvolutionMemory, createStructuredMemoryAuthorityReceipt } =
+  structuredMemory;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const REVIEWERS = new WeakSet();
+
+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 strings(value, name, { allowEmpty = true } = {}) {
+  if (
+    !Array.isArray(value) ||
+    (!allowEmpty && value.length === 0) ||
+    value.length > 256 ||
+    value.some((item) => typeof item !== "string" || item.trim() === "")
+  ) {
+    throw new TypeError(`${name} must be a bounded string list`);
+  }
+  return [...new Set(value)].sort();
+}
+
+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 (!["critic", "evaluator"].includes(input?.kind)) {
+    throw new TypeError("semantic reviewer kind is invalid");
+  }
+  for (const field of ["issuerRevision", "verifierRevision"]) {
+    if (!Number.isSafeInteger(input[field]) || input[field] < 1) {
+      throw new TypeError(`${field} must be a positive integer`);
+    }
+  }
+  const value = Object.freeze({
+    tenantId: requiredString(input.tenantId, "tenantId"),
+    kind: input.kind,
+    issuerId: requiredString(input.issuerId, "issuerId"),
+    issuerRevision: input.issuerRevision,
+    issuerHandlerDigest: requiredDigest(
+      input.issuerHandlerDigest,
+      "issuerHandlerDigest",
+    ),
+    verifierId: requiredString(input.verifierId, "verifierId"),
+    verifierRevision: input.verifierRevision,
+    verifierHandlerDigest: requiredDigest(
+      input.verifierHandlerDigest,
+      "verifierHandlerDigest",
+    ),
+  });
+  if (
+    value.issuerId === value.verifierId ||
+    value.issuerHandlerDigest === value.verifierHandlerDigest
+  ) {
+    throw new Error(
+      "semantic review producer and verifier must be independent",
+    );
+  }
+  return value;
+}
+
+function normalizeRequest(input, tenantId) {
+  return Object.freeze({
+    tenantId,
+    memoryId: requiredString(input?.memoryId, "memoryId"),
+    layer:
+      input?.layer === "semantic"
+        ? "semantic"
+        : (() => {
+            throw new TypeError("semantic layer is required");
+          })(),
+    action:
+      input?.action === "accept"
+        ? "accept"
+        : (() => {
+            throw new TypeError("semantic accept action is required");
+          })(),
+    contentDigest: requiredDigest(input?.contentDigest, "contentDigest"),
+    artifactRef: requiredString(input?.artifactRef, "artifactRef"),
+    evidenceRefs: strings(input?.evidenceRefs, "evidenceRefs", {
+      allowEmpty: false,
+    }),
+  });
+}
+
+export function createStructuredMemorySemanticReviewer({
+  descriptor: input,
+  producer,
+  attestor,
+  verifier,
+  clock = () => new Date().toISOString(),
+} = {}) {
+  const identity = descriptor(input);
+  const review = capture(producer, "review");
+  const attest = capture(attestor, "attest");
+  const verify = capture(verifier, "verify");
+  if (typeof clock !== "function")
+    throw new TypeError("clock must be a function");
+  const reviewer = Object.freeze({
+    identity,
+    async issue(requestInput) {
+      const request = normalizeRequest(requestInput, identity.tenantId);
+      const outcome = await review(request);
+      if (!outcome || !["accepted", "rejected"].includes(outcome.decision)) {
+        throw new Error(`${identity.kind} returned an invalid review decision`);
+      }
+      const reasonCodes = strings(outcome.reasonCodes || [], "reasonCodes");
+      if (outcome.decision !== "accepted") {
+        return Object.freeze({
+          accepted: false,
+          kind: identity.kind,
+          reasonCodes,
+        });
+      }
+      const issuedAt = requiredString(clock(), "issuedAt");
+      if (!Number.isFinite(Date.parse(issuedAt))) {
+        throw new TypeError("issuedAt must be an ISO timestamp");
+      }
+      const receipt = createStructuredMemoryAuthorityReceipt({
+        ...request,
+        kind: identity.kind,
+        decision: "accepted",
+        issuerId: identity.issuerId,
+        issuerRevision: identity.issuerRevision,
+        issuerHandlerDigest: identity.issuerHandlerDigest,
+        issuedAt,
+      });
+      const attestation = await attest({
+        purpose: `structured-memory-${identity.kind}-receipt`,
+        payloadDigest: receipt.receiptDigest,
+        receipt,
+        reasonCodes,
+      });
+      if (attestation === null || attestation === undefined) {
+        throw new Error(`${identity.kind} attestor returned no attestation`);
+      }
+      const signed = Object.freeze({ ...receipt, attestation });
+      if (
+        (await verify({
+          descriptor: identity,
+          request,
+          receipt: signed,
+          reasonCodes,
+        })) !== true
+      ) {
+        throw new Error(`${identity.kind} receipt authentication failed`);
+      }
+      return Object.freeze({
+        accepted: true,
+        kind: identity.kind,
+        reasonCodes,
+        receipt: signed,
+      });
+    },
+  });
+  REVIEWERS.add(reviewer);
+  return reviewer;
+}
+
+function captureReviewer(value, kind, tenantId) {
+  if (
+    !REVIEWERS.has(value) ||
+    value.identity.kind !== kind ||
+    value.identity.tenantId !== tenantId
+  ) {
+    throw new TypeError(`a branded tenant-scoped ${kind} reviewer is required`);
+  }
+  return Object.freeze({
+    identity: value.identity,
+    issue: capture(value, "issue"),
+  });
+}
+
+export function createStructuredMemorySemanticReviewPipeline({
+  tenantId: tenantIdInput,
+  memory,
+  authorityStore,
+  critic,
+  evaluator,
+  proposerAuthority,
+  governorAuthority,
+} = {}) {
+  const tenantId = requiredString(tenantIdInput, "tenantId");
+  if (
+    !(memory instanceof StructuredEvolutionMemory) ||
+    memory.tenantId !== tenantId
+  ) {
+    throw new TypeError(
+      "a tenant-scoped StructuredEvolutionMemory is required",
+    );
+  }
+  const retainReceipt = capture(authorityStore, "retainReceipt");
+  const reviewers = Object.freeze({
+    critic: captureReviewer(critic, "critic", tenantId),
+    evaluator: captureReviewer(evaluator, "evaluator", tenantId),
+  });
+  const authorityIds = [
+    reviewers.critic.identity.issuerId,
+    reviewers.critic.identity.verifierId,
+    reviewers.evaluator.identity.issuerId,
+    reviewers.evaluator.identity.verifierId,
+  ];
+  const handlerDigests = [
+    reviewers.critic.identity.issuerHandlerDigest,
+    reviewers.critic.identity.verifierHandlerDigest,
+    reviewers.evaluator.identity.issuerHandlerDigest,
+    reviewers.evaluator.identity.verifierHandlerDigest,
+  ];
+  if (
+    new Set(authorityIds).size !== authorityIds.length ||
+    new Set(handlerDigests).size !== handlerDigests.length
+  ) {
+    throw new Error("critic and evaluator authorities must be independent");
+  }
+
+  return Object.freeze({
+    tenantId,
+    async propose(input = {}) {
+      return memory.append({
+        eventId: requiredString(input.eventId, "eventId"),
+        memoryId: requiredString(input.memoryId, "memoryId"),
+        layer: "semantic",
+        action: "propose",
+        authority: proposerAuthority,
+        automatic: input.automatic !== false,
+        contentDigest: requiredDigest(input.contentDigest, "contentDigest"),
+        artifactRef: requiredString(input.artifactRef, "artifactRef"),
+        evidenceRefs: strings(input.evidenceRefs, "evidenceRefs", {
+          allowEmpty: false,
+        }),
+        supersedes: strings(input.supersedes || [], "supersedes"),
+        timestamp: requiredString(input.timestamp, "timestamp"),
+        metadata: input.metadata || {},
+      });
+    },
+    async reviewAndAccept({
+      memoryId,
+      eventId,
+      timestamp,
+      metadata = {},
+    } = {}) {
+      const proposed =
+        memory.projection().memories[requiredString(memoryId, "memoryId")];
+      if (
+        !proposed ||
+        proposed.layer !== "semantic" ||
+        proposed.status !== "proposed"
+      ) {
+        throw new Error("semantic memory is not awaiting review");
+      }
+      const request = {
+        tenantId,
+        memoryId: proposed.memoryId,
+        layer: "semantic",
+        action: "accept",
+        contentDigest: proposed.contentDigest,
+        artifactRef: proposed.artifactRef,
+        evidenceRefs: proposed.evidenceRefs,
+      };
+      const [criticResult, evaluatorResult] = await Promise.all([
+        reviewers.critic.issue(request),
+        reviewers.evaluator.issue(request),
+      ]);
+      if (!criticResult.accepted || !evaluatorResult.accepted) {
+        throw new Error("semantic memory was rejected by independent review");
+      }
+      for (const result of [criticResult, evaluatorResult]) {
+        const retained = await retainReceipt(result.receipt);
+        if (
+          retained?.persisted !== true ||
+          retained.receiptDigest !== result.receipt.receiptDigest
+        ) {
+          throw new Error(
+            `${result.kind} receipt was not durably acknowledged`,
+          );
+        }
+      }
+      return memory.append({
+        eventId: requiredString(eventId, "eventId"),
+        memoryId: proposed.memoryId,
+        layer: "semantic",
+        action: "accept",
+        authority: governorAuthority,
+        automatic: false,
+        contentDigest: proposed.contentDigest,
+        artifactRef: proposed.artifactRef,
+        evidenceRefs: proposed.evidenceRefs,
+        supersedes: proposed.supersedes,
+        receiptRefs: {
+          critic: criticResult.receipt.receiptDigest,
+          evaluator: evaluatorResult.receipt.receiptDigest,
+        },
+        timestamp: requiredString(timestamp, "timestamp"),
+        metadata,
+      });
+    },
+  });
+}

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

@@ -0,0 +1,343 @@
+import { createHash } from "node:crypto";
+
+export const WIKI_SKILL_PROPOSAL_SCHEMA =
+  "chainlesschain.wiki-informed-skill-proposal/v1";
+export const WIKI_PROPOSAL_STATUS = Object.freeze({
+  PROPOSAL: "proposal",
+  NO_PROPOSAL: "no-proposal",
+  NEEDS_EVIDENCE: "needs-evidence",
+});
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const SKILL_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const INITIAL_SOURCES = Object.freeze([
+  "wiki-index",
+  "skill-impact",
+  "active-skill",
+  "training-summary",
+]);
+const SELECTIVE_SOURCES = new Set(["pattern", "raw"]);
+const SAFE_DIFF_ROOTS = new Set([
+  "SKILL.md",
+  "PURPOSE.md",
+  "assets",
+  "references",
+  "scripts",
+]);
+
+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 deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+function requiredString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${name} is required`);
+  }
+  return value;
+}
+
+function stringList(value, name, { allowEmpty = false, max = 64 } = {}) {
+  if (
+    !Array.isArray(value) ||
+    (!allowEmpty && value.length === 0) ||
+    value.length > max ||
+    value.some((item) => typeof item !== "string" || item.trim() === "") ||
+    new Set(value).size !== value.length
+  ) {
+    throw new TypeError(`${name} must be a bounded unique string list`);
+  }
+  return [...value];
+}
+
+function verifyEnvelope(value, expectedKind) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    value.kind !== expectedKind ||
+    value.trusted !== true ||
+    typeof value.ref !== "string" ||
+    !DIGEST.test(value.digest ?? "") ||
+    value.digest !== hash(value.data)
+  ) {
+    const error = new Error(`${expectedKind} evidence is not digest-bound and trusted`);
+    error.code = "WIKI_PROPOSAL_UNTRUSTED_EVIDENCE";
+    throw error;
+  }
+  return deepFreeze({
+    kind: value.kind,
+    ref: value.ref,
+    digest: value.digest,
+    data: structuredClone(value.data),
+  });
+}
+
+function normalizeDescriptor(input) {
+  const descriptor = {
+    tenantId: requiredString(input?.tenantId, "tenantId"),
+    evolutionRunId: requiredString(input?.evolutionRunId, "evolutionRunId"),
+    targetSkillName: requiredString(input?.targetSkillName, "targetSkillName"),
+    wikiRevision: requiredString(input?.wikiRevision, "wikiRevision"),
+    proposerModel: requiredString(input?.proposerModel, "proposerModel"),
+    minEvidenceSamples: Math.max(1, Number(input?.minEvidenceSamples) || 1),
+    maxSelectiveEvidence: Math.min(
+      16,
+      Math.max(0, Number(input?.maxSelectiveEvidence) || 4),
+    ),
+  };
+  if (!SKILL_NAME.test(descriptor.targetSkillName)) {
+    throw new TypeError("targetSkillName must be canonical kebab-case");
+  }
+  return deepFreeze(descriptor);
+}
+
+function validateDiff(diff) {
+  if (!Array.isArray(diff) || diff.length === 0 || diff.length > 128) {
+    throw new TypeError("machineDiff must contain 1..128 operations");
+  }
+  return diff.map((entry) => {
+    if (!entry || !["add", "replace", "remove"].includes(entry.op)) {
+      throw new TypeError("machineDiff operation is invalid");
+    }
+    const path = requiredString(entry.path, "machineDiff.path").replaceAll("\\", "/");
+    const parts = path.split("/");
+    if (
+      path.startsWith("/") ||
+      parts.includes("..") ||
+      !SAFE_DIFF_ROOTS.has(parts[0]) ||
+      /(^|\/)(active|\.chainlesschain)(\/|$)/u.test(path)
+    ) {
+      const error = new Error("machineDiff escaped the single candidate Skill");
+      error.code = "WIKI_PROPOSAL_UNSAFE_DIFF";
+      throw error;
+    }
+    return {
+      op: entry.op,
+      path,
+      beforeDigest: entry.beforeDigest ?? null,
+      afterDigest: entry.afterDigest ?? null,
+    };
+  });
+}
+
+function validateProposal(output, descriptor, evidence) {
+  if (output?.status !== WIKI_PROPOSAL_STATUS.PROPOSAL) {
+    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");
+    error.code = "WIKI_PROPOSAL_MULTI_SKILL";
+    throw error;
+  }
+  const knownRefs = new Set(evidence.map((item) => item.ref));
+  const purpose = {
+    summary: requiredString(output.purpose?.summary, "purpose.summary"),
+    patternRefs: stringList(output.purpose?.patternRefs, "purpose.patternRefs"),
+    sourceEvidenceRefs: stringList(
+      output.purpose?.sourceEvidenceRefs,
+      "purpose.sourceEvidenceRefs",
+    ),
+  };
+  for (const ref of [...purpose.patternRefs, ...purpose.sourceEvidenceRefs]) {
+    if (!knownRefs.has(ref)) {
+      const error = new Error("PURPOSE references evidence outside the resolved set");
+      error.code = "WIKI_PROPOSAL_UNKNOWN_LINEAGE";
+      throw error;
+    }
+  }
+  const contextCost = {
+    maxTokens: Number(output.contextCost?.maxTokens),
+    maxBytes: Number(output.contextCost?.maxBytes),
+  };
+  if (
+    !Number.isInteger(contextCost.maxTokens) ||
+    contextCost.maxTokens <= 0 ||
+    !Number.isInteger(contextCost.maxBytes) ||
+    contextCost.maxBytes <= 0
+  ) {
+    throw new TypeError("contextCost must provide positive maxTokens/maxBytes");
+  }
+  return deepFreeze({
+    schema: WIKI_SKILL_PROPOSAL_SCHEMA,
+    status: WIKI_PROPOSAL_STATUS.PROPOSAL,
+    tenantId: descriptor.tenantId,
+    evolutionRunId: descriptor.evolutionRunId,
+    skillName: descriptor.targetSkillName,
+    purpose,
+    applicableWhen: stringList(output.applicableWhen, "applicableWhen"),
+    notApplicableWhen: stringList(output.notApplicableWhen, "notApplicableWhen"),
+    failureCounterexamples: stringList(
+      output.failureCounterexamples,
+      "failureCounterexamples",
+    ),
+    rollbackSteps: stringList(output.rollbackSteps, "rollbackSteps"),
+    validationMethods: stringList(output.validationMethods, "validationMethods"),
+    requestedCapabilities: stringList(
+      output.requestedCapabilities,
+      "requestedCapabilities",
+      { allowEmpty: true },
+    ),
+    targetRuntimes: stringList(output.targetRuntimes, "targetRuntimes"),
+    contextCost,
+    machineDiff: validateDiff(output.machineDiff),
+    sourceEvidenceRefs: evidence.map(({ ref, digest }) => ({ ref, digest })),
+    wikiRevision: descriptor.wikiRevision,
+    proposerModel: descriptor.proposerModel,
+  });
+}
+
+function abstention(status, reason, evidence = []) {
+  return deepFreeze({
+    schema: WIKI_SKILL_PROPOSAL_SCHEMA,
+    status,
+    reason,
+    sourceEvidenceRefs: evidence.map(({ ref, digest }) => ({ ref, digest })),
+  });
+}
+
+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 (typeof ports?.readInitial !== "function")
+      throw new TypeError("readInitial port is required");
+    if (typeof ports?.readSelective !== "function")
+      throw new TypeError("readSelective port is required");
+    if (typeof ports?.generate !== "function")
+      throw new TypeError("generate port is required");
+    if (typeof ports?.createCandidate !== "function")
+      throw new TypeError("createCandidate port is required");
+    this._ports = ports;
+    Object.freeze(this);
+  }
+
+  async propose() {
+    const initial = [];
+    for (const kind of INITIAL_SOURCES) {
+      initial.push(verifyEnvelope(await this._ports.readInitial(kind), kind));
+    }
+    const wiki = initial.find((item) => item.kind === "wiki-index");
+    const training = initial.find((item) => item.kind === "training-summary");
+    if ((wiki.data?.contradictionRefs?.length ?? 0) > 0) {
+      return abstention(
+        WIKI_PROPOSAL_STATUS.NEEDS_EVIDENCE,
+        "wiki evidence is contradictory",
+        initial,
+      );
+    }
+    if (Number(training.data?.sampleCount) < this.descriptor.minEvidenceSamples) {
+      return abstention(
+        WIKI_PROPOSAL_STATUS.NEEDS_EVIDENCE,
+        "training evidence sample is insufficient",
+        initial,
+      );
+    }
+
+    let evidence = [...initial];
+    let output = await this._ports.generate({
+      descriptor: this.descriptor,
+      evidence: deepFreeze([...evidence]),
+    });
+    if (output?.status === WIKI_PROPOSAL_STATUS.NO_PROPOSAL) {
+      return abstention(output.status, requiredString(output.reason, "reason"), evidence);
+    }
+    if (output?.status === WIKI_PROPOSAL_STATUS.NEEDS_EVIDENCE) {
+      const requests = output.requests;
+      if (
+        !Array.isArray(requests) ||
+        requests.length === 0 ||
+        requests.length > this.descriptor.maxSelectiveEvidence
+      ) {
+        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);
+        }
+        evidence.push(
+          verifyEnvelope(
+            await this._ports.readSelective(request.kind, request.ref),
+            request.kind,
+          ),
+        );
+      }
+      output = await this._ports.generate({
+        descriptor: this.descriptor,
+        evidence: deepFreeze([...evidence]),
+      });
+      if (output?.status !== WIKI_PROPOSAL_STATUS.PROPOSAL) {
+        return abstention(
+          output?.status === WIKI_PROPOSAL_STATUS.NO_PROPOSAL
+            ? output.status
+            : WIKI_PROPOSAL_STATUS.NEEDS_EVIDENCE,
+          requiredString(output?.reason, "reason"),
+          evidence,
+        );
+      }
+    }
+
+    const proposal = validateProposal(output, this.descriptor, evidence);
+    const proposalDigest = hash(proposal);
+    const candidateInput = deepFreeze({
+      tenantId: proposal.tenantId,
+      skillName: proposal.skillName,
+      derivationMode: "wiki",
+      wikiRevision: proposal.wikiRevision,
+      proposerModel: proposal.proposerModel,
+      requestedCapabilities: proposal.requestedCapabilities,
+      sourceEvidenceRefs: proposal.sourceEvidenceRefs,
+      content: canonical(proposal),
+    });
+    const created = await this._ports.createCandidate(candidateInput);
+    const candidate = created?.candidate;
+    if (
+      typeof candidate?.candidateId !== "string" ||
+      typeof candidate?.contentDigest !== "string" ||
+      candidate.skillName !== proposal.skillName ||
+      candidate.content !== candidateInput.content ||
+      candidate.derivationMode !== "wiki" ||
+      candidate.wikiRevision !== proposal.wikiRevision ||
+      candidate.proposerModel !== proposal.proposerModel ||
+      canonical(candidate.requestedCapabilities) !==
+        canonical(proposal.requestedCapabilities) ||
+      canonical(candidate.targetRuntimes) !== canonical(proposal.targetRuntimes) ||
+      canonical(candidate.sourceEvidenceRefs) !==
+        canonical(proposal.sourceEvidenceRefs)
+    ) {
+      const error = new Error(
+        "candidate sink did not return an exact immutable proposal binding",
+      );
+      error.code = "WIKI_PROPOSAL_CANDIDATE_UNCONFIRMED";
+      throw error;
+    }
+    return deepFreeze({
+      status: WIKI_PROPOSAL_STATUS.PROPOSAL,
+      proposal,
+      proposalDigest,
+      candidateId: candidate.candidateId,
+      contentDigest: candidate.contentDigest,
+    });
+  }
+}
+
+export function createWikiInformedSkillProposer(options) {
+  return new WikiInformedSkillProposer(options);
+}