datanotes 3.1.0 → 3.3.0

package/dist/docs/develop/write-an-extension.md

@@ -0,0 +1,369 @@
+# Write an extension
+
+> An extension adds tables and MCP tools to any Datanotes database: a git repository with a manifest, a built entry file and docs.
+
+An extension is a git repository that adds tables, views, bases and MCP tools to a Datanotes database. You install it with `datanotes extension install`. [Install extensions](https://datanotes.dev/administration/extensions/) covers the user’s side.
+
+This page builds a small extension, `acme/datanotes-ext-reading`. It keeps a reading list: books, their authors and what you read now.
+
+## Lay out the repository
+
+The repository holds the manifest at its root, the built entry file the manifest names, and a `docs` folder.
+
+```text
+datanotes-ext-reading/
+  datanotes-extension.json
+  dist/extension.mjs
+  docs/
+    index.md
+    tools.md
+  src/extension.ts
+  package.json
+  README.md
+  LICENSE
+```
+
+* `dist/extension.mjs` is committed. The installer never runs `npm install`, a build or a script. It copies the files and checks their hashes.
+* The entry file is one bundled ES module that imports only Node built-ins. Bundle your code and its libraries into it. The installer reads its imports, minified or not, and refuses a package or another file.
+* `docs/index.md` is required. `docs/tools.md` has one `##` heading per tool, named like the tool.
+* `README.md` and a licence file travel with the code when present.
+
+Bundle the entry file with esbuild:
+
+```bash
+npx esbuild src/extension.ts --bundle --platform=node \
+  --format=esm --target=node18 --outfile=dist/extension.mjs
+```
+
+Your repository must not ignore `dist/`. Commit the bundle with each release.
+
+## Write the manifest
+
+`datanotes-extension.json` declares the extension’s name, version, tables, tools and permissions. Before you confirm, the installer reads only the manifest. So the plan shows what the extension may do, without running its code.
+
+```json
+{
+  "manifest_version": 1,
+  "name": "reading",
+  "version": "1.0.0",
+  "description": "A reading list: books and who wrote them",
+  "datanotes": ">=3.3.0",
+  "api": 1,
+  "entry": "dist/extension.mjs",
+  "default_schema": "reading",
+  "instructions": "Call list_reading, then finish_book once a book is read.",
+  "tables": {
+    "person": {
+      "owned": false,
+      "names": ["person", "people", "author"],
+      "description": "A person: here, the author of a book",
+      "filename": "{name}",
+      "columns": [
+        { "name": "name", "type": "string", "required": true,
+          "description": "The person's full name" }
+      ]
+    },
+    "book": {
+      "owned": true,
+      "description": "A book on the reading list",
+      "filename": "{title}",
+      "columns": [
+        { "name": "title", "type": "string", "required": true,
+          "description": "The book's title, as printed on the cover" },
+        { "name": "author", "type": "link", "ref": "@person",
+          "description": "Who wrote it" },
+        { "name": "status", "type": "enum",
+          "values": ["to_read", "reading", "read"], "default": "to_read",
+          "description": "Where the reader is with it" },
+        { "name": "rating", "type": "integer", "min": 1, "max": 5,
+          "description": "From 1 to 5, once read" }
+      ],
+      "constraints": [
+        {
+          "name": "rating_only_when_read",
+          "check": {
+            "or": [{ "status": "read" }, { "rating": { "exists": false } }]
+          },
+          "hint": "Rate a book only once it is read: set status read too."
+        }
+      ],
+      "instructions": "Link author to a row of @{person}.",
+      "bases": ["shelved"]
+    }
+  },
+  "bases": {
+    "shelved": {
+      "description": "Where a thing sits on a shelf",
+      "columns": [
+        { "name": "shelf", "type": "string",
+          "description": "The shelf it sits on" }
+      ]
+    }
+  },
+  "views": {
+    "vw_reading": {
+      "description": "Books being read now",
+      "query": { "table": "@book", "where": { "status": "reading" } }
+    }
+  },
+  "permissions": { "write": ["book"] },
+  "tools": [
+    {
+      "name": "list_reading",
+      "description": "List the books being read now: title and author.",
+      "inputSchema": {
+        "type": "object", "properties": {}, "additionalProperties": false
+      },
+      "annotations": { "title": "List Reading", "readOnlyHint": true },
+      "tables": ["book", "person"],
+      "writes": []
+    },
+    {
+      "name": "finish_book",
+      "description": "Mark a book read, with an optional rating from 1 to 5.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string", "description": "The book's title" },
+          "rating": { "type": "integer", "minimum": 1, "maximum": 5 }
+        },
+        "required": ["title"],
+        "additionalProperties": false
+      },
+      "annotations": { "title": "Finish Book", "readOnlyHint": false },
+      "tables": ["book"],
+      "writes": ["book"]
+    }
+  ]
+}
+```
+
+The `book` table has a CHECK with its hint, and the base `shelved`. The view `vw_reading` lists the books being read.
+
+Every key at the top level follows a rule:
+
+| Key                | Rule                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `manifest_version` | Required. Exactly `1`.                                                                                 |
+| `name`             | Required. 2 to 40 lowercase letters, digits or `-`, starting with a letter. The token is `ext-<name>`. |
+| `version`          | Required. `MAJOR.MINOR.PATCH`, with an optional `-pre` suffix.                                         |
+| `description`      | Required. 1 to 300 characters.                                                                         |
+| `datanotes`        | Required. Exactly `">=X.Y.Z"`: the oldest engine version it works with.                                |
+| `api`              | Required. Exactly `1`: the module API version.                                                         |
+| `entry`            | Required. A relative path to a `.mjs` file inside the repository, with `/` separators.                 |
+| `default_schema`   | Required. Lowercase letters, digits and `_`: the schema of created owned tables and views.             |
+| `instructions`     | Optional. 1 to 400 characters, added to the `datanotes mcp` instructions.                              |
+| `tables`           | Required. At least one role. Order matters.                                                            |
+| `bases`            | Optional. The extension’s own bases.                                                                   |
+| `views`            | Optional. Names start with `vw_`.                                                                      |
+| `permissions`      | Required. `write` lists the roles the extension’s token may write. It may be empty.                    |
+| `tools`            | Required. May be empty.                                                                                |
+| `migrations`       | Optional. See [Migrate the schema between versions](#migrate-the-schema-between-versions).             |
+
+An unknown key is an error, and the message suggests the closest real key. Tool definitions keep MCP’s own field names, such as `inputSchema` and `readOnlyHint`. Every other key is snake_case.
+
+`datanotes extension check` reports every problem at once, each as `<path>: <text>`. A path looks like `tables.book.columns[2].ref`. Common problems:
+
+* `name: must be 2 to 40 lowercase letters, digits or -, starting with a letter`
+* `datanotes: must be ">=X.Y.Z", such as ">=3.3.0"`
+* `tables.book.columns[1].type: "text" is not a column type (...)` lists the real types.
+* `tables.book.columns[1].ref: must be "self" or "@<role>" of a table declared before this one`
+* `tools[0].writes[0]: "book" is not in permissions.write`
+* `tools[0]: a read-only tool writes nothing (empty writes, or readOnlyHint false)`
+* `tools[0]: a tool that writes has readOnlyHint false`
+* `tables.book.columns[0]: "id" is the engine's own column: leave it out`
+
+## Declare the tables
+
+Each table has a role: a short name the manifest uses, such as `book`. Tools never use a table’s real name. They ask for it with `ctx.table("book")`, so the extension works on any database.
+
+An extension relates to a role in one of two ways:
+
+* **Owned** (`"owned": true`): the extension creates the table, or adopts one of that name. It declares columns, `constraints`, `instructions` and `bases`.
+* **Dependency** (`"owned": false`): the table belongs to the user, such as `person`. `names` lists the names that identify a match. The default is the table’s name.
+
+These rules apply to tables:
+
+* **Order matters.** A column’s `ref: "@person"` names a role declared before it. Put the dependencies first. Use `ref: "self"` for a link to the table itself.
+* **`need`** is `"required"` (default) or `"optional"`. On a dependency, it says whether a matched table must have the column.
+* **`@{role}`** inside any text is replaced by the role’s real table name. Use it in `instructions` and hints.
+* **CHECKs** carry a `hint`, what to do when a row breaks the rule. Write one for every CHECK.
+
+The installer compares the manifest with a table it adopts or matches:
+
+* Columns are compared by name and by their rules (type, `ref`, values).
+* A missing column is added on an owned table. On a dependency, it is a problem the user solves with `--map` or `--add`.
+* CHECKs are compared by name. Equal ones stay. Different ones are replaced, and the plan shows it.
+* Instructions that differ are replaced, and the plan shows it.
+* Tags are added. Nothing is migrated again.
+
+Version 1 has three limits:
+
+* A manifest cannot declare an `inverse` across two tables. Only `ref: "self"` takes `inverse`.
+* The columns of the extension’s own tables keep the manifest’s names. Users map only dependency columns.
+* A dotted key into a dependency, such as `project.kind`, is not mapped in CHECKs and view queries.
+
+## Write the tools
+
+The entry file exports one handler per tool. The default export looks like this:
+
+```ts
+import {
+  defineExtension,
+  ExtensionToolError,
+} from "datanotes/extensions";
+
+
+interface Rows {
+  rows: { path: string; title: string; author?: string }[];
+}
+
+
+export default defineExtension({
+  api: 1,
+  handlers: {
+    async list_reading(_args, ctx) {
+      const found = await ctx.callTool("select_rows", {
+        table: ctx.table("book"),
+        where: { status: "reading" },
+        columns: ["title", "author"],
+      });
+      if (!found.ok) throw new ExtensionToolError(String(found.value));
+      return { books: (found.value as Rows).rows };
+    },
+    async finish_book(args, ctx) {
+      const book = ctx.table("book");
+      const found = await ctx.callTool("select_rows", {
+        table: book,
+        where: { title: args.title },
+        columns: ["title"],
+      });
+      if (!found.ok) throw new ExtensionToolError(String(found.value));
+      const [row] = (found.value as Rows).rows;
+      if (row === undefined) {
+        throw new ExtensionToolError(
+          `no book titled "${String(args.title)}"`,
+          "Call list_reading to find the title as written.",
+          "tools#finish_book",
+        );
+      }
+      const set: Record<string, unknown> = { status: "read" };
+      if (args.rating !== undefined) set.rating = args.rating;
+      const done = await ctx.callTool("update_row", {
+        table: book,
+        path: row.path,
+        set,
+      });
+      if (!done.ok) throw new ExtensionToolError(String(done.value));
+      return { path: row.path, status: "read" };
+    },
+  },
+});
+```
+
+The types come from `datanotes/extensions`, the package’s module API. Your bundle may hold its own copy of `ExtensionToolError`, or a small class of your own. Either works: the host recognises a refusal by its name, `ToolError`.
+
+A handler gets the agent’s arguments and a context:
+
+| Member                                | What it does                                                                                                                       |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.callTool(operation, args)`       | Runs an engine operation with the extension’s token, on behalf of the agent. It never throws for a refusal: read `ok` and `value`. |
+| `ctx.table(role)`                     | The qualified name of the table bound to a role.                                                                                   |
+| `ctx.column(role, column)`            | The name of a role’s column in the bound table: the user’s mapping, or the manifest’s name.                                        |
+| `ctx.hasColumn(role, column)`         | Whether the bound table has that column. An optional column may be missing.                                                        |
+| `ctx.actor()`                         | The agent that called: `session`, `harness`, `harness_version`, `model`.                                                           |
+| `ctx.timezone`                        | The database’s time zone, or an empty string.                                                                                      |
+| `ctx.log(level, message, attributes)` | A log record through the MCP server’s log.                                                                                         |
+| `ctx.extension`                       | `{ name, version }`.                                                                                                               |
+
+The extension never sees a token. The MCP server checks the arguments against the tool’s `inputSchema` before the handler runs.
+
+### Refuse with a hint
+
+Throw `ExtensionToolError(message, hint, docs)` for a mistake the agent can fix. The message says what is wrong. The hint says how to fix it. `docs` is a page of your docs, with an optional anchor: `"tools#finish_book"`. The agent reads:
+
+```text
+no book titled "Dune"
+Hint: Call list_reading to find the title as written.
+Docs: read_docs("extensions/reading/tools#finish_book")
+```
+
+Write a `## finish_book` heading in `docs/tools.md` for every link you give. Any other error becomes `extension reading failed in finish_book: <message>`, and the server logs it.
+
+### Declare what a tool writes
+
+Each tool lists `tables`, the roles it reads or writes, and `writes`, the roles it writes. Every role in `writes` must be in `permissions.write`. A tool with `readOnlyHint: true` has an empty `writes`. A tool that writes has `readOnlyHint: false`.
+
+Before a tool with a non-empty `writes` runs, the server checks the calling agent’s token. That token must be able to write those tables. A token that may not write them gets a refusal. This is why a wrong `writes` list matters: declare it exactly.
+
+A tool with an empty `writes` may not write rows, even if the extension’s token could. The server refuses these calls from the tool’s handler:
+
+* `batch`
+* `restore_table`
+* any operation that writes rows, such as `insert_row` or `update_rows`
+
+The refusal reads `tool <tool> of extension <name> declares no writes: it may not call <operation>`. To write, declare the roles in `writes` and set `readOnlyHint: false`. Otherwise, call a read operation.
+
+### Log without leaking
+
+Call `ctx.log` with a constant message and put the variable parts in attributes. Never log argument values, tokens or note text.
+
+## Migrate the schema between versions
+
+The manifest always describes the latest schema. `migrations` lists the operations that bring a database from an older version to the new one. A migration holds only declarative operations, the ones `batch` takes.
+
+```json
+"migrations": [
+  {
+    "version": "1.1.0",
+    "description": "Record the day a book was finished",
+    "operations": [
+      {
+        "op": "add_column",
+        "table": "@book",
+        "column": {
+          "name": "finished_on",
+          "type": "date",
+          "description": "The day the book was finished"
+        }
+      }
+    ]
+  }
+]
+```
+
+Follow these rules:
+
+* Versions increase down the list, and none is later than the manifest’s `version`.
+* `@book` is replaced by the real table name, as everywhere in the manifest.
+* A step whose effect is already there is skipped, so a migration runs safely twice.
+* A migration cannot run code. A data conversion is out of scope for version 1.
+
+An update also reconciles the tables with the new manifest by itself. It adds missing columns, CHECKs, instructions, tags, bases and views, and replaces CHECKs that changed. List a migration only when you rename, move or drop something. The installer never drops a column unless a migration does.
+
+## Check and publish an extension
+
+Run the check in the repository. It validates the manifest and the files without a database:
+
+```bash
+datanotes extension check .
+```
+
+While you develop, install from the folder on a test copy of a database, never your real one:
+
+```bash
+datanotes extension install ./datanotes-ext-reading \
+  --database ~/scratch/notes-copy
+datanotes extension update reading --from ./datanotes-ext-reading \
+  --database ~/scratch/notes-copy
+```
+
+To publish, follow these steps:
+
+1. Set `version` in the manifest.
+2. Rebuild `dist/extension.mjs` and commit it.
+3. Run `datanotes extension check .`.
+4. Tag the commit `v<version>`, for example `v1.0.0`. The tag must name the manifest’s version.
+5. Push the tag. Users install with `owner/repo@v1.0.0`.
+
+An out-of-date `dist` is the most common mistake: the installer ships what is committed.

package/dist/docs/guides/data-quality/check-constraints.md

@@ -6,7 +6,7 @@ A CHECK constraint is a rule written as a `where` filter, such as “a watched f
 
 ## Enforce rules with CHECK constraints
 
-`add_constraint` adds a CHECK constraint, a rule every row must satisfy, written as a `where` filter. The engine refuses it while existing rows break the rule and lists them; after that, it enforces the rule on every write. A condition on a column the row leaves empty passes, as in Structured Query Language (SQL). Inside `or`, `and` and `not`, the engine tests an empty value as it is, so a watched film without a `rating` breaks `rated_when_watched`.
+`add_constraint` adds a CHECK constraint, a rule every row must satisfy, written as a `where` filter. The engine refuses it while existing rows break the rule and lists them; after that, it enforces the rule on every write. A condition on a column the row leaves empty passes, as in Structured Query Language (SQL). Inside `or`, `and` and `not`, the engine tests an empty value as it is, so a watched film without a `rating` breaks `rated_when_watched`. `hint` says what to do when a row breaks the rule. The refusal puts it first, and `describe_table` lists it in `constraint_hints`.
 
 **`add_constraint`**
 
@@ -14,7 +14,8 @@ A CHECK constraint is a rule written as a `where` filter, such as “a watched f
 {
   "table": "film",
   "name": "rated_when_watched",
-  "check": { "or": [{ "status": { "ne": "watched" } }, { "rating": { "exists": true } }] }
+  "check": { "or": [{ "status": { "ne": "watched" } }, { "rating": { "exists": true } }] },
+  "hint": "A watched film needs a rating from 1 to 5: ask me for it."
 }
 ```
 
@@ -28,7 +29,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 8, "operation": "ADD CONSTRAINT" }
   ],
-  "migration_id": "20261014T191534-add_constraint-add-constraint-rated_when_watc"
+  "migration_id": "20261020T173845-add_constraint-add-constraint-rated_when_watc"
 }
 ```
 
@@ -57,7 +58,7 @@ Refused:
 ```text
 insert_row refused — nothing was written:
 invalid datanotes/diary/classics/film/His Girl Friday.md: rated_when_watched violates CHECK rated_when_watched: {"or":[{"status":{"ne":"watched"}},{"rating":{"exists":true}}]}
-Hint: The row breaks a CHECK constraint of the table (named in the message, with its rule): change the values so the rule holds. describe_table lists the table's constraints. Then call insert_row again (dry_run: true checks without writing).
+Hint: A watched film needs a rating from 1 to 5: ask me for it. The row breaks a CHECK constraint of the table (named in the message, with its rule): change the values so the rule holds. describe_table lists the table's constraints. Then call insert_row again (dry_run: true checks without writing).
 Docs: https://datanotes.dev/guides/data-quality/check-constraints.md#enforce-rules-with-check-constraints (offline: read_docs("guides/data-quality/check-constraints#enforce-rules-with-check-constraints"))
 ```
 
@@ -85,7 +86,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/His Girl Friday.md"],
   "commits": [{ "table": "diary.classics.film", "version": 10, "operation": "WRITE" }],
-  "migration_id": "20261014T191534-insert_row-insert-into-film-2"
+  "migration_id": "20261020T173845-insert_row-insert-into-film"
 }
 ```
 
@@ -107,7 +108,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 11, "operation": "DROP CONSTRAINT" }
   ],
-  "migration_id": "20261014T191534-drop_constraint-drop-constraint-at_most_three_"
+  "migration_id": "20261020T173845-drop_constraint-drop-constraint-at_most_three_"
 }
 ```
 
@@ -148,7 +149,7 @@ Answer:
   "commits": [
     { "table": "main.public.genre", "version": 4, "operation": "ADD CONSTRAINT" }
   ],
-  "migration_id": "20261014T191519-add_constraint-add-constraint-parent_by_level"
+  "migration_id": "20261020T173831-add_constraint-add-constraint-parent_by_level"
 }
 ```
 
@@ -227,34 +228,34 @@ Answer:
   "ok": true,
   "op": "batch",
   "dry_run": false,
-  "migration_id": "20261014T191519-batch-add-the-silent-era-and-slapsti",
+  "migration_id": "20261020T173831-batch-add-the-silent-era-and-slapsti",
   "steps": [
     {
       "index": 0,
       "op": "insert_row",
       "ok": true,
-      "migration_id": "20261014T191519-insert_row-insert-into-genre-4",
+      "migration_id": "20261020T173831-insert_row-insert-into-genre-4",
       "result": {
         "ok": true,
         "op": "insert_row",
         "files_created": 1,
         "planned_creates": ["datanotes/main/public/genre/Silent cinema.md"],
         "commits": [{ "table": "main.public.genre", "version": 5, "operation": "WRITE" }],
-        "migration_id": "20261014T191519-insert_row-insert-into-genre-4"
+        "migration_id": "20261020T173831-insert_row-insert-into-genre-4"
       }
     },
     {
       "index": 1,
       "op": "insert_row",
       "ok": true,
-      "migration_id": "20261014T191519-insert_row-insert-into-genre-5",
+      "migration_id": "20261020T173831-insert_row-insert-into-genre-5",
       "result": {
         "ok": true,
         "op": "insert_row",
         "files_created": 1,
         "planned_creates": ["datanotes/main/public/genre/Slapstick comedy.md"],
         "commits": [{ "table": "main.public.genre", "version": 6, "operation": "WRITE" }],
-        "migration_id": "20261014T191519-insert_row-insert-into-genre-5"
+        "migration_id": "20261020T173831-insert_row-insert-into-genre-5"
       }
     }
   ]
@@ -342,7 +343,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.genre", "version": 7, "operation": "UPDATE" }],
-  "migration_id": "20261014T191519-update_row-update-genre"
+  "migration_id": "20261020T173831-update_row-update-genre"
 }
 ```
 

