datanotes 2.0.1 → 3.0.0

package/dist/docs/administration/use-with-obsidian.md

@@ -0,0 +1,75 @@
+# Use Datanotes with Obsidian
+
+> Run the engine with --vault when an app such as Obsidian opens the whole vault: how paths and wikilinks work, and how to move between a vault and a database folder.
+
+Datanotes runs on a database folder by default, with `--database`. Apps such as Obsidian work on a vault instead: a folder of all your notes, where the database is one folder among others. This page shows:
+
+* When to start the engine with `--vault`
+* How paths and wikilinks work in a vault
+* How to move between a vault and a database folder
+
+## Choose between a database folder and a vault
+
+You have two ways to use Obsidian with Datanotes:
+
+* **Open the database folder in Obsidian**: start the engine with `--database`, and open that same folder as an Obsidian vault. The folder’s root is then the vault root, so links resolve as they are. Use it when the database is all you keep in the vault.
+* **Run the engine on the vault**: start the engine with `--vault` on the folder Obsidian opens. The database is a subfolder of the vault. Use it when the vault already holds other notes, or other apps that expect a vault.
+
+Start the engine on a vault with `--vault`, or the `DATANOTES_VAULT` variable:
+
+```bash
+npx -y datanotes serve --vault your_vault_folder
+```
+
+Give `--vault` or `--database`, never both: the engine refuses to start with both.
+
+## Find the database in the vault
+
+The database is the folder of the vault’s one `metastore.yaml`. A new database goes to `datanotes/`, at the top of the vault. The folder can have any name and sit anywhere in the vault, also in a subfolder. [One database per vault](https://datanotes.dev/administration/run-the-service/#one-database-per-vault) explains how the engine finds it at each start.
+
+Rows and plain notes live side by side. A plain note links to a row, and a row links to a plain note, with backlinks on both sides. The engine serves every note of the vault, not only the rows: [`read_note`](https://datanotes.dev/reference/operations/queries/#read_note), [`list_folder`](https://datanotes.dev/reference/operations/queries/#list_folder) and [`search_notes`](https://datanotes.dev/reference/operations/queries/#search_notes) reach them all.
+
+## Read paths and wikilinks from the vault root
+
+With `--vault`, every path is relative to the vault. A row of the table `film`, in catalog `main` and schema `public`, has this path:
+
+```text
+datanotes/main/public/film/Metropolis.md
+```
+
+A note at the vault’s root is `intro.md`. Operations take and return paths in this form, and the wikilinks the engine writes start from the vault root too. Obsidian resolves links from the same root, so it follows every link the engine writes.
+
+With `--database`, paths start from the database folder instead: the same row is `main/public/film/Metropolis.md`. When you open that folder in Obsidian, its root is the vault root, so links resolve there too.
+
+## Move between a vault and a database folder
+
+[`configure_database`](https://datanotes.dev/reference/operations/auxiliary/#configure_database) with `root` moves the database within the folder the engine serves. The move rewrites every link in one operation, as for any [move of the database folder](https://datanotes.dev/start/how-it-works/#move-the-vault-or-the-database-folder).
+
+To turn a vault into a database folder, move the database to the vault root with `root: ""`:
+
+```ts
+await db.call("configure_database", { root: "" });
+```
+
+The catalog folders and `metastore.yaml` then sit at the root, and paths lose their `datanotes/` prefix. From the next start, run the engine with `--database` on that folder. The engine refuses the move when a catalog folder or a `metastore.yaml` already exists at the root.
+
+To move the database back into a subfolder, give the folder’s name:
+
+```ts
+await db.call("configure_database", { root: "datanotes" });
+```
+
+From the next start, run the engine with `--vault` on the same folder.
+
+## Pass the same option to every command
+
+The other commands find the engine by the same folder and option you gave `datanotes serve`:
+
+```bash
+npx -y datanotes status --vault your_vault_folder
+npx -y datanotes stop --vault your_vault_folder
+npx -y datanotes store path --vault your_vault_folder
+npx -y datanotes mcp --vault your_vault_folder
+```
+
+With a database folder, pass `--database your_database_folder` to each instead.

package/dist/docs/api/operations/add_column.md

@@ -0,0 +1,49 @@
+# Add a typed column. Sparse by default (written only on rows that have a value — use for
+
+`POST /datanotes/operations/add_column/` (operation `add_column`)
+
+Add a typed column. Sparse by default (written only on rows that have a value — use for
+metrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label":
+"Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`).
+`description` is required: what the column holds, for the agents and people who read the schema
+(the engine writes it for `identity` "uuid" / "created" columns).
+`dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add
+a column whose meaning an existing column (name/label/aliases/description) already covers.
+Column names are permanent identifiers; only `rename_column` changes them.
+Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them.
+Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet).
+Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `column` | `object` | yes |  | The column's spec: name, type, description and its other attributes; `dense: true` writes it on every row. |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/add_constraint.md

@@ -0,0 +1,55 @@
+# ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,
+
+`POST /datanotes/operations/add_constraint/` (operation `add_constraint`)
+
+ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,
+e.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL;
+inside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails).
+A key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}`
+(further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` /
+`not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row
+whose parent has no parent). A link to a row that does not exist fails; on a list of links every linked
+row must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a
+missing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the
+vault (by path, from the row's note: same-named rows in two folders stay apart); renaming or moving a
+linked row keeps them (they follow it).
+Refused while existing rows violate it (they are listed); then enforced on every write, by the same rule.
+A write that changes a linked row re-checks the rows that link to it and is refused, listing them, when
+it breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault
+the earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too.
+rename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `name` | `string` | yes |  |  |
+| `check` | `object` | yes |  |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/adopt_rows.md

@@ -0,0 +1,50 @@
+# Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and
+
+`POST /datanotes/operations/adopt_rows/` (operation `adopt_rows`)
+
+Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and
+links: `rename` keys (`{"data": "occurred_at"}`), `set` for all, `per_row` values by
+note path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.
+Every note gets `table` and a system `id`; with `relocate` (default true, unlike move_rows:
+notes become rows where the table keeps its rows) it moves to the table's folder, named by its filename pattern (links to it are rewritten). All notes are validated first
+(as rows of `table`, so notes of the same call may link to one another):
+unknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo
+with `undo_migration`. Many notes: adopt them in calls of about 1,000 `paths` each, so a
+stop or a crash interrupts less (each call is one journal entry).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `paths` | `string[]` | yes |  |  |
+| `rename` | `object \| null` | no | `null` |  |
+| `set` | `object \| null` | no | `null` |  |
+| `per_row` | `object \| null` | no | `null` |  |
+| `drop` | `string[] \| null` | no | `null` |  |
+| `relocate` | `boolean` | no | `true` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/align_relations.md

@@ -0,0 +1,41 @@
+# Add the reciprocal links missing on a table's `inverse` link columns (e.g. Alice lists Carol
+
+`POST /datanotes/operations/align_relations/` (operation `align_relations`)
+
+Add the reciprocal links missing on a table's `inverse` link columns (e.g. Alice lists Carol
+in `friends` but Carol does not list Alice). Run it after declaring `inverse` on existing data;
+check_table reports such rows (code `inverse`). Single-value links already pointing elsewhere
+are conflicts (nothing written). The links it adds are checked like other writes (CHECKs that
+follow links, `ref_where` / `ref_by`). Writes through the tools already keep both sides in step.
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `paths` | `string[] \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/alter_column.md

@@ -0,0 +1,46 @@
+# Change a column's attributes (type, min/max/step, values, required, default, label,
+
+`POST /datanotes/operations/alter_column/` (operation `alter_column`)
+
+Change a column's attributes (type, min/max/step, values, required, default, label,
+aliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except
+`description`, which changes but never goes (null or "" is refused); `dense` true/false). Refused with
+the list of violating rows when existing values do not satisfy the new definition. A
+different scale means a different column: add a new one instead of rescaling. To rename one
+enum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a
+target level is refused, naming it.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `column` | `string` | yes |  | The column's name. |
+| `changes` | `object` | yes |  |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/alter_table.md

@@ -0,0 +1,67 @@
+# Alter a table: move it (`catalog`, `schema`), rename it (`name`), change
+
+`POST /datanotes/operations/alter_table/` (operation `alter_table`)
+
+Alter a table: move it (`catalog`, `schema`), rename it (`name`), change
+`partition` / `filename` patterns, `description` (changes, never goes: "" is refused), `aliases`,
+`exclude` folders, `row_template`
+("" removes it), `history` (true | false | "default"), `autolink_target`
+(true | false | "default": may automatic links link its rows? default: yes, unless its rows are named by
+a date or a time) or `tags` (key/value
+labels merged into the table's, e.g. `{"domain": "health"}`; a `null` value removes that tag;
+`clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those),
+`archive` (folder name inside the table folder) or `fields` (untyped fields, name → default; a
+`null` value removes one). Rows, archive and transaction log follow; links are updated; renamed
+rows keep their old name in `aliases`. A change of metadata only (tags, description, aliases,
+history, autolink_target, row_template, fields) rewrites the table entry alone: no row is moved or rewritten. Refused
+when a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows
+links, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not
+rewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `catalog` | `string \| null` | no | `null` |  |
+| `schema` | `string \| null` | no | `null` |  |
+| `name` | `string \| null` | no | `null` |  |
+| `partition` | `string \| null` | no | `null` |  |
+| `filename` | `string \| null` | no | `null` |  |
+| `description` | `string \| null` | no | `null` | The new description: what a row records (it changes, never goes: "" is refused). |
+| `aliases` | `string[] \| null` | no | `null` |  |
+| `history` | `boolean \| "default" \| null` | no | `null` | Keep the table's versions: true, false, or "default" (the database's setting). |
+| `autolink_target` | `boolean \| "default" \| null` | no | `null` | May automatic links link the table's rows? true, false, or "default" (yes, unless its rows are named by a date or a time). |
+| `exclude` | `string[] \| null` | no | `null` |  |
+| `row_template` | `string \| null` | no | `null` | Markdown body of new rows; "" removes it. |
+| `tags` | `object \| null` | no | `null` | Tags to add or change (strings); a null value removes that tag. The other tags are kept. |
+| `clear_tags` | `boolean` | no | `false` | Remove every tag first (with `tags`: the table keeps exactly those). |
+| `archive` | `string \| null` | no | `null` | Archive folder: a folder name inside the table folder (e.g. "_archive"); "" = the database default (`archive_folder`). Archived rows follow. |
+| `fields` | `object \| null` | no | `null` | Untyped fields to set (name → default, as in create_table `fields`); a null value removes that field. The other fields are kept; a name cannot be a column. |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/batch.md

@@ -0,0 +1,48 @@
+# Several writes that succeed or fail together. `operations`: `[{"op": ..., ...arguments}]` where
+
+`POST /datanotes/operations/batch/` (operation `batch`)
+
+Several writes that succeed or fail together. `operations`: `[{"op": ..., ...arguments}]` where
+`op` is a row operation (`insert_row`, `update_row`, `update_rows`, `delete_rows`, `merge_rows`,
+`move_rows`, `adopt_rows`, `recompute_columns`, `align_relations`, `restore_table`) or a DDL op
+(`create_table`, `add_column`, `alter_column`, …), with the same arguments as the operation (an unknown one refuses the batch) (e.g.
+`values` for insert_row, `set` for update_row / update_rows). They run in order, each seeing the previous ones; if one is
+refused, the ones already applied are undone (`rolled_back`). Returns `steps` (per operation, each with its result,
+where `ambiguous_mentions` is as in insert_row) and
+`migration_id`: undo_migration on it reverts the whole batch. Use it when a change spans several
+rows (create an event and update the people in it). `dry_run` checks each operation against the
+current data only.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `operations` | `object[]` | yes |  |  |
+| `summary` | `string \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `object` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `object \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `object` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/changes_stream.md

@@ -0,0 +1,28 @@
+# The change feed as Server-Sent Events (id = sequence number). Resumes from Last-Event-ID or `since`.
+
+`GET /datanotes/changes/stream` (operation `changes_stream`)
+
+Same filters as list_changes (`tables`, `kinds`, `columns`: comma-separated; `exclude_actor`; `where`: JSON). A comment line every 25 s keeps proxies from closing the connection; `event: gap` tells the client events were pruned.
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `since` | query | `string` | no |  |
+| `tables` | query | `string` | no |  |
+| `kinds` | query | `string` | no |  |
+| `columns` | query | `string` | no |  |
+| `exclude_actor` | query | `string` | no |  |
+| `where` | query | `string` | no |  |
+| `Last-Event-ID` | header | `string` | no |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | The events, one `data:` line (JSON) each. | `string` (text/event-stream) |
+| 400 | `where` is not a JSON object. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 503 | The change feed is not running. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/check_table.md

@@ -0,0 +1,29 @@
+# Validate every row against the table (required, types, ranges, enums, links, unknown
+
+`POST /datanotes/operations/check_table/` (operation `check_table`)
+
+Validate every row against the table (required, types, ranges, enums, links, unknown
+columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). A CHECK violation has code `check` and the CHECK's name as `constraint` (every other code names its `column`), as in the `violations` of list_changes. Use it to find rows edited by hand that break the schema. Without `table`, every table is checked: each row then names its `table`, `tables_checked` counts the tables checked, and a table that cannot be checked is listed in `errors` ({table, error}) while the others are. The rows with violations are paged: `limit` (default 500, at most 5000) from `offset`; `total` counts them all. (Hand edits are also checked as they happen: see `violations` in list_changes.)
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string \| null` | no | `null` | Omit to check every table. |
+| `limit` | `integer` | no | `500` | Rows with violations returned (paging). |
+| `offset` | `integer` | no | `0` | Rows with violations skipped first (paging). |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/clone_table.md

@@ -0,0 +1,48 @@
+# CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows
+
+`POST /datanotes/operations/clone_table/` (operation `clone_table`)
+
+CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows
+(deep clone), optionally as of a `version` / `timestamp`. `copy_rows: false` copies the
+definition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (in the
+source's catalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy
+in the `agent` catalog. The clone is a new table, so it needs the descriptions create_table does: a
+source without them is refused, naming what to describe first (alter_table, alter_column). A past
+version lacking one gets the one the source has now.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `source` | `string` | yes |  |  |
+| `target` | `string` | yes |  |  |
+| `version` | `integer \| null` | no | `null` |  |
+| `timestamp` | `string \| null` | no | `null` |  |
+| `copy_rows` | `boolean` | no | `true` | Copy the rows (default); false copies the definition only (CREATE TABLE LIKE). |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/comment_on.md

@@ -0,0 +1,42 @@
+# COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its
+
+`POST /datanotes/operations/comment_on/` (operation `comment_on`)
+
+COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its
+schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place.
+`description` "" removes it. An unknown catalog or schema is refused with the existing ones.
+describe_database and `system.information_schema.catalogs` / `schemata` show it. Undo with
+`undo_migration`. A table's description: alter_table.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `catalog` | `string` | yes |  |  |
+| `schema` | `string \| null` | no | `null` | A schema of the catalog; omitted, the description is the catalog's. |
+| `description` | `string` | yes |  | The new description; "" removes it. |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).