datanotes 3.1.0 → 3.3.0

package/dist/api/extension-manifest.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The manifest of a Datanotes extension (`datanotes-extension.json`, format version 1): parsing, validation
+ * with errors that teach (every problem at once, each as `<path>: <text>`), version comparison and the
+ * binding of table roles to real tables. The installer reads only this file before the user confirms, so
+ * everything an extension can do is declared here. No dependency but ./guidance.js.
+ */
+/** The manifest's file name at the root of the extension's repository. */
+export declare const MANIFEST_FILE = "datanotes-extension.json";
+/** Docs pages and headings that the errors of extensions point to (the pages are in docs/). */
+export declare const EXT_DOCS: {
+    readonly install: "https://datanotes.dev/administration/extensions.md#install-an-extension";
+    readonly tables: "https://datanotes.dev/administration/extensions.md#choose-the-tables-an-extension-uses";
+    readonly permissions: "https://datanotes.dev/administration/extensions.md#what-an-extension-can-do";
+    readonly update: "https://datanotes.dev/administration/extensions.md#update-an-extension";
+    readonly rollback: "https://datanotes.dev/administration/extensions.md#undo-an-install-or-an-update";
+    readonly remove: "https://datanotes.dev/administration/extensions.md#remove-an-extension";
+    readonly skipped: "https://datanotes.dev/administration/extensions.md#when-the-mcp-server-skips-an-extension";
+    readonly where: "https://datanotes.dev/administration/extensions.md#where-extensions-live";
+    readonly layout: "https://datanotes.dev/develop/write-an-extension.md#lay-out-the-repository";
+    readonly manifest: "https://datanotes.dev/develop/write-an-extension.md#write-the-manifest";
+    readonly declare: "https://datanotes.dev/develop/write-an-extension.md#declare-the-tables";
+    readonly tools: "https://datanotes.dev/develop/write-an-extension.md#write-the-tools";
+    readonly migrations: "https://datanotes.dev/develop/write-an-extension.md#migrate-the-schema-between-versions";
+    readonly publish: "https://datanotes.dev/develop/write-an-extension.md#check-and-publish-an-extension";
+};
+/** An extension's name (its token is `ext-<name>`). */
+export declare const EXTENSION_NAME: RegExp;
+/** A role, a table, a schema, a column, a base. */
+export declare const IDENT: RegExp;
+/** A tool's name. */
+export declare const TOOL_NAME: RegExp;
+/** The column types of the engine (a test checks the list against src/core). */
+export declare const COLUMN_TYPES: readonly string[];
+/** The attributes of a column spec in the engine (src/core/table-loader.ts; a test checks the list). */
+export declare const COLUMN_ATTRS: readonly string[];
+/** The operations a batch takes (src/server/rest.ts; a test checks the list). */
+export declare const BATCH_OPERATIONS: readonly string[];
+/** The operations that write rows. */
+export declare const DATA_OPERATIONS: readonly string[];
+/** An extension's own error: what is wrong, how to fix it, where to read more. */
+export declare class ExtensionError extends Error {
+    readonly hint: string;
+    readonly docs: string;
+    readonly code: string;
+    readonly name: string;
+    constructor(message: string, hint: string, docs: string, code?: string);
+}
+/** A manifest that is not valid: every problem, in the order of the walk. */
+export declare class ExtensionManifestError extends ExtensionError {
+    readonly problems: string[];
+    readonly name = "ExtensionManifestError";
+    constructor(problems: string[], file?: string);
+}
+/** Whether a table the extension depends on must have the column. */
+export type ColumnNeed = "required" | "optional";
+/** A column spec as the engine's operations take it, plus `need`. */
+export interface ManifestColumn {
+    name: string;
+    type: string;
+    description: string;
+    need: ColumnNeed;
+    [attribute: string]: unknown;
+}
+export interface ManifestConstraint {
+    name: string;
+    check: Record<string, unknown>;
+    hint: string;
+}
+export interface ManifestTable {
+    owned: boolean;
+    /** The table's name when created; the role when missing. */
+    name?: string;
+    schema?: string;
+    names?: string[];
+    description: string;
+    aliases?: string[];
+    filename?: string;
+    columns: ManifestColumn[];
+    constraints?: ManifestConstraint[];
+    instructions?: string;
+    bases?: string[];
+}
+export interface ManifestBase {
+    description: string;
+    columns: ManifestColumn[];
+}
+export interface ManifestView {
+    description: string;
+    query: Record<string, unknown>;
+    aliases?: string[];
+    labels?: Record<string, unknown>;
+}
+export interface ManifestTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: Record<string, unknown>;
+    /** Roles the tool reads or writes. */
+    tables: string[];
+    /** Roles the tool writes. */
+    writes: string[];
+}
+export interface ManifestMigration {
+    version: string;
+    description: string;
+    operations: ({
+        op: string;
+    } & Record<string, unknown>)[];
+}
+export interface ExtensionManifest {
+    manifest_version: 1;
+    name: string;
+    version: string;
+    description: string;
+    datanotes: string;
+    api: 1;
+    entry: string;
+    default_schema: string;
+    instructions?: string;
+    tables: Record<string, ManifestTable>;
+    /** The keys of `tables`, in order. */
+    roles: string[];
+    bases: Record<string, ManifestBase>;
+    views: Record<string, ManifestView>;
+    permissions: {
+        write: string[];
+    };
+    tools: ManifestTool[];
+    migrations: ManifestMigration[];
+}
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string | null;
+}
+/** MAJOR.MINOR.PATCH[-pre] (no leading `v`); null when it is not a version. */
+export declare function parseVersion(v: string): SemVer | null;
+/** Negative when a is older than b, 0 when equal, positive when newer. Throws for text that is not a version. */
+export declare function compareVersions(a: string, b: string): number;
+/** Whether an engine version meets a manifest's `">=X.Y.Z"`. A source run ("dev", "") meets every range. */
+export declare function satisfiesEngine(range: string, engineVersion: string): boolean;
+/** A string that is exactly a role: `@task`. */
+export declare const ROLE_REF: RegExp;
+/** A role inside a text: `@{task}`. */
+export declare const ROLE_TEXT: RegExp;
+/** A deep copy of `value` with every `@role` string and every `@{role}` in a string replaced by the role's table. Keys stay. */
+export declare function bindRoles<T>(value: T, tables: Readonly<Record<string, string>>): T;
+/** The roles a value names, in order of first appearance (both forms). */
+export declare function rolesNamed(value: unknown): string[];
+/** Read a manifest's text (a leading BOM is fine) and validate it. */
+export declare function parseManifest(text: string, file?: string): ExtensionManifest;
+/** Check a parsed manifest, collecting every problem; returns the typed manifest (a deep copy) or throws ExtensionManifestError. */
+export declare function validateManifest(raw: unknown, file?: string): ExtensionManifest;