package/dist/docs/guides/data-quality/hand-edits.md

@@ -35,7 +35,7 @@ You edit `datanotes/main/public/genre/Silent film.md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.genre
-id: 01a13bd7-2bd8-71e9-a39c-6ec373b79149
+id: 01a15a64-b310-70dd-a3f1-8f7d07ed2729
 name: Silent film
 kind: cinema
 parent: "[[Cinema]]"
@@ -47,7 +47,7 @@ Read the hand edit’s event. `list_changes` long-polls with `wait_ms` until the
 **`list_changes`**
 
 ```json
-{ "since": 39, "tables": ["genre"], "wait_ms": 10000 }
+{ "since": 45, "tables": ["genre"], "wait_ms": 10000 }
 ```
 
 Answer:
@@ -55,7 +55,7 @@ Answer:
 ```json
 [
   {
-    "seq": 40,
+    "seq": 46,
     "kind": "update",
     "path": "datanotes/main/public/genre/Silent film.md",
     "source": "external",
@@ -152,7 +152,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.genre", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261014T191521-update_row-update-genre"
+  "migration_id": "20261020T173832-update_row-update-genre"
 }
 ```
 
@@ -167,7 +167,7 @@ You edit `datanotes/main/public/watch/2026-10-03T2130.md` by hand, outside the e
 ```markdown
 ---
 table: main.public.watch
-id: 01a13bd7-2222-7352-9dea-dd1d7658c61f
+id: 01a15a64-ab35-73d2-a276-9c24d3c889dd
 film: His Girl Friday
 occurred_at: 2026-10-03T21:30
 where: cinema
@@ -226,7 +226,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.watch", "version": 3, "operation": "RECOMPUTE" }],
-  "migration_id": "20261014T191518-recompute_columns-recompute-id-day-label-of-watc"
+  "migration_id": "20261020T173830-recompute_columns-recompute-id-day-label-of-watc"
 }
 ```
 
@@ -292,7 +292,7 @@ Answer:
 ```markdown
 ---
 table: main.public.watch
