datanotes 2.0.0 → 3.0.0

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

@@ -0,0 +1,52 @@
+# Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database
+
+`POST /datanotes/operations/configure_database/` (operation `configure_database`)
+
+Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database
+folder; links follow; revert by renaming back), `default_catalog`, `default_schema`,
+`default_partition` ("" = flat) and `default_filename` (date formats for new time-based tables),
+`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`
+(transaction log for every table: true in a database the engine creates, false when
+`config` lacks it, as in a metastore from before 3.0.0; change it only on the user's request), `autolink` (the text a write
+puts in a body links the notes it mentions; on by default). Returns describe_database.
+Renaming `root` moves the folder (links to its notes are rewritten; the tables' archive and
+`exclude` folders inside it follow); the move is listed in the journal as `move_database` (undo
+and time travel read older entries with the new paths) and cannot be undone. Settings changes are
+not journaled (no `migration_id`, nothing for undo_migration): to revert, call it again with the
+previous values.
+
+The metastore changes only through operations: never edit metastore.yaml by hand (no validation).
+
+## 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`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `root` | `string \| null` | no | `null` |  |
+| `default_catalog` | `string \| null` | no | `null` |  |
+| `default_schema` | `string \| null` | no | `null` |  |
+| `default_partition` | `string \| null` | no | `null` |  |
+| `default_filename` | `string \| null` | no | `null` |  |
+| `archive_folder` | `string \| null` | no | `null` |  |
+| `timezone` | `string \| null` | no | `null` |  |
+| `history` | `boolean \| null` | no | `null` |  |
+| `autolink` | `boolean \| null` | no | `null` | Automatic links: the text a write puts in a note's body links the notes it mentions by name (on by default). A write's own `autolink` overrides it. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `DatabaseDescription` (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) |
+| 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/create_table.md

