blun-king-cli 9.1.567 → 9.1.570

package/agent-spine-plugin/src/lib/learning-storage.js

@@ -0,0 +1,203 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildCatalog } from "./catalog.js";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { projectStateDir } from "./paths.js";
+import {
+  EVIDENCE_TYPES, PRIVACY, ID_RE, MAX_STATE_BYTES, SECRET_RE, AUTHORITY_ASSERTION_RE,
+  emptyLearning
+} from "./learning-schema.js";
+import {
+  normalizeState
+} from "./learning-state-upgrade.js";
+import {
+  validConfig
+} from "./learning-scope-targets.js";
+import {
+  visible
+} from "./learning-context.js";
+
+export function date(value, field = "date") {
+  const parsed = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(parsed.getTime())) throw new Error(`${field} must be a valid date`);
+  return parsed.toISOString();
+}
+
+export function number(value, field, minimum, maximum) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < minimum || parsed > maximum) {
+    throw new Error(`${field} must be between ${minimum} and ${maximum}`);
+  }
+  return parsed;
+}
+
+export function integer(value, field, minimum, maximum) {
+  const parsed = number(value, field, minimum, maximum);
+  if (!Number.isInteger(parsed)) throw new Error(`${field} must be an integer`);
+  return parsed;
+}
+
+export function relativePath(value, field) {
+  if (value === null || value === undefined || value === "") return null;
+  if (typeof value !== "string") throw new Error(`${field} must be a project-relative path`);
+  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (normalized.startsWith("/") || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+    throw new Error(`${field} must be a project-relative path`);
+  }
+  return normalized;
+}
+
+export function safeText(value, field, maximum) {
+  if (!value || typeof value !== "string") throw new Error(`${field} is required`);
+  const text = value.trim().slice(0, maximum);
+  if (SECRET_RE.test(text)) throw new Error(`${field} appears to contain a secret and cannot enter learning state`);
+  return text;
+}
+
+export function assertSafeClaim(claim) {
+  if (AUTHORITY_ASSERTION_RE.test(claim)) {
+    throw new Error("authority and access claims cannot become learned context");
+  }
+}
+
+export function isGroupMember(graph, groupId, entityId) {
+  if (!entityId || entityId === groupId) return true;
+  return graph.entityEdges.some((edge) => edge.relation === "member-of" && edge.privacy !== "private" && (
+    (edge.from === entityId && edge.to === groupId) || (edge.to === entityId && edge.from === groupId)
+  ));
+}
+
+export function validateScope(privacy, groupId, graph, subjectId) {
+  if (!PRIVACY.has(privacy)) throw new Error(`unsupported privacy scope: ${privacy}`);
+  if (subjectId !== null && !graph.entities.some((entity) => entity.id === subjectId)) throw new Error(`unknown subject entity: ${subjectId}`);
+  if (privacy === "group") {
+    if (!groupId) throw new Error("group privacy requires groupId");
+    const group = graph.entities.find((entity) => entity.id === groupId);
+    if (!group || group.kind !== "group") throw new Error(`unknown group entity: ${groupId}`);
+    if (!isGroupMember(graph, groupId, subjectId)) throw new Error(`subject is not a visible member of group: ${groupId}`);
+  } else if (groupId !== null && groupId !== undefined) {
+    throw new Error("groupId is only valid with group privacy");
+  }
+}
+
+export async function readState(path, root) {
+  try {
+    const metadata = await stat(path);
+    if (metadata.size > MAX_STATE_BYTES) throw new Error("learning state exceeds the 5 MiB read limit");
+    return normalizeState(JSON.parse(await readFile(path, "utf8")), root);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return emptyLearning(root);
+  }
+}
+
+export async function loadLearning(root = process.cwd(), providedCatalog = null) {
+  const catalog = providedCatalog || await buildCatalog(root);
+  const directory = await projectStateDir(catalog.root);
+  const learningPath = join(directory, "learning.json");
+  return { learning: await readState(learningPath, catalog.root), learningPath, catalog };
+}
+
+export async function inspectLearning(root = process.cwd(), providedCatalog = null) {
+  const catalog = providedCatalog || await buildCatalog(root);
+  const directory = await projectStateDir(catalog.root);
+  const learningPath = join(directory, "learning.json");
+  try {
+    return { learning: await readState(learningPath, catalog.root), learningPath, catalog, error: null };
+  } catch (error) {
+    return { learning: emptyLearning(catalog.root), learningPath, catalog, error: error.message };
+  }
+}
+
+export async function saveState(state, path, beforeReplace = null) {
+  const content = `${JSON.stringify(state, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_STATE_BYTES) throw new Error("learning state exceeds 5 MiB; reject or delete old candidates first");
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, content, { mode: 0o600 });
+  try {
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        await beforeReplace?.();
+        await rename(temporary, path);
+        break;
+      } catch (error) {
+        const transientWindowsReplace = process.platform === "win32"
+          && ["EACCES", "EBUSY", "EPERM"].includes(error.code);
+        if (!transientWindowsReplace || attempt >= 7) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 10 * (attempt + 1)));
+      }
+    }
+  } catch (error) {
+    await unlink(temporary).catch((cleanupError) => {
+      if (cleanupError.code !== "ENOENT") error.cleanupError = cleanupError;
+    });
+    throw error;
+  }
+}
+
+export async function withLock(path, root, task) {
+  const lockPath = `${path}.lock`;
+  return withOwnedFileLock(lockPath, async ({ assertOwned }) => {
+    const state = await readState(path, root);
+    if (!validConfig(state.config)) throw new Error("learning configuration is invalid; run the audit before learning");
+    const result = await task(state);
+    await saveState(state, path, assertOwned);
+    return result;
+  }).catch((error) => {
+    if (error.message === "state is busy; retry shortly") {
+      throw new Error("learning state is busy; retry shortly");
+    }
+    throw error;
+  });
+}
+
+export async function mutation(root, operation, providedCatalog = null) {
+  const catalog = providedCatalog || await buildCatalog(root);
+  const { learningPath } = await loadLearning(catalog.root, catalog);
+  return withLock(learningPath, catalog.root, async (state) => operation(state, catalog, learningPath));
+}
+
+export function preserve(state, kind, value, now) {
+  if (!value) return;
+  state.history.push({
+    kind,
+    recordId: value.id || "config",
+    subjectId: value.subjectId || null,
+    supersededAt: now,
+    privacy: value.privacy || "private",
+    value: { ...value, authority: "context-only" },
+    authority: "context-only"
+  });
+}
+
+export function normalizeEvidence(input, catalog, now) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("evidence is required");
+  const id = input.id || `evidence:${randomUUID()}`;
+  if (!ID_RE.test(id)) throw new Error("evidence.id must be a stable, whitespace-free identifier");
+  const type = input.type || "interaction";
+  if (!EVIDENCE_TYPES.has(type)) throw new Error(`unsupported evidence type: ${type}`);
+  const sourceDocument = relativePath(input.sourceDocument, "evidence.sourceDocument");
+  let sourceSha256 = null;
+  if (sourceDocument !== null) {
+    const source = catalog.documents.find((document) => document.relativePath === sourceDocument);
+    if (!source) throw new Error(`unknown evidence source document: ${sourceDocument}`);
+    sourceSha256 = source.sha256;
+  }
+  if (type === "document" && !sourceDocument) throw new Error("document evidence requires sourceDocument");
+  return {
+    id,
+    type,
+    summary: safeText(input.summary, "evidence.summary", 500),
+    sourceDocument,
+    sourceSha256,
+    confidence: number(input.confidence ?? 0.5, "evidence.confidence", 0, 1),
+    observedAt: date(input.observedAt || now, "evidence.observedAt"),
+    authority: "context-only"
+  };
+}
+
+export function evidenceConfidence(evidence) {
+  if (!evidence.length) return 0;
+  return evidence.reduce((sum, item) => sum + item.confidence, 0) / evidence.length;
+}

package/agent-spine-plugin/src/lib/learning-trial-recovery.js

@@ -0,0 +1,218 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  PAIRED_EVALUATIONS, ROOT_BOUND_EVALUATIONS, REGISTRY_BOUND_EVALUATIONS, INITIAL_TRIAL_EVALUATIONS
+} from "./learning-schema.js";
+import {
+  exactScope, digest, revokedMeasurementForCandidate, activeEvaluationBinding
+} from "./learning-scope-targets.js";
+import {
+  revokedEvaluationForCandidate, validationOutcomeReferences, validationLeasePayload
+} from "./learning-validation-contracts.js";
+import {
+  revokedValidationForCandidate, validationLeaseState, initialTrialTimeout
+} from "./learning-validation-runtime.js";
+import {
+  revokedEvidenceSourceAttestationForCandidate
+} from "./learning-measurement-contracts.js";
+import {
+  revokedApplicationForCandidate, revokedOutcomeForCandidate
+} from "./learning-delivery-contracts.js";
+import {
+  preserve
+} from "./learning-storage.js";
+import {
+  outcomeFresh
+} from "./learning-applications.js";
+import {
+  outcomeMatchesContract, outcomeMatchesInitialTrial, improvement, rollbackCandidate, recordInitialTrialFailure, recordTrialRetryExhaustion
+} from "./learning-reconciliation.js";
+
+export function reconcileCanary(state, candidate, timestamp) {
+  const canary = candidate.promotion?.canary;
+  if (candidate.status !== "accepted" || candidate.promotion?.mode !== "outcome-canary"
+    || !["active", "validated"].includes(canary?.status)) {
+    return { candidate, decision: "unchanged", restored: [] };
+  }
+  const evaluationRevocation = revokedEvaluationForCandidate(state, candidate);
+  if (evaluationRevocation) {
+    const result = rollbackCandidate(state, candidate, "learning evaluation contract was explicitly revoked",
+      timestamp, "automatic-evaluation-revocation");
+    return { ...result, decision: "rolled-back", evaluationRevocation };
+  }
+  const evidenceSourceAttestationRevocation = revokedEvidenceSourceAttestationForCandidate(state, candidate);
+  if (evidenceSourceAttestationRevocation) {
+    const result = rollbackCandidate(state, candidate, "learning evidence source attestation was explicitly revoked",
+      timestamp, "automatic-evidence-source-attestation-revocation");
+    return { ...result, decision: "rolled-back", evidenceSourceAttestationRevocation };
+  }
+  const validationRevocation = revokedValidationForCandidate(state, candidate);
+  if (validationRevocation) {
+    const result = rollbackCandidate(state, candidate, "learning validation decision was explicitly revoked",
+      timestamp, "automatic-validation-revocation");
+    return { ...result, decision: "rolled-back", validationRevocation };
+  }
+  const measurementRevocation = revokedMeasurementForCandidate(state, candidate);
+  if (measurementRevocation) {
+    const result = rollbackCandidate(state, candidate, "learning measurement evidence was explicitly revoked",
+      timestamp, "automatic-measurement-revocation");
+    return { ...result, decision: "rolled-back", measurementRevocation };
+  }
+  const applicationRevocation = revokedApplicationForCandidate(state, candidate);
+  if (applicationRevocation) {
+    const result = rollbackCandidate(state, candidate, "learning application evidence was explicitly revoked",
+      timestamp, "automatic-application-revocation");
+    return { ...result, decision: "rolled-back", applicationRevocation };
+  }
+  const outcomeRevocation = revokedOutcomeForCandidate(state, candidate);
+  if (outcomeRevocation) {
+    const result = rollbackCandidate(state, candidate, "learning outcome evidence was explicitly revoked",
+      timestamp, "automatic-outcome-revocation");
+    return { ...result, decision: "rolled-back", outcomeRevocation };
+  }
+  if (new Date(canary.expiresAt).getTime() <= new Date(timestamp).getTime()) {
+    const result = rollbackCandidate(state, candidate, canary.status === "validated"
+      ? "validated learning evidence lease expired" : "outcome canary expired before validation", timestamp,
+    canary.status === "validated" ? "automatic-validation-stale" : "automatic-stale");
+    return { ...result, decision: "rolled-back" };
+  }
+  const evaluation = canary.evaluationId
+    ? state.evaluations.find((contract) => contract.id === canary.evaluationId && contract.learningId === candidate.id)
+    : null;
+  if (canary.evaluationId && (!evaluation || evaluation.digest !== canary.evaluationDigest
+    || new Date(evaluation.expiresAt).getTime() <= new Date(timestamp).getTime())) {
+    const result = rollbackCandidate(state, candidate, "outcome evaluation contract is missing, changed, or stale", timestamp, "automatic-stale");
+    return { ...result, decision: "rolled-back" };
+  }
+  if (REGISTRY_BOUND_EVALUATIONS.has(evaluation?.schema)
+    && !activeEvaluationBinding(state, evaluation)) {
+    const result = rollbackCandidate(state, candidate, "outcome evaluator registry binding was revoked or changed", timestamp, "automatic-evaluator-revocation");
+    return { ...result, decision: "rolled-back" };
+  }
+  const failedTrial = initialTrialTimeout(state, candidate, timestamp);
+  if (failedTrial) {
+    const failureReceipt = recordInitialTrialFailure(state, failedTrial, timestamp);
+    const result = rollbackCandidate(state, candidate,
+      failedTrial.failure === "delivery-timeout"
+        ? "initial Canary trial missed its immutable model-turn delivery deadline"
+        : "initial Canary trial missed its immutable measured-outcome deadline",
+      timestamp, "automatic-incomplete-trial", failureReceipt);
+    const retryExhaustionReceipt = recordTrialRetryExhaustion(state, failureReceipt);
+    return { ...result, decision: "rolled-back", failureReceipt, retryExhaustionReceipt };
+  }
+  if (canary.status === "validated") {
+    const validation = validationLeaseState(state, candidate, timestamp);
+    if (REGISTRY_BOUND_EVALUATIONS.has(evaluation?.schema)
+      && validation.status !== "active") {
+      const result = rollbackCandidate(state, candidate,
+        validation.status === "missing" ? "validated learning is missing its immutable evidence lease"
+          : "validated learning evidence lease is no longer current",
+        timestamp, validation.status === "missing" ? "automatic-validation-unproven" : "automatic-validation-stale");
+      return { ...result, decision: "rolled-back" };
+    }
+    return { candidate, decision: "unchanged", restored: [] };
+  }
+  const planned = Boolean(evaluation);
+  const receipts = state.outcomes.filter((item) => (planned
+    ? outcomeMatchesContract(item, evaluation)
+    : item.schema === "agentspine.learning-outcome/v2")
+    && item.learningId === candidate.id && item.phase === "after"
+    && (!planned || item.evaluationId === evaluation.id)
+    && exactScope(item.scope, canary.scope) && item.metric.name === canary.metric.name
+    && item.metric.direction === canary.metric.direction && outcomeFresh(item, evaluation, state.config, timestamp)
+    && outcomeMatchesInitialTrial(state, item, evaluation)
+    && state.applications.some((application) => application.id === item.applicationId
+      && application.learningId === candidate.id && exactScope(application.scope, canary.scope)));
+  if (receipts.some((item) => item.metric.blockingDefects > 0)) {
+    const result = rollbackCandidate(state, candidate, "outcome canary recorded a blocking defect", timestamp, "automatic-regression");
+    return { ...result, decision: "rolled-back" };
+  }
+  const paired = PAIRED_EVALUATIONS.has(evaluation?.schema);
+  const rootBound = ROOT_BOUND_EVALUATIONS.has(evaluation?.schema);
+  const beforeByEvaluator = paired ? new Map((canary.beforeReceipts || [])
+    .map((id) => state.outcomes.find((item) => item.id === id))
+    .filter((item) => item?.schema === (rootBound ? "agentspine.learning-outcome/v9" : "agentspine.learning-outcome/v8"))
+    .map((item) => [rootBound ? item.measurement.evaluatorRootDigest : item.measurement.evaluatorId, item])) : new Map();
+  const eligible = receipts.filter((item) => item.measurement.kind !== "model-suggestion"
+    && (!paired || beforeByEvaluator.has(rootBound ? item.measurement.evaluatorRootDigest : item.measurement.evaluatorId)));
+  if (INITIAL_TRIAL_EVALUATIONS.has(evaluation?.schema)) eligible.sort((a, b) =>
+    evaluation.initialTrials.after.findIndex((trial) => trial.evaluatorId === a.measurement.evaluatorId)
+    - evaluation.initialTrials.after.findIndex((trial) => trial.evaluatorId === b.measurement.evaluatorId));
+  const independentEvaluators = new Set(eligible.map((item) => rootBound
+    ? item.measurement.evaluatorRootDigest : item.measurement.evaluatorId)).size;
+  const independentApplications = new Set(eligible.map((item) => item.applicationId)).size;
+  const deltas = eligible.map((item) => improvement(canary.metric.direction,
+    paired ? beforeByEvaluator.get(rootBound ? item.measurement.evaluatorRootDigest : item.measurement.evaluatorId).metric.value : canary.baseline,
+    item.metric.value));
+  const thresholds = planned ? evaluation.thresholds : {
+    regressionTolerance: state.config.regressionTolerance,
+    afterReceipts: state.config.canaryReceipts,
+    minImprovement: state.config.minImprovement
+  };
+  if (deltas.some((value) => value < -thresholds.regressionTolerance)) {
+    const result = rollbackCandidate(state, candidate, "outcome canary regressed against its baseline", timestamp, "automatic-regression");
+    return { ...result, decision: "rolled-back" };
+  }
+  if (independentEvaluators < thresholds.afterReceipts || independentApplications < thresholds.afterReceipts
+    || !eligible.some((item) => item.measurement.kind === "objective")) {
+    return { candidate, decision: "active", restored: [] };
+  }
+  const average = deltas.reduce((sum, value) => sum + value, 0) / deltas.length;
+  if (average < thresholds.minImprovement) {
+    const result = rollbackCandidate(state, candidate, "outcome canary did not meet the minimum measured improvement", timestamp, "automatic-no-improvement");
+    return { ...result, decision: "rolled-back" };
+  }
+  preserve(state, "learning-candidate", candidate, timestamp);
+  let validationLease = null;
+  if (REGISTRY_BOUND_EVALUATIONS.has(evaluation?.schema)) {
+    const binding = activeEvaluationBinding(state, evaluation);
+    if (!binding) {
+      const result = rollbackCandidate(state, candidate, "outcome evaluator registry binding was revoked or changed",
+        timestamp, "automatic-evaluator-revocation");
+      return { ...result, decision: "rolled-back" };
+    }
+    const beforeOutcomes = (canary.beforeReceipts || []).map((id) => state.outcomes.find((item) => item.id === id));
+    if (beforeOutcomes.some((item) => !item)) {
+      const result = rollbackCandidate(state, candidate, "validated learning baseline evidence is missing",
+        timestamp, "automatic-validation-unproven");
+      return { ...result, decision: "rolled-back" };
+    }
+    const payload = validationLeasePayload({
+      id: `validation:${randomUUID()}`,
+      learningId: candidate.id,
+      evaluationId: evaluation.id,
+      evaluationDigest: evaluation.digest,
+      evaluatorRegistryBindingDigest: binding.digest,
+      scope: canary.scope,
+      metric: canary.metric,
+      beforeOutcomes: validationOutcomeReferences(beforeOutcomes),
+      afterOutcomes: validationOutcomeReferences(eligible),
+      improvement: average,
+      validatedAt: timestamp,
+      expiresAt: canary.expiresAt
+    });
+    validationLease = { ...payload, digest: digest(payload) };
+    state.validationLeases.push(validationLease);
+    state.validationLeases.sort((a, b) => a.id.localeCompare(b.id));
+  }
+  const validated = {
+    ...candidate,
+    promotion: {
+      ...candidate.promotion,
+      canary: {
+        ...canary,
+        status: "validated",
+        validatedAt: timestamp,
+        afterReceipts: eligible.map((item) => item.id),
+        improvement: average,
+        ...(validationLease ? {
+          validationLeaseId: validationLease.id,
+          validationLeaseDigest: validationLease.digest
+        } : {})
+      }
+    },
+    updatedAt: timestamp,
+    authority: "context-only"
+  };
+  state.candidates = state.candidates.map((entry) => entry.id === candidate.id ? validated : entry);
+  return { candidate: validated, decision: "validated", restored: [] };
+}