datanotes 2.0.1 → 3.1.0

package/dist/api/catalog.d.cts

@@ -0,0 +1,69 @@
+/**
+ * The operations of the HTTP API, described for their callers: name, description, input schema
+ * and hints. The MCP server (`datanotes mcp`, src/mcp) offers each one as a tool of the same name
+ * (the shape is MCP's tool definition); the OpenAPI document and the docs are generated from it. The route and body each
+ * one sends: `requests.ts`.
+ */
+export interface OperationDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /**
+     * MCP tool hints (not part of the Datanotes 3 contract). `destructiveHint` is true for every
+     * write that may overwrite or remove existing data (values, names, definitions, settings, history)
+     * or send it out of the engine (webhooks); false only for reads and purely additive writes
+     * (tests/api-mcp.test.ts holds the list).
+     */
+    annotations: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    /** JSON Schema of the successful (2xx) response body, for the OpenAPI document; not sent to MCP clients. */
+    responseSchema?: Record<string, unknown>;
+    /**
+     * Secrets in the call: the argument names and result keys never recorded (the change feed's
+     * `tool_call` events, which the store backup commits). `redactToolCall` (redact.ts) applies it.
+     */
+    sensitive?: {
+        args?: string[];
+        result?: string[];
+    };
+}
+export declare const OPERATIONS: OperationDef[];
+/**
+ * The kinds of operation, as the docs' reference groups them (one page each,
+ * `reference/operations/<kind>`), like the statement kinds of a SQL reference.
+ */
+export declare const OPERATION_KINDS: {
+    readonly schema: {
+        readonly title: "Schema operations (DDL)";
+        readonly label: "Schema (DDL)";
+        readonly description: "Operations that define the database: tables, columns, constraints, bases and views.";
+    };
+    readonly rows: {
+        readonly title: "Row operations (DML)";
+        readonly label: "Rows (DML)";
+        readonly description: "Operations that write rows: insert, update, merge, delete, move, adopt and batch.";
+    };
+    readonly queries: {
+        readonly title: "Query operations";
+        readonly label: "Queries";
+        readonly description: "Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph.";
+    };
+    readonly history: {
+        readonly title: "History operations";
+        readonly label: "History";
+        readonly description: "Operations on the journal, a table's versions, the change feed and webhooks: undo, time travel, restore and vacuum.";
+    };
+    readonly auxiliary: {
+        readonly title: "Auxiliary operations";
+        readonly label: "Auxiliary";
+        readonly description: "Operations that describe and check the database, configure it and maintain its indexes.";
+    };
+};
+export type OperationKind = keyof typeof OPERATION_KINDS;
+/** The kind of every operation of {@link OPERATIONS} (tests/operation-kinds.test.ts: each has exactly one). */
+export declare const OPERATION_KIND: Readonly<Record<string, OperationKind>>;

package/dist/api/catalog.d.ts