package/dist/api/extension-plan.d.cts

@@ -0,0 +1,174 @@
+/**
+ * The install plan of a Datanotes extension: which table each role of the manifest uses, how the
+ * existing tables differ from what the manifest declares, the migrations between two versions, and
+ * the one batch that brings the database to the new version, with the token change, the tools, the
+ * problems and the record to write. Pure: the CLI reads the database (list_tables, describe_table,
+ * describe_database) and passes what it read; nothing here reads or writes anything.
+ */
+import type { ExtensionManifest } from "./extension-manifest.cjs";
+import type { ExtensionSourceRecord, InstalledExtension } from "./extension-record.cjs";
+/** What list_tables answered, with the database's default catalog. */
+export interface TablesListing {
+    default_catalog: string;
+    tables: {
+        qualified: string;
+        name: string;
+        catalog: string;
+        schema: string;
+        aliases?: string[];
+        tags?: Record<string, string>;
+    }[];
+    views: {
+        qualified: string;
+    }[];
+}
+/** The user's choices, from the options of the command. */
+export interface InstallChoices {
+    /** role → qualified table (`--map role=catalog.schema.table`). */
+    map: Record<string, string>;
+    /** role → (manifest column → the user's column) (`--map role.column=column`). */
+    columns: Record<string, Record<string, string>>;
+    /** Dependency roles to create (`--create`). */
+    create: string[];
+    /** role → manifest columns to add to the matched dependency table (`--add role.column`). */
+    add: Record<string, string[]>;
+    /** Catalog of created tables and views (`--catalog`; default: the database's default catalog). */
+    catalog?: string;
+    /** Schema of created owned tables and views (`--schema`; default: the manifest's default_schema). */
+    schema?: string;
+}
+export type TableDecision = "create" | "adopt" | "match" | "unresolved";
+/** The table chosen for one role. */
+export interface TableChoice {
+    role: string;
+    owned: boolean;
+    table: string | null;
+    decision: TableDecision;
+    /** True when the installer chose it, not the user: the agent must confirm it with the user. */
+    proposed: boolean;
+    candidates: string[];
+}
+export type ProblemCode = "engine_too_old" | "unknown_role" | "table_not_found" | "table_missing" | "table_exists" | "owned_create" | "ambiguous_dependency" | "missing_column" | "column_differs" | "owned_column_map" | "migration_conflict" | "base_differs" | "view_exists" | "tool_name_taken" | "token_exists" | "too_many_operations" | "already_installed" | "downgrade" | "same_version";
+/** Something that keeps the plan from being written: what is wrong, how to fix it, where to read more. */
+export interface PlanProblem {
+    code: ProblemCode;
+    role?: string;
+    table?: string;
+    column?: string;
+    detail: string;
+    hint: string;
+    docs: string;
+}
+/** What describe_table answered for an existing table. */
+export interface DescribedTable {
+    qualified: string;
+    columns: Record<string, unknown>[];
+    constraints?: Record<string, Record<string, unknown>>;
+    constraint_hints?: Record<string, string>;
+    instructions?: string;
+    bases?: string[];
+    tags?: Record<string, string>;
+}
+export interface PlanInput {
+    manifest: ExtensionManifest;
+    /** What was fetched: the label the user reads, the source record, the commit and the hashes. */
+    source: {
+        label: string;
+        record: ExtensionSourceRecord;
+        commit: string;
+        manifest_sha256: string;
+        entry_sha256: string;
+    };
+    engineVersion: string;
+    listing: TablesListing;
+    chosen: TableChoice[];
+    choiceProblems: PlanProblem[];
+    /** describe_table answers, by qualified name, for every bound existing table. */
+    described: Record<string, DescribedTable>;
+    /** describe_database bases. */
+    bases: {
+        name: string;
+        columns: string[];
+    }[];
+    choices: InstallChoices;
+    /** Names of the named tokens (/tokens/). */
+    tokens: string[];
+    /** The record of this extension, when installed. */
+    installed: InstalledExtension | null;
+    /** install: null; a repair: the fetched manifest itself (null is read as it); update: the installed version's manifest. */
+    oldManifest: ExtensionManifest | null;
+    /** The other installed extensions (their tool names). */
+    others: InstalledExtension[];
+    /** Engine operations and docs tools (the CLI passes OPERATIONS names + DOCS_TOOL_NAMES). */
+    reservedTools: string[];
+    /** Whether this machine holds the extension's token file. */
+    localTokenPresent: boolean;
+    /** ISO time for the record's dates. */
+    now: string;
+}
+export interface PlanTable {
+    role: string;
+    owned: boolean;
+    table: string | null;
+    decision: TableDecision;
+    proposed: boolean;
+    candidates: string[];
+    /** Human lines: "create", "add column repo", "replace CHECK run_has_executor", "set instructions", "add tags". */
+    changes: string[];
+    columns: Record<string, string>;
+    absent: string[];
+}
+export interface PlanTool {
+    name: string;
+    read_only: boolean;
+    /** Qualified names of the tables it writes. */
+    writes: string[];
+    change: "added" | "removed" | "changed" | "same";
+}
+export interface ExtensionPlan {
+    action: "install" | "repair" | "update";
+    extension: {
+        name: string;
+        version: string;
+        description: string;
+        from_version: string | null;
+        source: string;
+        commit: string;
+    };
+    tables: PlanTable[];
+    /** The batch, each `{ op, ...arguments }`, in order (empty: nothing to write). */
+    operations: Record<string, unknown>[];
+    token: {
+        name: string;
+        action: "create" | "rotate" | "update" | "keep";
+        write: string[];
+        previous_write: string[] | null;
+    };
+    tools: PlanTool[];
+    problems: PlanProblem[];
+    notes: string[];
+    ready: boolean;
+    agent_message: string;
+    summary: string;
+    /** The record to write after the batch (`migration_id` filled by the CLI); null when not ready. */
+    record: InstalledExtension | null;
+}
+/** The text every plan ends with, for the agent that runs the installer. */
+export declare const AGENT_MESSAGE = "For the agent installing this extension: show this plan to the user before anything is written. Where a table says \"proposed\", the installer chose it: ask the user to confirm it, to pick another table (--map <role>=<catalog.schema.table>, --map <role>.<column>=<column>), or to create it (--create <role>). Add a missing column only after the user agrees (--add <role>.<column>). Solve each problem the same way. Then run the same command again with the user's choices and --yes, only once the user approved the tables it creates or changes, the tools and the token's permissions.";
+/** The most operations one batch takes. */
+export declare const MAX_OPERATIONS = 200;
+/**
+ * How an existing column differs from what the manifest expects, in a few words (null: it fits).
+ * `ref: "self"` means `ownTable` on both sides. `strict` also compares hierarchy, acyclic and inverse
+ * (the extension's own tables); other attributes never count.
+ */
+export declare function columnDifference(expected: Record<string, unknown>, actual: Record<string, unknown>, ownTable: string, strict: boolean): string | null;
+/** The table of every role of the manifest, from the user's choices, the installed record and the listing. */
+export declare function chooseTables(m: ExtensionManifest, listing: TablesListing, choices: InstallChoices, installed: InstalledExtension | null): {
+    chosen: TableChoice[];
+    problems: PlanProblem[];
+};
+/** Compute the plan of an install, a repair or an update from what the CLI read. */
+export declare function planChanges(input: PlanInput): ExtensionPlan;
+/** The plan as the user reads it in a terminal. */
+export declare function renderPlan(plan: ExtensionPlan): string;

