datanotes 3.1.0 → 3.3.0

package/dist/api/index.cjs

@@ -390,7 +390,7 @@ var OPERATIONS = [
   },
   {
     "name": "describe_table",
-    "description": "Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,\n`catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern\nof new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns`\nwith label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set:\n`tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name \u2192 where), `row_template`, `history`,\n`autolink_target`, `fields` (their values).\n\nBefore adding a column (e.g. a new metric), read `columns` and match your concept against\n`name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.\n\n`missing_descriptions` (`{table, columns}`), present only when something has no description (a table\ndefined before descriptions were required), names what lacks one: write them with alter_table\n`description` and alter_column `changes.description`, asking the user when the meaning is unclear.",
+    "description": "Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,\n`catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern\nof new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns`\nwith label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set:\n`tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name \u2192 where), `constraint_hints` (their own hints, name \u2192 hint), `instructions` (how to fill a row: follow them before you write one), `row_template`, `history`,\n`autolink_target`, `fields` (their values).\n\nBefore adding a column (e.g. a new metric), read `columns` and match your concept against\n`name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.\n\n`missing_descriptions` (`{table, columns}`), present only when something has no description (a table\ndefined before descriptions were required), names what lacks one: write them with alter_table\n`description` and alter_column `changes.description`, asking the user when the meaning is unclear.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -513,6 +513,10 @@ var OPERATIONS = [
               "inverse": {
                 "type": "string"
               },
+              "acyclic": {
+                "type": "boolean",
+                "description": "Link column to its own table whose links never form a cycle (a write that closes one is refused)."
+              },
               "ref_where": {
                 "type": "object",
                 "description": "Link column: the where filter every linked row must match.",
@@ -622,6 +626,17 @@ var OPERATIONS = [
           },
           "description": "Its CHECK constraints: name \u2192 the where every row must match."
         },
+        "constraint_hints": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "The hint of each CHECK that has one: name \u2192 what to do when a row breaks it."
+        },
+        "instructions": {
+          "type": "string",
+          "description": "How to fill a row of the table (alter_table instructions): follow them before you write one."
+        },
         "row_template": {
           "type": "string",
           "description": "The text of every new row's note."
@@ -655,7 +670,7 @@ var OPERATIONS = [
   },
   {
     "name": "create_table",
-    "description": 'Create a table: `name`, in `catalog` and `schema` (default: the database\'s defaults); the definition\ngoes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters,\ndigits, `_` (no dots: pass the catalog and the schema as their own arguments).\n- `description` (required): what a row of the table records. Every column needs its own `description`\n  too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how\n  agents and people understand the schema, so write them for a reader who never saw the notes. The\n  engine writes those of `id` and of `identity` "uuid" / "created" columns.\n- `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true,\n  "description": "What kind of entry the row is"}`.\n  Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json.\n  Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in\n  order: filters/avg use the position), ref (link target, full `catalog.schema.table` or "self"),\n  unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`),\n  `identity` ("filename" | "created"), `vocabulary` (allowed values = names of another table\'s rows),\n  `hierarchy: true` (one parent link to its own table), `dense` (written on every row),\n  `inverse` on a link column: the column of the `ref` table that links back (`friends` \u2194\n  `friends`, `children` \u2194 `parents`, `partner` \u2194 `partner`); writes keep both sides in step.\n- `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).\n- The table\'s options, as alter_table names them: `aliases` (how agents find it, with the\n  description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the\n  database\'s setting), `autolink_target` (true / false: may automatic links link its rows? default:\n  yes, unless its rows are named by a date or a time, as with `time_column`).\n- `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.\n- `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and\n  describe_table return them, alter_table changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+    "description": 'Create a table: `name`, in `catalog` and `schema` (default: the database\'s defaults); the definition\ngoes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters,\ndigits, `_` (no dots: pass the catalog and the schema as their own arguments).\n- `description` (required): what a row of the table records. Every column needs its own `description`\n  too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how\n  agents and people understand the schema, so write them for a reader who never saw the notes. The\n  engine writes those of `id` and of `identity` "uuid" / "created" columns.\n- `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true,\n  "description": "What kind of entry the row is"}`.\n  Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json.\n  Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in\n  order: filters/avg use the position), ref (link target, full `catalog.schema.table` or "self"),\n  unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`),\n  `identity` ("filename" | "created"), `vocabulary` (allowed values = names of another table\'s rows),\n  `hierarchy: true` (one parent link to its own table), `acyclic: true` (links to rows of its own table that never loop back, such as tasks blocked by tasks; with `inverse`, the rule holds on both sides), `dense` (written on every row),\n  `inverse` on a link column: the column of the `ref` table that links back (`friends` \u2194\n  `friends`, `children` \u2194 `parents`, `partner` \u2194 `partner`); writes keep both sides in step.\n- `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).\n- The table\'s options, as alter_table names them: `aliases` (how agents find it, with the\n  description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the\n  database\'s setting), `autolink_target` (true / false: may automatic links link its rows? default:\n  yes, unless its rows are named by a date or a time, as with `time_column`).\n- `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.\n- `instructions`: how to fill a row, for agents (Markdown); describe_table returns them.\n- `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and\n  describe_table return them, alter_table changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -816,6 +831,18 @@ var OPERATIONS = [
           "default": null,
           "description": "Markdown body of new rows; {column} placeholders are filled from the row."
         },
+        "instructions": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "How to fill a row, for agents (Markdown): which columns first, what to ask the user. describe_table returns them."
+        },
         "fields": {
           "anyOf": [
             {
@@ -953,6 +980,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -1362,6 +1393,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -1641,7 +1676,7 @@ var OPERATIONS = [
   },
   {
     "name": "add_column",
-    "description": 'Add a typed column. Sparse by default (written only on rows that have a value \u2014 use for\nmetrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label":\n"Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`).\n`description` is required: what the column holds, for the agents and people who read the schema\n(the engine writes it for `identity` "uuid" / "created" columns).\n`dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add\na column whose meaning an existing column (name/label/aliases/description) already covers.\nColumn names are permanent identifiers; only `rename_column` changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+    "description": 'Add a typed column. Sparse by default (written only on rows that have a value \u2014 use for\nmetrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label":\n"Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`).\n`description` is required: what the column holds, for the agents and people who read the schema\n(the engine writes it for `identity` "uuid" / "created" columns).\n`dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add\na column whose meaning an existing column (name/label/aliases/description) already covers.\nColumn names are permanent identifiers; only `rename_column` changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\nAcyclic links: `acyclic: true` on a link (or list of links) to the table itself refuses every write that closes a cycle, on either side of an `inverse`; refused while existing rows form one (they are listed).\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -1762,6 +1797,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -2164,6 +2203,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -2563,6 +2606,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -2842,7 +2889,7 @@ var OPERATIONS = [
   },
   {
     "name": "alter_column",
-    "description": 'Change a column\'s attributes (type, min/max/step, values, required, default, label,\naliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except\n`description`, which changes but never goes (null or "" is refused); `dense` true/false). Refused with\nthe list of violating rows when existing values do not satisfy the new definition. A\ndifferent scale means a different column: add a new one instead of rescaling. To rename one\nenum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a\ntarget level is refused, naming it.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+    "description": 'Change a column\'s attributes (type, min/max/step, values, required, default, label,\naliases, description, note, `ref_where`, `ref_by` (see list_link_targets), `acyclic` (refused while the rows already form a cycle: they are listed); `null` removes an attribute, except\n`description`, which changes but never goes (null or "" is refused); `dense` true/false). Refused with\nthe list of violating rows when existing values do not satisfy the new definition. A\ndifferent scale means a different column: add a new one instead of rescaling. To rename one\nenum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a\ntarget level is refused, naming it.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -2967,6 +3014,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -3246,7 +3297,7 @@ var OPERATIONS = [
   },
   {
     "name": "alter_table",
-    "description": 'Alter a table: move it (`catalog`, `schema`), rename it (`name`), change\n`partition` / `filename` patterns, `description` (changes, never goes: "" is refused), `aliases`,\n`exclude` folders, `row_template`\n("" removes it), `history` (true | false | "default"), `autolink_target`\n(true | false | "default": may automatic links link its rows? default: yes, unless its rows are named by\na date or a time) or `tags` (key/value\nlabels merged into the table\'s, e.g. `{"domain": "health"}`; a `null` value removes that tag;\n`clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those),\n`archive` (folder name inside the table folder) or `fields` (untyped fields, name \u2192 default; a\n`null` value removes one). Rows, archive and transaction log follow; links are updated; renamed\nrows keep their old name in `aliases`. A change of metadata only (tags, description, aliases,\nhistory, autolink_target, row_template, fields) rewrites the table entry alone: no row is moved or rewritten. Refused\nwhen a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows\nlinks, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not\nrewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+    "description": 'Alter a table: move it (`catalog`, `schema`), rename it (`name`), change\n`partition` / `filename` patterns, `description` (changes, never goes: "" is refused), `aliases`,\n`exclude` folders, `row_template`\n("" removes it), `instructions` (how to fill a row, for agents; "" removes them), `history` (true | false | "default"), `autolink_target`\n(true | false | "default": may automatic links link its rows? default: yes, unless its rows are named by\na date or a time) or `tags` (key/value\nlabels merged into the table\'s, e.g. `{"domain": "health"}`; a `null` value removes that tag;\n`clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those),\n`archive` (folder name inside the table folder) or `fields` (untyped fields, name \u2192 default; a\n`null` value removes one). Rows, archive and transaction log follow; links are updated; renamed\nrows keep their old name in `aliases`. A change of metadata only (tags, description, aliases,\nhistory, autolink_target, row_template, instructions, fields) rewrites the table entry alone: no row is moved or rewritten. Refused\nwhen a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows\nlinks, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not\nrewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -3396,6 +3447,18 @@ var OPERATIONS = [
           "default": null,
           "description": 'Markdown body of new rows; "" removes it.'
         },
+        "instructions": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": 'How to fill a row, for agents (Markdown); "" removes them.'
+        },
         "tags": {
           "anyOf": [
             {
@@ -3556,6 +3619,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -4012,6 +4079,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -4413,6 +4484,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -5475,6 +5550,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -5881,6 +5960,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -6160,7 +6243,7 @@ var OPERATIONS = [
   },
   {
     "name": "insert_row",
-    "description": "Insert a row (new note). Values are validated against the columns; the note path comes from\nthe table's `path`/`filename` patterns (e.g. an event logged today about last night lands in\nlast night's day folder when you set `occurred_at` to last night). `body` is the note text.\nGenerated / identity columns are computed (do not pass them); CHECK constraints are enforced.\nReturns `migration_id` (undo) and the created path in `planned_creates`.\n`body` links the notes it mentions by name, at their first mention (automatic links; off with\n`autolink: false` or the database's `autolink` setting). `links_added` lists the links made;\n`ambiguous_mentions` lists the mentions left as text with the notes they may name: read those,\nthen link the right one with update_row and `autolink: false`, or leave the text.",
+    "description": "Insert a row (new note). When describe_table gives the table's `instructions`, fill the row as they say. Values are validated against the columns; the note path comes from\nthe table's `path`/`filename` patterns (e.g. an event logged today about last night lands in\nlast night's day folder when you set `occurred_at` to last night). `body` is the note text.\nGenerated / identity columns are computed (do not pass them); CHECK constraints are enforced.\nReturns `migration_id` (undo) and the created path in `planned_creates`.\n`body` links the notes it mentions by name, at their first mention (automatic links; off with\n`autolink: false` or the database's `autolink` setting). `links_added` lists the links made;\n`ambiguous_mentions` lists the mentions left as text with the notes they may name: read those,\nthen link the right one with update_row and `autolink: false`, or leave the text.",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -6315,6 +6398,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -6753,6 +6840,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -7266,6 +7357,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -7697,6 +7792,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -8145,6 +8244,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -8605,6 +8708,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -9113,7 +9220,7 @@ var OPERATIONS = [
   },
   {
     "name": "check_table",
-    "description": "Validate every row against the table (required, types, ranges, enums, links, unknown\ncolumns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). A CHECK violation has code `check` and the CHECK's name as `constraint` (every other code names its `column`), as in the `violations` of list_changes. Use it to find rows edited by hand that break the schema. Without `table`, every table is checked: each row then names its `table`, `tables_checked` counts the tables checked, and a table that cannot be checked is listed in `errors` ({table, error}) while the others are. The rows with violations are paged: `limit` (default 500, at most 5000) from `offset`; `total` counts them all. (Hand edits are also checked as they happen: see `violations` in list_changes.)",
+    "description": "Validate every row against the table (required, types, ranges, enums, links, unknown\ncolumns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, cycles of hierarchy and acyclic columns, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). A CHECK violation has code `check` and the CHECK's name as `constraint` (every other code names its `column`), as in the `violations` of list_changes. Use it to find rows edited by hand that break the schema. Without `table`, every table is checked: each row then names its `table`, `tables_checked` counts the tables checked, and a table that cannot be checked is listed in `errors` ({table, error}) while the others are. The rows with violations are paged: `limit` (default 500, at most 5000) from `offset`; `total` counts them all. (Hand edits are also checked as they happen: see `violations` in list_changes.)",
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -9226,6 +9333,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -9679,6 +9790,10 @@ var OPERATIONS = [
                                 "type": "string",
                                 "description": "The CHECK's name (code check)."
                               },
+                              "hint": {
+                                "type": "string",
+                                "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                              },
                               "code": {
                                 "type": "string",
                                 "enum": [
@@ -10122,6 +10237,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -11205,6 +11324,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -12642,6 +12765,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -13052,6 +13179,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -13518,7 +13649,7 @@ var OPERATIONS = [
   },
   {
     "name": "add_constraint",
-    "description": 'ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,\ne.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL;\ninside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails).\nA key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}`\n(further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` /\n`not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row\nwhose parent has no parent). A link to a row that does not exist fails; on a list of links every linked\nrow must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a\nmissing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the\nvault (by path, from the row\'s note: same-named rows in two folders stay apart); renaming or moving a\nlinked row keeps them (they follow it).\nRefused while existing rows violate it (they are listed); then enforced on every write, by the same rule.\nA write that changes a linked row re-checks the rows that link to it and is refused, listing them, when\nit breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault\nthe earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too.\nrename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+    "description": 'ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,\ne.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL;\ninside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails).\nA key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}`\n(further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` /\n`not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row\nwhose parent has no parent). A link to a row that does not exist fails; on a list of links every linked\nrow must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a\nmissing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the\nvault (by path, from the row\'s note: same-named rows in two folders stay apart); renaming or moving a\nlinked row keeps them (they follow it).\nRefused while existing rows violate it (they are listed); then enforced on every write, by the same rule.\nA write that changes a linked row re-checks the rows that link to it and is refused, listing them, when\nit breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault\nthe earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too.\nrename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.\n`hint`: what to do when a row breaks the rule, in your words; a refused write puts it first in its hint, and each violation of the CHECK carries it.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -13532,6 +13663,18 @@ var OPERATIONS = [
           "additionalProperties": true,
           "type": "object"
         },
+        "hint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "What a refused write tells the agent when a row breaks this CHECK: how to fix the row. It comes first in the refusal's hint; describe_table lists it in constraint_hints."
+        },
         "dry_run": {
           "default": false,
           "type": "boolean"
@@ -13642,6 +13785,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -14040,6 +14187,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -14505,6 +14656,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -14899,6 +15054,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -15324,6 +15483,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -15736,6 +15899,10 @@ var OPERATIONS = [
                       "type": "string",
                       "description": "The CHECK's name (code check)."
                     },
+                    "hint": {
+                      "type": "string",
+                      "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                    },
                     "code": {
                       "type": "string",
                       "enum": [
@@ -16760,425 +16927,99 @@ function classOf(cp) {
   return k;
 }
 
-// src/api/otlp.ts
-var SEVERITY_NUMBER = { DEBUG: 5, INFO: 9, WARN: 13, ERROR: 17 };
-var SPAN_KIND = { internal: 1, server: 2, client: 3, producer: 4, consumer: 5 };
-var STATUS_CODE = { unset: 0, ok: 1, error: 2 };
-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 } };
+// src/api/tracing.ts
+var TRACEPARENT_HEADER = "traceparent";
+var TRACESTATE_HEADER = "tracestate";
+var TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
+function parseTraceparent(traceparent, tracestate) {
+  const m = TRACEPARENT.exec((typeof traceparent === "string" ? traceparent : "").trim().toLowerCase());
+  if (!m) return null;
+  const [, version, traceId, spanId, flags, rest] = m;
+  if (version === "ff" || version === "00" && rest !== void 0) return null;
+  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return null;
+  const state = (typeof tracestate === "string" ? tracestate : "").trim();
+  return { traceId, spanId, sampled: (parseInt(flags, 16) & 1) === 1, ...state ? { traceState: state.slice(0, 512) } : {} };
 }
-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, body });
-  if (!res.ok) throw new Error(`OTLP HTTP ${res.status}`);
-};
-function unixNano(ms) {
-  const whole = Math.floor(ms);
-  const frac = Math.round((ms - whole) * 1e6);
-  return (BigInt(whole) * BigInt(1e6) + BigInt(frac)).toString();
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
 }
-var Pb = class {
-  constructor() {
-    this.parts = [];
-  }
-  varint(v) {
-    if (typeof v === "number" && v >= 0 && v < 2 ** 31) {
-      let x2 = v;
-      while (x2 >= 128) {
-        this.parts.push(x2 & 127 | 128);
-        x2 >>>= 7;
-      }
-      this.parts.push(x2);
-      return;
-    }
-    let x = BigInt.asUintN(64, BigInt(v));
-    const b128 = BigInt(128);
-    const low7 = BigInt(127);
-    const seven = BigInt(7);
-    while (x >= b128) {
-      this.parts.push(Number(x & low7) | 128);
-      x >>= seven;
-    }
-    this.parts.push(Number(x));
-  }
-  tag(field, wire) {
-    this.varint(field << 3 | wire);
+function traceHeaders(ctx) {
+  return { [TRACEPARENT_HEADER]: formatTraceparent(ctx), ...ctx.traceState ? { [TRACESTATE_HEADER]: ctx.traceState } : {} };
+}
+function randomHex(bytes) {
+  const b = new Uint8Array(bytes);
+  const c = globalThis.crypto;
+  if (c?.getRandomValues) c.getRandomValues(b);
+  else for (let i = 0; i < bytes; i++) b[i] = Math.floor(Math.random() * 256);
+  const hex = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return /^0+$/.test(hex) ? randomHex(bytes) : hex;
+}
+var newTraceId = () => randomHex(16);
+var newSpanId = () => randomHex(8);
+var perf = globalThis.performance;
+var defaultNow = perf ? () => perf.timeOrigin + perf.now() : () => Date.now();
+var TraceSpan = class {
+  constructor(tracer, name, kind, parent, recording, attributes) {
+    this.tracer = tracer;
+    this.name = name;
+    this.kind = kind;
+    this.parent = parent;
+    this.recording = recording;
+    this.attributes = {};
+    this.events = [];
+    this.status = { code: "unset" };
+    this.ended = false;
+    this.context = {
+      traceId: parent?.traceId ?? newTraceId(),
+      spanId: newSpanId(),
+      sampled: recording,
+      ...parent?.traceState ? { traceState: parent.traceState } : {}
+    };
+    this.startMs = tracer.now();
+    this.setAttributes(attributes);
   }
-  uint(field, v) {
-    this.tag(field, 0);
-    this.varint(v);
+  setAttribute(key, value) {
+    if (value !== void 0 && value !== null) this.attributes[key] = value;
     return this;
   }
-  fixed32(field, v) {
-    this.tag(field, 5);
-    for (let i = 0; i < 4; i++) this.parts.push(v >>> 8 * i & 255);
+  setAttributes(attributes) {
+    for (const k in attributes) this.setAttribute(k, attributes[k]);
     return this;
   }
-  fixed64(field, v) {
-    this.tag(field, 1);
-    for (let i = 0; i < 8; i++) this.parts.push(Number(v >> BigInt(8 * i) & BigInt(255)));
+  addEvent(name, attributes = {}) {
+    this.events.push({ name, timeMs: this.tracer.now(), attributes });
     return this;
   }
-  double(field, v) {
-    this.tag(field, 1);
-    const b = new DataView(new ArrayBuffer(8));
-    b.setFloat64(0, v, true);
-    for (let i = 0; i < 8; i++) this.parts.push(b.getUint8(i));
-    return this;
+  /** An `exception` event, `error.type` and status ERROR. */
+  recordException(e) {
+    const type = e instanceof Error ? e.name : typeof e;
+    const message = e instanceof Error ? e.message : String(e);
+    this.addEvent("exception", { "exception.type": type, "exception.message": message, ...e instanceof Error && e.stack ? { "exception.stacktrace": e.stack.slice(0, 8192) } : {} });
+    if (!("error.type" in this.attributes)) this.attributes["error.type"] = type;
+    return this.setStatus("error", message);
   }
-  bytes(field, data) {
-    this.tag(field, 2);
-    this.varint(data.length);
-    for (const x of data) this.parts.push(x);
+  setStatus(code, message) {
+    if (this.status.code === "error" && code !== "error") return this;
+    this.status = code === "error" && message ? { code, message } : { code };
     return this;
   }
-  /** An id given in hex (trace and span ids), as bytes. */
-  hex(field, hex) {
-    const out = [];
-    for (let i = 0; i < hex.length; i += 2) out.push(parseInt(hex.slice(i, i + 2), 16));
-    return this.bytes(field, out);
-  }
-  string(field, s) {
-    return this.bytes(field, new TextEncoder().encode(s));
-  }
-  message(field, m) {
-    return this.bytes(field, m.finish());
-  }
-  finish() {
-    return Uint8Array.from(this.parts);
-  }
-};
-function pbValue(v) {
-  if (typeof v === "string") return new Pb().string(1, v);
-  if (typeof v === "boolean") return new Pb().uint(2, v ? 1 : 0);
-  return Number.isInteger(v) ? new Pb().uint(3, BigInt(v)) : new Pb().double(4, v);
-}
-function pbAttrs(m, field, a) {
-  for (const [k, v] of Object.entries(a)) {
-    if (v === void 0 || v === null) continue;
-    m.message(field, new Pb().string(1, k).message(2, pbValue(v)));
-  }
-  return m;
-}
-var OtlpBatcher = class {
-  constructor(o, path, maxBatch) {
-    this.o = o;
-    this.path = path;
-    this.maxBatch = maxBatch;
-    this.buffer = [];
-    this.inflight = Promise.resolve();
-    this.timer = null;
-    /** Items sent, and items lost because the collector did not take them (or the buffer was full). */
-    this.sent = 0;
-    this.dropped = 0;
-    const every = o.flushMs ?? 5e3;
-    if (every > 0) {
-      this.timer = setInterval(() => void this.flush(), every);
-      this.timer.unref?.();
-    }
-  }
-  push(items) {
-    const room = this.maxBatch * 8 - this.buffer.length;
-    if (room < items.length) this.dropped += items.length - Math.max(room, 0);
-    for (let i = 0; i < Math.min(items.length, Math.max(room, 0)); i++) this.buffer.push(items[i]);
-    if (this.buffer.length >= this.maxBatch) void this.flush();
-  }
-  resource() {
-    return { "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource };
-  }
-  /** Send what is buffered. Never rejects. */
-  flush() {
-    if (this.buffer.length === 0) return this.inflight;
-    const send = this.o.send ?? fetchSend;
-    const url = `${this.o.endpoint.replace(/\/+$/, "")}${this.path}`;
-    const protobuf = (this.o.protocol ?? "http/protobuf") === "http/protobuf";
-    const headers = { "Content-Type": protobuf ? "application/x-protobuf" : "application/json", ...this.o.headers ?? {} };
-    while (this.buffer.length > 0) {
-      const batch = this.buffer.splice(0, this.maxBatch);
-      let body;
-      try {
-        body = this.encode(batch, protobuf);
-      } catch {
-        this.dropped += batch.length;
-        continue;
-      }
-      this.inflight = this.inflight.then(
-        () => send(url, body, 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();
-  }
-};
-var OtlpLogExporter = class extends OtlpBatcher {
-  constructor(o) {
-    super(o, "/v1/logs", o.maxBatch ?? 50);
-  }
-  /** Buffer a record; `context`: the span it was made in (its trace and span id go with it). */
-  log(severity, body, attributes = {}, context) {
-    const ms = (this.o.now ?? Date.now)();
-    this.push([{ timeUnixNano: `${Math.round(ms)}000000`, severity, body, attributes, ...context ? { context } : {} }]);
-  }
-  encode(batch, protobuf) {
-    const resource = this.resource();
-    if (protobuf) return this.protobuf(resource, batch);
-    return JSON.stringify({
-      resourceLogs: [
-        {
-          resource: { attributes: attrs(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),
-                ...r.context ? { traceId: r.context.traceId, spanId: r.context.spanId, flags: r.context.sampled ? 1 : 0 } : {}
-              }))
-            }
-          ]
-        }
-      ]
-    });
-  }
-  protobuf(resource, batch) {
-    const scope = new Pb().message(1, new Pb().string(1, this.o.serviceName));
-    for (const r of batch) {
-      const t = BigInt(r.timeUnixNano);
-      const rec = new Pb().fixed64(1, t).uint(2, SEVERITY_NUMBER[r.severity]).string(3, r.severity).message(5, new Pb().string(1, r.body));
-      pbAttrs(rec, 6, r.attributes);
-      if (r.context) rec.fixed32(8, r.context.sampled ? 1 : 0).hex(9, r.context.traceId).hex(10, r.context.spanId);
-      rec.fixed64(11, t);
-      scope.message(2, rec);
-    }
-    const resourceLogs = new Pb().message(1, pbAttrs(new Pb(), 1, resource)).message(2, scope);
-    return new Pb().message(1, resourceLogs).finish();
-  }
-};
-var OtlpTraceExporter = class extends OtlpBatcher {
-  constructor(o) {
-    super(o, "/v1/traces", o.maxBatch ?? 512);
-  }
-  /** Buffer finished spans (sent with the next batch). Never throws. */
-  export(spans) {
-    this.push(Array.isArray(spans) ? spans : [spans]);
-  }
-  encode(batch, protobuf) {
-    const resource = this.resource();
-    if (protobuf) return this.protobuf(resource, batch);
-    return JSON.stringify({
-      resourceSpans: [
-        {
-          resource: { attributes: attrs(resource) },
-          scopeSpans: [
-            {
-              scope: { name: this.o.serviceName, ...this.o.serviceVersion ? { version: this.o.serviceVersion } : {} },
-              spans: batch.map((s) => ({
-                traceId: s.traceId,
-                spanId: s.spanId,
-                ...s.parentSpanId ? { parentSpanId: s.parentSpanId } : {},
-                ...s.traceState ? { traceState: s.traceState } : {},
-                flags: 1,
-                name: s.name,
-                kind: SPAN_KIND[s.kind],
-                startTimeUnixNano: unixNano(s.startMs),
-                endTimeUnixNano: unixNano(s.endMs),
-                attributes: attrs(s.attributes),
-                ...s.droppedAttributes ? { droppedAttributesCount: s.droppedAttributes } : {},
-                events: s.events.map((e) => ({ timeUnixNano: unixNano(e.timeMs), name: e.name, attributes: attrs(e.attributes) })),
-                ...s.droppedEvents ? { droppedEventsCount: s.droppedEvents } : {},
-                status: { code: STATUS_CODE[s.status.code], ...s.status.message ? { message: s.status.message } : {} }
-              }))
-            }
-          ]
-        }
-      ]
-    });
-  }
-  protobuf(resource, batch) {
-    const scopeInfo = new Pb().string(1, this.o.serviceName);
-    if (this.o.serviceVersion) scopeInfo.string(2, this.o.serviceVersion);
-    const scope = new Pb().message(1, scopeInfo);
-    for (const s of batch) {
-      const span = new Pb().hex(1, s.traceId).hex(2, s.spanId);
-      if (s.traceState) span.string(3, s.traceState);
-      if (s.parentSpanId) span.hex(4, s.parentSpanId);
-      span.string(5, s.name).uint(6, SPAN_KIND[s.kind]).fixed64(7, BigInt(unixNano(s.startMs))).fixed64(8, BigInt(unixNano(s.endMs)));
-      pbAttrs(span, 9, s.attributes);
-      if (s.droppedAttributes) span.uint(10, s.droppedAttributes);
-      for (const e of s.events) span.message(11, pbAttrs(new Pb().fixed64(1, BigInt(unixNano(e.timeMs))).string(2, e.name), 3, e.attributes));
-      if (s.droppedEvents) span.uint(12, s.droppedEvents);
-      const status = new Pb();
-      if (s.status.message) status.string(2, s.status.message);
-      if (s.status.code !== "unset") status.uint(3, STATUS_CODE[s.status.code]);
-      span.message(15, status).fixed32(16, 1);
-      scope.message(2, span);
-    }
-    const resourceSpans = new Pb().message(1, pbAttrs(new Pb(), 1, resource)).message(2, scope);
-    return new Pb().message(1, resourceSpans).finish();
-  }
-};
-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;
-}
-var parseResourceAttributes = parseOtlpHeaders;
-var truthy = (v) => (v ?? "").trim().toLowerCase() === "true";
-function otlpFromEnv(env, defaults) {
-  return fromEnv(env, defaults, "LOGS", "logs");
-}
-function otlpTracesFromEnv(env, defaults) {
-  return fromEnv(env, defaults, "TRACES", "traces");
-}
-function fromEnv(env, defaults, signal, path) {
-  if (truthy(env.OTEL_SDK_DISABLED) || (env[`OTEL_${signal}_EXPORTER`] ?? "").trim().toLowerCase() === "none") return null;
-  const own = env[`OTEL_EXPORTER_OTLP_${signal}_ENDPOINT`]?.trim();
-  const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
-  const endpoint = own ? own.replace(new RegExp(`/v1/${path}/?$`), "") : base;
-  if (!endpoint) return null;
-  const protocol = otlpProtocol(env[`OTEL_EXPORTER_OTLP_${signal}_PROTOCOL`] ?? env.OTEL_EXPORTER_OTLP_PROTOCOL);
-  const resource = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
-  return {
-    endpoint,
-    serviceName: env.OTEL_SERVICE_NAME?.trim() || resource["service.name"] || defaults.serviceName,
-    ...defaults.serviceVersion ? { serviceVersion: defaults.serviceVersion } : {},
-    ...protocol ? { protocol } : {},
-    ...Object.keys(resource).length ? { resource } : {},
-    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env[`OTEL_EXPORTER_OTLP_${signal}_HEADERS`]) }
-  };
-}
-function samplerRatioFromEnv(env) {
-  const sampler = (env.OTEL_TRACES_SAMPLER ?? "").trim().toLowerCase().replace(/^parentbased_/, "");
-  if (sampler === "always_on") return 1;
-  if (sampler === "always_off") return 0;
-  if (sampler !== "traceidratio") return void 0;
-  const arg = Number((env.OTEL_TRACES_SAMPLER_ARG ?? "").trim() || "1");
-  return Number.isFinite(arg) && arg >= 0 && arg <= 1 ? arg : 1;
-}
-function otlpProtocol(v) {
-  const p = (v ?? "").trim().toLowerCase();
-  return p === "http/protobuf" || p === "http/json" ? p : void 0;
-}
-
-// src/api/tracing.ts
-var TRACEPARENT_HEADER = "traceparent";
-var TRACESTATE_HEADER = "tracestate";
-var TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
-function parseTraceparent(traceparent, tracestate) {
-  const m = TRACEPARENT.exec((typeof traceparent === "string" ? traceparent : "").trim().toLowerCase());
-  if (!m) return null;
-  const [, version, traceId, spanId, flags, rest] = m;
-  if (version === "ff" || version === "00" && rest !== void 0) return null;
-  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return null;
-  const state = (typeof tracestate === "string" ? tracestate : "").trim();
-  return { traceId, spanId, sampled: (parseInt(flags, 16) & 1) === 1, ...state ? { traceState: state.slice(0, 512) } : {} };
-}
-function formatTraceparent(ctx) {
-  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
-}
-function traceHeaders(ctx) {
-  return { [TRACEPARENT_HEADER]: formatTraceparent(ctx), ...ctx.traceState ? { [TRACESTATE_HEADER]: ctx.traceState } : {} };
-}
-function randomHex(bytes) {
-  const b = new Uint8Array(bytes);
-  const c = globalThis.crypto;
-  if (c?.getRandomValues) c.getRandomValues(b);
-  else for (let i = 0; i < bytes; i++) b[i] = Math.floor(Math.random() * 256);
-  const hex = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
-  return /^0+$/.test(hex) ? randomHex(bytes) : hex;
-}
-var newTraceId = () => randomHex(16);
-var newSpanId = () => randomHex(8);
-var perf = globalThis.performance;
-var defaultNow = perf ? () => perf.timeOrigin + perf.now() : () => Date.now();
-var TraceSpan = class {
-  constructor(tracer, name, kind, parent, recording, attributes) {
-    this.tracer = tracer;
-    this.name = name;
-    this.kind = kind;
-    this.parent = parent;
-    this.recording = recording;
-    this.attributes = {};
-    this.events = [];
-    this.status = { code: "unset" };
-    this.ended = false;
-    this.context = {
-      traceId: parent?.traceId ?? newTraceId(),
-      spanId: newSpanId(),
-      sampled: recording,
-      ...parent?.traceState ? { traceState: parent.traceState } : {}
-    };
-    this.startMs = tracer.now();
-    this.setAttributes(attributes);
-  }
-  setAttribute(key, value) {
-    if (value !== void 0 && value !== null) this.attributes[key] = value;
-    return this;
-  }
-  setAttributes(attributes) {
-    for (const k in attributes) this.setAttribute(k, attributes[k]);
-    return this;
-  }
-  addEvent(name, attributes = {}) {
-    this.events.push({ name, timeMs: this.tracer.now(), attributes });
-    return this;
-  }
-  /** An `exception` event, `error.type` and status ERROR. */
-  recordException(e) {
-    const type = e instanceof Error ? e.name : typeof e;
-    const message = e instanceof Error ? e.message : String(e);
-    this.addEvent("exception", { "exception.type": type, "exception.message": message, ...e instanceof Error && e.stack ? { "exception.stacktrace": e.stack.slice(0, 8192) } : {} });
-    if (!("error.type" in this.attributes)) this.attributes["error.type"] = type;
-    return this.setStatus("error", message);
-  }
-  setStatus(code, message) {
-    if (this.status.code === "error" && code !== "error") return this;
-    this.status = code === "error" && message ? { code, message } : { code };
-    return this;
-  }
-  end() {
-    if (this.ended) return;
-    this.ended = true;
-    if (!this.recording) return;
-    this.tracer.send({
-      traceId: this.context.traceId,
-      spanId: this.context.spanId,
-      ...this.parent ? { parentSpanId: this.parent.spanId } : {},
-      ...this.context.traceState ? { traceState: this.context.traceState } : {},
-      name: this.name,
-      kind: this.kind,
-      startMs: this.startMs,
-      endMs: this.tracer.now(),
-      attributes: this.attributes,
-      events: this.events,
-      status: this.status
-    });
+  end() {
+    if (this.ended) return;
+    this.ended = true;
+    if (!this.recording) return;
+    this.tracer.send({
+      traceId: this.context.traceId,
+      spanId: this.context.spanId,
+      ...this.parent ? { parentSpanId: this.parent.spanId } : {},
+      ...this.context.traceState ? { traceState: this.context.traceState } : {},
+      name: this.name,
+      kind: this.kind,
+      startMs: this.startMs,
+      endMs: this.tracer.now(),
+      attributes: this.attributes,
+      events: this.events,
+      status: this.status
+    });
   }
 };
 var Tracer = class {
@@ -17251,104 +17092,435 @@ function clientSpan(tracer, method, url, parent) {
       "server.address": target?.hostname,
       "server.port": target ? Number(target.port || (target.protocol === "https:" ? 443 : 80)) : void 0
     }
-  });
-}
-function parse(text) {
-  try {
-    return text.trim() ? JSON.parse(text) : void 0;
-  } catch {
-    return void 0;
+  });
+}
+function parse(text) {
+  try {
+    return text.trim() ? JSON.parse(text) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function trimTrailingSlashes(s) {
+  let end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
+  return end === s.length ? s : s.slice(0, end);
+}
+var DatanotesClient = class {
+  constructor(o) {
+    this.o = o;
+    this.url = trimTrailingSlashes(o.url);
+    this.send = o.transport ?? fetchTransport;
+  }
+  /** The parent of a request: the call's own `trace`, else the client's. */
+  parentOf(trace) {
+    const given = trace ?? (typeof this.o.trace === "function" ? this.o.trace() : this.o.trace);
+    return typeof given === "string" ? parseTraceparent(given) : given ?? null;
+  }
+  /**
+   * Send a request; the answer's status, its JSON (when it is JSON) and its text. `trace`: the
+   * trace this request continues (over the client's `trace` option).
+   */
+  async request(method, path, body, opts = {}) {
+    if (!this.url) throw new DatanotesError("engine address not set", "unreachable");
+    if (!this.o.token) throw new DatanotesError("token not set", "auth");
+    const actor = opts.actor ?? this.o.actor;
+    const parent = this.parentOf(opts.trace);
+    const span = this.o.tracer ? clientSpan(this.o.tracer, method, `${this.url}${path}`, parent) : void 0;
+    const sent = span?.context ?? parent;
+    let res;
+    try {
+      res = await this.send({
+        url: `${this.url}${path}`,
+        method,
+        headers: {
+          Authorization: `Bearer ${this.o.token}`,
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {},
+          ...opts.accept ? { Accept: opts.accept } : {},
+          ...actor && Object.keys(actor).length ? { [ACTOR_HEADER]: JSON.stringify(actor) } : {},
+          ...sent ? traceHeaders(sent) : {}
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      });
+    } catch (e) {
+      span?.recordException(e);
+      span?.end();
+      throw new DatanotesError(`engine unreachable at ${this.url}: ${e instanceof Error ? e.message : String(e)}`, "unreachable");
+    }
+    span?.setAttribute("http.response.status_code", res.status);
+    if (res.status >= 400) span?.setAttribute("error.type", String(res.status));
+    if (res.status >= 500) span?.setStatus("error", `HTTP ${res.status}`);
+    span?.end();
+    if (res.status === 401) throw new DatanotesError("token refused by the engine", "auth", 401);
+    const json = parse(res.text);
+    const unreachable = res.status === 0 || res.status === 502 || res.status === 504 || res.status === 503 && !isEngineAnswer(json);
+    if (unreachable) throw new DatanotesError(`engine unreachable at ${this.url} (HTTP ${res.status})`, "unreachable", res.status);
+    return { status: res.status, json, text: res.text };
+  }
+  /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
+  async post(route, body = {}, actor) {
+    const r = await this.request("POST", `/datanotes${route}`, body, actor ? { actor } : {});
+    if (r.status >= 400) throw Object.assign(new DatanotesError(resultOf(r.status, r.json, r.text).value, "http", r.status), guidanceIn(r.json));
+    return r.json;
+  }
+  /**
+   * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
+   * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
+   * with the same message the engine gives.
+   */
+  async call(name, args = {}, actor, options = {}) {
+    let req;
+    try {
+      req = operationRequest(name, args);
+    } catch (e) {
+      if (e instanceof OperationInputError) return { ok: false, value: e.message };
+      throw e;
+    }
+    const problem = checkArguments(name, args);
+    if (problem) return { ok: false, value: guidedText(problem.message, problem) };
+    const r = await this.request(req.method, req.path, req.body, { ...actor ? { actor } : {}, ...options.trace ? { trace: options.trace } : {} });
+    return resultOf(r.status, r.json, r.text);
+  }
+  /** True when the engine answers `GET /` (no token needed). */
+  async ping() {
+    try {
+      const r = await this.send({ url: `${this.url}/`, method: "GET", headers: {} });
+      return r.status === 200;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Record an agent's tool call in the change feed (what MCP servers report). Answers what the
+   * engine said: `takes_summary` when it records a `value` sent cut with its `summary`.
+   */
+  async recordToolCall(call, actor) {
+    return this.post("/tool-calls/record/", call, actor);
+  }
+};
+
+// src/api/otlp.ts
+var SEVERITY_NUMBER = { DEBUG: 5, INFO: 9, WARN: 13, ERROR: 17 };
+var SPAN_KIND = { internal: 1, server: 2, client: 3, producer: 4, consumer: 5 };
+var STATUS_CODE = { unset: 0, ok: 1, error: 2 };
+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, body });
+  if (!res.ok) throw new Error(`OTLP HTTP ${res.status}`);
+};
+function unixNano(ms) {
+  const whole = Math.floor(ms);
+  const frac = Math.round((ms - whole) * 1e6);
+  return (BigInt(whole) * BigInt(1e6) + BigInt(frac)).toString();
+}
+var Pb = class {
+  constructor() {
+    this.parts = [];
+  }
+  varint(v) {
+    if (typeof v === "number" && v >= 0 && v < 2 ** 31) {
+      let x2 = v;
+      while (x2 >= 128) {
+        this.parts.push(x2 & 127 | 128);
+        x2 >>>= 7;
+      }
+      this.parts.push(x2);
+      return;
+    }
+    let x = BigInt.asUintN(64, BigInt(v));
+    const b128 = BigInt(128);
+    const low7 = BigInt(127);
+    const seven = BigInt(7);
+    while (x >= b128) {
+      this.parts.push(Number(x & low7) | 128);
+      x >>= seven;
+    }
+    this.parts.push(Number(x));
+  }
+  tag(field, wire) {
+    this.varint(field << 3 | wire);
+  }
+  uint(field, v) {
+    this.tag(field, 0);
+    this.varint(v);
+    return this;
+  }
+  fixed32(field, v) {
+    this.tag(field, 5);
+    for (let i = 0; i < 4; i++) this.parts.push(v >>> 8 * i & 255);
+    return this;
+  }
+  fixed64(field, v) {
+    this.tag(field, 1);
+    for (let i = 0; i < 8; i++) this.parts.push(Number(v >> BigInt(8 * i) & BigInt(255)));
+    return this;
+  }
+  double(field, v) {
+    this.tag(field, 1);
+    const b = new DataView(new ArrayBuffer(8));
+    b.setFloat64(0, v, true);
+    for (let i = 0; i < 8; i++) this.parts.push(b.getUint8(i));
+    return this;
+  }
+  bytes(field, data) {
+    this.tag(field, 2);
+    this.varint(data.length);
+    for (const x of data) this.parts.push(x);
+    return this;
+  }
+  /** An id given in hex (trace and span ids), as bytes. */
+  hex(field, hex) {
+    const out = [];
+    for (let i = 0; i < hex.length; i += 2) out.push(parseInt(hex.slice(i, i + 2), 16));
+    return this.bytes(field, out);
+  }
+  string(field, s) {
+    return this.bytes(field, new TextEncoder().encode(s));
+  }
+  message(field, m) {
+    return this.bytes(field, m.finish());
+  }
+  finish() {
+    return Uint8Array.from(this.parts);
+  }
+};
+function pbValue(v) {
+  if (typeof v === "string") return new Pb().string(1, v);
+  if (typeof v === "boolean") return new Pb().uint(2, v ? 1 : 0);
+  return Number.isInteger(v) ? new Pb().uint(3, BigInt(v)) : new Pb().double(4, v);
+}
+function pbAttrs(m, field, a) {
+  for (const [k, v] of Object.entries(a)) {
+    if (v === void 0 || v === null) continue;
+    m.message(field, new Pb().string(1, k).message(2, pbValue(v)));
+  }
+  return m;
+}
+var OtlpBatcher = class {
+  constructor(o, path, maxBatch) {
+    this.o = o;
+    this.path = path;
+    this.maxBatch = maxBatch;
+    this.buffer = [];
+    this.inflight = Promise.resolve();
+    this.timer = null;
+    /** Items sent, and items lost because the collector did not take them (or the buffer was full). */
+    this.sent = 0;
+    this.dropped = 0;
+    const every = o.flushMs ?? 5e3;
+    if (every > 0) {
+      this.timer = setInterval(() => void this.flush(), every);
+      this.timer.unref?.();
+    }
+  }
+  push(items) {
+    const room = this.maxBatch * 8 - this.buffer.length;
+    if (room < items.length) this.dropped += items.length - Math.max(room, 0);
+    for (let i = 0; i < Math.min(items.length, Math.max(room, 0)); i++) this.buffer.push(items[i]);
+    if (this.buffer.length >= this.maxBatch) void this.flush();
+  }
+  resource() {
+    return { "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource };
+  }
+  /** Send what is buffered. Never rejects. */
+  flush() {
+    if (this.buffer.length === 0) return this.inflight;
+    const send = this.o.send ?? fetchSend;
+    const url = `${trimTrailingSlashes(this.o.endpoint)}${this.path}`;
+    const protobuf = (this.o.protocol ?? "http/protobuf") === "http/protobuf";
+    const headers = { "Content-Type": protobuf ? "application/x-protobuf" : "application/json", ...this.o.headers ?? {} };
+    while (this.buffer.length > 0) {
+      const batch = this.buffer.splice(0, this.maxBatch);
+      let body;
+      try {
+        body = this.encode(batch, protobuf);
+      } catch {
+        this.dropped += batch.length;
+        continue;
+      }
+      this.inflight = this.inflight.then(
+        () => send(url, body, headers).then(
+          () => void (this.sent += batch.length),
+          () => void (this.dropped += batch.length)
+        )
+      );
+    }
+    return this.inflight;
   }
-}
-var DatanotesClient = class {
+  /** Stop the timer and send what is left. */
+  async close() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    await this.flush();
+  }
+};
+var OtlpLogExporter = class extends OtlpBatcher {
   constructor(o) {
-    this.o = o;
-    this.url = o.url.replace(/\/+$/, "");
-    this.send = o.transport ?? fetchTransport;
+    super(o, "/v1/logs", o.maxBatch ?? 50);
   }
-  /** The parent of a request: the call's own `trace`, else the client's. */
-  parentOf(trace) {
-    const given = trace ?? (typeof this.o.trace === "function" ? this.o.trace() : this.o.trace);
-    return typeof given === "string" ? parseTraceparent(given) : given ?? null;
+  /** Buffer a record; `context`: the span it was made in (its trace and span id go with it). */
+  log(severity, body, attributes = {}, context) {
+    const ms = (this.o.now ?? Date.now)();
+    this.push([{ timeUnixNano: `${Math.round(ms)}000000`, severity, body, attributes, ...context ? { context } : {} }]);
   }
-  /**
-   * Send a request; the answer's status, its JSON (when it is JSON) and its text. `trace`: the
-   * trace this request continues (over the client's `trace` option).
-   */
-  async request(method, path, body, opts = {}) {
-    if (!this.url) throw new DatanotesError("engine address not set", "unreachable");
-    if (!this.o.token) throw new DatanotesError("token not set", "auth");
-    const actor = opts.actor ?? this.o.actor;
-    const parent = this.parentOf(opts.trace);
-    const span = this.o.tracer ? clientSpan(this.o.tracer, method, `${this.url}${path}`, parent) : void 0;
-    const sent = span?.context ?? parent;
-    let res;
-    try {
-      res = await this.send({
-        url: `${this.url}${path}`,
-        method,
-        headers: {
-          Authorization: `Bearer ${this.o.token}`,
-          ...body !== void 0 ? { "Content-Type": "application/json" } : {},
-          ...opts.accept ? { Accept: opts.accept } : {},
-          ...actor && Object.keys(actor).length ? { [ACTOR_HEADER]: JSON.stringify(actor) } : {},
-          ...sent ? traceHeaders(sent) : {}
-        },
-        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
-      });
-    } catch (e) {
-      span?.recordException(e);
-      span?.end();
-      throw new DatanotesError(`engine unreachable at ${this.url}: ${e instanceof Error ? e.message : String(e)}`, "unreachable");
+  encode(batch, protobuf) {
+    const resource = this.resource();
+    if (protobuf) return this.protobuf(resource, batch);
+    return JSON.stringify({
+      resourceLogs: [
+        {
+          resource: { attributes: attrs(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),
+                ...r.context ? { traceId: r.context.traceId, spanId: r.context.spanId, flags: r.context.sampled ? 1 : 0 } : {}
+              }))
+            }
+          ]
+        }
+      ]
+    });
+  }
+  protobuf(resource, batch) {
+    const scope = new Pb().message(1, new Pb().string(1, this.o.serviceName));
+    for (const r of batch) {
+      const t = BigInt(r.timeUnixNano);
+      const rec = new Pb().fixed64(1, t).uint(2, SEVERITY_NUMBER[r.severity]).string(3, r.severity).message(5, new Pb().string(1, r.body));
+      pbAttrs(rec, 6, r.attributes);
+      if (r.context) rec.fixed32(8, r.context.sampled ? 1 : 0).hex(9, r.context.traceId).hex(10, r.context.spanId);
+      rec.fixed64(11, t);
+      scope.message(2, rec);
     }
-    span?.setAttribute("http.response.status_code", res.status);
-    if (res.status >= 400) span?.setAttribute("error.type", String(res.status));
-    if (res.status >= 500) span?.setStatus("error", `HTTP ${res.status}`);
-    span?.end();
-    if (res.status === 401) throw new DatanotesError("token refused by the engine", "auth", 401);
-    const json = parse(res.text);
-    const unreachable = res.status === 0 || res.status === 502 || res.status === 504 || res.status === 503 && !isEngineAnswer(json);
-    if (unreachable) throw new DatanotesError(`engine unreachable at ${this.url} (HTTP ${res.status})`, "unreachable", res.status);
-    return { status: res.status, json, text: res.text };
+    const resourceLogs = new Pb().message(1, pbAttrs(new Pb(), 1, resource)).message(2, scope);
+    return new Pb().message(1, resourceLogs).finish();
   }
-  /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
-  async post(route, body = {}, actor) {
-    const r = await this.request("POST", `/datanotes${route}`, body, actor ? { actor } : {});
-    if (r.status >= 400) throw Object.assign(new DatanotesError(resultOf(r.status, r.json, r.text).value, "http", r.status), guidanceIn(r.json));
-    return r.json;
+};
+var OtlpTraceExporter = class extends OtlpBatcher {
+  constructor(o) {
+    super(o, "/v1/traces", o.maxBatch ?? 512);
   }
-  /**
-   * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
-   * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
-   * with the same message the engine gives.
-   */
-  async call(name, args = {}, actor, options = {}) {
-    let req;
-    try {
-      req = operationRequest(name, args);
-    } catch (e) {
-      if (e instanceof OperationInputError) return { ok: false, value: e.message };
-      throw e;
+  /** Buffer finished spans (sent with the next batch). Never throws. */
+  export(spans) {
+    this.push(Array.isArray(spans) ? spans : [spans]);
+  }
+  encode(batch, protobuf) {
+    const resource = this.resource();
+    if (protobuf) return this.protobuf(resource, batch);
+    return JSON.stringify({
+      resourceSpans: [
+        {
+          resource: { attributes: attrs(resource) },
+          scopeSpans: [
+            {
+              scope: { name: this.o.serviceName, ...this.o.serviceVersion ? { version: this.o.serviceVersion } : {} },
+              spans: batch.map((s) => ({
+                traceId: s.traceId,
+                spanId: s.spanId,
+                ...s.parentSpanId ? { parentSpanId: s.parentSpanId } : {},
+                ...s.traceState ? { traceState: s.traceState } : {},
+                flags: 1,
+                name: s.name,
+                kind: SPAN_KIND[s.kind],
+                startTimeUnixNano: unixNano(s.startMs),
+                endTimeUnixNano: unixNano(s.endMs),
+                attributes: attrs(s.attributes),
+                ...s.droppedAttributes ? { droppedAttributesCount: s.droppedAttributes } : {},
+                events: s.events.map((e) => ({ timeUnixNano: unixNano(e.timeMs), name: e.name, attributes: attrs(e.attributes) })),
+                ...s.droppedEvents ? { droppedEventsCount: s.droppedEvents } : {},
+                status: { code: STATUS_CODE[s.status.code], ...s.status.message ? { message: s.status.message } : {} }
+              }))
+            }
+          ]
+        }
+      ]
+    });
+  }
+  protobuf(resource, batch) {
+    const scopeInfo = new Pb().string(1, this.o.serviceName);
+    if (this.o.serviceVersion) scopeInfo.string(2, this.o.serviceVersion);
+    const scope = new Pb().message(1, scopeInfo);
+    for (const s of batch) {
+      const span = new Pb().hex(1, s.traceId).hex(2, s.spanId);
+      if (s.traceState) span.string(3, s.traceState);
+      if (s.parentSpanId) span.hex(4, s.parentSpanId);
+      span.string(5, s.name).uint(6, SPAN_KIND[s.kind]).fixed64(7, BigInt(unixNano(s.startMs))).fixed64(8, BigInt(unixNano(s.endMs)));
+      pbAttrs(span, 9, s.attributes);
+      if (s.droppedAttributes) span.uint(10, s.droppedAttributes);
+      for (const e of s.events) span.message(11, pbAttrs(new Pb().fixed64(1, BigInt(unixNano(e.timeMs))).string(2, e.name), 3, e.attributes));
+      if (s.droppedEvents) span.uint(12, s.droppedEvents);
+      const status = new Pb();
+      if (s.status.message) status.string(2, s.status.message);
+      if (s.status.code !== "unset") status.uint(3, STATUS_CODE[s.status.code]);
+      span.message(15, status).fixed32(16, 1);
+      scope.message(2, span);
     }
-    const problem = checkArguments(name, args);
-    if (problem) return { ok: false, value: guidedText(problem.message, problem) };
-    const r = await this.request(req.method, req.path, req.body, { ...actor ? { actor } : {}, ...options.trace ? { trace: options.trace } : {} });
-    return resultOf(r.status, r.json, r.text);
+    const resourceSpans = new Pb().message(1, pbAttrs(new Pb(), 1, resource)).message(2, scope);
+    return new Pb().message(1, resourceSpans).finish();
   }
-  /** True when the engine answers `GET /` (no token needed). */
-  async ping() {
+};
+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 {
-      const r = await this.send({ url: `${this.url}/`, method: "GET", headers: {} });
-      return r.status === 200;
+      out[key] = decodeURIComponent(value);
     } catch {
-      return false;
+      out[key] = value;
     }
   }
-  /**
-   * Record an agent's tool call in the change feed (what MCP servers report). Answers what the
-   * engine said: `takes_summary` when it records a `value` sent cut with its `summary`.
-   */
-  async recordToolCall(call, actor) {
-    return this.post("/tool-calls/record/", call, actor);
-  }
-};
+  return out;
+}
+var parseResourceAttributes = parseOtlpHeaders;
+var truthy = (v) => (v ?? "").trim().toLowerCase() === "true";
+function otlpFromEnv(env, defaults) {
+  return fromEnv(env, defaults, "LOGS", "logs");
+}
+function otlpTracesFromEnv(env, defaults) {
+  return fromEnv(env, defaults, "TRACES", "traces");
+}
+function fromEnv(env, defaults, signal, path) {
+  if (truthy(env.OTEL_SDK_DISABLED) || (env[`OTEL_${signal}_EXPORTER`] ?? "").trim().toLowerCase() === "none") return null;
+  const own = env[`OTEL_EXPORTER_OTLP_${signal}_ENDPOINT`]?.trim();
+  const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+  const endpoint = own ? own.replace(new RegExp(`/v1/${path}/?$`), "") : base;
+  if (!endpoint) return null;
+  const protocol = otlpProtocol(env[`OTEL_EXPORTER_OTLP_${signal}_PROTOCOL`] ?? env.OTEL_EXPORTER_OTLP_PROTOCOL);
+  const resource = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
+  return {
+    endpoint,
+    serviceName: env.OTEL_SERVICE_NAME?.trim() || resource["service.name"] || defaults.serviceName,
+    ...defaults.serviceVersion ? { serviceVersion: defaults.serviceVersion } : {},
+    ...protocol ? { protocol } : {},
+    ...Object.keys(resource).length ? { resource } : {},
+    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env[`OTEL_EXPORTER_OTLP_${signal}_HEADERS`]) }
+  };
+}
+function samplerRatioFromEnv(env) {
+  const sampler = (env.OTEL_TRACES_SAMPLER ?? "").trim().toLowerCase().replace(/^parentbased_/, "");
+  if (sampler === "always_on") return 1;
+  if (sampler === "always_off") return 0;
+  if (sampler !== "traceidratio") return void 0;
+  const arg = Number((env.OTEL_TRACES_SAMPLER_ARG ?? "").trim() || "1");
+  return Number.isFinite(arg) && arg >= 0 && arg <= 1 ? arg : 1;
+}
+function otlpProtocol(v) {
+  const p = (v ?? "").trim().toLowerCase();
+  return p === "http/protobuf" || p === "http/json" ? p : void 0;
+}