@henols/c64-re-tools 2.0.0-rc.11 → 2.0.0-rc.13

package/src/host-client/transfer.ts

@@ -4,11 +4,35 @@
 import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, relative, sep } from "node:path";
 
-import { isInside, projectRoot, resolveProjectFile, resolveProjectPath } from "../project.ts";
+import { isInside, ProjectError, projectRoot, resolveProject, resolveProjectFile, resolveProjectPath } from "../project.ts";
 import { MAX_ATTACHMENT_BYTES } from "../protocol/framing.ts";
 import { WireFailure } from "../protocol/messages.ts";
 import { MAX_TREE_FILES, type SourceTree } from "../protocol/tools.ts";
 
+/** Runs a project lookup and gives a refusal of the project rules as a WireFailure with the same code and message. */
+function asWireFailure<T>(lookup: () => T): T {
+  try {
+    return lookup();
+  } catch (error) {
+    if (error instanceof ProjectError) throw new WireFailure(error.code, error.message);
+    throw error;
+  }
+}
+
+/**
+ * The project folder of a call that names it with `project` (relative to the
+ * working directory) or not (D67, D68). Throws WireFailure when the rules
+ * refuse it, for example at a folder with several projects below it.
+ */
+export function projectFolder(project: string | undefined): string {
+  return asWireFailure(() => resolveProject(project, process.cwd(), { remedy: "Give project: <folder>" }));
+}
+
+/** The project folder of this process (--project or the D67 lookup), or a WireFailure. */
+function currentProject(): string {
+  return asWireFailure(projectRoot);
+}
+
 export interface ProjectFile {
   bytes: Buffer;
   /** Lowercase extension without the dot; empty when the file has none. */
@@ -21,16 +45,16 @@ export interface ProjectFile {
  * the file is too large to transfer.
  */
 export function readProjectFile(path: string, options: { root?: string } = {}): ProjectFile {
-  const root = options.root ?? projectRoot();
+  const root = options.root ?? currentProject();
   let real: string;
   try {
     real = resolveProjectFile(path, root);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new WireFailure("not-found", `There is no file at ${path} in the project directory.`);
+      throw new WireFailure("not-found", `There is no file at ${path} in the project folder.`);
     }
     if (error instanceof TypeError) {
-      throw new WireFailure("invalid-input", `${path}: give a path relative to the project directory that stays inside it.`);
+      throw new WireFailure("invalid-input", `${path}: give a path relative to the project folder that stays inside it.`);
     }
     throw error;
   }
@@ -48,8 +72,8 @@ export function readProjectFile(path: string, options: { root?: string } = {}):
  * project, also one that leaves it through a symbolic link.
  */
 export function writeProjectFile(path: string, bytes: Uint8Array, options: { root?: string; what?: string } = {}): void {
-  const root = options.root ?? projectRoot();
-  const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project directory that stays inside it, not ${path}.`);
+  const root = options.root ?? currentProject();
+  const refuse = () => new WireFailure("invalid-input", `${options.what ?? path}: give a path relative to the project folder that stays inside it, not ${path}.`);
   let file: string;
   try {
     file = resolveProjectPath(path, root);
@@ -72,18 +96,18 @@ export function writeProjectFile(path: string, bytes: Uint8Array, options: { roo
 const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", ".c64-re-tools"]);
 
 /**
- * Reads a project directory as a source tree for staging: ordinary
+ * Reads a project folder as a source tree for staging: ordinary
  * files with relative POSIX paths. A symbolic link is followed only when its
  * target stays inside the source root; otherwise the tree is refused.
  */
 export function readProjectTree(path: string, options: { root?: string } = {}): { files: SourceTree; contents: Buffer[] } {
-  const projectRootPath = options.root ?? projectRoot();
+  const projectRootPath = options.root ?? currentProject();
   let sourceRoot: string;
   try {
     sourceRoot = resolveProjectFile(path, projectRootPath);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new WireFailure("not-found", `There is no directory ${path} in the project directory.`);
-    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project directory that stays inside it.`);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new WireFailure("not-found", `There is no directory ${path} in the project folder.`);
+    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project folder that stays inside it.`);
     throw error;
   }
   if (!statSync(sourceRoot).isDirectory()) throw new WireFailure("invalid-input", `${path} is not a directory.`);

package/src/host-client/vice-session.ts

@@ -127,21 +127,21 @@ export class ViceSessionClient {
     return this.#request("runUntil", params);
   }
 
-  /** Loads a project PRG into memory without reset or start; finishes stopped. */
-  async programLoad(params: { path: string; address?: number }): Promise<{ state: RunState; loadAddress: number; size: number }> {
-    const file = readProjectFile(params.path);
+  /** Loads a project PRG into memory without reset or start; finishes stopped. `root` is the project folder; it stays on this side. */
+  async programLoad(params: { path: string; address?: number; root?: string }): Promise<{ state: RunState; loadAddress: number; size: number }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("programLoad", params.address === undefined ? {} : { address: params.address }, [file.bytes]);
   }
 
-  /** Autostarts a project program or image, as VICE's autostart does. */
-  async autostart(params: { path: string; index: number; run: boolean }): Promise<{ state: RunState; emulatorFlaw?: string }> {
-    const file = readProjectFile(params.path);
+  /** Autostarts a project program or image, as VICE's autostart does. `root` is the project folder; it stays on this side. */
+  async autostart(params: { path: string; index: number; run: boolean; root?: string }): Promise<{ state: RunState; emulatorFlaw?: string }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("autostart", { type: file.type, index: params.index, run: params.run }, [file.bytes]);
   }
 
-  /** Attaches a project disk image to drive 8. */
-  async diskAttach(params: { path: string }): Promise<{ attached: boolean }> {
-    const file = readProjectFile(params.path);
+  /** Attaches a project disk image to drive 8. `root` is the project folder; it stays on this side. */
+  async diskAttach(params: { path: string; root?: string }): Promise<{ attached: boolean }> {
+    const file = readProjectFile(params.path, params.root === undefined ? {} : { root: params.root });
     return this.#request("diskAttach", { type: file.type }, [file.bytes]);
   }
 

package/src/knowledge/conflicts.ts

@@ -0,0 +1,157 @@
+// Conflicts (D69): current rows that break a current-row rule. One computer
+// never writes them, but git joins the knowledge of two computers line by
+// line, so after a merge two names can be current at one address, or two
+// regions can overlap. Reads show them; writes are refused until a merge
+// revision decides them.
+
+import type { DatabaseSync } from "node:sqlite";
+
+import type { HistoryEntry } from "./history.ts";
+import {
+  COMMENT_COLUMNS,
+  MACRO_COLUMNS,
+  MACRO_USE_COLUMNS,
+  MODULE_COLUMNS,
+  OPERAND_COLUMNS,
+  PATCH_COLUMNS,
+  REFERENCE_COLUMNS,
+  REGION_COLUMNS,
+  SUPPRESSION_COLUMNS,
+  SYMBOL_COLUMNS,
+  toComment,
+  toMacro,
+  toMacroUse,
+  toModule,
+  toOperand,
+  toPatch,
+  toReference,
+  toRegion,
+  toSuppression,
+  toSymbol,
+} from "./read.ts";
+import type { Space } from "./schema.ts";
+import { compareText, sqlName } from "./text.ts";
+
+/** The current-row rules, each with what breaks it. */
+export const CONFLICT_RULES = {
+  "symbol-address": "two symbols at one address",
+  "symbol-name": "one name at two addresses",
+  region: "regions that overlap",
+  comment: "two comments at one place",
+  reference: "the same reference two times",
+  operand: "two operand expressions at one address",
+  "module-start": "two modules at one address",
+  "module-file": "one module file at two addresses",
+  "suppression-symbol": "the same symbol suppression two times",
+  "suppression-reference": "the same reference suppression two times",
+  "suppression-region": "region suppressions that overlap",
+  patch: "patches that overlap",
+  macro: "two macros with one name",
+  "macro-use": "macro uses that overlap",
+} as const;
+export type ConflictRule = keyof typeof CONFLICT_RULES;
+
+/** One row of a conflict: the row with its revisions and its id. */
+export type ConflictRow = HistoryEntry & { id: string };
+
+/** Current rows that break one rule together, oldest first. */
+export interface Conflict {
+  rule: ConflictRule;
+  space: Space;
+  rows: ConflictRow[];
+}
+
+type Raw = Record<string, unknown>;
+
+interface TableRule {
+  rule: ConflictRule;
+  table: string;
+  entity: HistoryEntry["entity"];
+  columns: string;
+  map: (raw: Raw) => HistoryEntry["row"];
+  /** The columns that must differ between current rows, or "overlap" for address ranges. */
+  key: readonly string[] | "overlap";
+  /** Rows of the table that the rule is about. */
+  where?: string;
+}
+
+const RULES: readonly TableRule[] = [
+  { rule: "symbol-address", table: "symbols", entity: "symbol", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["address"] },
+  { rule: "symbol-name", table: "symbols", entity: "symbol", columns: SYMBOL_COLUMNS, map: toSymbol, key: ["name"] },
+  { rule: "region", table: "regions", entity: "region", columns: REGION_COLUMNS, map: toRegion, key: "overlap" },
+  { rule: "comment", table: "comments", entity: "comment", columns: COMMENT_COLUMNS, map: toComment, key: ["address", "placement"] },
+  { rule: "reference", table: "references", entity: "reference", columns: REFERENCE_COLUMNS, map: toReference, key: ["from_address", "to_address", "kind"] },
+  { rule: "operand", table: "operands", entity: "operand", columns: OPERAND_COLUMNS, map: toOperand, key: ["address"] },
+  { rule: "module-start", table: "modules", entity: "module", columns: MODULE_COLUMNS, map: toModule, key: ["start_address"] },
+  { rule: "module-file", table: "modules", entity: "module", columns: MODULE_COLUMNS, map: toModule, key: ["file"] },
+  { rule: "suppression-symbol", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: ["start_address"], where: "entity = 'symbol'" },
+  {
+    rule: "suppression-reference",
+    table: "suppressions",
+    entity: "suppression",
+    columns: SUPPRESSION_COLUMNS,
+    map: toSuppression,
+    key: ["start_address", "to_address", "kind"],
+    where: "entity = 'reference'",
+  },
+  { rule: "suppression-region", table: "suppressions", entity: "suppression", columns: SUPPRESSION_COLUMNS, map: toSuppression, key: "overlap", where: "entity = 'region'" },
+  { rule: "patch", table: "patches", entity: "patch", columns: PATCH_COLUMNS, map: toPatch, key: "overlap" },
+  { rule: "macro", table: "macros", entity: "macro", columns: MACRO_COLUMNS, map: toMacro, key: ["name"] },
+  { rule: "macro-use", table: "macro_uses", entity: "macro-use", columns: MACRO_USE_COLUMNS, map: toMacroUse, key: "overlap" },
+];
+
+function conflictRow(rule: TableRule, raw: Raw): ConflictRow {
+  return { entity: rule.entity, row: rule.map(raw), from: raw.valid_from_revision as string, id: raw.id as string } as ConflictRow;
+}
+
+const byAge = (a: ConflictRow, b: ConflictRow) => compareText(a.from, b.from) || compareText(a.id, b.id);
+
+/** The current rows of one rule that share a key, in groups. */
+function sameKey(db: DatabaseSync, rule: TableRule, key: readonly string[]): Conflict[] {
+  const where = `valid_to_revision IS NULL${rule.where === undefined ? "" : ` AND ${rule.where}`}`;
+  const columns = ["space", ...key].join(", ");
+  const rows = db
+    .prepare(`SELECT ${rule.columns}, id FROM ${sqlName(rule.table)} WHERE ${where} AND (${columns}) IN (SELECT ${columns} FROM ${sqlName(rule.table)} WHERE ${where} GROUP BY ${columns} HAVING count(*) > 1)`)
+    .all() as Raw[];
+  const groups = new Map<string, Conflict>();
+  for (const raw of rows) {
+    const id = JSON.stringify(["space", ...key].map((column) => raw[column]));
+    const group = groups.get(id) ?? { rule: rule.rule, space: raw.space as Space, rows: [] };
+    group.rows.push(conflictRow(rule, raw));
+    groups.set(id, group);
+  }
+  return [...groups.values()];
+}
+
+/** The current rows of one rule whose address ranges overlap, in groups of rows that overlap in a chain. */
+function overlapping(db: DatabaseSync, rule: TableRule): Conflict[] {
+  const rows = db
+    .prepare(`SELECT ${rule.columns}, id FROM ${sqlName(rule.table)} WHERE valid_to_revision IS NULL${rule.where === undefined ? "" : ` AND ${rule.where}`} ORDER BY space, start_address, end_address`)
+    .all() as Raw[];
+  const conflicts: Conflict[] = [];
+  let group: Conflict | undefined;
+  let end = -1;
+  for (const raw of rows) {
+    if (group !== undefined && raw.space === group.space && (raw.start_address as number) <= end) {
+      group.rows.push(conflictRow(rule, raw));
+      end = Math.max(end, raw.end_address as number);
+      continue;
+    }
+    if (group !== undefined && group.rows.length > 1) conflicts.push(group);
+    group = { rule: rule.rule, space: raw.space as Space, rows: [conflictRow(rule, raw)] };
+    end = raw.end_address as number;
+  }
+  if (group !== undefined && group.rows.length > 1) conflicts.push(group);
+  return conflicts;
+}
+
+/** Every conflict of the knowledge, rule by rule; the rows of each, oldest first. */
+export function conflicts(db: DatabaseSync | undefined): Conflict[] {
+  if (db === undefined) return [];
+  return RULES.flatMap((rule) => (rule.key === "overlap" ? overlapping(db, rule) : sameKey(db, rule, rule.key))).map((conflict) => ({ ...conflict, rows: conflict.rows.sort(byAge) }));
+}
+
+/** The table of a conflict rule. */
+export function conflictTable(rule: ConflictRule): string {
+  return RULES.find((item) => item.rule === rule)!.table;
+}

package/src/knowledge/database.ts

@@ -1,14 +1,23 @@
-// The one place that opens .c64-re-tools/knowledge.db.
+// The one place that opens the knowledge. The knowledge is text in
+// .c64-re-tools/knowledge/ (D69); .c64-re-tools/local/knowledge.db is an index
+// that is made again from the text when the text changed.
 
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
 
-import { projectRoot } from "../project.ts";
-import { checkVersion, ensureSchema, schemaVersion } from "./schema.ts";
+import { ensureLocal, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRoot } from "../project.ts";
+import { ensureSchema } from "./schema.ts";
+import { compareText, loadText, readText, REVISIONS_FILE, revisionsText, sha256, sqlName, TABLES, tableText, writeAtomic } from "./text.ts";
 
-export const KNOWLEDGE_DIRECTORY = ".c64-re-tools";
-export const KNOWLEDGE_FILE = "knowledge.db";
+export const KNOWLEDGE_DIRECTORY = PROJECT_DIRECTORY;
+/** The folder of the committed knowledge text. */
+export const TEXT_DIRECTORY = "knowledge";
+/** The index file in .c64-re-tools/local/. */
+export const INDEX_FILE = "knowledge.db";
+/** Git keeps the lines of both sides when two computers changed the same knowledge file. */
+// eol=lf: with core.autocrlf (the Windows default) git would check the files out with CRLF, so two computers would hold other bytes.
+export const GIT_ATTRIBUTES = "# The knowledge of c64-re-tools: git keeps the lines of both sides of a merge, with LF line ends on every system.\n*.jsonl merge=union text eol=lf\n.gitattributes text eol=lf\n";
 
 export const KNOWLEDGE_ERROR_CODES = [
   "invalid-input",
@@ -31,12 +40,27 @@ export class KnowledgeError extends Error {
   }
 }
 
-export function knowledgePath(root: string = projectRoot()): string {
-  return join(root, KNOWLEDGE_DIRECTORY, KNOWLEDGE_FILE);
+/** The folder of the knowledge text: .c64-re-tools/knowledge/. */
+export function textPath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, TEXT_DIRECTORY);
+}
+
+/** The index: .c64-re-tools/local/knowledge.db. */
+export function indexPath(root: string = projectRoot()): string {
+  return join(root, KNOWLEDGE_DIRECTORY, LOCAL_DIRECTORY, INDEX_FILE);
+}
+
+/** Refuses a project that has only the knowledge.db of an older c64-re-tools. */
+function refuseOldLayout(root: string): void {
+  if (!existsSync(textPath(root)) && existsSync(join(root, KNOWLEDGE_DIRECTORY, INDEX_FILE))) {
+    throw new KnowledgeError(
+      "unsupported-schema",
+      `${KNOWLEDGE_DIRECTORY}/${INDEX_FILE} is the knowledge of an older c64-re-tools. This c64-re-tools keeps the knowledge as text in ${KNOWLEDGE_DIRECTORY}/${TEXT_DIRECTORY}/. Convert it one time with distribution/convert-knowledge.ts of the c64-re-tools source repository.`,
+    );
+  }
 }
 
 function configure(db: DatabaseSync): void {
-  // A committed write must be complete in knowledge.db itself: rollback journal, never WAL.
   db.exec("PRAGMA journal_mode = DELETE; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
 }
 
@@ -47,28 +71,23 @@ function open(path: string, readOnly: boolean): DatabaseSync {
     configure(db);
     db.prepare("SELECT count(*) FROM sqlite_master").get();
   } catch (error) {
-    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${KNOWLEDGE_FILE} is not a readable SQLite database: ${(error as Error).message}`);
+    throw new KnowledgeError("invalid-database", `${KNOWLEDGE_DIRECTORY}/${LOCAL_DIRECTORY}/${INDEX_FILE} is not a readable SQLite database: ${(error as Error).message} Delete it: it is made again from the knowledge text.`);
   }
   return db;
 }
 