package/dist/api/extension-plan.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The install plan of a Datanotes extension: which table each role of the manifest uses, how the
+ * existing tables differ from what the manifest declares, the migrations between two versions, and
+ * the one batch that brings the database to the new version, with the token change, the tools, the
+ * problems and the record to write. Pure: the CLI reads the database (list_tables, describe_table,
+ * describe_database) and passes what it read; nothing here reads or writes anything.
+ */
+import type { ExtensionManifest } from "./extension-manifest.js";
+import type { ExtensionSourceRecord, InstalledExtension } from "./extension-record.js";
+/** What list_tables answered, with the database's default catalog. */
+export interface TablesListing {
+    default_catalog: string;
+    tables: {
+        qualified: string;
+        name: string;
+        catalog: string;
+        schema: string;
+        aliases?: string[];
+        tags?: Record<string, string>;
+    }[];
+    views: {
+        qualified: string;
+    }[];
+}
+/** The user's choices, from the options of the command. */
+export interface InstallChoices {
+    /** role → qualified table (`--map role=catalog.schema.table`). */
+    map: Record<string, string>;
+    /** role → (manifest column → the user's column) (`--map role.column=column`). */
+    columns: Record<string, Record<string, string>>;
+    /** Dependency roles to create (`--create`). */
+    create: string[];
+    /** role → manifest columns to add to the matched dependency table (`--add role.column`). */
+    add: Record<string, string[]>;
+    /** Catalog of created tables and views (`--catalog`; default: the database's default catalog). */
+    catalog?: string;
+    /** Schema of created owned tables and views (`--schema`; default: the manifest's default_schema). */
+    schema?: string;
+}
+export type TableDecision = "create" | "adopt" | "match" | "unresolved";
+/** The table chosen for one role. */
+export interface TableChoice {
+    role: string;
+    owned: boolean;
+    table: string | null;
+    decision: TableDecision;
+    /** True when the installer chose it, not the user: the agent must confirm it with the user. */
+    proposed: boolean;
+    candidates: string[];
+}
+export type ProblemCode = "engine_too_old" | "unknown_role" | "table_not_found" | "table_missing" | "table_exists" | "owned_create" | "ambiguous_dependency" | "missing_column" | "column_differs" | "owned_column_map" | "migration_conflict" | "base_differs" | "view_exists" | "tool_name_taken" | "token_exists" | "too_many_operations" | "already_installed" | "downgrade" | "same_version";
+/** Something that keeps the plan from being written: what is wrong, how to fix it, where to read more. */
+export interface PlanProblem {
+    code: ProblemCode;
+    role?: string;
+    table?: string;
+    column?: string;
+    detail: string;
+    hint: string;
+    docs: string;
+}
+/** What describe_table answered for an existing table. */
+export interface DescribedTable {
+    qualified: string;
+    columns: Record<string, unknown>[];
+    constraints?: Record<string, Record<string, unknown>>;
+    constraint_hints?: Record<string, string>;
+    instructions?: string;
+    bases?: string[];
+    tags?: Record<string, string>;
+}
+export interface PlanInput {
+    manifest: ExtensionManifest;
+    /** What was fetched: the label the user reads, the source record, the commit and the hashes. */
+    source: {
+        label: string;
+        record: ExtensionSourceRecord;
+        commit: string;
+        manifest_sha256: string;
+        entry_sha256: string;
+    };
+    engineVersion: string;
+    listing: TablesListing;
+    chosen: TableChoice[];
+    choiceProblems: PlanProblem[];
+    /** describe_table answers, by qualified name, for every bound existing table. */
+    described: Record<string, DescribedTable>;
+    /** describe_database bases. */
+    bases: {
+        name: string;
+        columns: string[];
+    }[];
+    choices: InstallChoices;
+    /** Names of the named tokens (/tokens/). */
+    tokens: string[];
+    /** The record of this extension, when installed. */
+    installed: InstalledExtension | null;
+    /** install: null; a repair: the fetched manifest itself (null is read as it); update: the installed version's manifest. */
+    oldManifest: ExtensionManifest | null;
+    /** The other installed extensions (their tool names). */
+    others: InstalledExtension[];
+    /** Engine operations and docs tools (the CLI passes OPERATIONS names + DOCS_TOOL_NAMES). */
+    reservedTools: string[];
+    /** Whether this machine holds the extension's token file. */
+    localTokenPresent: boolean;
+    /** ISO time for the record's dates. */
+    now: string;
+}
+export interface PlanTable {
+    role: string;
+    owned: boolean;
+    table: string | null;
+    decision: TableDecision;
+    proposed: boolean;
+    candidates: string[];
+    /** Human lines: "create", "add column repo", "replace CHECK run_has_executor", "set instructions", "add tags". */
+    changes: string[];
+    columns: Record<string, string>;
+    absent: string[];
+}
+export interface PlanTool {
+    name: string;
+    read_only: boolean;
+    /** Qualified names of the tables it writes. */
+    writes: string[];
+    change: "added" | "removed" | "changed" | "same";
+}
+export interface ExtensionPlan {
+    action: "install" | "repair" | "update";
+    extension: {
+        name: string;
+        version: string;
+        description: string;
+        from_version: string | null;
+        source: string;
+        commit: string;
+    };
+    tables: PlanTable[];
+    /** The batch, each `{ op, ...arguments }`, in order (empty: nothing to write). */
+    operations: Record<string, unknown>[];
+    token: {
+        name: string;
+        action: "create" | "rotate" | "update" | "keep";
+        write: string[];
+        previous_write: string[] | null;
+    };
+    tools: PlanTool[];
+    problems: PlanProblem[];
+    notes: string[];
+    ready: boolean;
+    agent_message: string;
+    summary: string;
+    /** The record to write after the batch (`migration_id` filled by the CLI); null when not ready. */
+    record: InstalledExtension | null;
+}
+/** The text every plan ends with, for the agent that runs the installer. */
+export declare const AGENT_MESSAGE = "For the agent installing this extension: show this plan to the user before anything is written. Where a table says \"proposed\", the installer chose it: ask the user to confirm it, to pick another table (--map <role>=<catalog.schema.table>, --map <role>.<column>=<column>), or to create it (--create <role>). Add a missing column only after the user agrees (--add <role>.<column>). Solve each problem the same way. Then run the same command again with the user's choices and --yes, only once the user approved the tables it creates or changes, the tools and the token's permissions.";
+/** The most operations one batch takes. */
+export declare const MAX_OPERATIONS = 200;
+/**
+ * How an existing column differs from what the manifest expects, in a few words (null: it fits).
+ * `ref: "self"` means `ownTable` on both sides. `strict` also compares hierarchy, acyclic and inverse
+ * (the extension's own tables); other attributes never count.
+ */
+export declare function columnDifference(expected: Record<string, unknown>, actual: Record<string, unknown>, ownTable: string, strict: boolean): string | null;
+/** The table of every role of the manifest, from the user's choices, the installed record and the listing. */
+export declare function chooseTables(m: ExtensionManifest, listing: TablesListing, choices: InstallChoices, installed: InstalledExtension | null): {
+    chosen: TableChoice[];
+    problems: PlanProblem[];
+};
+/** Compute the plan of an install, a repair or an update from what the CLI read. */
+export declare function planChanges(input: PlanInput): ExtensionPlan;
+/** The plan as the user reads it in a terminal. */
+export declare function renderPlan(plan: ExtensionPlan): string;

