superlab 0.1.11 → 0.1.13

package/lib/auto_common.cjs

@@ -0,0 +1,129 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PLACEHOLDER_VALUES = new Set(["", "tbd", "none", "待补充", "无"]);
+
+function contextFile(targetDir, name) {
+  return path.join(targetDir, ".lab", "context", name);
+}
+
+function readFileIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return "";
+  }
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function extractValue(text, labels) {
+  for (const label of labels) {
+    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^\\s*-\\s*${escaped}:[ \\t]*([^\\n\\r]+?)[ \\t]*$`, "im");
+    const match = text.match(regex);
+    if (match && match[1]) {
+      return match[1].trim();
+    }
+  }
+  return "";
+}
+
+function isMeaningful(value) {
+  return !PLACEHOLDER_VALUES.has((value || "").trim().toLowerCase());
+}
+
+function normalizeAllowedStages(rawValue) {
+  return (rawValue || "")
+    .split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function normalizeScalar(value) {
+  return (value || "").trim().toLowerCase();
+}
+
+function parseInteger(value, fallback = null) {
+  const normalized = (value || "").trim();
+  if (!normalized) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function parseDurationMs(value, fallbackMs) {
+  const normalized = (value || "").trim().toLowerCase();
+  if (!normalized) {
+    return fallbackMs;
+  }
+  const match = normalized.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (!match) {
+    return fallbackMs;
+  }
+  const amount = Number.parseFloat(match[1]);
+  const unit = match[2] || "s";
+  const multipliers = {
+    ms: 1,
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+  };
+  return Math.max(1, Math.round(amount * multipliers[unit]));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeList(rawValue) {
+  return (rawValue || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function readWorkflowLanguage(targetDir) {
+  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
+  if (!fs.existsSync(configPath)) {
+    return "en";
+  }
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return config.workflow_language === "zh" ? "zh" : "en";
+  } catch {
+    return "en";
+  }
+}
+
+function readWorkflowConfig(targetDir) {
+  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function resolveProjectPath(targetDir, configuredPath, fallbackRelativePath) {
+  if (typeof configuredPath !== "string" || configuredPath.trim() === "") {
+    return path.join(targetDir, fallbackRelativePath);
+  }
+  return path.isAbsolute(configuredPath)
+    ? configuredPath
+    : path.resolve(targetDir, configuredPath);
+}
+
+module.exports = {
+  contextFile,
+  extractValue,
+  isMeaningful,
+  normalizeAllowedStages,
+  normalizeList,
+  normalizeScalar,
+  parseDurationMs,
+  parseInteger,
+  readFileIfExists,
+  readWorkflowConfig,
+  readWorkflowLanguage,
+  resolveProjectPath,
+  sleep,
+};

package/lib/auto_contracts.cjs

@@ -0,0 +1,387 @@
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const path = require("node:path");
+const {
+  contextFile,
+  extractValue,
+  isMeaningful,
+  normalizeList,
+  parseInteger,
+  readFileIfExists,
+  readWorkflowConfig,
+  resolveProjectPath,
+} = require("./auto_common.cjs");
+
+const ALLOWED_AUTO_STAGES = new Set(["run", "iterate", "review", "report", "write"]);
+const LOOP_AUTO_STAGES = new Set(["run", "iterate", "review"]);
+const FINAL_AUTO_STAGES = new Set(["report", "write"]);
+const AUTO_LEVEL_STAGE_ENVELOPES = {
+  l1: new Set(["run", "review", "report"]),
+  l2: new Set(["run", "iterate", "review", "report"]),
+  l3: new Set(["run", "iterate", "review", "report", "write"]),
+};
+const VALID_APPROVAL_STATUSES = new Set(["draft", "approved"]);
+const VALID_TERMINAL_GOAL_TYPES = new Set(["rounds", "metric-threshold", "task-completion"]);
+const FROZEN_CORE_ALIASES = {
+  mission: [path.join(".lab", "context", "mission.md")],
+  framing: [
+    path.join(".lab", "context", "terminology-lock.md"),
+    path.join(".lab", "writing", "framing.md"),
+  ],
+  claims: [path.join(".lab", "context", "terminology-lock.md")],
+  "terminology-lock": [path.join(".lab", "context", "terminology-lock.md")],
+};
+const REVIEW_CONTEXT_FILES = [
+  path.join(".lab", "context", "decisions.md"),
+  path.join(".lab", "context", "state.md"),
+  path.join(".lab", "context", "open-questions.md"),
+  path.join(".lab", "context", "evidence-index.md"),
+];
+const PROMOTION_CANONICAL_FILES = [
+  path.join(".lab", "context", "data-decisions.md"),
+  path.join(".lab", "context", "decisions.md"),
+  path.join(".lab", "context", "state.md"),
+  path.join(".lab", "context", "session-brief.md"),
+];
+
+function resolveFrozenCoreEntries(rawValue) {
+  const normalized = normalizeList(rawValue);
+  const paths = new Set();
+  const invalidEntries = [];
+
+  for (const entry of normalized) {
+    const key = entry.trim().toLowerCase();
+    if (FROZEN_CORE_ALIASES[key]) {
+      for (const aliasedPath of FROZEN_CORE_ALIASES[key]) {
+        paths.add(aliasedPath);
+      }
+      continue;
+    }
+
+    if (entry.includes("/") || entry.includes(path.sep) || entry.endsWith(".md")) {
+      paths.add(entry);
+      continue;
+    }
+
+    invalidEntries.push(entry);
+  }
+
+  return {
+    entries: normalized,
+    relativePaths: Array.from(paths),
+    invalidEntries,
+  };
+}
+
+function hashPathState(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return "__missing__";
+  }
+
+  const stat = fs.statSync(filePath);
+  if (stat.isDirectory()) {
+    const entries = fs.readdirSync(filePath)
+      .sort((left, right) => left.localeCompare(right))
+      .map((entry) => {
+        const childPath = path.join(filePath, entry);
+        return `${entry}:${hashPathState(childPath)}`;
+      })
+      .join("|");
+    return crypto.createHash("sha256").update(entries).digest("hex");
+  }
+
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function snapshotFrozenCore(targetDir, rawValue) {
+  const { relativePaths } = resolveFrozenCoreEntries(rawValue);
+  const snapshot = new Map();
+
+  for (const relativePath of relativePaths) {
+    const absolutePath = path.resolve(targetDir, relativePath);
+    snapshot.set(absolutePath, hashPathState(absolutePath));
+  }
+
+  return snapshot;
+}
+
+function detectFrozenCoreChanges(snapshot) {
+  const changedPaths = [];
+  for (const [absolutePath, initialHash] of snapshot.entries()) {
+    const currentHash = hashPathState(absolutePath);
+    if (currentHash !== initialHash) {
+      changedPaths.push(absolutePath);
+    }
+  }
+  return changedPaths;
+}
+
+function validateAutoMode(mode, status = null, evalProtocol = null) {
+  const issues = [];
+  const activated =
+    isMeaningful(mode.objective) ||
+    (status && ["running", "stopped", "failed", "completed"].includes((status.status || "").toLowerCase()));
+
+  if (!activated) {
+    return issues;
+  }
+
+  const requiredFields = [
+    ["objective", mode.objective],
+    ["autonomy level", mode.autonomyLevel],
+    ["approval status", mode.approvalStatus],
+    ["allowed stages", mode.allowedStages.join(", ")],
+    ["success criteria", mode.successCriteria],
+    ["terminal goal type", mode.terminalGoalType],
+    ["terminal goal target", mode.terminalGoalTarget],
+    ["required terminal artifact", mode.requiredTerminalArtifact],
+    ["max iterations", mode.maxIterations],
+    ["max wall-clock time", mode.maxWallClockTime],
+    ["max failures", mode.maxFailures],
+    ["poll interval", mode.pollInterval],
+    ["stop check command", mode.stopCheckCommand],
+    ["promotion policy", mode.promotionPolicy],
+    ["promotion check command", mode.promotionCheckCommand],
+    ["promotion command", mode.promotionCommand],
+    ["frozen core", mode.frozenCore],
+    ["exploration envelope", mode.explorationEnvelope],
+    ["stop conditions", mode.stopConditions],
+  ];
+
+  const missing = requiredFields
+    .filter(([, value]) => !isMeaningful(value))
+    .map(([name]) => name);
+  if (missing.length > 0) {
+    issues.push(`missing auto mode fields: ${missing.join(", ")}`);
+  }
+
+  const invalidStages = mode.allowedStages.filter((stage) => !ALLOWED_AUTO_STAGES.has(stage));
+  if (invalidStages.length > 0) {
+    issues.push(`unsupported auto stages: ${invalidStages.join(", ")}`);
+  }
+
+  if (isMeaningful(mode.autonomyLevel) && !AUTO_LEVEL_STAGE_ENVELOPES[mode.autonomyLevel]) {
+    issues.push(`invalid autonomy level: ${mode.autonomyLevel}`);
+  }
+
+  if (isMeaningful(mode.approvalStatus) && !VALID_APPROVAL_STATUSES.has(mode.approvalStatus)) {
+    issues.push(`invalid approval status: ${mode.approvalStatus}`);
+  }
+
+  if (isMeaningful(mode.terminalGoalType) && !VALID_TERMINAL_GOAL_TYPES.has(mode.terminalGoalType)) {
+    issues.push(`invalid terminal goal type: ${mode.terminalGoalType}`);
+  }
+
+  const allowedEnvelope = AUTO_LEVEL_STAGE_ENVELOPES[mode.autonomyLevel];
+  if (allowedEnvelope) {
+    const outOfEnvelopeStages = mode.allowedStages.filter((stage) => !allowedEnvelope.has(stage));
+    if (outOfEnvelopeStages.length > 0) {
+      issues.push(
+        `autonomy level ${mode.autonomyLevel} does not allow stages: ${outOfEnvelopeStages.join(", ")}`
+      );
+    }
+  }
+
+  const ladderStageCoverage = new Map();
+  if (evalProtocol && Array.isArray(evalProtocol.experimentRungs)) {
+    for (const rung of evalProtocol.experimentRungs) {
+      const hasExplicitCommand = isMeaningful(rung.command);
+      ladderStageCoverage.set(rung.stage, (ladderStageCoverage.get(rung.stage) || false) || hasExplicitCommand);
+    }
+  }
+
+  const missingCommands = mode.allowedStages.filter(
+    (stage) => !isMeaningful(mode.stageCommands?.[stage]) && !ladderStageCoverage.get(stage)
+  );
+  if (missingCommands.length > 0) {
+    issues.push(`missing auto commands for stages: ${missingCommands.join(", ")}`);
+  }
+
+  if (mode.terminalGoalType === "metric-threshold" && !isMeaningful(mode.successCheckCommand)) {
+    issues.push("missing auto mode fields: success check command");
+  }
+
+  if (mode.terminalGoalType === "rounds") {
+    const roundsTarget = parseInteger(mode.terminalGoalTarget, null);
+    if (!Number.isInteger(roundsTarget) || roundsTarget <= 0) {
+      issues.push(`terminal goal target must be a positive integer for rounds: ${mode.terminalGoalTarget}`);
+    }
+  }
+
+  const invalidFrozenCoreEntries = resolveFrozenCoreEntries(mode.frozenCore).invalidEntries;
+  if (invalidFrozenCoreEntries.length > 0) {
+    issues.push(`unsupported frozen core entries: ${invalidFrozenCoreEntries.join(", ")}`);
+  }
+
+  return issues;
+}
+
+function validateAutoStatus(status, mode = null) {
+  const issues = [];
+  const normalizedStatus = (status.status || "").trim().toLowerCase();
+  if (!normalizedStatus || normalizedStatus === "idle") {
+    return issues;
+  }
+
+  if (!["running", "stopped", "failed", "completed"].includes(normalizedStatus)) {
+    issues.push(`invalid auto status: ${status.status}`);
+    return issues;
+  }
+
+  if (normalizedStatus === "running") {
+    if (!isMeaningful(status.currentStage)) {
+      issues.push("auto status is missing current stage");
+    }
+    if (!isMeaningful(status.startedAt)) {
+      issues.push("auto status is missing started at");
+    }
+    if (!isMeaningful(status.lastHeartbeat)) {
+      issues.push("auto status is missing last heartbeat");
+    }
+  }
+
+  if (mode && mode.allowedStages.length > 0 && isMeaningful(status.currentStage)) {
+    const currentStage = status.currentStage.trim().toLowerCase();
+    if (!mode.allowedStages.includes(currentStage)) {
+      issues.push(`auto status stage is outside allowed stages: ${status.currentStage}`);
+    }
+  }
+
+  if (
+    mode &&
+    ["running", "completed"].includes(normalizedStatus) &&
+    mode.approvalStatus !== "approved"
+  ) {
+    issues.push(`auto mode must be approved before it can be ${normalizedStatus}`);
+  }
+
+  return issues;
+}
+
+function snapshotPaths(targetDir, relativePaths) {
+  const snapshot = new Map();
+  for (const relativePath of relativePaths) {
+    const absolutePath = path.resolve(targetDir, relativePath);
+    snapshot.set(absolutePath, hashPathState(absolutePath));
+  }
+  return snapshot;
+}
+
+function changedSnapshotPaths(snapshot) {
+  const changed = [];
+  for (const [absolutePath, previousHash] of snapshot.entries()) {
+    if (hashPathState(absolutePath) !== previousHash) {
+      changed.push(absolutePath);
+    }
+  }
+  return changed;
+}
+
+function stageContractSnapshot(targetDir, stage) {
+  const workflowConfig = readWorkflowConfig(targetDir);
+  const resultsRoot = resolveProjectPath(targetDir, workflowConfig.results_root, "results");
+  const deliverablesRoot = resolveProjectPath(targetDir, workflowConfig.deliverables_root, path.join("docs", "research"));
+  const trackedPathsByStage = {
+    run: [resultsRoot],
+    iterate: [resultsRoot],
+    review: REVIEW_CONTEXT_FILES.map((relativePath) => path.resolve(targetDir, relativePath)),
+    report: [path.join(deliverablesRoot, "report.md")],
+    write: [
+      path.join(deliverablesRoot, "paper", "main.tex"),
+      path.join(deliverablesRoot, "paper", "sections"),
+    ],
+  };
+
+  const absolutePaths = trackedPathsByStage[stage] || [];
+  const snapshot = new Map();
+  for (const absolutePath of absolutePaths) {
+    snapshot.set(absolutePath, hashPathState(absolutePath));
+  }
+  return {
+    stage,
+    absolutePaths,
+    snapshot,
+  };
+}
+
+function verifyStageContract({ stage, snapshot }) {
+  const changedPaths = [];
+  for (const [absolutePath, previousHash] of snapshot.entries()) {
+    if (hashPathState(absolutePath) !== previousHash) {
+      changedPaths.push(absolutePath);
+    }
+  }
+
+  if (stage === "review") {
+    if (changedPaths.length === 0) {
+      throw new Error(
+        "review stage did not update canonical review context (.lab/context/decisions.md, state.md, open-questions.md, or evidence-index.md)"
+      );
+    }
+    return;
+  }
+
+  if (stage === "report") {
+    if (changedPaths.length === 0) {
+      throw new Error("report stage did not produce the deliverable report.md under deliverables_root");
+    }
+    return;
+  }
+
+  if (stage === "write") {
+    if (changedPaths.length === 0) {
+      throw new Error("write stage did not produce LaTeX output under deliverables_root/paper");
+    }
+    return;
+  }
+
+  if ((stage === "run" || stage === "iterate") && changedPaths.length === 0) {
+    throw new Error(`${stage} stage did not produce persistent outputs under results_root`);
+  }
+}
+
+function verifyPromotionWriteback(targetDir, snapshot) {
+  const changedPaths = changedSnapshotPaths(snapshot);
+  if (changedPaths.length !== PROMOTION_CANONICAL_FILES.length) {
+    throw new Error(
+      `promotion did not update canonical context: ${PROMOTION_CANONICAL_FILES.filter(
+        (relativePath) => !changedPaths.includes(path.resolve(targetDir, relativePath))
+      ).join(", ")}`
+    );
+  }
+}
+
+function splitAutoStages(allowedStages) {
+  const loopStages = allowedStages.filter((stage) => LOOP_AUTO_STAGES.has(stage));
+  const finalStages = allowedStages.filter((stage) => FINAL_AUTO_STAGES.has(stage));
+  return { loopStages, finalStages };
+}
+
+function resolveStageCommand(mode, stage, commandOverride = "") {
+  return isMeaningful(commandOverride) ? commandOverride : mode.stageCommands[stage];
+}
+
+module.exports = {
+  ALLOWED_AUTO_STAGES,
+  AUTO_LEVEL_STAGE_ENVELOPES,
+  FINAL_AUTO_STAGES,
+  FROZEN_CORE_ALIASES,
+  LOOP_AUTO_STAGES,
+  PROMOTION_CANONICAL_FILES,
+  REVIEW_CONTEXT_FILES,
+  VALID_APPROVAL_STATUSES,
+  VALID_TERMINAL_GOAL_TYPES,
+  changedSnapshotPaths,
+  detectFrozenCoreChanges,
+  hashPathState,
+  resolveFrozenCoreEntries,
+  resolveStageCommand,
+  snapshotFrozenCore,
+  snapshotPaths,
+  splitAutoStages,
+  stageContractSnapshot,
+  validateAutoMode,
+  validateAutoStatus,
+  verifyPromotionWriteback,
+  verifyStageContract,
+};