@awak-app/simy-cli 0.3.3 → 0.4.0

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); }

package/src/sqm/proof.js

@@ -0,0 +1,154 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, verify } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { canonicalize } from "./canonical.js";
+
+export function repositoryIdentity(repository) {
+  return {
+    repository: repository.repository,
+    base_ref: repository.base_ref,
+    base_commit: repository.base_commit ?? null,
+    head_commit: repository.head_commit ?? null,
+    committed_diff_digest: repository.committed_diff_digest ?? null,
+    working_tree_digest: repository.working_tree_digest ?? null,
+    diff_digest: repository.diff_digest ?? null,
+  };
+}
+
+export function sameRepositoryIdentity(left, right) {
+  return ["repository", "base_ref", "base_commit", "head_commit", "committed_diff_digest", "working_tree_digest", "diff_digest"]
+    .every((key) => left?.[key] === right?.[key]);
+}
+
+export function finalizeMinCheck(value) {
+  const result = structuredClone(value);
+  delete result.result_digest;
+  return { ...result, result_digest: taggedDigest(result) };
+}
+
+export function verifyMinCheck(value) {
+  if (!value || value.schema_version !== "1.0.0" || value.kind !== "sqm_min_check") throw new Error("SQM min-check result is invalid.");
+  const copy = structuredClone(value);
+  const claimed = copy.result_digest;
+  delete copy.result_digest;
+  if (claimed !== taggedDigest(copy)) throw new Error("SQM min-check result digest does not match its content.");
+  return value;
+}
+
+export function buildProof({ organizationId, repository, bundle, minCheck, evaluation, findings, cliVersion, executedAt = new Date().toISOString() }) {
+  const statuses = evaluation.modules.flatMap((module) => module.scenarios.map((scenario) => scenario.status));
+  const failedModules = evaluation.modules.filter((module) => module.scenarios.some((scenario) => scenario.status === "failed"));
+  const hasFailure = findings.length > 0 || failedModules.length > 0;
+  const shadowOnly = hasFailure && findings.every((finding) => finding.lifecycle === "shadow") && failedModules.every((module) => module.lifecycle === "shadow");
+  const requiresHuman = statuses.includes("requires_human");
+  const requiresPostDeploy = statuses.includes("requires_post_deploy");
+  const status = shadowOnly ? "shadow" : hasFailure ? "failed" : requiresHuman ? "requires_human" : requiresPostDeploy ? "requires_post_deploy" : evaluation.modules.length === 0 ? "skipped" : "passed";
+  const proof = {
+    schema_version: "1.0.0",
+    proof_id: `SQM-PROOF-${randomUUID()}`,
+    organization_id: organizationId,
+    repository_identity: repositoryIdentity(repository),
+    knowledge_bundle: {
+      id: bundle.bundle_id,
+      version: bundle.version,
+      digest: bundle.integrity.digest,
+      signing_key_id: bundle.integrity.key_id,
+    },
+    min_check: {
+      result_digest: minCheck.result_digest,
+      executed_at: minCheck.executed_at,
+      status: minCheck.status,
+      preliminary_finding_count: minCheck.preliminary_findings.length,
+    },
+    executions: evaluation.modules,
+    findings,
+    outcome: {
+      status,
+      reasons: [
+        ...(hasFailure && !shadowOnly ? ["one_or_more_declarative_checks_failed"] : []),
+        ...(shadowOnly ? ["declarative_checks_failed_in_shadow_mode"] : []),
+        ...(evaluation.modules.length === 0 ? ["no_applicable_knowledge_module"] : []),
+        ...(requiresHuman ? ["human_evidence_required"] : []),
+        ...(requiresPostDeploy ? ["post_deploy_evidence_required"] : []),
+      ],
+    },
+    provenance: { cli_version: cliVersion, executed_at: executedAt, executor: "simy-cli" },
+  };
+  return { ...proof, integrity: { algorithm: "sha256", digest: taggedDigest(proof) } };
+}
+
+export function verifyProof(proof) {
+  const copy = structuredClone(proof);
+  const integrity = copy.integrity;
+  delete copy.integrity;
+  if (integrity?.algorithm !== "sha256" || integrity.digest !== taggedDigest(copy)) throw new Error("SQM proof digest verification failed.");
+  return integrity.digest;
+}
+
+export async function signProof(proof, {
+  deviceId,
+  accountId = null,
+  keyPath = process.env.SIMY_SQM_SIGNING_KEY_PATH || path.join(process.env.SIMY_HOME?.trim() || path.join(homedir(), ".simy"), "sqm", "run-signing-key.json"),
+  issuedAt = new Date().toISOString(),
+} = {}) {
+  if (!deviceId) throw new Error("A trusted SIMY CLI device identity is required to sign SQM proof.");
+  const identity = await loadOrCreateSigningIdentity(keyPath);
+  const proofDigest = verifyProof(proof);
+  const signature = sign(null, Buffer.from(proofDigest.slice("sha256:".length), "hex"), identity.privateKey).toString("base64");
+  return {
+    schema_version: "1.0.0",
+    evidence_id: `SQM-EVIDENCE-${randomUUID()}`,
+    proof_id: proof.proof_id,
+    organization_id: proof.organization_id,
+    repository: proof.repository_identity.repository,
+    proof_digest: proofDigest,
+    signer: {
+      type: "simy_cli_device",
+      device_id: deviceId,
+      account_id: accountId,
+      key_id: identity.keyId,
+      public_key: identity.publicKeyDer.toString("base64"),
+    },
+    issued_at: issuedAt,
+    integrity: { algorithm: "ed25519", signature },
+  };
+}
+
+export function verifySignedEvidence(proof, evidence) {
+  const proofDigest = verifyProof(proof);
+  if (evidence?.proof_id !== proof.proof_id || evidence?.proof_digest !== proofDigest || evidence?.organization_id !== proof.organization_id || evidence?.repository !== proof.repository_identity.repository) throw new Error("SQM signed evidence is not bound to this proof.");
+  if (evidence?.integrity?.algorithm !== "ed25519") throw new Error("SQM signed evidence uses an unsupported algorithm.");
+  const publicKeyDer = Buffer.from(String(evidence?.signer?.public_key || ""), "base64");
+  const keyId = `sha256:${createHash("sha256").update(publicKeyDer).digest("hex")}`;
+  if (evidence?.signer?.key_id !== keyId) throw new Error("SQM signed evidence key ID does not match its public key.");
+  const publicKey = createPublicKey({ key: publicKeyDer, format: "der", type: "spki" });
+  const signature = Buffer.from(String(evidence?.integrity?.signature || ""), "base64");
+  if (signature.length !== 64 || !verify(null, Buffer.from(proofDigest.slice("sha256:".length), "hex"), publicKey, signature)) throw new Error("SQM per-run signature verification failed.");
+  return { proof_digest: proofDigest, key_id: keyId, valid: true };
+}
+
+async function loadOrCreateSigningIdentity(location) {
+  try {
+    const parsed = JSON.parse(await readFile(location, "utf8"));
+    const privateKey = createPrivateKey({ key: Buffer.from(parsed.private_key, "base64"), format: "der", type: "pkcs8" });
+    const publicKeyDer = Buffer.from(parsed.public_key, "base64");
+    const keyId = `sha256:${createHash("sha256").update(publicKeyDer).digest("hex")}`;
+    if (parsed.key_id !== keyId) throw new Error("stored key ID mismatch");
+    return { privateKey, publicKeyDer, keyId };
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw new Error(`SQM signing identity is invalid: ${error.message}`);
+  }
+  const pair = generateKeyPairSync("ed25519");
+  const privateKeyDer = pair.privateKey.export({ format: "der", type: "pkcs8" });
+  const publicKeyDer = pair.publicKey.export({ format: "der", type: "spki" });
+  const keyId = `sha256:${createHash("sha256").update(publicKeyDer).digest("hex")}`;
+  await mkdir(path.dirname(location), { recursive: true, mode: 0o700 });
+  await writeFile(location, `${JSON.stringify({ algorithm: "ed25519", key_id: keyId, private_key: privateKeyDer.toString("base64"), public_key: publicKeyDer.toString("base64"), created_at: new Date().toISOString() }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  return { privateKey: pair.privateKey, publicKeyDer, keyId };
+}
+
+function taggedDigest(value) {
+  return `sha256:${createHash("sha256").update(canonicalize(value), "utf8").digest("hex")}`;
+}

package/src/sqm/repository.js

@@ -0,0 +1,163 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { normalizeGitHubRemote } from "../workspace-context.js";
+
+const execFileAsync = promisify(execFile);
+const MAX_UNTRACKED_FILE_BYTES = 1024 * 1024;
+const MAX_UNTRACKED_TOTAL_BYTES = 10 * 1024 * 1024;
+const MAX_UNTRACKED_FILES = 1_000;
+const MAX_UNTRACKED_LINES = 100_000;
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+
+export async function inspectRepository(cwd, { baseBranch = "dev", runCommand = execFileAsync } = {}) {
+  const root = await git(runCommand, ["rev-parse", "--show-toplevel"], cwd);
+  const remote = await git(runCommand, ["remote", "get-url", "origin"], root);
+  const repository = normalizeGitHubRemote(remote);
+  if (!repository) throw new Error("SQM requires a GitHub origin remote in owner/repository form.");
+  const baseRef = await resolveBaseRef(runCommand, root, baseBranch);
+  const baseCommit = await git(runCommand, ["merge-base", baseRef, "HEAD"], root);
+  const headCommit = await git(runCommand, ["rev-parse", "HEAD"], root);
+  const committed = await git(runCommand, ["diff", "--unified=0", "--no-color", `${baseRef}...HEAD`], root);
+  const working = await git(runCommand, ["diff", "--unified=0", "--no-color", "HEAD"], root);
+  const untracked = zeroSeparated(
+    await git(runCommand, ["ls-files", "-z", "--others", "--exclude-standard"], root),
+  );
+  const files = zeroSeparated(
+    await git(
+      runCommand,
+      ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+      root,
+    ),
+  );
+  const trackedDiff = parseUnifiedDiff(`${committed}\n${working}`);
+  const untrackedDiff = await untrackedAddedDiff(root, untracked);
+  const diff = [...trackedDiff, ...untrackedDiff];
+  const workingTreeDigest = digest({ working, untracked: untrackedDiff });
+  return {
+    root,
+    repository,
+    base_ref: baseRef,
+    base_commit: baseCommit,
+    head_commit: headCommit,
+    committed_diff_digest: digest(committed),
+    working_tree_digest: workingTreeDigest,
+    diff_digest: digest(diff),
+    diff,
+    paths: [...new Set(files)],
+  };
+}
+
+function digest(value) {
+  const encoded = typeof value === "string" ? value : JSON.stringify(value);
+  return `sha256:${createHash("sha256").update(encoded).digest("hex")}`;
+}
+
+async function untrackedAddedDiff(root, files) {
+  const result = [];
+  let totalBytes = 0;
+  for (const relative of files.slice(0, MAX_UNTRACKED_FILES)) {
+    const resolved = pathInsideRoot(root, relative);
+    if (!resolved) continue;
+    let fileStat;
+    try {
+      fileStat = await lstat(resolved);
+    } catch {
+      continue;
+    }
+    if (
+      !fileStat.isFile() ||
+      fileStat.isSymbolicLink() ||
+      fileStat.size > MAX_UNTRACKED_FILE_BYTES ||
+      totalBytes + fileStat.size > MAX_UNTRACKED_TOTAL_BYTES
+    ) {
+      continue;
+    }
+    let buffer;
+    let content;
+    try {
+      buffer = await readFile(resolved);
+      if (buffer.includes(0)) continue;
+      content = UTF8_DECODER.decode(buffer);
+    } catch {
+      continue;
+    }
+    const textLines = content.split(/\r?\n/);
+    if (textLines.length > MAX_UNTRACKED_LINES) continue;
+    if (textLines.at(-1) === "") textLines.pop();
+    totalBytes += buffer.length;
+    result.push({
+      path: relative,
+      lines: textLines.map((text, index) => ({ side: "added", line: index + 1, text })),
+    });
+  }
+  return result;
+}
+
+export function parseUnifiedDiff(raw) {
+  const files = new Map();
+  let current = null;
+  let oldPath = null;
+  let oldLine = 0;
+  let newLine = 0;
+  for (const line of String(raw || "").split(/\r?\n/)) {
+    if (line.startsWith("--- ")) {
+      const candidate = line.slice(4).replace(/^a\//, "");
+      oldPath = candidate === "/dev/null" ? null : candidate;
+      continue;
+    }
+    if (line.startsWith("+++ ")) {
+      const candidate = line.slice(4).replace(/^b\//, "");
+      current = candidate === "/dev/null" ? oldPath : candidate;
+      if (current && !files.has(current)) files.set(current, []);
+      continue;
+    }
+    const hunk = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hunk) {
+      oldLine = Number(hunk[1]);
+      newLine = Number(hunk[2]);
+      continue;
+    }
+    if (!current || line.startsWith("diff --git ")) continue;
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      files.get(current).push({ side: "added", line: newLine, text: line.slice(1) });
+      newLine += 1;
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      files.get(current).push({ side: "removed", line: oldLine, text: line.slice(1) });
+      oldLine += 1;
+    } else if (!line.startsWith("\\")) {
+      oldLine += 1;
+      newLine += 1;
+    }
+  }
+  return [...files.entries()].map(([path, lines]) => ({ path, lines }));
+}
+
+async function resolveBaseRef(runCommand, cwd, baseBranch) {
+  for (const ref of [`origin/${baseBranch}`, baseBranch]) {
+    try {
+      await git(runCommand, ["rev-parse", "--verify", ref], cwd);
+      return ref;
+    } catch {
+      // Try the local branch after origin/<branch>.
+    }
+  }
+  throw new Error(`SQM could not resolve base branch ${baseBranch}.`);
+}
+
+async function git(runCommand, args, cwd) {
+  const result = await runCommand("git", args, { cwd, maxBuffer: 10 * 1024 * 1024 });
+  return String(result?.stdout || "").trimEnd();
+}
+
+function zeroSeparated(value) {
+  return String(value || "").split("\0").filter(Boolean);
+}
+
+function pathInsideRoot(root, relative) {
+  const resolved = path.resolve(root, relative);
+  return resolved !== root && resolved.startsWith(`${root}${path.sep}`) ? resolved : null;
+}