@awak-app/simy-cli 0.2.3 → 0.4.0

package/src/sqm/checkers.js

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_FILES_PER_PATTERN = 5_000;
+
+export async function executeKnowledgeBundle(bundle, repository) {
+  return (await evaluateKnowledgeBundle(bundle, repository)).findings;
+}
+
+export async function evaluateKnowledgeBundle(bundle, repository) {
+  const findings = [];
+  const modules = [];
+  for (const module of bundle.modules) {
+    if (["candidate", "retired"].includes(module.lifecycle.status)) continue;
+    if (!moduleApplies(module, repository.repository)) continue;
+    if (!(await matchModule(module, repository))) continue;
+    const exceptions = activeExceptionPatterns(module);
+    const ruleResults = [];
+    for (const rule of module.detection.checks) {
+      const violations = await executeRule(rule, repository);
+      const accepted = violations.filter((violation) => !exceptions.some((glob) => globMatches(glob, violation.file)));
+      ruleResults.push({ rule_id: rule.id, status: accepted.length ? "failed" : "passed", finding_count: accepted.length });
+      for (const violation of accepted) {
+        const evidenceHash = sha256(violation.evidence);
+        const findingId = sha256([bundle.integrity.digest, module.id, rule.id, violation.file || "repository", violation.line ?? "", violation.side || "", evidenceHash].join("\0"));
+        const assurance = assuranceContext(module, rule.id);
+        findings.push({
+          finding_id: `sqm:${findingId}`,
+          module_id: module.id,
+          module_version: module.version,
+          rule_id: rule.id,
+          lifecycle: module.lifecycle.status,
+          severity: module.lifecycle.severity,
+          message: rule.message,
+          invariant: module.invariant.statement,
+          remediation: module.invariant.remediation ?? null,
+          incident_refs: [...module.incident_refs],
+          file: violation.file,
+          line: violation.line ?? null,
+          side: violation.side ?? null,
+          evidence_hash: `sha256:${evidenceHash}`,
+          bundle_id: bundle.bundle_id,
+          bundle_version: bundle.version,
+          bundle_digest: bundle.integrity.digest,
+          state_model_ids: assurance.state_model_ids,
+          transition_ids: assurance.transition_ids,
+          stressor_ids: assurance.stressor_ids,
+          strength_ids: assurance.strength_ids,
+          scenario_ids: assurance.scenario_ids,
+        });
+      }
+    }
+    modules.push(evaluateAssurance(module, ruleResults));
+  }
+  return { findings, modules };
+}
+
+function evaluateAssurance(module, ruleResults) {
+  const failed = new Set(ruleResults.filter((result) => result.status === "failed").map((result) => result.rule_id));
+  const assurance = module.assurance;
+  if (!assurance) {
+    return {
+      module_id: module.id,
+      module_version: module.version,
+      lifecycle: module.lifecycle.status,
+      severity: module.lifecycle.severity,
+      rule_results: ruleResults,
+      state_models: [],
+      stressors: [],
+      strengths: [],
+      scenarios: [],
+    };
+  }
+  const stressors = assurance.stressors.map((stressor) => ({
+    id: stressor.id,
+    status: stressor.activation_check_refs.some((ref) => failed.has(ref)) ? "activated" : "not_activated",
+    check_refs: [...stressor.activation_check_refs],
+  }));
+  const strengths = assurance.strengths.map((strength) => ({
+    id: strength.id,
+    status: strength.check_refs.some((ref) => failed.has(ref)) ? "failed" : "passed",
+    check_refs: [...strength.check_refs],
+  }));
+  const strengthStatus = new Map(strengths.map((strength) => [strength.id, strength.status]));
+  const scenarios = assurance.scenarios.map((scenario) => {
+    let status = scenario.execution_requirement;
+    if (scenario.execution_requirement === "local") {
+      const checkFailed = scenario.check_refs.some((ref) => failed.has(ref));
+      const strengthFailed = scenario.expected_strength_refs.some((ref) => strengthStatus.get(ref) === "failed");
+      status = checkFailed || strengthFailed ? "failed" : "passed";
+    }
+    return {
+      id: scenario.id,
+      state_model_id: scenario.state_model_id,
+      transition_id: scenario.transition_id,
+      status,
+      stressor_refs: [...scenario.stressor_refs],
+      expected_strength_refs: [...scenario.expected_strength_refs],
+      check_refs: [...scenario.check_refs],
+    };
+  });
+  const scenarioStatus = new Map(scenarios.map((scenario) => [scenario.id, scenario.status]));
+  const stateModels = assurance.state_models.map((model) => ({
+    id: model.id,
+    version: model.version,
+    transitions: model.transitions.map((transition) => ({
+      id: transition.id,
+      from: transition.from,
+      event: transition.event,
+      to: transition.to,
+      status: transition.scenario_refs.some((ref) => scenarioStatus.get(ref) === "failed") ? "failed" :
+        transition.scenario_refs.some((ref) => ["requires_human", "requires_post_deploy"].includes(scenarioStatus.get(ref))) ? "skipped" : "passed",
+      scenario_refs: [...transition.scenario_refs],
+    })),
+  }));
+  return {
+    module_id: module.id,
+    module_version: module.version,
+    lifecycle: module.lifecycle.status,
+    severity: module.lifecycle.severity,
+    rule_results: ruleResults,
+    state_models: stateModels,
+    stressors,
+    strengths,
+    scenarios,
+  };
+}
+
+function assuranceContext(module, ruleId) {
+  const assurance = module.assurance;
+  if (!assurance) return { state_model_ids: [], transition_ids: [], stressor_ids: [], strength_ids: [], scenario_ids: [] };
+  const stressorIds = assurance.stressors.filter((item) => item.activation_check_refs.includes(ruleId)).map((item) => item.id);
+  const strengthIds = assurance.strengths.filter((item) => item.check_refs.includes(ruleId)).map((item) => item.id);
+  const scenarios = assurance.scenarios.filter((item) => item.check_refs.includes(ruleId) || item.stressor_refs.some((id) => stressorIds.includes(id)) || item.expected_strength_refs.some((id) => strengthIds.includes(id)));
+  const scenarioIds = scenarios.map((item) => item.id);
+  const stateModelIds = [...new Set(scenarios.map((item) => item.state_model_id))];
+  const transitionIds = [...new Set(scenarios.map((item) => item.transition_id))];
+  return { state_model_ids: stateModelIds, transition_ids: transitionIds, stressor_ids: stressorIds, strength_ids: strengthIds, scenario_ids: scenarioIds };
+}
+
+function moduleApplies(module, repository) {
+  const scoped = module.scope.repositories;
+  return !scoped?.length || scoped.some((item) => item.toLowerCase() === repository.toLowerCase());
+}
+
+async function matchModule(module, repository) {
+  for (const matcher of module.detection.matchers) {
+    if (!(await match(matcher, repository))) return false;
+  }
+  return true;
+}
+
+async function match(matcher, repository) {
+  const changed = repository.diff.filter((file) => matchesAny(matcher.paths, file.path));
+  if (matcher.type === "changed_path") return changed.length > 0;
+  const regex = safeRegex(matcher.pattern);
+  if (matcher.type === "diff_regex" || matcher.type === "reference") {
+    return changed.some((file) => file.lines.some((line) => sideMatches(matcher.side, line.side) && test(regex, line.text)));
+  }
+  if (matcher.type === "content_regex") {
+    const files = selectPaths(repository.paths, matcher.paths);
+    for (const file of files) if (test(regex, await readText(repository.root, file))) return true;
+  }
+  return false;
+}
+
+async function executeRule(rule, repository) {
+  switch (rule.type) {
+    case "diff_regex":
+      return diffRegex(rule, repository);
+    case "path_presence":
+      return pathPresence(rule, repository);
+    case "content_regex":
+      return contentRegex(rule, repository);
+    case "reference_definition":
+      return referenceDefinition(rule, repository);
+    default:
+      throw new Error(`Unsupported SQM checker type: ${rule.type}`);
+  }
+}
+
+function diffRegex(rule, repository) {
+  const regex = safeRegex(rule.pattern);
+  const matches = [];
+  for (const file of repository.diff.filter((item) => matchesAny(rule.paths || ["**"], item.path))) {
+    for (const line of file.lines) if (sideMatches(rule.side, line.side) && test(regex, line.text)) matches.push({ file: file.path, line: line.line, side: line.side, evidence: `${line.side}: ${line.text}` });
+  }
+  if (rule.expect === "present") return matches.length ? [] : [{ file: null, evidence: "Required diff pattern was not present." }];
+  return matches;
+}
+
+function pathPresence(rule, repository) {
+  const matches = selectPaths(repository.paths, rule.paths || []);
+  if (rule.expect === "present") return matches.length ? [] : [{ file: null, evidence: `Required repository path was not present: ${(rule.paths || []).join(", ")}` }];
+  return matches.map((file) => ({ file, evidence: `Forbidden repository path is present: ${file}` }));
+}
+
+async function contentRegex(rule, repository) {
+  const regex = safeRegex(rule.pattern);
+  const matches = [];
+  for (const file of selectPaths(repository.paths, rule.paths || ["**"])) {
+    const content = await readText(repository.root, file);
+    for (const result of matchLines(regex, content)) matches.push({ file, line: result.line, evidence: truncate(result.text) });
+  }
+  if (rule.expect === "present") return matches.length ? [] : [{ file: null, evidence: "Required content pattern was not present." }];
+  return matches;
+}
+
+async function referenceDefinition(rule, repository) {
+  const regex = safeRegex(rule.pattern);
+  const references = [];
+  for (const file of repository.diff.filter((item) => matchesAny(rule.paths || ["**"], item.path))) {
+    for (const line of file.lines.filter((item) => item.side === "added")) {
+      for (const match of allMatches(regex, line.text)) references.push({ value: match[1] || match[0], file: file.path, line: line.line });
+    }
+  }
+  const definitions = await Promise.all(selectPaths(repository.paths, rule.definition_paths || []).map((file) => readText(repository.root, file)));
+  return references
+    .filter((reference) => !definitions.some((content) => content.includes(reference.value)))
+    .map((reference) => ({ file: reference.file, line: reference.line, evidence: `Reference ${reference.value} has no definition in ${(rule.definition_paths || []).join(", ")}.` }));
+}
+
+function activeExceptionPatterns(module) {
+  const now = Date.now();
+  return (module.detection.exceptions || [])
+    .filter((item) => !item.expires_at || Date.parse(item.expires_at) > now)
+    .flatMap((item) => item.paths);
+}
+
+function selectPaths(paths, globs) {
+  return paths.filter((file) => matchesAny(globs, file)).slice(0, MAX_FILES_PER_PATTERN);
+}
+
+function matchesAny(globs, file) {
+  return globs.some((glob) => globMatches(glob, file));
+}
+
+export function globMatches(glob, file) {
+  const value = String(glob);
+  let source = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character === "*" && value[index + 1] === "*" && value[index + 2] === "/") {
+      source += "(?:.*/)?";
+      index += 2;
+    } else if (character === "*" && value[index + 1] === "*") {
+      source += ".*";
+      index += 1;
+    } else if (character === "*") source += "[^/]*";
+    else if (character === "?") source += "[^/]";
+    else source += /[.+^${}()|[\]\\]/.test(character) ? `\\${character}` : character;
+  }
+  return new RegExp(`^${source}$`).test(file);
+}
+
+function safeRegex(pattern) {
+  let source = String(pattern || "");
+  let flags = "g";
+  const leadingFlags = source.match(/^\(\?([ims]+)\)/);
+  if (leadingFlags) {
+    flags += [...new Set(leadingFlags[1])].join("");
+    source = source.slice(leadingFlags[0].length);
+  }
+  if (source.length > 2_000 || /\\[1-9]|\(\?[=!<]|\([^)]*[+*][^)]*\)[+*{]/.test(source)) {
+    throw new Error("SQM regex uses an unsupported potentially unsafe construct.");
+  }
+  if (/\(\?[ims-]/.test(source)) {
+    throw new Error("SQM regex flags must appear once at the start of the pattern.");
+  }
+  return new RegExp(source, flags);
+}
+
+function test(regex, text) { regex.lastIndex = 0; return regex.test(text); }
+function allMatches(regex, text) { regex.lastIndex = 0; return [...text.matchAll(regex)]; }
+function sideMatches(expected, actual) { return !expected || expected === "either" || expected === actual; }
+function truncate(value) { const text = String(value); return text.length > 300 ? `${text.slice(0, 297)}...` : text; }
+function sha256(value) { return createHash("sha256").update(String(value)).digest("hex"); }
+
+function matchLines(regex, content) {
+  const results = [];
+  for (const [index, line] of content.split(/\r?\n/).entries()) if (test(regex, line)) results.push({ line: index + 1, text: line });
+  return results;
+}
+
+async function readText(root, relative) {
+  const resolved = path.resolve(root, relative);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) throw new Error("SQM path escaped the repository root.");
+  try {
+    const fileStat = await lstat(resolved);
+    if (!fileStat.isFile() || fileStat.isSymbolicLink()) return "";
+    const buffer = await readFile(resolved);
+    if (buffer.length > MAX_FILE_BYTES || buffer.includes(0)) return "";
+    return buffer.toString("utf8");
+  } catch {
+    return "";
+  }
+}