-id: 01a13bd7-8a28-7d6f-843c-977d6d33e981
+id: 01a15a65-0df1-7af6-9ccd-c58c8b5346c0
 occurred_at: 2026-09-25T21:00
 film: "[[Charade]]"
 where: home
@@ -311,7 +311,7 @@ You edit `datanotes/main/public/film/Metropolis.md` by hand, outside the engine.
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-4bf3-7a1e-b23c-2769c0dc41d3
+id: 01a15a64-cea3-776e-b81b-389706767aa1
 year: 1927
 minutes: 153
 status: to watch
@@ -384,7 +384,7 @@ You edit `datanotes/main/public/film/Sherlock Jr..md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-3226-73d9-ba6b-80f93c52766a
+id: 01a15a64-b991-7728-99e2-bf13797d5532
 title: Sherlock Jr.: the projectionist
 year: 1924
 status: watched
@@ -471,7 +471,7 @@ You edit `datanotes/main/public/film/Sherlock Jr..md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-3226-73d9-ba6b-80f93c52766a
+id: 01a15a64-b991-7728-99e2-bf13797d5532
 title: "Sherlock Jr.: the projectionist"
 year: 1924
 status: watched

package/dist/docs/guides/database-objects/bases.md

@@ -30,7 +30,7 @@ Answer:
   "ok": true,
   "op": "define_base",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-define_base-create-base-entry"
