chainlesschain 0.162.162 → 0.162.164

package/src/lib/hook-stats-store.cjs

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * hook-stats-store — a small, best-effort, cross-session RELIABILITY aggregate
+ * for async settings hooks, so `cc doctor` (a separate process) can surface
+ * hooks that have been slow, repeatedly failing, or circuit-broken. The gap's
+ * P2 "Doctor" wants "慢/熔断 Hook" health, but that state otherwise lives only
+ * in-memory in AsyncHookSupervisor for the life of one process.
+ *
+ * Design: the supervisor folds each completed hook run into an in-memory
+ * aggregate (bounded by the number of DISTINCT hooks, not runs) and persists it
+ * once on stopAll() — NOT per run — so there is no write amplification on the
+ * hook hot path. Persistence merges with whatever is already on disk, so counts
+ * accumulate across sessions. Reads/writes are best-effort (a corrupt/ío-failed
+ * file never blocks a hook or the agent).
+ *
+ * Pure aggregation (no clock/RNG/fs in the fold) so it's fully unit-testable;
+ * load/save take an injected fs. The default circuit threshold mirrors the
+ * doctor evaluator's `hookFailureThreshold`.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const fsDefault = require("node:fs");
+
+const MAX_HOOKS = 200; // bound distinct-hook entries; drop least-recently-run
+const DEFAULT_CIRCUIT_THRESHOLD = 3;
+const CONFIG_DIR_NAME = ".chainlesschain";
+
+/** Stable per-hook id from its (event, command). */
+function hookKey(command, event) {
+  return `${event || "*"}::${String(command || "").trim()}`;
+}
+
+/** Default on-disk location (matches the ESM getHomeDir() layout). */
+function defaultHookStatsPath() {
+  return path.join(os.homedir(), CONFIG_DIR_NAME, "hook-stats.json");
+}
+
+/** Fresh empty aggregate map. */
+function emptyStats() {
+  return {};
+}
+
+/**
+ * Fold ONE completed run into the aggregate (mutates + returns `stats`). Pure:
+ * `now`/`ok`/`ms` are supplied by the caller. `consecutiveFailures` resets on
+ * any success — the circuit signal is "N failures in a row", not lifetime.
+ */
+function aggregateRun(stats, { command, event, ok, ms, now }) {
+  if (!stats || typeof stats !== "object") stats = {};
+  const id = hookKey(command, event);
+  const dur = Number.isFinite(Number(ms)) ? Number(ms) : 0;
+  const at = Number.isFinite(Number(now)) ? Number(now) : 0;
+  const e = stats[id] || {
+    id,
+    command: command || "",
+    event: event || null,
+    runs: 0,
+    failures: 0,
+    consecutiveFailures: 0,
+    lastFailureAt: null,
+    totalMs: 0,
+    maxMs: 0,
+    lastRunAt: 0,
+  };
+  e.runs += 1;
+  e.totalMs += dur;
+  if (dur > e.maxMs) e.maxMs = dur;
+  if (at > e.lastRunAt) e.lastRunAt = at;
+  if (ok === true) {
+    e.consecutiveFailures = 0;
+  } else {
+    e.failures += 1;
+    e.consecutiveFailures += 1;
+    e.lastFailureAt = at;
+  }
+  stats[id] = e;
+  boundStats(stats);
+  return stats;
+}
+
+/** Keep only the MAX_HOOKS most-recently-run entries. */
+function boundStats(stats) {
+  const keys = Object.keys(stats);
+  if (keys.length <= MAX_HOOKS) return stats;
+  keys
+    .sort((a, b) => (stats[a].lastRunAt || 0) - (stats[b].lastRunAt || 0))
+    .slice(0, keys.length - MAX_HOOKS)
+    .forEach((k) => delete stats[k]);
+  return stats;
+}
+
+/**
+ * Merge a session `delta` aggregate INTO a `base` aggregate (returns a new map).
+ * Counts add; maxMs/lastRunAt/lastFailureAt take the larger; the session's
+ * consecutiveFailures wins (it reflects the most recent streak).
+ */
+function mergeStats(base, delta) {
+  const out = {};
+  for (const src of [base, delta]) {
+    if (!src || typeof src !== "object") continue;
+    for (const [id, e] of Object.entries(src)) {
+      if (!e || typeof e !== "object") continue;
+      const cur = out[id];
+      if (!cur) {
+        out[id] = { ...e };
+        continue;
+      }
+      cur.runs += e.runs || 0;
+      cur.failures += e.failures || 0;
+      cur.totalMs += e.totalMs || 0;
+      cur.maxMs = Math.max(cur.maxMs || 0, e.maxMs || 0);
+      cur.lastRunAt = Math.max(cur.lastRunAt || 0, e.lastRunAt || 0);
+      cur.lastFailureAt =
+        Math.max(cur.lastFailureAt || 0, e.lastFailureAt || 0) || null;
+      // `delta` is applied second, so its streak (most recent) wins.
+      cur.consecutiveFailures =
+        e.consecutiveFailures ?? cur.consecutiveFailures;
+      cur.command = e.command || cur.command;
+      cur.event = e.event ?? cur.event;
+    }
+  }
+  return boundStats(out);
+}
+
+/**
+ * Shape the aggregate for the doctor `checkHooks` evaluator: id, lifetime
+ * failure count, average duration, and a derived circuit-open flag.
+ */
+function toCheckHooksInput(
+  stats,
+  { circuitThreshold = DEFAULT_CIRCUIT_THRESHOLD } = {},
+) {
+  if (!stats || typeof stats !== "object") return [];
+  return Object.values(stats).map((e) => ({
+    id: e.command || e.id,
+    event: e.event || null,
+    failures: e.failures || 0,
+    avgMs: e.runs > 0 ? e.totalMs / e.runs : 0,
+    circuitOpen: (e.consecutiveFailures || 0) >= circuitThreshold,
+  }));
+}
+
+/** Best-effort read of the on-disk aggregate (→ {} on missing/corrupt). */
+function loadHookStats(file = defaultHookStatsPath(), fs = fsDefault) {
+  try {
+    if (!fs.existsSync(file)) return {};
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Best-effort atomic write (tmp + rename). Never throws. */
+function saveHookStats(stats, file = defaultHookStatsPath(), fs = fsDefault) {
+  try {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(stats), "utf-8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load the on-disk aggregate, fold in a session `delta`, and write it back.
+ * Best-effort end-to-end — the single call a supervisor makes on stopAll().
+ */
+function persistSessionStats(
+  delta,
+  file = defaultHookStatsPath(),
+  fs = fsDefault,
+) {
+  if (!delta || Object.keys(delta).length === 0) return false;
+  const merged = mergeStats(loadHookStats(file, fs), delta);
+  return saveHookStats(merged, file, fs);
+}
+
+module.exports = {
+  hookKey,
+  defaultHookStatsPath,
+  emptyStats,
+  aggregateRun,
+  mergeStats,
+  boundStats,
+  toCheckHooksInput,
+  loadHookStats,
+  saveHookStats,
+  persistSessionStats,
+  MAX_HOOKS,
+  DEFAULT_CIRCUIT_THRESHOLD,
+};

package/src/lib/idempotency.js

@@ -0,0 +1,109 @@
+/**
+ * Content-addressed idempotency — the P0-2 "Diff Apply 使用内容哈希/版本号" +
+ * "外部 API 优先使用 Provider Idempotency Key" primitives.
+ *
+ * All PURE (deterministic, no clock / RNG / I/O):
+ *
+ *  - `classifyEditReplay` — decide, from the CURRENT file content alone, whether
+ *    a literal edit still applies, has ALREADY landed (a resumed replay), or
+ *    genuinely conflicts. Lets a recovered worker skip an edit it already made
+ *    instead of double-applying it or erroring confusingly.
+ *  - `editIdempotencyKey` / `operationIdempotencyKey` — stable keys derived from
+ *    the operation and a canonicalized (order-independent) view of its args, so
+ *    a retry of the SAME effect yields the SAME key. An external provider that
+ *    honors `Idempotency-Key` then de-dupes a resumed replay; internally the key
+ *    tags each side-effect ledger op for duplicate detection.
+ */
+
+import { createHash } from "node:crypto";
+
+function sha256Hex(input) {
+  return createHash("sha256").update(String(input), "utf8").digest("hex");
+}
+
+/**
+ * Canonicalize a value so semantically-equal args hash identically regardless of
+ * key order. Arrays keep order (order is meaningful); object keys are sorted.
+ */
+function canonicalize(v) {
+  if (v == null) return null;
+  if (Array.isArray(v)) return v.map(canonicalize);
+  if (typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = canonicalize(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/** Fate of an edit checked against the current on-disk content. */
+export const EDIT_REPLAY = Object.freeze({
+  APPLY: "apply", // old_string present — the edit still applies
+  ALREADY_APPLIED: "already_applied", // old gone, new present — idempotent no-op
+  CONFLICT: "conflict", // neither present — a genuine mismatch, surface it
+});
+
+/**
+ * Decide the fate of a literal (old→new) edit against CURRENT content — the
+ * content-addressed idempotency check. On a resumed replay the edit already
+ * landed, so `old_string` is gone and `new_string` is present → already_applied
+ * (skip, never double-apply). PURE.
+ *
+ * Deletions (`new_string === ""`) are deliberately NOT auto-detected as
+ * already-applied: "old absent + nothing to look for" is indistinguishable from
+ * "old never existed", so those keep surfacing as a conflict (the safe default).
+ *
+ * @param {{content:string, oldString:string, newString:string, replaceAll?:boolean}} p
+ * @returns {"apply"|"already_applied"|"conflict"}
+ */
+export function classifyEditReplay({ content, oldString, newString }) {
+  const text = String(content ?? "");
+  const oldS = String(oldString ?? "");
+  const newS = String(newString ?? "");
+  if (oldS && text.includes(oldS)) return EDIT_REPLAY.APPLY;
+  // old_string is absent. A present, non-empty new_string means the intended
+  // change is already in the file — the edit already happened.
+  if (newS && text.includes(newS)) return EDIT_REPLAY.ALREADY_APPLIED;
+  return EDIT_REPLAY.CONFLICT;
+}
+
+/** Stable idempotency key for a literal edit against a target file. */
+export function editIdempotencyKey({ path, oldString, newString, replaceAll }) {
+  return (
+    "edit_" +
+    sha256Hex(
+      JSON.stringify([
+        String(path || ""),
+        String(oldString ?? ""),
+        String(newString ?? ""),
+        replaceAll === true,
+      ]),
+    ).slice(0, 40)
+  );
+}
+
+/**
+ * Deterministic idempotency key for an external, irreversible operation — stable
+ * across retries so a provider honoring `Idempotency-Key` de-dupes a resumed
+ * replay, and so the side-effect ledger can spot a duplicated commit. Derived
+ * from the tool + a canonicalized view of its args; NO wall-clock / RNG so the
+ * SAME logical effect always maps to the SAME key.
+ *
+ * `scope` is optional namespacing (e.g. a session id); OMIT it when you want a
+ * pure retry of the same call to collide with its earlier attempt.
+ *
+ * @param {{tool:string, args?:object, scope?:string}} p
+ * @returns {string}
+ */
+export function operationIdempotencyKey({ tool, args, scope } = {}) {
+  return (
+    "op_" +
+    sha256Hex(
+      JSON.stringify([
+        String(tool || ""),
+        scope == null ? "" : String(scope),
+        canonicalize(args ?? null),
+      ]),
+    ).slice(0, 40)
+  );
+}

package/src/lib/interaction-adapter.js

@@ -14,6 +14,7 @@ import {
   LEGACY_TO_UNIFIED_TYPE,
 } from "../runtime/runtime-events.js";
 import { createAbortError } from "./abort-utils.js";
+import { verifyApprovalBinding } from "./agent-authority.js";
 import { createEnvelope } from "@chainlesschain/session-core";
 
 // Phase 5: parallel service-envelope emission. Map WS agent-handler event
@@ -167,12 +168,21 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         reject,
         timeoutId,
         kind: options.kind || null,
+        // Approval binding (authority §"权限来源"): when a permission gate raises
+        // this request WITH a binding (tool_call_id + args + policy digest), an
+        // *approve* answer must echo the SAME binding or it is a stale / mis-
+        // routed / argument-tampered verdict and is rejected in _resolvePending.
+        // null (the default for plain questions) → no binding check, unchanged.
+        binding: options.binding || null,
       });
 
       this._sendWs({
         ...message,
         sessionId: this.sessionId,
         requestId,
+        // Ride the binding out so the remote UI/bridge can echo it back on the
+        // answer (only present when the caller supplied one).
+        ...(options.binding ? { binding: options.binding } : {}),
       });
     });
   }
@@ -210,8 +220,8 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
    * Called by ws-server when a session-answer message arrives.
    * Resolves the corresponding pending promise.
    */
-  resolveAnswer(requestId, answer) {
-    this._resolvePending(requestId, answer, "question");
+  resolveAnswer(requestId, answer, binding = null) {
+    this._resolvePending(requestId, answer, "question", binding);
   }
 
   async requestHostTool(toolName, args = {}, extra = {}) {
@@ -321,7 +331,12 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     }
   }
 
-  _resolvePending(requestId, payload, expectedKind = null) {
+  _resolvePending(
+    requestId,
+    payload,
+    expectedKind = null,
+    incomingBinding = null,
+  ) {
     const pending = this._pending.get(requestId);
     if (!pending) {
       return;
@@ -337,11 +352,26 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
       return;
     }
 
+    // Approval-binding guard (authority §"权限来源"): if this request was raised
+    // with a binding AND the answer echoes a binding that does NOT match, the
+    // verdict is for a different / argument-tampered call — settle as a DENY
+    // (fail closed) instead of the approve it claims to be, mirroring the local
+    // headless approval gate. Backward-compatible: no request binding, or an
+    // answer with no echoed binding, resolves exactly as before.
+    let effective = payload;
+    if (
+      pending.binding &&
+      incomingBinding &&
+      !verifyApprovalBinding(pending.binding, incomingBinding)
+    ) {
+      effective = false;
+    }
+
     this._pending.delete(requestId);
     if (pending.timeoutId) {
       clearTimeout(pending.timeoutId);
     }
-    pending.resolve(payload);
+    pending.resolve(effective);
   }
 }
 

package/src/lib/json-schema-output.js

@@ -7,13 +7,17 @@
  * `deps.writeOut` capture seam — the runner itself is untouched: each attempt
  * runs with output captured, the validated JSON is the only thing printed.
  *
- * Validator subset (enough for tool/script contracts, not full draft-2020):
- * type (object/array/string/number/integer/boolean/null), properties,
- * required, items, enum, const, additionalProperties:false. Zero deps.
+ * Constrained validation delegates to the richer Draft-2020-12-subset validator
+ * in [[json-schema-validate.js]] (type, properties, required, items/prefixItems,
+ * enum/const, additionalProperties, min/max, pattern, format, allOf/anyOf/oneOf/
+ * not, if/then/else, local $ref) so retries get precise coded/pointered errors —
+ * the model is told exactly WHICH JSON Pointer failed and WHY. The legacy
+ * `validateAgainstSchema` (loose `$.a.b` strings) stays exported for callers.
  */
 
 import fsDefault from "fs";
 import {
+  validate,
   validateSchema,
   buildStructuredResultEvent,
   computeSchemaDigest,
@@ -96,6 +100,20 @@ export function validateAgainstSchema(value, schema, path = "$") {
   return errors;
 }
 
+/**
+ * Render the richer validator's coded/pointered error objects as human-readable
+ * `<JSON Pointer>: <message>` strings for the corrective retry prompt and the
+ * final failure report. The empty root pointer is shown as `(root)`.
+ *
+ * @param {Array<{instancePath?:string, message:string}>} errors
+ * @returns {string[]}
+ */
+export function formatSchemaErrors(errors) {
+  return (errors || []).map(
+    (e) => `${e.instancePath || "(root)"}: ${e.message}`,
+  );
+}
+
 /**
  * Return the first *balanced* JSON object/array substring in `text`, honoring
  * string literals so braces inside strings don't throw off the depth count.
@@ -203,18 +221,29 @@ export function loadSchemaFile(fs, schemaFile) {
       "No schema provided: pass --json-schema <file> or a schema object",
     );
   }
+  // Inline JSON support: a value that starts with `{` is treated as a literal
+  // schema object, never a path (a filesystem path can't start with `{`). This
+  // lets `--json-schema '{"type":"object",...}'` work without a temp file.
+  const trimmed = String(schemaFile).trim();
+  const isInline = trimmed.startsWith("{");
   let raw;
-  try {
-    raw = fs.readFileSync(schemaFile, "utf-8");
-  } catch (e) {
-    throw new Error(`Cannot read schema file "${schemaFile}": ${e.message}`);
+  if (isInline) {
+    raw = trimmed;
+  } else {
+    try {
+      raw = fs.readFileSync(schemaFile, "utf-8");
+    } catch (e) {
+      throw new Error(`Cannot read schema file "${schemaFile}": ${e.message}`);
+    }
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (e) {
     throw new Error(
-      `Invalid JSON in schema file "${schemaFile}": ${e.message}`,
+      isInline
+        ? `Invalid inline JSON schema: ${e.message}`
+        : `Invalid JSON in schema file "${schemaFile}": ${e.message}`,
     );
   }
   // Startup schema meta-validation (P2): reject a malformed schema up front
@@ -226,7 +255,9 @@ export function loadSchemaFile(fs, schemaFile) {
       .slice(0, 5)
       .map((e) => `  - ${e.schemaPath || "/"}: ${e.message}`)
       .join("\n");
-    throw new Error(`Invalid JSON Schema in "${schemaFile}":\n${detail}`);
+    throw new Error(
+      `Invalid JSON Schema in ${isInline ? "inline schema" : `"${schemaFile}"`}:\n${detail}`,
+    );
   }
   return parsed;
 }
@@ -275,12 +306,15 @@ export async function runJsonSchemaConstrained(cfg = {}) {
     lastRaw = raw;
     const parsed = extractJsonPayload(raw);
     if (parsed.ok) {
-      const errors = validateAgainstSchema(parsed.value, schema);
-      if (errors.length === 0) {
+      // Richer validator: enforces the full supported subset (format assertions,
+      // if/then/else, min/max, pattern, combinators, …) and yields coded/pointered
+      // errors so the retry prompt tells the model exactly which pointer failed.
+      const { valid, errors } = validate(parsed.value, schema);
+      if (valid) {
         writeOut(`${JSON.stringify(parsed.value, null, 2)}\n`);
         return 0;
       }
-      lastErrors = errors;
+      lastErrors = formatSchemaErrors(errors);
     } else {
       lastErrors = [parsed.error];
     }

package/src/lib/json-schema-validate.js

@@ -22,9 +22,11 @@
  * Supported keywords: type (+ integer), enum, const, properties, required,
  * additionalProperties (bool|schema), patternProperties-free, items,
  * prefixItems, minItems/maxItems, uniqueItems, minLength/maxLength, pattern,
- * minimum/maximum/exclusiveMinimum/exclusiveMaximum, multipleOf,
- * minProperties/maxProperties, allOf/anyOf/oneOf/not, and local `$ref`
- * (`#/$defs/…`, `#/definitions/…`, or any in-document JSON Pointer).
+ * format (date-time/date/time/email/uri/uuid/ipv4/ipv6/hostname — asserted;
+ * unknown formats pass through as annotations), minimum/maximum/
+ * exclusiveMinimum/exclusiveMaximum, multipleOf, minProperties/maxProperties,
+ * allOf/anyOf/oneOf/not, if/then/else, and local `$ref` (`#/$defs/…`,
+ * `#/definitions/…`, or any in-document JSON Pointer).
  */
 
 import crypto from "crypto";
@@ -41,6 +43,97 @@ const KNOWN_TYPES = new Set([
 
 const MAX_REF_DEPTH = 128; // guards recursive $ref against cyclic data
 
+// ─── format assertions ───────────────────────────────────────────────────────
+// Draft 2020-12 `format` is asserted here (the protocol-facing structured-output
+// contract wants it enforced, not merely annotated). A format not in this map is
+// treated as an annotation and always passes. All checkers are pure strings→bool.
+
+function isCalendarDate(y, m, d) {
+  if (m < 1 || m > 12 || d < 1) return false;
+  const leap = (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return d <= days[m - 1];
+}
+
+function checkDate(v) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(v);
+  return !!m && isCalendarDate(+m[1], +m[2], +m[3]);
+}
+
+function checkTime(v) {
+  const m = /^(\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})?$/.exec(v);
+  if (!m) return false;
+  const hh = +m[1];
+  const mm = +m[2];
+  const ss = +m[3];
+  return hh <= 23 && mm <= 59 && ss <= 60; // 60 allows a leap second
+}
+
+function checkDateTime(v) {
+  const m = /^(.+)[Tt](.+)$/.exec(v);
+  if (!m) return false;
+  // RFC 3339 date-time requires an offset/Z on the time part.
+  if (!/([Zz]|[+-]\d{2}:\d{2})$/.test(m[2])) return false;
+  return checkDate(m[1]) && checkTime(m[2]);
+}
+
+function checkOctet(s) {
+  if (!/^\d{1,3}$/.test(s)) return false;
+  if (s.length > 1 && s[0] === "0") return false; // no leading zeros
+  return +s <= 255;
+}
+
+function checkIpv4(v) {
+  const parts = v.split(".");
+  return parts.length === 4 && parts.every(checkOctet);
+}
+
+function checkIpv6(v) {
+  if (typeof v !== "string" || v.length === 0) return false;
+  // At most one "::" compression; split on it.
+  const halves = v.split("::");
+  if (halves.length > 2) return false;
+  const hextet = /^[0-9a-fA-F]{1,4}$/;
+  if (halves.length === 2) {
+    const left = halves[0] === "" ? [] : halves[0].split(":");
+    const right = halves[1] === "" ? [] : halves[1].split(":");
+    if (
+      !left.every((g) => hextet.test(g)) ||
+      !right.every((g) => hextet.test(g))
+    )
+      return false;
+    return left.length + right.length <= 7; // "::" stands for ≥1 zero group
+  }
+  const groups = v.split(":");
+  return groups.length === 8 && groups.every((g) => hextet.test(g));
+}
+
+function checkHostname(v) {
+  if (typeof v !== "string" || v.length === 0 || v.length > 253) return false;
+  const labels = v.replace(/\.$/, "").split(".");
+  return labels.every((l) =>
+    /^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/.test(l),
+  );
+}
+
+const FORMAT_CHECKERS = {
+  "date-time": checkDateTime,
+  date: checkDate,
+  time: checkTime,
+  email: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
+  uri: (v) => /^[A-Za-z][A-Za-z0-9+.-]*:\S*$/.test(v),
+  uuid: (v) =>
+    /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(
+      v,
+    ),
+  ipv4: checkIpv4,
+  ipv6: checkIpv6,
+  hostname: checkHostname,
+};
+
+/** Known format names (exported for meta-validation / callers). */
+export const KNOWN_FORMATS = new Set(Object.keys(FORMAT_CHECKERS));
+
 /** RFC 6901 JSON Pointer from a segment array ("" = document root). */
 export function jsonPointer(segments) {
   if (!segments || segments.length === 0) return "";
@@ -194,6 +287,32 @@ function _validate(value, schema, inst, sch, root, errors, depth) {
     _validateObject(value, schema, inst, sch, root, errors, depth);
 
   _validateCombinators(value, schema, inst, sch, root, errors, depth);
+  _validateConditional(value, schema, inst, sch, root, errors, depth);
+}
+
+/**
+ * if/then/else — Draft 2020-12 conditional application. `if` is a *test* whose
+ * own errors are never reported; if the value matches `if`, `then` applies,
+ * otherwise `else` applies. No `if` keyword ⇒ then/else are inert.
+ */
+function _validateConditional(value, schema, inst, sch, root, errors, depth) {
+  if (schema.if === undefined) return;
+  const matched = _branchValid(value, schema.if, root, depth);
+  if (matched) {
+    if (schema.then !== undefined) {
+      _validate(
+        value,
+        schema.then,
+        inst,
+        [...sch, "then"],
+        root,
+        errors,
+        depth,
+      );
+    }
+  } else if (schema.else !== undefined) {
+    _validate(value, schema.else, inst, [...sch, "else"], root, errors, depth);
+  }
 }
 
 function _validateString(value, schema, inst, sch, errors) {
@@ -232,6 +351,19 @@ function _validateString(value, schema, inst, sch, errors) {
       );
     }
   }
+  if (typeof schema.format === "string") {
+    const check = FORMAT_CHECKERS[schema.format];
+    // Unknown format = annotation only (always passes), per Draft 2020-12.
+    if (check && !check(value)) {
+      _err(
+        errors,
+        "format",
+        inst,
+        [...sch, "format"],
+        `string is not a valid ${schema.format}`,
+      );
+    }
+  }
 }
 
 function _validateNumber(value, schema, inst, sch, errors) {
@@ -650,6 +782,14 @@ function _metaValidate(schema, segs, errors, depth) {
   }
   if (schema.not !== undefined)
     _metaValidate(schema.not, [...segs, "not"], errors, depth + 1);
+  if (schema.format !== undefined && typeof schema.format !== "string") {
+    _metaErr(errors, "format", [...segs, "format"], "format must be a string");
+  }
+  for (const k of ["if", "then", "else"]) {
+    if (schema[k] !== undefined) {
+      _metaValidate(schema[k], [...segs, k], errors, depth + 1);
+    }
+  }
   for (const defsKey of ["$defs", "definitions"]) {
     if (schema[defsKey] !== undefined) {
       if (

package/src/lib/jsonl-session-store.js

@@ -24,6 +24,7 @@ export {
   renameSession,
   pruneJsonlSessions,
   forkSession,
+  createBranchSession,
   sessionExists,
   getLastSessionId,
   migrateLegacySessions,