package/src/sqm/command.js

@@ -0,0 +1,149 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { isSessionValid, readSession } from "../session-store.js";
+import { resolveWebOrigin } from "../web-origin.js";
+import { uploadRunEvidence } from "./evidence-client.js";
+import { runSqmCheck, runSqmMinCheck } from "./index.js";
+import { ensureSqmSession } from "./session.js";
+
+export async function runSqmCommand(argv, { cliVersion }) {
+  if (argv.includes("--help") || argv.includes("-h") || !argv.length) {
+    printHelp();
+    return 0;
+  }
+  if (!["min-check", "check"].includes(argv[0])) throw new Error("Usage: simy sqm <min-check|check> [options]");
+  const webOrigin = resolveWebOrigin(option(argv, "--host"));
+  let session = await readSession(webOrigin);
+  let validSession = isSessionValid(session, Date.now(), webOrigin) ? session : null;
+  if (!validSession && !explicitSqmEnvironment(argv)) {
+    session = await ensureSqmSession(webOrigin, { noOpen: argv.includes("--no-open") });
+    validSession = session;
+  }
+  const organizationId = process.env.SIMY_SQM_ORGANIZATION_ID || validSession?.organization_id || validSession?.org_id;
+  const token = process.env.SIMY_SQM_TOKEN || process.env.SIMY_ACCESS_TOKEN || validSession?.token;
+  const accountId = process.env.SIMY_SQM_ACCOUNT_ID || validSession?.account_id || validSession?.auth_user_id || validSession?.device_id;
+  const deviceId = process.env.SIMY_SQM_DEVICE_ID || validSession?.device_id;
+  if (!organizationId) throw new Error(`SQM needs an organization-bound SIMY session. Run \`simy --host ${webOrigin}\` once, then retry.`);
+  const endpoint = process.env.SIMY_SQM_BUNDLE_URL || (validSession?.api_base_url ? new URL("sqm/knowledge-bundle", validSession.api_base_url).href : undefined);
+  const common = {
+    cwd: process.cwd(),
+    baseBranch: option(argv, "--base") || "dev",
+    cliVersion,
+    offline: argv.includes("--offline"),
+    refresh: argv.includes("--refresh"),
+    token,
+    endpoint,
+    accountId,
+    organizationId,
+  };
+
+  if (argv[0] === "min-check") {
+    const result = await runSqmMinCheck(common);
+    const output = option(argv, "--output") || defaultMinResultPath();
+    await atomicJson(output, result);
+    if (argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+    else printMin(result, output);
+    return result.status === "unavailable" ? 2 : result.status === "preliminary_failed" ? 1 : 0;
+  }
+
+  const minPath = option(argv, "--min-result") || defaultMinResultPath();
+  let minCheck;
+  try {
+    minCheck = JSON.parse(await readFile(minPath, "utf8"));
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    console.warn("No min-check result was found; running the deterministic min-check first.");
+    minCheck = await runSqmMinCheck(common);
+    await atomicJson(minPath, minCheck);
+  }
+  const result = await runSqmCheck({ ...common, minCheck, deviceId, signingKeyPath: option(argv, "--signing-key") || undefined });
+  const proofPath = path.resolve(option(argv, "--proof") || "proof.json");
+  const evidencePath = path.resolve(option(argv, "--signed-evidence") || `${proofPath}.signed.json`);
+  await Promise.all([atomicJson(proofPath, result.proof), atomicJson(evidencePath, result.signed_evidence)]);
+  let upload = { uploaded: false, reason: "disabled" };
+  if (!argv.includes("--no-upload")) {
+    const evidenceEndpoint = process.env.SIMY_SQM_EVIDENCE_URL || (validSession?.api_base_url ? new URL("sqm/run-evidence", validSession.api_base_url).href : undefined);
+    upload = await uploadRunEvidence({ endpoint: evidenceEndpoint, token, proof: result.proof, signedEvidence: result.signed_evidence });
+  }
+  result.upload = upload;
+  result.artifacts = { min_check: minPath, proof: proofPath, signed_evidence: evidencePath };
+  if (argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+  else printFull(result);
+  return result.proof.outcome.status === "failed" ? 1 : 0;
+}
+
+function printHelp() {
+  console.log(`Usage:
+  simy sqm min-check [options]
+  simy sqm check [options]
+
+Two-stage SQM flow:
+  min-check  Fast deterministic diff preflight and full-check execution plan.
+  check      Full state/invariant/stress/strength/scenario verification. It
+             verifies the pinned min-check identity, writes proof.json, and
+             produces independent per-run signed evidence.
+
+Options:
+  --base <branch>             Compare against this base branch (default: dev)
+  --host <origin>             SIMY Web origin used for the existing device session
+  --offline                   Use only the last verified cached knowledge bundle
+  --refresh                   Revalidate the signed bundle
+  --no-open                   Print the sign-in URL instead of opening a browser
+  --output <path>             min-check result path
+  --min-result <path>         full check input (default: the last local min-check)
+  --proof <path>              proof.json output (default: ./proof.json)
+  --signed-evidence <path>    per-run signature output
+  --no-upload                 keep proof local instead of uploading hashes/results
+  --json                      print machine-readable output
+
+Neither phase executes Cloud-provided code or calls a local LLM.`);
+}
+
+function explicitSqmEnvironment(argv) {
+  const organization = process.env.SIMY_SQM_ORGANIZATION_ID?.trim();
+  const account = process.env.SIMY_SQM_ACCOUNT_ID?.trim();
+  if (argv.includes("--offline")) return Boolean(organization && account);
+  const token = (process.env.SIMY_SQM_TOKEN || process.env.SIMY_ACCESS_TOKEN)?.trim();
+  const endpoint = process.env.SIMY_SQM_BUNDLE_URL?.trim();
+  return Boolean(organization && token && endpoint);
+}
+
+function printMin(result, output) {
+  for (const warning of result.warnings || []) console.warn(`warning: ${warning}`);
+  if (result.status === "unavailable") return;
+  console.log(`SQM min-check: ${result.status} · ${result.preliminary_findings.length} preliminary finding(s)`);
+  console.log(`Pinned bundle ${result.knowledge_bundle.id}@${result.knowledge_bundle.version} (${result.knowledge_bundle.digest})`);
+  console.log(`Full-check plan: ${result.full_check_plan.length} scenario(s)`);
+  console.log(`Result: ${output}`);
+}
+
+function printFull(result) {
+  console.log(`SQM full check: ${result.proof.outcome.status} · ${result.findings.length} finding(s)`);
+  console.log(`Proof ${result.proof.proof_id} (${result.proof.integrity.digest})`);
+  console.log(`Per-run signature: valid · ${result.signature_verification.key_id}`);
+  console.log(`Artifacts: ${result.artifacts.proof} · ${result.artifacts.signed_evidence}`);
+  if (result.upload.uploaded) console.log(`Cloud evidence: stored · ${result.upload.evidence_id || result.signed_evidence.evidence_id}`);
+  else console.log(`Cloud evidence: local only (${result.upload.reason})`);
+}
+
+function defaultMinResultPath() {
+  return path.join(process.env.SIMY_HOME?.trim() || path.join(homedir(), ".simy"), "sqm", "min-check.json");
+}
+
+async function atomicJson(target, value) {
+  const resolved = path.resolve(target);
+  await mkdir(path.dirname(resolved), { recursive: true, mode: 0o700 });
+  const temporary = `${resolved}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, resolved);
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  if (index < 0) return null;
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
+}

package/src/sqm/evidence-client.js

@@ -0,0 +1,12 @@
+export async function uploadRunEvidence({ endpoint, token, proof, signedEvidence, fetchImpl = globalThis.fetch }) {
+  if (!endpoint || !token) return { uploaded: false, reason: "authenticated_cloud_session_unavailable" };
+  const response = await fetchImpl(endpoint, {
+    method: "POST",
+    headers: { accept: "application/json", authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify({ proof, signed_evidence: signedEvidence }),
+    signal: AbortSignal.timeout(10_000),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(`SQM run evidence upload failed with HTTP ${response.status}${payload?.error ? `: ${typeof payload.error === "string" ? payload.error : payload.error.message || "unknown error"}` : ""}.`);
+  return { uploaded: true, ...payload };
+}

package/src/sqm/index.js

@@ -0,0 +1,141 @@
+import { evaluateKnowledgeBundle } from "./checkers.js";
+import { loadKnowledgeBundle } from "./bundle-store.js";
+import { uploadRunEvidence } from "./evidence-client.js";
+import { buildProof, finalizeMinCheck, repositoryIdentity, sameRepositoryIdentity, signProof, verifyMinCheck, verifySignedEvidence } from "./proof.js";
+import { inspectRepository } from "./repository.js";
+
+export function createSqmChecker({
+  cwd = process.cwd(),
+  baseBranch = "dev",
+  cliVersion,
+  offline = false,
+  refresh = false,
+  token,
+  endpoint,
+  accountId,
+  organizationId,
+  deviceId,
+  evidenceEndpoint,
+  uploadRunEvidenceImpl = uploadRunEvidence,
+  inspectRepositoryImpl = inspectRepository,
+  loadKnowledgeBundleImpl = loadKnowledgeBundle,
+  evaluateKnowledgeBundleImpl = evaluateKnowledgeBundle,
+  executeKnowledgeBundleImpl,
+  ...dependencies
+}) {
+  let pinnedLoad = null;
+  let pinnedRepository = null;
+  let latestMinCheck = null;
+
+  return async function checkCurrentRepository(_attempt = null, { phase = "min" } = {}) {
+    let repository;
+    try {
+      repository = await inspectRepositoryImpl(cwd, { baseBranch, runCommand: dependencies.runCommand });
+    } catch (error) {
+      return unavailable(`SQM repository inspection failed: ${message(error)}`);
+    }
+    if (pinnedRepository && pinnedRepository !== repository.repository) return unavailable(`SQM repository changed during a pinned run (${pinnedRepository} to ${repository.repository}).`, repository.repository);
+    if (!pinnedLoad) {
+      pinnedRepository = repository.repository;
+      pinnedLoad = loadKnowledgeBundleImpl({ repository: repository.repository, cliVersion, offline, refresh, token, endpoint, accountId, organizationId, ...dependencies });
+    }
+    const loaded = await pinnedLoad;
+    if (!loaded.bundle) return { ...unavailable(loaded.warnings[0], repository.repository), warnings: loaded.warnings };
+    try {
+      const evaluate = executeKnowledgeBundleImpl
+        ? async (bundle, currentRepository) => ({ findings: await executeKnowledgeBundleImpl(bundle, currentRepository), modules: [] })
+        : evaluateKnowledgeBundleImpl;
+      if (phase === "full") {
+        if (!latestMinCheck || !sameRepositoryIdentity(latestMinCheck.repository_identity, repositoryIdentity(repository))) {
+          latestMinCheck = await buildMinCheck({ repository, bundle: loaded.bundle, evaluation: await evaluate(loaded.bundle, repository), organizationId: organizationId || loaded.bundle.organization_id, cliVersion });
+        }
+        const full = await buildFullCheck({ repository, bundle: loaded.bundle, minCheck: latestMinCheck, evaluation: await evaluate(loaded.bundle, repository), organizationId: organizationId || loaded.bundle.organization_id, cliVersion, deviceId, accountId });
+        try {
+          full.upload = await uploadRunEvidenceImpl({ endpoint: evidenceEndpoint, token, proof: full.proof, signedEvidence: full.signed_evidence });
+        } catch (error) {
+          full.upload = { uploaded: false, reason: `upload_failed: ${message(error)}` };
+          full.warnings.push(`SQM signed evidence remains local because Cloud upload failed: ${message(error)}`);
+        }
+        return full;
+      }
+      latestMinCheck = await buildMinCheck({ repository, bundle: loaded.bundle, evaluation: await evaluate(loaded.bundle, repository), organizationId: organizationId || loaded.bundle.organization_id, cliVersion });
+      return toLegacyCheck(latestMinCheck, loaded);
+    } catch (error) {
+      return { ...unavailable(`SQM ${phase} execution failed: ${message(error)}`, repository.repository), bundle: bundleIdentity(loaded.bundle), warnings: [...loaded.warnings, `SQM ${phase} execution failed: ${message(error)}`] };
+    }
+  };
+}
+
+export async function runSqmMinCheck(options) {
+  const context = await loadContext(options);
+  if (!context.loaded.bundle) return { ...unavailable(context.loaded.warnings[0], context.repository.repository), warnings: context.loaded.warnings };
+  const evaluation = await (options.evaluateKnowledgeBundleImpl || evaluateKnowledgeBundle)(context.loaded.bundle, context.repository);
+  return buildMinCheck({ repository: context.repository, bundle: context.loaded.bundle, evaluation, organizationId: options.organizationId, cliVersion: options.cliVersion });
+}
+
+export async function runSqmCheck(options) {
+  const context = await loadContext(options);
+  if (!context.loaded.bundle) return { ...unavailable(context.loaded.warnings[0], context.repository.repository), warnings: context.loaded.warnings };
+  verifyMinCheck(options.minCheck);
+  if (!sameRepositoryIdentity(options.minCheck.repository_identity, repositoryIdentity(context.repository))) throw new Error("Repository identity changed after min-check; run `simy sqm min-check` again.");
+  if (options.minCheck.knowledge_bundle.digest !== context.loaded.bundle.integrity.digest) throw new Error("Knowledge bundle changed after min-check; run `simy sqm min-check` again so both phases use one pinned bundle.");
+  const evaluation = await (options.evaluateKnowledgeBundleImpl || evaluateKnowledgeBundle)(context.loaded.bundle, context.repository);
+  return buildFullCheck({ repository: context.repository, bundle: context.loaded.bundle, minCheck: options.minCheck, evaluation, organizationId: options.organizationId, cliVersion: options.cliVersion, deviceId: options.deviceId, accountId: options.accountId, signingKeyPath: options.signingKeyPath });
+}
+
+async function loadContext(options) {
+  const repository = await (options.inspectRepositoryImpl || inspectRepository)(options.cwd || process.cwd(), { baseBranch: options.baseBranch || "dev", runCommand: options.runCommand });
+  const loaded = await (options.loadKnowledgeBundleImpl || loadKnowledgeBundle)({ repository: repository.repository, cliVersion: options.cliVersion, offline: options.offline, refresh: options.refresh, token: options.token, endpoint: options.endpoint, accountId: options.accountId, organizationId: options.organizationId, ...(options.bundleDependencies || {}) });
+  return { repository, loaded };
+}
+
+async function buildMinCheck({ repository, bundle, evaluation, organizationId, cliVersion }) {
+  const plan = evaluation.modules.flatMap((module) => module.scenarios.map((scenario) => ({ module_id: module.module_id, scenario_id: scenario.id, state_model_id: scenario.state_model_id, transition_id: scenario.transition_id, stressor_refs: scenario.stressor_refs, expected_strength_refs: scenario.expected_strength_refs, execution_requirement: scenario.status === "requires_human" ? "requires_human" : scenario.status === "requires_post_deploy" ? "requires_post_deploy" : "local" })));
+  return finalizeMinCheck({
+    schema_version: "1.0.0",
+    kind: "sqm_min_check",
+    organization_id: organizationId,
+    repository_identity: repositoryIdentity(repository),
+    knowledge_bundle: bundleIdentity(bundle),
+    executed_at: new Date().toISOString(),
+    cli_version: cliVersion,
+    status: evaluation.findings.length ? "preliminary_failed" : "passed",
+    preliminary_findings: evaluation.findings,
+    matched_modules: evaluation.modules.map((module) => ({ module_id: module.module_id, module_version: module.module_version, state_model_ids: module.state_models.map((model) => model.id), transition_ids: module.state_models.flatMap((model) => model.transitions.map((transition) => transition.id)), stressor_ids: module.stressors.map((stressor) => stressor.id), scenario_ids: module.scenarios.map((scenario) => scenario.id) })),
+    full_check_plan: plan,
+  });
+}
+
+async function buildFullCheck({ repository, bundle, minCheck, evaluation, organizationId, cliVersion, deviceId, accountId, signingKeyPath }) {
+  const proof = buildProof({ organizationId, repository, bundle, minCheck, evaluation, findings: evaluation.findings, cliVersion });
+  const signedEvidence = await signProof(proof, { deviceId, accountId, keyPath: signingKeyPath });
+  const verification = verifySignedEvidence(proof, signedEvidence);
+  return {
+    status: "checked",
+    mode: "full",
+    repository: repository.repository,
+    base_ref: repository.base_ref,
+    bundle: bundleIdentity(bundle),
+    min_check: minCheck,
+    findings: evaluation.findings,
+    executions: evaluation.modules,
+    proof,
+    signed_evidence: signedEvidence,
+    signature_verification: verification,
+    warnings: [],
+  };
+}
+
+function toLegacyCheck(minCheck, loaded) {
+  return { status: "checked", mode: "min", repository: minCheck.repository_identity.repository, base_ref: minCheck.repository_identity.base_ref, source: loaded.source, warnings: loaded.warnings, bundle: minCheck.knowledge_bundle, findings: minCheck.preliminary_findings, min_check: minCheck };
+}
+
+function bundleIdentity(bundle) {
+  return { id: bundle.bundle_id, version: bundle.version, digest: bundle.integrity.digest, signing_key_id: bundle.integrity.key_id };
+}
+
+function unavailable(warning, repository = null) {
+  return { status: "unavailable", mode: "shadow", repository, bundle: null, findings: [], warnings: [warning] };
+}
+
+function message(error) { return error instanceof Error ? error.message : String(error); }