datanotes 3.0.0 → 3.1.0

package/README.md

@@ -25,7 +25,7 @@ Datanotes keeps every row as a file, so it isn't a replacement for SQLite or Pos
 - High write throughput
 - Many concurrent writers on one folder
 
-Datanotes is comfortable at 10,000 notes. At 50,000 notes, the engine takes 22 to 115 seconds to start.
+Datanotes is comfortable at 10,000 notes. At 50,000 notes, the engine takes about 15 seconds for its first start, and 2 to 3 seconds to restart.
 
 ## Quick start
 
@@ -214,10 +214,6 @@ console.log(films.value);
 
 Each film is now a note, `main/public/film/Nosferatu.md`, with the values in its front matter. The [JavaScript client](https://datanotes.dev/develop/client/) page covers the rest of the client.
 
-## Stability: Datanotes 3 stays 3
-
-Every 3.x version adds to what you use and never takes it away. Operations, arguments, answer fields, routes, commands and settings keep working the same way. [Compatibility](https://datanotes.dev/reference/compatibility/) explains the promise and how the tests enforce it.
-
 ## Learn more
 
 - [Documentation](https://datanotes.dev)

package/dist/api/client.d.cts

@@ -5,6 +5,7 @@
  */
 import { type OperationResult } from "./results.cjs";
 import { type Guidance } from "./guidance.cjs";
+import { type TraceContext, type Tracer } from "./tracing.cjs";
 export interface HttpRequest {
     url: string;
     method: "GET" | "POST";
@@ -45,7 +46,17 @@ export interface ClientOptions {
     /** Recorded with every write unless a call names another actor. */
     actor?: ActorInfo;
     transport?: Transport;
+    /**
+     * The trace the requests continue (W3C Trace Context): a context, a `traceparent` header, or a
+     * function that returns the current one. Sent as `traceparent` (and `tracestate`), so the
+     * engine's spans join the caller's trace.
+     */
+    trace?: TraceParent | (() => TraceParent | undefined);
+    /** Make a CLIENT span for each request (child of `trace`), and send that span as the parent. */
+    tracer?: Tracer;
 }
+/** Where a request sits in a trace: a context, or a `traceparent` header value. */
+export type TraceParent = TraceContext | string;
 /** One tool call by an agent (an engine operation, or a tool of the MCP server's own), for the engine's change feed. */
 export interface ToolCallRecord {
     tool: string;
@@ -58,6 +69,17 @@ export interface ToolCallRecord {
     session?: string;
     result_chars?: number;
     result_tokens?: number;
+    /**
+     * The result's summary, when `value` is sent already cut (redact.ts `cutToolCall`): an engine
+     * that answers `takes_summary: true` records it.
+     */
+    summary?: Record<string, unknown>;
+}
+/** What the engine answers a recorded tool call. */
+export interface RecordedToolCall {
+    ok: boolean;
+    /** The engine records a `value` sent cut with its `summary` (engines before 3.1 leave it out). */
+    takes_summary?: boolean;
 }
 export declare const fetchTransport: Transport;
 export declare class DatanotesClient {
@@ -65,10 +87,16 @@ export declare class DatanotesClient {
     readonly url: string;
     private readonly send;
     constructor(o: ClientOptions);
-    /** 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. */
+    private parentOf;
+    /**
+     * 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).
+     */
     request(method: "GET" | "POST", path: string, body?: unknown, opts?: {
         actor?: ActorInfo;
         accept?: string;
+        trace?: TraceParent;
     }): Promise<{
         status: number;
         json: unknown;
@@ -81,9 +109,14 @@ export declare class DatanotesClient {
      * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
      * with the same message the engine gives.
      */
-    call(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult>;
+    call(name: string, args?: Record<string, unknown>, actor?: ActorInfo, options?: {
+        trace?: TraceParent;
+    }): Promise<OperationResult>;
     /** True when the engine answers `GET /` (no token needed). */
     ping(): Promise<boolean>;
-    /** Record an agent's tool call in the change feed (what MCP servers report). */
-    recordToolCall(call: ToolCallRecord, actor?: ActorInfo): Promise<void>;
+    /**
+     * 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`.
+     */
+    recordToolCall(call: ToolCallRecord, actor?: ActorInfo): Promise<RecordedToolCall>;
 }

package/dist/api/client.d.ts

@@ -5,6 +5,7 @@
  */
 import { type OperationResult } from "./results.js";
 import { type Guidance } from "./guidance.js";
+import { type TraceContext, type Tracer } from "./tracing.js";
 export interface HttpRequest {
     url: string;
     method: "GET" | "POST";
@@ -45,7 +46,17 @@ export interface ClientOptions {
     /** Recorded with every write unless a call names another actor. */
     actor?: ActorInfo;
     transport?: Transport;
+    /**
+     * The trace the requests continue (W3C Trace Context): a context, a `traceparent` header, or a
+     * function that returns the current one. Sent as `traceparent` (and `tracestate`), so the
+     * engine's spans join the caller's trace.
+     */
+    trace?: TraceParent | (() => TraceParent | undefined);
+    /** Make a CLIENT span for each request (child of `trace`), and send that span as the parent. */
+    tracer?: Tracer;
 }
+/** Where a request sits in a trace: a context, or a `traceparent` header value. */
+export type TraceParent = TraceContext | string;
 /** One tool call by an agent (an engine operation, or a tool of the MCP server's own), for the engine's change feed. */
 export interface ToolCallRecord {
     tool: string;
@@ -58,6 +69,17 @@ export interface ToolCallRecord {
     session?: string;
     result_chars?: number;
     result_tokens?: number;
+    /**
+     * The result's summary, when `value` is sent already cut (redact.ts `cutToolCall`): an engine
+     * that answers `takes_summary: true` records it.
+     */
+    summary?: Record<string, unknown>;
+}
+/** What the engine answers a recorded tool call. */
+export interface RecordedToolCall {
+    ok: boolean;
+    /** The engine records a `value` sent cut with its `summary` (engines before 3.1 leave it out). */
+    takes_summary?: boolean;
 }
 export declare const fetchTransport: Transport;
 export declare class DatanotesClient {
@@ -65,10 +87,16 @@ export declare class DatanotesClient {
     readonly url: string;
     private readonly send;
     constructor(o: ClientOptions);
-    /** 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. */
+    private parentOf;
+    /**
+     * 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).
+     */
     request(method: "GET" | "POST", path: string, body?: unknown, opts?: {
         actor?: ActorInfo;
         accept?: string;
+        trace?: TraceParent;
     }): Promise<{
         status: number;
         json: unknown;
@@ -81,9 +109,14 @@ export declare class DatanotesClient {
      * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
      * with the same message the engine gives.
      */
-    call(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult>;
+    call(name: string, args?: Record<string, unknown>, actor?: ActorInfo, options?: {
+        trace?: TraceParent;
+    }): Promise<OperationResult>;
     /** True when the engine answers `GET /` (no token needed). */
     ping(): Promise<boolean>;
-    /** Record an agent's tool call in the change feed (what MCP servers report). */
-    recordToolCall(call: ToolCallRecord, actor?: ActorInfo): Promise<void>;
+    /**
+     * 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`.
+     */
+    recordToolCall(call: ToolCallRecord, actor?: ActorInfo): Promise<RecordedToolCall>;
 }