chainlesschain 0.166.22 → 0.166.25

package/src/lib/evolution/wiki-revision-protocol.js

@@ -0,0 +1,120 @@
+import {
+  WIKI_REVISION_SCHEMA,
+  WIKI_STATE_SCHEMA,
+  digestWikiState,
+} from "./evidence-backed-wiki-maintainer.js";
+
+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 fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+// Same canonical digest as the Maintainer, including legacy revisions whose
+// payload predates maintenanceRequestId/maintenanceRequestDigest.
+export function verifyWikiRevision(revision, descriptor) {
+  const { state, stateDigest, revisionId, ...payload } = revision ?? {};
+  const fields = [
+    "schema",
+    "tenantId",
+    "evolutionRunId",
+    "revision",
+    "priorStateDigest",
+    "rulesDigest",
+    "maintainerModel",
+    "effectiveAt",
+    "evidenceRefs",
+    "operationDigest",
+  ];
+  const hasRequest = Object.hasOwn(payload, "maintenanceRequestId");
+  if (hasRequest)
+    fields.push("maintenanceRequestId", "maintenanceRequestDigest");
+  if (
+    Object.keys(payload).length !== fields.length ||
+    fields.some((key) => !Object.hasOwn(payload, key)) ||
+    payload.schema !== WIKI_REVISION_SCHEMA ||
+    payload.tenantId !== descriptor.tenantId ||
+    payload.evolutionRunId !== descriptor.evolutionRunId ||
+    !Number.isSafeInteger(payload.revision) ||
+    payload.revision < 1 ||
+    !DIGEST.test(payload.priorStateDigest ?? "") ||
+    !DIGEST.test(payload.rulesDigest ?? "") ||
+    !DIGEST.test(payload.operationDigest ?? "") ||
+    typeof payload.maintainerModel !== "string" ||
+    !payload.maintainerModel.trim() ||
+    typeof payload.effectiveAt !== "string" ||
+    !Number.isFinite(Date.parse(payload.effectiveAt)) ||
+    !Array.isArray(payload.evidenceRefs) ||
+    payload.evidenceRefs.length === 0 ||
+    payload.evidenceRefs.length > 256 ||
+    payload.evidenceRefs.some(
+      (ref) => typeof ref !== "string" || !ref.trim(),
+    ) ||
+    digestWikiState(payload.evidenceRefs) !==
+      digestWikiState([...new Set(payload.evidenceRefs)].sort()) ||
+    !REVISION_ID.test(revisionId ?? "") ||
+    revisionId !== `wiki:${digestWikiState(payload).slice(7)}` ||
+    state?.schema !== WIKI_STATE_SCHEMA ||
+    state.tenantId !== descriptor.tenantId ||
+    state.revision !== payload.revision ||
+    state.revisionId !== revisionId ||
+    stateDigest !== digestWikiState(state)
+  ) {
+    fail(
+      WIKI_LEDGER_CORRUPT_CODE,
+      "Wiki revision identity or state binding is invalid",
+    );
+  }
+  if (
+    hasRequest &&
+    !(
+      payload.maintenanceRequestId === null &&
+      payload.maintenanceRequestDigest === null
+    ) &&
+    (!DIGEST.test(payload.maintenanceRequestDigest ?? "") ||
+      payload.maintenanceRequestId !==
+        `wiki-maintenance:${payload.maintenanceRequestDigest.slice(7)}`)
+  ) {
+    fail(
+      WIKI_LEDGER_CORRUPT_CODE,
+      "Wiki maintenance request binding is invalid",
+    );
+  }
+  return revision;
+}
+
+export function verifyWikiRequestTransition(previousState, revision) {
+  const requests = revision.state.maintenanceRequests ?? {};
+  const previous = previousState.maintenanceRequests ?? {};
+  const requestId = revision.maintenanceRequestId ?? null;
+  if (
+    !requests ||
+    typeof requests !== "object" ||
+    Array.isArray(requests) ||
+    (requestId && Object.hasOwn(previous, requestId))
+  ) {
+    fail(
+      WIKI_LEDGER_CORRUPT_CODE,
+      "Wiki maintenance request is duplicated or invalid",
+    );
+  }
+  const expected = { ...previous };
+  if (requestId)
+    expected[requestId] = {
+      requestDigest: revision.maintenanceRequestDigest,
+      evidenceRefs: revision.evidenceRefs,
+      effectiveAt: revision.effectiveAt,
+      operationDigest: revision.operationDigest,
+      revision: revision.revision,
+      revisionId: revision.revisionId,
+    };
+  if (digestWikiState(requests) !== digestWikiState(expected)) {
+    fail(
+      WIKI_LEDGER_CORRUPT_CODE,
+      "Wiki maintenance request history was substituted",
+    );
+  }
+}