package/dist/api/extension-record.d.cts

@@ -0,0 +1,65 @@
+/**
+ * The record of an installed extension: what `datanotes extension install` writes to the engine's
+ * registry (`POST /datanotes/extensions/record/`) and every MCP host reads back
+ * (`POST /datanotes/extensions/`). Shape only: this file imports nothing.
+ */
+export interface RecordTable {
+    /** The qualified table bound to the role. */
+    table: string;
+    /** True for a role the extension owns. */
+    owned: boolean;
+    /** Dependency roles: manifest column → the user's column, only where they differ. */
+    columns?: Record<string, string>;
+    /** Dependency roles: optional manifest columns the bound table does not have. */
+    absent?: string[];
+}
+export interface ExtensionSourceRecord {
+    kind: "git" | "local";
+    /** git: the URL as given (https://…, git@…, ssh://…, file://…). */
+    url?: string;
+    /** git: the tag or commit id given (or the newest tag chosen). */
+    ref?: string;
+    /** local: the absolute folder, with "/" separators. */
+    path?: string;
+}
+export interface InstalledExtension {
+    name: string;
+    version: string;
+    description: string;
+    api: number;
+    source: ExtensionSourceRecord;
+    /** The git commit id (40 hex), or "local-<12 hex>" for a folder. */
+    commit: string;
+    manifest_sha256: string;
+    entry_sha256: string;
+    /** The extension's named token: "ext-<name>". */
+    token: string;
+    tables: Record<string, RecordTable>;
+    tools: string[];
+    /** The token's write patterns (qualified table names). */
+    write: string[];
+    /** The batch that brought the database from `previous` to this record (null: nothing was written). */
+    migration_id: string | null;
+    installed_at: string;
+    updated_at: string;
+    /** The record before the last install, repair or update (null after a first install). */
+    previous: InstalledExtension | null;
+}
+export interface ExtensionList {
+    database_id: string | null;
+    extensions: InstalledExtension[];
+}
+/** The rule of extension names (the same as EXTENSION_NAME in extension-manifest.ts). */
+export declare const RECORD_NAME: RegExp;
+/**
+ * The rule of a record's commit: a git commit id (40 hex) or a folder's content id ("local-" and lowercase letters,
+ * digits, "." or "-"). The registry checks only shape; the extension host and the commands check this before they
+ * build a path from a record.
+ */
+export declare const RECORD_COMMIT: RegExp;
+/** The rule of a database id: a UUID, as src/api/local.ts reads it. It names a folder of the token files. */
+export declare const DATABASE_ID: RegExp;
+/** The largest record the registry keeps (JSON characters). */
+export declare const MAX_RECORD_CHARS = 1000000;
+/** The problems of a record (empty: valid), each a short sentence naming the field. Unknown keys are kept. */
+export declare function recordProblems(v: unknown, prefix?: string): string[];

