blun-king-cli 9.1.566 → 9.1.569

package/agent-spine-plugin/src/lib/learning-evaluation-registration.js

@@ -0,0 +1,372 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  METRIC_DIRECTIONS, ID_RE, DIGEST_RE, TRIAL_RETRY_EVALUATIONS, STALENESS_BOUND_EVALUATIONS, CANDIDATE_EVIDENCE_BOUND_EVALUATIONS,
+  BLOCKING_DEFECT_BOUND_EVALUATIONS, EVIDENCE_SOURCE_BOUND_EVALUATIONS, EVIDENCE_SOURCE_ATTESTED_EVALUATIONS, CANDIDATE_EVIDENCE_LINEAGE_EVALUATIONS
+} from "./learning-schema.js";
+import {
+  normalizeScope, scopeContains, exactScope, digest, learningTargetForCandidate, evaluationBindingPayload,
+  activeEvaluatorRecord
+} from "./learning-scope-targets.js";
+import {
+  initialTrialDigest, completionPolicyPayload, stalenessPolicyPayload, blockingDefectPolicyPayload, evidenceSourcePolicyPayload, qualifyingEvidenceCount,
+  evidenceSourceAttestations
+} from "./learning-measurement-contracts.js";
+import {
+  candidateEvidencePolicyPayload, eligibleCandidateEvidence, candidateEvidenceCohort, candidateEvidenceLineageReceipts, candidateAdmissionPayload, trialComparisonDigest,
+  trialRetryPayload
+} from "./learning-evidence-contracts.js";
+import {
+  evaluationPayload
+} from "./learning-evaluation-contracts.js";
+import {
+  retryableTrialFailures, trialRetryMatchesState
+} from "./learning-retry-contracts.js";
+import {
+  date, integer, safeText, mutation, evidenceConfidence
+} from "./learning-storage.js";
+
+export async function registerLearningEvaluation({
+  root = process.cwd(), id = `evaluation:${randomUUID()}`, learningId, scope, metric, benchmark,
+  evaluatorIds, evaluatorRoots, expiresAt = null, retryTrialFailureId = null,
+  confirmLocalEvaluation = false, confirmLocalTrialRetry = false,
+  confirmLocalEvidenceSources = false, now = new Date()
+}) {
+  if (!confirmLocalEvaluation) throw new Error("evaluation registration requires explicit local confirmation");
+  if (!ID_RE.test(id || "") || !ID_RE.test(learningId || "")) {
+    throw new Error("evaluation id and learningId must be stable identifiers");
+  }
+  const timestamp = date(now, "now");
+  return mutation(root, (state, _catalog, learningPath) => {
+    const candidate = state.candidates.find((entry) => entry.id === learningId);
+    if (!candidate) throw new Error(`unknown learning candidate: ${learningId}`);
+    if (candidate.kind !== "behavior" || candidate.status !== "candidate" || candidate.requiresLocalReview) {
+      throw new Error("evaluation contracts are limited to unreviewed, low-risk behavior candidates");
+    }
+    const normalizedScope = normalizeScope(scope);
+    if (!scopeContains(candidate.scope, normalizedScope)) throw new Error("evaluation scope does not match the learning candidate");
+    const name = safeText(metric?.name, "evaluation.metric.name", 120);
+    const direction = metric?.direction;
+    if (!METRIC_DIRECTIONS.has(direction)) throw new Error("evaluation.metric.direction must be higher or lower");
+    const digests = {
+      taskDigest: benchmark?.taskDigest,
+      datasetDigest: benchmark?.datasetDigest,
+      protocolDigest: benchmark?.protocolDigest
+    };
+    if (Object.entries(digests).some(([, value]) => !DIGEST_RE.test(value || ""))) {
+      throw new Error("evaluation benchmark digests must be SHA-256 values");
+    }
+    const requestedEvaluators = [...new Set((evaluatorIds || []).map((value) => String(value)))];
+    const normalizedEvaluators = [...requestedEvaluators].sort();
+    const requestedRoots = new Map((evaluatorRoots || []).map((root) => [String(root?.evaluatorId || ""),
+      String(root?.principalDigest || "")]));
+    const requiredEvaluators = Math.max(state.config.minOutcomeReceipts, state.config.canaryReceipts, 2);
+    if (normalizedEvaluators.length < requiredEvaluators || normalizedEvaluators.some((value) => !ID_RE.test(value))) {
+      throw new Error(`evaluation requires at least ${requiredEvaluators} distinct stable evaluator IDs`);
+    }
+    const registeredRoots = normalizedEvaluators.map((evaluatorId) => activeEvaluatorRecord(state, evaluatorId));
+    if (registeredRoots.some((record) => !record)
+      || new Set(registeredRoots.map((record) => record.principalDigest)).size !== registeredRoots.length) {
+      throw new Error("evaluation requires every evaluator root to be active in the locally confirmed registry");
+    }
+    if (requestedRoots.size && (requestedRoots.size !== registeredRoots.length
+      || registeredRoots.some((record) => requestedRoots.get(record.id) !== record.principalDigest))) {
+      throw new Error("evaluation evaluator roots do not match the active local registry");
+    }
+    const normalizedRoots = registeredRoots.map((record) => ({
+      evaluatorId: record.id, principalDigest: record.principalDigest, authority: "context-only"
+    })).sort((a, b) => a.evaluatorId.localeCompare(b.evaluatorId));
+    const expiry = date(expiresAt || new Date(new Date(timestamp).getTime()
+      + state.config.outcomeMaxAgeDays * 86400000), "evaluation.expiresAt");
+    if (new Date(expiry).getTime() <= new Date(timestamp).getTime()
+      || new Date(expiry).getTime() > new Date(timestamp).getTime() + 365 * 86400000) {
+      throw new Error("evaluation expiry must be in the future and no more than 365 days away");
+    }
+    const normalizedMetric = { name, direction };
+    const normalizedBenchmark = {
+      ...digests, minCases: integer(benchmark?.minCases, "evaluation.benchmark.minCases", 1, 1000000)
+    };
+    const selectedRoots = requestedEvaluators.slice(0, requiredEvaluators).map((evaluatorId) => {
+      const rootRecord = registeredRoots.find((record) => record.id === evaluatorId);
+      return { evaluatorId, evaluatorRootDigest: rootRecord.principalDigest };
+    });
+    const trialsForPhase = (phase) => selectedRoots.map((rootRecord, index) => {
+      const trial = {
+        slot: index + 1,
+        evaluatorId: rootRecord.evaluatorId,
+        evaluatorRootDigest: rootRecord.evaluatorRootDigest,
+        runId: `run:initial:${phase}:${digest([id, learningId, normalizedScope, normalizedMetric,
+          normalizedBenchmark, phase, index + 1, rootRecord.evaluatorId,
+          rootRecord.evaluatorRootDigest]).slice(0, 32)}`,
+        caseCount: normalizedBenchmark.minCases,
+        authority: "context-only"
+      };
+      return { ...trial, trialDigest: initialTrialDigest({
+        evaluationId: id, learningId, scope: normalizedScope, metric: normalizedMetric,
+        benchmark: normalizedBenchmark, phase, slot: trial.slot, evaluatorId: trial.evaluatorId,
+        evaluatorRootDigest: trial.evaluatorRootDigest, runId: trial.runId, caseCount: trial.caseCount
+      }) };
+    });
+    const initialTrials = {
+      schema: "agentspine.learning-initial-trials/v1",
+      mode: "first-admitted-trials",
+      requiredTrials: requiredEvaluators,
+      benchmarkDigest: digest(normalizedBenchmark),
+      before: trialsForPhase("before"),
+      after: trialsForPhase("after"),
+      authority: "context-only"
+    };
+    let thresholds = {
+      minImprovement: state.config.minImprovement,
+      regressionTolerance: state.config.regressionTolerance,
+      beforeReceipts: requiredEvaluators,
+      afterReceipts: requiredEvaluators,
+      minConfidence: state.config.minConfidence,
+      minEvidence: Math.max(2, state.config.minEvidence)
+    };
+    const pairing = {
+      mode: "same-evaluator",
+      maxOutcomesPerEvaluatorPerPhase: 1,
+      matchMeasurementKind: true,
+      matchCaseCount: true,
+      authority: "context-only"
+    };
+    const target = learningTargetForCandidate(candidate);
+    const stalenessPolicyPayloadValue = stalenessPolicyPayload({
+      outcomeMaxAgeDays: state.config.outcomeMaxAgeDays,
+      canaryTtlDays: state.config.canaryTtlDays
+    });
+    const stalenessPolicy = {
+      ...stalenessPolicyPayloadValue,
+      digest: digest(stalenessPolicyPayloadValue)
+    };
+    const blockingDefectPolicyPayloadValue = blockingDefectPolicyPayload();
+    const blockingDefectPolicy = {
+      ...blockingDefectPolicyPayloadValue,
+      digest: digest(blockingDefectPolicyPayloadValue)
+    };
+    const evidenceSourcePolicyPayloadValue = evidenceSourcePolicyPayload(
+      "agentspine.learning-evidence-source-policy/v2");
+    let evidenceSourcePolicy = {
+      ...evidenceSourcePolicyPayloadValue,
+      digest: digest(evidenceSourcePolicyPayloadValue)
+    };
+    const retryable = retryableTrialFailures(state, candidate);
+    let retry = null;
+    let evaluationSchema = "agentspine.learning-evaluation/v28";
+    if (retryable.length) {
+      if (!confirmLocalTrialRetry) {
+        throw new Error("a repeated failed learning requires explicit local trial-retry confirmation");
+      }
+      if (!ID_RE.test(retryTrialFailureId || "")) {
+        throw new Error("retryTrialFailureId must identify the revoked failure being retried");
+      }
+      const selected = retryable.find((entry) => entry.failure.id === retryTrialFailureId);
+      const latest = retryable[retryable.length - 1];
+      if (!selected || selected.revocation.id !== latest.revocation.id) {
+        throw new Error("trial retry must bind the latest matching revoked failure");
+      }
+      const predecessorEvaluation = state.evaluations.find((entry) =>
+        entry.id === selected.failure.evaluationId && entry.digest === selected.failure.evaluationDigest);
+      if (!predecessorEvaluation) {
+        throw new Error("trial retry predecessor evaluation is missing or changed");
+      }
+      if (EVIDENCE_SOURCE_BOUND_EVALUATIONS.has(predecessorEvaluation.schema)
+        && !EVIDENCE_SOURCE_ATTESTED_EVALUATIONS.has(predecessorEvaluation.schema)) {
+        evidenceSourcePolicy = predecessorEvaluation.evidenceSourcePolicy;
+      }
+      if (state.trialRetryExhaustions.some((receipt) => receipt.trialFailureId === selected.failure.id
+        && receipt.trialFailureDigest === selected.failure.digest)) {
+        throw new Error("trial retry budget is exhausted by an immutable terminal receipt");
+      }
+      if (TRIAL_RETRY_EVALUATIONS.has(predecessorEvaluation.schema)) {
+        throw new Error("trial retry budget is exhausted; a failed corrective Canary cannot be retried again");
+      }
+      evaluationSchema = EVIDENCE_SOURCE_ATTESTED_EVALUATIONS.has(predecessorEvaluation.schema)
+        ? "agentspine.learning-evaluation/v29"
+        : EVIDENCE_SOURCE_BOUND_EVALUATIONS.has(predecessorEvaluation.schema)
+        ? "agentspine.learning-evaluation/v25"
+        : BLOCKING_DEFECT_BOUND_EVALUATIONS.has(predecessorEvaluation.schema)
+          ? "agentspine.learning-evaluation/v23"
+          : STALENESS_BOUND_EVALUATIONS.has(predecessorEvaluation.schema)
+          ? "agentspine.learning-evaluation/v21"
+          : "agentspine.learning-evaluation/v13";
+      const comparisonDigest = trialComparisonDigest({
+        schema: evaluationSchema,
+        metric: normalizedMetric,
+        benchmark: normalizedBenchmark,
+        evaluatorRoots: normalizedRoots,
+        thresholds,
+        pairing,
+        stalenessPolicy,
+        blockingDefectPolicy,
+        evidenceSourcePolicy
+      });
+      if (comparisonDigest !== trialComparisonDigest(predecessorEvaluation, selected.predecessor.promotion)) {
+        throw new Error("trial retry objective contract drift is not allowed");
+      }
+      const retryPayload = trialRetryPayload({
+        schema: "agentspine.learning-trial-retry/v3",
+        trialFailureId: selected.failure.id,
+        trialFailureDigest: selected.failure.digest,
+        trialFailureRevocationId: selected.revocation.id,
+        trialFailureRevocationDigest: selected.revocation.digest,
+        predecessorLearningId: selected.predecessor.id,
+        predecessorEvaluationId: predecessorEvaluation.id,
+        predecessorEvaluationDigest: predecessorEvaluation.digest,
+        comparisonDigest,
+        rootEvaluationId: predecessorEvaluation.id,
+        rootEvaluationDigest: predecessorEvaluation.digest,
+        attempt: 2,
+        maxAttempts: 2,
+        learningId: candidate.id,
+        targetDigest: target.digest,
+        scopeDigest: digest(candidate.scope),
+        minimumEvidenceObservedAt: selected.revocation.revokedAt,
+        admittedAt: timestamp
+      });
+      retry = { ...retryPayload, digest: digest(retryPayload) };
+    } else if (retryTrialFailureId !== null || confirmLocalTrialRetry) {
+      throw new Error("trial retry confirmation does not match a revoked failure for this exact learning scope");
+    }
+    const evidencePolicyPayloadValue = candidateEvidencePolicyPayload({
+      maxAgeDays: stalenessPolicy.outcomeMaxAgeDays,
+      minimumIndependentEvidence: thresholds.minEvidence
+    });
+    const evidencePolicy = {
+      ...evidencePolicyPayloadValue,
+      digest: digest(evidencePolicyPayloadValue)
+    };
+    const eligibleEvidence = eligibleCandidateEvidence(candidate, timestamp, evidencePolicy.maxAgeDays);
+    const evidenceCohort = candidateEvidenceCohort(eligibleEvidence);
+    if (EVIDENCE_SOURCE_ATTESTED_EVALUATIONS.has(evaluationSchema) && !confirmLocalEvidenceSources) {
+      throw new Error("qualifying evidence sources require explicit local confirmation");
+    }
+    const sourceAttestations = EVIDENCE_SOURCE_ATTESTED_EVALUATIONS.has(evaluationSchema)
+      ? evidenceSourceAttestations(evidenceCohort, timestamp) : [];
+    const evidenceCount = new Set(evidenceCohort.map((entry) => entry.independenceDigest)).size;
+    const observedConfidence = evidenceConfidence(eligibleEvidence);
+    if (candidate.evidence.some((entry) => new Date(entry.observedAt).getTime() > new Date(timestamp).getTime())) {
+      throw new Error("evaluation candidate evidence cannot be observed in the future");
+    }
+    if (EVIDENCE_SOURCE_BOUND_EVALUATIONS.has(evaluationSchema)
+      && qualifyingEvidenceCount(evidenceCohort, evidenceSourcePolicy, sourceAttestations)
+        < evidenceSourcePolicy.minimumQualifyingEvidence) {
+      throw new Error("evaluation requires fresh explicit-user or objective-test evidence; interaction- or document-only cohorts are insufficient");
+    }
+    if (!retry && (observedConfidence < thresholds.minConfidence || evidenceCount < thresholds.minEvidence)) {
+      throw new Error("evaluation requires a candidate that already satisfies the frozen confidence and evidence gates");
+    }
+    const evidenceLineage = CANDIDATE_EVIDENCE_LINEAGE_EVALUATIONS.has(evaluationSchema)
+      ? candidateEvidenceLineageReceipts({
+        learningId: candidate.id,
+        evaluationId: id,
+        attestations: sourceAttestations,
+        targetDigest: target.digest,
+        scopeDigest: digest(normalizedScope),
+        admittedAt: timestamp
+      }) : [];
+    const liveIdempotentEvaluation = state.evaluations.some((entry) => entry.id === id
+      && entry.learningId === candidate.id);
+    for (const lineage of evidenceLineage) {
+      const existingLineage = state.candidateEvidenceLineage.find((entry) =>
+        entry.scopeDigest === lineage.scopeDigest
+        && (entry.evidenceDigest === lineage.evidenceDigest
+          || entry.independenceDigest === lineage.independenceDigest));
+      if (existingLineage && (!liveIdempotentEvaluation || existingLineage.evaluationId !== id
+        || existingLineage.learningId !== candidate.id || existingLineage.digest !== lineage.digest)) {
+        throw new Error("qualifying candidate evidence was already admitted in this exact scope and cannot be replayed");
+      }
+    }
+    const candidateAdmissionPayloadValue = candidateAdmissionPayload({
+      schema: EVIDENCE_SOURCE_ATTESTED_EVALUATIONS.has(evaluationSchema)
+        ? CANDIDATE_EVIDENCE_LINEAGE_EVALUATIONS.has(evaluationSchema)
+          ? "agentspine.learning-candidate-admission/v4"
+          : "agentspine.learning-candidate-admission/v3"
+        : CANDIDATE_EVIDENCE_BOUND_EVALUATIONS.has(evaluationSchema)
+        ? "agentspine.learning-candidate-admission/v2"
+        : "agentspine.learning-candidate-admission/v1",
+      learningId: candidate.id,
+      targetDigest: target.digest,
+      scopeDigest: digest(normalizedScope),
+      minConfidence: thresholds.minConfidence,
+      minEvidence: thresholds.minEvidence,
+      observedConfidence,
+      evidenceCount,
+      evidencePolicy,
+      evidenceCohort,
+      evidenceSourceAttestations: sourceAttestations,
+      evidenceLineageDigest: evidenceLineage.length ? digest(evidenceLineage) : undefined,
+      admittedAt: timestamp
+    });
+    const candidateAdmission = {
+      ...candidateAdmissionPayloadValue,
+      digest: digest(candidateAdmissionPayloadValue)
+    };
+    const completionPolicyPayloadValue = completionPolicyPayload({
+      deliveryTimeoutMs: 5 * 60_000,
+      outcomeTimeoutMs: state.config.initialTrialOutcomeTimeoutMinutes * 60_000
+    });
+    const completionPolicy = {
+      ...completionPolicyPayloadValue,
+      digest: digest(completionPolicyPayloadValue)
+    };
+    const payload = evaluationPayload({
+      schema: evaluationSchema,
+      id, learningId, scope: normalizedScope, metric: normalizedMetric,
+      benchmark: normalizedBenchmark,
+      evaluatorIds: normalizedEvaluators,
+      evaluatorRoots: normalizedRoots,
+      thresholds,
+      pairing,
+      initialTrials,
+      target,
+      completionPolicy,
+      stalenessPolicy,
+      blockingDefectPolicy,
+      evidenceSourcePolicy,
+      candidateAdmission,
+      retry,
+      registeredAt: timestamp, expiresAt: expiry
+    });
+    const contract = { ...payload, digest: digest(payload) };
+    if (retry && !trialRetryMatchesState(state, contract)) {
+      throw new Error("trial retry requires a fresh candidate and independently observed evidence after revocation");
+    }
+    if (retry && (observedConfidence < thresholds.minConfidence || evidenceCount < thresholds.minEvidence)) {
+      throw new Error("evaluation requires a candidate that already satisfies the frozen confidence and evidence gates");
+    }
+    const existing = state.evaluations.find((entry) => entry.id === id);
+    if (existing) {
+      if (existing.digest === contract.digest) {
+        const binding = state.evaluationBindings.find((entry) => entry.evaluationId === existing.id) || null;
+        return { contract: existing, binding, learningPath, unchanged: true };
+      }
+      throw new Error("evaluation contract IDs are immutable");
+    }
+    if (retry && state.evaluations.some((entry) => TRIAL_RETRY_EVALUATIONS.has(entry.schema)
+      && entry.retry.trialFailureRevocationId === retry.trialFailureRevocationId)) {
+      throw new Error("the revoked trial failure already has an immutable retry contract");
+    }
+    if (state.evaluations.some((entry) => entry.learningId === learningId
+      && exactScope(entry.scope, normalizedScope) && new Date(entry.expiresAt).getTime() >= new Date(timestamp).getTime())) {
+      throw new Error("an active evaluation contract already exists for this learning and exact scope");
+    }
+    state.evaluations.push(contract);
+    state.evaluations.sort((a, b) => a.id.localeCompare(b.id));
+    state.candidateEvidenceLineage.push(...evidenceLineage);
+    state.candidateEvidenceLineage.sort((a, b) => a.evidenceDigest.localeCompare(b.evidenceDigest)
+      || a.scopeDigest.localeCompare(b.scopeDigest));
+    const bindingPayload = evaluationBindingPayload({
+      evaluationId: contract.id,
+      evaluationDigest: contract.digest,
+      evaluators: registeredRoots.map((record) => ({ evaluatorId: record.id,
+        principalDigest: record.principalDigest, registryDigest: record.digest, authority: "context-only" }))
+        .sort((a, b) => a.evaluatorId.localeCompare(b.evaluatorId)),
+      boundAt: timestamp
+    });
+    const binding = { ...bindingPayload, digest: digest(bindingPayload) };
+    state.evaluationBindings.push(binding);
+    state.evaluationBindings.sort((a, b) => a.evaluationId.localeCompare(b.evaluationId));
+    return { contract, binding, learningPath, unchanged: false };
+  });
+}

