@wrenai/genbi 0.0.1

package/dist-server/server/native-artifacts.d.ts

@@ -0,0 +1,1004 @@
+import { type NativeSessionRow, type NativeStructuredAnswerRow, type Store } from "./db.js";
+import type { EnrichmentBinding } from "./enrichment.js";
+export declare const NATIVE_MCP_CREDENTIAL_ENV_VAR = "WARBLE_MCP_CONNECTION_CREDENTIAL";
+export declare const NATIVE_MCP_TOOL_NAME = "save_dashboard";
+export declare const NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME = "persist_answer";
+export declare const NATIVE_MCP_SERVER_LABEL = "GenBI MCP";
+export declare const NATIVE_MCP_ARTIFACTS_LABEL = "GenBI Artifacts";
+/**
+ * Rules that relate sibling fields and therefore cannot be expressed by the
+ * JSON Schema vocabulary used by MCP. These descriptions and the executable
+ * helpers below form the advertised second validation layer.
+ */
+export declare const NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS: {
+    readonly table: {
+        readonly positionalRows: "Positional scalar rows in columns order. Each row must contain exactly one cell per columns entry.";
+    };
+    readonly chart: {
+        readonly x: "The x field must not also appear in series.";
+        readonly series: "Each series item must differ from x.";
+        readonly positionalRows: "Positional scalar rows in [x, ...series] order. Each row must contain exactly one x cell plus one cell per series entry.";
+    };
+};
+/** The exact public MCP shape advertised to native clients and accepted by the host. */
+export declare const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version", "name", "idempotency_key"];
+    readonly oneOf: readonly [{
+        readonly required: readonly ["envelope"];
+        readonly not: {
+            readonly anyOf: readonly [{
+                readonly required: readonly ["answer_ref"];
+            }, {
+                readonly required: readonly ["answer_selection"];
+            }];
+        };
+    }, {
+        readonly required: readonly ["answer_ref"];
+        readonly not: {
+            readonly anyOf: readonly [{
+                readonly required: readonly ["envelope"];
+            }, {
+                readonly required: readonly ["answer_selection"];
+            }];
+        };
+    }, {
+        readonly required: readonly ["answer_selection"];
+        readonly not: {
+            readonly anyOf: readonly [{
+                readonly required: readonly ["envelope"];
+            }, {
+                readonly required: readonly ["answer_ref"];
+            }];
+        };
+    }];
+    readonly properties: {
+        readonly version: {
+            readonly anyOf: readonly [{
+                readonly const: "1";
+            }, {
+                readonly const: 1;
+            }];
+            readonly description: "Use the canonical string literal \"1\". Numeric 1 is accepted for Claude Code compatibility and is canonicalized before persistence.";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly not: {
+                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+            };
+            readonly minLength: 1;
+            readonly maxLength: 120;
+            readonly pattern: "\\S";
+        };
+        readonly idempotency_key: {
+            readonly type: "string";
+            readonly not: {
+                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+            };
+            readonly minLength: 8;
+            readonly maxLength: 128;
+            readonly pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]+$";
+        };
+        readonly answer_ref: {
+            readonly type: "string";
+            readonly not: {
+                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+            };
+            readonly pattern: "^answer-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
+            readonly description: "Opaque reference returned by persist_answer for this native session.";
+        };
+        readonly answer_selection: {
+            readonly const: "latest";
+            readonly description: "Resolve the newest verified answer retained by this native session when its opaque answer_ref is no longer available in the conversation.";
+        };
+        readonly envelope: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["blocks", "verified"];
+            readonly properties: {
+                readonly verified: {
+                    readonly const: true;
+                };
+                readonly summary: {
+                    readonly anyOf: readonly [{
+                        readonly type: "string";
+                        readonly not: {
+                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                        };
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly estimate: {
+                    readonly type: readonly ["boolean", "null"];
+                };
+                readonly blocks: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "label", "value"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "kpi_card";
+                                };
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                };
+                                readonly value: {
+                                    readonly anyOf: readonly [{
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                    }, {
+                                        readonly type: "number";
+                                    }];
+                                };
+                                readonly unit: {
+                                    readonly anyOf: readonly [{
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                    }, {
+                                        readonly type: "null";
+                                    }];
+                                };
+                                readonly delta: {
+                                    readonly type: readonly ["number", "null"];
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "columns", "rows"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "table";
+                                };
+                                readonly columns: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly uniqueItems: true;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly rows: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly anyOf: readonly [{
+                                                readonly type: "string";
+                                                readonly not: {
+                                                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                                };
+                                            }, {
+                                                readonly type: "number";
+                                            }, {
+                                                readonly type: "boolean";
+                                            }, {
+                                                readonly type: "null";
+                                            }];
+                                        };
+                                    };
+                                    readonly description: "Positional scalar rows in columns order. Each row must contain exactly one cell per columns entry.";
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "chart_type", "x", "series", "rows"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "chart";
+                                };
+                                readonly chart_type: {
+                                    readonly enum: readonly ["bar", "line", "pie", "area", "scatter"];
+                                };
+                                readonly x: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                    readonly minLength: 1;
+                                    readonly description: "The x field must not also appear in series.";
+                                };
+                                readonly series: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly uniqueItems: true;
+                                    readonly description: "Each series item must differ from x.";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly rows: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly anyOf: readonly [{
+                                                readonly type: "string";
+                                                readonly not: {
+                                                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                                };
+                                            }, {
+                                                readonly type: "number";
+                                            }, {
+                                                readonly type: "boolean";
+                                            }, {
+                                                readonly type: "null";
+                                            }];
+                                        };
+                                    };
+                                    readonly description: "Positional scalar rows in [x, ...series] order. Each row must contain exactly one x cell plus one cell per series entry.";
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "sql", "source_tables", "filters"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "definition";
+                                };
+                                readonly sql: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                    readonly minLength: 1;
+                                };
+                                readonly source_tables: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly filters: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "text"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "narrative";
+                                };
+                                readonly text: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                    readonly minLength: 1;
+                                };
+                                readonly title: {
+                                    readonly anyOf: readonly [{
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                    }, {
+                                        readonly type: "null";
+                                    }];
+                                };
+                            };
+                        }];
+                    };
+                };
+            };
+        };
+    };
+};
+/**
+ * The producer persists only the existing answer_query result blocks. The
+ * semantic validator below requires exactly one table and allows at most one
+ * definition block. It rejects summary/chart/raw/transcript-shaped additions.
+ */
+export declare const NATIVE_PERSIST_ANSWER_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version", "idempotency_key", "envelope"];
+    readonly properties: {
+        readonly version: {
+            readonly const: "1";
+        };
+        readonly idempotency_key: {
+            readonly type: "string";
+            readonly not: {
+                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+            };
+            readonly minLength: 8;
+            readonly maxLength: 128;
+            readonly pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]+$";
+            readonly description: "Caller retry key only; the host mints canonical answer provenance.";
+        };
+        readonly envelope: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["blocks", "verified"];
+            readonly properties: {
+                readonly verified: {
+                    readonly const: true;
+                };
+                readonly blocks: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 2;
+                    readonly items: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "columns", "rows"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "table";
+                                };
+                                readonly columns: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly uniqueItems: true;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly rows: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly anyOf: readonly [{
+                                                readonly type: "string";
+                                                readonly not: {
+                                                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                                };
+                                            }, {
+                                                readonly type: "number";
+                                            }, {
+                                                readonly type: "boolean";
+                                            }, {
+                                                readonly type: "null";
+                                            }];
+                                        };
+                                    };
+                                    readonly description: "Positional scalar rows in columns order. Each row must contain exactly one cell per columns entry.";
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["type", "sql", "source_tables", "filters"];
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "definition";
+                                };
+                                readonly sql: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                    readonly minLength: 1;
+                                };
+                                readonly source_tables: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly filters: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                    };
+                                };
+                            };
+                        }];
+                    };
+                    readonly allOf: readonly [{
+                        readonly contains: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly type: {
+                                    readonly const: "table";
+                                };
+                            };
+                            readonly required: readonly ["type"];
+                        };
+                    }];
+                };
+            };
+        };
+    };
+};
+export interface NativeMcpDescriptor {
+    readonly version: "1";
+    readonly url: string;
+    readonly credential: string;
+}
+export interface NativeMcpReadiness {
+    readonly available: boolean;
+    readonly reason?: string;
+}
+/** Browser-safe health projection; credentials and binding details stay server-side. */
+export interface NativeMcpHealth extends NativeMcpReadiness {
+    readonly server: typeof NATIVE_MCP_SERVER_LABEL;
+    readonly tool: typeof NATIVE_MCP_TOOL_NAME;
+    readonly destination: typeof NATIVE_MCP_ARTIFACTS_LABEL;
+}
+export interface SaveDashboardPayloadInput {
+    readonly version: "1";
+    readonly name: string;
+    readonly envelope: unknown;
+    readonly idempotency_key: string;
+}
+export interface SaveDashboardReferenceInput {
+    readonly version: "1";
+    readonly name: string;
+    readonly answer_ref: string;
+    readonly idempotency_key: string;
+}
+export interface SaveDashboardLatestInput {
+    readonly version: "1";
+    readonly name: string;
+    readonly answer_selection: "latest";
+    readonly idempotency_key: string;
+}
+export type SaveDashboardInput = SaveDashboardPayloadInput | SaveDashboardReferenceInput | SaveDashboardLatestInput;
+export interface PersistStructuredAnswerInput {
+    readonly version: "1";
+    readonly idempotency_key: string;
+    readonly envelope: unknown;
+}
+export interface PersistedStructuredAnswer {
+    readonly answer_ref: string;
+    readonly digest: string;
+    readonly persisted_at: string;
+}
+export interface SavedNativeArtifact {
+    readonly artifact_id: string;
+    readonly saved_at: string;
+    readonly source_href: string;
+}
+export declare class NativeArtifactError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** Shared executable counterpart of the advertised positional-row rules. */
+export declare function hasExactNativePositionalRow(row: unknown, expectedLength: number): boolean;
+/** Shared executable counterpart of the advertised chart x/series rule. */
+export declare function hasDistinctNativeChartSeries(x: unknown, series: unknown): series is string[];
+/** The complete MCP contract: mechanically checked schema plus semantic rules. */
+export declare const NATIVE_SAVE_DASHBOARD_CONTRACT: {
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["version", "name", "idempotency_key"];
+        readonly oneOf: readonly [{
+            readonly required: readonly ["envelope"];
+            readonly not: {
+                readonly anyOf: readonly [{
+                    readonly required: readonly ["answer_ref"];
+                }, {
+                    readonly required: readonly ["answer_selection"];
+                }];
+            };
+        }, {
+            readonly required: readonly ["answer_ref"];
+            readonly not: {
+                readonly anyOf: readonly [{
+                    readonly required: readonly ["envelope"];
+                }, {
+                    readonly required: readonly ["answer_selection"];
+                }];
+            };
+        }, {
+            readonly required: readonly ["answer_selection"];
+            readonly not: {
+                readonly anyOf: readonly [{
+                    readonly required: readonly ["envelope"];
+                }, {
+                    readonly required: readonly ["answer_ref"];
+                }];
+            };
+        }];
+        readonly properties: {
+            readonly version: {
+                readonly anyOf: readonly [{
+                    readonly const: "1";
+                }, {
+                    readonly const: 1;
+                }];
+                readonly description: "Use the canonical string literal \"1\". Numeric 1 is accepted for Claude Code compatibility and is canonicalized before persistence.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly not: {
+                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                };
+                readonly minLength: 1;
+                readonly maxLength: 120;
+                readonly pattern: "\\S";
+            };
+            readonly idempotency_key: {
+                readonly type: "string";
+                readonly not: {
+                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                };
+                readonly minLength: 8;
+                readonly maxLength: 128;
+                readonly pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]+$";
+            };
+            readonly answer_ref: {
+                readonly type: "string";
+                readonly not: {
+                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                };
+                readonly pattern: "^answer-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
+                readonly description: "Opaque reference returned by persist_answer for this native session.";
+            };
+            readonly answer_selection: {
+                readonly const: "latest";
+                readonly description: "Resolve the newest verified answer retained by this native session when its opaque answer_ref is no longer available in the conversation.";
+            };
+            readonly envelope: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["blocks", "verified"];
+                readonly properties: {
+                    readonly verified: {
+                        readonly const: true;
+                    };
+                    readonly summary: {
+                        readonly anyOf: readonly [{
+                            readonly type: "string";
+                            readonly not: {
+                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                            };
+                        }, {
+                            readonly type: "null";
+                        }];
+                    };
+                    readonly estimate: {
+                        readonly type: readonly ["boolean", "null"];
+                    };
+                    readonly blocks: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly oneOf: readonly [{
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "label", "value"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "kpi_card";
+                                    };
+                                    readonly label: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                    };
+                                    readonly value: {
+                                        readonly anyOf: readonly [{
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                        }, {
+                                            readonly type: "number";
+                                        }];
+                                    };
+                                    readonly unit: {
+                                        readonly anyOf: readonly [{
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                        }, {
+                                            readonly type: "null";
+                                        }];
+                                    };
+                                    readonly delta: {
+                                        readonly type: readonly ["number", "null"];
+                                    };
+                                };
+                            }, {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "columns", "rows"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "table";
+                                    };
+                                    readonly columns: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly uniqueItems: true;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly rows: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly anyOf: readonly [{
+                                                    readonly type: "string";
+                                                    readonly not: {
+                                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                                    };
+                                                }, {
+                                                    readonly type: "number";
+                                                }, {
+                                                    readonly type: "boolean";
+                                                }, {
+                                                    readonly type: "null";
+                                                }];
+                                            };
+                                        };
+                                        readonly description: "Positional scalar rows in columns order. Each row must contain exactly one cell per columns entry.";
+                                    };
+                                };
+                            }, {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "chart_type", "x", "series", "rows"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "chart";
+                                    };
+                                    readonly chart_type: {
+                                        readonly enum: readonly ["bar", "line", "pie", "area", "scatter"];
+                                    };
+                                    readonly x: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                        readonly description: "The x field must not also appear in series.";
+                                    };
+                                    readonly series: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly uniqueItems: true;
+                                        readonly description: "Each series item must differ from x.";
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly rows: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly anyOf: readonly [{
+                                                    readonly type: "string";
+                                                    readonly not: {
+                                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                                    };
+                                                }, {
+                                                    readonly type: "number";
+                                                }, {
+                                                    readonly type: "boolean";
+                                                }, {
+                                                    readonly type: "null";
+                                                }];
+                                            };
+                                        };
+                                        readonly description: "Positional scalar rows in [x, ...series] order. Each row must contain exactly one x cell plus one cell per series entry.";
+                                    };
+                                };
+                            }, {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "sql", "source_tables", "filters"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "definition";
+                                    };
+                                    readonly sql: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                    readonly source_tables: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly filters: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                        };
+                                    };
+                                };
+                            }, {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "text"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "narrative";
+                                    };
+                                    readonly text: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                    readonly title: {
+                                        readonly anyOf: readonly [{
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                        }, {
+                                            readonly type: "null";
+                                        }];
+                                    };
+                                };
+                            }];
+                        };
+                    };
+                };
+            };
+        };
+    };
+    readonly semanticConstraints: {
+        readonly table: {
+            readonly positionalRows: "Positional scalar rows in columns order. Each row must contain exactly one cell per columns entry.";
+        };
+        readonly chart: {
+            readonly x: "The x field must not also appear in series.";
+            readonly series: "Each series item must differ from x.";
+            readonly positionalRows: "Positional scalar rows in [x, ...series] order. Each row must contain exactly one x cell plus one cell per series entry.";
+        };
+    };
+    readonly hasExactPositionalRow: typeof hasExactNativePositionalRow;
+    readonly hasDistinctChartSeries: typeof hasDistinctNativeChartSeries;
+};
+export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["version", "idempotency_key", "envelope"];
+        readonly properties: {
+            readonly version: {
+                readonly const: "1";
+            };
+            readonly idempotency_key: {
+                readonly type: "string";
+                readonly not: {
+                    readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                };
+                readonly minLength: 8;
+                readonly maxLength: 128;
+                readonly pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]+$";
+                readonly description: "Caller retry key only; the host mints canonical answer provenance.";
+            };
+            readonly envelope: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["blocks", "verified"];
+                readonly properties: {
+                    readonly verified: {
+                        readonly const: true;
+                    };
+                    readonly blocks: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly maxItems: 2;
+                        readonly items: {
+                            readonly oneOf: readonly [{
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "columns", "rows"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "table";
+                                    };
+                                    readonly columns: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly uniqueItems: true;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly rows: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly anyOf: readonly [{
+                                                    readonly type: "string";
+                                                    readonly not: {
+                                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                                    };
+                                                }, {
+                                                    readonly type: "number";
+                                                }, {
+                                                    readonly type: "boolean";
+                                                }, {
+                                                    readonly type: "null";
+                                                }];
+                                            };
+                                        };
+                                        readonly description: "Positional scalar rows in columns order. Each row must contain exactly one cell per columns entry.";
+                                    };
+                                };
+                            }, {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "sql", "source_tables", "filters"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "definition";
+                                    };
+                                    readonly sql: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                    };
+                                    readonly source_tables: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly filters: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly not: {
+                                                readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                            };
+                                        };
+                                    };
+                                };
+                            }];
+                        };
+                        readonly allOf: readonly [{
+                            readonly contains: {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "table";
+                                    };
+                                };
+                                readonly required: readonly ["type"];
+                            };
+                        }];
+                    };
+                };
+            };
+        };
+    };
+    readonly semanticConstraint: "The envelope contains exactly one typed table block and at most one typed definition block, with no presentation-only fields.";
+};
+export interface NativeArtifactServiceOptions {
+    readonly store: Store;
+    readonly artifactsRoot: string;
+    /** Canonical local BFF endpoint derived from its actual listener port. */
+    readonly expectedMcpUrl: string;
+    /** Optional override, accepted only when it is the expected local endpoint. */
+    readonly mcpUrl: string;
+    readonly getBinding: () => EnrichmentBinding | undefined;
+    /** Test-only seam; production writes one contained JSON file atomically. */
+    readonly writeAtomic?: (target: string, contents: string) => void;
+    /** Test-only seam for a persistence outage; production uses the typed Store method. */
+    readonly persistStructuredAnswer?: (input: {
+        readonly id: string;
+        readonly nativeSessionId: string;
+        readonly idempotencyKey: string;
+        readonly envelopeJson: string;
+        readonly digest: string;
+    }) => {
+        readonly row: NativeStructuredAnswerRow;
+        readonly created: boolean;
+    };
+}
+export declare class NativeArtifactService {
+    private readonly options;
+    private readonly credentials;
+    constructor(options: NativeArtifactServiceOptions);
+    /** Validate the exact local BFF endpoint before advertising or issuing it. */
+    readiness(): NativeMcpReadiness;
+    issue(session: NativeSessionRow, binding: EnrichmentBinding | undefined): NativeMcpDescriptor;
+    revoke(credential: string | undefined): void;
+    /** Releases opaque credentials when the owning BFF service shuts down. */
+    dispose(): void;
+    hasCredential(credential: string | undefined): boolean;
+    health(): NativeMcpHealth;
+    /**
+     * Resolves the live session behind an opaque MCP credential without exposing
+     * its secret or binding. The generic MCP route uses this before purpose/tool
+     * allowlisting; artifact persistence applies its stricter bound-project
+     * fence below.
+     */
+    authorize(credential: string | undefined): NativeSessionRow;
+    /**
+     * Retains the exact typed answer before conversational presentation. This
+     * contract is intentionally independent of dashboard naming/save intent so
+     * a later follow-up can only reference this stored result, never recompute.
+     */
+    persistAnswer(credential: string | undefined, input: unknown): PersistedStructuredAnswer;
+    save(credential: string | undefined, input: unknown): SavedNativeArtifact;
+}