@circuitwall/jarela 2.2.1 → 2.3.0

package/lib/env/config.ts

@@ -44,6 +44,7 @@ export interface JarelaConfig {
   readonly streamParseTripwire: number;
   readonly recallBudgetMs: number;
   readonly warmSummaryBudgetMs: number;
+  readonly compactionTimeoutMs: number;
   readonly maxThreadMessages: number;
   readonly maxSessionArchives: number;
 
@@ -212,6 +213,7 @@ export function getConfig(): JarelaConfig {
     streamParseTripwire: parsePositiveInt(env.JARELA_STREAM_PARSE_TRIPWIRE, ENV_DEFAULTS.streamParseTripwire),
     recallBudgetMs: parseNonNegativeInt(env.JARELA_RECALL_BUDGET_MS, ENV_DEFAULTS.recallBudgetMs),
     warmSummaryBudgetMs: parseNonNegativeInt(env.JARELA_WARM_SUMMARY_BUDGET_MS, ENV_DEFAULTS.warmSummaryBudgetMs),
+    compactionTimeoutMs: parsePositiveInt(env.JARELA_COMPACTION_TIMEOUT_MS, ENV_DEFAULTS.compactionTimeoutMs),
     maxThreadMessages: parsePositiveInt(env.JARELA_MAX_THREAD_MESSAGES, ENV_DEFAULTS.maxThreadMessages),
     maxSessionArchives: parsePositiveInt(env.JARELA_MAX_SESSION_ARCHIVES, ENV_DEFAULTS.maxSessionArchives),
 

package/lib/env/schema.ts

@@ -86,6 +86,7 @@ export const ENV_DEFAULTS = {
   streamParseTripwire: 6,
   recallBudgetMs: 1500,
   warmSummaryBudgetMs: 5000,
+  compactionTimeoutMs: 10 * 60_000,
   maxThreadMessages: 1000,
   maxSessionArchives: 50,
   // tools
@@ -268,6 +269,17 @@ export const ENV_SCHEMA: readonly EnvVarDef[] = [
     agentWritable: false,
     min: 60_000,
   },
+  {
+    name: "JARELA_COMPACTION_TIMEOUT_MS",
+    type: "int",
+    default: ENV_DEFAULTS.compactionTimeoutMs,
+    description: "Deadline for one warm-context compaction of a thread; a late result is discarded and the thread is released.",
+    category: "agent",
+    tier: "B",
+    requiresRestart: false,
+    agentWritable: false,
+    min: 30_000,
+  },
   {
     name: "JARELA_RUN_REGISTRY_TTL_MS",
     type: "int",

package/lib/lifecycle/changeset-build.test.ts

@@ -0,0 +1,93 @@
+import { afterAll, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  extractAdoptionHints,
+  renderChangesetsMarkdown,
+  upsertChangeset,
+  writeReleaseChangeset,
+} from "./changeset-build";
+import type { SurfaceSnapshot } from "./surface-snapshot";
+
+const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-changeset-build-"));
+afterAll(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* held open */ }
+});
+
+const CHANGELOG = [
+  "# Changelog",
+  "## [Unreleased]",
+  "## [2.3.0] - 2026-02-01",
+  "### Added",
+  "- Something.",
+  "### Adoption",
+  "- Re-run watchers that use `web_search`;",
+  "  the `query` param is now required.",
+  "- Remove `old_tool` from allowlists.",
+  "## [2.2.0] - 2026-01-01",
+  "### Adoption",
+  "- Older hint.",
+].join("\n");
+
+function snapshot(version: string, tools: SurfaceSnapshot["tools"], prompts: SurfaceSnapshot["prompts"] = {}): SurfaceSnapshot {
+  return { schema_version: 1, version, prompts, tools };
+}
+
+describe("extractAdoptionHints", () => {
+  it("reads only the version's Adoption bullets, joining wrapped lines", () => {
+    expect(extractAdoptionHints(CHANGELOG, "2.3.0")).toEqual([
+      "Re-run watchers that use `web_search`; the `query` param is now required.",
+      "Remove `old_tool` from allowlists.",
+    ]);
+    expect(extractAdoptionHints(CHANGELOG, "2.2.0")).toEqual(["Older hint."]);
+    expect(extractAdoptionHints(CHANGELOG, "9.9.9")).toEqual([]);
+  });
+});
+
+describe("upsertChangeset and renderChangesetsMarkdown", () => {
+  const base = { previous_version: "1.0.0", date: "d", hints: [], commits: [], prompts: [], tools: [] };
+
+  it("replaces an existing version and keeps versions sorted", () => {
+    const file = upsertChangeset(
+      { schema_version: 1, changesets: [{ ...base, version: "2.10.0" }, { ...base, version: "2.9.0", hints: ["old"] }] },
+      { ...base, version: "2.9.0", hints: ["new"] },
+    );
+    expect(file.changesets.map((e) => [e.version, e.hints])).toEqual([["2.9.0", ["new"]], ["2.10.0", []]]);
+    const md = renderChangesetsMarkdown(file);
+    expect(md.indexOf("## 2.10.0")).toBeLessThan(md.indexOf("## 2.9.0"));
+    expect(md).toContain("- new");
+  });
+});
+
+describe("writeReleaseChangeset", () => {
+  it("diffs the committed snapshot, writes docs, and advances the snapshot", () => {
+    const root = join(tmpRoot, "repo");
+    mkdirSync(join(root, "docs/adoption"), { recursive: true });
+    writeFileSync(join(root, "CHANGELOG.md"), CHANGELOG);
+    const prev = snapshot("2.2.0", { web_search: { description: "Search.", parameters: { type: "object", properties: { query: {} } } } });
+    writeFileSync(join(root, "docs/adoption/surface-snapshot.json"), JSON.stringify(prev));
+    const next = snapshot("ignored", {
+      web_search: { description: "Search.", parameters: { type: "object", properties: { query: {} }, required: ["query"] } },
+    }, { "system.Rules": { source: "s.ts", text: "be careful" } });
+
+    const entry = writeReleaseChangeset({ root, version: "2.3.0", nextSnapshot: next, date: "2026-02-01" });
+
+    expect(entry).toMatchObject({ version: "2.3.0", previous_version: "2.2.0", commits: [] });
+    expect(entry.hints).toHaveLength(2);
+    expect(entry.tools).toMatchObject([{ name: "web_search", required_added: ["query"] }]);
+    expect(entry.prompts).toMatchObject([{ id: "system.Rules", change: "added" }]);
+    const written = JSON.parse(readFileSync(join(root, "docs/adoption/changesets.json"), "utf8"));
+    expect(written.changesets.map((e: { version: string }) => e.version)).toEqual(["2.3.0"]);
+    expect(JSON.parse(readFileSync(join(root, "docs/adoption/surface-snapshot.json"), "utf8")).version).toBe("2.3.0");
+    expect(readFileSync(join(root, "docs/adoption/index.md"), "utf8")).toContain("`web_search` — changed");
+  });
+
+  it("refuses to record a version that is not newer than the snapshot", () => {
+    const root = join(tmpRoot, "stale");
+    mkdirSync(join(root, "docs/adoption"), { recursive: true });
+    writeFileSync(join(root, "docs/adoption/surface-snapshot.json"), JSON.stringify(snapshot("2.3.0", {})));
+    expect(() => writeReleaseChangeset({ root, version: "2.2.0", nextSnapshot: snapshot("x", {}), date: "d" }))
+      .toThrow(/must be newer/);
+  });
+});

package/lib/lifecycle/changeset-build.ts

@@ -0,0 +1,210 @@
+/**
+ * Release-time changeset generation. Diffs the committed surface snapshot
+ * (docs/adoption/surface-snapshot.json) against the current one and records
+ * the prompt and tool deltas for the release version. Run through
+ * `npm run release:changeset`; never imported by the running app.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  changesetFileSchema,
+  compareVersions,
+  type ChangesetFile,
+  type ReleaseChangeset,
+} from "./changesets";
+import { diffSurfaces, type SurfaceSnapshot } from "./surface-snapshot";
+
+export const ADOPTION_DOCS_DIR = "docs/adoption";
+export const CHANGESETS_FILE = `${ADOPTION_DOCS_DIR}/changesets.json`;
+export const SNAPSHOT_FILE = `${ADOPTION_DOCS_DIR}/surface-snapshot.json`;
+export const CHANGESETS_PAGE = `${ADOPTION_DOCS_DIR}/index.md`;
+const MAX_COMMITS = 40;
+
+/** Bullets under `### Adoption` in the version's CHANGELOG section. */
+export function extractAdoptionHints(changelog: string, version: string): string[] {
+  const lines = changelog.split(/\r?\n/);
+  const start = lines.findIndex((line) => new RegExp(`^## \\[?${version.replace(/\./g, "\\.")}\\]?(\\s|$)`).test(line));
+  if (start === -1) return [];
+  const hints: string[] = [];
+  let inAdoption = false;
+  for (const line of lines.slice(start + 1)) {
+    if (/^## /.test(line)) break;
+    if (/^### /.test(line)) {
+      inAdoption = /^### Adoption\s*$/i.test(line);
+      continue;
+    }
+    if (!inAdoption) continue;
+    const bullet = /^\s*[-*]\s+(.+)$/.exec(line);
+    if (bullet) hints.push(bullet[1].trim());
+    else if (line.trim() && hints.length > 0) hints[hints.length - 1] += ` ${line.trim()}`;
+  }
+  return hints;
+}
+
+export function buildChangesetEntry(input: {
+  version: string;
+  previousSnapshot: SurfaceSnapshot;
+  nextSnapshot: SurfaceSnapshot;
+  date: string;
+  hints: string[];
+  commits: string[];
+}): ReleaseChangeset {
+  const delta = diffSurfaces(input.previousSnapshot, input.nextSnapshot);
+  return {
+    version: input.version,
+    previous_version: input.previousSnapshot.version,
+    date: input.date,
+    hints: input.hints,
+    commits: input.commits.slice(0, MAX_COMMITS),
+    prompts: delta.prompts,
+    tools: delta.tools,
+  };
+}
+
+export function upsertChangeset(file: ChangesetFile, entry: ReleaseChangeset): ChangesetFile {
+  const rest = file.changesets.filter((existing) => existing.version !== entry.version);
+  return {
+    schema_version: 1,
+    changesets: [...rest, entry].sort((a, b) => compareVersions(a.version, b.version)),
+  };
+}
+
+export function renderChangesetsMarkdown(file: ChangesetFile): string {
+  const out = [
+    "# Version adoption changesets",
+    "",
+    "Generated by `npm run release:changeset` — do not edit by hand.",
+    "",
+    "Each release records how the model-facing surface changed: prompt text Jarela sends and built-in tool",
+    "descriptions and parameter schemas. When Jarela starts on a new version, the default agent reads the",
+    "changesets between your last adopted version and the running one, then adapts your settings, agent",
+    "instructions, skills, and scheduled task or watcher prompts. Code changes are covered by the",
+    "[changelog](https://github.com/CircuitWall/jarela/blob/main/CHANGELOG.md).",
+    "",
+    "Release authors can add adoption hints as bullets under a `### Adoption` heading in the version's",
+    "CHANGELOG section.",
+  ];
+  for (const entry of [...file.changesets].reverse()) {
+    out.push("", `## ${entry.version}`, "", `From ${entry.previous_version ?? "—"} · ${entry.date}`, "");
+    if (entry.hints.length) {
+      out.push("### Adoption hints", "", ...entry.hints.map((hint) => `- ${hint}`), "");
+    }
+    out.push("### Tools", "");
+    if (entry.tools.length === 0) out.push("No tool description or schema changes.");
+    for (const tool of entry.tools) {
+      const details = [
+        tool.description_changed ? "description changed" : "",
+        tool.params_added.length ? `params added: ${tool.params_added.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.params_removed.length ? `params removed: ${tool.params_removed.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.params_changed.length ? `params changed: ${tool.params_changed.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.required_added.length ? `now required: ${tool.required_added.map((p) => `\`${p}\``).join(", ")}` : "",
+        tool.required_removed.length ? `no longer required: ${tool.required_removed.map((p) => `\`${p}\``).join(", ")}` : "",
+      ].filter(Boolean);
+      out.push(`- \`${tool.name}\` — ${tool.change}${details.length ? `; ${details.join("; ")}` : ""}`);
+    }
+    out.push("", "### Prompts", "");
+    if (entry.prompts.length === 0) out.push("No prompt text changes.");
+    for (const prompt of entry.prompts) {
+      out.push(`- \`${prompt.id}\` — ${prompt.change} (\`${prompt.source}\`)`);
+      const diff = [
+        ...prompt.added_lines.map((line) => `+ ${line}`),
+        ...prompt.removed_lines.map((line) => `- ${line}`),
+        ...(prompt.omitted_lines > 0 ? [`… ${prompt.omitted_lines} more line(s)`] : []),
+      ];
+      if (diff.length) out.push("", "    ```diff", ...diff.map((line) => `    ${line}`), "    ```", "");
+    }
+    if (entry.commits.length) {
+      out.push("", "### Commits", "", ...entry.commits.map((subject) => `- ${subject}`));
+    }
+  }
+  return `${out.join("\n").replace(/\n{3,}/g, "\n\n")}\n`;
+}
+
+export function readChangesetFile(root: string): ChangesetFile {
+  const path = join(root, CHANGESETS_FILE);
+  if (!existsSync(path)) return { schema_version: 1, changesets: [] };
+  return changesetFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function readSnapshot(path: string): SurfaceSnapshot {
+  return JSON.parse(readFileSync(path, "utf8")) as SurfaceSnapshot;
+}
+
+function snapshotAtTag(root: string, version: string): SurfaceSnapshot | null {
+  try {
+    const raw = execFileSync("git", ["show", `v${version}:${SNAPSHOT_FILE}`], {
+      cwd: root,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return JSON.parse(raw) as SurfaceSnapshot;
+  } catch {
+    return null;
+  }
+}
+
+export function gitCommitSubjects(root: string, from: string, to: string): string[] {
+  try {
+    const raw = execFileSync("git", ["log", "--no-merges", "--format=%s", `${from}..${to}`], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+/**
+ * Records the changeset for `version` against the committed snapshot, then
+ * moves the committed snapshot forward. Re-running for the same version
+ * replaces that entry, diffing against the snapshot committed at the
+ * predecessor's release tag.
+ */
+export function writeReleaseChangeset(input: {
+  root: string;
+  version: string;
+  nextSnapshot: SurfaceSnapshot;
+  date: string;
+  /** Git ref the release is cut from, for commit subjects. Defaults to HEAD. */
+  ref?: string;
+  /** Snapshot to diff against instead of the committed one (backfill). */
+  previousSnapshot?: SurfaceSnapshot;
+}): ReleaseChangeset {
+  const snapshotPath = join(input.root, SNAPSHOT_FILE);
+  const file = readChangesetFile(input.root);
+  let previous = input.previousSnapshot ?? readSnapshot(snapshotPath);
+  if (!input.previousSnapshot && previous.version === input.version) {
+    const recorded = file.changesets.find((entry) => entry.version === input.version)?.previous_version;
+    const prior = recorded ? snapshotAtTag(input.root, recorded) : null;
+    if (!prior) {
+      throw new Error(`Snapshot is already at ${input.version}; cannot find the v${recorded ?? "?"} snapshot to diff against.`);
+    }
+    previous = prior;
+  }
+  if (compareVersions(input.version, previous.version) <= 0) {
+    throw new Error(`Release version ${input.version} must be newer than snapshot version ${previous.version}.`);
+  }
+  const changelogPath = join(input.root, "CHANGELOG.md");
+  const changelog = existsSync(changelogPath) ? readFileSync(changelogPath, "utf8") : "";
+  const entry = buildChangesetEntry({
+    version: input.version,
+    previousSnapshot: previous,
+    nextSnapshot: { ...input.nextSnapshot, version: input.version },
+    date: input.date,
+    hints: extractAdoptionHints(changelog, input.version),
+    commits: gitCommitSubjects(input.root, `v${previous.version}`, input.ref ?? "HEAD"),
+  });
+  const updated = upsertChangeset(file, entry);
+  writeJson(join(input.root, CHANGESETS_FILE), updated);
+  writeFileSync(join(input.root, CHANGESETS_PAGE), renderChangesetsMarkdown(updated), "utf8");
+  writeJson(snapshotPath, { ...input.nextSnapshot, version: input.version });
+  return entry;
+}

package/lib/lifecycle/changesets.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  changesetFileSchema,
+  changesetsBetween,
+  compareVersions,
+  formatChangesetsForPrompt,
+  loadBundledChangesets,
+  summarizeChangesets,
+  type ReleaseChangeset,
+} from "./changesets";
+
+function entry(version: string, previous: string | null, overrides: Partial<ReleaseChangeset> = {}): ReleaseChangeset {
+  return { version, previous_version: previous, date: "2026-01-01", hints: [], commits: [], prompts: [], tools: [], ...overrides };
+}
+
+const tool = (name: string, change: "added" | "removed" | "changed") => ({
+  name, change, description_changed: change === "changed", description: `${name} does things.`,
+  params_added: [], params_removed: [], params_changed: [], required_added: [], required_removed: [],
+});
+
+describe("compareVersions", () => {
+  it("orders numerically, not lexically", () => {
+    expect(compareVersions("2.10.0", "2.9.9")).toBeGreaterThan(0);
+    expect(compareVersions("2.0.5", "2.0.5")).toBe(0);
+    expect(compareVersions("1.99.0", "2.0.0")).toBeLessThan(0);
+  });
+});
+
+describe("changesetsBetween", () => {
+  const all = [entry("2.0.1", "2.0.0"), entry("2.1.0", "2.0.1"), entry("2.2.0", "2.1.0")];
+
+  it("returns the cumulative range (previous, current] and marks full coverage", () => {
+    const range = changesetsBetween("2.0.1", "2.2.0", all);
+    expect(range.entries.map((e) => e.version)).toEqual(["2.1.0", "2.2.0"]);
+    expect(range.complete).toBe(true);
+  });
+
+  it("flags partial coverage when the range starts before the first changeset", () => {
+    const range = changesetsBetween("1.9.0", "2.2.0", all);
+    expect(range.entries).toHaveLength(3);
+    expect(range.complete).toBe(false);
+  });
+
+  it("flags partial coverage when the current version has no changeset", () => {
+    expect(changesetsBetween("2.1.0", "2.3.0", all).complete).toBe(false);
+  });
+});
+
+describe("summarizeChangesets and formatChangesetsForPrompt", () => {
+  const entries = [
+    entry("2.1.0", "2.0.0", {
+      hints: ["Re-check watchers."],
+      tools: [tool("old_tool", "removed"), tool("search", "changed")],
+      prompts: [{ id: "system.Tool usage SOP", source: "s.ts", change: "changed", added_lines: ["+rule"], removed_lines: ["-rule"], omitted_lines: 2 }],
+    }),
+    entry("2.2.0", "2.1.0", { tools: [tool("old_tool", "added")] }),
+  ];
+
+  it("keeps the latest state of each surface across the range", () => {
+    expect(summarizeChangesets(entries)).toEqual({
+      promptIds: ["system.Tool usage SOP"],
+      toolNames: ["old_tool", "search"],
+      removedTools: [],
+      hints: ["2.1.0: Re-check watchers."],
+    });
+  });
+
+  it("renders hints, tool deltas, and prompt excerpts within the budget", () => {
+    const text = formatChangesetsForPrompt(entries);
+    expect(text).toContain("adoption hint: Re-check watchers.");
+    expect(text).toContain("tool `old_tool`: removed");
+    expect(text).toContain("+ +rule");
+    expect(text).toContain("2 more changed line(s)");
+    expect(formatChangesetsForPrompt(entries, 40).length).toBeLessThan(200);
+  });
+});
+
+describe("bundled changesets", () => {
+  const raw = JSON.parse(readFileSync(join(process.cwd(), "docs/adoption/changesets.json"), "utf8"));
+  const bundled = loadBundledChangesets();
+
+  it("matches the schema", () => {
+    expect(changesetFileSchema.safeParse(raw).success).toBe(true);
+    expect(bundled.length).toBe(raw.changesets.length);
+  });
+
+  it("has an entry for the package.json version so the release PR cannot skip it", () => {
+    const { version } = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8")) as { version: string };
+    expect(bundled.map((e) => e.version), "run `npm run release:changeset` in the release PR").toContain(version);
+    const snapshot = JSON.parse(readFileSync(join(process.cwd(), "docs/adoption/surface-snapshot.json"), "utf8"));
+    expect(snapshot.version).toBe(version);
+  });
+
+  it("chains each release to its predecessor without gaps", () => {
+    for (let i = 1; i < bundled.length; i++) {
+      expect(bundled[i].previous_version, bundled[i].version).toBe(bundled[i - 1].version);
+    }
+  });
+});

package/lib/lifecycle/changesets.ts

@@ -0,0 +1,166 @@
+/**
+ * Bundled release changesets (docs/adoption/changesets.json), generated at
+ * release time by `npm run release:changeset`. Installed bundles have no git
+ * history, so version adoption reads these to learn which prompts and tool
+ * descriptions/schemas changed between the user's last adopted version and
+ * the running one.
+ */
+import { z } from "zod";
+import bundled from "@/docs/adoption/changesets.json";
+import type { PromptChange, ToolChange } from "./surface-snapshot";
+
+const changeKind = z.enum(["added", "removed", "changed"]);
+
+const promptChangeSchema = z.object({
+  id: z.string(),
+  source: z.string(),
+  change: changeKind,
+  added_lines: z.array(z.string()),
+  removed_lines: z.array(z.string()),
+  omitted_lines: z.number().int().nonnegative(),
+});
+
+const toolChangeSchema = z.object({
+  name: z.string(),
+  change: changeKind,
+  description_changed: z.boolean(),
+  description: z.string().optional(),
+  previous_description: z.string().optional(),
+  params_added: z.array(z.string()),
+  params_removed: z.array(z.string()),
+  params_changed: z.array(z.string()),
+  required_added: z.array(z.string()),
+  required_removed: z.array(z.string()),
+});
+
+export const releaseChangesetSchema = z.object({
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  previous_version: z.string().regex(/^\d+\.\d+\.\d+$/).nullable(),
+  date: z.string(),
+  hints: z.array(z.string()),
+  commits: z.array(z.string()),
+  prompts: z.array(promptChangeSchema),
+  tools: z.array(toolChangeSchema),
+});
+
+export const changesetFileSchema = z.object({
+  schema_version: z.literal(1),
+  changesets: z.array(releaseChangesetSchema),
+});
+
+export type ReleaseChangeset = z.infer<typeof releaseChangesetSchema>;
+export type ChangesetFile = z.infer<typeof changesetFileSchema>;
+
+// Compile-time guard: the bundled schema must stay in sync with the diff types.
+type Assert<T extends true> = T;
+type _PromptShape = Assert<PromptChange extends z.infer<typeof promptChangeSchema> ? true : false>;
+type _ToolShape = Assert<ToolChange extends z.infer<typeof toolChangeSchema> ? true : false>;
+
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const pb = b.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+let cached: ReleaseChangeset[] | null = null;
+
+export function loadBundledChangesets(): ReleaseChangeset[] {
+  if (cached) return cached;
+  const parsed = changesetFileSchema.safeParse(bundled);
+  cached = parsed.success
+    ? [...parsed.data.changesets].sort((a, b) => compareVersions(a.version, b.version))
+    : [];
+  return cached;
+}
+
+export interface ChangesetRange {
+  entries: ReleaseChangeset[];
+  /** True when the entries chain fully from `previous` to `current`. */
+  complete: boolean;
+}
+
+/** Cumulative changesets for versions in (previous, current]. */
+export function changesetsBetween(
+  previous: string,
+  current: string,
+  all: readonly ReleaseChangeset[] = loadBundledChangesets(),
+): ChangesetRange {
+  const entries = all
+    .filter((entry) => compareVersions(entry.version, previous) > 0 && compareVersions(entry.version, current) <= 0)
+    .sort((a, b) => compareVersions(a.version, b.version));
+  const reachesCurrent = entries.some((entry) => compareVersions(entry.version, current) === 0);
+  const first = entries[0];
+  const reachesPrevious = Boolean(first?.previous_version && compareVersions(first.previous_version, previous) <= 0);
+  return { entries, complete: reachesCurrent && reachesPrevious };
+}
+
+export interface ChangesetSurfaceSummary {
+  promptIds: string[];
+  toolNames: string[];
+  removedTools: string[];
+  hints: string[];
+}
+
+/** Collapses a version range to the latest state of each changed surface. */
+export function summarizeChangesets(entries: readonly ReleaseChangeset[]): ChangesetSurfaceSummary {
+  const prompts = new Set<string>();
+  const tools = new Map<string, ToolChange["change"]>();
+  const hints: string[] = [];
+  for (const entry of entries) {
+    for (const prompt of entry.prompts) prompts.add(prompt.id);
+    for (const tool of entry.tools) tools.set(tool.name, tool.change);
+    for (const hint of entry.hints) hints.push(`${entry.version}: ${hint}`);
+  }
+  return {
+    promptIds: [...prompts].sort(),
+    toolNames: [...tools.keys()].sort(),
+    removedTools: [...tools].filter(([, change]) => change === "removed").map(([name]) => name).sort(),
+    hints,
+  };
+}
+
+function describeTool(tool: ToolChange): string {
+  const parts: string[] = [];
+  if (tool.change === "added") parts.push("new tool");
+  if (tool.change === "removed") parts.push("removed — references to it will fail");
+  if (tool.description_changed) parts.push("description changed");
+  if (tool.params_added.length) parts.push(`params added: ${tool.params_added.join(", ")}`);
+  if (tool.params_removed.length) parts.push(`params removed: ${tool.params_removed.join(", ")}`);
+  if (tool.params_changed.length) parts.push(`params changed: ${tool.params_changed.join(", ")}`);
+  if (tool.required_added.length) parts.push(`now required: ${tool.required_added.join(", ")}`);
+  if (tool.required_removed.length) parts.push(`no longer required: ${tool.required_removed.join(", ")}`);
+  const head = `  - tool \`${tool.name}\`: ${parts.join("; ") || tool.change}`;
+  return tool.description && tool.change !== "removed"
+    ? `${head}\n    description: ${tool.description}`
+    : head;
+}
+
+function describePrompt(prompt: PromptChange): string {
+  const lines = [`  - prompt \`${prompt.id}\` (${prompt.source}): ${prompt.change}`];
+  for (const line of prompt.added_lines) lines.push(`    + ${line}`);
+  for (const line of prompt.removed_lines) lines.push(`    - ${line}`);
+  if (prompt.omitted_lines > 0) lines.push(`    … ${prompt.omitted_lines} more changed line(s)`);
+  return lines.join("\n");
+}
+
+/** Renders the range for the adoption prompt, bounded to `maxChars`. */
+export function formatChangesetsForPrompt(entries: readonly ReleaseChangeset[], maxChars = 8000): string {
+  const blocks: string[] = [];
+  for (const entry of entries) {
+    const lines = [`Version ${entry.version} (from ${entry.previous_version ?? "unknown"}, ${entry.date}):`];
+    if (entry.hints.length) lines.push(...entry.hints.map((hint) => `  - adoption hint: ${hint}`));
+    lines.push(...entry.tools.map(describeTool));
+    lines.push(...entry.prompts.map(describePrompt));
+    if (!entry.hints.length && !entry.tools.length && !entry.prompts.length) {
+      lines.push("  - no prompt or tool surface changes");
+    }
+    blocks.push(lines.join("\n"));
+  }
+  const text = blocks.join("\n");
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n… changeset truncated; the full record is docs/adoption/changesets.json in the release.`;
+}