chainlesschain 0.166.24 → 0.166.26

package/src/lib/evolution/knowledge-wiki-source-admission.js

@@ -8,11 +8,15 @@ import {
   readRetainedWikiRevision,
   createKnowledgeWikiSourceTracker,
 } from "./knowledge-wiki-source-provenance.js";
+import {
+  GOVERNED_KNOWLEDGE_QUARANTINE_RELEASE_EVENT_TYPE,
+  verifyGovernedKnowledgeQuarantineReleaseRecord,
+} from "./governed-knowledge-quarantine-release.js";
 
 export { WIKI_SOURCE_ADMISSION_INVALID_CODE } from "./knowledge-wiki-source-provenance.js";
 export const WIKI_SOURCE_REVOKED_CODE = "CC_EVOLUTION_WIKI_SOURCE_REVOKED";
 const WIKI_EVENT = "wiki.revision.committed";
-const TERMINAL = new Set(["revoked", "tombstoned"]);
+const TERMINAL = new Set(["quarantined", "revoked", "tombstoned"]);
 
 function canonical(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
@@ -24,6 +28,121 @@ function canonical(value) {
 }
 const same = (a, b) => canonical(a) === canonical(b);
 
+function quarantineReleaseFor({
+  events,
+  prepared,
+  descriptor,
+  resolveSubject,
+  fail,
+}) {
+  const eventId = `${GOVERNED_KNOWLEDGE_QUARANTINE_RELEASE_EVENT_TYPE}.${prepared.operationDigest.slice(7)}`;
+  const matches = events.filter(
+    (event) =>
+      event.type === GOVERNED_KNOWLEDGE_QUARANTINE_RELEASE_EVENT_TYPE &&
+      event.eventId === eventId &&
+      event.tenantId === prepared.tenantId,
+  );
+  if (matches.length > 1) fail("quarantine release is ambiguous");
+  if (matches.length === 0) return null;
+  const event = matches[0];
+  const value = readWikiSourceRecord(
+    event,
+    "governed-knowledge-quarantine-release",
+    descriptor,
+    resolveSubject,
+  ).value;
+  let release;
+  try {
+    release = verifyGovernedKnowledgeQuarantineReleaseRecord(value, {
+      tenantId: prepared.tenantId,
+    });
+  } catch {
+    fail("quarantine release record is invalid");
+  }
+  const quarantines = prepared.knowledge.dependencies.filter(
+    (dependency) => dependency.disposition === "quarantine",
+  );
+  if (
+    event.decision !== "committed" ||
+    event.timestamp !== release.committedAt ||
+    !Array.isArray(event.sourceRefs) ||
+    event.sourceRefs.length !== 0 ||
+    release.preparedRecordDigest !== prepared.recordDigest ||
+    release.knowledgeId !== prepared.knowledge.knowledgeId ||
+    release.contentDigest !== prepared.knowledge.contentDigest ||
+    !same(release.dependencies, quarantines)
+  ) {
+    fail("quarantine release does not bind the prepared revocation");
+  }
+  return release;
+}
+
+function isReleasedWikiRestoration(
+  previous,
+  candidate,
+  patternId,
+  release,
+  releaseCoversRun,
+  baseline,
+) {
+  if (
+    !release ||
+    !releaseCoversRun ||
+    !baseline ||
+    previous.patterns[patternId]?.status !== "quarantined" ||
+    !candidate.state.patterns[patternId] ||
+    TERMINAL.has(candidate.state.patterns[patternId].status) ||
+    !release.dependencies.some(
+      (dependency) =>
+        dependency.kind === "wiki" && dependency.disposition === "quarantine",
+    )
+  ) {
+    return false;
+  }
+  const expectedPattern = {
+    ...baseline.patterns[patternId],
+    updatedAt: release.committedAt,
+  };
+  const actualPattern = candidate.state.patterns[patternId];
+  const expectedIndex = [
+    {
+      patternId: expectedPattern.patternId,
+      kind: expectedPattern.kind,
+      status: expectedPattern.status,
+      summary: expectedPattern.summary,
+      confidence: expectedPattern.operationalConfidence,
+      actionable: expectedPattern.actionable,
+      skillNames: expectedPattern.skillNames,
+    },
+  ];
+  const refs = [
+    ...new Set([
+      ...expectedPattern.positiveEvidence,
+      ...expectedPattern.negativeEvidence,
+    ]),
+  ].sort();
+  if (
+    !same(actualPattern, expectedPattern) ||
+    !same(
+      candidate.state.index.filter((entry) => entry.patternId === patternId),
+      expectedIndex,
+    ) ||
+    !same(
+      refs.map((ref) => candidate.state.evidence[ref]),
+      refs.map((ref) => baseline.evidence[ref]),
+    )
+  ) {
+    return false;
+  }
+  return candidate.state.evolutionLog.some(
+    (entry) =>
+      entry.type === "pattern-quarantine-released" &&
+      entry.subjectId === patternId &&
+      entry.details?.operationDigest === release.operationDigest &&
+      entry.details?.releaseRecordDigest === release.recordDigest,
+  );
+}
+
 // Only called with bytes resolved and digest-authenticated by the real Ledger
 // while its write lock is held. There is no public success flag / writer port.
 export function assertKnowledgeWikiSourceAdmission({
@@ -83,16 +202,44 @@ export function assertKnowledgeWikiSourceAdmission({
         `${GOVERNED_KNOWLEDGE_DEPENDENCY_PREPARED_EVENT_TYPE}.${prepared.operationDigest.slice(7)}`
     )
       fail("revocation is not an exact durable prepared operation");
+    const release = quarantineReleaseFor({
+      events,
+      prepared,
+      descriptor,
+      resolveSubject,
+      fail,
+    });
     const tracker = createKnowledgeWikiSourceTracker({
       tenantId: input.tenantId,
       knowledge: prepared.knowledge,
       readWiki: wiki,
     });
     for (const entry of history) tracker.visit(entry, wiki(entry));
+    const releaseWikiDigests = new Set(
+      (release?.dependencies ?? [])
+        .filter(
+          (dependency) =>
+            dependency.kind === "wiki" &&
+            dependency.disposition === "quarantine",
+        )
+        .map((dependency) => dependency.digest),
+    );
+    const releaseCoversRun = history
+      .filter((event) => event.correlationId === input.correlationId)
+      .some((event) => releaseWikiDigests.has(wiki(event).stateDigest));
     const { previous, unsafePatternIds } = tracker.visit(input, candidate, {
       proposed: true,
     });
     for (const id of unsafePatternIds) {
+      let restorationBaseline = null;
+      for (const event of history) {
+        if (event.correlationId !== input.correlationId) continue;
+        const state = wiki(event).state;
+        if (state.patterns[id] && state.patterns[id].status !== "quarantined") {
+          restorationBaseline = state;
+        }
+        if (state.patterns[id]?.status === "quarantined") break;
+      }
       const next = candidate.state.patterns[id];
       // Permit removal/terminalization and unchanged pending cleanup batches.
       if (!next || (TERMINAL.has(next.status) && next.actionable === false))
@@ -101,6 +248,18 @@ export function assertKnowledgeWikiSourceAdmission({
         !previous.patterns[id] ||
         !same(exposure(previous, id), exposure(candidate.state, id))
       ) {
+        if (
+          isReleasedWikiRestoration(
+            previous,
+            candidate,
+            id,
+            release,
+            releaseCoversRun,
+            restorationBaseline,
+          )
+        ) {
+          continue;
+        }
         const error = new Error(
           "Wiki source admission: revoked Knowledge cannot create, rewrite or reactivate a Wiki pattern",
         );

package/src/lib/evolution/knowledge-wiki-source-provenance.js

@@ -27,6 +27,7 @@ const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const PATTERN = /^pat-[a-z0-9][a-z0-9-]{2,127}$/u;
 const STATUSES = new Set(Object.values(WIKI_PATTERN_STATUS));
 const TERMINAL = new Set([
+  WIKI_PATTERN_STATUS.QUARANTINED,
   WIKI_PATTERN_STATUS.REVOKED,
   WIKI_PATTERN_STATUS.TOMBSTONED,
 ]);

package/src/lib/evolution/skill-candidate-registry.js

@@ -1596,6 +1596,9 @@ export class SkillCandidateRegistry {
       Object.freeze({
         tenantId,
         read: Object.freeze(SkillCandidateRegistry.prototype.read.bind(this)),
+        readInventory: Object.freeze(
+          SkillCandidateRegistry.prototype.readInventory.bind(this),
+        ),
       }),
     );
   }
@@ -2914,14 +2917,29 @@ export class SkillCandidateRegistry {
         `limit must be an integer from 1 to ${MAX_LIST_LIMIT}`,
       );
     }
-    const names = this._assertNoMixedTenantArtifacts()
+    return Object.freeze(this.readInventory().slice(0, limit));
+  }
+
+  readInventory() {
+    const before = this._assertNoMixedTenantArtifacts()
       .filter((name) => CANDIDATE_FILE_PATTERN.test(name))
       .sort();
-    const candidates = names.slice(0, limit).map((name) => {
+    const candidates = before.map((name) => {
       const match = CANDIDATE_FILE_PATTERN.exec(name);
       return this.read(`sha256:${match[1]}`);
     });
-    this._assertBoundary();
+    const after = this._assertNoMixedTenantArtifacts()
+      .filter((name) => CANDIDATE_FILE_PATTERN.test(name))
+      .sort();
+    if (
+      before.length !== after.length ||
+      before.some((name, index) => name !== after[index])
+    ) {
+      throw registryError(
+        "SKILL_CANDIDATE_STORE_UNSAFE",
+        "candidate tenant inventory changed during authenticated enumeration",
+      );
+    }
     return Object.freeze(candidates);
   }
 }

package/src/lib/evolution/skill-release-registry.js

@@ -87,6 +87,9 @@ const TENANT_KEY_PATTERN = /^[a-f0-9]{64}$/u;
 const TEMP_PATTERN = /^\.(?:release|state|write)-[A-Za-z0-9._-]+\.tmp$/u;
 const MAX_FILE_BYTES = 4 * 1024 * 1024;
 const MAX_TENANT_MARKER_BYTES = 4096;
+export const SKILL_RELEASE_INVENTORY_MAX_ENTRIES = 4_096;
+export const SKILL_RELEASE_INVENTORY_MAX_BYTES = 32 * 1024 * 1024;
+export const SKILL_RELEASE_INVENTORY_MAX_NODES = 1_000_000;
 const MAX_CANONICAL_DEPTH = 32;
 const MAX_CANONICAL_NODES = 100_000;
 const MAX_CANONICAL_ARRAY_ENTRIES = 65_536;
@@ -2783,6 +2786,8 @@ export class SkillReleaseRegistry {
         readActive: SkillReleaseRegistry.prototype.readActive.bind(this),
         readState: SkillReleaseRegistry.prototype.readState.bind(this),
         readRelease: SkillReleaseRegistry.prototype.readRelease.bind(this),
+        readInventory:
+          SkillReleaseRegistry.prototype.readInventory.bind(this),
         matchesTransactionLedger: (value) => value === transactionLedger,
       }),
     );
@@ -3882,6 +3887,144 @@ export class SkillReleaseRegistry {
         });
   }
 
+  #readInventoryNames(area, pattern) {
+    const directory = this.#directories[area]?.path;
+    if (!directory || typeof this.#fs.opendirSync !== "function") {
+      throw failure(
+        "SKILL_RELEASE_STORE_UNSAFE",
+        "release inventory requires bounded directory enumeration",
+      );
+    }
+    const names = [];
+    let handle = null;
+    let enumerationError = null;
+    try {
+      handle = this.#fs.opendirSync(directory);
+      while (true) {
+        const entry = handle.readSync();
+        if (entry === null) break;
+        if (
+          !entry ||
+          typeof entry.name !== "string" ||
+          !pattern.test(entry.name)
+        ) {
+          throw failure(
+            "SKILL_RELEASE_STORE_UNSAFE",
+            `release inventory found an unexpected ${area} entry`,
+          );
+        }
+        if (names.length >= SKILL_RELEASE_INVENTORY_MAX_ENTRIES) {
+          throw failure(
+            "SKILL_RELEASE_STORE_LIMIT",
+            `release inventory ${area} entry limit was exceeded`,
+          );
+        }
+        names.push(entry.name);
+      }
+    } catch (cause) {
+      enumerationError =
+        cause instanceof SkillReleaseRegistryError
+          ? cause
+          : failure(
+              "SKILL_RELEASE_STORE_UNSAFE",
+              `release inventory could not enumerate ${area} safely`,
+              { cause },
+            );
+    }
+    if (handle !== null && typeof handle.closeSync === "function") {
+      try {
+        handle.closeSync();
+      } catch (cause) {
+        enumerationError = failure(
+          "SKILL_RELEASE_STORE_UNSAFE",
+          `release inventory could not close ${area} safely`,
+          { cause, enumerationError },
+        );
+      }
+    }
+    if (enumerationError !== null) throw enumerationError;
+    return names.sort();
+  }
+
+  readInventory() {
+    this.#assertBoundary();
+    const releasePattern = /^[a-f0-9]{64}\.json$/u;
+    const statePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.json$/u;
+    const beforeReleases = this.#readInventoryNames(
+      "artifacts",
+      releasePattern,
+    );
+    const beforeStates = this.#readInventoryNames("active", statePattern);
+    if (
+      beforeReleases.length + beforeStates.length >
+      SKILL_RELEASE_INVENTORY_MAX_ENTRIES
+    ) {
+      throw failure(
+        "SKILL_RELEASE_STORE_LIMIT",
+        "release inventory aggregate entry limit was exceeded",
+      );
+    }
+    const releases = beforeReleases.map((name) =>
+      this.readRelease(`sha256:${name.slice(0, -".json".length)}`),
+    );
+    const active = beforeStates.map((name) => {
+      const skill = name.slice(0, -".json".length);
+      const value = this.readActive(skill);
+      if (value === null) {
+        throw failure(
+          "SKILL_RELEASE_STATE_CORRUPT",
+          "persisted active state has no committed release",
+        );
+      }
+      return deepFreeze({ skillName: skill, ...value });
+    });
+    let bytes = 0;
+    let nodes = 0;
+    const stack = [...releases, ...active.map(({ state }) => state)];
+    for (const value of stack) {
+      bytes += Buffer.byteLength(canonicalJson(value), "utf8");
+      const pending = [value];
+      while (pending.length > 0) {
+        const node = pending.pop();
+        nodes += 1;
+        if (nodes > SKILL_RELEASE_INVENTORY_MAX_NODES) {
+          throw failure(
+            "SKILL_RELEASE_STORE_LIMIT",
+            "release inventory aggregate node limit was exceeded",
+          );
+        }
+        if (node !== null && typeof node === "object") {
+          pending.push(...(Array.isArray(node) ? node : Object.values(node)));
+        }
+      }
+    }
+    if (bytes > SKILL_RELEASE_INVENTORY_MAX_BYTES) {
+      throw failure(
+        "SKILL_RELEASE_STORE_LIMIT",
+        "release inventory aggregate byte limit was exceeded",
+      );
+    }
+    const afterReleases = this.#readInventoryNames("artifacts", releasePattern);
+    const afterStates = this.#readInventoryNames("active", statePattern);
+    const afterStateDigests = afterStates.map((name) =>
+      this.readState(name.slice(0, -".json".length)).stateDigest,
+    );
+    if (
+      canonicalJson(beforeReleases) !== canonicalJson(afterReleases) ||
+      canonicalJson(beforeStates) !== canonicalJson(afterStates) ||
+      active.some(
+        ({ state }, index) => state.stateDigest !== afterStateDigests[index],
+      )
+    ) {
+      throw failure(
+        "SKILL_RELEASE_STORE_UNSAFE",
+        "release inventory changed during authenticated enumeration",
+      );
+    }
+    this.#assertBoundary();
+    return deepFreeze({ active, releases });
+  }
+
   pinActive(name) {
     const active = this.readActive(name);
     if (!active)

package/src/lib/evolution/wiki-maintainer-ledger-adapter.js

@@ -162,6 +162,7 @@ export class WikiMaintainerLedgerAdapter {
         descriptor: this.descriptor,
         matchesLedger: (candidate) => candidate === ledger,
         loadWiki: () => this.#loadWiki(),
+        readInventory: () => this.#readInventory(),
         readRevision: (input) => this.#readRevision(input),
         readKnowledgeProvenance: (input) =>
           this.#readKnowledgeProvenance(input),
@@ -177,6 +178,7 @@ export class WikiMaintainerLedgerAdapter {
     sourceDigest = null,
     allowed = [],
     checkpoint = null,
+    inventory = false,
     revisionId = null,
     stateRevisionDigest = null,
   } = {}) {
@@ -231,12 +233,25 @@ export class WikiMaintainerLedgerAdapter {
         event.tenantId === this.descriptor.tenantId &&
         event.correlationId === this.descriptor.evolutionRunId,
     );
+    const tenantWikiRunIds = [
+      ...new Set(
+        events
+          .filter(
+            (event) =>
+              event.schema === EVOLUTION_LEDGER_DOMAIN_EVENT_SCHEMA &&
+              event.type === WIKI_LEDGER_EVENT_TYPE &&
+              event.tenantId === this.descriptor.tenantId,
+          )
+          .map((event) => requiredString(event.correlationId, "correlationId")),
+      ),
+    ].sort();
     let state = createEmptyWikiState(this.descriptor.tenantId);
     let viewState = state;
     let latest = null;
     let selectedRevision = null;
     let source = sourceDigest === digestWikiState(state) ? state : null;
     const successors = [];
+    const revisions = [];
     let retainedBytes = 0;
     let batch = [];
     for (const [index, event] of matches.entries()) {
@@ -301,6 +316,37 @@ export class WikiMaintainerLedgerAdapter {
         );
       }
       verifyRequestTransition(state, revision);
+      if (inventory) {
+        const wikiSourceRevisionIds = [
+          ...new Set(
+            Object.values(revision.state.evidence)
+              .flatMap((entry) => [entry.ref, entry.artifactRef])
+              .filter(
+                (ref) =>
+                  typeof ref === "string" &&
+                  ref.startsWith(`wiki-source://${this.descriptor.tenantId}/wiki:`),
+              )
+              .map((ref) => ref.slice(ref.lastIndexOf("/") + 1)),
+          ),
+        ].sort();
+        revisions.push(
+          freeze({
+            revision: revision.revision,
+            revisionId: revision.revisionId,
+            priorStateDigest: revision.priorStateDigest,
+            stateDigest: revision.stateDigest,
+            artifactRef: event.subjectRef,
+            wikiSourceRevisionIds,
+            checkpoint: {
+              epoch: event.epoch,
+              ledgerId: event.ledgerId,
+              identityDigest: event.identityDigest,
+              sequence: event.sequence,
+              headDigest: event.eventDigest,
+            },
+          }),
+        );
+      }
       if (
         revision.revisionId === revisionId ||
         revision.stateDigest === stateRevisionDigest
@@ -380,9 +426,24 @@ export class WikiMaintainerLedgerAdapter {
       source,
       successors,
       selectedRevision,
+      revisions,
+      tenantWikiRunIds,
     };
   }
 
+  #readInventory() {
+    const { head, revisions, tenantWikiRunIds } = this.#history({
+      inventory: true,
+    });
+    return freeze({
+      authenticated: true,
+      descriptor: this.descriptor,
+      ledgerHead: head,
+      revisions,
+      tenantWikiRunIds,
+    });
+  }
+
   #readKnowledgeProvenance({
     tenantId,
     revisionId,

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

