chainlesschain 0.166.17 → 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-maintainer-ledger-adapter.js

@@ -0,0 +1,200 @@
+import {
+  EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA,
+  isEvolutionLedgerArtifactResolver,
+} from "./evolution-artifact-ports.js";
+import {
+  EVOLUTION_ARTIFACT_RESOLUTION_SCHEMA,
+  EVOLUTION_LEDGER_DOMAIN_EVENT_SCHEMA,
+} from "./evolution-ledger.js";
+import {
+  WIKI_REVISION_SCHEMA,
+  WIKI_STATE_SCHEMA,
+  createEmptyWikiState,
+  digestWikiState,
+} from "./evidence-backed-wiki-maintainer.js";
+
+export const WIKI_LEDGER_EVENT_TYPE = "wiki.revision.committed";
+export const WIKI_LEDGER_CONFLICT_CODE = "CC_EVOLUTION_WIKI_REVISION_CONFLICT";
+export const WIKI_LEDGER_CORRUPT_CODE = "CC_EVOLUTION_WIKI_LEDGER_CORRUPT";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const REVISION_ID = /^wiki:[a-f0-9]{64}$/u;
+
+function requiredString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} is required`);
+  return value;
+}
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+function captureMethod(owner, name, label) {
+  const method = owner?.[name];
+  if (typeof method !== "function") throw new TypeError(`${label}.${name} is required`);
+  return (...args) => Reflect.apply(method, owner, args);
+}
+
+function parseRecord(resolution, descriptor) {
+  if (resolution?.schema !== EVOLUTION_ARTIFACT_RESOLUTION_SCHEMA || resolution.authenticated !== true ||
+      resolution.found !== true || !DIGEST.test(resolution.digest ?? "") ||
+      !DIGEST.test(resolution.receiptDigest ?? "") || !Buffer.isBuffer(resolution.bytes)) {
+    fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki artifact resolution is not authenticated and complete");
+  }
+  let record;
+  try {
+    record = JSON.parse(resolution.bytes.toString("utf8"));
+  } catch {
+    fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki artifact is not canonical JSON");
+  }
+  const revision = record?.value;
+  if (record?.schema !== EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA || record.tenantId !== descriptor.artifactTenantId ||
+      record.audience !== descriptor.audience || record.purpose !== descriptor.purpose || record.retention !== "ledger" ||
+      record.type !== "wiki-revision" || revision?.schema !== WIKI_REVISION_SCHEMA ||
+      revision.tenantId !== descriptor.tenantId || revision.evolutionRunId !== descriptor.evolutionRunId ||
+      revision.state?.schema !== WIKI_STATE_SCHEMA || revision.state.tenantId !== descriptor.tenantId ||
+      revision.stateDigest !== digestWikiState(revision.state) || revision.state.revisionId !== revision.revisionId ||
+      !REVISION_ID.test(revision.revisionId ?? "")) {
+    fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki artifact record or revision binding is invalid");
+  }
+  return revision;
+}
+
+function normalizeDescriptor(input) {
+  return Object.freeze({
+    tenantId: requiredString(input?.tenantId, "tenantId"),
+    artifactTenantId: requiredString(input?.artifactTenantId, "artifactTenantId"),
+    evolutionRunId: requiredString(input?.evolutionRunId, "evolutionRunId"),
+    audience: requiredString(input?.audience, "audience"),
+    purpose: requiredString(input?.purpose, "purpose"),
+  });
+}
+
+export class WikiMaintainerLedgerAdapter {
+  constructor({ descriptor, artifactPorts, ledger, ledgerArtifactResolver } = {}) {
+    this.descriptor = normalizeDescriptor(descriptor);
+    this._putCanonical = captureMethod(artifactPorts, "putCanonical", "artifactPorts");
+    this._readLedger = captureMethod(ledger, "read", "ledger");
+    this._verifyLedger = captureMethod(ledger, "verify", "ledger");
+    this._appendDomainEvent = captureMethod(ledger, "appendDomainEvent", "ledger");
+    if (!isEvolutionLedgerArtifactResolver(ledgerArtifactResolver)) {
+      throw new TypeError("a branded EvolutionArtifactPorts ledger resolver is required");
+    }
+    this._resolveArtifact = ledgerArtifactResolver;
+    Object.freeze(this);
+  }
+
+  _matchingEvents() {
+    const events = this._readLedger();
+    if (!Array.isArray(events)) fail(WIKI_LEDGER_CORRUPT_CODE, "EvolutionLedger read did not return events");
+    return events.filter((event) => event.schema === EVOLUTION_LEDGER_DOMAIN_EVENT_SCHEMA &&
+      event.type === WIKI_LEDGER_EVENT_TYPE && event.tenantId === this.descriptor.tenantId &&
+      event.correlationId === this.descriptor.evolutionRunId);
+  }
+
+  _resolveEvent(event) {
+    const authority = this._verifyLedger();
+    const resolution = this._resolveArtifact({
+      epoch: authority.epoch,
+      ledgerId: authority.ledgerId,
+      ref: event.subjectRef,
+      tenantId: this.descriptor.artifactTenantId,
+    });
+    if (resolution?.ref !== event.subjectRef.ref || resolution.digest !== event.subjectRef.digest) {
+      fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki ledger event resolved a substituted artifact");
+    }
+    return parseRecord(resolution, this.descriptor);
+  }
+
+  _latest() {
+    const matches = this._matchingEvents();
+    if (matches.length === 0) return null;
+    for (let index = 1; index < matches.length; index += 1) {
+      if (matches[index].sequence <= matches[index - 1].sequence) {
+        fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki ledger revisions are not strictly ordered");
+      }
+    }
+    const event = matches.at(-1);
+    const revision = this._resolveEvent(event);
+    if (revision.revision !== matches.length) {
+      fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki revision sequence has a gap or duplicate");
+    }
+    return { event, revision };
+  }
+
+  loadWiki = () => {
+    const latest = this._latest();
+    const state = latest?.revision.state ?? createEmptyWikiState(this.descriptor.tenantId);
+    return Object.freeze({ trusted: true, state, stateDigest: digestWikiState(state) });
+  };
+
+  commitRevision = ({ expectedStateDigest, revision } = {}) => {
+    if (!DIGEST.test(expectedStateDigest ?? "") || revision?.schema !== WIKI_REVISION_SCHEMA ||
+        revision.tenantId !== this.descriptor.tenantId || revision.evolutionRunId !== this.descriptor.evolutionRunId ||
+        revision.stateDigest !== digestWikiState(revision.state) || revision.state.revisionId !== revision.revisionId ||
+        !REVISION_ID.test(revision.revisionId ?? "")) {
+      throw new TypeError("Wiki revision commit request is invalid");
+    }
+    const latest = this._latest();
+    const currentState = latest?.revision.state ?? createEmptyWikiState(this.descriptor.tenantId);
+    const currentDigest = digestWikiState(currentState);
+    if (currentDigest !== expectedStateDigest) {
+      if (latest?.revision.revisionId === revision.revisionId && currentDigest === revision.stateDigest) {
+        return Object.freeze({ committed: true, recovered: true, revisionId: revision.revisionId,
+          stateDigest: revision.stateDigest, evolutionRunId: this.descriptor.evolutionRunId });
+      }
+      fail(WIKI_LEDGER_CONFLICT_CODE, "Wiki state changed before revision commit");
+    }
+    if (revision.revision !== currentState.revision + 1 || revision.priorStateDigest !== currentDigest) {
+      fail(WIKI_LEDGER_CONFLICT_CODE, "Wiki revision does not extend the current state");
+    }
+    const head = this._verifyLedger();
+    const published = this._putCanonical("wiki-revision", revision, {
+      audience: this.descriptor.audience,
+      purpose: this.descriptor.purpose,
+      retention: "ledger",
+    });
+    if (!published?.ref || published.receipt?.persisted !== true || published.receipt?.readbackVerified !== true ||
+        published.receipt?.integrityVerified !== true || published.receipt?.retention !== "ledger") {
+      fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki revision artifact was not durably read back");
+    }
+    const eventId = `wiki.revision.${revision.revisionId.slice("wiki:".length)}`;
+    const receipt = this._appendDomainEvent({
+      artifactTenantId: this.descriptor.artifactTenantId,
+      correlationId: this.descriptor.evolutionRunId,
+      decision: "committed",
+      eventId,
+      reason: `wiki revision ${revision.revision} committed`,
+      skillName: null,
+      sourceRefs: latest ? [latest.event.subjectRef] : [],
+      subjectRef: published.ref,
+      tenantId: this.descriptor.tenantId,
+      timestamp: revision.effectiveAt,
+      type: WIKI_LEDGER_EVENT_TYPE,
+    }, { expectedHeadDigest: head.headDigest, expectedSequence: head.sequence });
+    if (receipt?.authenticated !== true || receipt?.committed !== true || receipt?.durable !== true ||
+        receipt.eventId !== eventId || !DIGEST.test(receipt.receiptDigest ?? "")) {
+      fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki ledger did not confirm a durable authenticated append");
+    }
+    const stored = this._latest();
+    if (stored?.revision.revisionId !== revision.revisionId || stored.revision.stateDigest !== revision.stateDigest) {
+      fail(WIKI_LEDGER_CORRUPT_CODE, "Wiki revision readback differs after ledger commit");
+    }
+    return Object.freeze({ committed: true, recovered: false, revisionId: revision.revisionId,
+      stateDigest: revision.stateDigest, evolutionRunId: this.descriptor.evolutionRunId,
+      ledgerReceiptDigest: receipt.receiptDigest });
+  };
+
+  maintainerPorts({ resolveEvidence, derive } = {}) {
+    if (typeof resolveEvidence !== "function" || typeof derive !== "function") {
+      throw new TypeError("resolveEvidence and derive ports are required");
+    }
+    return Object.freeze({ loadWiki: this.loadWiki, commitRevision: this.commitRevision, resolveEvidence, derive });
+  }
+}
+
+export function createWikiMaintainerLedgerAdapter(options) {
+  return new WikiMaintainerLedgerAdapter(options);
+}