avorelo 0.1.0

package/scripts/lib/proof-canonical.js

@@ -0,0 +1,398 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const CANONICAL_PROOF_VERSION = 1;
+const CANONICAL_PROOF_FAMILIES = [
+  "task_contract",
+  "control_decision",
+  "material_step",
+  "safe_stop",
+  "completion_truth",
+];
+
+const BOUNDED_STATE_SUMMARY_REL = path.join(
+  "artifacts",
+  "ws-aif",
+  "l8",
+  "state-summary",
+  "bounded-state-summary.v1.json"
+);
+const REENTRY_CARRY_FORWARD_REL = path.join(
+  "artifacts",
+  "ws-aif",
+  "l8",
+  "state-summary",
+  "reentry-carry-forward.v1.json"
+);
+const CONTROLLED_EXPOSURE_READINESS_REL = path.join(
+  "artifacts",
+  "ws-aif",
+  "l8",
+  "controlled-exposure",
+  "controlled-exposure-readiness.v1.json"
+);
+const ARTIFACT_TRUTH_RATCHET_REL = path.join(
+  "artifacts",
+  "ws-aif",
+  "l8",
+  "artifact-truth",
+  "artifact-truth-ratchet.v1.json"
+);
+
+function hasNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function normalizeStringList(values) {
+  if (!Array.isArray(values)) return [];
+  return values.map((value) => String(value || "").trim()).filter(Boolean);
+}
+
+function uniqueStrings(values) {
+  return [...new Set(normalizeStringList(values))];
+}
+
+function collectRefValues(objectValue) {
+  if (!objectValue || typeof objectValue !== "object" || Array.isArray(objectValue)) return [];
+  return Object.entries(objectValue)
+    .filter(([key, value]) => key.endsWith("_ref") && hasNonEmptyString(value))
+    .map(([, value]) => value.trim());
+}
+
+function cloneNextBoundedAction(value) {
+  if (hasNonEmptyString(value)) return value.trim();
+  if (!value || typeof value !== "object") return null;
+  const normalized = {};
+  if (hasNonEmptyString(value.action_id)) normalized.action_id = value.action_id.trim();
+  if (hasNonEmptyString(value.reason)) normalized.reason = value.reason.trim();
+  if (hasNonEmptyString(value.command)) normalized.command = value.command.trim();
+  if (hasNonEmptyString(value.rollback_baseline_id)) normalized.rollback_baseline_id = value.rollback_baseline_id.trim();
+  if (hasNonEmptyString(value.rollback_trigger)) normalized.rollback_trigger = value.rollback_trigger.trim();
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+function readJsonOrNull(absPath) {
+  if (!absPath || !fs.existsSync(absPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeTaskContractSummary(contract) {
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return null;
+
+  const normalized = {};
+  const scalarAliases = [
+    ["status", ["status"]],
+    ["tool", ["tool"]],
+    ["intent", ["intent"]],
+    ["objective", ["objective"]],
+  ];
+  const listAliases = [
+    ["allowed_paths", ["allowed_paths", "allowedPaths"]],
+    ["scope_out", ["scope_out", "scopeOut"]],
+    ["requested_outputs", ["requested_outputs", "requestedOutputs"]],
+    ["stop_conditions", ["stop_conditions", "stopConditions"]],
+    ["success_criteria", ["success_criteria", "successCriteria"]],
+    ["evidence_refs", ["evidence_refs", "evidenceRefs"]],
+    ["review_reasons", ["review_reasons", "reviewReasons"]],
+  ];
+
+  for (const [field, aliases] of scalarAliases) {
+    const value = aliases.map((alias) => contract[alias]).find(hasNonEmptyString);
+    if (hasNonEmptyString(value)) normalized[field] = value.trim();
+  }
+
+  for (const [field, aliases] of listAliases) {
+    const values = aliases
+      .map((alias) => contract[alias])
+      .find((candidate) => Array.isArray(candidate));
+    const normalizedValues = uniqueStrings(values || []);
+    if (normalizedValues.length > 0) normalized[field] = normalizedValues;
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+function validateCanonicalProof(signal) {
+  if (!signal || typeof signal !== "object" || Array.isArray(signal)) {
+    return { valid: false, errors: ["canonical_proof must be an object"] };
+  }
+  const errors = [];
+  if (Number(signal.version || CANONICAL_PROOF_VERSION) !== CANONICAL_PROOF_VERSION) errors.push(`unsupported canonical_proof version: ${signal.version}`);
+  if (!CANONICAL_PROOF_FAMILIES.includes(signal.family)) errors.push(`unknown canonical_proof family: ${signal.family}`);
+  if (
+    signal.family === "task_contract" &&
+    !hasNonEmptyString(signal.objective) &&
+    (!Array.isArray(signal.allowed_paths) || signal.allowed_paths.length === 0) &&
+    (!Array.isArray(signal.stop_conditions) || signal.stop_conditions.length === 0)
+  ) {
+    errors.push("task_contract requires at least objective, allowed_paths, or stop_conditions");
+  }
+  if (signal.family === "control_decision" && !hasNonEmptyString(signal.decision)) errors.push("control_decision requires decision");
+  if (signal.family === "material_step" && !hasNonEmptyString(signal.step_type || signal.step_kind)) errors.push("material_step requires step_type");
+  if (signal.family === "completion_truth" && !hasNonEmptyString(signal.completion_status)) errors.push("completion_truth requires completion_status");
+  return { valid: errors.length === 0, errors };
+}
+
+function normalizeCanonicalProof(signal) {
+  if (!signal || typeof signal !== "object" || Array.isArray(signal)) return null;
+  const normalized = { version: CANONICAL_PROOF_VERSION, family: signal.family };
+  const rawStepType = signal.step_type || signal.step_kind;
+  const rawArtifactRef = signal.artifact_ref || signal.output_artifact_reference;
+  const rawProgressRef = signal.progress_ref || signal.progress_reference;
+  const rawUnresolvedItems = signal.unresolved_items || signal.unresolved_limitations;
+  const rawRiskLevel =
+    signal.risk_level
+    || (Number(signal.risk_score) >= 70 ? "high" : Number(signal.risk_score) >= 40 ? "medium" : Number.isFinite(Number(signal.risk_score)) ? "low" : null);
+
+  [
+    "decision",
+    "source",
+    "scope_status",
+    "policy_boundary",
+    "decision_basis",
+    "message",
+    "step_type",
+    "value_type",
+    "artifact_ref",
+    "notes",
+    "output_artifact_type",
+    "output_artifact_reference",
+    "completion_status",
+    "final_outcome_type",
+    "useful_result_state",
+    "completion_quality_state",
+    "partial_completion_reason",
+    "safe_stop_reason",
+    "reentry_status",
+    "claim_boundary",
+    "where_am_i_now",
+    "progress_ref",
+    "progress_reference",
+    "recommended_next_action",
+    "evidence_status",
+    "reason_summary",
+    "risk_level",
+    "status",
+    "tool",
+    "intent",
+    "objective",
+  ].forEach((field) => {
+    if (hasNonEmptyString(signal[field])) normalized[field] = signal[field].trim();
+  });
+
+  [
+    "approval_required",
+    "blocked",
+    "downgraded",
+    "recovery_triggered",
+    "rollback_available",
+    "progress_preserved",
+    "reentry_anchor_saved",
+    "evidence_backed_completion",
+    "has_related_evidence",
+    "user_visible_proof_supported",
+  ].forEach((field) => {
+    if (typeof signal[field] === "boolean") normalized[field] = signal[field];
+  });
+
+  if (Number.isFinite(Number(signal.risk_score))) normalized.risk_score = Number(signal.risk_score);
+  if (Number.isFinite(Number(signal.bytes))) normalized.bytes = Number(signal.bytes);
+  if (hasNonEmptyString(rawStepType)) normalized.step_type = rawStepType.trim();
+  if (hasNonEmptyString(rawArtifactRef)) normalized.artifact_ref = rawArtifactRef.trim();
+  if (hasNonEmptyString(rawProgressRef)) {
+    normalized.progress_ref = rawProgressRef.trim();
+    normalized.progress_reference = rawProgressRef.trim();
+  }
+  if (hasNonEmptyString(rawRiskLevel)) normalized.risk_level = rawRiskLevel.trim();
+
+  const reasonCodes = normalizeStringList(signal.reason_codes);
+  if (reasonCodes.length > 0) normalized.reason_codes = reasonCodes;
+  const evidenceRefs = normalizeStringList(signal.evidence_refs);
+  if (evidenceRefs.length > 0) normalized.evidence_refs = evidenceRefs;
+  if (Array.isArray(rawUnresolvedItems)) {
+    const unresolved = normalizeStringList(rawUnresolvedItems);
+    normalized.unresolved_items = unresolved;
+    normalized.unresolved_limitations = unresolved;
+  }
+  [
+    "allowed_paths",
+    "scope_out",
+    "requested_outputs",
+    "stop_conditions",
+    "success_criteria",
+    "review_reasons",
+  ].forEach((field) => {
+    const values = uniqueStrings(signal[field]);
+    if (values.length > 0) normalized[field] = values;
+  });
+
+  const nextBoundedAction = cloneNextBoundedAction(signal.next_bounded_action);
+  if (nextBoundedAction) normalized.next_bounded_action = nextBoundedAction;
+  const taskContract = normalizeTaskContractSummary(signal.task_contract);
+  if (taskContract) normalized.task_contract = taskContract;
+
+  return validateCanonicalProof(normalized).valid ? normalized : null;
+}
+
+function createCanonicalProof(family, payload = {}) {
+  return normalizeCanonicalProof({ version: CANONICAL_PROOF_VERSION, family, ...(payload || {}) });
+}
+
+function createTaskContractProof(taskContract) {
+  const normalizedTaskContract = normalizeTaskContractSummary(taskContract);
+  if (!normalizedTaskContract) return null;
+  return createCanonicalProof("task_contract", normalizedTaskContract);
+}
+
+function withCanonicalProof(meta, signal) {
+  const canonicalProof = normalizeCanonicalProof(signal);
+  if (!canonicalProof) return { ...(meta || {}) };
+  return { ...(meta || {}), canonical_proof: canonicalProof };
+}
+
+function getCanonicalProofFromEntry(entry) {
+  return normalizeCanonicalProof(entry?.meta?.canonical_proof || entry?.metadata?.canonical_proof);
+}
+
+function extractCanonicalProofEntries(entries) {
+  return (entries || []).map((entry) => {
+    const signal = getCanonicalProofFromEntry(entry);
+    if (!signal) return null;
+    return {
+      signal,
+      ts: entry?.ts || entry?.timestamp || null,
+      event: entry?.event || entry?.event_name || null,
+      action: entry?.action || null,
+      tool: entry?.tool || null,
+    };
+  }).filter(Boolean);
+}
+
+function latestCanonicalEntriesByFamily(entries) {
+  const latest = new Map();
+  extractCanonicalProofEntries(entries).forEach((entry) => latest.set(entry.signal.family, entry));
+  return latest;
+}
+
+function latestTerminalCanonicalSignal(entries) {
+  const extracted = extractCanonicalProofEntries(entries).filter((entry) => entry.signal.family === "safe_stop" || entry.signal.family === "completion_truth");
+  return extracted.length > 0 ? extracted[extracted.length - 1].signal : null;
+}
+
+function formatNextBoundedAction(action) {
+  if (!action) return null;
+  if (hasNonEmptyString(action)) return action.trim();
+  if (typeof action !== "object") return null;
+  const actionId = hasNonEmptyString(action.action_id) ? action.action_id.trim() : null;
+  const reason = hasNonEmptyString(action.reason) ? action.reason.trim() : null;
+  if (actionId && reason) return `${actionId}: ${reason}`;
+  return actionId || reason || null;
+}
+
+function buildBoundedStateContext(cwd) {
+  const summaryPayload = readJsonOrNull(path.join(cwd, BOUNDED_STATE_SUMMARY_REL));
+  const reentryCarryForward = readJsonOrNull(path.join(cwd, REENTRY_CARRY_FORWARD_REL));
+  const controlledExposure = readJsonOrNull(path.join(cwd, CONTROLLED_EXPOSURE_READINESS_REL));
+  const artifactTruth = readJsonOrNull(path.join(cwd, ARTIFACT_TRUTH_RATCHET_REL));
+
+  if (!summaryPayload && !reentryCarryForward && !controlledExposure && !artifactTruth) return null;
+
+  const evidenceRefs = uniqueStrings([
+    summaryPayload ? BOUNDED_STATE_SUMMARY_REL : null,
+    reentryCarryForward ? REENTRY_CARRY_FORWARD_REL : null,
+    controlledExposure ? CONTROLLED_EXPOSURE_READINESS_REL : null,
+    artifactTruth ? ARTIFACT_TRUTH_RATCHET_REL : null,
+    ...collectRefValues(summaryPayload?.evidence_refs),
+    ...collectRefValues(controlledExposure?.evidence_summary),
+    ...(reentryCarryForward?.minimum_reentry_refs || []).map((item) => item?.ref),
+  ].map((value) => (hasNonEmptyString(value) ? value.trim() : null)).filter(Boolean));
+
+  const artifactRefs = uniqueStrings([
+    summaryPayload ? BOUNDED_STATE_SUMMARY_REL : null,
+    reentryCarryForward ? REENTRY_CARRY_FORWARD_REL : null,
+    controlledExposure ? CONTROLLED_EXPOSURE_READINESS_REL : null,
+    artifactTruth ? ARTIFACT_TRUTH_RATCHET_REL : null,
+  ]);
+
+  const nextBoundedAction =
+    cloneNextBoundedAction(summaryPayload?.next_bounded_action) ||
+    cloneNextBoundedAction(reentryCarryForward?.next_bounded_action) ||
+    cloneNextBoundedAction(controlledExposure?.next_bounded_action);
+  const whereAmINow =
+    (hasNonEmptyString(summaryPayload?.where_am_i_now) ? summaryPayload.where_am_i_now.trim() : null) ||
+    (hasNonEmptyString(reentryCarryForward?.where_am_i_now) ? reentryCarryForward.where_am_i_now.trim() : null);
+  const claimBoundary = hasNonEmptyString(summaryPayload?.what_can_i_honestly_claim)
+    ? summaryPayload.what_can_i_honestly_claim.trim()
+    : null;
+  const reentryStatus =
+    (hasNonEmptyString(summaryPayload?.reentry_status) ? summaryPayload.reentry_status.trim() : null) ||
+    (hasNonEmptyString(reentryCarryForward?.reentry_status) ? reentryCarryForward.reentry_status.trim() : null) ||
+    null;
+
+  return {
+    artifact_path:
+      summaryPayload ? BOUNDED_STATE_SUMMARY_REL.split(path.sep).join("/")
+        : reentryCarryForward ? REENTRY_CARRY_FORWARD_REL.split(path.sep).join("/")
+          : controlledExposure ? CONTROLLED_EXPOSURE_READINESS_REL.split(path.sep).join("/")
+            : ARTIFACT_TRUTH_RATCHET_REL.split(path.sep).join("/"),
+    state_source:
+      summaryPayload ? BOUNDED_STATE_SUMMARY_REL.split(path.sep).join("/")
+        : reentryCarryForward ? REENTRY_CARRY_FORWARD_REL.split(path.sep).join("/")
+          : controlledExposure ? CONTROLLED_EXPOSURE_READINESS_REL.split(path.sep).join("/")
+            : ARTIFACT_TRUTH_RATCHET_REL.split(path.sep).join("/"),
+    artifact_refs: artifactRefs.map((value) => value.split(path.sep).join("/")),
+    claim_boundary: claimBoundary,
+    what_can_i_honestly_claim: claimBoundary,
+    where_am_i_now: whereAmINow,
+    reentry_status: reentryStatus,
+    next_bounded_action: nextBoundedAction,
+    latest_trustworthy_run_id:
+      hasNonEmptyString(reentryCarryForward?.latest_trustworthy_run_id)
+        ? reentryCarryForward.latest_trustworthy_run_id.trim()
+        : null,
+    latest_trustworthy_workset_id:
+      hasNonEmptyString(reentryCarryForward?.latest_trustworthy_workset_id)
+        ? reentryCarryForward.latest_trustworthy_workset_id.trim()
+        : null,
+    rollback_available:
+      whereAmINow === "rollback"
+      || controlledExposure?.readiness_status === "rollback"
+      || nextBoundedAction?.action_id === "rollback_to_safe_baseline",
+    rollback_trigger: hasNonEmptyString(controlledExposure?.rollback_trigger) ? controlledExposure.rollback_trigger.trim() : null,
+    readiness_status: hasNonEmptyString(controlledExposure?.readiness_status) ? controlledExposure.readiness_status.trim() : null,
+    exposure_scope: hasNonEmptyString(controlledExposure?.exposure_scope) ? controlledExposure.exposure_scope.trim() : null,
+    artifact_truth_status: hasNonEmptyString(artifactTruth?.artifact_truth_status) ? artifactTruth.artifact_truth_status.trim() : null,
+    counts_as_meaningful_output:
+      typeof artifactTruth?.counts_as_meaningful_output === "boolean"
+        ? artifactTruth.counts_as_meaningful_output
+        : null,
+    reentry_reason_summary:
+      hasNonEmptyString(reentryCarryForward?.reason_summary)
+        ? reentryCarryForward.reason_summary.trim()
+        : null,
+    evidence_refs: evidenceRefs.map((value) => value.split(path.sep).join("/")),
+  };
+}
+
+module.exports = {
+  CANONICAL_PROOF_FAMILIES,
+  CANONICAL_PROOF_VERSION,
+  buildBoundedStateContext,
+  createCanonicalProof,
+  createTaskContractProof,
+  extractCanonicalProofEntries,
+  formatNextBoundedAction,
+  getCanonicalProofFromEntry,
+  latestCanonicalEntriesByFamily,
+  latestTerminalCanonicalSignal,
+  normalizeTaskContractSummary,
+  normalizeCanonicalProof,
+  validateCanonicalProof,
+  withCanonicalProof,
+};