package/dist/api/extension-record.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The record of an installed extension: what `datanotes extension install` writes to the engine's
+ * registry (`POST /datanotes/extensions/record/`) and every MCP host reads back
+ * (`POST /datanotes/extensions/`). Shape only: this file imports nothing.
+ */
+export interface RecordTable {
+    /** The qualified table bound to the role. */
+    table: string;
+    /** True for a role the extension owns. */
+    owned: boolean;
+    /** Dependency roles: manifest column → the user's column, only where they differ. */
+    columns?: Record<string, string>;
+    /** Dependency roles: optional manifest columns the bound table does not have. */
+    absent?: string[];
+}
+export interface ExtensionSourceRecord {
+    kind: "git" | "local";
+    /** git: the URL as given (https://…, git@…, ssh://…, file://…). */
+    url?: string;
+    /** git: the tag or commit id given (or the newest tag chosen). */
+    ref?: string;
+    /** local: the absolute folder, with "/" separators. */
+    path?: string;
+}
+export interface InstalledExtension {
+    name: string;
+    version: string;
+    description: string;
+    api: number;
+    source: ExtensionSourceRecord;
+    /** The git commit id (40 hex), or "local-<12 hex>" for a folder. */
+    commit: string;
+    manifest_sha256: string;
+    entry_sha256: string;
+    /** The extension's named token: "ext-<name>". */
+    token: string;
+    tables: Record<string, RecordTable>;
+    tools: string[];
+    /** The token's write patterns (qualified table names). */
+    write: string[];
+    /** The batch that brought the database from `previous` to this record (null: nothing was written). */
+    migration_id: string | null;
+    installed_at: string;
+    updated_at: string;
+    /** The record before the last install, repair or update (null after a first install). */
+    previous: InstalledExtension | null;
+}
+export interface ExtensionList {
+    database_id: string | null;
+    extensions: InstalledExtension[];
+}
+/** The rule of extension names (the same as EXTENSION_NAME in extension-manifest.ts). */
+export declare const RECORD_NAME: RegExp;
+/**
+ * The rule of a record's commit: a git commit id (40 hex) or a folder's content id ("local-" and lowercase letters,
+ * digits, "." or "-"). The registry checks only shape; the extension host and the commands check this before they
+ * build a path from a record.
+ */
+export declare const RECORD_COMMIT: RegExp;
+/** The rule of a database id: a UUID, as src/api/local.ts reads it. It names a folder of the token files. */
+export declare const DATABASE_ID: RegExp;
+/** The largest record the registry keeps (JSON characters). */
+export declare const MAX_RECORD_CHARS = 1000000;
+/** The problems of a record (empty: valid), each a short sentence naming the field. Unknown keys are kept. */
+export declare function recordProblems(v: unknown, prefix?: string): string[];