chainlesschain 0.166.22 → 0.166.25

package/src/lib/evolution/controlled-skill-production-pilot.js

@@ -1,10 +1,22 @@
 import { createHash } from "node:crypto";
 import { types as utilTypes } from "node:util";
 
+import {
+  isProgressiveCanaryGateAuthority,
+  nextProgressiveCanaryStage,
+  verifyProgressiveCanaryPlan,
+} from "./statistical-progressive-canary.js";
+import {
+  SKILL_WIKI_PILOT_OUTCOME_SCHEMA,
+  createSkillWikiPilotReconciliationSource,
+} from "./skill-wiki-reconciliation.js";
+
 export const CONTROLLED_SKILL_PILOT_SCHEMA =
   "chainlesschain.controlled-skill-production-pilot/v1";
 export const CONTROLLED_SKILL_PILOT_STATE_SCHEMA =
   "chainlesschain.controlled-skill-production-pilot-state/v1";
+export const CONTROLLED_SKILL_PILOT_PROGRESSIVE_STATE_SCHEMA =
+  "chainlesschain.controlled-skill-production-pilot-state/v2";
 export const CONTROLLED_SKILL_PILOT_EVENT_SCHEMA =
   "chainlesschain.controlled-skill-production-pilot-event/v1";
 
@@ -12,6 +24,7 @@ export const CONTROLLED_SKILL_PILOT_STAGE = Object.freeze({
   CANDIDATE: "candidate",
   SHADOW: "shadow",
   CANARY: "canary",
+  ACTIVE_PROBATION: "active-probation",
   ACTIVE: "active",
   ROLLED_BACK: "rolled-back",
 });
@@ -50,6 +63,14 @@ function hash(value) {
   return `sha256:${createHash("sha256").update(canonical(value)).digest("hex")}`;
 }
 
+export function digestControlledSkillPilotState(value) {
+  return hash(value);
+}
+
+export function digestControlledSkillPilotEvent(value) {
+  return hash(value);
+}
+
 function clone(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
 }
@@ -264,9 +285,15 @@ function normalizeDescriptor(input) {
   return deepFreeze(normalized);
 }
 