package/agent-spine-plugin/src/lib/learning-evaluation-revocation.js

@@ -0,0 +1,292 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  ID_RE, DIGEST_RE, REGISTRY_BOUND_EVALUATIONS, EVIDENCE_SOURCE_ATTESTED_EVALUATIONS, EVALUATION_REVOCATION_REASONS, EVIDENCE_SOURCE_ATTESTATION_REVOCATION_REASONS,
+  VALIDATION_REVOCATION_REASONS
+} from "./learning-schema.js";
+import {
+  digest, learningTargetForCandidate, evaluationRevocationPayload, revokedEvaluation
+} from "./learning-scope-targets.js";
+import {
+  revokedEvaluationForCandidate, revalidationWindowPayload, revalidationTrialDigest, storedValidationLeaseStructure
+} from "./learning-validation-contracts.js";
+import {
+  validationLeaseRecord, validationLeaseChain, validationRevocationPayload, revokedValidation, validationLeaseState
+} from "./learning-validation-runtime.js";
+import {
+  evaluationStalenessPolicy, evidenceSourceAttestations, evidenceSourceAttestationRevocationPayload, revokedEvidenceSourceAttestation, revokedEvidenceSourceAttestationForCandidate
+} from "./learning-measurement-contracts.js";
+import {
+  revokedApplicationForCandidate, revokedOutcomeForCandidate
+} from "./learning-delivery-contracts.js";
+import {
+  date, safeText, mutation, preserve
+} from "./learning-storage.js";
+
+export async function revokeLearningEvaluation({
+  root = process.cwd(), evaluationId, reasonCode, reason, confirmation, now = new Date()
+}) {
+  if (confirmation !== "local-evaluation-revocation-confirmed") {
+    throw new Error("evaluation revocation requires explicit local confirmation");
+  }
+  if (!ID_RE.test(evaluationId || "")) throw new Error("evaluationId must be a stable identifier");
+  if (!EVALUATION_REVOCATION_REASONS.has(reasonCode)) {
+    throw new Error("reasonCode must be benchmark-invalid, protocol-invalid, scope-invalid, threshold-invalid, duplicate, or other");
+  }
+  const revokeReason = safeText(reason, "reason", 500);
+  const timestamp = date(now, "now");
+  return mutation(root, (state, _catalog, learningPath) => {
+    const evaluation = state.evaluations.find((entry) => entry.id === evaluationId);
+    if (!evaluation) throw new Error(`unknown learning evaluation: ${evaluationId}`);
+    const candidate = state.candidates.find((entry) => entry.id === evaluation.learningId);
+    if (!candidate) throw new Error("evaluation revocation requires its immutable candidate lineage");
+    const binding = state.evaluationBindings.find((entry) => entry.evaluationId === evaluation.id
+      && entry.evaluationDigest === evaluation.digest) || null;
+    if (REGISTRY_BOUND_EVALUATIONS.has(evaluation.schema) && !binding) {
+      throw new Error("evaluation revocation requires its immutable evaluator binding");
+    }
+    const targetDigest = learningTargetForCandidate(candidate).digest;
+    const reasonDigest = digest(revokeReason);
+    const existing = revokedEvaluation(state, evaluationId);
+    if (existing) {
+      if (existing.reasonCode !== reasonCode || existing.reasonDigest !== reasonDigest
+        || existing.learningId !== candidate.id || existing.evaluationDigest !== evaluation.digest
+        || existing.evaluatorBindingDigest !== (binding?.digest || null)
+        || existing.targetDigest !== targetDigest) {
+        throw new Error("learning evaluation revocations are immutable");
+      }
+      return { receipt: existing, learningPath, unchanged: true, authority: "context-only" };
+    }
+    const id = `evaluation-revocation:${createHash("sha256")
+      .update(`${evaluation.id}\0${evaluation.digest}\0${targetDigest}`).digest("hex").slice(0, 32)}`;
+    const payload = evaluationRevocationPayload({
+      id,
+      learningId: candidate.id,
+      evaluationId: evaluation.id,
+      evaluationDigest: evaluation.digest,
+      evaluatorBindingDigest: binding?.digest || null,
+      targetDigest,
+      reasonCode,
+      reasonDigest,
+      revokedAt: timestamp
+    });
+    const receipt = { ...payload, digest: digest(payload) };
+    state.evaluationRevocations.push(receipt);
+    state.evaluationRevocations.sort((a, b) => a.id.localeCompare(b.id));
+    return { receipt, learningPath, unchanged: false, authority: "context-only" };
+  });
+}
+
+export async function revokeLearningEvidenceSourceAttestation({
+  root = process.cwd(), evaluationId, evidenceDigest, reasonCode, reason, confirmation, now = new Date()
+}) {
+  if (confirmation !== "local-evidence-source-attestation-revocation-confirmed") {
+    throw new Error("evidence source attestation revocation requires explicit local confirmation");
+  }
+  if (!ID_RE.test(evaluationId || "")) throw new Error("evaluationId must be a stable identifier");
+  if (!DIGEST_RE.test(evidenceDigest || "")) throw new Error("evidenceDigest must be one SHA-256 digest");
+  if (!EVIDENCE_SOURCE_ATTESTATION_REVOCATION_REASONS.has(reasonCode)) {
+    throw new Error("reasonCode must be source-class-invalid, confirmation-invalid, scope-invalid, duplicate, or other");
+  }
+  const revokeReason = safeText(reason, "reason", 500);
+  const timestamp = date(now, "now");
+  return mutation(root, (state, _catalog, learningPath) => {
+    const evaluation = state.evaluations.find((entry) => entry.id === evaluationId);
+    if (!evaluation || !EVIDENCE_SOURCE_ATTESTED_EVALUATIONS.has(evaluation.schema)) {
+      throw new Error(`unknown source-attested learning evaluation: ${evaluationId}`);
+    }
+    const candidate = state.candidates.find((entry) => entry.id === evaluation.learningId);
+    const attestation = evaluation.candidateAdmission.evidenceSourceAttestations.find((entry) =>
+      entry.evidenceDigest === evidenceDigest);
+    if (!candidate || !attestation) {
+      throw new Error("source attestation revocation requires its exact immutable candidate and evidence binding");
+    }
+    const targetDigest = learningTargetForCandidate(candidate).digest;
+    const scopeDigest = digest(evaluation.scope);
+    const reasonDigest = digest(revokeReason);
+    const existing = revokedEvidenceSourceAttestation(state, evaluationId, evidenceDigest);
+    if (existing) {
+      if (existing.reasonCode !== reasonCode || existing.reasonDigest !== reasonDigest
+        || existing.learningId !== candidate.id || existing.evaluationDigest !== evaluation.digest
+        || existing.candidateAdmissionDigest !== evaluation.candidateAdmission.digest
+        || existing.independenceDigest !== attestation.independenceDigest
+        || existing.sourceClass !== attestation.sourceClass || existing.targetDigest !== targetDigest
+        || existing.scopeDigest !== scopeDigest) {
+        throw new Error("learning evidence source attestation revocations are immutable");
+      }
+      return { receipt: existing, learningPath, unchanged: true, authority: "context-only" };
+    }
+    const id = `evidence-source-attestation-revocation:${createHash("sha256")
+      .update(`${evaluation.id}\0${evaluation.digest}\0${evidenceDigest}`).digest("hex").slice(0, 32)}`;
+    const payload = evidenceSourceAttestationRevocationPayload({
+      id,
+      learningId: candidate.id,
+      evaluationId: evaluation.id,
+      evaluationDigest: evaluation.digest,
+      candidateAdmissionDigest: evaluation.candidateAdmission.digest,
+      evidenceDigest,
+      independenceDigest: attestation.independenceDigest,
+      sourceClass: attestation.sourceClass,
+      targetDigest,
+      scopeDigest,
+      reasonCode,
+      reasonDigest,
+      revokedAt: timestamp
+    });
+    const receipt = { ...payload, digest: digest(payload) };
+    state.evidenceSourceAttestationRevocations.push(receipt);
+    state.evidenceSourceAttestationRevocations.sort((a, b) => a.id.localeCompare(b.id));
+    return { receipt, learningPath, unchanged: false, authority: "context-only" };
+  });
+}
+
+export async function revokeLearningValidation({
+  root = process.cwd(), validationLeaseId, reasonCode, reason, confirmation, now = new Date()
+}) {
+  if (confirmation !== "local-validation-revocation-confirmed") {
+    throw new Error("validation revocation requires explicit local confirmation");
+  }
+  if (!ID_RE.test(validationLeaseId || "")) throw new Error("validationLeaseId must be a stable identifier");
+  if (!VALIDATION_REVOCATION_REASONS.has(reasonCode)) {
+    throw new Error("reasonCode must be decision-invalid, cohort-invalid, binding-invalid, scope-invalid, duplicate, or other");
+  }
+  const revokeReason = safeText(reason, "reason", 500);
+  const timestamp = date(now, "now");
+  return mutation(root, (state, _catalog, learningPath) => {
+    const lease = validationLeaseRecord(state, validationLeaseId);
+    if (!lease || !storedValidationLeaseStructure(lease)) {
+      throw new Error(`unknown learning validation lease: ${validationLeaseId}`);
+    }
+    const candidate = state.candidates.find((entry) => entry.id === lease.learningId);
+    const evaluation = state.evaluations.find((entry) => entry.id === lease.evaluationId
+      && entry.digest === lease.evaluationDigest);
+    const binding = state.evaluationBindings.find((entry) => entry.evaluationId === lease.evaluationId
+      && entry.evaluationDigest === lease.evaluationDigest);
+    if (!candidate || !evaluation || !binding || binding.digest !== lease.evaluatorRegistryBindingDigest) {
+      throw new Error("validation revocation requires its immutable candidate, evaluation, and evaluator binding");
+    }
+    const activeChain = validationLeaseChain(state, candidate);
+    if (!activeChain.some((entry) => entry.id === lease.id && entry.digest === lease.digest)) {
+      throw new Error("validation revocation requires a lease in the candidate's current immutable validation chain");
+    }
+    const targetDigest = learningTargetForCandidate(candidate).digest;
+    const scopeDigest = digest(lease.scope);
+    const reasonDigest = digest(revokeReason);
+    const existing = revokedValidation(state, validationLeaseId);
+    if (existing) {
+      if (existing.reasonCode !== reasonCode || existing.reasonDigest !== reasonDigest
+        || existing.learningId !== candidate.id || existing.evaluationId !== evaluation.id
+        || existing.evaluationDigest !== evaluation.digest || existing.evaluatorBindingDigest !== binding.digest
+        || existing.validationLeaseDigest !== lease.digest || existing.targetDigest !== targetDigest
+        || existing.scopeDigest !== scopeDigest) {
+        throw new Error("learning validation revocations are immutable");
+      }
+      return { receipt: existing, learningPath, unchanged: true, authority: "context-only" };
+    }
+    const id = `validation-revocation:${createHash("sha256")
+      .update(`${lease.id}\0${lease.digest}\0${targetDigest}`).digest("hex").slice(0, 32)}`;
+    const payload = validationRevocationPayload({
+      id,
+      learningId: candidate.id,
+      evaluationId: evaluation.id,
+      evaluationDigest: evaluation.digest,
+      evaluatorBindingDigest: binding.digest,
+      validationLeaseId: lease.id,
+      validationLeaseDigest: lease.digest,
+      targetDigest,
+      scopeDigest,
+      reasonCode,
+      reasonDigest,
+      revokedAt: timestamp
+    });
+    const receipt = { ...payload, digest: digest(payload) };
+    state.validationRevocations.push(receipt);
+    state.validationRevocations.sort((a, b) => a.id.localeCompare(b.id));
+    return { receipt, learningPath, unchanged: false, authority: "context-only" };
+  });
+}
+
+export async function beginLearningRevalidation({
+  root = process.cwd(), learningId, confirmLocalValidation = false, now = new Date()
+}) {
+  if (!confirmLocalValidation) throw new Error("revalidation requires explicit local confirmation");
+  if (!ID_RE.test(learningId || "")) throw new Error("learningId is required");
+  const timestamp = date(now, "now");
+  return mutation(root, (state, _catalog, learningPath) => {
+    const candidate = state.candidates.find((entry) => entry.id === learningId);
+    if (revokedEvaluationForCandidate(state, candidate)) {
+      throw new Error("revalidation baseline contains an explicitly revoked evaluation contract");
+    }
+    if (revokedEvidenceSourceAttestationForCandidate(state, candidate)) {
+      throw new Error("revalidation baseline contains an explicitly revoked evidence source attestation");
+    }
+    if (revokedApplicationForCandidate(state, candidate)) {
+      throw new Error("revalidation baseline contains an explicitly revoked application");
+    }
+    if (revokedOutcomeForCandidate(state, candidate)) {
+      throw new Error("revalidation baseline contains an explicitly revoked outcome");
+    }
+    const validation = validationLeaseState(state, candidate, timestamp);
+    if (validation.status !== "active"
+      || !REGISTRY_BOUND_EVALUATIONS.has(validation.evaluation?.schema)) {
+      throw new Error("revalidation requires one current registry-bound validation lease");
+    }
+    const canary = candidate.promotion.canary;
+    if (canary.revalidation?.status === "active"
+      && new Date(canary.revalidation.expiresAt).getTime() > new Date(timestamp).getTime()) {
+      return { candidate, revalidation: canary.revalidation, learningPath, unchanged: true };
+    }
+    const possibleExpiry = Math.min(new Date(validation.evaluation.expiresAt).getTime(),
+      new Date(timestamp).getTime()
+        + evaluationStalenessPolicy(validation.evaluation, state.config).canaryTtlDays * 86400000);
+    if (possibleExpiry <= new Date(validation.lease.expiresAt).getTime()) {
+      throw new Error("revalidation cannot extend evidence within the current evaluation contract window");
+    }
+    const baselineReferences = validation.lease.schema === "agentspine.learning-validation/v1"
+      ? validation.lease.beforeOutcomes : validation.lease.baselineOutcomes;
+    const baselines = baselineReferences.map((reference) => state.outcomes.find((outcome) =>
+      outcome.id === reference.id && outcome.digest === reference.digest));
+    if (baselines.some((outcome) => outcome?.schema !== "agentspine.learning-outcome/v9"
+      || !DIGEST_RE.test(outcome.measurement?.evaluatorRootDigest || ""))) {
+      throw new Error("revalidation requires a complete root-bound frozen baseline cohort");
+    }
+    const orderedRoots = [...baselines].sort((a, b) => a.measurement.evaluatorId.localeCompare(b.measurement.evaluatorId))
+      .map((outcome, index) => {
+        const trial = {
+          evaluationId: validation.evaluation.id,
+          evaluationDigest: validation.evaluation.digest,
+          predecessorValidationId: validation.lease.id,
+          predecessorValidationDigest: validation.lease.digest,
+          slot: index + 1,
+          evaluatorId: outcome.measurement.evaluatorId,
+          evaluatorRootDigest: outcome.measurement.evaluatorRootDigest,
+          runId: `run:revalidation:${randomUUID()}`,
+          benchmark: validation.evaluation.benchmark,
+          caseCount: outcome.coverage.caseCount
+        };
+        return { slot: trial.slot, evaluatorId: trial.evaluatorId,
+          evaluatorRootDigest: trial.evaluatorRootDigest, runId: trial.runId,
+          caseCount: trial.caseCount, trialDigest: revalidationTrialDigest(trial), authority: "context-only" };
+      });
+    const revalidationPayload = revalidationWindowPayload({
+      schema: "agentspine.learning-revalidation-window/v4",
+      id: `revalidation:${randomUUID()}`,
+      status: "active",
+      startedAt: timestamp,
+      expiresAt: validation.lease.expiresAt,
+      predecessorValidationId: validation.lease.id,
+      predecessorValidationDigest: validation.lease.digest,
+      selection: { mode: "first-admitted-trials", requiredDeliveries: orderedRoots.length,
+        evaluatorRoots: orderedRoots, authority: "context-only" }
+    });
+    const revalidation = { ...revalidationPayload, digest: digest(revalidationPayload) };
+    preserve(state, "learning-candidate", candidate, timestamp);
+    const updated = {
+      ...candidate,
+      promotion: { ...candidate.promotion, canary: { ...canary, revalidation } },
+      updatedAt: timestamp,
+      authority: "context-only"
+    };
+    state.candidates = state.candidates.map((entry) => entry.id === learningId ? updated : entry);
+    return { candidate: updated, revalidation, learningPath, unchanged: false };
+  });
+}