datanotes 3.0.0 → 3.2.0

package/dist/api/index.cjs

@@ -28,21 +28,33 @@ __export(index_exports, {
   OPERATIONS: () => OPERATIONS,
   OperationInputError: () => OperationInputError,
   OtlpLogExporter: () => OtlpLogExporter,
+  OtlpTraceExporter: () => OtlpTraceExporter,
   ROUTE_PREFIX: () => ROUTE_PREFIX,
+  TRACEPARENT_HEADER: () => TRACEPARENT_HEADER,
+  TRACESTATE_HEADER: () => TRACESTATE_HEADER,
+  TraceSpan: () => TraceSpan,
+  Tracer: () => Tracer,
   argumentsOf: () => argumentsOf,
   checkArguments: () => checkArguments,
   describeBatch: () => describeBatch,
   describeRefusal: () => describeRefusal,
   estimateTokens: () => estimateTokens,
   fetchTransport: () => fetchTransport,
+  formatTraceparent: () => formatTraceparent,
   guidanceIn: () => guidanceIn,
   guidedText: () => guidedText,
+  newSpanId: () => newSpanId,
+  newTraceId: () => newTraceId,
   operationRequest: () => operationRequest,
   operationRoute: () => operationRoute,
   otlpFromEnv: () => otlpFromEnv,
+  otlpTracesFromEnv: () => otlpTracesFromEnv,
   parseOtlpHeaders: () => parseOtlpHeaders,
+  parseTraceparent: () => parseTraceparent,
   resultOf: () => resultOf,
-  toolDocs: () => toolDocs
+  samplerRatioFromEnv: () => samplerRatioFromEnv,
+  toolDocs: () => toolDocs,
+  traceHeaders: () => traceHeaders
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -378,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": {
@@ -501,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.",
@@ -610,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."
@@ -643,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": {
@@ -804,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": [
             {
@@ -941,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": [
@@ -1350,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": [
@@ -1629,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": {
@@ -1750,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": [
@@ -2152,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": [
@@ -2551,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": [
@@ -2830,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": {
@@ -2955,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": [
@@ -3234,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": {
@@ -3384,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": [
             {
@@ -3544,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": [
@@ -4000,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": [
@@ -4401,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": [
@@ -5463,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": [
@@ -5869,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": [
@@ -6148,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": {
@@ -6303,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": [
@@ -6741,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": [
@@ -7254,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": [
@@ -7685,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": [
@@ -8133,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": [
@@ -8593,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": [
@@ -9101,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": {
@@ -9214,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": [
@@ -9667,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": [
@@ -10110,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": [
@@ -11193,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": [
@@ -12630,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": [
@@ -13040,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": [
@@ -13506,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": {
@@ -13520,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"
@@ -13630,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": [
@@ -14028,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": [
@@ -14493,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": [
@@ -14887,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": [
@@ -15312,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": [
@@ -15724,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": [
@@ -16003,7 +16182,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_neighbors",
-    "description": 'Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,\nbacklinks), with counts per edge label. `direction`: out, in or both (default).\n\n`from_nodes` selects the notes: `{"paths": [...]}` and/or `{"table": ..., "where": {...}}`.\nEdges are labelled with their link column (`people`, `event`, \u2026) or `link` for other links.',
+    "description": 'Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,\nbacklinks), with counts per edge label. `direction`: out, in or both (default).\n\n`from_nodes` selects the notes: `{"paths": [...]}`, `{"table": ..., "where": {...}}` and/or\n`{"tables": [...]}`: the rows of several tables, by name or pattern (`["*"]` every table, `["personal.*"]` a\ncatalog\'s). The whole vault\'s graph in one call: `{"tables": ["*"]}` with direction `out` (at most 5000\nstart notes). Edges are labelled with their link column (`people`, `event`, \u2026) or `link` for other links.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -16122,7 +16301,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_traverse",
-    "description": 'Breadth-first walk over links from `from_nodes` (`{"paths": [...]}` and/or `{"table", "where"}`).\n\n- `direction`: out (default, follow links), in (follow backlinks) or both.\n- `edges`: edge labels to follow (link columns such as `people`, `event`, or `link`).\n- `tables`: return only notes of these tables; `through`: only walk on through these tables.\n- `min_depth` (default 1) / `max_depth` (default 2, max 10), `limit` (default 500).\n\nEach node comes with `depth` and `via` (one shortest route). Example \u2014 moods tied to events\nwith Alice: from `{"table": "person", "where": {"name": "Alice"}}`, direction `in`, edges\n`["people", "event"]`, tables `["mood"]`, max_depth 2. Feed the paths to `select_rows` with\n`where: {"path": {"in": [...]}}` to aggregate them.',
+    "description": 'Breadth-first walk over links from `from_nodes` (`{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`).\n\n- `direction`: out (default, follow links), in (follow backlinks) or both.\n- `edges`: edge labels to follow (link columns such as `people`, `event`, or `link`).\n- `tables`: return only notes of these tables; `through`: only walk on through these tables.\n- `min_depth` (default 1) / `max_depth` (default 2, max 10), `limit` (default 500).\n\nEach node comes with `depth` and `via` (one shortest route). Example \u2014 moods tied to events\nwith Alice: from `{"table": "person", "where": {"name": "Alice"}}`, direction `in`, edges\n`["people", "event"]`, tables `["mood"]`, max_depth 2. Feed the paths to `select_rows` with\n`where: {"path": {"in": [...]}}` to aggregate them.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -16318,7 +16497,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 `path`: 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": [...]}`, `{"table", "where"}`\nand/or `{"tables": [...]}`): `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": {
@@ -16706,17 +16885,52 @@ function resultOf(status, json, text) {
 // src/api/tokens.ts
 function estimateTokens(text) {
   let n = 0;
-  for (const m of text.matchAll(/\p{L}+|\p{N}+|[^\s\p{L}\p{N}]/gu)) {
-    const s = m[0];
-    if (/^\p{L}/u.test(s)) n += Math.ceil(s.length / 4);
-    else if (/^\p{N}/u.test(s)) n += Math.ceil(s.length / 3);
-    else n += 1;
+  let run = 0;
+  for (let i = 0; i < text.length; ) {
+    const c = text.charCodeAt(i);
+    const cp = c >= 55296 && c <= 56319 ? text.codePointAt(i) : c;
+    const width = cp > 65535 ? 2 : 1;
+    const kind = classOf(cp);
+    if (kind === LETTER && run >= 0) run += width;
+    else if (kind === DIGIT && run <= 0) run -= width;
+    else {
+      n += run > 0 ? Math.ceil(run / 4) : Math.ceil(-run / 3);
+      run = kind === LETTER ? width : kind === DIGIT ? -width : 0;
+      if (kind === OTHER) n += 1;
+    }
+    i += width;
+  }
+  return n + (run > 0 ? Math.ceil(run / 4) : Math.ceil(-run / 3));
+}
+var LETTER = 0;
+var DIGIT = 1;
+var SPACE = 2;
+var OTHER = 3;
+function test(cp) {
+  const ch = String.fromCodePoint(cp);
+  return /\p{L}/u.test(ch) ? LETTER : /\p{N}/u.test(ch) ? DIGIT : /\s/u.test(ch) ? SPACE : OTHER;
+}
+var BMP = new Uint8Array(65536).fill(255);
+var ASTRAL = /* @__PURE__ */ new Map();
+var ASTRAL_KEPT = 4096;
+function classOf(cp) {
+  if (cp <= 65535) {
+    let k2 = BMP[cp];
+    if (k2 === 255) BMP[cp] = k2 = test(cp);
+    return k2;
+  }
+  let k = ASTRAL.get(cp);
+  if (k === void 0) {
+    k = test(cp);
+    if (ASTRAL.size < ASTRAL_KEPT) ASTRAL.set(cp, k);
   }
-  return n;
+  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 } };
@@ -16728,12 +16942,26 @@ 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) {
-    let x = BigInt.asUintN(64, 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);
@@ -16744,11 +16972,16 @@ var Pb = class {
     this.parts.push(Number(x));
   }
   tag(field, wire) {
-    this.varint(BigInt(field << 3 | wire));
+    this.varint(field << 3 | wire);
   }
   uint(field, v) {
     this.tag(field, 0);
-    this.varint(BigInt(v));
+    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) {
@@ -16765,10 +16998,16 @@ var Pb = class {
   }
   bytes(field, data) {
     this.tag(field, 2);
-    this.varint(BigInt(data.length));
+    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));
   }
@@ -16791,13 +17030,15 @@ function pbAttrs(m, field, a) {
   }
   return m;
 }
-var OtlpLogExporter = class {
-  constructor(o) {
+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;
-    /** Records sent, and records lost because the collector did not take them. */
+    /** 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;
@@ -16806,19 +17047,60 @@ var OtlpLogExporter = class {
       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();
+  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 batch = this.buffer;
-    this.buffer = [];
-    const resource = { "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource };
+    const send = this.o.send ?? fetchSend;
+    const url = `${this.o.endpoint.replace(/\/+$/, "")}${this.path}`;
     const protobuf = (this.o.protocol ?? "http/protobuf") === "http/protobuf";
-    const body = protobuf ? this.protobuf(resource, batch) : JSON.stringify({
+    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) },
@@ -16831,39 +17113,90 @@ var OtlpLogExporter = class {
                 severityNumber: SEVERITY_NUMBER[r.severity],
                 severityText: r.severity,
                 body: { stringValue: r.body },
-                attributes: attrs(r.attributes)
+                attributes: attrs(r.attributes),
+                ...r.context ? { traceId: r.context.traceId, spanId: r.context.spanId, flags: r.context.sampled ? 1 : 0 } : {}
               }))
             }
           ]
         }
       ]
     });
-    const url = `${this.o.endpoint.replace(/\/+$/, "")}/v1/logs`;
-    const send = this.o.send ?? fetchSend;
-    this.inflight = this.inflight.then(
-      () => send(url, body, { "Content-Type": protobuf ? "application/x-protobuf" : "application/json", ...this.o.headers ?? {} }).then(
-        () => void (this.sent += batch.length),
-        () => void (this.dropped += batch.length)
-      )
-    );
-    return this.inflight;
   }
   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).fixed64(11, t);
+      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();
   }
-  /** Stop the timer and send what is left. */
-  async close() {
-    if (this.timer) clearInterval(this.timer);
-    this.timer = null;
-    await this.flush();
+};
+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) {
@@ -16885,12 +17218,18 @@ function parseOtlpHeaders(text) {
 var parseResourceAttributes = parseOtlpHeaders;
 var truthy = (v) => (v ?? "").trim().toLowerCase() === "true";
 function otlpFromEnv(env, defaults) {
-  if (truthy(env.OTEL_SDK_DISABLED) || (env.OTEL_LOGS_EXPORTER ?? "").trim().toLowerCase() === "none") return null;
-  const logs = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT?.trim();
+  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 = logs ? logs.replace(/\/v1\/logs\/?$/, "") : base;
+  const endpoint = own ? own.replace(new RegExp(`/v1/${path}/?$`), "") : base;
   if (!endpoint) return null;
-  const protocol = otlpProtocol(env.OTEL_EXPORTER_OTLP_LOGS_PROTOCOL ?? env.OTEL_EXPORTER_OTLP_PROTOCOL);
+  const protocol = otlpProtocol(env[`OTEL_EXPORTER_OTLP_${signal}_PROTOCOL`] ?? env.OTEL_EXPORTER_OTLP_PROTOCOL);
   const resource = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
   return {
     endpoint,
@@ -16898,14 +17237,139 @@ function otlpFromEnv(env, defaults) {
     ...defaults.serviceVersion ? { serviceVersion: defaults.serviceVersion } : {},
     ...protocol ? { protocol } : {},
     ...Object.keys(resource).length ? { resource } : {},
-    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_LOGS_HEADERS) }
+    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
+    });
+  }
+};
+var Tracer = class {
+  constructor(o) {
+    this.o = o;
+    this.now = o.now ?? defaultNow;
+  }
+  /** A new span: a child of `parent` (a context or a `traceparent` header), or a new trace. */
+  startSpan(name, opts = {}) {
+    const parent = typeof opts.parent === "string" ? parseTraceparent(opts.parent) : opts.parent ?? null;
+    const ratio = this.o.sampleRatio ?? 1;
+    const span = new TraceSpan(this, name, opts.kind ?? "internal", parent, true, opts.attributes ?? {});
+    const recording = parent ? parent.sampled : ratio >= 1 || ratio > 0 && parseInt(span.context.traceId.slice(-13), 16) / 2 ** 52 < ratio;
+    return recording ? span : new TraceSpan(this, name, opts.kind ?? "internal", parent ?? { ...span.context, sampled: false }, false, {});
+  }
+  /** @internal */
+  send(span) {
+    try {
+      this.o.export([span]);
+    } catch {
+    }
+  }
+};
+
 // src/api/client.ts
 var ACTOR_HEADER = "X-Datanotes-Actor";
 var UNREACHABLE = {
@@ -16938,6 +17402,24 @@ function isEngineAnswer(json) {
   const o = json;
   return typeof o.ok === "boolean" || typeof o.error === "string";
 }
+function clientSpan(tracer, method, url, parent) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    target = null;
+  }
+  return tracer.startSpan(target ? `${method} ${target.pathname}` : method, {
+    kind: "client",
+    parent,
+    attributes: {
+      "http.request.method": method,
+      "url.full": target ? `${target.protocol}//${target.host}${target.pathname}` : void 0,
+      "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;
@@ -16951,11 +17433,22 @@ var DatanotesClient = class {
     this.url = o.url.replace(/\/+$/, "");
     this.send = o.transport ?? fetchTransport;
   }
-  /** Send a request; the answer's status, its JSON (when it is JSON) and its text. */
+  /** 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({
@@ -16965,13 +17458,20 @@ var DatanotesClient = class {
           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) } : {}
+          ...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);
@@ -16989,7 +17489,7 @@ var DatanotesClient = class {
    * 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) {
+  async call(name, args = {}, actor, options = {}) {
     let req;
     try {
       req = operationRequest(name, args);
@@ -16999,7 +17499,7 @@ var DatanotesClient = class {
     }
     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 } : {});
+    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). */
@@ -17011,8 +17511,11 @@ var DatanotesClient = class {
       return false;
     }
   }
-  /** Record an agent's tool call in the change feed (what MCP servers report). */
+  /**
+   * 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) {
-    await this.post("/tool-calls/record/", call, actor);
+    return this.post("/tool-calls/record/", call, actor);
   }
 };