@@ -0,0 +1,78 @@
+# Create a table: `name`, in `catalog` and `schema` (default: the database's defaults); the definition
+
+`POST /datanotes/operations/create_table/` (operation `create_table`)
+
+Create a table: `name`, in `catalog` and `schema` (default: the database's defaults); the definition
+goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters,
+digits, `_` (no dots: pass the catalog and the schema as their own arguments).
+- `description` (required): what a row of the table records. Every column needs its own `description`
+  too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how
+  agents and people understand the schema, so write them for a reader who never saw the notes. The
+  engine writes those of `id` and of `identity` "uuid" / "created" columns.
+- `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true,
+  "description": "What kind of entry the row is"}`.
+  Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json.
+  Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in
+  order: filters/avg use the position), ref (link target, full `catalog.schema.table` or "self"),
+  unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`),
+  `identity` ("filename" | "created"), `vocabulary` (allowed values = names of another table's rows),
+  `hierarchy: true` (one parent link to its own table), `dense` (written on every row),
+  `inverse` on a link column: the column of the `ref` table that links back (`friends` ↔
+  `friends`, `children` ↔ `parents`, `partner` ↔ `partner`); writes keep both sides in step.
+- `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).
+- The table's options, as alter_table names them: `aliases` (how agents find it, with the
+  description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the
+  database's setting), `autolink_target` (true / false: may automatic links link its rows? default:
+  yes, unless its rows are named by a date or a time, as with `time_column`).
+- `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.
+- `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and
+  describe_table return them, alter_table 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 |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | yes |  |  |
+| `description` | `string \| null` | no | `null` | What a row of the table records (required: the table is refused without it, as without a column's own description). |
+| `columns` | `object[]` | yes |  |  |
+| `catalog` | `string \| null` | no | `null` |  |
+| `schema` | `string \| null` | no | `null` |  |
+| `time_column` | `string \| null` | no | `null` |  |
+| `filename` | `string \| null` | no | `null` | File name pattern of the rows, e.g. "{name}" (instead of time_column). |
+| `partition` | `string \| null` | no | `null` | Sub-folder pattern of the rows, e.g. "{occurred_at:YYYY/MM}"; "" = flat. |
+| `exclude` | `string[] \| null` | no | `null` | Folders whose notes are never rows of the table (e.g. templates that create them). |
+| `archive` | `string \| null` | no | `null` | Archive folder: a folder name inside the table folder (default: the database's archive_folder). |
+| `aliases` | `string[] \| null` | no | `null` | Other words for what the table records, for agents. |
+| `history` | `boolean \| null` | no | `null` | Keep the table's versions (time travel, restore); default: the database's setting. |
+| `autolink_target` | `boolean \| null` | no | `null` | May automatic links link the table's rows? Default: yes, unless its rows are named by a date or a time. |
+| `row_template` | `string \| null` | no | `null` | Markdown body of new rows; {column} placeholders are filled from the row. |
+| `fields` | `object \| null` | no | `null` | Untyped fields of the table (name → default), kept on every row; a field cannot share a name with a column. |
+| `tags` | `object \| null` | no | `null` | Key/value labels of the table (strings), e.g. {"domain": "health"}. |
+| `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`).

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

@@ -0,0 +1,54 @@
+# Create (or `replace`) a view: a named select stored in metastore.yaml. Name it with the prefix
+
+`POST /datanotes/operations/create_view/` (operation `create_view`)
+
+Create (or `replace`) a view: a named select stored in metastore.yaml. Name it with the prefix
+`vw_` (e.g. `vw_open_tasks`): views share names and folders with tables. `query` takes the
+select_rows parameters (table, columns, where, order_by, limit, join, group_by, aggregates, expand;
+relative dates keep it current) and must run now. Or `query: {union: [{table, columns, where}, …],
+columns, where, order_by, limit, expand}` stacks the rows of several tables (UNION ALL, each row
+tagged `_source`). Its filters may read the note the view is shown for: `{this.<property>}`
+(`{this.date+1d}`, `{this.date-1w}` shift a date), `{this.link}`, `{this.name}`, `{this.path}`,
+filled in from select_rows `this_note` (one view serves every daily note, every project note).
+`description` and `aliases` let agents find it; `labels` are column headings. Views are selected with
+`select_rows(table=<view>)`, which may narrow them further (where, columns, order_by, limit; a `where`
+operator the view already has on a column replaces it). A view writes no note: it lives only in
+metastore.yaml.
+
+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 |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | yes |  |  |
+| `query` | `object` | yes |  |  |
+| `catalog` | `string \| null` | no | `null` |  |
+| `schema` | `string \| null` | no | `null` |  |
+| `description` | `string \| null` | no | `null` | What the view shows, for agents and people. |
+| `aliases` | `string[] \| null` | no | `null` |  |
+| `labels` | `object \| null` | no | `null` |  |
+| `replace` | `boolean` | no | `false` |  |
+| `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`).

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

@@ -0,0 +1,37 @@
+# Push row changes to a URL (a service that would rather be called than poll `list_changes`): batches of up to 100 events POSTed as `{webhook, events, last}`, signed with `X-Datanotes-Signature: sha256=<HMAC of the body>`, retried with backoff until a 2xx. Events are those of `list_changes` (hand edits with their `violations`; the hand edits the service has seen are recorded before it stops). Starts from now unless `since`. Returns the webhook with its `secret` — shown only here: give it to the receiver. Only on the user's explicit request: a webhook sends the database's changes (and, with `since`, its past ones) to that address.
+
+`POST /datanotes/operations/create_webhook/` (operation `create_webhook`)
+
+Push row changes to a URL (a service that would rather be called than poll `list_changes`): batches of up to 100 events POSTed as `{webhook, events, last}`, signed with `X-Datanotes-Signature: sha256=<HMAC of the body>`, retried with backoff until a 2xx. Events are those of `list_changes` (hand edits with their `violations`; the hand edits the service has seen are recorded before it stops). Starts from now unless `since`. Returns the webhook with its `secret` — shown only here: give it to the receiver. Only on the user's explicit request: a webhook sends the database's changes (and, with `since`, its past ones) to that address.
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `url` | `string` | yes |  |  |
+| `tables` | `string[] \| null` | no | `null` |  |
+| `kinds` | `("insert" \| "update" \| "delete" \| "move" \| "metastore" \| "tool_call" \| "unreadable")[] \| null` | no | `null` |  |
+| `columns` | `string[] \| null` | no | `null` |  |
+| `exclude_actor` | `string \| null` | no | `null` |  |
+| `where` | `object \| null` | no | `null` |  |
+| `since` | `integer \| null` | no | `null` |  |
+
+## 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) |
+| 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/define_base.md