-function emptyState(descriptorDigest) {
-  return {
-    schema: CONTROLLED_SKILL_PILOT_STATE_SCHEMA,
+export function digestControlledSkillPilotDescriptor(input) {
+  return hash(normalizeDescriptor(input));
+}
+
+function emptyState(descriptorDigest, progressive = null) {
+  const state = {
+    schema: progressive
+      ? CONTROLLED_SKILL_PILOT_PROGRESSIVE_STATE_SCHEMA
+      : CONTROLLED_SKILL_PILOT_STATE_SCHEMA,
     descriptorDigest,
     revision: 0,
     stage: CONTROLLED_SKILL_PILOT_STAGE.CANDIDATE,
@@ -278,28 +305,86 @@ function emptyState(descriptorDigest) {
     pendingTransition: null,
     lastTransitionReceiptDigest: null,
   };
+  if (progressive) {
+    state.progressivePlanDigest = progressive.plan.planDigest;
+    state.progressiveStepId = null;
+    state.progressiveGateReceiptDigests = [];
+  }
+  return state;
+}
+
+function progressiveStateIsCoherent(state, progressive) {
+  if (!progressive) return true;
+  const digests = state.progressiveGateReceiptDigests;
+  if (
+    !Array.isArray(digests) ||
+    digests.length > progressive.plan.steps.length ||
+    new Set(digests).size !== digests.length
+  ) {
+    return false;
+  }
+  const effectiveStage = state.pendingTransition?.request?.to ?? state.stage;
+  if (effectiveStage === CONTROLLED_SKILL_PILOT_STAGE.ROLLED_BACK) {
+    return (
+      state.progressiveStepId === null ||
+      progressive.plan.steps.some(
+        ({ id: stepId }) => stepId === state.progressiveStepId,
+      )
+    );
+  }
+  if (effectiveStage === CONTROLLED_SKILL_PILOT_STAGE.CANDIDATE) {
+    return state.progressiveStepId === null && digests.length === 0;
+  }
+  if (effectiveStage === CONTROLLED_SKILL_PILOT_STAGE.ACTIVE) {
+    return (
+      state.progressiveStepId === null &&
+      digests.length === progressive.plan.steps.length
+    );
+  }
+  const index = progressive.plan.steps.findIndex(
+    ({ id: stepId, stage }) =>
+      stepId === state.progressiveStepId && stage === effectiveStage,
+  );
+  return index >= 0 && digests.length === index;
 }
 
-function normalizeRestore(input, descriptorDigest) {
+function normalizeRestore(input, descriptorDigest, progressive) {
   plain(input, "pilot restore");
   const state = plain(input.state, "pilot restore.state");
   if (
     input.authenticated !== true ||
     input.durable !== true ||
     input.descriptorDigest !== descriptorDigest ||
-    input.stateDigest !== hash(state) ||
-    state.schema !== CONTROLLED_SKILL_PILOT_STATE_SCHEMA ||
+    input.stateDigest !== digestControlledSkillPilotState(state) ||
+    state.schema !==
+      (progressive
+        ? CONTROLLED_SKILL_PILOT_PROGRESSIVE_STATE_SCHEMA
+        : CONTROLLED_SKILL_PILOT_STATE_SCHEMA) ||
     state.descriptorDigest !== descriptorDigest ||
     !STAGES.has(state.stage) ||
     !Number.isSafeInteger(state.revision) ||
     state.revision < 0 ||
     !Array.isArray(state.observations) ||
+    (progressive === null
+      ? state.progressivePlanDigest !== undefined ||
+        state.progressiveStepId !== undefined ||
+        state.progressiveGateReceiptDigests !== undefined
+      : state.progressivePlanDigest !== progressive.plan.planDigest ||
+        (state.progressiveStepId !== null &&
+          !progressive.plan.steps.some(
+            ({ id: stepId }) => stepId === state.progressiveStepId,
+          )) ||
+        !Array.isArray(state.progressiveGateReceiptDigests) ||
+        state.progressiveGateReceiptDigests.some(
+          (value) => !DIGEST.test(value),
+        )) ||
     (state.pendingTransition !== null &&
       (!state.pendingTransition ||
         typeof state.pendingTransition !== "object" ||
         state.pendingTransition.requestDigest !==
           hash(state.pendingTransition.request) ||
-        state.pendingTransition.request?.from !== state.stage))
+        state.pendingTransition.request?.from !== state.stage)) ||
+    !progressiveStateIsCoherent(state, progressive)
   ) {
     fail(
       CONTROLLED_SKILL_PILOT_ERROR.PERSISTENCE_FAILED,
@@ -309,6 +394,37 @@ function normalizeRestore(input, descriptorDigest) {
   return clone(state);
 }
 
+function normalizeProgressiveCanary(input, descriptor) {
+  if (input == null) return null;
+  plain(input, "progressive Canary configuration");
+  if (
+    Reflect.ownKeys(input).length !== 2 ||
+    !Object.hasOwn(input, "plan") ||
+    !Object.hasOwn(input, "gateAuthority")
+  ) {
+    throw new TypeError("progressive Canary configuration is not exact");
+  }
+  const plan = verifyProgressiveCanaryPlan(input.plan);
+  if (!isProgressiveCanaryGateAuthority(input.gateAuthority)) {
+    throw new TypeError(
+      "a branded progressive Canary gate authority is required",
+    );
+  }
+  if (
+    plan.tenantId !== descriptor.tenantId ||
+    plan.pilotId !== descriptor.pilotId ||
+    plan.skillName !== descriptor.skillName ||
+    plan.candidateDigest !== descriptor.candidateDigest ||
+    plan.baselineDigest !== descriptor.baselineDigest ||
+    input.gateAuthority.planDigest !== plan.planDigest ||
+    input.gateAuthority.tenantId !== plan.tenantId ||
+    input.gateAuthority.pilotId !== plan.pilotId
+  ) {
+    throw new TypeError("progressive Canary plan is not bound to this pilot");
+  }
+  return Object.freeze({ plan, gateAuthority: input.gateAuthority });
+}
+
 function normalizeApproval(value, descriptor, descriptorDigest) {
   plain(value, "review approval");
   if (
@@ -447,9 +563,16 @@ export class ControlledSkillProductionPilot {
     ports,
     now = Date.now,
     restore = null,
+    progressiveCanary = null,
   } = {}) {
     this.descriptor = normalizeDescriptor(input);
-    this.descriptorDigest = hash(this.descriptor);
+    this.descriptorDigest = digestControlledSkillPilotDescriptor(
+      this.descriptor,
+    );
+    this._progressiveCanary = normalizeProgressiveCanary(
+      progressiveCanary,
+      this.descriptor,
+    );
     this._now = typeof now === "function" ? now : Date.now;
     this._readActiveState = capture(ports, "readActiveState");
     this._verifyApproval = capture(ports, "verifyApproval");
@@ -465,8 +588,9 @@ export class ControlledSkillProductionPilot {
             descriptorDigest: this.descriptorDigest,
           }),
           this.descriptorDigest,
+          this._progressiveCanary,
         )
-      : emptyState(this.descriptorDigest);
+      : emptyState(this.descriptorDigest, this._progressiveCanary);
   }
 
   async start({ optedIn, tenantId, cohortId } = {}) {
@@ -510,15 +634,35 @@ export class ControlledSkillProductionPilot {
     await this._assertActiveUnchanged();
     const next = clone(this._state);
     next.reviewReceiptDigest = reviewReceiptDigest;
-    await this._advance(next, CONTROLLED_SKILL_PILOT_STAGE.SHADOW, {
-      reviewReceiptDigest,
-    });
+    if (this._progressiveCanary) {
+      next.progressiveStepId = this._progressiveCanary.plan.steps[0].id;
+    }
+    await this._advance(
+      next,
+      CONTROLLED_SKILL_PILOT_STAGE.SHADOW,
+      {
+        reviewReceiptDigest,
+        ...(this._progressiveCanary
+          ? {
+              progressivePlanDigest: this._progressiveCanary.plan.planDigest,
+              progressiveStepId: next.progressiveStepId,
+            }
+          : {}),
+      },
+      { progressive: this._progressiveCanary !== null },
+    );
     return this.view();
   }
 
   async recordObservation(input) {
     this._started();
     this._noPending();
+    if (this._progressiveCanary) {
+      fail(
+        CONTROLLED_SKILL_PILOT_ERROR.INVALID,
+        "progressive Canary observations must enter the gate authority",
+      );
+    }
     if (
       ![
         CONTROLLED_SKILL_PILOT_STAGE.SHADOW,
@@ -627,9 +771,12 @@ export class ControlledSkillProductionPilot {
     return this.view();
   }
 
-  async advance() {
+  async advance(input = {}) {
     this._started();
     this._noPending();
+    if (this._progressiveCanary) {
+      return this._advanceProgressive(input);
+    }
     const target = FORWARD.get(this._state.stage);
     if (!target) {
       fail(
@@ -693,7 +840,7 @@ export class ControlledSkillProductionPilot {
   snapshot() {
     return deepFreeze({
       descriptorDigest: this.descriptorDigest,
-      stateDigest: hash(this._state),
+      stateDigest: digestControlledSkillPilotState(this._state),
       state: clone(this._state),
     });
   }
@@ -736,9 +883,135 @@ export class ControlledSkillProductionPilot {
       cohort: clone(this.descriptor.cohort),
       lastTransitionReceiptDigest: this._state.lastTransitionReceiptDigest,
       reconciliationRequired: this._state.pendingTransition !== null,
+      progressiveCanary:
+        this._progressiveCanary === null
+          ? null
+          : {
+              planDigest: this._state.progressivePlanDigest,
+              stepId: this._state.progressiveStepId,
+              gateReceiptDigests: clone(
+                this._state.progressiveGateReceiptDigests,
+              ),
+            },
+    });
+  }
+
+  createWikiOutcomeSource() {
+    return createSkillWikiPilotReconciliationSource({
+      tenantId: this.descriptor.tenantId,
+      streamId: `${this.descriptor.pilotId}:wiki-outcomes`,
+      readPilotOutcomes: () => {
+        if (
+          this._state.pendingTransition !== null ||
+          this._state.lastTransitionReceiptDigest === null ||
+          this._state.activeStateDigest === null
+        ) {
+          return [];
+        }
+        const stable =
+          this._progressiveCanary !== null &&
+          this._state.stage === CONTROLLED_SKILL_PILOT_STAGE.ACTIVE &&
+          this._state.progressiveStepId === null &&
+          this._state.progressiveGateReceiptDigests.length ===
+            this._progressiveCanary.plan.steps.length;
+        const rolledBack =
+          this._state.stage === CONTROLLED_SKILL_PILOT_STAGE.ROLLED_BACK;
+        if (!stable && !rolledBack) return [];
+        return [
+          {
+            schema: SKILL_WIKI_PILOT_OUTCOME_SCHEMA,
+            authenticated: true,
+            durable: true,
+            tenantId: this.descriptor.tenantId,
+            streamId: `${this.descriptor.pilotId}:wiki-outcomes`,
+            sequence: this._state.revision,
+            pilotId: this.descriptor.pilotId,
+            descriptorDigest: this.descriptorDigest,
+            candidateId: this.descriptor.candidateDigest,
+            skillName: this.descriptor.skillName,
+            outcome: stable ? "stable" : "rollback",
+            reason: stable
+              ? "The statistical progressive Canary reached stable."
+              : "The production Pilot rolled back the candidate.",
+            occurredAt: new Date(this._state.stageStartedAt).toISOString(),
+            activeStateDigest: this._state.activeStateDigest,
+            evidenceReceiptDigests: [
+              ...(this._state.reviewReceiptDigest === null
+                ? []
+                : [this._state.reviewReceiptDigest]),
+              ...(this._state.progressiveGateReceiptDigests ?? []),
+            ],
+            sourceReceiptDigest: this._state.lastTransitionReceiptDigest,
+          },
+        ];
+      },
     });
   }
 
+  async _advanceProgressive({ gateReceipt } = {}) {
+    if (this._state.stage === CONTROLLED_SKILL_PILOT_STAGE.CANDIDATE) {
+      fail(
+        CONTROLLED_SKILL_PILOT_ERROR.REVIEW_REQUIRED,
+        "shadow requires explicit durable human approval",
+      );
+    }
+    if (this._state.killSwitch) {
+      fail(
+        CONTROLLED_SKILL_PILOT_ERROR.KILL_SWITCH,
+        "pilot kill switch is set",
+      );
+    }
+    const currentStepId = this._state.progressiveStepId;
+    if (typeof currentStepId !== "string") {
+      fail(
+        CONTROLLED_SKILL_PILOT_ERROR.INVALID,
+        "progressive Canary step is unavailable",
+      );
+    }
+    let receipt;
+    let nextStep;
+    try {
+      receipt = await this._progressiveCanary.gateAuthority.verify(
+        gateReceipt,
+        {
+          stepId: currentStepId,
+        },
+      );
+      nextStep = nextProgressiveCanaryStage({
+        plan: this._progressiveCanary.plan,
+        currentStepId,
+        gateReport: receipt.report,
+      });
+    } catch (error) {
+      const failure = new Error(
+        `pilot progressive gate failed: ${error.message}`,
+      );
+      failure.code = CONTROLLED_SKILL_PILOT_ERROR.GATE_FAILED;
+      throw failure;
+    }
+    const target =
+      nextStep.stage === "stable"
+        ? CONTROLLED_SKILL_PILOT_STAGE.ACTIVE
+        : nextStep.stage;
+    await this._assertActiveUnchanged();
+    const next = clone(this._state);
+    next.progressiveStepId = nextStep.stepId;
+    next.progressiveGateReceiptDigests.push(receipt.receiptDigest);
+    await this._advance(
+      next,
+      target,
+      {
+        progressivePlanDigest: this._progressiveCanary.plan.planDigest,
+        gateReportDigest: receipt.reportDigest,
+        gateReceiptDigest: receipt.receiptDigest,
+        fromStepId: currentStepId,
+        toStepId: nextStep.stepId,
+      },
+      { progressive: true },
+    );
+    return this.view();
+  }
+
   _started() {
     if (this._state.activeStateDigest === null) {
       fail(CONTROLLED_SKILL_PILOT_ERROR.INVALID, "pilot has not started");
@@ -777,9 +1050,26 @@ export class ControlledSkillProductionPilot {
     }
   }
 
-  async _advance(next, target, evidence) {
+  async _advance(next, target, evidence, { progressive = false } = {}) {
     const from = this._state.stage;
-    if (target !== CONTROLLED_PILOT_ROLLBACK && FORWARD.get(from) !== target) {
+    const progressiveTransition =
+      progressive &&
+      ((from === CONTROLLED_SKILL_PILOT_STAGE.CANDIDATE &&
+        target === CONTROLLED_SKILL_PILOT_STAGE.SHADOW) ||
+        (from === CONTROLLED_SKILL_PILOT_STAGE.SHADOW &&
+          target === CONTROLLED_SKILL_PILOT_STAGE.CANARY) ||
+        (from === CONTROLLED_SKILL_PILOT_STAGE.CANARY &&
+          [
+            CONTROLLED_SKILL_PILOT_STAGE.CANARY,
+            CONTROLLED_SKILL_PILOT_STAGE.ACTIVE_PROBATION,
+          ].includes(target)) ||
+        (from === CONTROLLED_SKILL_PILOT_STAGE.ACTIVE_PROBATION &&
+          target === CONTROLLED_SKILL_PILOT_STAGE.ACTIVE));
+    if (
+      target !== CONTROLLED_PILOT_ROLLBACK &&
+      !progressiveTransition &&
+      FORWARD.get(from) !== target
+    ) {
       fail(
         CONTROLLED_SKILL_PILOT_ERROR.INVALID,
         "non-canonical pilot transition",
@@ -869,7 +1159,7 @@ export class ControlledSkillProductionPilot {
   async _commit(next, type, evidence) {
     const expectedRevision = this._state.revision;
     next.revision = expectedRevision + 1;
-    const stateDigest = hash(next);
+    const stateDigest = digestControlledSkillPilotState(next);
     const event = deepFreeze({
       schema: CONTROLLED_SKILL_PILOT_EVENT_SCHEMA,
       descriptorDigest: this.descriptorDigest,
@@ -882,7 +1172,7 @@ export class ControlledSkillProductionPilot {
       evidence: clone(evidence),
       committedAt: this._timestamp(),
     });
-    const eventDigest = hash(event);
+    const eventDigest = digestControlledSkillPilotEvent(event);
     const acknowledgement = await this._commitState({
       expectedRevision,
       state: deepFreeze(clone(next)),

package/src/lib/evolution/evidence-backed-wiki-maintainer.js

@@ -11,6 +11,7 @@ export const WIKI_PATTERN_STATUS = Object.freeze({
   CORROBORATED: "corroborated",
   CONTRADICTED: "contradicted",
   STALE: "stale",
+  QUARANTINED: "quarantined",
   REVOKED: "revoked",
   TOMBSTONED: "tombstoned",
 });
@@ -47,6 +48,7 @@ const EVIDENCE_FIELDS = new Set([
 const OPERATIONS = new Set([
   "upsert",
   "merge",
+  "quarantine",
   "revoke",
   "tombstone",
   "proposal-impact",
@@ -309,9 +311,11 @@ function rebuildDerivedState(state, effectiveAt, descriptor) {
       (dependents[ref] ??= []).push(pattern.patternId);
     }
     if (
-      [WIKI_PATTERN_STATUS.REVOKED, WIKI_PATTERN_STATUS.TOMBSTONED].includes(
-        pattern.status,
-      )
+      [
+        WIKI_PATTERN_STATUS.QUARANTINED,
+        WIKI_PATTERN_STATUS.REVOKED,
+        WIKI_PATTERN_STATUS.TOMBSTONED,
+      ].includes(pattern.status)
     )
       continue;
     const positive = pattern.positiveEvidence
@@ -340,6 +344,7 @@ function rebuildDerivedState(state, effectiveAt, descriptor) {
       ).toFixed(6),
     );
     if (
+      (pattern.rollbackCount ?? 0) > 0 ||
       positive.length === 0 ||
       expired ||
       pattern.operationalConfidence < descriptor.staleConfidenceFloor
@@ -372,6 +377,7 @@ function rebuildDerivedState(state, effectiveAt, descriptor) {
         ![
           WIKI_PATTERN_STATUS.REVOKED,
           WIKI_PATTERN_STATUS.TOMBSTONED,
+          WIKI_PATTERN_STATUS.QUARANTINED,
           WIKI_PATTERN_STATUS.STALE,
         ].includes(pattern.status),
     )
@@ -402,6 +408,9 @@ function applyUpsert(state, operation, evidenceByRef, effectiveAt) {
       fingerprint(item) === fingerprint(proposed),
   );
   const existing = duplicate ?? state.patterns[proposed.patternId];
+  if (existing?.status === WIKI_PATTERN_STATUS.QUARANTINED) {
+    throw new Error("cannot rewrite a quarantined pattern");
+  }
   const patternId = existing?.patternId ?? proposed.patternId;
   state.patterns[patternId] = {
     ...proposed,
@@ -425,6 +434,7 @@ function applyUpsert(state, operation, evidenceByRef, effectiveAt) {
       ...new Set([...(existing?.supersedes ?? []), ...proposed.supersedes]),
     ].sort(),
     rejectionCount: existing?.rejectionCount ?? 0,
+    rollbackCount: existing?.rollbackCount ?? 0,
     status: WIKI_PATTERN_STATUS.HYPOTHESIS,
     actionable: false,
     evidenceCounts: { positive: 0, negative: 0, trustDomains: 0 },
@@ -489,14 +499,19 @@ function applyOperation(state, operation, evidenceByRef, effectiveAt) {
     });
     return;
   }
-  if (operation.type === "revoke" || operation.type === "tombstone") {
+  if (
+    operation.type === "quarantine" ||
+    operation.type === "revoke" ||
+    operation.type === "tombstone"
+  ) {
     const pattern =
       state.patterns[requiredString(operation.patternId, "patternId")];
-    if (!pattern) throw new Error("cannot revoke an unknown pattern");
-    pattern.status =
-      operation.type === "revoke"
-        ? WIKI_PATTERN_STATUS.REVOKED
-        : WIKI_PATTERN_STATUS.TOMBSTONED;
+    if (!pattern) throw new Error("cannot disposition an unknown pattern");
+    pattern.status = {
+      quarantine: WIKI_PATTERN_STATUS.QUARANTINED,
+      revoke: WIKI_PATTERN_STATUS.REVOKED,
+      tombstone: WIKI_PATTERN_STATUS.TOMBSTONED,
+    }[operation.type];
     pattern.revocationReason = requiredString(operation.reason, "reason");
     pattern.actionable = false;
     appendLog(
@@ -549,8 +564,15 @@ function applyOperation(state, operation, evidenceByRef, effectiveAt) {
       throw new Error(
         `proposal decision references unknown pattern: ${patternId}`,
       );
-    if (decision.outcome === "rejected")
+    if (decision.outcome === "rejected") {
       pattern.rejectionCount = (pattern.rejectionCount ?? 0) + 1;
+      if (
+        evidence.data?.pilotOutcome === "rollback" ||
+        evidence.data?.revocationOutcome === "revoke"
+      ) {
+        pattern.rollbackCount = (pattern.rollbackCount ?? 0) + 1;
+      }
+    }
   }
   appendLog(
     state,