-/**
- * Opens the project's knowledge database read-only, as it is: a read never
- * migrates and never writes. Returns undefined when the database does not
- * exist or has no schema yet: that reads as empty knowledge, and a read
- * creates nothing. Refuses a schema version other than this build's.
- */
-export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
-  const path = knowledgePath(root);
-  if (!existsSync(path)) return undefined;
-  const db = open(path, true);
+/** Opens the index for a write and gives it the schema of this build. A file that is no database is made again. */
+function openIndex(root: string): DatabaseSync {
+  ensureLocal(root);
+  let db: DatabaseSync;
   try {
-    const version = schemaVersion(db);
-    if (version === 0) {
-      db.close();
-      return undefined;
-    }
-    checkVersion(version);
+    db = open(indexPath(root), false);
+  } catch {
+    writeFileSync(indexPath(root), "");
+    db = open(indexPath(root), false);
+  }
+  try {
+    ensureSchema(db);
   } catch (error) {
     db.close();
     throw error;
@@ -76,16 +95,75 @@ export function openForRead(root: string = projectRoot()): DatabaseSync | undefi
   return db;
 }
 
+function storedHashes(db: DatabaseSync): Record<string, string> {
+  const row = db.prepare("SELECT value FROM meta WHERE key = 'text_hashes'").get() as { value: string } | undefined;
+  return row === undefined ? {} : (JSON.parse(row.value) as Record<string, string>);
+}
+
+function storeHashes(db: DatabaseSync, hashes: Record<string, string>): void {
+  const sorted = Object.fromEntries(Object.entries(hashes).sort(([a], [b]) => compareText(a, b)));
+  db.prepare("INSERT INTO meta (key, value) VALUES ('text_hashes', ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value").run(JSON.stringify(sorted));
+}
+
+/** The SHA-256 of each knowledge file, by file name, in name order. */
+function textHashes(files: ReadonlyMap<string, { sha256: string }>): Record<string, string> {
+  return Object.fromEntries([...files].map(([name, file]): [string, string] => [name, file.sha256]).sort(([a], [b]) => compareText(a, b)));
+}
+
+const sameHashes = (a: Record<string, string>, b: Record<string, string>) => JSON.stringify(Object.entries(a).sort()) === JSON.stringify(Object.entries(b).sort());
+
 /**
- * Opens the project's knowledge database for a write, creating
- * .c64-re-tools/knowledge.db and its schema when needed. Refuses a schema
- * version other than this build's.
+ * Makes the index equal to the text when a knowledge file has another
+ * SHA-256 than the index holds, or a file came or went. Runs inside a write
+ * transaction, so two processes never make the index at the same time.
+ */
+function freshen(db: DatabaseSync, root: string): void {
+  const files = readText(textPath(root));
+  const hashes = textHashes(files);
+  if (sameHashes(hashes, storedHashes(db))) return;
+  db.exec("DELETE FROM evidence");
+  for (const spec of TABLES) db.exec(`DELETE FROM ${sqlName(spec.table)}`);
+  db.exec("DELETE FROM revisions");
+  loadText(db, files);
+  storeHashes(db, hashes);
+}
+
+/** The project of each index opened for a write: its writes go to the text too. */
+const projects = new WeakMap<DatabaseSync, string>();
+
+/**
+ * Opens the project's knowledge read-only, made fresh from the text first. A
+ * read never changes the knowledge. Returns undefined when the project has no
+ * knowledge text: that reads as empty knowledge, and a read creates nothing.
+ */
+export function openForRead(root: string = projectRoot()): DatabaseSync | undefined {
+  refuseOldLayout(root);
+  if (!existsSync(textPath(root))) return undefined;
+  const index = openIndex(root);
+  try {
+    // The lock is taken only when the text changed: a read does not wait for a long write that keeps the index fresh.
+    if (!sameHashes(textHashes(readText(textPath(root))), storedHashes(index))) transaction(index, () => freshen(index, root));
+  } finally {
+    index.close();
+  }
+  return open(indexPath(root), true);
+}
+
+/**
+ * Opens the project's knowledge for a write: it creates
+ * .c64-re-tools/knowledge/ with its .gitattributes when needed, and the index.
+ * Every committed transaction on the database writes the changed knowledge
+ * files.
  */
 export function openForWrite(root: string = projectRoot()): DatabaseSync {
-  mkdirSync(join(root, KNOWLEDGE_DIRECTORY), { recursive: true });
-  const db = open(knowledgePath(root), false);
+  refuseOldLayout(root);
+  mkdirSync(textPath(root), { recursive: true });
+  const attributes = join(textPath(root), ".gitattributes");
+  if (!existsSync(attributes)) writeFileSync(attributes, GIT_ATTRIBUTES);
+  const db = openIndex(root);
+  projects.set(db, root);
   try {
-    ensureSchema(db);
+    transaction(db, () => undefined);
   } catch (error) {
     db.close();
     throw error;
@@ -94,13 +172,14 @@ export function openForWrite(root: string = projectRoot()): DatabaseSync {
 }
 
 /**
- * Runs one write on the project's knowledge database and closes it. When the
- * project has no knowledge.db yet, `work` first runs on an empty database in
- * memory: a write that is refused there creates no .c64-re-tools/. `work`
- * must change nothing outside the database it gets.
+ * Runs one write on the project's knowledge and closes it. When the project
+ * has no knowledge yet, `work` first runs on an empty database in memory: a
+ * write that is refused there creates no .c64-re-tools/. `work` must change
+ * nothing outside the database it gets.
  */
 export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = projectRoot()): T {
-  if (!existsSync(knowledgePath(root))) {
+  refuseOldLayout(root);
+  if (!existsSync(textPath(root))) {
     const trial = new DatabaseSync(":memory:");
     try {
       configure(trial);
@@ -118,11 +197,44 @@ export function withWrite<T>(work: (db: DatabaseSync) => T, root: string = proje
   }
 }
 
-/** Runs `work` in one immediate transaction: all of it commits, or none of it does. */
+/** The newest revision id, or "0" when there is none. */
+function newest(db: DatabaseSync): string {
+  return (db.prepare("SELECT max(id) AS id FROM revisions").get() as { id: string | null }).id ?? "0";
+}
+
+/**
+ * Writes the knowledge files that the revisions after `before` changed, then
+ * keeps their SHA-256 in the index. The text is written before the index
+ * commits: when the commit fails, the next open makes the index from the text.
+ */
+function writeText(db: DatabaseSync, root: string, before: string): void {
+  const directory = textPath(root);
+  const hashes = storedHashes(db);
+  const write = (file: string, text: string) => {
+    writeAtomic(join(directory, file), text);
+    hashes[file] = sha256(text);
+  };
+  write(REVISIONS_FILE, revisionsText(db));
+  for (const spec of TABLES) {
+    const changed = db.prepare(`SELECT 1 FROM ${sqlName(spec.table)} WHERE valid_from_revision > ? OR valid_to_revision > ? LIMIT 1`).get(before, before);
+    if (changed !== undefined) write(spec.file, tableText(db, spec));
+  }
+  storeHashes(db, hashes);
+}
+
+/**
+ * Runs `work` in one immediate transaction: all of it commits, or none of it
+ * does. On the knowledge of a project, the index is made fresh from the text
+ * first, and a work that adds a revision writes the changed knowledge files.
+ */
 export function transaction<T>(db: DatabaseSync, work: () => T): T {
+  const root = projects.get(db);
   db.exec("BEGIN IMMEDIATE");
   try {
+    if (root !== undefined) freshen(db, root);
+    const before = root === undefined ? "0" : newest(db);
     const result = work();
+    if (root !== undefined && newest(db) !== before) writeText(db, root, before);
     db.exec("COMMIT");
     return result;
   } catch (error) {