@@ -23,7 +23,7 @@ function freeze(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 deriveWikiTargetTombstoneRevision({
+export async function deriveWikiTargetDispositionRevision({
   source,
   descriptor,
   operations,
@@ -34,15 +34,18 @@ export async function deriveWikiTargetTombstoneRevision({
     !Array.isArray(operations) ||
     operations.length < 1 ||
     operations.length > 128 ||
-    operations.some((operation) => operation.type !== "tombstone")
+    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 bounded tombstones",
+      "target-only Wiki derivation requires one bounded disposition",
     );
   const ref = Object.keys(source.state.evidence ?? {}).sort()[0];
   if (!ref)
     throw new TypeError(
-      "Wiki tombstones require retained authenticated evidence metadata",
+      "Wiki dispositions require retained authenticated evidence metadata",
     );
   const core = source.state.evidence[ref];
   const evidence = { ...core, envelopeDigest: digestWikiState(core) };
@@ -76,9 +79,7 @@ export async function deriveWikiTargetTombstoneRevision({
     },
   });
   if (!revision)
-    throw new Error(
-      "Wiki tombstone derivation unexpectedly reused an existing request",
-    );
+    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);
@@ -99,3 +100,10 @@ export async function deriveWikiTargetTombstoneRevision({
     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);
+}