avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/browser-proof-preflight.js

@@ -0,0 +1,321 @@
+"use strict";
+
+// ── Browser Proof Preflight ───────────────────────────────────────────────────
+// Contract: avorelo.browserProofPreflight.v1
+// Answers: "Can avorelo prove value WITHOUT a browser? Is local-first proof path
+// viable? Is browser an optional enhancement (not a requirement)?"
+// PREFLIGHT ONLY — does NOT launch a browser, does NOT start a server,
+// does NOT make network requests.
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.browserProofPreflight.v1";
+const SCHEMA_VERSION = 1;
+const ARTIFACT_DIR_REL = ".claude/cco/orchestration/adapter-readiness";
+const ARTIFACT_REL = ARTIFACT_DIR_REL + "/latest-browser-proof-preflight.json";
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch { return null; }
+}
+
+function pass(id, label, evidence, detail) {
+  return { id, label, status: "pass", evidence: evidence || null, detail: detail || null, safeNextAction: null };
+}
+function warn(id, label, safeNextAction, evidence, detail) {
+  return { id, label, status: "warn", evidence: evidence || null, detail: detail || null, safeNextAction: safeNextAction || "Review and resolve." };
+}
+function blocked(id, label, safeNextAction, evidence, detail) {
+  return { id, label, status: "blocked", evidence: evidence || null, detail: detail || null, safeNextAction: safeNextAction || "Fix blocker before proceeding." };
+}
+function info(id, label, evidence, detail) {
+  return { id, label, status: "info", evidence: evidence || null, detail: detail || null, safeNextAction: null };
+}
+
+// ── Preflight Checks ──────────────────────────────────────────────────────────
+
+function checkLocalFirstProofPathExists(cwd) {
+  // Verify that CLI proof path exists (no browser required)
+  const binPath = path.join(cwd, "bin", "avorelo");
+  if (!fs.existsSync(binPath)) {
+    return blocked("local_first_proof_path", "bin/avorelo entry point missing",
+      "Create bin/avorelo. Local-first proof path is the primary path.",
+      null, "bin/avorelo not found.");
+  }
+
+  // Check for proof-receipt command availability via public-cli
+  const cliPath = path.join(cwd, "scripts/lib/public-cli.js");
+  if (!fs.existsSync(cliPath)) {
+    return blocked("local_first_proof_path", "public-cli.js missing",
+      "scripts/lib/public-cli.js not found. Restore CLI before browser preflight.",
+      null);
+  }
+
+  const cliText = fs.readFileSync(cliPath, "utf8");
+  if (cliText.includes("proof-receipt") || cliText.includes("proof-outcome")) {
+    return pass("local_first_proof_path", "Local-first proof path available via CLI",
+      { binExists: true, cliHasProofCommand: true });
+  }
+
+  return warn("local_first_proof_path", "CLI proof command not found in public-cli.js",
+    "Add proof-receipt or proof-outcome command to public-cli.js.",
+    { cliChecked: true });
+}
+
+function checkProofDoesNotRequireBrowser(cwd) {
+  // Check that existing proof artifacts were generated without browser
+  const proofPath = path.join(cwd, ".claude/cco/orchestration/proof-outcome/latest-proof-outcome.json");
+  const proof = safeReadJson(proofPath);
+  if (!proof) {
+    return info("proof_no_browser_required", "No proof artifact to inspect",
+      null, "Proof artifact not yet generated — browser requirement not determinable.");
+  }
+
+  if (proof.requiresBrowser === true) {
+    return blocked("proof_no_browser_required", "Proof artifact marks browser as required",
+      "Update proof generation to work without browser. Browser is an optional enhancement.",
+      { requiresBrowser: true });
+  }
+
+  return pass("proof_no_browser_required", "Proof artifact does not require browser",
+    { requiresBrowser: proof.requiresBrowser || false });
+}
+
+function checkBrowserIsOptionalEnhancement(cwd) {
+  // Verify documentation states browser is optional
+  const docsToCheck = [
+    { relPath: "docs/ACTIVATION.md", pattern: /local|cli|terminal|without.*browser/i },
+    { relPath: "docs/INSTALL.md", pattern: /local|cli|terminal/i },
+    { relPath: "README.md", pattern: /local.first|cli|terminal/i },
+  ];
+
+  let anyDocHasLocalFirst = false;
+  const found = [];
+
+  for (const { relPath, pattern } of docsToCheck) {
+    const absPath = path.join(cwd, relPath);
+    if (!fs.existsSync(absPath)) continue;
+    try {
+      const text = fs.readFileSync(absPath, "utf8").slice(0, 5000);
+      if (pattern.test(text)) {
+        anyDocHasLocalFirst = true;
+        found.push(relPath);
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (!anyDocHasLocalFirst) {
+    return warn("browser_optional_enhancement", "No doc confirms local-first/CLI path without browser",
+      "Add explicit local-first activation path in docs/ACTIVATION.md or README.md.",
+      { docsChecked: docsToCheck.map(function(d) { return d.relPath; }) });
+  }
+
+  return pass("browser_optional_enhancement", "Docs confirm local-first/CLI path exists",
+    { docsWithLocalFirst: found });
+}
+
+function checkNoBrowserRuntimeDependency(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  const pkg = safeReadJson(pkgPath);
+  if (!pkg) {
+    return warn("no_browser_runtime_dependency", "No package.json found",
+      "Run from a directory with package.json.",
+      null);
+  }
+
+  const allDeps = Object.assign({},
+    pkg.dependencies || {},
+    pkg.devDependencies || {}
+  );
+
+  // Check for browser-specific runtime dependencies that would block local-first
+  const browserRuntimeDeps = Object.keys(allDeps).filter(function(dep) {
+    // playwright/puppeteer as prod dependency (not devDependency) would be a concern
+    return /^playwright$|^puppeteer$/.test(dep) && (pkg.dependencies || {})[dep];
+  });
+
+  if (browserRuntimeDeps.length > 0) {
+    return warn("no_browser_runtime_dependency",
+      "Browser runtime dependencies in prod dependencies: " + browserRuntimeDeps.join(", "),
+      "Move playwright/puppeteer to devDependencies. Browser should not be required at runtime.",
+      { deps: browserRuntimeDeps });
+  }
+
+  return pass("no_browser_runtime_dependency", "No browser runtime dependencies in prod deps",
+    { checked: Object.keys(allDeps).length });
+}
+
+function checkBrowserProofDocsOrPlanned(cwd) {
+  // Check if browser proof is at least documented as a future enhancement
+  const browserProofDocs = [
+    "docs/browser-proof.md",
+    "docs/product/browser-proof.md",
+    "docs/Browser-Capability-Governance.md",
+  ];
+
+  for (const relPath of browserProofDocs) {
+    if (fs.existsSync(path.join(cwd, relPath))) {
+      return pass("browser_proof_docs_or_planned", "Browser proof documented",
+        { path: relPath });
+    }
+  }
+
+  // Check if mentioned in roadmap
+  const roadmapPath = path.join(cwd, "docs/Roadmap.md");
+  if (fs.existsSync(roadmapPath)) {
+    try {
+      const text = fs.readFileSync(roadmapPath, "utf8").slice(0, 10000);
+      if (/browser.*proof|browser.*capability|browser.*enhancement/i.test(text)) {
+        return pass("browser_proof_docs_or_planned", "Browser proof mentioned in Roadmap.md",
+          { path: "docs/Roadmap.md" });
+      }
+    } catch { /* ignore */ }
+  }
+
+  return info("browser_proof_docs_or_planned", "Browser proof not yet documented as planned feature",
+    null, "Optional — document when browser proof is on the roadmap.");
+}
+
+// ── Build Browser Proof Preflight ─────────────────────────────────────────────
+
+function buildBrowserProofPreflight(cwd, options) {
+  const checks = [
+    checkLocalFirstProofPathExists(cwd),
+    checkProofDoesNotRequireBrowser(cwd),
+    checkBrowserIsOptionalEnhancement(cwd),
+    checkNoBrowserRuntimeDependency(cwd),
+    checkBrowserProofDocsOrPlanned(cwd),
+  ];
+
+  const blockers = checks.filter(function(c) { return c.status === "blocked"; });
+  const warnings = checks.filter(function(c) { return c.status === "warn"; });
+
+  var status;
+  if (blockers.length > 0) {
+    status = "blocked";
+  } else if (warnings.length > 0) {
+    status = "warn";
+  } else {
+    status = "pass";
+  }
+
+  const safeNextAction = blockers.length > 0
+    ? "Fix preflight blockers. Ensure local-first proof path works without browser."
+    : warnings.length > 0
+    ? "Review preflight warnings. Document local-first activation path and browser-optional stance."
+    : "Browser proof preflight passed. Local-first proof path verified. Browser is optional enhancement.";
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: nowIso(),
+    status,
+    checks,
+    localFirstPathVerified: !blockers.some(function(b) { return b.id === "local_first_proof_path"; }),
+    browserRequired: false, // Preflight asserts browser is never required for core value
+    browserOptionalEnhancement: true,
+    blockerCount: blockers.length,
+    warningCount: warnings.length,
+    safeNextAction,
+    noPublicLaunchClaim: true,
+    noBrowserLaunch: true, // This module never launches a browser
+    redacted: true,
+  };
+}
+
+// ── Write ─────────────────────────────────────────────────────────────────────
+
+function writeBrowserProofPreflight(cwd, preflight) {
+  const dir = path.join(cwd, ARTIFACT_DIR_REL);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(preflight, null, 2));
+}
+
+// ── Surface ───────────────────────────────────────────────────────────────────
+
+function buildBrowserProofPreflightSurface(cwd, options) {
+  const preflight = buildBrowserProofPreflight(cwd, options);
+  writeBrowserProofPreflight(cwd, preflight);
+  try {
+    appendProductLearningEvent(cwd, {
+      event: "browser_proof_preflight_run",
+      contract: CONTRACT,
+      status: preflight.status,
+      localFirstPathVerified: preflight.localFirstPathVerified,
+      browserRequired: false,
+    });
+  } catch { /* non-fatal */ }
+  return {
+    status: preflight.status,
+    localFirstPathVerified: preflight.localFirstPathVerified,
+    browserRequired: false,
+    browserOptionalEnhancement: true,
+    blockerCount: preflight.blockerCount,
+    warningCount: preflight.warningCount,
+    noPublicLaunchClaim: true,
+  };
+}
+
+// ── Format ────────────────────────────────────────────────────────────────────
+
+function formatBrowserProofPreflightText(preflight) {
+  var lines = [
+    "Browser Proof Preflight [" + (preflight.status || "?").toUpperCase() + "] (preflight only — no browser launched)",
+    "  Local-first path verified: " + (preflight.localFirstPathVerified ? "yes" : "no"),
+    "  Browser required: " + (preflight.browserRequired ? "yes" : "no"),
+    "  Browser optional enhancement: " + (preflight.browserOptionalEnhancement ? "yes" : "no"),
+    "  Blockers: " + (preflight.blockerCount || 0),
+    "  Warnings: " + (preflight.warningCount || 0),
+    "  Next: " + (preflight.safeNextAction || "Review browser proof preflight."),
+  ];
+  return lines.join("\n");
+}
+
+// ── Detect Browser Proof Capabilities ────────────────────────────────────────
+
+function detectBrowserProofCapabilities(cwd, options) {
+  options = options || {};
+  const preflight = buildBrowserProofPreflight(cwd, options);
+  return {
+    localFirstPathVerified: preflight.localFirstPathVerified,
+    browserRequired: preflight.browserRequired,
+    browserOptionalEnhancement: preflight.browserOptionalEnhancement,
+    status: preflight.status,
+    noBrowserLaunch: preflight.noBrowserLaunch,
+    blockerCount: preflight.blockerCount,
+    warningCount: preflight.warningCount,
+  };
+}
+
+// ── Classify Browser Proof Need ───────────────────────────────────────────────
+// Returns: "not_required" | "optional_enhancement" | "required_unavailable"
+
+function classifyBrowserProofNeed(cwd, options) {
+  options = options || {};
+  const caps = detectBrowserProofCapabilities(cwd, options);
+  if (caps.browserRequired === true) return "required_unavailable";
+  if (caps.localFirstPathVerified) return "not_required";
+  return "optional_enhancement";
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  ARTIFACT_REL,
+  buildBrowserProofPreflight,
+  writeBrowserProofPreflight,
+  buildBrowserProofPreflightSurface,
+  formatBrowserProofPreflightText,
+  checkLocalFirstProofPathExists,
+  checkProofDoesNotRequireBrowser,
+  checkBrowserIsOptionalEnhancement,
+  checkNoBrowserRuntimeDependency,
+  checkBrowserProofDocsOrPlanned,
+  detectBrowserProofCapabilities,
+  classifyBrowserProofNeed,
+};

package/scripts/lib/cache-readiness.js

@@ -0,0 +1,296 @@
+"use strict";
+
+// ── Cache Readiness Checker ───────────────────────────────────────────────────
+//
+// Checks whether prompt layout is stable and cache-friendly.
+// Does NOT claim active caching from any provider.
+// Does NOT act as a caching gateway.
+//
+// Contract: avorelo.cacheReadiness.v1
+//
+// Non-goals: OpenAI/Anthropic/LiteLLM cache integration, provider-specific claims,
+//            cache warming, cache invalidation management.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.cacheReadiness.v1";
+const SCHEMA_VERSION = 1;
+
+const CACHE_DIR_REL = ".claude/cco/orchestration/cache-readiness";
+const LATEST_READINESS_REL = `${CACHE_DIR_REL}/latest-readiness.json`;
+
+// ── Deterministic volatile-prefix detection ───────────────────────────────────
+//
+// A cache prefix only stays cache-hot if its content is byte-stable across runs.
+// Embedded timestamps / session IDs / UUIDs / absolute paths / PIDs silently
+// bust the prefix every run. Detect them deterministically (no model, no
+// provider call). claimType is "heuristic" — advisory, never blocking.
+
+const VOLATILE_PATTERNS = [
+  ["iso_timestamp", /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?\b/],
+  ["epoch_millis", /\b1[0-9]{12}\b/],
+  ["uuid", /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/],
+  ["session_id", /\b(?:session|sess|sid)[-_=:]\s*[A-Za-z0-9]{6,}\b/i],
+  ["user_id", /\b(?:user|uid|userId)[-_=:]\s*[A-Za-z0-9]{4,}\b/i],
+  ["request_id", /\b(?:request|req|reqId|trace|correlation)[-_=:]\s*[A-Za-z0-9]{6,}\b/i],
+  ["run_id", /\b(?:run|runId|build)[-_=:]\s*[A-Za-z0-9]{6,}\b/i],
+  ["pid", /\b(?:pid|process)[-_=:]\s*\d{2,}\b/i],
+  ["abs_path_win", /\b[A-Za-z]:\\(?:[^\s\\]+\\?){2,}/],
+  ["abs_path_posix", /(?:^|\s)\/(?:home|users|tmp|var|root)\/[^\s]+/i],
+  ["long_hex", /\b[A-Fa-f0-9]{32,}\b/],
+];
+
+function detectVolatilePrefixContent(prefixText) {
+  const text = typeof prefixText === "string" ? prefixText : "";
+  const volatileMatches = [];
+  for (const [type, re] of VOLATILE_PATTERNS) {
+    const m = text.match(re);
+    if (m) {
+      // Never surface the raw value (may be a path/secret-ish) — only the type + length.
+      volatileMatches.push({ type, sampleLength: m[0].length });
+    }
+  }
+  return {
+    stable: volatileMatches.length === 0,
+    volatileTypes: volatileMatches.map((v) => v.type),
+    volatileCount: volatileMatches.length,
+    claimType: "heuristic",
+  };
+}
+
+// Compare 2+ sampled prefixes for byte-stability after stripping volatile tokens.
+// If they differ only in volatile content → prefix is "logically stable but
+// volatile-busted"; if they differ structurally → ordering/content unstable.
+function stripVolatile(text) {
+  let out = typeof text === "string" ? text : "";
+  for (const [, re] of VOLATILE_PATTERNS) {
+    out = out.replace(new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g"), "§VOL§");
+  }
+  return out;
+}
+
+function checkPrefixStability(samples) {
+  const list = Array.isArray(samples) ? samples.filter((s) => typeof s === "string") : [];
+  if (list.length < 2) {
+    return {
+      evaluated: false,
+      reasonCode: "cache_prefix_samples_insufficient",
+      detail: "Need >=2 prefix samples to compare stability.",
+      claimType: "heuristic",
+    };
+  }
+  const rawAllEqual = list.every((s) => s === list[0]);
+  const strippedAllEqual = list.every((s) => stripVolatile(s) === stripVolatile(list[0]));
+  const volatile = detectVolatilePrefixContent(list[0]);
+
+  let reasonCode;
+  let stable;
+  if (rawAllEqual) {
+    reasonCode = "cache_prefix_stable";
+    stable = true;
+  } else if (strippedAllEqual) {
+    reasonCode = "cache_prefix_volatile"; // identical structure, busted by volatile tokens
+    stable = false;
+  } else {
+    reasonCode = "cache_ordering_unstable"; // structural drift across runs
+    stable = false;
+  }
+  return {
+    evaluated: true,
+    stable,
+    reasonCode,
+    rawAllEqual,
+    strippedAllEqual,
+    volatileTypes: volatile.volatileTypes,
+    claimType: "heuristic",
+  };
+}
+
+// ── Prompt layout checks ──────────────────────────────────────────────────────
+
+function checkPromptLayoutStability(input, options = {}) {
+  const checks = [];
+  let {
+    hasStaticInstructionsBefore = null,
+    hasDynamicTaskAfter = null,
+    toolDefinitionsGrouped = null,
+    dynamicToolOutputInPrefix = null,
+    fileSpecificContentLate = null,
+    orderingStableAcrossRuns = null,
+    providerConfirmed = false,
+  } = input || {};
+
+  // Deterministic derivation: if the caller supplies real prefix text/samples,
+  // derive stability signals instead of trusting asserted booleans.
+  const { prefixText = null, prefixSamples = null } = input || {};
+  if (prefixText && typeof prefixText === "string") {
+    const v = detectVolatilePrefixContent(prefixText);
+    if (!v.stable) {
+      checks.push({ id: "prefix_volatile_content", status: "warn", detail: `Prefix contains volatile content (${v.volatileTypes.join(", ")}); busts cache every run.`, reasonCode: "cache_prefix_volatile", claimType: "heuristic" });
+      // A volatile prefix means tool/dynamic content effectively sits in the prefix.
+      if (dynamicToolOutputInPrefix === null) dynamicToolOutputInPrefix = true;
+    } else {
+      checks.push({ id: "prefix_volatile_content", status: "pass", detail: "No volatile tokens detected in prefix.", reasonCode: "cache_prefix_stable", claimType: "heuristic" });
+    }
+  }
+  if (Array.isArray(prefixSamples) && prefixSamples.length >= 2) {
+    const s = checkPrefixStability(prefixSamples);
+    checks.push({ id: "prefix_stability_across_runs", status: s.stable ? "pass" : "warn", detail: `Prefix stability across ${prefixSamples.length} samples: ${s.reasonCode}.`, reasonCode: s.reasonCode, claimType: "heuristic" });
+    // Derive ordering stability when not explicitly asserted.
+    if (orderingStableAcrossRuns === null) orderingStableAcrossRuns = s.reasonCode === "cache_prefix_stable";
+  }
+
+  // Static instructions before dynamic task
+  if (hasStaticInstructionsBefore === true) {
+    checks.push({ id: "static_before_dynamic", status: "pass", detail: "Static instructions precede dynamic task content." });
+  } else if (hasStaticInstructionsBefore === false) {
+    checks.push({ id: "static_before_dynamic", status: "warn", detail: "Dynamic content may appear before static instructions, reducing cache stability." });
+  } else {
+    checks.push({ id: "static_before_dynamic", status: "unknown", detail: "Cannot determine ordering from available signals." });
+  }
+
+  // Dynamic tool output not in cache prefix
+  if (dynamicToolOutputInPrefix === true) {
+    checks.push({ id: "dynamic_output_not_in_prefix", status: "warn", detail: "Dynamic tool output appears in cache prefix position. Move to suffix for cache stability." });
+  } else if (dynamicToolOutputInPrefix === false) {
+    checks.push({ id: "dynamic_output_not_in_prefix", status: "pass", detail: "Dynamic tool output is not in cache prefix position." });
+  } else {
+    checks.push({ id: "dynamic_output_not_in_prefix", status: "unknown", detail: "Tool output position not confirmed." });
+  }
+
+  // File-specific content late
+  if (fileSpecificContentLate === true) {
+    checks.push({ id: "file_specific_content_late", status: "pass", detail: "File-specific content appears late in prompt (after stable prefix)." });
+  } else if (fileSpecificContentLate === false) {
+    checks.push({ id: "file_specific_content_late", status: "warn", detail: "File-specific content appears early; may invalidate cache prefix on every file change." });
+  } else {
+    checks.push({ id: "file_specific_content_late", status: "unknown", detail: "File content position not confirmed." });
+  }
+
+  // Tool definitions grouped
+  if (toolDefinitionsGrouped === true) {
+    checks.push({ id: "tool_definitions_grouped", status: "pass", detail: "Tool definitions are grouped and stable." });
+  } else if (toolDefinitionsGrouped === false) {
+    checks.push({ id: "tool_definitions_grouped", status: "warn", detail: "Tool definitions appear scattered or dynamic. Group them for cache stability." });
+  } else {
+    checks.push({ id: "tool_definitions_grouped", status: "unknown", detail: "Tool definition grouping not confirmed." });
+  }
+
+  // Stable ordering across runs
+  if (orderingStableAcrossRuns === true) {
+    checks.push({ id: "ordering_stable", status: "pass", detail: "Prompt ordering is stable across runs." });
+  } else if (orderingStableAcrossRuns === false) {
+    checks.push({ id: "ordering_stable", status: "warn", detail: "Prompt ordering varies across runs. Randomized or unstable ordering prevents caching." });
+  } else {
+    checks.push({ id: "ordering_stable", status: "unknown", detail: "Ordering stability not confirmed." });
+  }
+
+  // Provider not confirmed — no active cache claim
+  if (!providerConfirmed) {
+    checks.push({ id: "provider_confirmed", status: "unknown", detail: "Provider not confirmed. No active cache claim can be made." });
+  } else {
+    checks.push({ id: "provider_confirmed", status: "pass", detail: `Provider confirmed: ${providerConfirmed}.` });
+  }
+
+  return checks;
+}
+
+function buildCacheReadiness(cwd, input = {}, options = {}) {
+  const checks = checkPromptLayoutStability(input, options);
+
+  const passed = checks.filter((c) => c.status === "pass").length;
+  const warned = checks.filter((c) => c.status === "warn").length;
+  const unknown = checks.filter((c) => c.status === "unknown").length;
+  const failed = checks.filter((c) => c.status === "fail").length;
+
+  let readinessLevel;
+  if (failed > 0) readinessLevel = "not_ready";
+  else if (warned > 0) readinessLevel = "partial";
+  else if (unknown === checks.length) readinessLevel = "unknown";
+  else if (passed > 0 && warned === 0) readinessLevel = "ready";
+  else readinessLevel = "partial";
+
+  const caveats = ["Cache readiness is a layout signal only. No provider-specific cache claim is made."];
+  if (unknown > 0) {
+    caveats.push(`${unknown} check(s) could not be evaluated from available signals.`);
+  }
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    readinessLevel,
+    checksPass: passed,
+    checksWarn: warned,
+    checksUnknown: unknown,
+    checksFail: failed,
+    checks,
+    caveats,
+    noProviderCacheClaim: true,
+    redacted: true,
+  };
+}
+
+function writeCacheReadiness(cwd, readiness) {
+  const dir = path.join(cwd, CACHE_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const abs = path.join(cwd, LATEST_READINESS_REL);
+  fs.writeFileSync(abs, JSON.stringify(readiness, null, 2), "utf8");
+  try {
+    appendProductLearningEvent(cwd, "cache_readiness_checked", {
+      readinessLevel: readiness.readinessLevel,
+      checksPass: readiness.checksPass,
+      checksWarn: readiness.checksWarn,
+      noProviderCacheClaim: readiness.noProviderCacheClaim,
+    });
+  } catch {}
+  return abs;
+}
+
+function buildCacheReadinessSurface(cwd, options = {}) {
+  const abs = path.join(cwd, LATEST_READINESS_REL);
+  if (!fs.existsSync(abs)) {
+    return { status: "not_available", artifactPath: LATEST_READINESS_REL };
+  }
+  try {
+    const r = JSON.parse(fs.readFileSync(abs, "utf8"));
+    return {
+      status: "available",
+      readinessLevel: r.readinessLevel,
+      checksPass: r.checksPass,
+      checksWarn: r.checksWarn,
+      noProviderCacheClaim: r.noProviderCacheClaim,
+      artifactPath: LATEST_READINESS_REL,
+    };
+  } catch {
+    return { status: "error", artifactPath: LATEST_READINESS_REL };
+  }
+}
+
+function formatCacheReadinessText(readiness, options = {}) {
+  const lines = [`Cache Readiness: ${readiness.readinessLevel}`];
+  lines.push(`  Pass: ${readiness.checksPass} | Warn: ${readiness.checksWarn} | Unknown: ${readiness.checksUnknown}`);
+  lines.push(`  noProviderCacheClaim: ${readiness.noProviderCacheClaim}`);
+  for (const c of readiness.checks) {
+    if (c.status !== "pass") lines.push(`  [${c.status}] ${c.id}: ${c.detail}`);
+  }
+  if (readiness.caveats.length) lines.push(`  Caveat: ${readiness.caveats[0]}`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  CACHE_DIR_REL,
+  LATEST_READINESS_REL,
+  detectVolatilePrefixContent,
+  checkPrefixStability,
+  checkPromptLayoutStability,
+  buildCacheReadiness,
+  writeCacheReadiness,
+  buildCacheReadinessSurface,
+  formatCacheReadinessText,
+};