@wrenai/genbi 0.0.4 → 0.0.6

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

@@ -1,8 +1,10 @@
 import { type NativeSessionRow, type NativeStructuredAnswerRow, type Store } from "./db.js";
 import type { EnrichmentBinding } from "./enrichment.js";
+import type { ComponentAccess } from "../harness/components/broker.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_QUERY_TOOL_NAME = "query";
 export declare const NATIVE_MCP_SERVER_LABEL = "GenBI MCP";
 export declare const NATIVE_MCP_ARTIFACTS_LABEL = "GenBI Artifacts";
 /**
@@ -20,7 +22,6 @@ export declare const NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS: {
         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;
@@ -90,7 +91,7 @@ export declare const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA: {
         };
         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 description: "Resolve the newest answer retained by this native session when its opaque answer_ref is no longer available in the conversation.";
         };
         readonly envelope: {
             readonly type: "object";
@@ -98,7 +99,8 @@ export declare const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA: {
             readonly required: readonly ["blocks", "verified"];
             readonly properties: {
                 readonly verified: {
-                    readonly const: true;
+                    readonly type: "boolean";
+                    readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                 };
                 readonly summary: {
                     readonly anyOf: readonly [{
@@ -286,6 +288,15 @@ export declare const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA: {
                                         };
                                     };
                                 };
+                                readonly query_id: {
+                                    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: 64;
+                                    readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                };
                             };
                         }, {
                             readonly type: "object";
@@ -349,7 +360,8 @@ export declare const NATIVE_PERSIST_ANSWER_INPUT_SCHEMA: {
             readonly required: readonly ["blocks", "verified"];
             readonly properties: {
                 readonly verified: {
-                    readonly const: true;
+                    readonly type: "boolean";
+                    readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                 };
                 readonly blocks: {
                     readonly type: "array";
@@ -433,6 +445,15 @@ export declare const NATIVE_PERSIST_ANSWER_INPUT_SCHEMA: {
                                         };
                                     };
                                 };
+                                readonly query_id: {
+                                    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: 64;
+                                    readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                };
                             };
                         }];
                     };
@@ -580,7 +601,7 @@ export declare const NATIVE_SAVE_DASHBOARD_CONTRACT: {
             };
             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 description: "Resolve the newest answer retained by this native session when its opaque answer_ref is no longer available in the conversation.";
             };
             readonly envelope: {
                 readonly type: "object";
@@ -588,7 +609,8 @@ export declare const NATIVE_SAVE_DASHBOARD_CONTRACT: {
                 readonly required: readonly ["blocks", "verified"];
                 readonly properties: {
                     readonly verified: {
-                        readonly const: true;
+                        readonly type: "boolean";
+                        readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                     };
                     readonly summary: {
                         readonly anyOf: readonly [{
@@ -776,6 +798,15 @@ export declare const NATIVE_SAVE_DASHBOARD_CONTRACT: {
                                             };
                                         };
                                     };
+                                    readonly query_id: {
+                                        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: 64;
+                                        readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                    };
                                 };
                             }, {
                                 readonly type: "object";
@@ -848,7 +879,8 @@ export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
                 readonly required: readonly ["blocks", "verified"];
                 readonly properties: {
                     readonly verified: {
-                        readonly const: true;
+                        readonly type: "boolean";
+                        readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                     };
                     readonly blocks: {
                         readonly type: "array";
@@ -932,6 +964,15 @@ export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
                                             };
                                         };
                                     };
+                                    readonly query_id: {
+                                        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: 64;
+                                        readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                    };
                                 };
                             }];
                         };
@@ -953,6 +994,29 @@ export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
     };
     readonly semanticConstraint: "The envelope contains exactly one typed table block and at most one typed definition block, with no presentation-only fields.";
 };
+/** The session `query` tool: one read-only SQL query run by the host through governed access. */
+export declare const NATIVE_QUERY_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["sql"];
+    readonly properties: {
+        readonly sql: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "One read-only SELECT over the bound semantic models.";
+        };
+        readonly limit: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Maximum rows to return (default 1000).";
+        };
+    };
+};
+export interface NativeQueryResult {
+    readonly isError: boolean;
+    readonly text: string;
+    readonly result?: unknown;
+}
 export interface NativeArtifactServiceOptions {
     readonly store: Store;
     readonly artifactsRoot: string;
@@ -961,6 +1025,11 @@ export interface NativeArtifactServiceOptions {
     /** Optional override, accepted only when it is the expected local endpoint. */
     readonly mcpUrl: string;
     readonly getBinding: () => EnrichmentBinding | undefined;
+    /**
+     * Opens governed Wren access for one native analysis session's `query` tool, against the
+     * session's bound project. Without it, the tool is not offered.
+     */
+    readonly openQueryAccess?: (binding: EnrichmentBinding, signal: AbortSignal) => Promise<ComponentAccess>;
     /** 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. */
@@ -970,6 +1039,7 @@ export interface NativeArtifactServiceOptions {
         readonly idempotencyKey: string;
         readonly envelopeJson: string;
         readonly digest: string;
+        readonly grounded: boolean;
     }) => {
         readonly row: NativeStructuredAnswerRow;
         readonly created: boolean;
@@ -978,11 +1048,32 @@ export interface NativeArtifactServiceOptions {
 export declare class NativeArtifactService {
     private readonly options;
     private readonly credentials;
+    /** One host query recorder per native session: its observations are never shared across sessions. */
+    private readonly queryRecorders;
+    private readonly queryClosing;
     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;
+    /** Whether native analysis sessions are offered the host `query` tool. */
+    queryAvailable(): boolean;
+    /** Resolves once every session query recorder closed so far has released its governed access. */
+    queriesClosed(): Promise<void>;
+    private closeQueries;
+    /**
+     * The session `query` tool: runs one read-only query through governed access against the
+     * session's bound project, records it as this session's observation and returns its rows with
+     * a session-tagged host `query_id` that a later persist_answer or save_dashboard may cite.
+     */
+    query(credential: string | undefined, input: unknown): Promise<NativeQueryResult>;
+    /**
+     * The host's grounding decision for a model-written envelope: the same envelope rebuilt from
+     * this session's query observations when every query it cites grounds on them (see
+     * `groundOnHostEvidence`), else `undefined`. Only this decision reaches a grounded entry from
+     * the MCP surface.
+     */
+    private groundedEnvelope;
     /** Releases opaque credentials when the owning BFF service shuts down. */
     dispose(): void;
     hasCredential(credential: string | undefined): boolean;
@@ -1000,5 +1091,19 @@ export declare class NativeArtifactService {
      * a later follow-up can only reference this stored result, never recompute.
      */
     persistAnswer(credential: string | undefined, input: unknown): PersistedStructuredAnswer;
+    /**
+     * Host-only entry for a grounded component root (never exposed over MCP).
+     * The caller must already have checked the component's verified provenance.
+     */
+    persistGroundedAnswer(credential: string | undefined, input: unknown): PersistedStructuredAnswer;
+    private persistStructured;
     save(credential: string | undefined, input: unknown): SavedNativeArtifact;
+    /**
+     * Host-only entry for a grounded component render root (never exposed over
+     * MCP). The caller must already have checked verified provenance.
+     */
+    saveGrounded(credential: string | undefined, input: unknown): SavedNativeArtifact;
+    /** The credential, session and binding checks every save runs before it reads its payload. */
+    private authorizeSave;
+    private saveArtifact;
 }

package/dist-server/server/native-artifacts.js

@@ -7,6 +7,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { newId } from "./db.js";
+import { createHostQueryRecorder } from "../harness/route/host-query.js";
+import { groundOnHostEvidence } from "./host-evidence-grounding.js";
 const MAX_DASHBOARD_BYTES = 256 * 1024;
 const MAX_NAME_LENGTH = 120;
 const MAX_IDEMPOTENCY_KEY_LENGTH = 128;
@@ -14,6 +16,7 @@ const ANSWER_REFERENCE_PATTERN = /^answer-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{
 export const NATIVE_MCP_CREDENTIAL_ENV_VAR = "WARBLE_MCP_CONNECTION_CREDENTIAL";
 export const NATIVE_MCP_TOOL_NAME = "save_dashboard";
 export const NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME = "persist_answer";
+export const NATIVE_MCP_QUERY_TOOL_NAME = "query";
 export const NATIVE_MCP_SERVER_LABEL = "GenBI MCP";
 export const NATIVE_MCP_ARTIFACTS_LABEL = "GenBI Artifacts";
 // Keep this JSON Schema compatible with the ECMA-262 regular-expression
@@ -53,6 +56,8 @@ const POSITIONAL_ROWS_SCHEMA = {
     items: { type: "array", items: SCALAR_SCHEMA },
 };
 /** The exact public MCP shape advertised to native clients and accepted by the host. */
+const VERIFIED_FIELD_SCHEMA = { type: "boolean", description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps." };
+const QUERY_ID_SCHEMA = { ...SAFE_TEXT_SCHEMA, minLength: 1, maxLength: 64, description: "Optional: the query_id the query tool returned for the query this definition describes." };
 export const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA = {
     type: "object",
     additionalProperties: false,
@@ -67,18 +72,18 @@ export const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA = {
         name: { ...SAFE_TEXT_SCHEMA, minLength: 1, maxLength: MAX_NAME_LENGTH, pattern: "\\S" },
         idempotency_key: { ...SAFE_TEXT_SCHEMA, minLength: 8, maxLength: MAX_IDEMPOTENCY_KEY_LENGTH, pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]+$" },
         answer_ref: { ...SAFE_TEXT_SCHEMA, 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}$", description: "Opaque reference returned by persist_answer for this native session." },
-        answer_selection: { const: "latest", description: "Resolve the newest verified answer retained by this native session when its opaque answer_ref is no longer available in the conversation." },
+        answer_selection: { const: "latest", description: "Resolve the newest answer retained by this native session when its opaque answer_ref is no longer available in the conversation." },
         envelope: {
             type: "object", additionalProperties: false, required: ["blocks", "verified"],
             properties: {
-                verified: { const: true }, summary: NULLABLE_SAFE_TEXT_SCHEMA, estimate: { type: ["boolean", "null"] },
+                verified: VERIFIED_FIELD_SCHEMA, summary: NULLABLE_SAFE_TEXT_SCHEMA, estimate: { type: ["boolean", "null"] },
                 blocks: {
                     type: "array", minItems: 1,
                     items: { oneOf: [
                             { type: "object", additionalProperties: false, required: ["type", "label", "value"], properties: { type: { const: "kpi_card" }, label: SAFE_TEXT_SCHEMA, value: SAFE_TEXT_OR_NUMBER_SCHEMA, unit: NULLABLE_SAFE_TEXT_SCHEMA, delta: { type: ["number", "null"] } } },
                             { type: "object", additionalProperties: false, required: ["type", "columns", "rows"], properties: { type: { const: "table" }, columns: { type: "array", minItems: 1, uniqueItems: true, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, rows: { ...POSITIONAL_ROWS_SCHEMA, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.table.positionalRows } } },
                             { type: "object", additionalProperties: false, required: ["type", "chart_type", "x", "series", "rows"], properties: { type: { const: "chart" }, chart_type: { enum: ["bar", "line", "pie", "area", "scatter"] }, x: { ...SAFE_TEXT_SCHEMA, minLength: 1, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.chart.x }, series: { type: "array", minItems: 1, uniqueItems: true, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.chart.series, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, rows: { ...POSITIONAL_ROWS_SCHEMA, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.chart.positionalRows } } },
-                            { type: "object", additionalProperties: false, required: ["type", "sql", "source_tables", "filters"], properties: { type: { const: "definition" }, sql: { ...SAFE_TEXT_SCHEMA, minLength: 1 }, source_tables: { type: "array", minItems: 1, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, filters: { type: "array", items: SAFE_TEXT_SCHEMA } } },
+                            { type: "object", additionalProperties: false, required: ["type", "sql", "source_tables", "filters"], properties: { type: { const: "definition" }, sql: { ...SAFE_TEXT_SCHEMA, minLength: 1 }, source_tables: { type: "array", minItems: 1, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, filters: { type: "array", items: SAFE_TEXT_SCHEMA }, query_id: QUERY_ID_SCHEMA } },
                             { type: "object", additionalProperties: false, required: ["type", "text"], properties: { type: { const: "narrative" }, text: { ...SAFE_TEXT_SCHEMA, minLength: 1 }, title: NULLABLE_SAFE_TEXT_SCHEMA } },
                         ] },
                 },
@@ -97,7 +102,7 @@ const NATIVE_STRUCTURED_ANSWER_ENVELOPE_SCHEMA = {
     additionalProperties: false,
     required: ["blocks", "verified"],
     properties: {
-        verified: { const: true },
+        verified: VERIFIED_FIELD_SCHEMA,
         blocks: {
             type: "array",
             minItems: 1,
@@ -162,6 +167,30 @@ export const NATIVE_PERSIST_ANSWER_CONTRACT = {
     inputSchema: NATIVE_PERSIST_ANSWER_INPUT_SCHEMA,
     semanticConstraint: "The envelope contains exactly one typed table block and at most one typed definition block, with no presentation-only fields.",
 };
+/** The session `query` tool: one read-only SQL query run by the host through governed access. */
+export const NATIVE_QUERY_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["sql"],
+    properties: {
+        sql: { type: "string", minLength: 1, description: "One read-only SELECT over the bound semantic models." },
+        limit: { type: "integer", minimum: 1, description: "Maximum rows to return (default 1000)." },
+    },
+};
+/** The sentence the model sees per host error class; nothing from the governed transport is forwarded. */
+const NATIVE_QUERY_ERROR_TEXT = {
+    invalid_request: "The request did not match the query contract: pass a non-empty sql string and an optional positive integer limit.",
+    model_not_found: "The query references a table that is not a model in the bound semantic context; query only the models it defines.",
+    policy_rejected: "The read-only analytical policy rejected the query: use one SELECT that reads at least one bound model.",
+    invalid_sql: "The SQL could not be parsed or planned against the semantic context.",
+    execution_failed: "The data source rejected the query at execution time, for example an unknown column or a type mismatch.",
+    timeout: "The query exceeded the statement time limit.",
+    datasource_unavailable: "The bound data source could not be reached.",
+    result_too_large: "The result exceeded the governed byte limit; narrow the query.",
+    budget_exhausted: "This session's query budget is exhausted; answer from the results you already have.",
+    internal: "The governed query failed for an unclassified reason.",
+    transport: "The host query service is unavailable.",
+};
 function rejectsExecutableText(value) {
     if (typeof value === "string")
         return /<\s*\/?(?:script|html)\b|javascript\s*:/i.test(value);
@@ -201,7 +230,7 @@ function validBlock(block) {
                 // Existing object rows remain exactly bound to x + series.
                 : isRecord(row) && scalar(row[x]) && series.every((item) => scalar(row[item])) && Object.keys(row).every((key) => key === x || series.includes(key)));
         case "definition":
-            return onlyKeys(block, ["type", "sql", "source_tables", "filters"]) && typeof block.sql === "string" && block.sql.length > 0 && Array.isArray(block.source_tables) && block.source_tables.length > 0 && block.source_tables.every((source) => typeof source === "string" && source.length > 0) && Array.isArray(block.filters) && block.filters.every((filter) => typeof filter === "string");
+            return (onlyKeys(block, ["type", "sql", "source_tables", "filters"]) || (onlyKeys(block, ["type", "sql", "source_tables", "filters", "query_id"]) && typeof block.query_id === "string" && block.query_id.length > 0 && block.query_id.length <= 64)) && typeof block.sql === "string" && block.sql.length > 0 && Array.isArray(block.source_tables) && block.source_tables.length > 0 && block.source_tables.every((source) => typeof source === "string" && source.length > 0) && Array.isArray(block.filters) && block.filters.every((filter) => typeof filter === "string");
         case "narrative":
             return (onlyKeys(block, ["type", "text"]) || onlyKeys(block, ["type", "text", "title"])) && typeof block.text === "string" && block.text.length > 0 && (block.title === undefined || block.title === null || typeof block.title === "string");
         default:
@@ -211,8 +240,8 @@ function validBlock(block) {
 function validateDashboardEnvelope(envelope) {
     if (!isRecord(envelope) || !Object.hasOwn(envelope, "blocks") || !Object.hasOwn(envelope, "verified") || !Object.keys(envelope).every((key) => ["blocks", "summary", "verified", "estimate"].includes(key)))
         throw new NativeArtifactError("invalid dashboard render envelope: expected blocks and verified with optional summary or estimate");
-    if (envelope.verified !== true)
-        throw new NativeArtifactError("invalid dashboard render envelope: verified must be true");
+    if (typeof envelope.verified !== "boolean")
+        throw new NativeArtifactError("invalid dashboard render envelope: verified must be a boolean");
     if (!Array.isArray(envelope.blocks) || envelope.blocks.length === 0)
         throw new NativeArtifactError("invalid dashboard render envelope: blocks must be a non-empty array");
     const invalidBlock = envelope.blocks.findIndex((block) => !validBlock(block));
@@ -258,6 +287,24 @@ function validateInput(value) {
         throw new NativeArtifactError("invalid Save to Artifacts payload: answer_selection must be latest");
     return { version: "1", name: value.name, answer_selection: "latest", idempotency_key: value.idempotency_key };
 }
+function isValidSaveInput(value) {
+    try {
+        validateInput(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidPersistedStructuredAnswer(value) {
+    try {
+        validatePersistedStructuredAnswer(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function validatePersistedStructuredAnswer(value) {
     if (!isRecord(value) || !onlyKeys(value, ["version", "idempotency_key", "envelope"]))
         throw new NativeArtifactError("invalid structured answer payload: expected exactly version, idempotency_key, and envelope");
@@ -275,6 +322,14 @@ function validatePersistedStructuredAnswer(value) {
     }
     return { version: "1", idempotency_key: value.idempotency_key, envelope: value.envelope };
 }
+/**
+ * The stored `verified` flag is host provenance, never the caller's claim: the
+ * persisted envelope carries exactly the flag the host recorded, so its own
+ * badge cannot disagree with the artifact row.
+ */
+function withHostVerified(envelope, verified) {
+    return { ...envelope, verified };
+}
 function structuredAnswerDigest(envelopeJson) {
     return `sha256:${createHash("sha256").update(envelopeJson).digest("hex")}`;
 }
@@ -296,6 +351,9 @@ function validateStoredStructuredAnswer(source, nativeSessionId) {
 export class NativeArtifactService {
     options;
     credentials = new Map();
+    /** One host query recorder per native session: its observations are never shared across sessions. */
+    queryRecorders = new Map();
+    queryClosing = new Set();
     constructor(options) {
         this.options = options;
     }
@@ -327,7 +385,78 @@ export class NativeArtifactService {
     revoke(credential) {
         if (!credential)
             return;
+        const context = this.credentials.get(credential);
         this.credentials.delete(credential);
+        // A session can hold more than one credential (a Codex session's terminal and its component
+        // runtime each get one). Its query recorder lives until the session ends: the last credential
+        // for the session is revoked, which every session end and `dispose()` do.
+        if (context && ![...this.credentials.values()].some((other) => other.session.id === context.session.id))
+            this.closeQueries(context.session.id);
+    }
+    /** Whether native analysis sessions are offered the host `query` tool. */
+    queryAvailable() { return this.options.openQueryAccess !== undefined; }
+    /** Resolves once every session query recorder closed so far has released its governed access. */
+    async queriesClosed() { await Promise.allSettled([...this.queryClosing]); }
+    closeQueries(sessionId) {
+        const recorder = this.queryRecorders.get(sessionId);
+        if (!recorder)
+            return;
+        this.queryRecorders.delete(sessionId);
+        const closing = recorder.close();
+        this.queryClosing.add(closing);
+        void closing.finally(() => this.queryClosing.delete(closing));
+    }
+    /**
+     * The session `query` tool: runs one read-only query through governed access against the
+     * session's bound project, records it as this session's observation and returns its rows with
+     * a session-tagged host `query_id` that a later persist_answer or save_dashboard may cite.
+     */
+    async query(credential, input) {
+        const session = this.authorize(credential);
+        const binding = this.credentials.get(credential)?.binding;
+        const openQueryAccess = this.options.openQueryAccess;
+        if (session.purpose !== "analysis" || !binding || !openQueryAccess)
+            throw new NativeArtifactError("the query tool is unavailable for this native session", 409);
+        const args = isRecord(input) ? input : {};
+        if (!isRecord(input) || !Object.keys(input).every((key) => key === "sql" || key === "limit"))
+            return { isError: true, text: NATIVE_QUERY_ERROR_TEXT.invalid_request };
+        let recorder = this.queryRecorders.get(session.id);
+        if (!recorder) {
+            recorder = createHostQueryRecorder({ openAccess: (signal) => openQueryAccess(binding, signal) });
+            this.queryRecorders.set(session.id, recorder);
+        }
+        const outcome = await recorder.execute(args.sql, args.limit);
+        if ("error" in outcome)
+            return { isError: true, text: `Governed Wren query failed [${outcome.error}]: ${NATIVE_QUERY_ERROR_TEXT[outcome.error] ?? NATIVE_QUERY_ERROR_TEXT.internal}` };
+        return { isError: false, text: JSON.stringify(outcome.result), result: outcome.result };
+    }
+    /**
+     * The host's grounding decision for a model-written envelope: the same envelope rebuilt from
+     * this session's query observations when every query it cites grounds on them (see
+     * `groundOnHostEvidence`), else `undefined`. Only this decision reaches a grounded entry from
+     * the MCP surface.
+     */
+    groundedEnvelope(credential, envelope) {
+        const context = credential === undefined ? undefined : this.credentials.get(credential);
+        const recorder = context ? this.queryRecorders.get(context.session.id) : undefined;
+        if (!recorder || !isRecord(envelope))
+            return undefined;
+        // The host rebuilds only table and definition blocks. Any other block (narrative, chart, KPI)
+        // or an `estimate` flag would be dropped by the rebuild, so such an envelope is never grounded:
+        // it is kept intact and stored unverified rather than losing content silently.
+        if (envelope.estimate !== undefined && envelope.estimate !== null)
+            return undefined;
+        if (!Array.isArray(envelope.blocks) || envelope.blocks.some((block) => !isRecord(block) || (block.type !== "table" && block.type !== "definition")))
+            return undefined;
+        const grounded = groundOnHostEvidence(envelope, envelope, recorder.observations());
+        if (grounded.verified !== true)
+            return undefined;
+        // The rebuild emits one table and one definition per cited query. If it has fewer of either
+        // than the envelope did (an extra uncited table, say), content would be lost: keep it intact.
+        const count = (value, type) => Array.isArray(value.blocks) ? value.blocks.filter((block) => isRecord(block) && block.type === type).length : 0;
+        if (count(grounded, "table") !== count(envelope, "table") || count(grounded, "definition") !== count(envelope, "definition"))
+            return undefined;
+        return grounded;
     }
     /** Releases opaque credentials when the owning BFF service shuts down. */
     dispose() { for (const credential of [...this.credentials.keys()])
@@ -377,11 +506,35 @@ export class NativeArtifactService {
      * a later follow-up can only reference this stored result, never recompute.
      */
     persistAnswer(credential, input) {
+        // Authorize before validating, as `persistStructured` does: a bad credential is a 401 and a
+        // non-analysis session a 409 whatever the payload.
         const session = this.authorize(credential);
         if (session.purpose !== "analysis")
             throw new NativeArtifactError("structured answer persistence is unavailable for this native session", 409);
         const payload = validatePersistedStructuredAnswer(input);
-        const envelopeJson = JSON.stringify(payload.envelope);
+        const grounded = this.groundedEnvelope(credential, payload.envelope);
+        if (grounded) {
+            const candidate = { ...payload, envelope: grounded };
+            // A rebuilt envelope the persist contract cannot hold (a truncation note needs a summary,
+            // which this contract has no field for) is persisted unverified, as written.
+            if (isValidPersistedStructuredAnswer(candidate))
+                return this.persistStructured(credential, candidate, true);
+        }
+        return this.persistStructured(credential, input, false);
+    }
+    /**
+     * Host-only entry for a grounded component root (never exposed over MCP).
+     * The caller must already have checked the component's verified provenance.
+     */
+    persistGroundedAnswer(credential, input) {
+        return this.persistStructured(credential, input, true);
+    }
+    persistStructured(credential, input, grounded) {
+        const session = this.authorize(credential);
+        if (session.purpose !== "analysis")
+            throw new NativeArtifactError("structured answer persistence is unavailable for this native session", 409);
+        const payload = validatePersistedStructuredAnswer(input);
+        const envelopeJson = JSON.stringify(withHostVerified(payload.envelope, grounded));
         const digest = structuredAnswerDigest(envelopeJson);
         const existing = this.options.store.getNativeStructuredAnswerByIdempotency(session.id, payload.idempotency_key);
         if (existing) {
@@ -392,7 +545,7 @@ export class NativeArtifactService {
         }
         try {
             const persisted = (this.options.persistStructuredAnswer ?? ((params) => this.options.store.createNativeStructuredAnswer(params)))({
-                id: newId("answer"), nativeSessionId: session.id, idempotencyKey: payload.idempotency_key, envelopeJson, digest,
+                id: newId("answer"), nativeSessionId: session.id, idempotencyKey: payload.idempotency_key, envelopeJson, digest, grounded,
             });
             if (persisted.row.digest !== digest || persisted.row.envelopeJson !== envelopeJson) {
                 throw new NativeArtifactError("structured answer idempotency key is already bound to a different answer", 409);
@@ -409,6 +562,27 @@ export class NativeArtifactService {
         }
     }
     save(credential, input) {
+        // Authorize before validating, as `saveArtifact` does.
+        this.authorizeSave(credential);
+        const payload = validateInput(input);
+        // Only an envelope save is grounded here; a save by reference inherits the retained answer's provenance.
+        const grounded = "envelope" in payload ? this.groundedEnvelope(credential, payload.envelope) : undefined;
+        if (grounded) {
+            const candidate = { ...payload, envelope: grounded };
+            if (isValidSaveInput(candidate))
+                return this.saveArtifact(credential, candidate, true);
+        }
+        return this.saveArtifact(credential, input, false);
+    }
+    /**
+     * Host-only entry for a grounded component render root (never exposed over
+     * MCP). The caller must already have checked verified provenance.
+     */
+    saveGrounded(credential, input) {
+        return this.saveArtifact(credential, input, true);
+    }
+    /** The credential, session and binding checks every save runs before it reads its payload. */
+    authorizeSave(credential) {
         const context = credential === undefined ? undefined : this.credentials.get(credential);
         if (!context)
             throw new NativeArtifactError("GenBI MCP bearer credential is invalid. Restart this native session to refresh its GenBI MCP connection.", 401);
@@ -418,8 +592,11 @@ export class NativeArtifactService {
             this.revoke(credential);
             throw new NativeArtifactError("GenBI MCP session binding is stale. Start a new native session.", 409);
         }
+        return { session, binding };
+    }
+    saveArtifact(credential, input, grounded) {
+        const { session, binding } = this.authorizeSave(credential);
         const payload = validateInput(input);
-        const referenceSave = "answer_ref" in payload || "answer_selection" in payload;
         const source = "answer_ref" in payload
             ? this.options.store.getNativeStructuredAnswer(payload.answer_ref)
             : "answer_selection" in payload
@@ -431,13 +608,16 @@ export class NativeArtifactService {
             throw new NativeArtifactError("no persisted answer is available for this native session", 404);
         if (source)
             validateStoredStructuredAnswer(source, session.id);
-        const contents = referenceSave ? source.envelopeJson : JSON.stringify(payload.envelope);
-        const digest = referenceSave ? source.digest : structuredAnswerDigest(contents);
+        // A reference save inherits the retained answer's provenance; an envelope
+        // save is verified only through the host-only grounded entry.
+        const verified = source ? source.grounded : grounded;
+        const contents = JSON.stringify(withHostVerified(source ? JSON.parse(source.envelopeJson) : "envelope" in payload ? payload.envelope : undefined, verified));
+        const digest = structuredAnswerDigest(contents);
         const sameSaveRequest = (artifact) => artifact !== undefined &&
             artifact.name === payload.name.trim() &&
             artifact.projectIdentity === binding.identity && artifact.bindingGeneration === binding.generation && artifact.projectRevision === binding.revision &&
             artifact.nativeVendor === session.vendor && artifact.nativeAgent === session.agent &&
-            artifact.contentDigest === digest && artifact.sourceAnswerId === (source?.id ?? null);
+            artifact.contentDigest === digest && artifact.sourceAnswerId === (source?.id ?? null) && artifact.verified === verified;
         const existing = this.options.store.getNativeArtifactByIdempotency(session.id, payload.idempotency_key);
         if (existing) {
             if (!sameSaveRequest(existing))
@@ -450,7 +630,7 @@ export class NativeArtifactService {
         try {
             const safeTarget = assertSafeContainedTarget(this.options.artifactsRoot, target);
             (this.options.writeAtomic ?? writeContainedAtomically)(safeTarget, contents);
-            const inserted = this.options.store.createNativeArtifact({ id, sessionId: session.id, nativeSessionId: session.id, name: payload.name.trim(), location, projectIdentity: binding.identity, bindingGeneration: binding.generation, projectRevision: binding.revision, vendor: session.vendor, agent: session.agent, digest, idempotencyKey: payload.idempotency_key, ...(source ? { sourceAnswerId: source.id } : {}) });
+            const inserted = this.options.store.createNativeArtifact({ id, sessionId: session.id, nativeSessionId: session.id, name: payload.name.trim(), location, projectIdentity: binding.identity, bindingGeneration: binding.generation, projectRevision: binding.revision, vendor: session.vendor, agent: session.agent, digest, idempotencyKey: payload.idempotency_key, verified, ...(source ? { sourceAnswerId: source.id } : {}) });
             if (!inserted.created && !sameSaveRequest(inserted.row)) {
                 rmSync(target, { force: true });
                 throw new NativeArtifactError("artifact idempotency key is already bound to a different save request", 409);

package/dist-server/server/native-component-context.d.ts

@@ -0,0 +1,19 @@
+import { type CodexSessionTools } from "./runtime-host/codex-direct-tools.js";
+import { type NativeComponentRuntimeOptions } from "./native-component-runtime.js";
+import type { NativeComponentPreparation } from "./native-components.js";
+export interface NativeComponentContextOptions extends Omit<NativeComponentRuntimeOptions, "contexts" | "wren"> {
+    /** All executables and the provider are resolved by the certified server provisioner. */
+    readonly contextLoaderBinary: string;
+    /** Explicit host-only credential environment supplied by the provisioner. */
+    readonly wrenEnvironment?: Readonly<NodeJS.ProcessEnv>;
+    readonly wrenBinary: string;
+    readonly project: string;
+    readonly signal: AbortSignal;
+}
+/** Capture file-only context before host admission; never opens a vendor or Wren process. */
+export declare function prepareCapturedNativeComponentHost(irDocument: string, scope: Readonly<Record<string, unknown>>, options: NativeComponentContextOptions): Promise<NativeComponentPreparation | undefined>;
+/** Direct-session variant shares the same captured project/credential provenance. */
+export declare function prepareCapturedCodexDirectTools(irDocument: string, scope: Readonly<Record<string, unknown>>, options: NativeComponentContextOptions & {
+    readonly producerBinary: string;
+    readonly expiresAt: number;
+}): Promise<CodexSessionTools>;