+  "migration_id": "20261020T173845-define_base-create-base-entry"
 }
 ```
 
@@ -50,7 +50,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 6, "operation": "SET TABLE BASES" }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-film-extends-en"
+  "migration_id": "20261020T173845-set_table_bases-diary-classics-film-extends-en"
 }
 ```
 
@@ -118,14 +118,14 @@ Answer:
   "rows": [
     {
       "path": "datanotes/diary/classics/actors/Max Schreck.md",
-      "id": "01a13bd7-65fe-747a-b7cc-7c6c8d09e39d",
+      "id": "01a15a64-e8e3-73eb-9164-1fc8de45795b",
       "added_on": "2026-10-05",
       "note": "The face of Nosferatu",
       "_source": "diary.classics.actors"
     },
     {
       "path": "datanotes/diary/classics/film/Nosferatu.md",
-      "id": "01a13bd7-659b-7233-a73c-4f8191e95b0e",
+      "id": "01a15a64-e863-705a-96ae-42d6c22c878b",
       "added_on": "2026-10-05",
       "note": null,
       "_source": "diary.classics.film"
@@ -169,7 +169,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actors", "version": 3, "operation": "DEFINE BASE" }
   ],
-  "migration_id": "20261014T191534-define_base-alter-base-entry"
+  "migration_id": "20261020T173845-define_base-alter-base-entry"
 }
 ```
 
@@ -246,7 +246,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actors", "version": 4, "operation": "DEFINE BASE" }
   ],
-  "migration_id": "20261014T191534-define_base-alter-base-entry-2"
+  "migration_id": "20261020T173845-define_base-alter-base-entry-2"
 }
 ```
 
@@ -280,7 +280,7 @@ Answer:
   "ok": true,
   "op": "define_base",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-define_base-create-base-credited"
+  "migration_id": "20261020T173845-define_base-create-base-credited"
 }
 ```
 
@@ -300,7 +300,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actors", "version": 5, "operation": "SET TABLE BASES" }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-actors-extends--2"
+  "migration_id": "20261020T173845-set_table_bases-diary-classics-actors-extends--2"
 }
 ```
 
@@ -329,7 +329,7 @@ Answer:
   "ok": true,
   "op": "define_base",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-define_base-create-base-tree"
+  "migration_id": "20261020T173845-define_base-create-base-tree"
 }
 ```
 
@@ -369,7 +369,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.genre", "version": 1, "operation": "SET TABLE BASES" }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-genre-extends-t"
+  "migration_id": "20261020T173845-set_table_bases-diary-classics-genre-extends-t"
 }
 ```
 
@@ -475,6 +475,6 @@ Answer:
       "operation": "SET TABLE BASES"
     }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-genre_draft-ext"
+  "migration_id": "20261020T173845-set_table_bases-diary-classics-genre_draft-ext"
 }
 ```