datanotes 2.0.1 → 3.1.0

package/dist/api/otlp.d.cts

@@ -0,0 +1,113 @@
+/**
+ * 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.)
+ *
+ * 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` or `/v1/traces` is added). */
+    endpoint: string;
+    /** `service.name` of the records. */
+    serviceName: string;
+    serviceVersion?: string;
+    /** `http/protobuf` (default) or `http/json`. */
+    protocol?: OtlpProtocol;
+    /** Extra headers, e.g. an API key or `Authorization`, as the backend asks. */
+    headers?: Record<string, string>;
+    /** More resource attributes (e.g. `host.name`). */
+    resource?: Record<string, AttrValue>;
+    /** 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;
+    /** POST a body; resolves on 2xx (default: fetch). `headers` include the Content-Type. */
+    send?: (url: string, body: string | Uint8Array, headers: Record<string, string>) => Promise<void>;
+    now?: () => number;
+}
+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;
+    /** Items sent, and items lost because the collector did not take them (or the buffer was full). */
+    sent: number;
+    dropped: number;
+    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>;
+    /** 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`. */
+export declare const parseResourceAttributes: typeof parseOtlpHeaders;
+/**
+ * Exporter options from the standard OpenTelemetry variables, or null when export is off (no
+ * endpoint, `OTEL_SDK_DISABLED=true` or `OTEL_LOGS_EXPORTER=none`):
+ * `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (full URL of /v1/logs) or `OTEL_EXPORTER_OTLP_ENDPOINT`;
+ * `OTEL_EXPORTER_OTLP_[LOGS_]HEADERS`; `OTEL_EXPORTER_OTLP_[LOGS_]PROTOCOL` (`http/protobuf`,
+ * `http/json`); `OTEL_SERVICE_NAME`; `OTEL_RESOURCE_ATTRIBUTES`.
+ */
+export declare function otlpFromEnv(env: Record<string, string | undefined>, defaults: {
+    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

@@ -0,0 +1,42 @@
+/**
+ * Secrets out of recorded tool calls. A tool call becomes a `tool_call` event of the change feed,
+ * which the engine keeps in its store and the store backup commits and pushes: a webhook's secret
+ * or a token returned by a call must never get there. Removed are the arguments and result keys
+ * the catalogue marks `sensitive`, and, for any tool, the keys that name a secret
+ * ({@link SECRET_KEYS}), at any depth. A text (an error, a result sent as text) loses the values
+ * of those keys written as JSON.
+ */
+/** What a removed value becomes. */
+export declare const REDACTED = "[redacted]";
+/** Keys whose values are secrets, whatever the tool (compared without case, `_` or `-`). */
+export declare const SECRET_KEYS: readonly ["secret", "token", "password", "apikey", "authorization", "httpservertoken", "accesstoken", "refreshtoken", "clientsecret"];
+/** A tool call's arguments and result without their secrets (new objects; the call's own are kept). */
+export declare function redactToolCall(tool: string, args: Record<string, unknown>, value: unknown): {
+    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

@@ -0,0 +1,42 @@
+/**
+ * Secrets out of recorded tool calls. A tool call becomes a `tool_call` event of the change feed,
+ * which the engine keeps in its store and the store backup commits and pushes: a webhook's secret
+ * or a token returned by a call must never get there. Removed are the arguments and result keys
+ * the catalogue marks `sensitive`, and, for any tool, the keys that name a secret
+ * ({@link SECRET_KEYS}), at any depth. A text (an error, a result sent as text) loses the values
+ * of those keys written as JSON.
+ */
+/** What a removed value becomes. */
+export declare const REDACTED = "[redacted]";
+/** Keys whose values are secrets, whatever the tool (compared without case, `_` or `-`). */
+export declare const SECRET_KEYS: readonly ["secret", "token", "password", "apikey", "authorization", "httpservertoken", "accesstoken", "refreshtoken", "clientsecret"];
+/** A tool call's arguments and result without their secrets (new objects; the call's own are kept). */
+export declare function redactToolCall(tool: string, args: Record<string, unknown>, value: unknown): {
+    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/requests.d.cts

@@ -0,0 +1,26 @@
+/**
+ * The HTTP request behind each operation of the catalogue (`catalog.ts`): every one is
+ * `POST /datanotes/operations/<name>/`, its JSON body the operation's arguments as they are (the
+ * same names an agent passes to the MCP tool), without the ones left out (null or undefined).
+ */
+import { type Guidance } from "./guidance.cjs";
+type Args = Record<string, unknown>;
+/** Arguments no request can be built from; `message` ends with how to fix them. */
+export declare class OperationInputError extends Error {
+    readonly name = "OperationInputError";
+    constructor(message: string, guidance: Guidance);
+}
+export declare const ROUTE_PREFIX = "/datanotes";
+/** The operations of the catalogue, by name. */
+export declare const CALLABLE_OPERATIONS: ReadonlySet<string>;
+/** The route of an operation, without the prefix: `/operations/<name>/`. */
+export declare function operationRoute(name: string): string;
+export interface OperationRequest {
+    method: "POST";
+    /** Path from the server root. */
+    path: string;
+    body: Args;
+}
+/** The request for an operation and its arguments; throws OperationInputError for an unknown operation. */
+export declare function operationRequest(name: string, args?: Args): OperationRequest;
+export {};

package/dist/api/requests.d.ts

@@ -1,28 +1,26 @@
 /**
- * The HTTP request behind each operation of the catalogue (`catalog.ts`): most are
- * `POST /datanotes/<route>` with a JSON body built from the operation's arguments (renamed where
- * the route names them differently); the note operations read the vault routes.
+ * The HTTP request behind each operation of the catalogue (`catalog.ts`): every one is
+ * `POST /datanotes/operations/<name>/`, its JSON body the operation's arguments as they are (the
+ * same names an agent passes to the MCP tool), without the ones left out (null or undefined).
  */
+import { type Guidance } from "./guidance.js";
 type Args = Record<string, unknown>;
+/** Arguments no request can be built from; `message` ends with how to fix them. */
 export declare class OperationInputError extends Error {
     readonly name = "OperationInputError";
+    constructor(message: string, guidance: Guidance);
 }
 export declare const ROUTE_PREFIX = "/datanotes";
+/** The operations of the catalogue, by name. */
+export declare const CALLABLE_OPERATIONS: ReadonlySet<string>;
+/** The route of an operation, without the prefix: `/operations/<name>/`. */
+export declare function operationRoute(name: string): string;
 export interface OperationRequest {
-    method: "GET" | "POST";
-    /** Path from the server root, query string included. */
+    method: "POST";
+    /** Path from the server root. */
     path: string;
-    body?: unknown;
-    /** Accept header, when the route answers in more than one format. */
-    accept?: string;
+    body: Args;
 }
-/** The request for an operation and its arguments; throws OperationInputError on bad arguments. */
+/** The request for an operation and its arguments; throws OperationInputError for an unknown operation. */
 export declare function operationRequest(name: string, args?: Args): OperationRequest;
-/** Operations this module can build a request for (to check the catalogue against). */
-export declare const CALLABLE_OPERATIONS: Set<string>;
-/** The route an operation calls (without the prefix) and the body fields it fixes (e.g. `op` for DDL), or null. */
-export declare function operationRoute(name: string): {
-    path: string;
-    fixed: Args;
-} | null;
 export {};

package/dist/api/results.d.cts

@@ -0,0 +1,16 @@
+/**
+ * What an operation returned, for its caller: the value of a success, or an agent-readable text
+ * for a refusal (what was refused; nothing was written) or an error, ending with the engine's
+ * `hint` (how to fix it) and `docs` (where to read more) when it sends them.
+ */
+/** Agent-readable summary of conflicts / violations / failures in a refused result. */
+export declare function describeRefusal(data: Record<string, unknown>): string;
+/** Agent-readable summary of a refused batch: the failing operation and the rollback. */
+export declare function describeBatch(data: Record<string, unknown>): string;
+export interface OperationResult {
+    ok: boolean;
+    /** The result (JSON, or the text of a note) or, when `ok` is false, the reason. */
+    value: unknown;
+}
+/** The result of an HTTP answer: `json` when the body was JSON, else its `text`. */
+export declare function resultOf(status: number, json: unknown, text: string): OperationResult;

package/dist/api/results.d.ts

@@ -1,6 +1,7 @@
 /**
  * What an operation returned, for its caller: the value of a success, or an agent-readable text
- * for a refusal (what was refused; nothing was written) or an error.
+ * for a refusal (what was refused; nothing was written) or an error, ending with the engine's
+ * `hint` (how to fix it) and `docs` (where to read more) when it sends them.
  */
 /** Agent-readable summary of conflicts / violations / failures in a refused result. */
 export declare function describeRefusal(data: Record<string, unknown>): string;

package/dist/api/tokens.d.cts

@@ -0,0 +1,12 @@
+/**
+ * A tokenizer-free estimate of how many tokens a text costs a model: words count about one token
+ * 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 {};