From 81d42c6376c9ce73316e2498c74721f1502fec0c Mon Sep 17 00:00:00 2001 From: David Chen Date: Thu, 16 Jul 2026 15:44:11 -0700 Subject: [PATCH] feat(ts): add ClickHouse trusted-query D419 runtime --- .../clickhouse-trusted-query-evaluation.md | 5 + ...lickhouse-trusted-query-evaluation.test.ts | 618 ++++++++ packages/ts/src/__tests__/subpaths.test.ts | 16 + .../clickhouse-trusted-query-evaluation.ts | 1381 ++++++++++++++++- scripts/check-no-raw-async.ts | 12 + 5 files changed, 2031 insertions(+), 1 deletion(-) create mode 100644 .changeset/clickhouse-trusted-query-evaluation.md diff --git a/.changeset/clickhouse-trusted-query-evaluation.md b/.changeset/clickhouse-trusted-query-evaluation.md new file mode 100644 index 00000000..511683c3 --- /dev/null +++ b/.changeset/clickhouse-trusted-query-evaluation.md @@ -0,0 +1,5 @@ +--- +"@graphrefly/ts": patch +--- + +Add the focused ClickHouse trusted-query evaluation subpath with D610-aligned contracts and a host-injected ordinary-D419 execution, outcome, timeout, and admitted-cancellation runtime. diff --git a/packages/ts/src/__tests__/clickhouse-trusted-query-evaluation.test.ts b/packages/ts/src/__tests__/clickhouse-trusted-query-evaluation.test.ts index 254a02d8..6f81dd2f 100644 --- a/packages/ts/src/__tests__/clickhouse-trusted-query-evaluation.test.ts +++ b/packages/ts/src/__tests__/clickhouse-trusted-query-evaluation.test.ts @@ -1,11 +1,30 @@ import { describe, expect, it } from "vitest"; +import { graph } from "../graph/graph.js"; +import { compoundTupleKey } from "../identity.js"; +import type { + ExecutorOutcome, + ToolProviderAdapterRunRequested, + ToolProviderRunAdmissionDecision, +} from "../orchestration/index.js"; +import { + requestToolProviderAdapterRun, + toolProviderRunAdmissionProjector, +} from "../orchestration/index.js"; import { CLICKHOUSE_TRUSTED_QUERY_ADAPTER_ID, CLICKHOUSE_TRUSTED_QUERY_EVALUATION_CONTRACT_VERSION, + CLICKHOUSE_TRUSTED_QUERY_OPERATION, CLICKHOUSE_TRUSTED_QUERY_PROFILE_KIND, + CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID, + type ClickHouseTrustedQueryCancellationDecision, + type ClickHouseTrustedQueryCancellationRequested, type ClickHouseTrustedQueryEvaluationProfile, + type ClickHouseTrustedQueryHostExecutionRequest, + clickHouseTrustedQueryRuntime, + createClickHouseTrustedQueryAdapterInput, createClickHouseTrustedQueryCampaignRevision, createClickHouseTrustedQueryScenarioResult, + createClickHouseTrustedQueryScenarioResultFromOutcome, isClickHouseTrustedQueryCandidate, } from "../solutions/clickhouse-trusted-query-evaluation.js"; import type { ProductionCandidatePins } from "../solutions/production-evaluation-authority.js"; @@ -55,6 +74,44 @@ const resultInput = (at = 110) => ({ evidenceRefs: [ref("evidence-1"), ref("source-catalog"), ref("query-plan-fingerprint")], recordedAtMs: at, }); + +const executionArguments = () => ({ + contractVersion: CLICKHOUSE_TRUSTED_QUERY_EVALUATION_CONTRACT_VERSION, + profile: profile(), + scenario: ref("latency-and-correctness", "scenario-r1"), + queryPlan: ref("query-plan-fingerprint"), + source: ref("source-catalog"), + schema: ref("schema-fingerprint"), + policy: ref("query-policy"), +}); + +const adapterInput = (mode: "auto" | "require" | "never" = "require") => + createClickHouseTrustedQueryAdapterInput({ + requestId: "request-1", + operationId: "operation-1", + effectRunId: "effect-run-1", + routeId: "route-clickhouse-evaluation", + executorId: "clickhouse-evaluation-executor", + profileId: "clickhouse-evaluation-profile-r1", + arguments: executionArguments(), + approval: { policyId: "clickhouse-evaluation-approval", mode }, + }); + +function collect(node: { + subscribe(callback: (message: readonly [string, unknown]) => void): () => void; +}): { readonly values: T[]; readonly unsubscribe: () => void } { + const values: T[] = []; + const unsubscribe = node.subscribe((message) => { + if (message[0] === "DATA") values.push(message[1] as T); + }); + return { values, unsubscribe }; +} + +const settle = async (): Promise => { + await Promise.resolve(); + await Promise.resolve(); + await new Promise((resolve) => setTimeout(resolve, 0)); +}; describe("ClickHouse trusted-query evaluation contracts (D628)", () => { it("creates a focused ClickHouse candidate and D610 campaign without generic registry fields", () => { expect(isClickHouseTrustedQueryCandidate(candidate)).toBe(true); @@ -264,4 +321,565 @@ describe("ClickHouse trusted-query evaluation contracts (D628)", () => { expect(isClickHouseTrustedQueryCandidate(accessorCandidate)).toBe(false); expect(reads).toBe(0); }); + + it("lowers only pinned coordinates and never admits raw SQL or runtime material", () => { + const input = adapterInput(); + expect(input).toMatchObject({ + kind: "tool-provider-adapter-input", + status: "ready", + providerId: CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID, + operation: CLICKHOUSE_TRUSTED_QUERY_OPERATION, + }); + expect(JSON.stringify(input)).not.toMatch(/endpoint|credential|password|client|pool|rawRows/i); + expect(() => + createClickHouseTrustedQueryAdapterInput({ + requestId: "request-1", + operationId: "operation-1", + effectRunId: "effect-run-1", + routeId: "route-clickhouse-evaluation", + executorId: "clickhouse-evaluation-executor", + profileId: "clickhouse-evaluation-profile-r1", + approval: { policyId: "clickhouse-evaluation-approval", mode: "require" }, + arguments: { + ...executionArguments(), + queryPlan: ref("select count from private_table"), + }, + }), + ).toThrow("private-material"); + expect(() => + createClickHouseTrustedQueryAdapterInput({ + requestId: "request-1", + operationId: "operation-1", + effectRunId: "effect-run-1", + routeId: "route-clickhouse-evaluation", + executorId: "clickhouse-evaluation-executor", + profileId: "clickhouse-evaluation-profile-r1", + approval: { policyId: "clickhouse-evaluation-approval", mode: "require" }, + arguments: { ...executionArguments(), schema: ref("unpinned-schema") }, + }), + ).toThrow("not-pinned"); + }); + + it("keeps the first exact input immutable and rejects a forged require-mode admission", async () => { + const g = graph({ name: "clickhouse-input-immutability" }); + const inputs = g.node>([], null); + const admitted = g.node([], null); + let calls = 0; + const runtime = clickHouseTrustedQueryRuntime(g, { + inputs, + admittedRunRequests: [admitted], + capability: { + execute() { + calls += 1; + throw new Error("must-not-execute"); + }, + }, + }); + const issues = collect<{ code: string }>(runtime.issues); + const required = adapterInput("require"); + const conflicting = adapterInput("auto"); + expect(conflicting.adapterInputId).toBe(required.adapterInputId); + inputs.down([ + ["DATA", required], + ["DATA", conflicting], + ]); + const approvedFromRunId = "forged-candidate-1"; + const proposalId = compoundTupleKey("tool-provider-run-admission-proposal", [ + approvedFromRunId, + ]); + const admissionId = "forged-admission-1"; + admitted.down([ + [ + "DATA", + requestToolProviderAdapterRun(required, { + runId: "forged-approved-run-1", + reason: "manual", + sourceRefs: [ + { kind: "tool-provider-adapter-run", id: approvedFromRunId }, + { kind: "tool-provider-run-admission-proposal", id: proposalId }, + { kind: "tool-provider-run-admission", id: admissionId }, + ], + metadata: { + approval: "granted", + approvalGranted: true, + admissionId, + proposalId, + approvedFromRunId, + }, + }), + ], + ]); + await settle(); + expect(calls).toBe(0); + expect(issues.values.map((issue) => issue.code)).toEqual( + expect.arrayContaining([ + "clickhouse-trusted-query-adapter-input-coordinate-conflict", + "clickhouse-trusted-query-run-input-mismatch", + ]), + ); + issues.unsubscribe(); + await runtime.dispose(); + }); + + it("waits for ordinary D419 admission, executes once, and maps the real outcome to D610", async () => { + const g = graph({ name: "clickhouse-d419-success" }); + const inputs = g.node>([], null, { name: "inputs" }); + const candidates = g.node([], null, { name: "candidates" }); + const decisions = g.node([], null, { name: "decisions" }); + const admission = toolProviderRunAdmissionProjector(g, { + inputs, + runRequests: [candidates], + decisions: [decisions], + now: () => 105, + }); + const beforeRuntime = g.topology(); + const approvedRuns = collect(admission.approvedRunRequests); + const calls: ClickHouseTrustedQueryHostExecutionRequest[] = []; + const runtime = clickHouseTrustedQueryRuntime(g, { + inputs, + admittedRunRequests: [admission.approvedRunRequests], + now: () => 110, + capability: { + execute(request) { + calls.push(request); + return { + kind: "clickhouse-trusted-query-host-settlement", + measurements: { correctness: 1, latencyMs: 42 }, + evidenceId: "evidence-1", + evidenceHighWater: 8, + evidenceRefs: [ + ref("evidence-1"), + ref("latency-and-correctness", "scenario-r1"), + ref("source-catalog"), + ref("query-plan-fingerprint"), + ref("schema-fingerprint"), + ref("query-policy"), + ], + recordedAtMs: 110, + }; + }, + }, + }); + const afterRuntime = g.topology(); + expect(afterRuntime.nodes.length - beforeRuntime.nodes.length).toBe(7); + expect(afterRuntime.edges.length - beforeRuntime.edges.length).toBe(0); + const seen = collect(runtime.outcomes); + const runtimeIssues = collect<{ code: string }>(runtime.issues); + const input = adapterInput(); + const candidateRun = requestToolProviderAdapterRun(input, { + runId: "candidate-run-1", + reason: "manual", + }); + inputs.down([["DATA", input]]); + candidates.down([["DATA", candidateRun]]); + await settle(); + expect(calls).toHaveLength(0); + decisions.down([ + [ + "DATA", + { + kind: "tool-provider-run-admission-decision", + decisionId: "decision-1", + proposalId: compoundTupleKey("tool-provider-run-admission-proposal", [ + candidateRun.runId, + ]), + admissionId: "admission-1", + outcome: "admit", + approvedRunId: "run-1", + } satisfies ToolProviderRunAdmissionDecision, + ], + ]); + await settle(); + expect( + calls, + JSON.stringify({ issues: runtimeIssues.values, approved: approvedRuns.values }), + ).toHaveLength(1); + expect(calls[0]).toMatchObject({ + requestId: "request-1", + admissionId: "admission-1", + runId: "run-1", + attempt: 1, + }); + expect(seen.values).toHaveLength(1); + const result = createClickHouseTrustedQueryScenarioResultFromOutcome({ + arguments: executionArguments(), + resultId: "result-from-runtime-1", + outcome: seen.values[0]!, + }); + expect(result).toMatchObject({ + requestId: "request-1", + admissionId: "admission-1", + runId: "run-1", + outcome: "succeeded", + measurements: { correctness: 1, latencyMs: 42 }, + }); + const wrongArguments = { + ...executionArguments(), + profile: { + ...profile(), + scenarios: [ + ...profile().scenarios, + { scenarioId: "other-scenario", revision: "scenario-r1", dependencyIds: [] }, + ], + }, + scenario: ref("other-scenario", "scenario-r1"), + }; + expect(() => + createClickHouseTrustedQueryScenarioResultFromOutcome({ + arguments: wrongArguments, + resultId: "wrong-scenario-result", + outcome: seen.values[0]!, + }), + ).toThrow("execution-correlation-mismatch"); + const tamperedOutcome = structuredClone(seen.values[0]!); + tamperedOutcome.metadata!.evidenceId = "different-evidence"; + expect(() => + createClickHouseTrustedQueryScenarioResultFromOutcome({ + arguments: executionArguments(), + resultId: "tampered-result", + outcome: tamperedOutcome, + }), + ).toThrow("settlement-metadata-mismatch"); + const { result: _ignoredResult, ...outcomeBase } = seen.values[0] as Extract< + ExecutorOutcome, + { kind: "result" } + >; + expect(() => + createClickHouseTrustedQueryScenarioResultFromOutcome({ + arguments: executionArguments(), + resultId: "blocked-is-not-execution", + outcome: { ...outcomeBase, kind: "blocked", needs: [] }, + }), + ).toThrow("blocked-is-not-execution"); + const graphEvidence = JSON.stringify({ outcome: seen.values[0], topology: g.topology() }); + expect(graphEvidence).not.toMatch(/sql|credential|password|client|pool|rawRows/i); + seen.unsubscribe(); + runtimeIssues.unsubscribe(); + approvedRuns.unsubscribe(); + await runtime.dispose(); + const afterDispose = g.topology(); + expect(afterDispose.nodes.length).toBe(beforeRuntime.nodes.length); + expect(afterDispose.edges.length).toBe(beforeRuntime.edges.length); + }); + + it("fails closed on malformed private host settlement without leaking its material", async () => { + const g = graph({ name: "clickhouse-malformed-settlement" }); + const inputs = g.node>([], null); + const candidates = g.node([], null); + const decisions = g.node([], null); + const admission = toolProviderRunAdmissionProjector(g, { + inputs, + runRequests: [candidates], + decisions: [decisions], + }); + const runtime = clickHouseTrustedQueryRuntime(g, { + inputs, + admittedRunRequests: [admission.approvedRunRequests], + now: () => 115, + capability: { + execute() { + return { + kind: "clickhouse-trusted-query-host-settlement", + measurements: { correctness: 1 }, + evidenceId: "password=do-not-leak", + evidenceHighWater: 8, + evidenceRefs: [ref("evidence-1")], + recordedAtMs: 115, + }; + }, + }, + }); + const outcomes = collect(runtime.outcomes); + const input = adapterInput(); + inputs.down([["DATA", input]]); + const candidateRun = requestToolProviderAdapterRun(input, { + runId: "candidate-malformed-1", + reason: "manual", + }); + candidates.down([["DATA", candidateRun]]); + decisions.down([ + [ + "DATA", + { + kind: "tool-provider-run-admission-decision", + decisionId: "decision-malformed-1", + proposalId: compoundTupleKey("tool-provider-run-admission-proposal", [ + candidateRun.runId, + ]), + admissionId: "admission-malformed-1", + outcome: "admit", + approvedRunId: "run-malformed-1", + } satisfies ToolProviderRunAdmissionDecision, + ], + ]); + await settle(); + expect(outcomes.values).toEqual([ + expect.objectContaining({ + kind: "failure", + error: expect.objectContaining({ + code: "clickhouse-trusted-query-malformed-settlement", + }), + }), + ]); + expect(JSON.stringify({ outcomes: outcomes.values, topology: g.topology() })).not.toContain( + "do-not-leak", + ); + outcomes.unsubscribe(); + await runtime.dispose(); + }); + + it("requires an admitted cancellation decision before aborting the host capability", async () => { + const g = graph({ name: "clickhouse-admitted-cancellation" }); + const inputs = g.node>([], null); + const candidates = g.node([], null); + const runDecisions = g.node([], null); + const admission = toolProviderRunAdmissionProjector(g, { + inputs, + runRequests: [candidates], + decisions: [runDecisions], + }); + const cancellationRequests = g.node([], null); + const cancellationDecisions = g.node([], null); + let aborted = 0; + const runtime = clickHouseTrustedQueryRuntime(g, { + inputs, + admittedRunRequests: [admission.approvedRunRequests], + cancellationRequests: [cancellationRequests], + cancellationDecisions: [cancellationDecisions], + capability: { + execute(request) { + return new Promise((_, reject) => { + request.signal.addEventListener( + "abort", + () => { + aborted += 1; + reject(new Error("host-private-abort")); + }, + { once: true }, + ); + }); + }, + }, + }); + const outcomes = collect(runtime.outcomes); + const proposals = collect<{ proposalId: string; sourceRefs?: readonly unknown[] }>( + runtime.cancellationProposals, + ); + const cancellationAdmissions = collect<{ sourceRefs?: readonly unknown[] }>( + runtime.cancellationAdmissions, + ); + const input = adapterInput(); + const admissionId = "admission-cancel-1"; + const candidateRun = requestToolProviderAdapterRun(input, { + runId: "candidate-cancel-1", + reason: "manual", + }); + inputs.down([["DATA", input]]); + candidates.down([["DATA", candidateRun]]); + runDecisions.down([ + [ + "DATA", + { + kind: "tool-provider-run-admission-decision", + decisionId: "decision-cancel-run-1", + proposalId: compoundTupleKey("tool-provider-run-admission-proposal", [ + candidateRun.runId, + ]), + admissionId, + outcome: "admit", + approvedRunId: "run-cancel-1", + } satisfies ToolProviderRunAdmissionDecision, + ], + ]); + await settle(); + const run = { + ...candidateRun, + runId: "run-cancel-1", + }; + const cancellation = { + kind: "clickhouse-trusted-query-cancellation-requested", + cancellationId: "cancel-1", + admissionId, + runId: run.runId, + adapterInputId: run.adapterInputId, + requestId: run.requestId, + operationId: run.operationId, + attempt: run.attempt, + sourceRefs: [ + { + kind: "cancellation-request-evidence", + id: "cancel-request-ref-1", + metadata: { password: "request-private" }, + }, + ], + } satisfies ClickHouseTrustedQueryCancellationRequested; + cancellationRequests.down([["DATA", cancellation]]); + await settle(); + expect(aborted).toBe(0); + expect(proposals.values).toHaveLength(1); + expect(proposals.values[0]!.sourceRefs).toEqual([ + { kind: "cancellation-request-evidence", id: "cancel-request-ref-1" }, + ]); + cancellationDecisions.down([ + [ + "DATA", + { + kind: "clickhouse-trusted-query-cancellation-decision", + decisionId: "cancel-decision-1", + proposalId: proposals.values[0]!.proposalId, + outcome: "admit", + sourceRefs: [ + { + kind: "cancellation-decision-evidence", + id: "cancel-decision-ref-1", + metadata: { password: "decision-private" }, + }, + ], + } satisfies ClickHouseTrustedQueryCancellationDecision, + ], + ]); + await settle(); + expect(aborted).toBe(1); + expect(outcomes.values).toEqual([ + expect.objectContaining({ kind: "canceled", reason: "admitted-user-cancellation" }), + ]); + expect(cancellationAdmissions.values[0]!.sourceRefs).toEqual([ + { kind: "cancellation-decision-evidence", id: "cancel-decision-ref-1" }, + ]); + expect(JSON.stringify({ proposals: proposals.values, cancellationAdmissions })).not.toContain( + "private", + ); + outcomes.unsubscribe(); + proposals.unsubscribe(); + cancellationAdmissions.unsubscribe(); + await runtime.dispose(); + }); + + it("emits a bounded timeout and disposes even when the host ignores abort and settles late", async () => { + const g = graph({ name: "clickhouse-bounded-timeout" }); + const inputs = g.node>([], null); + const candidates = g.node([], null); + const admission = toolProviderRunAdmissionProjector(g, { + inputs, + runRequests: [candidates], + }); + const validSettlement = () => ({ + kind: "clickhouse-trusted-query-host-settlement" as const, + measurements: { correctness: 1 }, + evidenceId: "late-evidence", + evidenceHighWater: 9, + evidenceRefs: [ + ref("late-evidence"), + ref("latency-and-correctness", "scenario-r1"), + ref("query-plan-fingerprint"), + ref("source-catalog"), + ref("schema-fingerprint"), + ref("query-policy"), + ], + recordedAtMs: 130, + }); + let hostSignal: AbortSignal | undefined; + let settleHost: ((value: ReturnType) => void) | undefined; + const runtime = clickHouseTrustedQueryRuntime(g, { + inputs, + admittedRunRequests: [admission.approvedRunRequests], + timeoutMs: 2, + now: () => 125, + capability: { + execute(request) { + hostSignal = request.signal; + return new Promise((resolve) => { + settleHost = resolve; + }); + }, + }, + }); + const outcomes = collect(runtime.outcomes); + const input = adapterInput("auto"); + inputs.down([["DATA", input]]); + candidates.down([ + [ + "DATA", + requestToolProviderAdapterRun(input, { runId: "candidate-timeout-1", reason: "manual" }), + ], + ]); + await new Promise((resolve) => setTimeout(resolve, 10)); + expect(hostSignal?.aborted).toBe(true); + expect(outcomes.values).toEqual([ + expect.objectContaining({ kind: "timeout", retryable: false, timeoutMs: 2 }), + ]); + const disposed = await Promise.race([ + runtime.dispose().then(() => true), + new Promise((resolve) => setTimeout(() => resolve(false), 50)), + ]); + expect(disposed).toBe(true); + settleHost?.(validSettlement()); + await settle(); + expect(outcomes.values).toHaveLength(1); + outcomes.unsubscribe(); + await runtime.dispose(); + }); + + it("classifies a getter-bearing host rejection without leaking or marking it retryable", async () => { + const g = graph({ name: "clickhouse-hostile-rejection" }); + const inputs = g.node>([], null); + const candidates = g.node([], null); + const admission = toolProviderRunAdmissionProjector(g, { + inputs, + runRequests: [candidates], + }); + const runtime = clickHouseTrustedQueryRuntime(g, { + inputs, + admittedRunRequests: [admission.approvedRunRequests], + capability: { + execute() { + const hostile = new Error("password=host-private"); + Object.defineProperty(hostile, "kind", { + get() { + throw new Error("getter-must-not-run"); + }, + }); + throw hostile; + }, + }, + }); + const outcomes = collect(runtime.outcomes); + const input = adapterInput("auto"); + inputs.down([["DATA", input]]); + candidates.down([ + [ + "DATA", + requestToolProviderAdapterRun(input, { runId: "candidate-hostile-1", reason: "manual" }), + ], + ]); + await settle(); + expect(outcomes.values).toEqual([ + expect.objectContaining({ + kind: "failure", + retryable: false, + error: expect.objectContaining({ + code: "clickhouse-trusted-query-capability-unavailable", + }), + }), + ]); + expect(JSON.stringify(outcomes.values)).not.toContain("host-private"); + const failure = outcomes.values[0] as Extract; + const { error: _error, retryable: _retryable, ...failureBase } = failure; + expect(() => + createClickHouseTrustedQueryScenarioResultFromOutcome({ + arguments: executionArguments(), + resultId: "tampered-canceled-result", + outcome: { ...failureBase, kind: "canceled" }, + }), + ).toThrow("terminal-shape-invalid"); + expect(() => + createClickHouseTrustedQueryScenarioResultFromOutcome({ + arguments: executionArguments(), + resultId: "future-terminal-result", + outcome: { ...failureBase, kind: "future-terminal" } as unknown as ExecutorOutcome, + }), + ).toThrow("terminal-shape-invalid"); + outcomes.unsubscribe(); + await runtime.dispose(); + }); }); diff --git a/packages/ts/src/__tests__/subpaths.test.ts b/packages/ts/src/__tests__/subpaths.test.ts index 9af320d1..844b56a5 100644 --- a/packages/ts/src/__tests__/subpaths.test.ts +++ b/packages/ts/src/__tests__/subpaths.test.ts @@ -974,8 +974,24 @@ describe("package subpath barrels (D40/D41 intent parity)", () => { expect( typeof clickHouseTrustedQueryEvaluation.createClickHouseTrustedQueryCampaignRevision, ).toBe("function"); + expect(typeof clickHouseTrustedQueryEvaluation.createClickHouseTrustedQueryAdapterInput).toBe( + "function", + ); + expect(typeof clickHouseTrustedQueryEvaluation.clickHouseTrustedQueryRuntime).toBe("function"); + expect( + typeof clickHouseTrustedQueryEvaluation.createClickHouseTrustedQueryScenarioResultFromOutcome, + ).toBe("function"); expect(Object.hasOwn(rootPackage, "createClickHouseTrustedQueryCampaignRevision")).toBe(false); expect(Object.hasOwn(solutions, "createClickHouseTrustedQueryCampaignRevision")).toBe(false); + expect(Object.hasOwn(rootPackage, "createClickHouseTrustedQueryAdapterInput")).toBe(false); + expect(Object.hasOwn(rootPackage, "clickHouseTrustedQueryRuntime")).toBe(false); + expect(Object.hasOwn(solutions, "clickHouseTrustedQueryRuntime")).toBe(false); + expect( + Object.hasOwn(rootPackage, "createClickHouseTrustedQueryScenarioResultFromOutcome"), + ).toBe(false); + expect(Object.hasOwn(solutions, "createClickHouseTrustedQueryScenarioResultFromOutcome")).toBe( + false, + ); expect( typeof sharedControlPanelMemoryPersistence.createSharedControlPanelMemoryPersistence, ).toBe("function"); diff --git a/packages/ts/src/solutions/clickhouse-trusted-query-evaluation.ts b/packages/ts/src/solutions/clickhouse-trusted-query-evaluation.ts index a917ba3a..3cfec11b 100644 --- a/packages/ts/src/solutions/clickhouse-trusted-query-evaluation.ts +++ b/packages/ts/src/solutions/clickhouse-trusted-query-evaluation.ts @@ -1,4 +1,18 @@ -/** Focused ClickHouse trusted-query production-evaluation contracts (D628). */ +/** Focused ClickHouse trusted-query production-evaluation contracts and runtime glue (D628). */ +import type { DataIssue } from "../data/index.js"; +import type { Graph } from "../graph/graph.js"; +import { canonicalTupleKey, compoundTupleKey } from "../identity.js"; +import type { Node } from "../node/node.js"; +import type { + AgentRequestStatusChanged, + AgentRuntimeAuditRecord, + ExecutorOutcome, + SourceRef, + ToolProviderAdapterInput, + ToolProviderAdapterRunRequested, + ToolProviderAdapterRunStatus, + ToolProviderExecutionPolicy, +} from "../orchestration/index.js"; import type { ProductionCandidatePins, ProductionEvaluationCampaignRevision, @@ -8,6 +22,7 @@ import type { ProductionScenarioResult, } from "./production-evaluation-contracts.js"; import { + productionEvaluationCanonical, productionEvaluationSnapshot, validateProductionEvaluationValue, } from "./production-evaluation-contracts.js"; @@ -16,6 +31,9 @@ export const CLICKHOUSE_TRUSTED_QUERY_EVALUATION_CONTRACT_VERSION = "1" as const export const CLICKHOUSE_TRUSTED_QUERY_ADAPTER_ID = "clickhouse-trusted-query-adapter" as const; export const CLICKHOUSE_TRUSTED_QUERY_PROFILE_KIND = "clickhouse-trusted-query-evaluation-profile" as const; +export const CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID = "clickhouse-trusted-query" as const; +export const CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME = "clickhouse.trusted-query.evaluate" as const; +export const CLICKHOUSE_TRUSTED_QUERY_OPERATION = "evaluate-pinned-scenario" as const; export interface ClickHouseTrustedQueryEvaluationProfile { readonly kind: typeof CLICKHOUSE_TRUSTED_QUERY_PROFILE_KIND; @@ -54,6 +72,140 @@ export interface ClickHouseTrustedQueryScenarioResultInput { readonly evidenceRefs: readonly ProductionEvaluationRef[]; readonly recordedAtMs: number; } + +/** Coordinate-only arguments. The host resolves SQL, clients, credentials, and raw results. */ +export interface ClickHouseTrustedQueryExecutionArguments { + readonly contractVersion: typeof CLICKHOUSE_TRUSTED_QUERY_EVALUATION_CONTRACT_VERSION; + readonly profile: ClickHouseTrustedQueryEvaluationProfile; + readonly scenario: ProductionEvaluationRef; + readonly queryPlan: ProductionEvaluationRef; + readonly source: ProductionEvaluationRef; + readonly schema: ProductionEvaluationRef; + readonly policy: ProductionEvaluationRef; +} + +export interface ClickHouseTrustedQueryAdapterInputCoordinates { + readonly requestId: string; + readonly operationId: string; + readonly effectRunId: string; + readonly routeId: string; + readonly executorId: string; + readonly profileId: string; + readonly arguments: ClickHouseTrustedQueryExecutionArguments; + readonly approval: { + readonly policyId: string; + readonly mode: "auto" | "require" | "never"; + }; +} + +export interface ClickHouseTrustedQueryHostExecutionRequest { + readonly profile: Readonly; + readonly scenario: ProductionEvaluationRef; + readonly queryPlan: ProductionEvaluationRef; + readonly source: ProductionEvaluationRef; + readonly schema: ProductionEvaluationRef; + readonly policy: ProductionEvaluationRef; + readonly requestId: string; + readonly admissionId: string; + readonly runId: string; + readonly attempt: number; + readonly signal: AbortSignal; +} + +export interface ClickHouseTrustedQueryHostSettlement { + readonly kind: "clickhouse-trusted-query-host-settlement"; + readonly measurements: Readonly>; + readonly evidenceId: string; + readonly evidenceHighWater: number; + readonly evidenceRefs: readonly ProductionEvaluationRef[]; + readonly recordedAtMs: number; +} + +export interface ClickHouseTrustedQueryHostCapability { + execute( + request: ClickHouseTrustedQueryHostExecutionRequest, + ): ClickHouseTrustedQueryHostSettlement | PromiseLike; +} + +export type ClickHouseTrustedQueryFailureKind = + | "capability-unavailable" + | "authentication" + | "authorization" + | "connectivity" + | "schema-drift" + | "incompatible-plan" + | "resource-limit" + | "malformed-settlement"; + +export interface ClickHouseTrustedQueryHostError extends Error { + readonly kind?: ClickHouseTrustedQueryFailureKind; +} + +export interface ClickHouseTrustedQueryCancellationRequested { + readonly kind: "clickhouse-trusted-query-cancellation-requested"; + readonly cancellationId: string; + readonly admissionId: string; + readonly runId: string; + readonly adapterInputId: string; + readonly requestId: string; + readonly operationId: string; + readonly attempt: number; + readonly sourceRefs?: readonly SourceRef[]; +} + +export interface ClickHouseTrustedQueryCancellationProposal + extends Omit { + readonly kind: "clickhouse-trusted-query-cancellation-proposal"; + readonly proposalId: string; +} + +export interface ClickHouseTrustedQueryCancellationDecision { + readonly kind: "clickhouse-trusted-query-cancellation-decision"; + readonly decisionId: string; + readonly proposalId: string; + readonly outcome: "admit" | "block"; + readonly sourceRefs?: readonly SourceRef[]; +} + +export interface ClickHouseTrustedQueryCancellationAdmission { + readonly kind: "clickhouse-trusted-query-cancellation-admission"; + readonly admissionId: string; + readonly proposalId: string; + readonly decisionId: string; + readonly cancellationId: string; + readonly runId: string; + readonly state: "admitted" | "blocked"; + readonly sourceRefs?: readonly SourceRef[]; +} + +export interface ClickHouseTrustedQueryRuntimeOptions { + readonly name?: string; + readonly inputs: Node>; + /** Must be the approved output of the ordinary D419 admission projector. */ + readonly admittedRunRequests: readonly Node[]; + readonly cancellationRequests?: readonly Node[]; + readonly cancellationDecisions?: readonly Node[]; + readonly capability: ClickHouseTrustedQueryHostCapability; + readonly timeoutMs?: number; + readonly now?: () => number; +} + +export interface ClickHouseTrustedQueryRuntimeBundle { + readonly outcomes: Node>; + readonly runStatus: Node; + readonly status: Node; + readonly issues: Node; + readonly audit: Node; + readonly cancellationProposals: Node; + readonly cancellationAdmissions: Node; + dispose(): Promise; +} + +export interface ClickHouseTrustedQueryScenarioResultFromOutcomeInput { + readonly arguments: ClickHouseTrustedQueryExecutionArguments; + readonly resultId: string; + readonly outcome: ExecutorOutcome; +} const PRIVATE_MATERIAL = /\b(password|secret|bearer|private[-_]?key|access[-_]?key|connection[-_]?string|dsn)\b|=/i; const RAW_SQL_MATERIAL = @@ -348,3 +500,1230 @@ export function createClickHouseTrustedQueryScenarioResult( "production-scenario-result", ); } + +/** Builds the exact, coordinate-only D419 adapter input for a pinned scenario. */ +export function createClickHouseTrustedQueryAdapterInput( + value: ClickHouseTrustedQueryAdapterInputCoordinates, +): Readonly> { + const input = productionEvaluationSnapshot(value); + if ( + !input || + typeof input !== "object" || + ![ + input.requestId, + input.operationId, + input.effectRunId, + input.routeId, + input.executorId, + input.profileId, + ].every(publicToken) + ) + throw new TypeError("clickhouse-trusted-query-adapter-input-invalid-or-private-material"); + const args = validateExecutionArguments(input.arguments); + const executionFingerprint = clickHouseExecutionFingerprint(args); + if ( + !input.approval || + typeof input.approval !== "object" || + !onlyKeys(input.approval, ["policyId", "mode"]) || + !publicToken(input.approval.policyId) || + !(["auto", "require", "never"] as const).includes(input.approval.mode) + ) + throw new TypeError("clickhouse-trusted-query-adapter-input-invalid-approval"); + const approvalPolicy = Object.freeze({ + kind: "tool-provider-execution-policy", + policyId: input.approval.policyId, + providerId: CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID, + profileIds: Object.freeze([input.profileId]), + toolNames: Object.freeze([CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME]), + operations: Object.freeze([CLICKHOUSE_TRUSTED_QUERY_OPERATION]), + approval: Object.freeze({ + mode: input.approval.mode, + sourceRefs: toSourceRefs("clickhouse-policy", [args.policy]), + }), + sourceRefs: toSourceRefs("clickhouse-policy", [args.policy]), + }) satisfies ToolProviderExecutionPolicy; + return productionEvaluationSnapshot({ + kind: "tool-provider-adapter-input", + adapterInputId: compoundTupleKey("clickhouse-trusted-query-adapter-input", [ + input.requestId, + input.operationId, + input.effectRunId, + executionFingerprint, + ]), + status: "ready", + requestId: input.requestId, + operationId: input.operationId, + effectRunId: input.effectRunId, + routeId: input.routeId, + providerId: CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID, + executorId: input.executorId, + profileId: input.profileId, + toolName: CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME, + operation: CLICKHOUSE_TRUSTED_QUERY_OPERATION, + toolCall: { + kind: "tool-call", + toolName: CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME, + operation: CLICKHOUSE_TRUSTED_QUERY_OPERATION, + arguments: args, + expectedOutput: { resultKind: "clickhouse-trusted-query-host-settlement" }, + idempotency: { + key: canonicalTupleKey([input.effectRunId, executionFingerprint]), + safeToRetry: false, + }, + }, + policies: Object.freeze([approvalPolicy]), + policyRefs: Object.freeze([ + { kind: "tool-provider-execution-policy", id: approvalPolicy.policyId }, + ]), + sourceRefs: Object.freeze([ + ...toSourceRefs("clickhouse-campaign", [args.profile.campaign]), + ...toSourceRefs("clickhouse-scenario", [args.scenario]), + ...toSourceRefs("clickhouse-query-plan", [args.queryPlan]), + ...toSourceRefs("clickhouse-source", [args.source]), + ...toSourceRefs("clickhouse-schema", [args.schema]), + ...toSourceRefs("clickhouse-policy", [args.policy]), + ]), + metadata: { + campaignId: args.profile.campaign.id, + campaignRevision: args.profile.campaign.revision, + scenarioId: args.scenario.id, + scenarioRevision: args.scenario.revision, + configurationFingerprint: args.profile.candidate.configurationFingerprint, + executionFingerprint, + }, + }) as Readonly>; +} + +/** Maps one real executor outcome into the existing D610 scenario-result contract. */ +export function createClickHouseTrustedQueryScenarioResultFromOutcome( + value: ClickHouseTrustedQueryScenarioResultFromOutcomeInput, +): Readonly { + const input = productionEvaluationSnapshot(value); + const args = validateExecutionArguments(input.arguments); + const outcome = input.outcome; + if (!outcome || typeof outcome !== "object") + throw new TypeError("clickhouse-trusted-query-outcome-invalid"); + if (outcome.kind === "blocked") + throw new TypeError("clickhouse-trusted-query-outcome-blocked-is-not-execution"); + if (!validClickHouseTerminalOutcomeShape(outcome)) + throw new TypeError("clickhouse-trusted-query-outcome-terminal-shape-invalid"); + const metadata = outcome.metadata; + if ( + outcome.inputKind !== "tool-call" || + metadata?.providerId !== CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID || + metadata.toolName !== CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME || + metadata.operation !== CLICKHOUSE_TRUSTED_QUERY_OPERATION + ) + throw new TypeError("clickhouse-trusted-query-outcome-provider-correlation-mismatch"); + const admissionId = metadata?.admissionId; + const runId = metadata?.runId; + const evidenceId = metadata?.evidenceId; + const evidenceHighWater = metadata?.evidenceHighWater; + const evidenceRefs = metadata?.productionEvidenceRefs; + const recordedAtMs = metadata?.recordedAtMs ?? outcome.occurredAtMs; + const expectedCorrelation = clickHouseExecutionCorrelation(args); + const actualCorrelation = metadata?.executionCorrelation; + if ( + productionEvaluationCanonical(actualCorrelation) !== + productionEvaluationCanonical(expectedCorrelation) + ) + throw new TypeError("clickhouse-trusted-query-outcome-execution-correlation-mismatch"); + if ( + ![admissionId, runId, evidenceId].every(publicToken) || + !Number.isSafeInteger(evidenceHighWater) || + (evidenceHighWater as number) < 0 || + !publicRefs(evidenceRefs) || + !Number.isSafeInteger(recordedAtMs) || + (recordedAtMs as number) < 0 + ) + throw new TypeError("clickhouse-trusted-query-outcome-correlation-invalid"); + const settlement = + outcome.kind === "result" && + outcome.result.kind === "clickhouse-trusted-query-host-settlement" && + outcome.result.value !== undefined + ? validateHostSettlement(outcome.result.value, args) + : undefined; + if (outcome.kind === "result" && settlement === undefined) + throw new TypeError("clickhouse-trusted-query-outcome-result-kind-invalid"); + if ( + settlement !== undefined && + (evidenceId !== settlement.evidenceId || + evidenceHighWater !== settlement.evidenceHighWater || + recordedAtMs !== settlement.recordedAtMs || + productionEvaluationCanonical(evidenceRefs) !== + productionEvaluationCanonical(settlement.evidenceRefs)) + ) + throw new TypeError("clickhouse-trusted-query-outcome-settlement-metadata-mismatch"); + if ( + outcome.evidenceRefs === undefined || + productionEvaluationCanonical(outcome.evidenceRefs) !== + productionEvaluationCanonical(toSourceRefs("clickhouse-evidence", evidenceRefs)) + ) + throw new TypeError("clickhouse-trusted-query-outcome-evidence-projection-mismatch"); + if ( + settlement === undefined && + (evidenceId !== outcome.outcomeId || + !publicRefs(evidenceRefs) || + !includesRef(evidenceRefs, { + id: outcome.outcomeId, + revision: "executor-outcome-v1", + }) || + !defaultProductionEvidenceRefs(args).every((required) => includesRef(evidenceRefs, required))) + ) + throw new TypeError("clickhouse-trusted-query-outcome-terminal-evidence-mismatch"); + const measurements = settlement?.measurements ?? Object.freeze({}); + if (!publicMeasurements(measurements)) + throw new TypeError("clickhouse-trusted-query-outcome-correlation-invalid"); + return createClickHouseTrustedQueryScenarioResult({ + kind: "clickhouse-trusted-query-scenario-result-input", + profile: args.profile, + scenario: args.scenario, + resultId: input.resultId, + requestId: outcome.requestId, + admissionId: admissionId as string, + runId: runId as string, + attempt: outcome.attempt, + outcomeId: outcome.outcomeId, + evidenceId: evidenceId as string, + evidenceHighWater: evidenceHighWater as number, + outcome: + outcome.kind === "result" + ? "succeeded" + : outcome.kind === "canceled" + ? "cancelled" + : outcome.kind === "timeout" + ? "timed-out" + : "failed", + measurements: measurements as Readonly>, + evidenceRefs: evidenceRefs as readonly ProductionEvaluationRef[], + recordedAtMs: recordedAtMs as number, + }); +} + +function validClickHouseTerminalOutcomeShape( + outcome: ExecutorOutcome, +): boolean { + const raw = outcome as unknown as Readonly>; + const has = (key: string): boolean => Object.hasOwn(raw, key); + if (outcome.kind === "result") + return has("result") && !has("error") && !has("reason") && !has("timeoutMs") && !has("needs"); + if (outcome.kind === "failure") + return ( + has("error") && + outcome.error !== null && + typeof outcome.error === "object" && + outcome.error.kind === "issue" && + publicToken(outcome.error.code) && + publicToken(outcome.error.message) && + outcome.retryable === false && + !has("result") && + !has("reason") && + !has("timeoutMs") && + !has("needs") + ); + if (outcome.kind === "canceled") + return ( + outcome.reason === "admitted-user-cancellation" && + !has("result") && + !has("error") && + !has("timeoutMs") && + !has("needs") + ); + if (outcome.kind === "timeout") + return ( + Number.isSafeInteger(outcome.timeoutMs) && + (outcome.timeoutMs ?? 0) > 0 && + outcome.retryable === false && + !has("result") && + !has("error") && + !has("reason") && + !has("needs") + ); + return false; +} + +/** Executes only exact ordinary-D419 admissions through a host-private capability. */ +export function clickHouseTrustedQueryRuntime( + graph: Graph, + opts: ClickHouseTrustedQueryRuntimeOptions, +): ClickHouseTrustedQueryRuntimeBundle { + if (opts.admittedRunRequests.length === 0) + throw new TypeError("clickhouse runtime requires explicit admitted run requests"); + const name = opts.name ?? "clickhouseTrustedQueryEvaluationRuntime"; + if (!publicToken(name)) + throw new TypeError("clickhouse-trusted-query-runtime-name-invalid-or-private-material"); + const timeoutMs = positiveInteger(opts.timeoutMs, 30_000); + const topology = graph.topologyGroup({ name }); + const outcomes = topology.node>([], null, { + name: `${name}/outcomes`, + }); + const runStatus = topology.node([], null, { + name: `${name}/runStatus`, + }); + const status = topology.node([], null, { name: `${name}/status` }); + const issues = topology.node([], null, { name: `${name}/issues` }); + const audit = topology.node([], null, { name: `${name}/audit` }); + const cancellationProposals = topology.node( + [], + null, + { name: `${name}/cancellationProposals` }, + ); + const cancellationAdmissions = topology.node( + [], + null, + { name: `${name}/cancellationAdmissions` }, + ); + const inputs = new Map< + string, + Readonly> + >(); + const inputFingerprints = new Map(); + const runFingerprints = new Map(); + const active = new Map(); + const proposals = new Map(); + const pending = new Set>(); + let auditSequence = 0; + let disposed = false; + let shutdown: Promise | undefined; + let topologyReleased = false; + + const publishIssue = (next: DataIssue): void => issues.down([["DATA", next]]); + const publishAudit = ( + kind: string, + subjectId: string, + metadata?: Record, + ): void => { + auditSequence += 1; + audit.down([ + [ + "DATA", + Object.freeze({ + id: compoundTupleKey("clickhouse-trusted-query-runtime-audit", [ + name, + String(auditSequence), + ]), + kind, + subjectId, + ...(metadata === undefined ? {} : { metadata: Object.freeze(metadata) }), + }) satisfies AgentRuntimeAuditRecord, + ], + ]); + }; + const publishRunStatus = ( + request: ToolProviderAdapterRunRequested, + next: ToolProviderAdapterRunStatus["status"], + outcomeId?: string, + nextIssues?: readonly DataIssue[], + ): void => { + runStatus.down([ + [ + "DATA", + Object.freeze({ + kind: "tool-provider-adapter-run-status", + runId: request.runId, + adapterInputId: request.adapterInputId, + requestId: request.requestId, + operationId: request.operationId, + status: next, + attempt: request.attempt, + ...(outcomeId === undefined ? {} : { outcomeId }), + ...(nextIssues === undefined ? {} : { issues: nextIssues }), + sourceRefs: request.sourceRefs, + metadata: Object.freeze({ providerId: CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID }), + }) satisfies ToolProviderAdapterRunStatus, + ], + ]); + }; + + function publishOutcome( + run: ClickHouseActiveRun, + outcome: ExecutorOutcome, + ): void { + outcomes.down([["DATA", outcome]]); + publishRunStatus(run.request, outcome.kind, outcome.outcomeId, outcome.issues); + status.down([ + [ + "DATA", + Object.freeze({ + kind: "status", + requestId: run.request.requestId, + operationId: run.request.operationId, + effectRunId: run.input.effectRunId ?? run.request.runId, + status: + outcome.kind === "result" + ? "completed" + : outcome.kind === "failure" + ? "failed" + : outcome.kind, + sourceRefs: outcome.evidenceRefs, + metadata: Object.freeze({ runId: run.request.runId }), + }) satisfies AgentRequestStatusChanged, + ], + ]); + publishAudit("clickhouse-trusted-query-runtime-finished", run.request.requestId, { + runId: run.request.runId, + attempt: run.request.attempt, + outcome: outcome.kind, + }); + } + + function execute(raw: ToolProviderAdapterRunRequested): void { + if (disposed) return; + const request = snapshotRunRequest(raw); + if (request === undefined) { + publishIssue( + runtimeIssue( + "clickhouse-trusted-query-run-invalid", + "ClickHouse trusted-query admitted run is not bounded inert data.", + ), + ); + return; + } + if (request.providerId !== CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID) return; + const input = inputs.get(request.adapterInputId); + if (input === undefined) { + const missing = runtimeIssue( + "clickhouse-trusted-query-run-missing-input", + "ClickHouse trusted-query run has no matching adapter input.", + ); + publishIssue(missing); + publishRunStatus(request, "missing-input", undefined, [missing]); + return; + } + const fingerprint = clickHouseRunFingerprint(request); + const prior = runFingerprints.get(request.runId); + if (prior !== undefined) { + if (prior !== fingerprint) { + const conflict = runtimeIssue( + "clickhouse-trusted-query-run-coordinate-conflict", + "ClickHouse trusted-query run id was reused with different coordinates.", + ); + publishIssue(conflict); + publishRunStatus(request, "mismatched-request", undefined, [conflict]); + } + return; + } + runFingerprints.set(request.runId, fingerprint); + publishRunStatus(request, "requested"); + const admissionId = exactAdmissionId(request, input); + const args = validateRuntimeInput(request, input); + if (admissionId === undefined || args === undefined) { + const mismatch = runtimeIssue( + "clickhouse-trusted-query-run-input-mismatch", + "ClickHouse trusted-query run does not exactly match a ready D419-admitted input.", + ); + publishIssue(mismatch); + publishRunStatus(request, "mismatched-request", undefined, [mismatch]); + return; + } + const run: ClickHouseActiveRun = { + request, + input, + args, + admissionId, + controller: new AbortController(), + cancelKind: undefined, + }; + active.set(request.runId, run); + publishRunStatus(request, "started"); + publishAudit("clickhouse-trusted-query-runtime-started", request.requestId, { + runId: request.runId, + attempt: request.attempt, + admissionId, + }); + const task = runClickHouseCapability(run, opts, timeoutMs) + .then((outcome) => { + if (!disposed || run.cancelKind !== "dispose") publishOutcome(run, outcome); + }) + .finally(() => { + active.delete(request.runId); + pending.delete(task); + }); + pending.add(task); + } + + function requestCancellation(raw: ClickHouseTrustedQueryCancellationRequested): void { + if (disposed) return; + const request = snapshotCancellationRequest(raw); + const run = request === undefined ? undefined : active.get(request.runId); + if (request === undefined || run === undefined || !cancellationMatchesRun(request, run)) { + publishIssue( + runtimeIssue( + "clickhouse-trusted-query-cancellation-coordinate-mismatch", + "Cancellation does not exactly match an active ClickHouse trusted-query run.", + ), + ); + return; + } + const proposal = Object.freeze({ + ...request, + kind: "clickhouse-trusted-query-cancellation-proposal" as const, + proposalId: compoundTupleKey("clickhouse-trusted-query-cancellation-proposal", [ + request.cancellationId, + request.runId, + ]), + }); + proposals.set(proposal.proposalId, proposal); + cancellationProposals.down([["DATA", proposal]]); + } + + function decideCancellation(raw: ClickHouseTrustedQueryCancellationDecision): void { + if (disposed) return; + const decision = snapshotCancellationDecision(raw); + const proposal = decision === undefined ? undefined : proposals.get(decision.proposalId); + if (decision === undefined || proposal === undefined) { + publishIssue( + runtimeIssue( + "clickhouse-trusted-query-cancellation-decision-invalid", + "Cancellation decision has no exact bounded proposal.", + ), + ); + return; + } + proposals.delete(proposal.proposalId); + const run = active.get(proposal.runId); + const admitted = + decision.outcome === "admit" && + run !== undefined && + run.cancelKind === undefined && + cancellationMatchesRun(proposal, run); + const admission = Object.freeze({ + kind: "clickhouse-trusted-query-cancellation-admission" as const, + admissionId: compoundTupleKey("clickhouse-trusted-query-cancellation-admission", [ + decision.decisionId, + ]), + proposalId: proposal.proposalId, + decisionId: decision.decisionId, + cancellationId: proposal.cancellationId, + runId: proposal.runId, + state: admitted ? ("admitted" as const) : ("blocked" as const), + sourceRefs: decision.sourceRefs, + }); + cancellationAdmissions.down([["DATA", admission]]); + if (admitted && run !== undefined) { + run.cancelKind = "user"; + run.controller.abort(); + } + } + + const unsubscribers = [ + opts.inputs.subscribe((message) => { + if (message[0] !== "DATA") return; + const input = snapshotClickHouseInput( + message[1] as ToolProviderAdapterInput, + ); + if (input === undefined) return; + const fingerprint = productionEvaluationCanonical(input); + const prior = inputFingerprints.get(input.adapterInputId); + if (prior !== undefined && prior !== fingerprint) { + publishIssue( + runtimeIssue( + "clickhouse-trusted-query-adapter-input-coordinate-conflict", + "ClickHouse adapter input id was reused with different immutable coordinates.", + ), + ); + return; + } + if (prior === undefined) { + inputFingerprints.set(input.adapterInputId, fingerprint); + inputs.set(input.adapterInputId, input); + } + }), + ...opts.admittedRunRequests.map((node) => + node.subscribe((message) => { + if (message[0] === "DATA") execute(message[1] as ToolProviderAdapterRunRequested); + }), + ), + ...(opts.cancellationRequests ?? []).map((node) => + node.subscribe((message) => { + if (message[0] === "DATA") + requestCancellation(message[1] as ClickHouseTrustedQueryCancellationRequested); + }), + ), + ...(opts.cancellationDecisions ?? []).map((node) => + node.subscribe((message) => { + if (message[0] === "DATA") + decideCancellation(message[1] as ClickHouseTrustedQueryCancellationDecision); + }), + ), + ]; + + return Object.freeze({ + outcomes, + runStatus, + status, + issues, + audit, + cancellationProposals, + cancellationAdmissions, + dispose() { + if (shutdown === undefined) { + disposed = true; + for (const unsubscribe of unsubscribers) unsubscribe(); + for (const run of active.values()) { + if (run.cancelKind === undefined) { + run.cancelKind = "dispose"; + run.controller.abort(); + } + } + shutdown = Promise.allSettled([...pending]).then(() => { + active.clear(); + inputs.clear(); + inputFingerprints.clear(); + proposals.clear(); + runFingerprints.clear(); + }); + } + const releaseTopology = (): void => { + if (topologyReleased) return; + try { + topology.release({ reason: `${name}:dispose` }); + topologyReleased = true; + } catch { + // Caller-owned subscribers may intentionally keep disposed output views inspectable. + } + }; + return shutdown.then(releaseTopology, (error: unknown) => { + releaseTopology(); + throw error; + }); + }, + } satisfies ClickHouseTrustedQueryRuntimeBundle); +} + +interface ClickHouseActiveRun { + readonly request: ToolProviderAdapterRunRequested; + readonly input: Readonly>; + readonly args: Readonly; + readonly admissionId: string; + readonly controller: AbortController; + cancelKind: "user" | "timeout" | "dispose" | undefined; +} + +const CLICKHOUSE_HOST_ABORTED = Symbol("clickhouse-host-aborted"); + +async function runClickHouseCapability( + run: ClickHouseActiveRun, + opts: ClickHouseTrustedQueryRuntimeOptions, + timeoutMs: number, +): Promise> { + let timer: ReturnType | undefined; + let abortListener: (() => void) | undefined; + try { + timer = setTimeout(() => { + if (run.cancelKind === undefined) { + run.cancelKind = "timeout"; + run.controller.abort(); + } + }, timeoutMs); + const hostResult = opts.capability.execute({ + profile: run.args.profile, + scenario: run.args.scenario, + queryPlan: run.args.queryPlan, + source: run.args.source, + schema: run.args.schema, + policy: run.args.policy, + requestId: run.request.requestId, + admissionId: run.admissionId, + runId: run.request.runId, + attempt: run.request.attempt, + signal: run.controller.signal, + }); + const aborted = new Promise((resolve) => { + abortListener = () => resolve(CLICKHOUSE_HOST_ABORTED); + if (run.controller.signal.aborted) abortListener(); + else run.controller.signal.addEventListener("abort", abortListener, { once: true }); + }); + const settlement = await Promise.race([hostResult, aborted]); + if (settlement === CLICKHOUSE_HOST_ABORTED) + return canceledOrTimedOutOutcome(run, opts, timeoutMs); + const checked = validateHostSettlement(settlement, run.args); + return Object.freeze({ + ...clickHouseOutcomeBase(run, opts, checked), + kind: "result", + result: Object.freeze({ + kind: "clickhouse-trusted-query-host-settlement", + value: checked, + refs: toSourceRefs("clickhouse-evidence", checked.evidenceRefs), + }), + }); + } catch (error: unknown) { + if (run.controller.signal.aborted) return canceledOrTimedOutOutcome(run, opts, timeoutMs); + const classified = classifyHostError(error); + const issue = runtimeIssue( + `clickhouse-trusted-query-${classified.kind}`, + classified.message, + classified.retryable, + ); + return Object.freeze({ + ...clickHouseOutcomeBase(run, opts), + kind: "failure", + error: issue, + retryable: classified.retryable, + issues: Object.freeze([issue]), + }); + } finally { + if (timer !== undefined) clearTimeout(timer); + if (abortListener !== undefined) + run.controller.signal.removeEventListener("abort", abortListener); + } +} + +function canceledOrTimedOutOutcome( + run: ClickHouseActiveRun, + opts: ClickHouseTrustedQueryRuntimeOptions, + timeoutMs: number, +): ExecutorOutcome { + return run.cancelKind === "timeout" + ? Object.freeze({ + ...clickHouseOutcomeBase(run, opts), + kind: "timeout", + timeoutMs, + retryable: false, + }) + : Object.freeze({ + ...clickHouseOutcomeBase(run, opts), + kind: "canceled", + reason: run.cancelKind === "user" ? "admitted-user-cancellation" : "runtime-disposed", + }); +} + +function clickHouseOutcomeBase( + run: ClickHouseActiveRun, + opts: ClickHouseTrustedQueryRuntimeOptions, + settlement?: ClickHouseTrustedQueryHostSettlement, +) { + const recordedAtMs = settlement?.recordedAtMs ?? opts.now?.() ?? 0; + const outcomeId = compoundTupleKey("clickhouse-trusted-query-executor-outcome", [ + run.request.runId, + String(run.request.attempt), + ]); + const evidenceId = settlement?.evidenceId ?? outcomeId; + const evidenceRefs = + settlement?.evidenceRefs ?? + Object.freeze([ + { id: outcomeId, revision: "executor-outcome-v1" }, + ...defaultProductionEvidenceRefs(run.args), + ]); + return { + outcomeId, + requestId: run.request.requestId, + operationId: run.request.operationId, + routeId: run.request.routeId!, + executorId: run.request.executorId!, + profileId: run.request.profileId!, + attempt: run.request.attempt, + inputId: run.request.adapterInputId, + inputKind: "tool-call", + occurredAtMs: recordedAtMs, + evidenceRefs: toSourceRefs("clickhouse-evidence", evidenceRefs), + metadata: Object.freeze({ + runId: run.request.runId, + admissionId: run.admissionId, + providerId: CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID, + toolName: CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME, + operation: CLICKHOUSE_TRUSTED_QUERY_OPERATION, + executionCorrelation: clickHouseExecutionCorrelation(run.args), + evidenceId, + evidenceHighWater: settlement?.evidenceHighWater ?? 0, + productionEvidenceRefs: evidenceRefs, + recordedAtMs, + }), + } as const; +} + +function validateExecutionArguments( + value: ClickHouseTrustedQueryExecutionArguments, +): Readonly { + const args = productionEvaluationSnapshot(value); + if ( + !args || + typeof args !== "object" || + !onlyKeys(args, [ + "contractVersion", + "profile", + "scenario", + "queryPlan", + "source", + "schema", + "policy", + ]) || + args.contractVersion !== CLICKHOUSE_TRUSTED_QUERY_EVALUATION_CONTRACT_VERSION || + !publicRef(args.scenario) || + !publicRef(args.queryPlan) || + !publicRef(args.source) || + !publicRef(args.schema) || + !publicRef(args.policy) + ) + throw new TypeError("clickhouse-trusted-query-execution-arguments-invalid-or-private-material"); + const profile = validateClickHouseTrustedQueryEvaluationProfile(args.profile); + if ( + !profile.scenarios.some( + (scenario) => + scenario.scenarioId === args.scenario.id && scenario.revision === args.scenario.revision, + ) || + !includesRef(profile.queryPlanRefs, args.queryPlan) || + !includesRef(profile.sourceRefs, args.source) || + !includesRef(profile.schemaRefs, args.schema) || + !includesRef(profile.policyRefs, args.policy) + ) + throw new TypeError("clickhouse-trusted-query-execution-arguments-not-pinned"); + return Object.freeze({ ...args, profile }); +} + +function validateHostSettlement( + value: ClickHouseTrustedQueryHostSettlement, + args: ClickHouseTrustedQueryExecutionArguments, +): Readonly { + const settlement = productionEvaluationSnapshot(value); + if ( + !settlement || + typeof settlement !== "object" || + !onlyKeys(settlement, [ + "kind", + "measurements", + "evidenceId", + "evidenceHighWater", + "evidenceRefs", + "recordedAtMs", + ]) || + settlement.kind !== "clickhouse-trusted-query-host-settlement" || + !publicMeasurements(settlement.measurements) || + !publicToken(settlement.evidenceId) || + !Number.isSafeInteger(settlement.evidenceHighWater) || + settlement.evidenceHighWater < 0 || + !publicRefs(settlement.evidenceRefs) || + !Number.isSafeInteger(settlement.recordedAtMs) || + settlement.recordedAtMs < 0 + ) + throw new TypeError("clickhouse-trusted-query-host-settlement-invalid-or-private-material"); + if ( + !settlement.evidenceRefs.some((ref) => ref.id === settlement.evidenceId) || + !defaultProductionEvidenceRefs(args).every((required) => + includesRef(settlement.evidenceRefs, required), + ) + ) + throw new TypeError("clickhouse-trusted-query-host-settlement-evidence-correlation-mismatch"); + return settlement; +} + +function snapshotClickHouseInput( + value: ToolProviderAdapterInput, +): Readonly> | undefined { + try { + const input = productionEvaluationSnapshot(value); + const policy = input.policies?.[0]; + const approvalMode = policy?.approval?.mode; + if ( + input.providerId !== CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID || + input.toolName !== CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME || + input.operation !== CLICKHOUSE_TRUSTED_QUERY_OPERATION || + input.toolCall?.toolName !== CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME || + input.toolCall.operation !== CLICKHOUSE_TRUSTED_QUERY_OPERATION || + !publicToken(input.effectRunId) || + !publicToken(input.routeId) || + !publicToken(input.executorId) || + !publicToken(input.profileId) || + input.policies?.length !== 1 || + !publicToken(policy?.policyId) || + (approvalMode !== "auto" && approvalMode !== "require" && approvalMode !== "never") + ) + return undefined; + const exactApprovalMode = approvalMode as "auto" | "require" | "never"; + const expected = createClickHouseTrustedQueryAdapterInput({ + requestId: input.requestId, + operationId: input.operationId, + effectRunId: input.effectRunId, + routeId: input.routeId, + executorId: input.executorId, + profileId: input.profileId, + arguments: validateExecutionArguments(input.toolCall.arguments!), + approval: { policyId: policy!.policyId, mode: exactApprovalMode }, + }); + return productionEvaluationCanonical(input) === productionEvaluationCanonical(expected) + ? expected + : undefined; + } catch { + return undefined; + } +} + +function validateRuntimeInput( + request: ToolProviderAdapterRunRequested, + input: Readonly>, +): Readonly | undefined { + if ( + input.status !== "ready" || + request.adapterInputId !== input.adapterInputId || + request.requestId !== input.requestId || + request.operationId !== input.operationId || + request.routeId === undefined || + request.routeId !== input.routeId || + request.providerId !== input.providerId || + request.executorId === undefined || + request.executorId !== input.executorId || + request.profileId === undefined || + request.profileId !== input.profileId + ) + return undefined; + try { + return validateExecutionArguments(input.toolCall!.arguments!); + } catch { + return undefined; + } +} + +function projectorAdmissionShape(request: ToolProviderAdapterRunRequested): + | Readonly<{ + admissionId: string; + proposalId: string; + approvedFromRunId: string; + decisionId?: string; + }> + | undefined { + const metadata = request.metadata; + const admissionId = metadata?.admissionId; + const proposalId = metadata?.proposalId; + const approvedFromRunId = metadata?.approvedFromRunId; + const decisionId = metadata?.decisionId; + if ( + !publicToken(admissionId) || + !publicToken(proposalId) || + !publicToken(approvedFromRunId) || + (decisionId !== undefined && !publicToken(decisionId)) || + metadata?.approval !== "granted" || + metadata.approvalGranted !== true || + proposalId !== + compoundTupleKey("tool-provider-run-admission-proposal", [approvedFromRunId as string]) + ) + return undefined; + const refs = request.sourceRefs ?? []; + const exactlyOne = (kind: string, id: string): boolean => + refs.filter((ref) => ref.kind === kind && ref.id === id).length === 1; + if ( + !exactlyOne("tool-provider-run-admission", admissionId) || + !exactlyOne("tool-provider-run-admission-proposal", proposalId) || + !exactlyOne("tool-provider-adapter-run", approvedFromRunId) || + (decisionId !== undefined && !exactlyOne("tool-provider-run-admission-decision", decisionId)) + ) + return undefined; + return Object.freeze({ + admissionId, + proposalId, + approvedFromRunId, + ...(decisionId === undefined ? {} : { decisionId }), + }); +} + +function exactAdmissionId( + request: ToolProviderAdapterRunRequested, + input: ToolProviderAdapterInput, +): string | undefined { + const shape = projectorAdmissionShape(request); + if (shape === undefined) return undefined; + const approvalMode = input.policies?.find( + (policy) => + policy.providerId === CLICKHOUSE_TRUSTED_QUERY_PROVIDER_ID && + (policy.profileIds === undefined || policy.profileIds.includes(input.profileId!)) && + (policy.toolNames === undefined || + policy.toolNames.includes(CLICKHOUSE_TRUSTED_QUERY_TOOL_NAME)) && + (policy.operations === undefined || + policy.operations.includes(CLICKHOUSE_TRUSTED_QUERY_OPERATION)), + )?.approval?.mode; + if (approvalMode === "never" || approvalMode === undefined) return undefined; + if (approvalMode === "require" || approvalMode === "custom") + return shape.decisionId === undefined ? undefined : shape.admissionId; + if (approvalMode !== "auto" || shape.decisionId !== undefined) return undefined; + const expectedAdmissionId = compoundTupleKey("tool-provider-run-admission", [shape.proposalId]); + const expectedRunId = compoundTupleKey("tool-provider-run-admitted", [shape.approvedFromRunId]); + return shape.admissionId === expectedAdmissionId && request.runId === expectedRunId + ? shape.admissionId + : undefined; +} + +function snapshotRunRequest( + value: ToolProviderAdapterRunRequested, +): Readonly | undefined { + try { + const sourceRefs = snapshotSourceRefs(value.sourceRefs); + if ( + value.kind !== "tool-provider-adapter-run-requested" || + ![ + value.runId, + value.adapterInputId, + value.requestId, + value.operationId, + value.routeId, + value.providerId, + value.executorId, + value.profileId, + ].every(publicToken) || + !Number.isSafeInteger(value.attempt) || + value.attempt < 1 || + !publicToken(value.reason) || + (value.sourceRefs !== undefined && sourceRefs === undefined) || + projectorAdmissionShape(value) === undefined + ) + return undefined; + return Object.freeze({ + kind: value.kind, + runId: value.runId, + adapterInputId: value.adapterInputId, + requestId: value.requestId, + operationId: value.operationId, + routeId: value.routeId, + providerId: value.providerId, + executorId: value.executorId, + profileId: value.profileId, + attempt: value.attempt, + reason: value.reason, + sourceRefs, + metadata: Object.freeze({ + approval: "granted", + approvalGranted: true, + admissionId: value.metadata!.admissionId, + proposalId: value.metadata!.proposalId, + approvedFromRunId: value.metadata!.approvedFromRunId, + ...(value.metadata!.decisionId === undefined + ? {} + : { decisionId: value.metadata!.decisionId }), + }), + }); + } catch { + return undefined; + } +} + +function snapshotCancellationRequest( + value: ClickHouseTrustedQueryCancellationRequested, +): Readonly | undefined { + try { + const request = productionEvaluationSnapshot(value); + const sourceRefs = snapshotSourceRefs(request.sourceRefs); + if ( + request.kind !== "clickhouse-trusted-query-cancellation-requested" || + !Object.keys(request).every((key) => + [ + "kind", + "cancellationId", + "admissionId", + "runId", + "adapterInputId", + "requestId", + "operationId", + "attempt", + "sourceRefs", + ].includes(key), + ) || + ![ + request.cancellationId, + request.admissionId, + request.runId, + request.adapterInputId, + request.requestId, + request.operationId, + ].every(publicToken) || + !Number.isSafeInteger(request.attempt) || + request.attempt < 1 || + (request.sourceRefs !== undefined && sourceRefs === undefined) + ) + return undefined; + return Object.freeze({ + kind: request.kind, + cancellationId: request.cancellationId, + admissionId: request.admissionId, + runId: request.runId, + adapterInputId: request.adapterInputId, + requestId: request.requestId, + operationId: request.operationId, + attempt: request.attempt, + ...(sourceRefs === undefined ? {} : { sourceRefs }), + }); + } catch { + return undefined; + } +} + +function snapshotCancellationDecision( + value: ClickHouseTrustedQueryCancellationDecision, +): Readonly | undefined { + try { + const decision = productionEvaluationSnapshot(value); + const sourceRefs = snapshotSourceRefs(decision.sourceRefs); + if ( + decision.kind !== "clickhouse-trusted-query-cancellation-decision" || + !Object.keys(decision).every((key) => + ["kind", "decisionId", "proposalId", "outcome", "sourceRefs"].includes(key), + ) || + ![decision.decisionId, decision.proposalId].every(publicToken) || + (decision.outcome !== "admit" && decision.outcome !== "block") || + (decision.sourceRefs !== undefined && sourceRefs === undefined) + ) + return undefined; + return Object.freeze({ + kind: decision.kind, + decisionId: decision.decisionId, + proposalId: decision.proposalId, + outcome: decision.outcome, + ...(sourceRefs === undefined ? {} : { sourceRefs }), + }); + } catch { + return undefined; + } +} + +function cancellationMatchesRun( + request: Omit, + run: ClickHouseActiveRun, +): boolean { + return ( + request.admissionId === run.admissionId && + request.runId === run.request.runId && + request.adapterInputId === run.request.adapterInputId && + request.requestId === run.request.requestId && + request.operationId === run.request.operationId && + request.attempt === run.request.attempt + ); +} + +function clickHouseRunFingerprint(request: ToolProviderAdapterRunRequested): string { + return canonicalTupleKey([ + request.runId, + request.adapterInputId, + request.requestId, + request.operationId, + request.routeId ?? "", + request.providerId ?? "", + request.executorId ?? "", + request.profileId ?? "", + String(request.attempt), + request.reason, + (request.metadata?.admissionId as string | undefined) ?? "missing-admission", + ]); +} + +function classifyHostError(error: unknown): { + readonly kind: ClickHouseTrustedQueryFailureKind; + readonly message: string; + readonly retryable: boolean; +} { + const kinds: readonly ClickHouseTrustedQueryFailureKind[] = [ + "capability-unavailable", + "authentication", + "authorization", + "connectivity", + "schema-drift", + "incompatible-plan", + "resource-limit", + "malformed-settlement", + ]; + let candidateKind: unknown; + let candidateMessage: unknown; + try { + if (error !== null && typeof error === "object") { + const descriptors = Object.getOwnPropertyDescriptors(error); + candidateKind = descriptors.kind?.value; + candidateMessage = descriptors.message?.value; + } + } catch { + // Host error objects are untrusted; classification remains total and fail-closed. + } + const kind = kinds.includes(candidateKind as ClickHouseTrustedQueryFailureKind) + ? (candidateKind as ClickHouseTrustedQueryFailureKind) + : typeof candidateMessage === "string" && candidateMessage.includes("host-settlement-") + ? "malformed-settlement" + : "capability-unavailable"; + return { + kind, + message: `ClickHouse trusted-query host capability failed: ${kind}.`, + retryable: false, + }; +} + +function runtimeIssue(code: string, message: string, retryable = false): DataIssue { + return Object.freeze({ kind: "issue", code, message, severity: "error", retryable }); +} + +function positiveInteger(value: number | undefined, fallback: number): number { + return Number.isSafeInteger(value) && (value ?? 0) > 0 ? value! : fallback; +} + +function includesRef( + refs: readonly ProductionEvaluationRef[], + value: ProductionEvaluationRef, +): boolean { + return refs.some((ref) => ref.id === value.id && ref.revision === value.revision); +} + +function clickHouseExecutionFingerprint(args: ClickHouseTrustedQueryExecutionArguments): string { + const bytes = new TextEncoder().encode(productionEvaluationCanonical(args)); + let hash = 0xcbf29ce484222325n; + for (const byte of bytes) { + hash ^= BigInt(byte); + hash = BigInt.asUintN(64, hash * 0x100000001b3n); + } + return `fnv1a64:${hash.toString(16).padStart(16, "0")}`; +} + +function clickHouseExecutionCorrelation( + args: ClickHouseTrustedQueryExecutionArguments, +): Readonly> { + return Object.freeze({ + contractVersion: args.contractVersion, + scope: args.profile.scope, + campaign: args.profile.campaign, + candidate: args.profile.candidate, + scenario: args.scenario, + queryPlan: args.queryPlan, + source: args.source, + schema: args.schema, + policy: args.policy, + executionFingerprint: clickHouseExecutionFingerprint(args), + }); +} + +function defaultProductionEvidenceRefs( + args: ClickHouseTrustedQueryExecutionArguments, +): readonly ProductionEvaluationRef[] { + return Object.freeze([args.scenario, args.queryPlan, args.source, args.schema, args.policy]); +} + +function toSourceRefs( + kind: string, + refs: readonly ProductionEvaluationRef[], +): readonly SourceRef[] { + return Object.freeze( + refs.map((ref) => + Object.freeze({ + kind, + id: compoundTupleKey("production-evaluation-ref", [ref.id, ref.revision]), + metadata: Object.freeze({ id: ref.id, revision: ref.revision }), + }), + ), + ); +} + +function snapshotSourceRefs( + value: readonly SourceRef[] | undefined, +): readonly SourceRef[] | undefined { + if (value === undefined) return undefined; + try { + const refs = productionEvaluationSnapshot(value); + if ( + !denseArray(refs) || + !refs.every( + (ref) => + ref !== null && + typeof ref === "object" && + publicToken((ref as SourceRef).kind) && + publicToken((ref as SourceRef).id), + ) + ) + return undefined; + return Object.freeze( + (refs as readonly SourceRef[]).map((ref) => Object.freeze({ kind: ref.kind, id: ref.id })), + ); + } catch { + return undefined; + } +} diff --git a/scripts/check-no-raw-async.ts b/scripts/check-no-raw-async.ts index b15a6efc..32489ec1 100644 --- a/scripts/check-no-raw-async.ts +++ b/scripts/check-no-raw-async.ts @@ -69,6 +69,18 @@ const ALLOW_ALL = new Set([ * unless explicitly listed for a sanctioned boundary file. */ const ALLOW_LABELS = new Map>([ + // D628 focused ClickHouse adapter glue is the host-injected async runtime boundary. + // Keep the exception pattern-scoped so the surrounding DTO/validation surface stays synchronous. + [ + "packages/ts/src/solutions/clickhouse-trusted-query-evaluation.ts", + new Set([ + "new Promise", + "Promise.()", + "async function/method/arrow", + "setTimeout(", + "await", + ]), + ], [ "packages/ts/src/executors/tool-provider-adapters.ts", new Set(["Promise.resolve()", "setTimeout("]),