@@ -0,0 +1,52 @@
+# Create or replace a base: a named set of columns (same spec as `create_table`) that tables
+
+`POST /datanotes/operations/define_base/` (operation `define_base`)
+
+Create or replace a base: a named set of columns (same spec as `create_table`) that tables
+inherit, like a parent class (`bases` in `metastore.yaml`). Tables using it get the columns
+with the same name and meaning; `ref: "self"` means the inheriting table (e.g. a `parent`
+column with `hierarchy: true`). `bases` builds on other bases. Descriptions are required, as in
+create_table: `description` says what the tables of the base share, and each column has its `description`
+(a column given without one keeps the one the base had for it). Replacing a base changes
+every inheriting table: `rename_columns` (`{"old": "new"}`) renames the column on their rows,
+`drop_columns` removes it from their rows; dropping a column without listing it is refused.
+A renamed column is followed into the CHECKs and `ref_where` / `ref_by` that read it (the base's
+own included); dropping one they read is refused, naming them. All affected rows are validated
+before any write, inherited `ref_where` / `ref_by` and CHECKs that follow links included.
+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.
+
+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 |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | yes |  |  |
+| `columns` | `object[]` | yes |  |  |
+| `bases` | `string[] \| null` | no | `null` |  |
+| `description` | `string \| null` | no | `null` | What the tables of the base share (required, as a table's description is). |
+| `rename_columns` | `object \| null` | no | `null` |  |
+| `drop_columns` | `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) |
+| 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/delete_rows.md

@@ -0,0 +1,43 @@
+# Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive
+
+`POST /datanotes/operations/delete_rows/` (operation `delete_rows`)
+
+Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive
+folder) or "delete" (trash; content journaled for undo). `on_referenced`: "restrict"
+(default, refuse rows other notes link to), "set_null" (clear front matter links to them) or
+"ignore" (the links stay, to no row: an archived row is gone as a trashed one, so check_table
+reports them as `broken_link` and new links to it are refused). `where` is required: `{}` deletes every row.
+
+## 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 |  |  |
+| `where` | `object` | yes |  | The rows to change; {} is every row of the table. |
+| `mode` | `"archive" \| "delete" \| null` | no | `null` |  |
+| `on_referenced` | `"restrict" \| "set_null" \| "ignore" \| 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/delete_webhook.md

@@ -0,0 +1,31 @@
+# Stop and remove a webhook (by `id` from list_webhooks).
+
+`POST /datanotes/operations/delete_webhook/` (operation `delete_webhook`)
+
+Stop and remove a webhook (by `id` from list_webhooks).
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `id` | `string` | yes |  |  |
+
+## 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) |
+| 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/describe_database.md

@@ -0,0 +1,30 @@
+# Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely,
+
+`POST /datanotes/operations/describe_database/` (operation `describe_database`)
+
+Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely,
+but it is read-only for agents and changes only through the schema operations), configuration
+(default catalog and schema, row partition and file-name formats, archive folder, time zone,
+history, automatic links),
+journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows' front matter cannot be read) and `views`;
+catalogs and schemas show their `comment` (set with `comment_on`). A table or base defined before
+descriptions were required has `missing_descriptions`: what lacks one, for alter_table / alter_column
+(define_base for a base) to fill, so every table and column says what it holds.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `DatabaseDescription` (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) |
+| 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/describe_history.md

