datanotes 1.2.0 → 1.3.0

package/README.md

@@ -3,9 +3,9 @@
 The engine of your second brain: Markdown notes as database tables, for you and your AI agents.
 
 A row is any note whose `table` property names a table; tables are defined in
-`Database/database.yaml`. Every write is checked against its table, journaled and undoable. Agents
-programs use its HTTP API or the `datanotes/client` library, and agents use the separate MCP
-server `datanotes-mcp`.
+`Database/database.yaml`. Every write is checked against its table, journaled and undoable.
+Programs use its HTTP API or the `datanotes/client` library; agents use the separate MCP server
+`datanotes-mcp`.
 
 **Documentation: [datanotes.dev](https://datanotes.dev)**
 
@@ -17,7 +17,8 @@ Requires Node.js 20 or newer. Start the engine on a vault:
 npx -y datanotes serve --vault /path/to/vault
 ```
 
-It serves the HTTP API on `http://127.0.0.1:27150/datanotes/*`, with the owner's token in
+It serves the HTTP API on `http://127.0.0.1:27150` (routes under `/datanotes/*`, plus the
+Local-REST-API-style `/vault/*` and `/search/simple/`), with the owner's token in
 `<vault>/.datanotes/service.json`. From code:
 
 ```js

package/SECURITY.md

@@ -25,7 +25,7 @@ run on your own machine, for you and the agents you choose.
 | Credential | Where | What it can do |
 | --- | --- | --- |
 | Owner token | `httpServerToken` in the settings | Everything: data, schema, apps, webhooks, undo. Keep it on the machine. |
-| App token | created with `POST /datanotes/apps/create/` (owner only), stored hashed | Read everything; write only the tables in its `write` patterns; change the schema only with `ddl`. It cannot create webhooks, manage apps or undo; with `maintain` it may also undo, restore, vacuum and configure (an agent's own token). |
+| App token | created with `POST /datanotes/apps/create/` (owner only), stored hashed | Read everything; write only the tables in its `write` patterns; change the schema only with `ddl`. It cannot create webhooks, manage apps or undo; with `maintain` it may also undo, restore, vacuum, configure and rebuild the semantic index (an agent's own token). |
 
 Prefer an **app token per device or agent**: it has only the permissions it needs and the journal
 names it. MCP clients use the same tokens: the MCP server passes them to the engine.
@@ -44,8 +44,14 @@ followed: do not link to folders you would not give the engine.
 
 Nothing leaves the machine unless you turn it on:
 
-- **Semantic search** sends note text to the embedding provider you configure (`semanticProvider`,
-  off by default). A local provider (Ollama) keeps it on the machine.
-- **Telemetry** sends logs to the OTLP endpoint you configure (`telemetryEnabled`, off by default).
+- **Semantic search** sends note text to the embedding provider you configure (`semanticEnabled`,
+  off by default; provider `semanticProvider` / `semanticBaseUrl`). A local provider (Ollama,
+  LM Studio) keeps it on the machine.
+- **Telemetry** sends logs to the OTLP endpoint you configure (`telemetryEnabled`, off by default):
+  operations, routes, note paths, actors, tool names and error messages (which may quote a value),
+  not note bodies. `telemetryHeaders` (e.g. an
+  ingestion key) is stored in the settings file; `OTEL_EXPORTER_OTLP_HEADERS` keeps it out.
 - **Webhooks** (created by the owner) post change events to the URLs they name.
+- **Apps' MCP endpoints** (registered by the owner): the engine sends each app's `mcp_token`, and
+  the arguments and caller of every call of its tools, to the app's `mcp_url`, which may be remote.
 - **Git sync** (`--git-sync`) pushes the vault to its git remote.

package/dist/api/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   DatanotesError: () => DatanotesError,
   OPERATIONS: () => OPERATIONS,
   OperationInputError: () => OperationInputError,
+  OtlpLogExporter: () => OtlpLogExporter,
   ROUTE_PREFIX: () => ROUTE_PREFIX,
   describeBatch: () => describeBatch,
   describeRefusal: () => describeRefusal,
@@ -33,6 +34,8 @@ __export(index_exports, {
   fetchTransport: () => fetchTransport,
   operationRequest: () => operationRequest,
   operationRoute: () => operationRoute,
+  otlpFromEnv: () => otlpFromEnv,
+  parseOtlpHeaders: () => parseOtlpHeaders,
   resultOf: () => resultOf
 });
 module.exports = __toCommonJS(index_exports);
@@ -41,7 +44,7 @@ module.exports = __toCommonJS(index_exports);
 var OPERATIONS = [
   {
     "name": "read_note",
-    "description": "Read a vault file (``GET /vault/{filename}``).\n\nDefault response is raw markdown. With ``as_json`` true, requests ``Accept: application/vnd.olrapi.note+json`` and returns ``NoteJson``: ``content``, ``frontmatter``, ``tags``, ``path``, and ``stat`` (file times and size), per the plugin OpenAPI schema.\n\nInputs:\n- ``path``: Vault-relative path to the file (forward slashes).\n- ``as_json``: If false (default), return markdown. If true, return ``NoteJson``.\n\nReturns:\n- ``str`` \u2014 markdown body, or\n- ``dict[str, Any]`` \u2014 parsed ``NoteJson`` when ``as_json`` is true.",
+    "description": "Read a vault file (`GET /vault/{path}`). Default: the raw markdown. With `as_json`:\n`{content, frontmatter, tags, path, stat}` (`tags` without `#`, from the text and the\nfrontmatter; `stat`: `{ctime, mtime, size}` or null). A missing file is an error.\n`path`: vault-relative, forward slashes.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -68,7 +71,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_directory",
-    "description": 'List files under a vault directory (``GET /vault/`` or ``GET /vault/{pathToDirectory}/``).\n\nResponse JSON includes a ``files`` array. Names ending with ``/`` are subdirectories. Empty directories may not appear in listings (per API). Use ``""`` for the vault root.\n\nInputs:\n- ``path``: Vault-relative directory path; use ``""`` for the vault root.\n\nReturns:\n- ``dict[str, Any]`` \u2014 parsed JSON listing from the API.',
+    "description": 'Direct children of a vault folder (`GET /vault/{folder}/`): `{files: [...]}`. Folders end with\n`/`, names are sorted, dot-files are hidden. `""` is the vault root. A missing folder is an\nerror.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -89,7 +92,7 @@ var OPERATIONS = [
   },
   {
     "name": "search_simple",
-    "description": "Full-text search (``POST /search/simple/``).\n\nUses Obsidian\u2019s native search syntax (keywords, ``path:``, ``tag:``, ``file:``, etc.). Results include filenames, match positions, context snippets, and scores per the plugin OpenAPI.\n\nInputs:\n- ``query``: Obsidian search expression.\n- ``context_length``: Max characters of context around each match (default 100).\n\nReturns:\n- Parsed JSON from the API (matches per file, context, score).",
+    "description": "Plain-text search (`POST /search/simple/`): every word of `query` must occur, case- and\naccent-insensitive, in the note's path or text; there are no operators. Returns up to 200\nfiles, best first: `[{filename, score, matches: [{match: {start, end}, context}]}]`, at most 20\nmatches per file. `context_length`: characters of context on each side (default 100, max 1000).",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -116,7 +119,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_tables",
-    "description": "List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` \u2014 use it\nwherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and,\nwhen declared, `description` and `aliases` (other words for what it records). Tables are\ndefined in `database.yaml` (catalog \u2192 schema \u2192 table); legacy schema-note tables have no\n`catalog` and a two-part `qualified` name. `views` lists the stored views (same fields, no\npath): select them like tables. `system.information_schema` is read with `select_rows`.\n\nCall this first to find the table for what the user reports (match their words against\nname, description and aliases), and before creating tables or columns so you reuse existing\nones instead of creating duplicates.",
+    "description": "List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` \u2014 use it\nwherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and,\nwhen declared, `description` and `aliases` (other words for what it records). Tables are\ndefined in `database.yaml` (catalog \u2192 schema \u2192 table). Returns `{tables, views}`: `views` lists the stored views (same fields, no\npath): select them like tables. `system.information_schema` is read with `select_rows`.\n\nCall this first to find the table for what the user reports (match their words against\nname, description and aliases), and before creating tables or columns so you reuse existing\nones instead of creating duplicates.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {},
@@ -236,7 +239,8 @@ var OPERATIONS = [
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Untyped fields of the table (name \u2192 default), kept on every row; a field cannot share a name with a column."
         },
         "body": {
           "anyOf": [
@@ -344,7 +348,7 @@ var OPERATIONS = [
   },
   {
     "name": "rename_column",
-    "description": "Rename a column on the schema and every row, and rewrite the references to it in notes.\nAlso the way to merge a duplicate column into an existing compatible one. Refused (nothing\nwritten) if any row has both columns with different values.",
+    "description": "Rename a column in database.yaml and on every row. Refused if `to_column` is already a column\nof the table; a row that has a stray `to_column` key with a different value is a conflict, and\nnothing is written. Views and note text that mention the old name are not rewritten.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -715,7 +719,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_database",
-    "description": "Describe the database: its folder (`root`), `metastore` (`database.yaml`), configuration\n(default catalog and schema, row partition and file-name formats, archive folder, time zone),\njournal folder, `bases` (shared column sets and the tables using them), `catalogs` \u2192 schemas \u2192 tables (row counts) and views, legacy schema-note\ntables (`schemas`) and tables outside the database (`outside`).",
+    "description": "Describe the database: its folder (`root`), `metastore` (`database.yaml`), configuration\n(default catalog and schema, row partition and file-name formats, archive folder, time zone),\njournal folder, `bases` (shared column sets and the tables using them), `catalogs` \u2192 `schemas` \u2192 `tables` (with `rows` counts) and `views`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {},
@@ -731,7 +735,7 @@ var OPERATIONS = [
   },
   {
     "name": "configure_database",
-    "description": 'Configure the database (persisted in database.yaml `config:`): `root` (rename the database\nfolder; links follow; revert by renaming back), `default_catalog`, `default_schema`,\n`default_partition` ("" = flat) and `filename` (date formats for new time-based tables),\n`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`\n(transaction log for every table \u2014 only on the user\'s request). Returns describe_database;\nafter a root rename also `rewritten` and `mentions` (show them to the user).',
+    "description": 'Configure the database (persisted in database.yaml `config:`): `root` (rename the database\nfolder; links follow; revert by renaming back), `default_catalog`, `default_schema`,\n`default_partition` ("" = flat) and `filename` (date formats for new time-based tables),\n`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`\n(transaction log for every table \u2014 only on the user\'s request). Returns describe_database.\nRenaming `root` moves the folder (links to its notes are rewritten); it is not journaled: to\nrevert, call it again with the old value.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -906,7 +910,8 @@ var OPERATIONS = [
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Optional note path (vault-relative), instead of the table's file-name pattern; `.md` is added if missing; it must stay inside the vault."
         },
         "dry_run": {
           "default": false,
@@ -1144,7 +1149,7 @@ var OPERATIONS = [
       "title": "Update Row",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -1298,7 +1303,7 @@ var OPERATIONS = [
   },
   {
     "name": "adopt_rows",
-    "description": 'Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and\nlinks: `rename` keys (`{"data": "occurred_at"}`), `set_values` for all, `per_row` values by\nnote path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.\nEvery note gets `table` and a system `id`; with `relocate` (default) it moves to the table\'s\nfolder, named by its filename pattern (Obsidian updates links). All notes are validated first:\nunknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo\nwith `undo_migration`.',
+    "description": 'Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and\nlinks: `rename` keys (`{"data": "occurred_at"}`), `set_values` for all, `per_row` values by\nnote path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.\nEvery note gets `table` and a system `id`; with `relocate` (default) it moves to the table\'s\nfolder, named by its filename pattern (links to it are rewritten). All notes are validated first:\nunknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo\nwith `undo_migration`.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1601,7 +1606,7 @@ var OPERATIONS = [
     "annotations": {
       "title": "Undo Migration",
       "readOnlyHint": false,
-      "destructiveHint": false,
+      "destructiveHint": true,
       "idempotentHint": false,
       "openWorldHint": false
     }
@@ -1766,7 +1771,7 @@ var OPERATIONS = [
   },
   {
     "name": "semantic_search",
-    "description": 'Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,\ntable?}]}`, one result per note (its best passage), best first. Use it for vague questions\n("the dinner where we talked about moving", "what did I decide about the car") and to find the\nrows to read or update; then read_note / select_rows for the details. Filters: `tables`\n(qualified or short names), `folder`, `min_score` (cosine 0\u20131; ~0.5+ is usually relevant).\nFails with a clear message when semantic search is off in the plugin settings.',
+    "description": 'Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,\ntable?}]}`, one result per note (its best passage), best first. Use it for vague questions\n("the dinner where we talked about moving", "what did I decide about the car") and to find the\nrows to read or update; then read_note / select_rows for the details. Filters: `tables`\n(qualified or short names), `folder`, `min_score` (cosine 0\u20131; ~0.5+ is usually relevant).\n`limit`: default 10, max 100. Fails with a clear message when semantic search is not enabled in\nthe engine settings.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1829,7 +1834,7 @@ var OPERATIONS = [
   },
   {
     "name": "semantic_index",
-    "description": "Semantic search index: `status` (provider, model, notes, passages, last error), `update`\n(embed notes changed since the last run; the plugin also does it on its own a few seconds after\nedits) or `rebuild` (re-embed everything: slow, and costs money with a paid provider \u2014 ask\nfirst).",
+    "description": "Semantic search index: `status` (`enabled`, `provider`, `model`, `files`, `passages`, `pending`,\n`running`, `lastSync`, `lastError`), `update` (embed notes changed since the last run; the\nengine also does it on its own about ten seconds after edits) or `rebuild` (re-embed\neverything: slow, and costs money with a paid provider \u2014 ask first).",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1975,7 +1980,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_history",
-    "description": "DESCRIBE HISTORY: the table's versions, newest first \u2014 `version`, `timestamp`, `operation`\n(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, \u2026;\n`EXTERNAL_EDIT` = changed by hand in Obsidian), `operationMetrics` and `migrationId` (undo).\nWorks for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`\n(time travel), `table_changes` or `restore_table`.",
+    "description": "DESCRIBE HISTORY: the table's versions, newest first \u2014 `version`, `timestamp`, `operation`\n(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, \u2026;\n`EXTERNAL_EDIT` = changed outside the engine: an editor, git, sync), `operationMetrics` and `migrationId` (undo).\nWorks for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`\n(time travel), `table_changes` or `restore_table`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2047,7 +2052,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_changes",
-    "description": "Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes\nand from hand edits (`source: external`). Each has `table`, `op` (insert, update, delete, move,\nschema), `path`, `changes` ({column: {before, after}}), `actor`, `migration`. MCP tool calls are `op: tool_call` events (`call`: tool, args, ok, value, servedBy), returned only when `ops` includes tool_call. Pass the returned\n`last` as `since` next time (`head` is the newest number); `wait_ms` waits for a new change (long poll). `gap: true` means\nolder changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.",
+    "description": "Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes\nand from hand edits (`source: external`). Each has `table`, `op` (insert, update, delete, move,\nschema), `path`, `changes` ({column: {before, after}}), `actor`, `migration`. Agents' tool calls (reported by MCP servers) are `op: tool_call` events (`call`: tool, args, ok, value, servedBy), returned only when `ops` includes tool_call. Pass the returned\n`last` as `since` next time (`head` is the newest number); `wait_ms` (max 60000) waits for a new change (long poll); `limit` max 5000. `gap: true` means\nolder changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2573,7 +2578,7 @@ var OPERATIONS = [
   },
   {
     "name": "clone_table",
-    "description": "CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows\n(deep clone), optionally as of a `version` / `timestamp`. `shallow=true` copies the\ndefinition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (default\ncatalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy\nin the `agent` catalog.",
+    "description": "CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows\n(deep clone), optionally as of a `version` / `timestamp`. `shallow=true` copies the\ndefinition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (in the\nsource's catalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy\nin the `agent` catalog.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2630,7 +2635,7 @@ var OPERATIONS = [
   },
   {
     "name": "recompute_columns",
-    "description": "Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after\nrows were edited outside the plugin or a generated expression changed with `alter_column`.\nAlso gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)\na new id. `new_ids=true` regenerates every id in scope: only on the user's explicit request.\n`check_table` reports stale values with code `generated`. No-op when nothing is stale;\notherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.",
+    "description": "Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after\nrows were edited by hand (an editor, git, sync) or a generated expression changed with `alter_column`.\nAlso gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)\na new id. `new_ids=true` regenerates every id in scope (new ones on every call): only on the user's\nexplicit request.\n`check_table` reports stale values with code `generated`. No-op when nothing is stale;\notherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2669,7 +2674,7 @@ var OPERATIONS = [
       "title": "Recompute Columns",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -2834,7 +2839,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_path",
-    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
+    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2972,7 +2977,8 @@ var ROUTES = {
   create_webhook: (a) => ["/webhooks/create/", pick(a, ["url", "tables", "ops", "columns", "exclude_actor", "where", "since"])],
   delete_webhook: (a) => ["/webhooks/delete/", pick(a, ["id"])],
   restore_table: (a) => ["/history/restore/", { ...pick(a, ["table", "version", "timestamp"]), ...dry(a) }],
-  vacuum_table: (a) => ["/history/vacuum/", { ...pick(a, ["table", "retain_from_version"]), ...dry(a) }],
+  // vacuum deletes history for good: a dry run unless the caller says `dry_run: false`
+  vacuum_table: (a) => ["/history/vacuum/", { ...pick(a, ["table", "retain_from_version"]), dry_run: a.dry_run !== false }],
   graph_neighbors: (a) => ["/graph/neighbors/", compact({ from: a.from_nodes, direction: a.direction, edges: a.edges })],
   graph_traverse: (a) => [
     "/graph/traverse/",
@@ -3059,6 +3065,110 @@ function estimateTokens(text) {
   return n;
 }
 
+// src/api/otlp.ts
+var SEVERITY_NUMBER = { DEBUG: 5, INFO: 9, WARN: 13, ERROR: 17 };
+function attr(key, v) {
+  if (v === void 0 || v === null) return null;
+  if (typeof v === "boolean") return { key, value: { boolValue: v } };
+  if (typeof v === "number") return Number.isInteger(v) ? { key, value: { intValue: String(v) } } : { key, value: { doubleValue: v } };
+  return { key, value: { stringValue: v } };
+}
+var attrs = (a) => Object.entries(a).map(([k, v]) => attr(k, v)).filter((x) => x !== null);
+var fetchSend = async (url, body, headers) => {
+  const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", ...headers }, body });
+  if (!res.ok) throw new Error(`OTLP HTTP ${res.status}`);
+};
+var OtlpLogExporter = class {
+  constructor(o) {
+    this.o = o;
+    this.buffer = [];
+    this.inflight = Promise.resolve();
+    this.timer = null;
+    /** Records sent, and records lost because the collector did not take them. */
+    this.sent = 0;
+    this.dropped = 0;
+    const every = o.flushMs ?? 5e3;
+    if (every > 0) {
+      this.timer = setInterval(() => void this.flush(), every);
+      this.timer.unref?.();
+    }
+  }
+  log(severity, body, attributes = {}) {
+    const ms = (this.o.now ?? Date.now)();
+    this.buffer.push({ timeUnixNano: `${Math.round(ms)}000000`, severity, body, attributes });
+    if (this.buffer.length >= (this.o.maxBatch ?? 50)) void this.flush();
+  }
+  /** Send what is buffered. Never rejects. */
+  flush() {
+    if (this.buffer.length === 0) return this.inflight;
+    const batch = this.buffer;
+    this.buffer = [];
+    const body = JSON.stringify({
+      resourceLogs: [
+        {
+          resource: { attributes: attrs({ "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource }) },
+          scopeLogs: [
+            {
+              scope: { name: this.o.serviceName },
+              logRecords: batch.map((r) => ({
+                timeUnixNano: r.timeUnixNano,
+                observedTimeUnixNano: r.timeUnixNano,
+                severityNumber: SEVERITY_NUMBER[r.severity],
+                severityText: r.severity,
+                body: { stringValue: r.body },
+                attributes: attrs(r.attributes)
+              }))
+            }
+          ]
+        }
+      ]
+    });
+    const url = `${this.o.endpoint.replace(/\/+$/, "")}/v1/logs`;
+    const send = this.o.send ?? fetchSend;
+    this.inflight = this.inflight.then(
+      () => send(url, body, this.o.headers ?? {}).then(
+        () => void (this.sent += batch.length),
+        () => void (this.dropped += batch.length)
+      )
+    );
+    return this.inflight;
+  }
+  /** Stop the timer and send what is left. */
+  async close() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    await this.flush();
+  }
+};
+function parseOtlpHeaders(text) {
+  const out = {};
+  for (const part of (text ?? "").split(",")) {
+    const i = part.indexOf("=");
+    if (i <= 0) continue;
+    const key = part.slice(0, i).trim();
+    const value = part.slice(i + 1).trim();
+    if (!key) continue;
+    try {
+      out[key] = decodeURIComponent(value);
+    } catch {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function otlpFromEnv(env, defaults) {
+  const logs = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT?.trim();
+  const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+  const endpoint = logs ? logs.replace(/\/v1\/logs\/?$/, "") : base;
+  if (!endpoint) return null;
+  return {
+    endpoint,
+    serviceName: env.OTEL_SERVICE_NAME?.trim() || defaults.serviceName,
+    ...defaults.serviceVersion ? { serviceVersion: defaults.serviceVersion } : {},
+    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_LOGS_HEADERS) }
+  };
+}
+
 // src/api/client.ts
 var ACTOR_HEADER = "X-Datanotes-Actor";
 var DatanotesError = class extends Error {

package/dist/api/index.d.ts

@@ -6,4 +6,5 @@ export { OPERATIONS, type OperationDef } from "./catalog";
 export { operationRequest, operationRoute, CALLABLE_OPERATIONS, OperationInputError, ROUTE_PREFIX, type OperationRequest } from "./requests";
 export { resultOf, describeRefusal, describeBatch, type OperationResult } from "./results";
 export { estimateTokens } from "./tokens";
+export { OtlpLogExporter, otlpFromEnv, parseOtlpHeaders, type OtlpOptions, type Severity, type AttrValue } from "./otlp";
 export { DatanotesClient, DatanotesError, fetchTransport, ACTOR_HEADER, type ActorInfo, type AppTool, type ClientOptions, type HttpRequest, type HttpResponse, type ToolCallRecord, type Transport, } from "./client";

package/dist/api/index.js

@@ -2,7 +2,7 @@
 var OPERATIONS = [
   {
     "name": "read_note",
-    "description": "Read a vault file (``GET /vault/{filename}``).\n\nDefault response is raw markdown. With ``as_json`` true, requests ``Accept: application/vnd.olrapi.note+json`` and returns ``NoteJson``: ``content``, ``frontmatter``, ``tags``, ``path``, and ``stat`` (file times and size), per the plugin OpenAPI schema.\n\nInputs:\n- ``path``: Vault-relative path to the file (forward slashes).\n- ``as_json``: If false (default), return markdown. If true, return ``NoteJson``.\n\nReturns:\n- ``str`` \u2014 markdown body, or\n- ``dict[str, Any]`` \u2014 parsed ``NoteJson`` when ``as_json`` is true.",
+    "description": "Read a vault file (`GET /vault/{path}`). Default: the raw markdown. With `as_json`:\n`{content, frontmatter, tags, path, stat}` (`tags` without `#`, from the text and the\nfrontmatter; `stat`: `{ctime, mtime, size}` or null). A missing file is an error.\n`path`: vault-relative, forward slashes.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -29,7 +29,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_directory",
-    "description": 'List files under a vault directory (``GET /vault/`` or ``GET /vault/{pathToDirectory}/``).\n\nResponse JSON includes a ``files`` array. Names ending with ``/`` are subdirectories. Empty directories may not appear in listings (per API). Use ``""`` for the vault root.\n\nInputs:\n- ``path``: Vault-relative directory path; use ``""`` for the vault root.\n\nReturns:\n- ``dict[str, Any]`` \u2014 parsed JSON listing from the API.',
+    "description": 'Direct children of a vault folder (`GET /vault/{folder}/`): `{files: [...]}`. Folders end with\n`/`, names are sorted, dot-files are hidden. `""` is the vault root. A missing folder is an\nerror.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -50,7 +50,7 @@ var OPERATIONS = [
   },
   {
     "name": "search_simple",
-    "description": "Full-text search (``POST /search/simple/``).\n\nUses Obsidian\u2019s native search syntax (keywords, ``path:``, ``tag:``, ``file:``, etc.). Results include filenames, match positions, context snippets, and scores per the plugin OpenAPI.\n\nInputs:\n- ``query``: Obsidian search expression.\n- ``context_length``: Max characters of context around each match (default 100).\n\nReturns:\n- Parsed JSON from the API (matches per file, context, score).",
+    "description": "Plain-text search (`POST /search/simple/`): every word of `query` must occur, case- and\naccent-insensitive, in the note's path or text; there are no operators. Returns up to 200\nfiles, best first: `[{filename, score, matches: [{match: {start, end}, context}]}]`, at most 20\nmatches per file. `context_length`: characters of context on each side (default 100, max 1000).",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -77,7 +77,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_tables",
-    "description": "List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` \u2014 use it\nwherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and,\nwhen declared, `description` and `aliases` (other words for what it records). Tables are\ndefined in `database.yaml` (catalog \u2192 schema \u2192 table); legacy schema-note tables have no\n`catalog` and a two-part `qualified` name. `views` lists the stored views (same fields, no\npath): select them like tables. `system.information_schema` is read with `select_rows`.\n\nCall this first to find the table for what the user reports (match their words against\nname, description and aliases), and before creating tables or columns so you reuse existing\nones instead of creating duplicates.",
+    "description": "List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` \u2014 use it\nwherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and,\nwhen declared, `description` and `aliases` (other words for what it records). Tables are\ndefined in `database.yaml` (catalog \u2192 schema \u2192 table). Returns `{tables, views}`: `views` lists the stored views (same fields, no\npath): select them like tables. `system.information_schema` is read with `select_rows`.\n\nCall this first to find the table for what the user reports (match their words against\nname, description and aliases), and before creating tables or columns so you reuse existing\nones instead of creating duplicates.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {},
@@ -197,7 +197,8 @@ var OPERATIONS = [
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Untyped fields of the table (name \u2192 default), kept on every row; a field cannot share a name with a column."
         },
         "body": {
           "anyOf": [
@@ -305,7 +306,7 @@ var OPERATIONS = [
   },
   {
     "name": "rename_column",
-    "description": "Rename a column on the schema and every row, and rewrite the references to it in notes.\nAlso the way to merge a duplicate column into an existing compatible one. Refused (nothing\nwritten) if any row has both columns with different values.",
+    "description": "Rename a column in database.yaml and on every row. Refused if `to_column` is already a column\nof the table; a row that has a stray `to_column` key with a different value is a conflict, and\nnothing is written. Views and note text that mention the old name are not rewritten.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -676,7 +677,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_database",
-    "description": "Describe the database: its folder (`root`), `metastore` (`database.yaml`), configuration\n(default catalog and schema, row partition and file-name formats, archive folder, time zone),\njournal folder, `bases` (shared column sets and the tables using them), `catalogs` \u2192 schemas \u2192 tables (row counts) and views, legacy schema-note\ntables (`schemas`) and tables outside the database (`outside`).",
+    "description": "Describe the database: its folder (`root`), `metastore` (`database.yaml`), configuration\n(default catalog and schema, row partition and file-name formats, archive folder, time zone),\njournal folder, `bases` (shared column sets and the tables using them), `catalogs` \u2192 `schemas` \u2192 `tables` (with `rows` counts) and `views`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {},
@@ -692,7 +693,7 @@ var OPERATIONS = [
   },
   {
     "name": "configure_database",
-    "description": 'Configure the database (persisted in database.yaml `config:`): `root` (rename the database\nfolder; links follow; revert by renaming back), `default_catalog`, `default_schema`,\n`default_partition` ("" = flat) and `filename` (date formats for new time-based tables),\n`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`\n(transaction log for every table \u2014 only on the user\'s request). Returns describe_database;\nafter a root rename also `rewritten` and `mentions` (show them to the user).',
+    "description": 'Configure the database (persisted in database.yaml `config:`): `root` (rename the database\nfolder; links follow; revert by renaming back), `default_catalog`, `default_schema`,\n`default_partition` ("" = flat) and `filename` (date formats for new time-based tables),\n`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`\n(transaction log for every table \u2014 only on the user\'s request). Returns describe_database.\nRenaming `root` moves the folder (links to its notes are rewritten); it is not journaled: to\nrevert, call it again with the old value.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -867,7 +868,8 @@ var OPERATIONS = [
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Optional note path (vault-relative), instead of the table's file-name pattern; `.md` is added if missing; it must stay inside the vault."
         },
         "dry_run": {
           "default": false,
@@ -1105,7 +1107,7 @@ var OPERATIONS = [
       "title": "Update Row",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -1259,7 +1261,7 @@ var OPERATIONS = [
   },
   {
     "name": "adopt_rows",
-    "description": 'Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and\nlinks: `rename` keys (`{"data": "occurred_at"}`), `set_values` for all, `per_row` values by\nnote path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.\nEvery note gets `table` and a system `id`; with `relocate` (default) it moves to the table\'s\nfolder, named by its filename pattern (Obsidian updates links). All notes are validated first:\nunknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo\nwith `undo_migration`.',
+    "description": 'Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and\nlinks: `rename` keys (`{"data": "occurred_at"}`), `set_values` for all, `per_row` values by\nnote path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.\nEvery note gets `table` and a system `id`; with `relocate` (default) it moves to the table\'s\nfolder, named by its filename pattern (links to it are rewritten). All notes are validated first:\nunknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo\nwith `undo_migration`.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1562,7 +1564,7 @@ var OPERATIONS = [
     "annotations": {
       "title": "Undo Migration",
       "readOnlyHint": false,
-      "destructiveHint": false,
+      "destructiveHint": true,
       "idempotentHint": false,
       "openWorldHint": false
     }
@@ -1727,7 +1729,7 @@ var OPERATIONS = [
   },
   {
     "name": "semantic_search",
-    "description": 'Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,\ntable?}]}`, one result per note (its best passage), best first. Use it for vague questions\n("the dinner where we talked about moving", "what did I decide about the car") and to find the\nrows to read or update; then read_note / select_rows for the details. Filters: `tables`\n(qualified or short names), `folder`, `min_score` (cosine 0\u20131; ~0.5+ is usually relevant).\nFails with a clear message when semantic search is off in the plugin settings.',
+    "description": 'Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,\ntable?}]}`, one result per note (its best passage), best first. Use it for vague questions\n("the dinner where we talked about moving", "what did I decide about the car") and to find the\nrows to read or update; then read_note / select_rows for the details. Filters: `tables`\n(qualified or short names), `folder`, `min_score` (cosine 0\u20131; ~0.5+ is usually relevant).\n`limit`: default 10, max 100. Fails with a clear message when semantic search is not enabled in\nthe engine settings.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1790,7 +1792,7 @@ var OPERATIONS = [
   },
   {
     "name": "semantic_index",
-    "description": "Semantic search index: `status` (provider, model, notes, passages, last error), `update`\n(embed notes changed since the last run; the plugin also does it on its own a few seconds after\nedits) or `rebuild` (re-embed everything: slow, and costs money with a paid provider \u2014 ask\nfirst).",
+    "description": "Semantic search index: `status` (`enabled`, `provider`, `model`, `files`, `passages`, `pending`,\n`running`, `lastSync`, `lastError`), `update` (embed notes changed since the last run; the\nengine also does it on its own about ten seconds after edits) or `rebuild` (re-embed\neverything: slow, and costs money with a paid provider \u2014 ask first).",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1936,7 +1938,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_history",
-    "description": "DESCRIBE HISTORY: the table's versions, newest first \u2014 `version`, `timestamp`, `operation`\n(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, \u2026;\n`EXTERNAL_EDIT` = changed by hand in Obsidian), `operationMetrics` and `migrationId` (undo).\nWorks for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`\n(time travel), `table_changes` or `restore_table`.",
+    "description": "DESCRIBE HISTORY: the table's versions, newest first \u2014 `version`, `timestamp`, `operation`\n(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, \u2026;\n`EXTERNAL_EDIT` = changed outside the engine: an editor, git, sync), `operationMetrics` and `migrationId` (undo).\nWorks for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`\n(time travel), `table_changes` or `restore_table`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2008,7 +2010,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_changes",
-    "description": "Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes\nand from hand edits (`source: external`). Each has `table`, `op` (insert, update, delete, move,\nschema), `path`, `changes` ({column: {before, after}}), `actor`, `migration`. MCP tool calls are `op: tool_call` events (`call`: tool, args, ok, value, servedBy), returned only when `ops` includes tool_call. Pass the returned\n`last` as `since` next time (`head` is the newest number); `wait_ms` waits for a new change (long poll). `gap: true` means\nolder changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.",
+    "description": "Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes\nand from hand edits (`source: external`). Each has `table`, `op` (insert, update, delete, move,\nschema), `path`, `changes` ({column: {before, after}}), `actor`, `migration`. Agents' tool calls (reported by MCP servers) are `op: tool_call` events (`call`: tool, args, ok, value, servedBy), returned only when `ops` includes tool_call. Pass the returned\n`last` as `since` next time (`head` is the newest number); `wait_ms` (max 60000) waits for a new change (long poll); `limit` max 5000. `gap: true` means\nolder changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2534,7 +2536,7 @@ var OPERATIONS = [
   },
   {
     "name": "clone_table",
-    "description": "CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows\n(deep clone), optionally as of a `version` / `timestamp`. `shallow=true` copies the\ndefinition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (default\ncatalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy\nin the `agent` catalog.",
+    "description": "CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows\n(deep clone), optionally as of a `version` / `timestamp`. `shallow=true` copies the\ndefinition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (in the\nsource's catalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy\nin the `agent` catalog.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2591,7 +2593,7 @@ var OPERATIONS = [
   },
   {
     "name": "recompute_columns",
-    "description": "Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after\nrows were edited outside the plugin or a generated expression changed with `alter_column`.\nAlso gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)\na new id. `new_ids=true` regenerates every id in scope: only on the user's explicit request.\n`check_table` reports stale values with code `generated`. No-op when nothing is stale;\notherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.",
+    "description": "Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after\nrows were edited by hand (an editor, git, sync) or a generated expression changed with `alter_column`.\nAlso gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)\na new id. `new_ids=true` regenerates every id in scope (new ones on every call): only on the user's\nexplicit request.\n`check_table` reports stale values with code `generated`. No-op when nothing is stale;\notherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2630,7 +2632,7 @@ var OPERATIONS = [
       "title": "Recompute Columns",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -2795,7 +2797,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_path",
-    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
+    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2933,7 +2935,8 @@ var ROUTES = {
   create_webhook: (a) => ["/webhooks/create/", pick(a, ["url", "tables", "ops", "columns", "exclude_actor", "where", "since"])],
   delete_webhook: (a) => ["/webhooks/delete/", pick(a, ["id"])],
   restore_table: (a) => ["/history/restore/", { ...pick(a, ["table", "version", "timestamp"]), ...dry(a) }],
-  vacuum_table: (a) => ["/history/vacuum/", { ...pick(a, ["table", "retain_from_version"]), ...dry(a) }],
+  // vacuum deletes history for good: a dry run unless the caller says `dry_run: false`
+  vacuum_table: (a) => ["/history/vacuum/", { ...pick(a, ["table", "retain_from_version"]), dry_run: a.dry_run !== false }],
   graph_neighbors: (a) => ["/graph/neighbors/", compact({ from: a.from_nodes, direction: a.direction, edges: a.edges })],
   graph_traverse: (a) => [
     "/graph/traverse/",
@@ -3020,6 +3023,110 @@ function estimateTokens(text) {
   return n;
 }
 
+// src/api/otlp.ts
+var SEVERITY_NUMBER = { DEBUG: 5, INFO: 9, WARN: 13, ERROR: 17 };
+function attr(key, v) {
+  if (v === void 0 || v === null) return null;
+  if (typeof v === "boolean") return { key, value: { boolValue: v } };
+  if (typeof v === "number") return Number.isInteger(v) ? { key, value: { intValue: String(v) } } : { key, value: { doubleValue: v } };
+  return { key, value: { stringValue: v } };
+}
+var attrs = (a) => Object.entries(a).map(([k, v]) => attr(k, v)).filter((x) => x !== null);
+var fetchSend = async (url, body, headers) => {
+  const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", ...headers }, body });
+  if (!res.ok) throw new Error(`OTLP HTTP ${res.status}`);
+};
+var OtlpLogExporter = class {
+  constructor(o) {
+    this.o = o;
+    this.buffer = [];
+    this.inflight = Promise.resolve();
+    this.timer = null;
+    /** Records sent, and records lost because the collector did not take them. */
+    this.sent = 0;
+    this.dropped = 0;
+    const every = o.flushMs ?? 5e3;
+    if (every > 0) {
+      this.timer = setInterval(() => void this.flush(), every);
+      this.timer.unref?.();
+    }
+  }
+  log(severity, body, attributes = {}) {
+    const ms = (this.o.now ?? Date.now)();
+    this.buffer.push({ timeUnixNano: `${Math.round(ms)}000000`, severity, body, attributes });
+    if (this.buffer.length >= (this.o.maxBatch ?? 50)) void this.flush();
+  }
+  /** Send what is buffered. Never rejects. */
+  flush() {
+    if (this.buffer.length === 0) return this.inflight;
+    const batch = this.buffer;
+    this.buffer = [];
+    const body = JSON.stringify({
+      resourceLogs: [
+        {
+          resource: { attributes: attrs({ "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource }) },
+          scopeLogs: [
+            {
+              scope: { name: this.o.serviceName },
+              logRecords: batch.map((r) => ({
+                timeUnixNano: r.timeUnixNano,
+                observedTimeUnixNano: r.timeUnixNano,
+                severityNumber: SEVERITY_NUMBER[r.severity],
+                severityText: r.severity,
+                body: { stringValue: r.body },
+                attributes: attrs(r.attributes)
+              }))
+            }
+          ]
+        }
+      ]
+    });
+    const url = `${this.o.endpoint.replace(/\/+$/, "")}/v1/logs`;
+    const send = this.o.send ?? fetchSend;
+    this.inflight = this.inflight.then(
+      () => send(url, body, this.o.headers ?? {}).then(
+        () => void (this.sent += batch.length),
+        () => void (this.dropped += batch.length)
+      )
+    );
+    return this.inflight;
+  }
+  /** Stop the timer and send what is left. */
+  async close() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    await this.flush();
+  }
+};
+function parseOtlpHeaders(text) {
+  const out = {};
+  for (const part of (text ?? "").split(",")) {
+    const i = part.indexOf("=");
+    if (i <= 0) continue;
+    const key = part.slice(0, i).trim();
+    const value = part.slice(i + 1).trim();
+    if (!key) continue;
+    try {
+      out[key] = decodeURIComponent(value);
+    } catch {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function otlpFromEnv(env, defaults) {
+  const logs = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT?.trim();
+  const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+  const endpoint = logs ? logs.replace(/\/v1\/logs\/?$/, "") : base;
+  if (!endpoint) return null;
+  return {
+    endpoint,
+    serviceName: env.OTEL_SERVICE_NAME?.trim() || defaults.serviceName,
+    ...defaults.serviceVersion ? { serviceVersion: defaults.serviceVersion } : {},
+    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_LOGS_HEADERS) }
+  };
+}
+
 // src/api/client.ts
 var ACTOR_HEADER = "X-Datanotes-Actor";
 var DatanotesError = class extends Error {
@@ -3127,6 +3234,7 @@ export {
   DatanotesError,
   OPERATIONS,
   OperationInputError,
+  OtlpLogExporter,
   ROUTE_PREFIX,
   describeBatch,
   describeRefusal,
@@ -3134,5 +3242,7 @@ export {
   fetchTransport,
   operationRequest,
   operationRoute,
+  otlpFromEnv,
+  parseOtlpHeaders,
   resultOf
 };

package/dist/api/otlp.d.ts

@@ -0,0 +1,54 @@
+/**
+ * OTLP/HTTP log export for programs around the engine (MCP servers, apps): records are buffered
+ * and POSTed as OTLP JSON to `<endpoint>/v1/logs`, the format SigNoz and any OpenTelemetry
+ * collector read. No dependency, no SDK. Export failures are counted, never thrown: logging must
+ * not break the program.
+ *
+ * Configure it in code, or from the standard environment variables with `otlpFromEnv`.
+ */
+export type Severity = "DEBUG" | "INFO" | "WARN" | "ERROR";
+export type AttrValue = string | number | boolean | null | undefined;
+export interface OtlpOptions {
+    /** Collector base URL, e.g. `http://127.0.0.1:4318` (`/v1/logs` is added). */
+    endpoint: string;
+    /** `service.name` of the records. */
+    serviceName: string;
+    serviceVersion?: string;
+    /** Extra headers, e.g. `{"signoz-ingestion-key": "…"}`. */
+    headers?: Record<string, string>;
+    /** More resource attributes (e.g. `host.name`). */
+    resource?: Record<string, AttrValue>;
+    /** Send at most this many records per request (default 50); a full buffer is sent at once. */
+    maxBatch?: number;
+    /** Send the buffer every this many ms (default 5000; 0: only on `flush`). */
+    flushMs?: number;
+    /** POST a body; resolves on 2xx (default: fetch). */
+    send?: (url: string, body: string, headers: Record<string, string>) => Promise<void>;
+    now?: () => number;
+}
+export declare class OtlpLogExporter {
+    private readonly o;
+    private buffer;
+    private inflight;
+    private timer;
+    /** Records sent, and records lost because the collector did not take them. */
+    sent: number;
+    dropped: number;
+    constructor(o: OtlpOptions);
+    log(severity: Severity, body: string, attributes?: Record<string, AttrValue>): void;
+    /** Send what is buffered. Never rejects. */
+    flush(): Promise<void>;
+    /** Stop the timer and send what is left. */
+    close(): Promise<void>;
+}
+/** `k1=v1,k2=v2` (values URL-encoded), the format of `OTEL_EXPORTER_OTLP_HEADERS`. */
+export declare function parseOtlpHeaders(text: string | undefined): Record<string, string>;
+/**
+ * Exporter options from the standard OpenTelemetry variables, or null when no endpoint is set:
+ * `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (full URL of /v1/logs) or `OTEL_EXPORTER_OTLP_ENDPOINT`,
+ * `OTEL_EXPORTER_OTLP_HEADERS` / `OTEL_EXPORTER_OTLP_LOGS_HEADERS`, `OTEL_SERVICE_NAME`.
+ */
+export declare function otlpFromEnv(env: Record<string, string | undefined>, defaults: {
+    serviceName: string;
+    serviceVersion?: string;
+}): OtlpOptions | null;

package/dist/datanotes.cjs

@@ -7425,6 +7425,7 @@ var DEFAULT_SETTINGS = {
   telemetryEnabled: false,
   telemetryEndpoint: "http://127.0.0.1:4318",
   telemetryServiceName: "datanotes",
+  telemetryHeaders: {},
   autoRecompute: true,
   viewNotes: true,
   semanticEnabled: false,
@@ -7450,6 +7451,7 @@ var KEYS = [
   "telemetryEnabled",
   "telemetryEndpoint",
   "telemetryServiceName",
+  "telemetryHeaders",
   "autoRecompute",
   "viewNotes",
   "semanticEnabled",
@@ -7500,6 +7502,14 @@ function mergeWithDefaults(loaded) {
         }
         break;
       }
+      case "telemetryHeaders": {
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+          out.telemetryHeaders = Object.fromEntries(
+            Object.entries(raw).filter(([k, v]) => /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(k) && typeof v === "string")
+          );
+        }
+        break;
+      }
       case "telemetryServiceName": {
         if (typeof raw === "string" && raw.trim().length > 0) {
           out.telemetryServiceName = raw.trim();
@@ -7659,7 +7669,7 @@ function otlpLogsPayload(serviceName, records, resource = {}) {
         resource: { attributes: attrs({ "service.name": serviceName, ...resource }) },
         scopeLogs: [
           {
-            scope: { name: "obsidian-datanotes" },
+            scope: { name: "datanotes" },
             logRecords: records.map((r) => ({
               timeUnixNano: r.timeUnixNano,
               observedTimeUnixNano: r.timeUnixNano,
@@ -7705,7 +7715,7 @@ var OtlpLogger = class {
     const url = `${settings.telemetryEndpoint.replace(/\/+$/, "")}/v1/logs`;
     const body = otlpLogsPayload(settings.telemetryServiceName, batch, this.opts.resource);
     this.inflight = this.inflight.then(
-      () => this.opts.transport(url, body).then(
+      () => this.opts.transport(url, body, { ...settings.telemetryHeaders ?? {} }).then(
         () => {
           this.sent += batch.length;
         },
@@ -7793,6 +7803,7 @@ var TeeTelemetry = class {
 
 // src/server/engine-lock.ts
 var LOCK_PATH_SUFFIX = "engine.lock";
+var LOCK_STALE_MS = 3e4;
 var LOCK_HEARTBEAT_MS = 1e4;
 function lockPath(storeFolder) {
   return `${storeFolder.replace(/\/+$/, "")}/${LOCK_PATH_SUFFIX}`;
@@ -7805,6 +7816,9 @@ async function readLock(adapter2, storeFolder) {
     return null;
   }
 }
+function isFresh(lock, now = Date.now()) {
+  return !!lock && now - Date.parse(lock.heartbeat) < LOCK_STALE_MS;
+}
 var LockHolder = class {
   constructor(adapter2, storeFolder, info) {
     this.adapter = adapter2;
@@ -7836,6 +7850,24 @@ var LockHolder = class {
   }
 };
 
+// src/api/otlp.ts
+function parseOtlpHeaders(text2) {
+  const out = {};
+  for (const part of (text2 ?? "").split(",")) {
+    const i = part.indexOf("=");
+    if (i <= 0) continue;
+    const key = part.slice(0, i).trim();
+    const value = part.slice(i + 1).trim();
+    if (!key) continue;
+    try {
+      out[key] = decodeURIComponent(value);
+    } catch {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
 // src/core/filename-values.ts
 var PLACEHOLDER = /\{([A-Za-z][A-Za-z0-9_-]*)(?::([^}]+))?\}/g;
 var FORMAT_TOKEN = /\[([^\]]*)\]|YYYY|MM|DD|HH|mm|ss/g;
@@ -10087,7 +10119,7 @@ async function tableStateAt(app, settings, full, asOf2 = {}) {
   if (versions.length === 0) {
     if (asOf2.version !== void 0 || asOf2.timestamp !== void 0) {
       throw new HistoryError(
-        `${full} has no history: time travel is off for it (turn it on with configure_database(history=true) or alter_table(history=true))`
+        `${full} has no history: time travel is off for it (turn it on with configure_database(history=true) or alter_table(history="on"))`
       );
     }
     return emptyState(full);
@@ -15006,7 +15038,7 @@ var SemanticIndex = class {
   }
   requireEnabled() {
     if (!this.getSettings().semanticEnabled) {
-      throw new OperationInputError("semantic search is off: enable it in the plugin settings and choose an embedding provider");
+      throw new OperationInputError("semantic search is off: set semanticEnabled, semanticProvider and semanticModel in the engine settings");
     }
   }
   async load() {
@@ -15054,7 +15086,7 @@ var SemanticIndex = class {
   /** Notes in scope: every markdown note, or only table rows; minus excluded folders and archives. */
   inScope(f, table) {
     const s = this.getSettings();
-    if (f.path.includes("/_archive/")) return false;
+    if (f.path.startsWith("_archive/") || f.path.includes("/_archive/")) return false;
     if (s.semanticExclude.some((dir) => f.path === dir || f.path.startsWith(`${dir.replace(/\/+$/, "")}/`))) return false;
     if (s.semanticScope === "tables" && !table) return false;
     return true;
@@ -16206,7 +16238,7 @@ var HttpApiServer = class {
   }
   /**
    * Resolves with the bound port once listening. A busy port is retried a few times: when the
-   * plugin reloads, the previous instance may still be closing.
+   * engine restarts, the previous instance may still be closing.
    */
   async start(retries = 6, delayMs = 500) {
     for (let i = 0; ; i++) {
@@ -17533,7 +17565,7 @@ function checkPatterns(patterns) {
 var OPERATIONS = [
   {
     "name": "read_note",
-    "description": "Read a vault file (``GET /vault/{filename}``).\n\nDefault response is raw markdown. With ``as_json`` true, requests ``Accept: application/vnd.olrapi.note+json`` and returns ``NoteJson``: ``content``, ``frontmatter``, ``tags``, ``path``, and ``stat`` (file times and size), per the plugin OpenAPI schema.\n\nInputs:\n- ``path``: Vault-relative path to the file (forward slashes).\n- ``as_json``: If false (default), return markdown. If true, return ``NoteJson``.\n\nReturns:\n- ``str`` \u2014 markdown body, or\n- ``dict[str, Any]`` \u2014 parsed ``NoteJson`` when ``as_json`` is true.",
+    "description": "Read a vault file (`GET /vault/{path}`). Default: the raw markdown. With `as_json`:\n`{content, frontmatter, tags, path, stat}` (`tags` without `#`, from the text and the\nfrontmatter; `stat`: `{ctime, mtime, size}` or null). A missing file is an error.\n`path`: vault-relative, forward slashes.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -17560,7 +17592,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_directory",
-    "description": 'List files under a vault directory (``GET /vault/`` or ``GET /vault/{pathToDirectory}/``).\n\nResponse JSON includes a ``files`` array. Names ending with ``/`` are subdirectories. Empty directories may not appear in listings (per API). Use ``""`` for the vault root.\n\nInputs:\n- ``path``: Vault-relative directory path; use ``""`` for the vault root.\n\nReturns:\n- ``dict[str, Any]`` \u2014 parsed JSON listing from the API.',
+    "description": 'Direct children of a vault folder (`GET /vault/{folder}/`): `{files: [...]}`. Folders end with\n`/`, names are sorted, dot-files are hidden. `""` is the vault root. A missing folder is an\nerror.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -17581,7 +17613,7 @@ var OPERATIONS = [
   },
   {
     "name": "search_simple",
-    "description": "Full-text search (``POST /search/simple/``).\n\nUses Obsidian\u2019s native search syntax (keywords, ``path:``, ``tag:``, ``file:``, etc.). Results include filenames, match positions, context snippets, and scores per the plugin OpenAPI.\n\nInputs:\n- ``query``: Obsidian search expression.\n- ``context_length``: Max characters of context around each match (default 100).\n\nReturns:\n- Parsed JSON from the API (matches per file, context, score).",
+    "description": "Plain-text search (`POST /search/simple/`): every word of `query` must occur, case- and\naccent-insensitive, in the note's path or text; there are no operators. Returns up to 200\nfiles, best first: `[{filename, score, matches: [{match: {start, end}, context}]}]`, at most 20\nmatches per file. `context_length`: characters of context on each side (default 100, max 1000).",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -17608,7 +17640,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_tables",
-    "description": "List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` \u2014 use it\nwherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and,\nwhen declared, `description` and `aliases` (other words for what it records). Tables are\ndefined in `database.yaml` (catalog \u2192 schema \u2192 table); legacy schema-note tables have no\n`catalog` and a two-part `qualified` name. `views` lists the stored views (same fields, no\npath): select them like tables. `system.information_schema` is read with `select_rows`.\n\nCall this first to find the table for what the user reports (match their words against\nname, description and aliases), and before creating tables or columns so you reuse existing\nones instead of creating duplicates.",
+    "description": "List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` \u2014 use it\nwherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and,\nwhen declared, `description` and `aliases` (other words for what it records). Tables are\ndefined in `database.yaml` (catalog \u2192 schema \u2192 table). Returns `{tables, views}`: `views` lists the stored views (same fields, no\npath): select them like tables. `system.information_schema` is read with `select_rows`.\n\nCall this first to find the table for what the user reports (match their words against\nname, description and aliases), and before creating tables or columns so you reuse existing\nones instead of creating duplicates.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {},
@@ -17728,7 +17760,8 @@ var OPERATIONS = [
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Untyped fields of the table (name \u2192 default), kept on every row; a field cannot share a name with a column."
         },
         "body": {
           "anyOf": [
@@ -17836,7 +17869,7 @@ var OPERATIONS = [
   },
   {
     "name": "rename_column",
-    "description": "Rename a column on the schema and every row, and rewrite the references to it in notes.\nAlso the way to merge a duplicate column into an existing compatible one. Refused (nothing\nwritten) if any row has both columns with different values.",
+    "description": "Rename a column in database.yaml and on every row. Refused if `to_column` is already a column\nof the table; a row that has a stray `to_column` key with a different value is a conflict, and\nnothing is written. Views and note text that mention the old name are not rewritten.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -18207,7 +18240,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_database",
-    "description": "Describe the database: its folder (`root`), `metastore` (`database.yaml`), configuration\n(default catalog and schema, row partition and file-name formats, archive folder, time zone),\njournal folder, `bases` (shared column sets and the tables using them), `catalogs` \u2192 schemas \u2192 tables (row counts) and views, legacy schema-note\ntables (`schemas`) and tables outside the database (`outside`).",
+    "description": "Describe the database: its folder (`root`), `metastore` (`database.yaml`), configuration\n(default catalog and schema, row partition and file-name formats, archive folder, time zone),\njournal folder, `bases` (shared column sets and the tables using them), `catalogs` \u2192 `schemas` \u2192 `tables` (with `rows` counts) and `views`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {},
@@ -18223,7 +18256,7 @@ var OPERATIONS = [
   },
   {
     "name": "configure_database",
-    "description": 'Configure the database (persisted in database.yaml `config:`): `root` (rename the database\nfolder; links follow; revert by renaming back), `default_catalog`, `default_schema`,\n`default_partition` ("" = flat) and `filename` (date formats for new time-based tables),\n`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`\n(transaction log for every table \u2014 only on the user\'s request). Returns describe_database;\nafter a root rename also `rewritten` and `mentions` (show them to the user).',
+    "description": 'Configure the database (persisted in database.yaml `config:`): `root` (rename the database\nfolder; links follow; revert by renaming back), `default_catalog`, `default_schema`,\n`default_partition` ("" = flat) and `filename` (date formats for new time-based tables),\n`archive_folder`, `timezone` (IANA; completes date-times written without offset), `history`\n(transaction log for every table \u2014 only on the user\'s request). Returns describe_database.\nRenaming `root` moves the folder (links to its notes are rewritten); it is not journaled: to\nrevert, call it again with the old value.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -18398,7 +18431,8 @@ var OPERATIONS = [
               "type": "null"
             }
           ],
-          "default": null
+          "default": null,
+          "description": "Optional note path (vault-relative), instead of the table's file-name pattern; `.md` is added if missing; it must stay inside the vault."
         },
         "dry_run": {
           "default": false,
@@ -18636,7 +18670,7 @@ var OPERATIONS = [
       "title": "Update Row",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -18790,7 +18824,7 @@ var OPERATIONS = [
   },
   {
     "name": "adopt_rows",
-    "description": 'Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and\nlinks: `rename` keys (`{"data": "occurred_at"}`), `set_values` for all, `per_row` values by\nnote path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.\nEvery note gets `table` and a system `id`; with `relocate` (default) it moves to the table\'s\nfolder, named by its filename pattern (Obsidian updates links). All notes are validated first:\nunknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo\nwith `undo_migration`.',
+    "description": 'Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and\nlinks: `rename` keys (`{"data": "occurred_at"}`), `set_values` for all, `per_row` values by\nnote path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have.\nEvery note gets `table` and a system `id`; with `relocate` (default) it moves to the table\'s\nfolder, named by its filename pattern (links to it are rewritten). All notes are validated first:\nunknown keys and bad values are listed and nothing is written. Run with `dry_run` first; undo\nwith `undo_migration`.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -19093,7 +19127,7 @@ var OPERATIONS = [
     "annotations": {
       "title": "Undo Migration",
       "readOnlyHint": false,
-      "destructiveHint": false,
+      "destructiveHint": true,
       "idempotentHint": false,
       "openWorldHint": false
     }
@@ -19258,7 +19292,7 @@ var OPERATIONS = [
   },
   {
     "name": "semantic_search",
-    "description": 'Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,\ntable?}]}`, one result per note (its best passage), best first. Use it for vague questions\n("the dinner where we talked about moving", "what did I decide about the car") and to find the\nrows to read or update; then read_note / select_rows for the details. Filters: `tables`\n(qualified or short names), `folder`, `min_score` (cosine 0\u20131; ~0.5+ is usually relevant).\nFails with a clear message when semantic search is off in the plugin settings.',
+    "description": 'Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,\ntable?}]}`, one result per note (its best passage), best first. Use it for vague questions\n("the dinner where we talked about moving", "what did I decide about the car") and to find the\nrows to read or update; then read_note / select_rows for the details. Filters: `tables`\n(qualified or short names), `folder`, `min_score` (cosine 0\u20131; ~0.5+ is usually relevant).\n`limit`: default 10, max 100. Fails with a clear message when semantic search is not enabled in\nthe engine settings.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -19321,7 +19355,7 @@ var OPERATIONS = [
   },
   {
     "name": "semantic_index",
-    "description": "Semantic search index: `status` (provider, model, notes, passages, last error), `update`\n(embed notes changed since the last run; the plugin also does it on its own a few seconds after\nedits) or `rebuild` (re-embed everything: slow, and costs money with a paid provider \u2014 ask\nfirst).",
+    "description": "Semantic search index: `status` (`enabled`, `provider`, `model`, `files`, `passages`, `pending`,\n`running`, `lastSync`, `lastError`), `update` (embed notes changed since the last run; the\nengine also does it on its own about ten seconds after edits) or `rebuild` (re-embed\neverything: slow, and costs money with a paid provider \u2014 ask first).",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -19467,7 +19501,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_history",
-    "description": "DESCRIBE HISTORY: the table's versions, newest first \u2014 `version`, `timestamp`, `operation`\n(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, \u2026;\n`EXTERNAL_EDIT` = changed by hand in Obsidian), `operationMetrics` and `migrationId` (undo).\nWorks for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`\n(time travel), `table_changes` or `restore_table`.",
+    "description": "DESCRIBE HISTORY: the table's versions, newest first \u2014 `version`, `timestamp`, `operation`\n(CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, \u2026;\n`EXTERNAL_EDIT` = changed outside the engine: an editor, git, sync), `operationMetrics` and `migrationId` (undo).\nWorks for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows`\n(time travel), `table_changes` or `restore_table`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -19539,7 +19573,7 @@ var OPERATIONS = [
   },
   {
     "name": "list_changes",
-    "description": "Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes\nand from hand edits (`source: external`). Each has `table`, `op` (insert, update, delete, move,\nschema), `path`, `changes` ({column: {before, after}}), `actor`, `migration`. MCP tool calls are `op: tool_call` events (`call`: tool, args, ok, value, servedBy), returned only when `ops` includes tool_call. Pass the returned\n`last` as `since` next time (`head` is the newest number); `wait_ms` waits for a new change (long poll). `gap: true` means\nolder changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.",
+    "description": "Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes\nand from hand edits (`source: external`). Each has `table`, `op` (insert, update, delete, move,\nschema), `path`, `changes` ({column: {before, after}}), `actor`, `migration`. Agents' tool calls (reported by MCP servers) are `op: tool_call` events (`call`: tool, args, ok, value, servedBy), returned only when `ops` includes tool_call. Pass the returned\n`last` as `since` next time (`head` is the newest number); `wait_ms` (max 60000) waits for a new change (long poll); `limit` max 5000. `gap: true` means\nolder changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -20065,7 +20099,7 @@ var OPERATIONS = [
   },
   {
     "name": "clone_table",
-    "description": "CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows\n(deep clone), optionally as of a `version` / `timestamp`. `shallow=true` copies the\ndefinition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (default\ncatalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy\nin the `agent` catalog.",
+    "description": "CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows\n(deep clone), optionally as of a `version` / `timestamp`. `shallow=true` copies the\ndefinition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (in the\nsource's catalog) or a name (source's catalog and schema). Useful for experiments, e.g. a sandbox copy\nin the `agent` catalog.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -20122,7 +20156,7 @@ var OPERATIONS = [
   },
   {
     "name": "recompute_columns",
-    "description": "Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after\nrows were edited outside the plugin or a generated expression changed with `alter_column`.\nAlso gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)\na new id. `new_ids=true` regenerates every id in scope: only on the user's explicit request.\n`check_table` reports stale values with code `generated`. No-op when nothing is stale;\notherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.",
+    "description": "Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after\nrows were edited by hand (an editor, git, sync) or a generated expression changed with `alter_column`.\nAlso gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)\na new id. `new_ids=true` regenerates every id in scope (new ones on every call): only on the user's\nexplicit request.\n`check_table` reports stale values with code `generated`. No-op when nothing is stale;\notherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -20161,7 +20195,7 @@ var OPERATIONS = [
       "title": "Recompute Columns",
       "readOnlyHint": false,
       "destructiveHint": false,
-      "idempotentHint": true,
+      "idempotentHint": false,
       "openWorldHint": false
     }
   },
@@ -20326,7 +20360,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_path",
-    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
+    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -20464,7 +20498,8 @@ var ROUTES = {
   create_webhook: (a) => ["/webhooks/create/", pick(a, ["url", "tables", "ops", "columns", "exclude_actor", "where", "since"])],
   delete_webhook: (a) => ["/webhooks/delete/", pick(a, ["id"])],
   restore_table: (a) => ["/history/restore/", { ...pick(a, ["table", "version", "timestamp"]), ...dry(a) }],
-  vacuum_table: (a) => ["/history/vacuum/", { ...pick(a, ["table", "retain_from_version"]), ...dry(a) }],
+  // vacuum deletes history for good: a dry run unless the caller says `dry_run: false`
+  vacuum_table: (a) => ["/history/vacuum/", { ...pick(a, ["table", "retain_from_version"]), dry_run: a.dry_run !== false }],
   graph_neighbors: (a) => ["/graph/neighbors/", compact({ from: a.from_nodes, direction: a.direction, edges: a.edges })],
   graph_traverse: (a) => [
     "/graph/traverse/",
@@ -20755,7 +20790,7 @@ var EngineRuntime = class {
     const s = this.o.getSettings;
     const logger = new OtlpLogger({
       getSettings: s,
-      transport: async (url, body) => this.o.postLogs(url, body),
+      transport: async (url, body, headers) => this.o.postLogs(url, body, headers),
       resource: { "service.version": this.o.version, "host.name": this.o.hostName }
     });
     const source = this.o.hostName;
@@ -22062,7 +22097,7 @@ var NodeWatcher = class {
 };
 
 // src/node/service.ts
-var VERSION = true ? "1.2.0" : "dev";
+var VERSION = true ? "1.3.0" : "dev";
 function parseArgs(argv, env = process.env) {
   const get = (name) => {
     const i = argv.indexOf(`--${name}`);
@@ -22107,6 +22142,11 @@ async function startService(o, env = process.env) {
     import_node_fs5.default.writeFileSync(file, JSON.stringify({ ...current2, ...settings }, null, 2));
   };
   const host = openNodeVault(o.vault);
+  const held = await readLock(host.vault.adapter, storeRoot(settings));
+  if (isFresh(held) && held.pid !== process.pid && (held.host !== import_node_os.default.hostname() || processAlive(held.pid))) {
+    host.metadataCache.dispose();
+    throw new Error(`another engine holds the vault (pid ${held.pid} on ${held.host}, port ${held.port}): stop it first`);
+  }
   const watcher = new NodeWatcher(host.vault, { mode: o.watch, intervalMs: o.pollMs });
   const keyFromFile = () => {
     if (!o.embeddingKeyFile) return void 0;
@@ -22125,8 +22165,9 @@ async function startService(o, env = process.env) {
       const res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
       return { status: res.status, text: await res.text() };
     },
-    postLogs: async (url, body) => {
-      const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body });
+    postLogs: async (url, body, headers) => {
+      const all = { ...headers, ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS) };
+      const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", ...all }, body });
       if (!res.ok) throw new Error(`OTLP HTTP ${res.status}`);
     },
     embeddingKey: () => env.DATANOTES_EMBEDDING_KEY || keyFromFile(),
@@ -22184,6 +22225,14 @@ async function startService(o, env = process.env) {
     }
   };
 }
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
 async function main(argv = process.argv.slice(2)) {
   const li = argv.indexOf("--log");
   if (li >= 0 && argv[li + 1]) {
@@ -22227,7 +22276,7 @@ Docs: https://datanotes.dev`;
 }
 
 // src/node/cli.ts
-var VERSION2 = true ? "1.2.0" : "dev";
+var VERSION2 = true ? "1.3.0" : "dev";
 async function main2(argv = process.argv.slice(2)) {
   const [command, ...rest] = argv;
   if (command === "--version" || command === "-v" || command === "version") return void process.stdout.write(`${VERSION2}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datanotes",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "The engine of your second brain: Markdown notes as database tables, for you and your agents.",
   "keywords": [
     "markdown",