datanotes 3.0.0 → 3.1.0

package/dist/api/mcp.cjs

@@ -16003,7 +16003,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 +16122,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 +16318,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": {
@@ -16646,6 +16646,9 @@ function checkToolArguments(op, schema, args, docs) {
 // src/api/requests.ts
 var CALLABLE_OPERATIONS = new Set(OPERATIONS.map((o) => o.name));
 
+// src/api/tracing.ts
+var perf = globalThis.performance;
+
 // src/api/client.ts
 var UNREACHABLE = {
   hint: "Start the engine (datanotes serve --database <folder>) or check its address; datanotes status --database <folder> shows whether it runs and where.",

package/dist/api/mcp.js

@@ -15955,7 +15955,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": {
@@ -16074,7 +16074,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": {
@@ -16270,7 +16270,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": {
@@ -16598,6 +16598,9 @@ function checkToolArguments(op, schema, args, docs) {
 // src/api/requests.ts
 var CALLABLE_OPERATIONS = new Set(OPERATIONS.map((o) => o.name));
 
+// src/api/tracing.ts
+var perf = globalThis.performance;
+
 // src/api/client.ts
 var UNREACHABLE = {
   hint: "Start the engine (datanotes serve --database <folder>) or check its address; datanotes status --database <folder> shows whether it runs and where.",

package/dist/api/otlp.d.cts

@@ -1,17 +1,21 @@
 /**
- * OpenTelemetry log export over OTLP/HTTP, vendor-neutral: records are buffered and POSTed to
- * `<endpoint>/v1/logs` as `http/protobuf` (the OTLP default) or `http/json`, which every
- * OpenTelemetry collector and OTLP backend reads. No dependency, no SDK. Export failures are
- * counted, never thrown: logging must not break the program. (OTLP over gRPC is not supported:
- * use the collector's HTTP port, 4318 by default.)
+ * OpenTelemetry export over OTLP/HTTP, vendor-neutral: log records (`OtlpLogExporter`, to
+ * `<endpoint>/v1/logs`) and spans (`OtlpTraceExporter`, to `<endpoint>/v1/traces`) are buffered
+ * and POSTed as `http/protobuf` (the OTLP default) or `http/json`, which every OpenTelemetry
+ * collector and OTLP backend reads. No dependency, no SDK. Export failures are counted, never
+ * thrown: telemetry must not break the program. (OTLP over gRPC is not supported: use the
+ * collector's HTTP port, 4318 by default.)
  *
- * Configure it in code, or from the standard OpenTelemetry variables with `otlpFromEnv`.
+ * A log record made inside a span names it (`log`'s `context`), so the backend links the two.
+ * Configure the exporters in code, or from the standard OpenTelemetry variables with
+ * `otlpFromEnv` and `otlpTracesFromEnv`.
  */
+import type { SpanRecord, TraceContext } from "./tracing.cjs";
 export type Severity = "DEBUG" | "INFO" | "WARN" | "ERROR";
 export type AttrValue = string | number | boolean | null | undefined;
 export type OtlpProtocol = "http/protobuf" | "http/json";
 export interface OtlpOptions {
-    /** Collector base URL, e.g. `http://127.0.0.1:4318` (`/v1/logs` is added). */
+    /** Collector base URL, e.g. `http://127.0.0.1:4318` (`/v1/logs` or `/v1/traces` is added). */
     endpoint: string;
     /** `service.name` of the records. */
     serviceName: string;
@@ -22,7 +26,7 @@ export interface OtlpOptions {
     headers?: Record<string, string>;
     /** More resource attributes (e.g. `host.name`). */
     resource?: Record<string, AttrValue>;
-    /** Send at most this many records per request (default 50); a full buffer is sent at once. */
+    /** Send at most this many records (or spans) per request (default 50 records, 512 spans); a full buffer is sent at once. */
     maxBatch?: number;
     /** Send the buffer every this many ms (default 5000; 0: only on `flush`). */
     flushMs?: number;
@@ -30,22 +34,50 @@ export interface OtlpOptions {
     send?: (url: string, body: string | Uint8Array, headers: Record<string, string>) => Promise<void>;
     now?: () => number;
 }
-export declare class OtlpLogExporter {
-    private readonly o;
-    private buffer;
+interface LogRecord {
+    timeUnixNano: string;
+    severity: Severity;
+    body: string;
+    attributes: Record<string, AttrValue>;
+    context?: Pick<TraceContext, "traceId" | "spanId" | "sampled">;
+}
+/** Unix ms (with a fraction) as OTLP nanoseconds, a decimal string. */
+export declare function unixNano(ms: number): string;
+/** What both exporters share: the buffer, the timer, the POST, the counts. */
+declare abstract class OtlpBatcher<T> {
+    protected readonly o: OtlpOptions;
+    private readonly path;
+    private readonly maxBatch;
+    protected buffer: T[];
     private inflight;
     private timer;
-    /** 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). */
     sent: number;
     dropped: number;
-    constructor(o: OtlpOptions);
-    log(severity: Severity, body: string, attributes?: Record<string, AttrValue>): void;
+    constructor(o: OtlpOptions, path: string, maxBatch: number);
+    protected push(items: readonly T[]): void;
+    protected resource(): Record<string, AttrValue>;
+    protected abstract encode(batch: T[], protobuf: boolean): string | Uint8Array;
     /** Send what is buffered. Never rejects. */
     flush(): Promise<void>;
-    private protobuf;
     /** Stop the timer and send what is left. */
     close(): Promise<void>;
 }
+export declare class OtlpLogExporter extends OtlpBatcher<LogRecord> {
+    constructor(o: OtlpOptions);
+    /** Buffer a record; `context`: the span it was made in (its trace and span id go with it). */
+    log(severity: Severity, body: string, attributes?: Record<string, AttrValue>, context?: Pick<TraceContext, "traceId" | "spanId" | "sampled">): void;
+    protected encode(batch: LogRecord[], protobuf: boolean): string | Uint8Array;
+    private protobuf;
+}
+/** Spans to `<endpoint>/v1/traces` (ExportTraceServiceRequest), in batches. */
+export declare class OtlpTraceExporter extends OtlpBatcher<SpanRecord> {
+    constructor(o: OtlpOptions);
+    /** Buffer finished spans (sent with the next batch). Never throws. */
+    export(spans: SpanRecord | readonly SpanRecord[]): void;
+    protected encode(batch: SpanRecord[], protobuf: boolean): string | Uint8Array;
+    private protobuf;
+}
 /** `k1=v1,k2=v2` (values URL-encoded), the format of `OTEL_EXPORTER_OTLP_HEADERS`. */
 export declare function parseOtlpHeaders(text: string | undefined): Record<string, string>;
 /** `k1=v1,k2=v2` resource attributes, the format of `OTEL_RESOURCE_ATTRIBUTES`. */
@@ -61,5 +93,21 @@ export declare function otlpFromEnv(env: Record<string, string | undefined>, def
     serviceName: string;
     serviceVersion?: string;
 }): OtlpOptions | null;
+/**
+ * The same for traces: `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (full URL of /v1/traces) or
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`; the `…_TRACES_…` headers and protocol; null also when
+ * `OTEL_TRACES_EXPORTER=none`.
+ */
+export declare function otlpTracesFromEnv(env: Record<string, string | undefined>, defaults: {
+    serviceName: string;
+    serviceVersion?: string;
+}): OtlpOptions | null;
+/**
+ * The share of new traces to keep, from `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`
+ * (`always_on`, `always_off`, `traceidratio`, and their `parentbased_` forms: a trace continued
+ * from a caller always follows the caller); undefined when they say nothing usable.
+ */
+export declare function samplerRatioFromEnv(env: Record<string, string | undefined>): number | undefined;
 /** `http/protobuf` or `http/json` from a setting or variable; undefined for anything else. */
 export declare function otlpProtocol(v: string | undefined): OtlpProtocol | undefined;
+export {};

package/dist/api/otlp.d.ts

@@ -1,17 +1,21 @@
 /**
- * OpenTelemetry log export over OTLP/HTTP, vendor-neutral: records are buffered and POSTed to
- * `<endpoint>/v1/logs` as `http/protobuf` (the OTLP default) or `http/json`, which every
- * OpenTelemetry collector and OTLP backend reads. No dependency, no SDK. Export failures are
- * counted, never thrown: logging must not break the program. (OTLP over gRPC is not supported:
- * use the collector's HTTP port, 4318 by default.)
+ * OpenTelemetry export over OTLP/HTTP, vendor-neutral: log records (`OtlpLogExporter`, to
+ * `<endpoint>/v1/logs`) and spans (`OtlpTraceExporter`, to `<endpoint>/v1/traces`) are buffered
+ * and POSTed as `http/protobuf` (the OTLP default) or `http/json`, which every OpenTelemetry
+ * collector and OTLP backend reads. No dependency, no SDK. Export failures are counted, never
+ * thrown: telemetry must not break the program. (OTLP over gRPC is not supported: use the
+ * collector's HTTP port, 4318 by default.)
  *
- * Configure it in code, or from the standard OpenTelemetry variables with `otlpFromEnv`.
+ * A log record made inside a span names it (`log`'s `context`), so the backend links the two.
+ * Configure the exporters in code, or from the standard OpenTelemetry variables with
+ * `otlpFromEnv` and `otlpTracesFromEnv`.
  */
+import type { SpanRecord, TraceContext } from "./tracing.js";
 export type Severity = "DEBUG" | "INFO" | "WARN" | "ERROR";
 export type AttrValue = string | number | boolean | null | undefined;
 export type OtlpProtocol = "http/protobuf" | "http/json";
 export interface OtlpOptions {
-    /** Collector base URL, e.g. `http://127.0.0.1:4318` (`/v1/logs` is added). */
+    /** Collector base URL, e.g. `http://127.0.0.1:4318` (`/v1/logs` or `/v1/traces` is added). */
     endpoint: string;
     /** `service.name` of the records. */
     serviceName: string;
@@ -22,7 +26,7 @@ export interface OtlpOptions {
     headers?: Record<string, string>;
     /** More resource attributes (e.g. `host.name`). */
     resource?: Record<string, AttrValue>;
-    /** Send at most this many records per request (default 50); a full buffer is sent at once. */
+    /** Send at most this many records (or spans) per request (default 50 records, 512 spans); a full buffer is sent at once. */
     maxBatch?: number;
     /** Send the buffer every this many ms (default 5000; 0: only on `flush`). */
     flushMs?: number;
@@ -30,22 +34,50 @@ export interface OtlpOptions {
     send?: (url: string, body: string | Uint8Array, headers: Record<string, string>) => Promise<void>;
     now?: () => number;
 }
-export declare class OtlpLogExporter {
-    private readonly o;
-    private buffer;
+interface LogRecord {
+    timeUnixNano: string;
+    severity: Severity;
+    body: string;
+    attributes: Record<string, AttrValue>;
+    context?: Pick<TraceContext, "traceId" | "spanId" | "sampled">;
+}
+/** Unix ms (with a fraction) as OTLP nanoseconds, a decimal string. */
+export declare function unixNano(ms: number): string;
+/** What both exporters share: the buffer, the timer, the POST, the counts. */
+declare abstract class OtlpBatcher<T> {
+    protected readonly o: OtlpOptions;
+    private readonly path;
+    private readonly maxBatch;
+    protected buffer: T[];
     private inflight;
     private timer;
-    /** 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). */
     sent: number;
     dropped: number;
-    constructor(o: OtlpOptions);
-    log(severity: Severity, body: string, attributes?: Record<string, AttrValue>): void;
+    constructor(o: OtlpOptions, path: string, maxBatch: number);
+    protected push(items: readonly T[]): void;
+    protected resource(): Record<string, AttrValue>;
+    protected abstract encode(batch: T[], protobuf: boolean): string | Uint8Array;
     /** Send what is buffered. Never rejects. */
     flush(): Promise<void>;
-    private protobuf;
     /** Stop the timer and send what is left. */
     close(): Promise<void>;
 }
+export declare class OtlpLogExporter extends OtlpBatcher<LogRecord> {
+    constructor(o: OtlpOptions);
+    /** Buffer a record; `context`: the span it was made in (its trace and span id go with it). */
+    log(severity: Severity, body: string, attributes?: Record<string, AttrValue>, context?: Pick<TraceContext, "traceId" | "spanId" | "sampled">): void;
+    protected encode(batch: LogRecord[], protobuf: boolean): string | Uint8Array;
+    private protobuf;
+}
+/** Spans to `<endpoint>/v1/traces` (ExportTraceServiceRequest), in batches. */
+export declare class OtlpTraceExporter extends OtlpBatcher<SpanRecord> {
+    constructor(o: OtlpOptions);
+    /** Buffer finished spans (sent with the next batch). Never throws. */
+    export(spans: SpanRecord | readonly SpanRecord[]): void;
+    protected encode(batch: SpanRecord[], protobuf: boolean): string | Uint8Array;
+    private protobuf;
+}
 /** `k1=v1,k2=v2` (values URL-encoded), the format of `OTEL_EXPORTER_OTLP_HEADERS`. */
 export declare function parseOtlpHeaders(text: string | undefined): Record<string, string>;
 /** `k1=v1,k2=v2` resource attributes, the format of `OTEL_RESOURCE_ATTRIBUTES`. */
@@ -61,5 +93,21 @@ export declare function otlpFromEnv(env: Record<string, string | undefined>, def
     serviceName: string;
     serviceVersion?: string;
 }): OtlpOptions | null;
+/**
+ * The same for traces: `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (full URL of /v1/traces) or
+ * `OTEL_EXPORTER_OTLP_ENDPOINT`; the `…_TRACES_…` headers and protocol; null also when
+ * `OTEL_TRACES_EXPORTER=none`.
+ */
+export declare function otlpTracesFromEnv(env: Record<string, string | undefined>, defaults: {
+    serviceName: string;
+    serviceVersion?: string;
+}): OtlpOptions | null;
+/**
+ * The share of new traces to keep, from `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`
+ * (`always_on`, `always_off`, `traceidratio`, and their `parentbased_` forms: a trace continued
+ * from a caller always follows the caller); undefined when they say nothing usable.
+ */
+export declare function samplerRatioFromEnv(env: Record<string, string | undefined>): number | undefined;
 /** `http/protobuf` or `http/json` from a setting or variable; undefined for anything else. */
 export declare function otlpProtocol(v: string | undefined): OtlpProtocol | undefined;
+export {};

package/dist/api/redact.d.cts

@@ -15,3 +15,28 @@ export declare function redactToolCall(tool: string, args: Record<string, unknow
     args: Record<string, unknown>;
     value: unknown;
 };
+/** How many characters of a recorded call's result, and of each of its arguments, are kept. */
+export declare const RECORDED_CHARS: {
+    readonly value: 1000;
+    readonly arg: 300;
+};
+/** A value as a recorded call keeps it: a text, or an object's JSON, longer than `n` characters is cut (with "…"). */
+export declare function cutRecorded(v: unknown, n: number): unknown;
+/** A result object in short: its first 30 fields, lists as their length, texts cut at 200 characters, nothing nested. */
+export declare function summarizeRecorded(v: Record<string, unknown>): Record<string, unknown>;
+/** An object that is no list. */
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/**
+ * A call (secrets already removed) as a reporter sends it to an engine that takes it cut: the
+ * arguments and the value cut as the engine cuts them, and the summary of a result object, which
+ * the cut value may no longer give. The engine records the same event as from the whole call.
+ */
+export declare function cutToolCall(call: {
+    args: Record<string, unknown>;
+    ok: boolean;
+    value: unknown;
+}): {
+    args: Record<string, unknown>;
+    value: unknown;
+    summary?: Record<string, unknown>;
+};

package/dist/api/redact.d.ts

@@ -15,3 +15,28 @@ export declare function redactToolCall(tool: string, args: Record<string, unknow
     args: Record<string, unknown>;
     value: unknown;
 };
+/** How many characters of a recorded call's result, and of each of its arguments, are kept. */
+export declare const RECORDED_CHARS: {
+    readonly value: 1000;
+    readonly arg: 300;
+};
+/** A value as a recorded call keeps it: a text, or an object's JSON, longer than `n` characters is cut (with "…"). */
+export declare function cutRecorded(v: unknown, n: number): unknown;
+/** A result object in short: its first 30 fields, lists as their length, texts cut at 200 characters, nothing nested. */
+export declare function summarizeRecorded(v: Record<string, unknown>): Record<string, unknown>;
+/** An object that is no list. */
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/**
+ * A call (secrets already removed) as a reporter sends it to an engine that takes it cut: the
+ * arguments and the value cut as the engine cuts them, and the summary of a result object, which
+ * the cut value may no longer give. The engine records the same event as from the whole call.
+ */
+export declare function cutToolCall(call: {
+    args: Record<string, unknown>;
+    ok: boolean;
+    value: unknown;
+}): {
+    args: Record<string, unknown>;
+    value: unknown;
+    summary?: Record<string, unknown>;
+};

package/dist/api/tokens.d.cts

@@ -3,5 +3,10 @@
  * per 4 letters, numbers one per 3 digits, every other symbol (JSON punctuation, quotes, …) one.
  * Close to real tokenizers on JSON and on Italian/English prose (within ~15%); good for telling
  * which tools and sessions fill the context, not for billing.
+ *
+ * One pass over the text, character by character: a run of letters (`\p{L}`) or of digits
+ * (`\p{N}`) is one word or number, its length counted in UTF-16 units; white space (`\s`) counts
+ * nothing; any other character counts one.
  */
 export declare function estimateTokens(text: string): number;
+export declare const ASTRAL_KEPT = 4096;

package/dist/api/tokens.d.ts

@@ -3,5 +3,10 @@
  * per 4 letters, numbers one per 3 digits, every other symbol (JSON punctuation, quotes, …) one.
  * Close to real tokenizers on JSON and on Italian/English prose (within ~15%); good for telling
  * which tools and sessions fill the context, not for billing.
+ *
+ * One pass over the text, character by character: a run of letters (`\p{L}`) or of digits
+ * (`\p{N}`) is one word or number, its length counted in UTF-16 units; white space (`\s`) counts
+ * nothing; any other character counts one.
  */
 export declare function estimateTokens(text: string): number;
+export declare const ASTRAL_KEPT = 4096;

package/dist/api/tracing.d.cts

@@ -0,0 +1,107 @@
+/**
+ * W3C Trace Context and a small tracer, with no dependency, for programs that call the engine:
+ * the MCP server (`datanotes mcp`), apps, scripts. A program continues its own trace in the
+ * engine by sending `traceparent` (and `tracestate`) with its requests: `DatanotesClient` does it
+ * with its `trace` option, or makes a CLIENT span per request with its `tracer` option.
+ *
+ * The spans go to an exporter, usually `OtlpTraceExporter` (otlp.ts). Unlike the engine's tracer,
+ * this one keeps no context across `await`: pass the parent explicitly, so it runs anywhere
+ * (Node, browsers, Obsidian).
+ */
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+export type SpanStatusCode = "unset" | "ok" | "error";
+type AttrValue = string | number | boolean | null | undefined;
+/** A position in a trace: what `traceparent` carries. */
+export interface TraceContext {
+    /** 32 lowercase hex characters. */
+    traceId: string;
+    /** 16 lowercase hex characters: the caller's span. */
+    spanId: string;
+    /** Whether the caller records the trace (flag `01`). */
+    sampled: boolean;
+    /** The `tracestate` header, passed on as it came. */
+    traceState?: string;
+}
+export declare const TRACEPARENT_HEADER = "traceparent";
+export declare const TRACESTATE_HEADER = "tracestate";
+/**
+ * Read a `traceparent` header (and its `tracestate`); null when it is missing or invalid (an
+ * all-zero id, version `ff`, a version 00 header with extra fields), as the W3C spec says.
+ */
+export declare function parseTraceparent(traceparent: string | null | undefined, tracestate?: string | null): TraceContext | null;
+/** The `traceparent` header of a context (version 00). */
+export declare function formatTraceparent(ctx: TraceContext): string;
+/** The headers that continue `ctx` in another process: `traceparent`, and `tracestate` when there is one. */
+export declare function traceHeaders(ctx: TraceContext): Record<string, string>;
+/** A new random trace id (32 hex characters). */
+export declare const newTraceId: () => string;
+/** A new random span id (16 hex characters). */
+export declare const newSpanId: () => string;
+/** A finished span, as `OtlpTraceExporter` sends it (times are Unix ms, with a fraction). */
+export interface SpanRecord {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceState?: string;
+    name: string;
+    kind: SpanKind;
+    startMs: number;
+    endMs: number;
+    attributes: Record<string, AttrValue>;
+    events: {
+        name: string;
+        timeMs: number;
+        attributes: Record<string, AttrValue>;
+    }[];
+    status: {
+        code: SpanStatusCode;
+        message?: string;
+    };
+    droppedAttributes?: number;
+    droppedEvents?: number;
+}
+export interface TracerOptions {
+    /** Where finished spans go, e.g. `(s) => exporter.export(s)` of an `OtlpTraceExporter`. */
+    export(spans: SpanRecord[]): void;
+    /** Share of new traces kept, 0 to 1 (default 1); a trace continued from a parent follows the parent. */
+    sampleRatio?: number;
+    /** Unix time in ms (default: `performance` when there is one, else `Date.now`). */
+    now?: () => number;
+}
+/** One operation of a program, timed; `end()` sends it. Not sampled: `recording` is false and nothing is sent. */
+export declare class TraceSpan {
+    private readonly tracer;
+    readonly name: string;
+    readonly kind: SpanKind;
+    readonly parent: TraceContext | null;
+    readonly recording: boolean;
+    readonly context: TraceContext;
+    private readonly startMs;
+    private readonly attributes;
+    private readonly events;
+    private status;
+    private ended;
+    constructor(tracer: Tracer, name: string, kind: SpanKind, parent: TraceContext | null, recording: boolean, attributes: Record<string, AttrValue>);
+    setAttribute(key: string, value: AttrValue): this;
+    setAttributes(attributes: Record<string, AttrValue>): this;
+    addEvent(name: string, attributes?: Record<string, AttrValue>): this;
+    /** An `exception` event, `error.type` and status ERROR. */
+    recordException(e: unknown): this;
+    setStatus(code: SpanStatusCode, message?: string): this;
+    end(): void;
+}
+/** Makes spans with explicit parents and hands them to an exporter. Never throws. */
+export declare class Tracer {
+    private readonly o;
+    readonly now: () => number;
+    constructor(o: TracerOptions);
+    /** A new span: a child of `parent` (a context or a `traceparent` header), or a new trace. */
+    startSpan(name: string, opts?: {
+        kind?: SpanKind;
+        parent?: TraceContext | string | null;
+        attributes?: Record<string, AttrValue>;
+    }): TraceSpan;
+    /** @internal */
+    send(span: SpanRecord): void;
+}
+export {};

package/dist/api/tracing.d.ts

@@ -0,0 +1,107 @@
+/**
+ * W3C Trace Context and a small tracer, with no dependency, for programs that call the engine:
+ * the MCP server (`datanotes mcp`), apps, scripts. A program continues its own trace in the
+ * engine by sending `traceparent` (and `tracestate`) with its requests: `DatanotesClient` does it
+ * with its `trace` option, or makes a CLIENT span per request with its `tracer` option.
+ *
+ * The spans go to an exporter, usually `OtlpTraceExporter` (otlp.ts). Unlike the engine's tracer,
+ * this one keeps no context across `await`: pass the parent explicitly, so it runs anywhere
+ * (Node, browsers, Obsidian).
+ */
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+export type SpanStatusCode = "unset" | "ok" | "error";
+type AttrValue = string | number | boolean | null | undefined;
+/** A position in a trace: what `traceparent` carries. */
+export interface TraceContext {
+    /** 32 lowercase hex characters. */
+    traceId: string;
+    /** 16 lowercase hex characters: the caller's span. */
+    spanId: string;
+    /** Whether the caller records the trace (flag `01`). */
+    sampled: boolean;
+    /** The `tracestate` header, passed on as it came. */
+    traceState?: string;
+}
+export declare const TRACEPARENT_HEADER = "traceparent";
+export declare const TRACESTATE_HEADER = "tracestate";
+/**
+ * Read a `traceparent` header (and its `tracestate`); null when it is missing or invalid (an
+ * all-zero id, version `ff`, a version 00 header with extra fields), as the W3C spec says.
+ */
+export declare function parseTraceparent(traceparent: string | null | undefined, tracestate?: string | null): TraceContext | null;
+/** The `traceparent` header of a context (version 00). */
+export declare function formatTraceparent(ctx: TraceContext): string;
+/** The headers that continue `ctx` in another process: `traceparent`, and `tracestate` when there is one. */
+export declare function traceHeaders(ctx: TraceContext): Record<string, string>;
+/** A new random trace id (32 hex characters). */
+export declare const newTraceId: () => string;
+/** A new random span id (16 hex characters). */
+export declare const newSpanId: () => string;
+/** A finished span, as `OtlpTraceExporter` sends it (times are Unix ms, with a fraction). */
+export interface SpanRecord {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceState?: string;
+    name: string;
+    kind: SpanKind;
+    startMs: number;
+    endMs: number;
+    attributes: Record<string, AttrValue>;
+    events: {
+        name: string;
+        timeMs: number;
+        attributes: Record<string, AttrValue>;
+    }[];
+    status: {
+        code: SpanStatusCode;
+        message?: string;
+    };
+    droppedAttributes?: number;
+    droppedEvents?: number;
+}
+export interface TracerOptions {
+    /** Where finished spans go, e.g. `(s) => exporter.export(s)` of an `OtlpTraceExporter`. */
+    export(spans: SpanRecord[]): void;
+    /** Share of new traces kept, 0 to 1 (default 1); a trace continued from a parent follows the parent. */
+    sampleRatio?: number;
+    /** Unix time in ms (default: `performance` when there is one, else `Date.now`). */
+    now?: () => number;
+}
+/** One operation of a program, timed; `end()` sends it. Not sampled: `recording` is false and nothing is sent. */
+export declare class TraceSpan {
+    private readonly tracer;
+    readonly name: string;
+    readonly kind: SpanKind;
+    readonly parent: TraceContext | null;
+    readonly recording: boolean;
+    readonly context: TraceContext;
+    private readonly startMs;
+    private readonly attributes;
+    private readonly events;
+    private status;
+    private ended;
+    constructor(tracer: Tracer, name: string, kind: SpanKind, parent: TraceContext | null, recording: boolean, attributes: Record<string, AttrValue>);
+    setAttribute(key: string, value: AttrValue): this;
+    setAttributes(attributes: Record<string, AttrValue>): this;
+    addEvent(name: string, attributes?: Record<string, AttrValue>): this;
+    /** An `exception` event, `error.type` and status ERROR. */
+    recordException(e: unknown): this;
+    setStatus(code: SpanStatusCode, message?: string): this;
+    end(): void;
+}
+/** Makes spans with explicit parents and hands them to an exporter. Never throws. */
+export declare class Tracer {
+    private readonly o;
+    readonly now: () => number;
+    constructor(o: TracerOptions);
+    /** A new span: a child of `parent` (a context or a `traceparent` header), or a new trace. */
+    startSpan(name: string, opts?: {
+        kind?: SpanKind;
+        parent?: TraceContext | string | null;
+        attributes?: Record<string, AttrValue>;
+    }): TraceSpan;
+    /** @internal */
+    send(span: SpanRecord): void;
+}
+export {};