@@ -0,0 +1,40 @@
+# DESCRIBE HISTORY: the table's versions, newest first — `version`, `timestamp`, `operation`
+
+`POST /datanotes/operations/describe_history/` (operation `describe_history`)
+
+DESCRIBE HISTORY: the table's versions, newest first — `version`, `timestamp`, `operation`
+(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, …;
+`EXTERNAL_EDIT` = changed outside the engine: an editor, git, sync), `operation_metrics` and `migration_id` (undo).
+An EXTERNAL_EDIT's `operation_metrics.violations` counts the rules this table's rows break because of the hand edits it holds (each once): the edited rows whose front matter changed and the rows of the table linking to them, a removed or renamed row included (rows of other tables count in their table; a body-only edit is not checked); every rule its rows break when its definition was edited in metastore.yaml. Absent when nothing was checked, or when the edits were logged right before an engine write (the change feed has them); check_table lists the rows invalid now.
+Works for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`
+(time travel), `table_changes` or `restore_table`.
+Without `table`: the history of the whole database — the commits of every table with a log (dropped
+ones included), newest first, each with its `table` (the result's `tables` lists the logged tables).
+An operation that changed several tables (a cascade, inverse links, restore_database) commits to each
+with the same `migration_id`, and the operations of a `batch` carry its id as `batch`: their commits list
+in `tables` every table that operation (or batch) committed to. Pick a moment for `restore_database`
+from it (`timestamp`, or `before_migration` with a `migration_id` or a `batch`).
+`limit` (default 50) counts commits; `since` (ISO date or date-time): only commits at or after it.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string \| null` | no | `null` | A table; omitted, the whole database. |
+| `limit` | `integer \| null` | no | `null` |  |
+| `since` | `string \| null` | no | `null` |  |
+
+## 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/describe_semantic_index.md

@@ -0,0 +1,24 @@
+# The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`,
+
+`POST /datanotes/operations/describe_semantic_index/` (operation `describe_semantic_index`)
+
+The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`,
+`running`, `last_sync`, `last_error`. sync_semantic_index brings it up to date.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `SemanticStatus` (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) |
+| 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/describe_table.md

@@ -0,0 +1,38 @@
+# Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,
+
+`POST /datanotes/operations/describe_table/` (operation `describe_table`)
+
+Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,
+`catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern
+of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns`
+with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set:
+`tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `row_template`, `history`,
+`autolink_target`, `fields` (their values).
+
+Before adding a column (e.g. a new metric), read `columns` and match your concept against
+`name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.
+
+`missing_descriptions` (`{table, columns}`), present only when something has no description (a table
+defined before descriptions were required), names what lacks one: write them with alter_table
+`description` and alter_column `changes.description`, asking the user when the meaning is unclear.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+
+## 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/docs.md

@@ -0,0 +1,13 @@
+# This document in an interactive console (Swagger UI, served by the engine; public). Authorize with a token to try the routes.
+
+`GET /datanotes/docs` (operation `docs`)
+
+No authentication needed.
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | HTML page. | `string` (text/html) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

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

@@ -0,0 +1,41 @@
+# Remove a column from the schema and every row. Previous values are journaled; revert with
+
+`POST /datanotes/operations/drop_column/` (operation `drop_column`)
+
+Remove a column from the schema and every row. Previous values are journaled; revert with
+`undo_migration`. Refused while a CHECK, `ref_where` or `ref_by` of any table reads the column
+(directly or through a link): the conflicts name them; drop or change them first.
+
+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. |
+| `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/drop_constraint.md

@@ -0,0 +1,39 @@
+# Remove the CHECK constraint `name` from `table`.
+
+`POST /datanotes/operations/drop_constraint/` (operation `drop_constraint`)
+
+Remove the CHECK constraint `name` from `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 |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `name` | `string` | 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/drop_table.md

@@ -0,0 +1,43 @@
+# Drop a table. Refused while it has rows unless `mode: "archive"`, which removes the
+
+`POST /datanotes/operations/drop_table/` (operation `drop_table`)
+
+Drop a table. Refused while it has rows unless `mode: "archive"`, which removes the
+definition from `metastore.yaml` and moves all rows to the table's archive folder (nothing is
+hard-deleted; undo restores). The transaction log is kept: `restore_table` can bring it back.
+Refused while a CHECK that follows links, or a `ref_where` / `ref_by`, of another table reads this
+table through a link (link targets are not rewritten): the conflicts name them; drop or change them first.
+
+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 |  |  |
+| `mode` | `"archive" \| null` | no | `null` | "archive": drop a table that has rows, moving them to its archive folder. |
+| `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`).