@@ -1,13 +1,19 @@
 /**
  * The operations of the HTTP API, described for their callers: name, description, input schema
- * and hints. An MCP server offers each one as a tool of the same name (the shape is MCP's tool
- * definition); the OpenAPI document and the docs are generated from it. The route and body each
+ * and hints. The MCP server (`datanotes mcp`, src/mcp) offers each one as a tool of the same name
+ * (the shape is MCP's tool definition); the OpenAPI document and the docs are generated from it. The route and body each
  * one sends: `requests.ts`.
  */
 export interface OperationDef {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    /**
+     * MCP tool hints (not part of the Datanotes 3 contract). `destructiveHint` is true for every
+     * write that may overwrite or remove existing data (values, names, definitions, settings, history)
+     * or send it out of the engine (webhooks); false only for reads and purely additive writes
+     * (tests/api-mcp.test.ts holds the list).
+     */
     annotations: {
         title?: string;
         readOnlyHint?: boolean;
@@ -17,5 +23,47 @@ export interface OperationDef {
     };
     /** JSON Schema of the successful (2xx) response body, for the OpenAPI document; not sent to MCP clients. */
     responseSchema?: Record<string, unknown>;
+    /**
+     * Secrets in the call: the argument names and result keys never recorded (the change feed's
+     * `tool_call` events, which the store backup commits). `redactToolCall` (redact.ts) applies it.
+     */
+    sensitive?: {
+        args?: string[];
+        result?: string[];
+    };
 }
 export declare const OPERATIONS: OperationDef[];
+/**
+ * The kinds of operation, as the docs' reference groups them (one page each,
+ * `reference/operations/<kind>`), like the statement kinds of a SQL reference.
+ */
+export declare const OPERATION_KINDS: {
+    readonly schema: {
+        readonly title: "Schema operations (DDL)";
+        readonly label: "Schema (DDL)";
+        readonly description: "Operations that define the database: tables, columns, constraints, bases and views.";
+    };
+    readonly rows: {
+        readonly title: "Row operations (DML)";
+        readonly label: "Rows (DML)";
+        readonly description: "Operations that write rows: insert, update, merge, delete, move, adopt and batch.";
+    };
+    readonly queries: {
+        readonly title: "Query operations";
+        readonly label: "Queries";
+        readonly description: "Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph.";
+    };
+    readonly history: {
+        readonly title: "History operations";
+        readonly label: "History";
+        readonly description: "Operations on the journal, a table's versions, the change feed and webhooks: undo, time travel, restore and vacuum.";
+    };
+    readonly auxiliary: {
+        readonly title: "Auxiliary operations";
+        readonly label: "Auxiliary";
+        readonly description: "Operations that describe and check the database, configure it and maintain its indexes.";
+    };
+};
+export type OperationKind = keyof typeof OPERATION_KINDS;
+/** The kind of every operation of {@link OPERATIONS} (tests/operation-kinds.test.ts: each has exactly one). */
+export declare const OPERATION_KIND: Readonly<Record<string, OperationKind>>;

package/dist/api/cli-options.d.cts

@@ -0,0 +1,39 @@
+/**
+ * The command line options of the `datanotes` commands: `--name value` or `--name=value` for an
+ * option with a value, `--name` for a flag. An option the command does not know is refused with
+ * the closest one, so a typo never runs a command with its defaults.
+ */
+export interface OptionSpec {
+    /** Options that take a value. */
+    values?: readonly string[];
+    /** Options that take none. */
+    flags?: readonly string[];
+}
+/** A command line the command cannot run: what is wrong, and how to write it. */
+export declare class CliOptionError extends Error {
+    readonly hint: string;
+    readonly name = "CliOptionError";
+    /** Every command and its options. */
+    readonly docs = "https://datanotes.dev/reference/cli.md";
+    constructor(message: string, hint: string);
+}
+export interface Options {
+    /** The value of an option, when given. */
+    get(name: string): string | undefined;
+    /** Was a flag given? */
+    has(name: string): boolean;
+}
+/** Read `argv` against what `command` takes; throws {@link CliOptionError} on anything else. */
+export declare function readOptions(argv: readonly string[], spec: OptionSpec, command: string): Options;
+/** The folder a command works on, and how to read it. */
+export interface FolderArg {
+    folder: string;
+    /** `--database`: the folder is the database (metastore.yaml at its root); else a vault holding it. */
+    atRoot: boolean;
+}
+/**
+ * The folder of `--database` (the folder is the database) or `--vault` (a vault holding the
+ * database in a subfolder), else DATANOTES_DATABASE or DATANOTES_VAULT: one of the two, never
+ * both. Null when none is given and the command can do without (`required` false).
+ */
+export declare function folderArg(o: Options, env: Record<string, string | undefined>, command: string, required?: boolean): FolderArg | null;

package/dist/api/cli-options.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The command line options of the `datanotes` commands: `--name value` or `--name=value` for an
+ * option with a value, `--name` for a flag. An option the command does not know is refused with
+ * the closest one, so a typo never runs a command with its defaults.
+ */
+export interface OptionSpec {
+    /** Options that take a value. */
+    values?: readonly string[];
+    /** Options that take none. */
+    flags?: readonly string[];
+}
+/** A command line the command cannot run: what is wrong, and how to write it. */
+export declare class CliOptionError extends Error {
+    readonly hint: string;
+    readonly name = "CliOptionError";
+    /** Every command and its options. */
+    readonly docs = "https://datanotes.dev/reference/cli.md";
+    constructor(message: string, hint: string);
+}
+export interface Options {
+    /** The value of an option, when given. */
+    get(name: string): string | undefined;
+    /** Was a flag given? */
+    has(name: string): boolean;
+}
+/** Read `argv` against what `command` takes; throws {@link CliOptionError} on anything else. */
+export declare function readOptions(argv: readonly string[], spec: OptionSpec, command: string): Options;
+/** The folder a command works on, and how to read it. */
+export interface FolderArg {
+    folder: string;
+    /** `--database`: the folder is the database (metastore.yaml at its root); else a vault holding it. */
+    atRoot: boolean;
+}
+/**
+ * The folder of `--database` (the folder is the database) or `--vault` (a vault holding the
+ * database in a subfolder), else DATANOTES_DATABASE or DATANOTES_VAULT: one of the two, never
+ * both. Null when none is given and the command can do without (`required` false).
+ */
+export declare function folderArg(o: Options, env: Record<string, string | undefined>, command: string, required?: boolean): FolderArg | null;

package/dist/api/client.d.cts

@@ -0,0 +1,122 @@
+/**
+ * A client of the Datanotes HTTP API, with no dependency: it runs in Node, in browsers and in
+ * Obsidian (pass Obsidian's `requestUrl` as the transport). `call` runs an operation of the
+ * catalogue by name, the way agents name them; `request` reaches any route.
+ */
+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";
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface HttpResponse {
+    status: number;
+    text: string;
+}
+export type Transport = (req: HttpRequest) => Promise<HttpResponse>;
+/** Who is calling, recorded with every write (header `X-Datanotes-Actor`). Self-reported. */
+export interface ActorInfo {
+    /** The program: "claude-code", "cursor", a program's own name. */
+    harness?: string;
+    harness_version?: string;
+    model?: string;
+    /** The agent's session (the engine remembers the model an MCP server reports for it). */
+    session?: string;
+    /** The tool the agent called, when the call comes from an MCP server. */
+    tool?: string;
+}
+export declare const ACTOR_HEADER = "X-Datanotes-Actor";
+export declare class DatanotesError extends Error {
+    readonly kind: "unreachable" | "auth" | "http";
+    readonly status: number;
+    readonly name = "DatanotesError";
+    /** How to fix it, and where to read more (also at the end of the message). */
+    readonly hint?: string;
+    readonly docs?: string;
+    /** `unreachable`: the engine did not answer; `auth`: the token was refused. */
+    constructor(message: string, kind?: "unreachable" | "auth" | "http", status?: number, guidance?: Guidance | null);
+}
+export interface ClientOptions {
+    /** The engine's address, e.g. `http://127.0.0.1:27150`. */
+    url: string;
+    token: string;
+    /** 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;
+    args: Record<string, unknown>;
+    ok: boolean;
+    duration_ms: number;
+    value: unknown;
+    /** Who served it: "engine", or the name of the MCP server whose own tool it is. */
+    served_by: string;
+    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 {
+    private readonly o;
+    readonly url: string;
+    private readonly send;
+    constructor(o: ClientOptions);
+    /** 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;
+        text: string;
+    }>;
+    /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
+    post<T = unknown>(route: string, body?: unknown, actor?: ActorInfo): Promise<T>;
+    /**
+     * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
+     * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
+     * with the same message the engine gives.
+     */
+    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). 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

@@ -3,8 +3,9 @@
  * Obsidian (pass Obsidian's `requestUrl` as the transport). `call` runs an operation of the
  * catalogue by name, the way agents name them; `request` reaches any route.
  */
-import { type OperationResult } from "./results";
-import type { OperationDef } from "./catalog";
+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";
@@ -18,11 +19,11 @@ export interface HttpResponse {
 export type Transport = (req: HttpRequest) => Promise<HttpResponse>;
 /** Who is calling, recorded with every write (header `X-Datanotes-Actor`). Self-reported. */
 export interface ActorInfo {
-    /** The program: "claude-code", "cursor", an app's name. */
+    /** The program: "claude-code", "cursor", a program's own name. */
     harness?: string;
     harness_version?: string;
     model?: string;
-    /** The agent's session (the engine remembers the model an app reports for it). */
+    /** The agent's session (the engine remembers the model an MCP server reports for it). */
     session?: string;
     /** The tool the agent called, when the call comes from an MCP server. */
     tool?: string;
@@ -32,8 +33,11 @@ export declare class DatanotesError extends Error {
     readonly kind: "unreachable" | "auth" | "http";
     readonly status: number;
     readonly name = "DatanotesError";
+    /** How to fix it, and where to read more (also at the end of the message). */
+    readonly hint?: string;
+    readonly docs?: string;
     /** `unreachable`: the engine did not answer; `auth`: the token was refused. */
-    constructor(message: string, kind?: "unreachable" | "auth" | "http", status?: number);
+    constructor(message: string, kind?: "unreachable" | "auth" | "http", status?: number, guidance?: Guidance | null);
 }
 export interface ClientOptions {
     /** The engine's address, e.g. `http://127.0.0.1:27150`. */
@@ -42,24 +46,40 @@ 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;
 }
-/** A tool of a registered app, as `GET /datanotes/apps/tools/` lists it. */
-export interface AppTool extends Omit<OperationDef, "annotations"> {
-    annotations?: OperationDef["annotations"];
-    app: string;
-}
-/** One call of an operation or an app tool by an agent, for the engine's change feed. */
+/** 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;
     args: Record<string, unknown>;
     ok: boolean;
-    durationMs: number;
+    duration_ms: number;
     value: unknown;
-    /** Who served it: "engine" or the app's name. */
-    servedBy: string;
+    /** Who served it: "engine", or the name of the MCP server whose own tool it is. */
+    served_by: string;
     session?: string;
-    resultChars?: number;
-    resultTokens?: number;
+    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 {
@@ -67,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;
@@ -78,23 +104,19 @@ export declare class DatanotesClient {
     }>;
     /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
     post<T = unknown>(route: string, body?: unknown, actor?: ActorInfo): Promise<T>;
-    /** Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments. */
-    call(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult>;
-    /** Run an operation of the engine, or else a registered app's tool of that name. */
-    invoke(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult & {
-        servedBy: string;
-    }>;
+    /**
+     * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
+     * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
+     * with the same message the engine gives.
+     */
+    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>;
-    /** The tools of the registered apps and the apps' instructions for agents. */
-    appTools(): Promise<{
-        tools: AppTool[];
-        instructions: string;
-    }>;
-    /** Call an app's tool through the engine (which holds the app's credentials). */
-    callAppTool(name: string, args: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult & {
-        servedBy: string;
-    }>;
-    /** 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>;
 }