kc-beta 0.3.2 → 0.5.3

package/src/agent/version-manager.js

@@ -1,130 +1,39 @@
-import fs from "node:fs";
-import path from "node:path";
+/**
+ * Trace ID utility.
+ *
+ * As of v0.4.0 (Block 11), real version history is kept by git
+ * (per-session repo, auto-committed by Workspace.autoCommit). This module
+ * is now just a stable place for trace ID generation, used by tools that
+ * need to cross-reference a write or a result with the event log.
+ *
+ * The legacy versions.json manifest in pre-v0.4.0 workspaces is left
+ * untouched — nothing reads it any more, but old data is preserved.
+ */
 
-const VERSIONED_DIRS = new Set(["workflows", "rule_skills", "rules"]);
-const VERSIONED_EXTS = new Set([".py", ".json", ".md", ".txt"]);
+/**
+ * Generate a trace ID like "20260417_114203_R001_workflow_result".
+ * @param {string} ruleId
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function generateTraceId(ruleId, label = "") {
+  const now = new Date().toISOString().replace(/[-:T]/g, (m) =>
+    m === "T" ? "_" : ""
+  ).slice(0, 15);
+  const suffix = label ? `_${label}` : "";
+  return `${now}_${ruleId}${suffix}`;
+}
 
 /**
- * Structural component: every write to versioned directories gets tracked.
- * - Immutable version copies tracked in manifest
- * - Manifest at versions.json: tracks lineage, timestamps, change reasons
- * - Trace ID generation: {timestamp}_{rule_id}_{version}
- * Cannot be bypassed — hooks into WorkspaceFileTool.
+ * Back-compat shell. The class is retained so existing constructors
+ * that take a VersionManager don't break, but it carries no state.
  */
 export class VersionManager {
-  /**
-   * @param {string} workspacePath
-   */
-  constructor(workspacePath) {
-    this._workspace = workspacePath;
-    this._manifestPath = path.join(workspacePath, "versions.json");
-    this._manifest = this._loadManifest();
-  }
-
-  _loadManifest() {
-    if (fs.existsSync(this._manifestPath)) {
-      try {
-        return JSON.parse(fs.readFileSync(this._manifestPath, "utf-8"));
-      } catch {
-        // fall through
-      }
-    }
-    return { version: "0.1.0", entries: [] };
-  }
-
-  _saveManifest() {
-    fs.writeFileSync(
-      this._manifestPath,
-      JSON.stringify(this._manifest, null, 2),
-      "utf-8",
-    );
-  }
-
-  /**
-   * Check if a path falls within versioned directories.
-   * @param {string} relPath
-   * @returns {boolean}
-   */
-  shouldVersion(relPath) {
-    const parts = relPath.split(path.sep);
-    if (parts.length === 0) return false;
-    const topDir = parts[0];
-    const ext = path.extname(relPath);
-    return VERSIONED_DIRS.has(topDir) && VERSIONED_EXTS.has(ext);
-  }
-
-  /**
-   * Called on file write. Returns trace ID if versioned, null otherwise.
-   * @param {string} relPath
-   * @param {string} content
-   * @returns {string|null}
-   */
-  onWrite(relPath, content) {
-    if (!this.shouldVersion(relPath)) return null;
-
-    const version = this._nextVersion(relPath);
-    const now = new Date().toISOString().replace(/[-:T]/g, (m) =>
-      m === "T" ? "_" : ""
-    ).slice(0, 15);
-
-    // Extract rule_id from path if possible (e.g., rule_skills/R001/SKILL.md → R001)
-    const parts = relPath.split(path.sep);
-    const ruleId = parts.length > 1 ? parts[1] : "global";
-
-    const traceId = `${now}_${ruleId}_v${version}`;
-
-    const entry = {
-      file: relPath,
-      version,
-      trace_id: traceId,
-      timestamp: new Date().toISOString(),
-      rule_id: ruleId,
-      size_chars: content.length,
-    };
-
-    this._manifest.entries.push(entry);
-    this._saveManifest();
-
-    return traceId;
-  }
-
-  _nextVersion(relPath) {
-    const existing = this._manifest.entries
-      .filter((e) => e.file === relPath)
-      .map((e) => e.version);
-    return Math.max(0, ...existing) + 1;
-  }
-
-  /**
-   * Get all version entries for a file.
-   * @param {string} relPath
-   * @returns {Array<object>}
-   */
-  getVersions(relPath) {
-    return this._manifest.entries.filter((e) => e.file === relPath);
-  }
-
-  /**
-   * Get the most recent version entry for a file.
-   * @param {string} relPath
-   * @returns {object|null}
-   */
-  latestVersion(relPath) {
-    const versions = this.getVersions(relPath);
-    return versions.length > 0 ? versions[versions.length - 1] : null;
+  constructor(_workspacePath) {
+    // No-op. Workspace path is no longer needed.
   }
 
-  /**
-   * Generate a standalone trace ID for results, QC records, etc.
-   * @param {string} ruleId
-   * @param {string} [label]
-   * @returns {string}
-   */
   generateTraceId(ruleId, label = "") {
-    const now = new Date().toISOString().replace(/[-:T]/g, (m) =>
-      m === "T" ? "_" : ""
-    ).slice(0, 15);
-    const suffix = label ? `_${label}` : "";
-    return `${now}_${ruleId}${suffix}`;
+    return generateTraceId(ruleId, label);
   }
 }

package/src/agent/workspace.js

@@ -1,24 +1,41 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { generateTraceId } from "./version-manager.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const GITIGNORE_TEMPLATE = path.resolve(__dirname, "../../template/workspace.gitignore");
 
 /**
  * Per-session workspace directory with path traversal protection.
  * Each agent session gets its own directory under the workspace root.
  * All file operations by tools must go through resolvePath().
+ *
+ * As of v0.4.0 (Block 11): the workspace is also a git repo. Writes to
+ * non-gitignored paths are auto-committed via autoCommit() so KC has a
+ * real version history of its outputs.
  */
 export class Workspace {
   /**
    * @param {string} root - Workspace root directory
    * @param {string} [sessionId] - Session identifier (auto-generated if omitted)
    * @param {string} [projectDir] - User's project directory (CWD at launch)
+   * @param {object} [opts]
+   * @param {boolean} [opts.gitAutoCommit=true] - If false, skip git init / auto-commit
    */
-  constructor(root, sessionId, projectDir) {
+  constructor(root, sessionId, projectDir, opts = {}) {
     this.root = path.resolve(root);
     this.sessionId = sessionId || crypto.randomUUID().replace(/-/g, "").slice(0, 12);
     this.path = path.resolve(this.root, this.sessionId);
     this.projectDir = projectDir ? path.resolve(projectDir) : null;
+    this._currentPhase = "bootstrap";
     fs.mkdirSync(this.path, { recursive: true });
+
+    this._gitAutoCommitEnabled = opts.gitAutoCommit !== false;
+    this._gitAvailable = this._gitAutoCommitEnabled && Workspace.isGitInstalled();
+    if (this._gitAvailable) this._initGitRepo();
   }
 
   /** @returns {string} Current workspace directory */
@@ -26,6 +43,16 @@ export class Workspace {
     return this.path;
   }
 
+  /** @returns {boolean} Whether auto-commit is wired up for this session */
+  get gitAvailable() {
+    return this._gitAvailable;
+  }
+
+  /** Update the current phase (used in auto-commit messages). */
+  setPhase(phase) {
+    if (phase) this._currentPhase = phase;
+  }
+
   /**
    * Resolve a user-supplied relative path against the workspace.
    * Rejects absolute paths and any path that escapes the workspace via .. or symlinks.
@@ -66,23 +93,62 @@ export class Workspace {
   }
 
   /**
-   * Rename the workspace folder. Returns the new sessionId.
+   * Auto-commit a workspace write. Silently no-ops if the path is gitignored,
+   * if there's nothing to commit, or if git isn't available. Returns the trace
+   * ID generated for this write (always returned, even if no commit happened,
+   * so callers can cross-reference with the event log).
+   *
+   * @param {string} relPath - workspace-relative path that was just written
+   * @param {string} [opLabel="update"] - short verb for the commit message
+   * @returns {string} trace id
+   */
+  autoCommit(relPath, opLabel = "update") {
+    const ruleId = this._extractRuleId(relPath);
+    const traceId = generateTraceId(ruleId, opLabel);
+
+    if (!this._gitAvailable) return traceId;
+
+    try {
+      const r = spawnSync("git", ["add", "--", relPath], {
+        cwd: this.path,
+        stdio: "ignore",
+      });
+      if (r.status !== 0) return traceId; // gitignored or other add error — skip commit
+      const msg = `[${this._currentPhase}] ${opLabel} ${relPath} [trace:${traceId}]`;
+      spawnSync("git", ["commit", "-m", msg, "--allow-empty-message"], {
+        cwd: this.path,
+        stdio: "ignore",
+      });
+      // Status doesn't matter — "nothing to commit" is fine.
+    } catch {
+      // Never let a git failure break a workspace write.
+    }
+    return traceId;
+  }
+
+  /**
+   * Rename the workspace folder. Returns `{ sessionId, oldCwd, newCwd }` so
+   * callers can cascade the new path to subsystems that captured cwd at
+   * construction (Bug 3).
    * @param {string} newName
-   * @returns {string}
+   * @returns {{sessionId: string, oldCwd: string, newCwd: string, changed: boolean}}
    */
   rename(newName) {
     newName = newName.trim().replace(/ /g, "_").replace(/\//g, "_");
     if (!newName) throw new Error("Name cannot be empty");
     const newPath = path.join(this.root, newName);
+    const oldCwd = this.path;
     if (fs.existsSync(newPath) && path.resolve(newPath) !== path.resolve(this.path)) {
       throw new Error(`Session '${newName}' already exists`);
     }
+    let changed = false;
     if (path.resolve(newPath) !== path.resolve(this.path)) {
       fs.renameSync(this.path, newPath);
       this.path = path.resolve(newPath);
       this.sessionId = newName;
+      changed = true;
     }
-    return this.sessionId;
+    return { sessionId: this.sessionId, oldCwd, newCwd: this.path, changed };
   }
 
   /**
@@ -102,4 +168,61 @@ export class Workspace {
     }
     return sessions;
   }
+
+  /** Probe whether the `git` executable is on PATH. Cached per process. */
+  static isGitInstalled() {
+    if (Workspace._gitProbeCache !== undefined) return Workspace._gitProbeCache;
+    try {
+      execFileSync("git", ["--version"], { stdio: "ignore" });
+      Workspace._gitProbeCache = true;
+    } catch {
+      Workspace._gitProbeCache = false;
+    }
+    return Workspace._gitProbeCache;
+  }
+
+  // --- private helpers ---
+
+  _initGitRepo() {
+    const gitDir = path.join(this.path, ".git");
+    const gitignorePath = path.join(this.path, ".gitignore");
+    const isFresh = !fs.existsSync(gitDir);
+
+    if (isFresh) {
+      try {
+        spawnSync("git", ["init", "--initial-branch=main"], { cwd: this.path, stdio: "ignore" });
+        // --initial-branch isn't supported on older git; fall back silently
+        if (!fs.existsSync(gitDir)) {
+          spawnSync("git", ["init"], { cwd: this.path, stdio: "ignore" });
+        }
+        // Local identity so commits don't depend on user's global config
+        spawnSync("git", ["config", "user.name", "kc-agent"], { cwd: this.path, stdio: "ignore" });
+        spawnSync("git", ["config", "user.email", "agent@kc.local"], { cwd: this.path, stdio: "ignore" });
+      } catch {
+        this._gitAvailable = false;
+        return;
+      }
+    }
+
+    // Always ensure .gitignore is present (template may have evolved)
+    if (!fs.existsSync(gitignorePath) && fs.existsSync(GITIGNORE_TEMPLATE)) {
+      fs.copyFileSync(GITIGNORE_TEMPLATE, gitignorePath);
+    }
+
+    if (isFresh) {
+      // Initial commit — captures whatever's already in the dir (for migrated workspaces)
+      spawnSync("git", ["add", "-A"], { cwd: this.path, stdio: "ignore" });
+      const msg = fs.existsSync(path.join(this.path, "AGENT.md"))
+        ? `Migrated session ${this.sessionId} to git-tracked workspace`
+        : `Initialized session ${this.sessionId}`;
+      spawnSync("git", ["commit", "--allow-empty", "-m", msg], { cwd: this.path, stdio: "ignore" });
+    }
+  }
+
+  /** Extract rule ID from a path like rule_skills/R001/SKILL.md → "R001". */
+  _extractRuleId(relPath) {
+    const parts = relPath.split(path.sep);
+    if (parts.length >= 2 && /^R\d+/i.test(parts[1])) return parts[1];
+    return "global";
+  }
 }

package/src/cli/components.js

@@ -88,7 +88,7 @@ export function TaskDashboard({ tasks, progress }) {
 
 // --- Welcome banner ---
 
-export function WelcomeBanner({ projectDir } = {}) {
+export function WelcomeBanner({ projectDir, pendingInputCount = 0 } = {}) {
   return h(Box, { flexDirection: "column", marginBottom: 1, borderStyle: "round", borderColor: "gray", paddingLeft: 1, paddingRight: 1 },
     h(Box, null,
       h(Text, { bold: true }, "KC AGENT CLI"),
@@ -102,6 +102,9 @@ export function WelcomeBanner({ projectDir } = {}) {
           h(Text, { color: "yellow", dimColor: true }, "KC has full read/write access to this directory. We recommend backing up important files."),
         )
       : null,
+    pendingInputCount > 0
+      ? h(Text, { color: "cyan" }, `📥 ${pendingInputCount} new file(s) pending in input/ — run /schedule for details`)
+      : null,
     h(Text, null, ""),
     h(Text, { dimColor: true }, "Product of Memium / kitchen-engineer42"),
   );

package/src/cli/index.js

@@ -5,6 +5,7 @@ import { LLMClient } from "../agent/llm-client.js";
 import { AgentEngine } from "../agent/engine.js";
 import { Workspace } from "../agent/workspace.js";
 import { ConversationHistory } from "../agent/history.js";
+import { Scheduler } from "../agent/scheduler.js";
 import {
   WelcomeBanner,
   StatusBar,
@@ -158,6 +159,7 @@ function App({ engine, config }) {
             "  /help                Show this help\n" +
             "  /status              Show session info, model, phase, workspace\n" +
             "  /tasks               Show task progress\n" +
+            "  /schedule            Show scheduled ingestion jobs and recent log lines\n" +
             "  /clear               Clear conversation history (keep workspace)\n" +
             "  /compact             Summarize older messages to reduce context\n" +
             "  /sessions            List all sessions\n" +
@@ -193,6 +195,30 @@ function App({ engine, config }) {
         });
         return true;
 
+      case "/schedule": {
+        const sched = new Scheduler(engineRef.current.workspace);
+        const jobs = sched.list();
+        if (jobs.length === 0) {
+          addMessage({ role: "system", content: "No scheduled ingestion jobs. Ask KC to set one up via the schedule_fetch tool." });
+        } else {
+          const lines = jobs.map((j) => {
+            const status = j.enabled ? "✓ enabled" : "· disabled";
+            const hint = j.cron_hint ? `   cron: ${j.cron_hint}` : "   cron: (not set)";
+            return `  ${status}  ${j.id}\n${hint}\n   cmd:  ${j.command}`;
+          });
+          const tail = sched.tailLog(8);
+          const pending = sched.pendingInputCount();
+          addMessage({
+            role: "system",
+            content:
+              `Scheduled jobs:\n${lines.join("\n\n")}\n\n` +
+              `Pending in input/: ${pending} file(s)` +
+              (tail ? `\n\nlogs/ingest.log (last 8):\n${tail}` : ""),
+          });
+        }
+        return true;
+      }
+
       case "/clear":
         engineRef.current.history = new ConversationHistory(engineRef.current.workspace.cwd);
         setMessages([]);
@@ -227,9 +253,22 @@ function App({ engine, config }) {
           addMessage({ role: "system", content: "Usage: /rename <new_name>" });
         } else {
           try {
-            const newId = engineRef.current.workspace.rename(arg);
-            setSessionId(newId);
-            addMessage({ role: "system", content: `Session renamed to: ${newId}` });
+            const r = engineRef.current.renameSession(arg);
+            setSessionId(r.sessionId);
+            const lines = [`Session renamed to: ${r.sessionId}`];
+            if (r.scheduleWrappersRegenerated.length > 0) {
+              lines.push(
+                `${r.scheduleWrappersRegenerated.length} cron wrapper script(s) regenerated.`,
+                `If you'd installed crontab lines for the OLD path, re-install via 'schedule_fetch print_crontab'.`,
+              );
+            }
+            if (r.scheduleWrappersFailed && r.scheduleWrappersFailed.length > 0) {
+              const ids = r.scheduleWrappersFailed.map((f) => f.id).join(", ");
+              lines.push(
+                `⚠ ${r.scheduleWrappersFailed.length} wrapper script(s) failed to regenerate (${ids}). Check workspace/scripts/ingest/ and disk space.`,
+              );
+            }
+            addMessage({ role: "system", content: lines.join("\n") });
           } catch (err) {
             addMessage({ role: "system", content: `Rename failed: ${err.message}` });
           }
@@ -342,7 +381,13 @@ function App({ engine, config }) {
 
   return h(Box, { flexDirection: "column" },
     // Welcome banner
-    showWelcome ? h(WelcomeBanner, { projectDir: config.projectDir }) : null,
+    showWelcome ? h(WelcomeBanner, {
+      projectDir: config.projectDir,
+      pendingInputCount: (() => {
+        try { return new Scheduler(engineRef.current.workspace).pendingInputCount(); }
+        catch { return 0; }
+      })(),
+    }) : null,
 
     // Task dashboard (ralph-loop)
     taskList.length > 0 ? h(TaskDashboard, { tasks: taskList, progress: taskProgress }) : null,
@@ -436,6 +481,14 @@ export async function main({ languageOverride } = {}) {
     console.log(`\x1b[33m${msg}\x1b[0m\n`);
   }
 
+  // Warn if git is missing — Block 11 file system relies on git for version history.
+  if (config.gitAutoCommit !== false && !Workspace.isGitInstalled()) {
+    const msg = config.language === "zh"
+      ? "  ⚠ 未检测到 git。本会话将不记录版本历史。安装 git 以启用自动提交。"
+      : "  ⚠ git not found — version history disabled this session. Install git to enable auto-commit.";
+    console.log(`\x1b[33m${msg}\x1b[0m\n`);
+  }
+
   const client = new LLMClient({
     apiKey: config.llmApiKey,
     baseUrl: config.llmBaseUrl,

package/src/config.js

@@ -65,7 +65,7 @@ export function loadSettings(workspacePath) {
     llmApiKey: env.LLM_API_KEY || env.SILICONFLOW_API_KEY || gc.api_key || "",
     llmBaseUrl: env.LLM_BASE_URL || env.SILICONFLOW_BASE_URL || gc.base_url || "https://api.siliconflow.cn/v1",
     kcModel: gc.conductor_model || "glm-5",
-    kcMaxTokens: 65536,
+    kcMaxTokens: parseInt(env.KC_MAX_TOKENS || gc.kc_max_tokens?.toString() || "65536", 10),
 
     // Tier models (from .env or global config tiers)
     tier1: env.TIER1 || gc.tiers?.tier1 || "",
@@ -111,6 +111,15 @@ export function loadSettings(workspacePath) {
 
     // Context management
     kcContextLimit: parseInt(env.KC_CONTEXT_LIMIT || "200000", 10),
+    toolOutputOffloadTokens: parseInt(env.TOOL_OUTPUT_OFFLOAD_TOKENS || gc.tool_output_offload_tokens?.toString() || "2000", 10),
+    toolOutputOffloadErrorTokens: parseInt(env.TOOL_OUTPUT_OFFLOAD_ERROR_TOKENS || gc.tool_output_offload_error_tokens?.toString() || "500", 10),
+    maxMessageTokens: parseInt(env.MAX_MESSAGE_TOKENS || gc.max_message_tokens?.toString() || "60000", 10),
+
+    // File system (Block 11)
+    gitAutoCommit: (env.GIT_AUTO_COMMIT ?? gc.git_auto_commit ?? true) !== false &&
+                   (env.GIT_AUTO_COMMIT !== "false") &&
+                   (gc.git_auto_commit !== false),
+    largeRefThresholdMB: parseInt(env.LARGE_REF_THRESHOLD_MB || gc.large_ref_threshold_mb?.toString() || "10", 10),
 
     // Language
     language: env.LANGUAGE || gc.language || "en",

package/template/release-runtime/README.md.tmpl

@@ -0,0 +1,84 @@
+# {LABEL} — KC Verification Release
+
+Generated: {CREATED_AT}
+Snapshot tag: `{SNAPSHOT_TAG}`
+Commit: `{SNAPSHOT_COMMIT}`
+Built by: kc-beta {KC_VERSION}
+
+{NOTES_BLOCK}
+
+This bundle is self-contained. It runs without `kc-beta` installed — only Python 3 and a worker LLM API key are required.
+
+## What's in here
+
+```
+manifest.json              — release metadata (rules, models, snapshot tag)
+README.md                  — this file
+run.py                     — standalone driver, runs all rules
+render_dashboard.py        — re-render an HTML dashboard from a result JSON
+serve.sh                   — optional helper, serves this dir over local HTTP
+kc_runtime/                — bundled Python helpers (confidence scoring, dashboard)
+workflows/                 — pinned per-rule Python workflows + prompts
+fixtures/                  — sample inputs (if KC selected any)
+glossary.json              — project entity vocabulary at release time
+catalog.json               — rule catalog at release time
+corner_cases.json          — known corner cases (used by confidence scoring)
+confidence_calibration.json — per-rule historical accuracy
+models.json                — worker LLM tier→model assignments
+```
+
+## Run a verification
+
+```sh
+export LLM_API_KEY="sk-..."
+export LLM_BASE_URL="https://api.siliconflow.cn/v1"   # or your provider
+export TIER1="..."                                     # comma-separated model list
+export TIER2="..."
+
+python run.py /path/to/document.pdf > result.json
+```
+
+Each rule's workflow runs against the document; results are aggregated into a single JSON.
+
+### Useful flags
+
+```sh
+python run.py doc.pdf --rule R001              # run only one rule
+python run.py doc.pdf --output result.json     # write to a file
+python run.py doc.pdf --dashboard              # also emit an HTML dashboard
+```
+
+### Re-render a dashboard
+
+```sh
+python render_dashboard.py result.json
+# → result.html alongside the JSON
+```
+
+### Browse dashboards in a browser
+
+```sh
+./serve.sh
+# → http://localhost:8080/result.html
+```
+
+## Rules in this release
+
+{RULES_LIST}
+
+## Reproducibility
+
+The release bundle is regenerable from the snapshot tag:
+
+```sh
+git checkout {SNAPSHOT_TAG}
+# then run kc-beta and ask it to release({label: "{LABEL}"}) again
+```
+
+The `manifest.json` records the exact commit (`{SNAPSHOT_COMMIT}`) so you can verify what's running.
+
+## Caveats
+
+- Workflows call worker LLMs. Costs depend on your provider; the bundle does not enforce a budget.
+- Workflow output for each rule is preserved in `result.raw[*]` for audit. If you need full audit history with KC's event log + corner-case registry, work from the source workspace, not this bundle.
+- Bundle does not sandbox `python`. Treat it like any executable you trust.

package/template/release-runtime/kc_runtime/__init__.py

@@ -0,0 +1,2 @@
+# KC release-runtime support package.
+# Bundled into every release. Self-contained, no external dependencies.

package/template/release-runtime/kc_runtime/confidence.py

@@ -0,0 +1,93 @@
+"""
+Confidence scorer — Python port of src/agent/confidence-scorer.js.
+
+Composite formula: confidence = method_prior * source_presence
+                                * historical_accuracy * (1 - corner_proximity)
+
+Identical to the JS scorer used inside KC, so release runs produce the same
+confidence values KC produces in-workspace.
+
+Note on rounding: JS Math.round() is half-up, Python's round() is half-to-even
+(banker's rounding). We use a half-up implementation here to match JS exactly.
+"""
+
+import math
+
+
+def _round3_halfup(x):
+    """Round x to 3 decimals, half-up (matches JS Math.round)."""
+    return math.floor(x * 1000 + 0.5) / 1000
+
+
+DEFAULT_PRIORS = {
+    "regex": 0.95,
+    "python": 0.90,
+    "llm": 0.75,
+    "ocr": 0.65,
+    "fallback": 0.50,
+}
+
+
+def score(rule_id, extracted_value, source_text="", method="llm",
+          document="", priors=None, historical=None, corner_cases=None):
+    """
+    Compute composite confidence score (0.0 - 1.0).
+
+    rule_id: rule identifier
+    extracted_value: the value the workflow extracted (string)
+    source_text: optional surrounding text from the document
+    method: "regex" | "python" | "llm" | "ocr" | "fallback"
+    document: document name / path (used for corner-case proximity)
+    priors: dict overriding DEFAULT_PRIORS
+    historical: dict of {rule_id: accuracy} from confidence_calibration.json
+    corner_cases: list/dict from corner_cases.json registry
+    """
+    p = priors or DEFAULT_PRIORS
+    method_prior = p.get(method, p.get("fallback", 0.50))
+
+    source_presence = 1.0
+    if source_text and extracted_value:
+        source_presence = 1.0 if str(extracted_value) in source_text else 0.7
+
+    hist = (historical or {}).get(rule_id, 0.8)
+
+    corner_proximity = _corner_proximity(corner_cases, document, rule_id)
+
+    confidence = method_prior * source_presence * hist * (1.0 - corner_proximity)
+    confidence = max(0.0, min(1.0, confidence))
+    return _round3_halfup(confidence)
+
+
+def band(confidence):
+    """Classify confidence into low/medium/high band — matches JS getBand()."""
+    if confidence >= 0.8:
+        return "high"
+    if confidence >= 0.5:
+        return "medium"
+    return "low"
+
+
+def _corner_proximity(corner_cases, document, rule_id):
+    """Mirror CornerCaseRegistry.match: count entries matching this doc + rule.
+    Each match adds 0.1 (capped at 0.3). Schema is intentionally loose — KC's
+    JS registry stores entries with optional `document_pattern` and `rule_id`
+    fields; we replicate the same matching semantics here.
+    """
+    if not corner_cases or not document:
+        return 0.0
+    entries = corner_cases if isinstance(corner_cases, list) else corner_cases.get("entries", [])
+    if not entries:
+        return 0.0
+
+    matches = 0
+    for e in entries:
+        if not isinstance(e, dict):
+            continue
+        if e.get("rule_id") and e.get("rule_id") != rule_id:
+            continue
+        pattern = e.get("document_pattern") or e.get("document") or ""
+        if pattern and pattern not in document:
+            continue
+        matches += 1
+
+    return min(0.3, 0.1 * matches)