package/src/lib/evolution/wiki-skill-proposal-ledger-adapter.js

@@ -0,0 +1,307 @@
+import { createHash } from "node:crypto";
+
+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_PROPOSAL_STATUS,
+  WIKI_SKILL_PROPOSAL_SCHEMA,
+  computeWikiSkillProposalDigest,
+} from "./wiki-informed-skill-proposer.js";
+
+export const WIKI_SKILL_PROPOSAL_RECORD_SCHEMA =
+  "chainlesschain.wiki-skill-proposal-record/v1";
+export const WIKI_SKILL_PROPOSAL_LEDGER_EVENT =
+  "evolution.wiki-skill-proposal.committed";
+export const WIKI_SKILL_PROPOSAL_CONFLICT_CODE =
+  "CC_EVOLUTION_WIKI_SKILL_PROPOSAL_CONFLICT";
+export const WIKI_SKILL_PROPOSAL_CORRUPT_CODE =
+  "CC_EVOLUTION_WIKI_SKILL_PROPOSAL_CORRUPT";
+
+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(WIKI_SKILL_PROPOSAL_RECORD_SCHEMA)
+    .update("\0")
+    .update(canonical(value))
+    .digest("hex")}`;
+}
+
+function text(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 fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+function capture(owner, method, name) {
+  if (!owner || typeof owner[method] !== "function")
+    throw new TypeError(`${name}.${method}() is required`);
+  return (...args) => Reflect.apply(owner[method], owner, args);
+}
+
+function normalizeDescriptor(input) {
+  const descriptor = Object.freeze({
+    tenantId: text(input?.tenantId, "tenantId"),
+    artifactTenantId: text(input?.artifactTenantId, "artifactTenantId"),
+    evolutionRunId: text(input?.evolutionRunId, "evolutionRunId"),
+    skillName: text(input?.skillName, "skillName"),
+    audience: text(input?.audience, "audience"),
+    purpose: text(input?.purpose, "purpose"),
+  });
+  if (descriptor.purpose !== "evolution-ledger")
+    throw new TypeError("proposal adapter purpose must be evolution-ledger");
+  return descriptor;
+}
+
+function verifyRecord(record, descriptor) {
+  const proposal = record?.drafted?.proposal;
+  if (
+    record?.schema !== WIKI_SKILL_PROPOSAL_RECORD_SCHEMA ||
+    record.tenantId !== descriptor.tenantId ||
+    record.evolutionRunId !== descriptor.evolutionRunId ||
+    record.skillName !== descriptor.skillName ||
+    !DIGEST.test(record.planDigest ?? "") ||
+    !DIGEST.test(record.operationKey ?? "") ||
+    !DIGEST.test(record.inputDigest ?? "") ||
+    !DIGEST.test(record.outputDigest ?? "") ||
+    record.drafted?.status !== WIKI_PROPOSAL_STATUS.PROPOSAL ||
+    proposal?.schema !== WIKI_SKILL_PROPOSAL_SCHEMA ||
+    proposal.tenantId !== descriptor.tenantId ||
+    proposal.evolutionRunId !== descriptor.evolutionRunId ||
+    proposal.skillName !== descriptor.skillName ||
+    record.drafted.proposalDigest !==
+      computeWikiSkillProposalDigest(proposal) ||
+    record.outputDigest !== record.drafted.proposalDigest ||
+    !Number.isFinite(Date.parse(record.effectiveAt ?? "")) ||
+    !DIGEST.test(record.recordDigest ?? "")
+  ) {
+    fail(
+      WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+      "Wiki Skill proposal record binding is invalid",
+    );
+  }
+  const core = structuredClone(record);
+  delete core.recordDigest;
+  if (hash(core) !== record.recordDigest)
+    fail(
+      WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+      "Wiki Skill proposal record digest mismatch",
+    );
+  return Object.freeze(structuredClone(record));
+}
+
+export class WikiSkillProposalLedgerAdapter {
+  constructor({
+    descriptor: input,
+    artifactPorts,
+    ledger,
+    ledgerArtifactResolver,
+  } = {}) {
+    this.descriptor = normalizeDescriptor(input);
+    this._put = capture(artifactPorts, "putCanonical", "artifactPorts");
+    this._read = capture(ledger, "read", "ledger");
+    this._verify = capture(ledger, "verify", "ledger");
+    this._append = capture(ledger, "appendDomainEvent", "ledger");
+    if (!isEvolutionLedgerArtifactResolver(ledgerArtifactResolver))
+      throw new TypeError(
+        "a branded EvolutionArtifactPorts ledger resolver is required",
+      );
+    this._resolve = ledgerArtifactResolver;
+    Object.freeze(this);
+  }
+
+  _events(planDigest) {
+    digest(planDigest, "planDigest");
+    const events = this._read();
+    if (!Array.isArray(events))
+      fail(WIKI_SKILL_PROPOSAL_CORRUPT_CODE, "proposal ledger read is invalid");
+    const selected = events.filter(
+      (event) =>
+        event.schema === EVOLUTION_LEDGER_DOMAIN_EVENT_SCHEMA &&
+        event.type === WIKI_SKILL_PROPOSAL_LEDGER_EVENT &&
+        event.tenantId === this.descriptor.tenantId &&
+        event.skillName === this.descriptor.skillName &&
+        event.correlationId === planDigest,
+    );
+    if (selected.length > 1)
+      fail(
+        WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+        "a release plan has multiple committed Wiki Skill proposals",
+      );
+    return selected;
+  }
+
+  _resolveEvent(event) {
+    const authority = this._verify();
+    const resolution = this._resolve({
+      epoch: authority.epoch,
+      ledgerId: authority.ledgerId,
+      ref: event.subjectRef,
+      tenantId: this.descriptor.artifactTenantId,
+    });
+    if (
+      resolution?.schema !== EVOLUTION_ARTIFACT_RESOLUTION_SCHEMA ||
+      resolution.authenticated !== true ||
+      resolution.found !== true ||
+      resolution.ref !== event.subjectRef.ref ||
+      resolution.digest !== event.subjectRef.digest ||
+      !Buffer.isBuffer(resolution.bytes)
+    )
+      fail(
+        WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+        "proposal artifact resolution is invalid",
+      );
+    let durable;
+    try {
+      durable = JSON.parse(resolution.bytes.toString("utf8"));
+    } catch {
+      fail(
+        WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+        "proposal artifact is not canonical JSON",
+      );
+    }
+    if (
+      durable?.schema !== EVOLUTION_DURABLE_ARTIFACT_RECORD_SCHEMA ||
+      durable.tenantId !== this.descriptor.artifactTenantId ||
+      durable.audience !== this.descriptor.audience ||
+      durable.purpose !== this.descriptor.purpose ||
+      durable.retention !== "ledger" ||
+      durable.type !== "wiki-skill-proposal"
+    )
+      fail(
+        WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+        "proposal durable artifact binding is invalid",
+      );
+    return verifyRecord(durable.value, this.descriptor);
+  }
+
+  load(planDigest) {
+    const event = this._events(planDigest)[0];
+    return event ? this._resolveEvent(event) : null;
+  }
+
+  commit({ planDigest, operationKey, inputDigest, drafted, effectiveAt } = {}) {
+    digest(planDigest, "planDigest");
+    digest(operationKey, "operationKey");
+    digest(inputDigest, "inputDigest");
+    const timestamp = new Date(effectiveAt).toISOString();
+    const core = {
+      schema: WIKI_SKILL_PROPOSAL_RECORD_SCHEMA,
+      tenantId: this.descriptor.tenantId,
+      evolutionRunId: this.descriptor.evolutionRunId,
+      skillName: this.descriptor.skillName,
+      planDigest,
+      operationKey,
+      inputDigest,
+      outputDigest: drafted?.proposalDigest,
+      drafted: structuredClone(drafted),
+      effectiveAt: timestamp,
+    };
+    const proposalRecord = verifyRecord(
+      { ...core, recordDigest: hash(core) },
+      this.descriptor,
+    );
+    const existing = this.load(planDigest);
+    if (existing) {
+      if (existing.recordDigest === proposalRecord.recordDigest)
+        return Object.freeze({
+          committed: true,
+          recovered: true,
+          outputDigest: existing.outputDigest,
+          recordDigest: existing.recordDigest,
+        });
+      fail(
+        WIKI_SKILL_PROPOSAL_CONFLICT_CODE,
+        "release plan is already bound to a different Wiki Skill proposal",
+      );
+    }
+    const head = this._verify();
+    const published = this._put("wiki-skill-proposal", proposalRecord, {
+      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_SKILL_PROPOSAL_CORRUPT_CODE,
+        "proposal artifact was not durably read back",
+      );
+    const eventId = `wiki-skill-proposal.${proposalRecord.recordDigest.slice("sha256:".length)}`;
+    const receipt = this._append(
+      {
+        artifactTenantId: this.descriptor.artifactTenantId,
+        correlationId: planDigest,
+        decision: "committed",
+        eventId,
+        reason: "Wiki-informed Skill proposal committed",
+        skillName: this.descriptor.skillName,
+        sourceRefs: [],
+        subjectRef: published.ref,
+        tenantId: this.descriptor.tenantId,
+        timestamp,
+        type: WIKI_SKILL_PROPOSAL_LEDGER_EVENT,
+      },
+      { 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_SKILL_PROPOSAL_CORRUPT_CODE,
+        "proposal ledger append was not durably confirmed",
+      );
+    const stored = this.load(planDigest);
+    if (stored?.recordDigest !== proposalRecord.recordDigest)
+      fail(
+        WIKI_SKILL_PROPOSAL_CORRUPT_CODE,
+        "proposal readback differs after ledger commit",
+      );
+    return Object.freeze({
+      committed: true,
+      recovered: false,
+      outputDigest: proposalRecord.outputDigest,
+      recordDigest: proposalRecord.recordDigest,
+      ledgerReceiptDigest: receipt.receiptDigest,
+    });
+  }
+}
+
+export function createWikiSkillProposalLedgerAdapter(options) {
+  return new WikiSkillProposalLedgerAdapter(options);
+}

package/src/lib/evolution/wiki-target-tombstone-revision.js

@@ -0,0 +1,109 @@
+import {
+  EvidenceBackedWikiMaintainer,
+  WIKI_MAINTENANCE_REQUEST_SCHEMA,
+  digestWikiState,
+} from "./evidence-backed-wiki-maintainer.js";
+
+const POLICY = Object.freeze({
+  trustedProjectionRead: true,
+  rawEvidenceRead: false,
+  activeSkillWrite: false,
+  shell: false,
+  network: false,
+  secretRead: false,
+});
+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;
+}
+
+// Pure derivation only; this function has no persistence or authorization port.
+// Callers must authenticate the source and authorize the exact operations, then
+// commit through the real adapter with the same authenticated head/sequence CAS.
+export async function deriveWikiTargetDispositionRevision({
+  source,
+  descriptor,
+  operations,
+  effectiveAt,
+  requestDigest,
+}) {
+  if (
+    !Array.isArray(operations) ||
+    operations.length < 1 ||
+    operations.length > 128 ||
+    operations.some(
+      (operation) => !["quarantine", "tombstone"].includes(operation.type),
+    ) ||
+    new Set(operations.map((operation) => operation.type)).size !== 1
+  )
+    throw new TypeError(
+      "target-only Wiki derivation requires one bounded disposition",
+    );
+  const ref = Object.keys(source.state.evidence ?? {}).sort()[0];
+  if (!ref)
+    throw new TypeError(
+      "Wiki dispositions require retained authenticated evidence metadata",
+    );
+  const core = source.state.evidence[ref];
+  const evidence = { ...core, envelopeDigest: digestWikiState(core) };
+  let revision = null;
+  const maintainer = new EvidenceBackedWikiMaintainer({
+    descriptor,
+    policy: POLICY,
+    ports: Object.freeze({
+      loadWiki: () => source,
+      resolveEvidence: () => evidence,
+      derive: () => ({ operations }),
+      commitRevision: ({ revision: next }) => {
+        revision = next;
+        return {
+          committed: true,
+          revisionId: next.revisionId,
+          stateDigest: next.stateDigest,
+          evolutionRunId: next.evolutionRunId,
+        };
+      },
+    }),
+  });
+  await maintainer.maintain({
+    evidenceRefs: [ref],
+    effectiveAt,
+    maintenanceRequest: {
+      schema: WIKI_MAINTENANCE_REQUEST_SCHEMA,
+      tenantId: descriptor.tenantId,
+      requestDigest,
+      requestId: `wiki-maintenance:${requestDigest.slice(7)}`,
+    },
+  });
+  if (!revision)
+    throw new Error("Wiki disposition unexpectedly reused an existing request");
+  // General maintenance also recalculates unrelated patterns. A targeted
+  // revocation has no authority to change their lifecycle, confidence or facts.
+  const scoped = structuredClone(source.state);
+  const targets = new Set(operations.map((operation) => operation.patternId));
+  for (const id of targets) scoped.patterns[id] = revision.state.patterns[id];
+  if (!Array.isArray(source.state.index))
+    throw new TypeError("Wiki source index is invalid");
+  scoped.index = source.state.index.filter(
+    (entry) => !targets.has(entry.patternId),
+  );
+  scoped.revision = revision.revision;
+  scoped.revisionId = revision.revisionId;
+  scoped.maintenanceRequests = revision.state.maintenanceRequests;
+  scoped.evolutionLog = revision.state.evolutionLog;
+  return freeze({
+    ...revision,
+    state: scoped,
+    stateDigest: digestWikiState(scoped),
+  });
+}
+
+export async function deriveWikiTargetTombstoneRevision(input) {
+  if (input?.operations?.some((operation) => operation.type !== "tombstone")) {
+    throw new TypeError("target-only Wiki derivation requires tombstones");
+  }
+  return deriveWikiTargetDispositionRevision(input);
+}