typekro 0.34.0 → 0.36.0

package/dist/alchemy/clickhouse-schema/executor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The default {@link ClickHouseExecutor}: `@kubernetes/client-node`'s `Exec` over the
+ * Kubernetes API server's `pods/exec` subresource.
+ *
+ * WHY EXEC AND NOT A CLIENT CONNECTION. A converge runs wherever the alchemy runtime
+ * runs — a laptop, a CI runner — which in general has no network path to a ClickHouse
+ * pod. The alternatives are a port-forward (a second moving part, a local listening
+ * socket, and a tunnel that has to outlive every statement) or exposing the native port
+ * (a durable hole punched for a one-off migration). Exec needs neither: the statement
+ * travels over the same authenticated API-server connection everything else uses, the
+ * client runs next to the server, and the credentials stay inside the pod.
+ *
+ * RBAC: the identity running the converge needs `create` on `pods/exec` and `list` on
+ * `pods` in the target namespace.
+ */
+import type { KubeConfig } from '@kubernetes/client-node';
+import type { ClickHouseExecCommand, ClickHouseExecResult, ClickHouseExecutor, ClickHousePodSummary } from './types.js';
+/** `Exec` over the API server. Constructed per resource from the resolved KubeConfig. */
+export declare class KubeExecClickHouseExecutor implements ClickHouseExecutor {
+    private readonly kubeConfig;
+    constructor(kubeConfig: KubeConfig);
+    listPods(namespace: string, podSelector: Readonly<Record<string, string>>, _abortSignal?: AbortSignal): Promise<readonly ClickHousePodSummary[]>;
+    exec(command: ClickHouseExecCommand, abortSignal?: AbortSignal): Promise<ClickHouseExecResult>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/alchemy/clickhouse-schema/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,yBAAyB,CAAC;AAGpE,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAgCpB,yFAAyF;AACzF,qBAAa,0BAA2B,YAAW,kBAAkB;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,UAAU;IAE7C,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC7C,YAAY,CAAC,EAAE,WAAW,GACzB,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC;IAkCrC,IAAI,CACR,OAAO,EAAE,qBAAqB,EAC9B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,oBAAoB,CAAC;CAyEjC"}

package/dist/alchemy/clickhouse-schema/executor.js

@@ -0,0 +1,144 @@
+/**
+ * The default {@link ClickHouseExecutor}: `@kubernetes/client-node`'s `Exec` over the
+ * Kubernetes API server's `pods/exec` subresource.
+ *
+ * WHY EXEC AND NOT A CLIENT CONNECTION. A converge runs wherever the alchemy runtime
+ * runs — a laptop, a CI runner — which in general has no network path to a ClickHouse
+ * pod. The alternatives are a port-forward (a second moving part, a local listening
+ * socket, and a tunnel that has to outlive every statement) or exposing the native port
+ * (a durable hole punched for a one-off migration). Exec needs neither: the statement
+ * travels over the same authenticated API-server connection everything else uses, the
+ * client runs next to the server, and the credentials stay inside the pod.
+ *
+ * RBAC: the identity running the converge needs `create` on `pods/exec` and `list` on
+ * `pods` in the target namespace.
+ */
+import { PassThrough, Readable as NodeReadable } from 'node:stream';
+import { createBunCompatibleApiClient } from '../../core/kubernetes/bun-api-client.js';
+import { getKubernetesClientNode } from '../../core/kubernetes/client-node-runtime.js';
+/** Collect a stream into a string, capped so a runaway command cannot exhaust memory. */
+const MAX_CAPTURED_BYTES = 64 * 1024;
+function collector() {
+    const chunks = [];
+    let size = 0;
+    const stream = new PassThrough();
+    stream.on('data', (chunk) => {
+        if (size >= MAX_CAPTURED_BYTES)
+            return;
+        const slice = chunk.subarray(0, MAX_CAPTURED_BYTES - size);
+        chunks.push(slice);
+        size += slice.length;
+    });
+    return { stream, text: () => Buffer.concat(chunks).toString('utf8') };
+}
+/**
+ * Kubernetes reports a non-zero exit as a `Failure` status carrying an `ExitCode` cause.
+ * A `Failure` with no such cause (the connection died mid-command, for instance) is
+ * reported as exit 1 — a command failure, deliberately NOT a transient transport error,
+ * because the statement may well have run.
+ */
+function exitCodeFromStatus(status) {
+    if (!status)
+        return 1;
+    if (status.status === 'Success')
+        return 0;
+    const cause = status.details?.causes?.find((entry) => entry.reason === 'ExitCode');
+    const parsed = Number.parseInt(cause?.message ?? '', 10);
+    return Number.isNaN(parsed) ? 1 : parsed;
+}
+/** `Exec` over the API server. Constructed per resource from the resolved KubeConfig. */
+export class KubeExecClickHouseExecutor {
+    kubeConfig;
+    constructor(kubeConfig) {
+        this.kubeConfig = kubeConfig;
+    }
+    async listPods(namespace, podSelector, _abortSignal) {
+        const clientNode = getKubernetesClientNode();
+        const coreApi = createBunCompatibleApiClient(this.kubeConfig, clientNode.CoreV1Api);
+        const labelSelector = Object.entries(podSelector)
+            .map(([key, value]) => `${key}=${value}`)
+            .join(',');
+        const pods = await coreApi.listNamespacedPod({ namespace, labelSelector });
+        return pods.items.flatMap((pod) => {
+            const name = pod.metadata?.name;
+            if (!name)
+                return [];
+            // `ready`, `phase` and `terminating` are reported SEPARATELY rather than folded into
+            // one boolean: selection has to tell "not Ready yet, keep waiting" apart from "leaving
+            // or finished, stop waiting", and a pod that is Ready while terminating is the case
+            // where those two answers differ. Which of them disqualifies a pod is the runner's
+            // decision, and it differs by execution model.
+            const ready = (pod.status?.conditions ?? []).some((condition) => condition.type === 'Ready' && condition.status === 'True');
+            // The UID identifies the pod OBJECT, which is what separates "the replica I applied
+            // to" from "its same-named replacement" after a drain or a template change.
+            const uid = pod.metadata?.uid;
+            return [
+                {
+                    name,
+                    ...(uid !== undefined ? { uid } : {}),
+                    ready,
+                    containers: (pod.spec?.containers ?? []).flatMap((c) => (c.name ? [c.name] : [])),
+                    ...(pod.status?.phase !== undefined ? { phase: pod.status.phase } : {}),
+                    ...(pod.metadata?.deletionTimestamp !== undefined ? { terminating: true } : {}),
+                },
+            ];
+        });
+    }
+    async exec(command, abortSignal) {
+        const clientNode = getKubernetesClientNode();
+        const exec = new clientNode.Exec(this.kubeConfig);
+        const stdout = collector();
+        const stderr = collector();
+        const stdin = NodeReadable.from([Buffer.from(command.stdin, 'utf8')]);
+        return await new Promise((resolve, reject) => {
+            let status;
+            let settled = false;
+            let socket;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                abortSignal?.removeEventListener('abort', onAbort);
+                fn();
+            };
+            const fail = (error) => {
+                finish(() => {
+                    try {
+                        socket?.close();
+                    }
+                    catch {
+                        // The socket may already be gone; the original failure is what matters.
+                    }
+                    reject(error);
+                });
+            };
+            const onAbort = () => fail(new Error('ClickHouse exec aborted'));
+            const timer = setTimeout(() => fail(new Error(`ClickHouse exec timed out after ${command.timeoutMs}ms`)), command.timeoutMs);
+            abortSignal?.addEventListener('abort', onAbort, { once: true });
+            if (abortSignal?.aborted) {
+                onAbort();
+                return;
+            }
+            exec
+                .exec(command.namespace, command.podName, command.container, [...command.command], stdout.stream, stderr.stream, stdin, false, (received) => {
+                status = received;
+            })
+                .then((ws) => {
+                socket = ws;
+                // A websocket error before the command completes is a TRANSPORT failure and is
+                // what the retry loop exists for; a clean close carries the command's own status.
+                ws.on('error', (error) => fail(error));
+                ws.on('close', () => {
+                    finish(() => resolve({
+                        stdout: stdout.text(),
+                        stderr: stderr.text(),
+                        exitCode: exitCodeFromStatus(status),
+                    }));
+                });
+            })
+                .catch((error) => fail(error instanceof Error ? error : new Error(String(error))));
+        });
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/alchemy/clickhouse-schema/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/executor.ts"],"names":[],"mappings":"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"}

package/dist/alchemy/clickhouse-schema/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ClickHouse schema management as an alchemy v2 resource.
+ *
+ * @see docs/api/alchemy/clickhouse-schema.md
+ */
+export { KubeExecClickHouseExecutor } from './executor.js';
+export { CLICKHOUSE_SCHEMA_RESOURCE_TYPE, ClickHouseSchema, type ClickHouseSchemaR, clickHouseSchema, clickHouseSchemaProvider, } from './resource.js';
+export { applyClickHouseSchema, computeFingerprint, DEFAULT_BACKOFF_MS, DEFAULT_CLICKHOUSE_CONTAINER, DEFAULT_CLICKHOUSE_DATABASE, DEFAULT_CLICKHOUSE_PASSWORD_ENV, DEFAULT_CLICKHOUSE_PORT, DEFAULT_CLICKHOUSE_USER, DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_RECONCILE_PASSES, DEFAULT_STATEMENT_TIMEOUT_MS, DEFAULT_WAIT_FOR_POD_TIMEOUT_MS, deleteClickHouseSchema, needsApply, renderClickHouseCommand, runStatements, selectExecutionPods, } from './runner.js';
+export type { ClickHouseSchemaRunContext, ClickHouseSchemaRuntimeDeps } from './runner.js';
+export { type ClickHouseSqlToken, escapeClickHouseString, extractStatementSecrets, leadingKeyword, statementTargetsCluster, tokenizeClickHouseSql, validateOnClusterStatement, } from './sql.js';
+export { type ClickHouseExecCommand, type ClickHouseExecResult, type ClickHouseExecutor, type ClickHousePodSummary, type ClickHouseSchemaAppliedPod, type ClickHouseSchemaClient, ClickHouseSchemaClientSchema, type ClickHouseSchemaConfig, type ClickHouseSchemaConfigInput, ClickHouseSchemaConfigSchema, ClickHouseSchemaError, type ClickHouseSchemaExecution, ClickHouseSchemaExecutionSchema, type ClickHouseSchemaProps, type ClickHouseSchemaResourceProps, type ClickHouseSchemaState, type ClickHouseSchemaTarget, ClickHouseSchemaTargetSchema, DEFAULT_EXECUTION, MAX_RETAINED_DETAIL_CHARS, parseClickHouseErrorCode, parseClickHouseExceptionName, redactClickHouseOutput, redactClickHouseText, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/alchemy/clickhouse-schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EACL,+BAA+B,EAC/B,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,UAAU,EACV,uBAAuB,EACvB,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EACL,KAAK,kBAAkB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,4BAA4B,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,4BAA4B,EAC5B,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,4BAA4B,EAC5B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/alchemy/clickhouse-schema/index.js

@@ -0,0 +1,11 @@
+/**
+ * ClickHouse schema management as an alchemy v2 resource.
+ *
+ * @see docs/api/alchemy/clickhouse-schema.md
+ */
+export { KubeExecClickHouseExecutor } from './executor.js';
+export { CLICKHOUSE_SCHEMA_RESOURCE_TYPE, ClickHouseSchema, clickHouseSchema, clickHouseSchemaProvider, } from './resource.js';
+export { applyClickHouseSchema, computeFingerprint, DEFAULT_BACKOFF_MS, DEFAULT_CLICKHOUSE_CONTAINER, DEFAULT_CLICKHOUSE_DATABASE, DEFAULT_CLICKHOUSE_PASSWORD_ENV, DEFAULT_CLICKHOUSE_PORT, DEFAULT_CLICKHOUSE_USER, DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_RECONCILE_PASSES, DEFAULT_STATEMENT_TIMEOUT_MS, DEFAULT_WAIT_FOR_POD_TIMEOUT_MS, deleteClickHouseSchema, needsApply, renderClickHouseCommand, runStatements, selectExecutionPods, } from './runner.js';
+export { escapeClickHouseString, extractStatementSecrets, leadingKeyword, statementTargetsCluster, tokenizeClickHouseSql, validateOnClusterStatement, } from './sql.js';
+export { ClickHouseSchemaClientSchema, ClickHouseSchemaConfigSchema, ClickHouseSchemaError, ClickHouseSchemaExecutionSchema, ClickHouseSchemaTargetSchema, DEFAULT_EXECUTION, MAX_RETAINED_DETAIL_CHARS, parseClickHouseErrorCode, parseClickHouseExceptionName, redactClickHouseOutput, redactClickHouseText, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/alchemy/clickhouse-schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EACL,+BAA+B,EAC/B,gBAAgB,EAEhB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,UAAU,EACV,uBAAuB,EACvB,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAOL,4BAA4B,EAG5B,4BAA4B,EAC5B,qBAAqB,EAErB,+BAA+B,EAK/B,4BAA4B,EAC5B,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,4BAA4B,EAC5B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/alchemy/clickhouse-schema/resource.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `ClickHouseSchema` alchemy v2 resource.
+ *
+ * WHY AN ALCHEMY RESOURCE RATHER THAN A CronJob. TypeKro can already run ClickHouse DDL
+ * from inside the cluster — `clickStackStorage`'s retention CronJob does exactly that —
+ * and that is the right shape when the statements must wait for objects TypeKro does not
+ * own (the OTel tables appear only after the collector migrates). Schema ownership is the
+ * other case: the statements are the deployment's own DDL, they should run once per
+ * converge rather than on a timer, a failure should fail the deploy instead of showing up
+ * in a Job log, and the applied state should be diffable so an unchanged schema costs
+ * nothing. That is a converge-time, stateful, ordered operation — an alchemy resource.
+ *
+ * ORDERING. A `ClickHouseSchema` depends on the ClickHouse instance the same way any
+ * alchemy resource depends on another: pass the instance's `KroResource` output through
+ * its props. Alchemy then deploys the instance (and waits for TypeKro's readiness
+ * evaluation) before this resource's first exec. See `docs/api/alchemy/clickhouse-schema.md`.
+ */
+import * as ProviderMod from 'alchemy/Provider';
+import type { Resource as ResourceT } from 'alchemy/Resource';
+import * as ResourceMod from 'alchemy/Resource';
+import { Effect } from 'effect';
+import { type ClickHouseSchemaProps, type ClickHouseSchemaResourceProps, type ClickHouseSchemaState } from './types.js';
+/** The alchemy resource type, following `KRO_RESOURCE_TYPE`'s `TypeKro.<Name>` convention. */
+export declare const CLICKHOUSE_SCHEMA_RESOURCE_TYPE: "TypeKro.ClickHouseSchema";
+export type ClickHouseSchemaR = ResourceT<typeof CLICKHOUSE_SCHEMA_RESOURCE_TYPE, ClickHouseSchemaResourceProps, ClickHouseSchemaState>;
+/**
+ * The declarative resource. Prefer the {@link clickHouseSchema} factory, which validates
+ * props against the ArkType schema before they reach alchemy state.
+ */
+export declare const ClickHouseSchema: ResourceMod.ResourceClass<ClickHouseSchemaR>;
+/**
+ * The provider `Layer` backing {@link ClickHouseSchema}. Merge it into the alchemy
+ * runtime's providers alongside `kroProvider`.
+ */
+export declare const clickHouseSchemaProvider: import("effect/Layer").Layer<ProviderMod.Provider<ClickHouseSchemaR>, never, never>;
+/**
+ * Declare a ClickHouse schema, validating its configuration first.
+ *
+ * ```ts
+ * const schema = yield* clickHouseSchema('orders-schema', {
+ *   target: { namespace: 'telemetry', podSelector: { 'clickhouse.altinity.com/chi': 'orders' } },
+ *   statements: [
+ *     'CREATE DATABASE IF NOT EXISTS orders',
+ *     'CREATE TABLE IF NOT EXISTS orders.events (id UUID, at DateTime) ENGINE = MergeTree ORDER BY at',
+ *   ],
+ * });
+ * ```
+ *
+ * @param id - Stable alchemy resource id
+ * @param props - Validated against {@link ClickHouseSchemaConfigSchema}
+ * @throws ValidationError when the configuration is invalid
+ */
+export declare function clickHouseSchema(id: string, props: ClickHouseSchemaProps): Effect.Effect<ClickHouseSchemaR, never, ProviderMod.Provider<ClickHouseSchemaR>>;
+//# sourceMappingURL=resource.d.ts.map

package/dist/alchemy/clickhouse-schema/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,IAAI,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAchC,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AAEpB,8FAA8F;AAC9F,eAAO,MAAM,+BAA+B,EAAG,0BAAmC,CAAC;AAEnF,MAAM,MAAM,iBAAiB,GAAG,SAAS,CACvC,OAAO,+BAA+B,EACtC,6BAA6B,EAC7B,qBAAqB,CACtB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,8CAE5B,CAAC;AAmCF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,qFA+DpC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,oFAoBxE"}

package/dist/alchemy/clickhouse-schema/resource.js

@@ -0,0 +1,158 @@
+/**
+ * The `ClickHouseSchema` alchemy v2 resource.
+ *
+ * WHY AN ALCHEMY RESOURCE RATHER THAN A CronJob. TypeKro can already run ClickHouse DDL
+ * from inside the cluster — `clickStackStorage`'s retention CronJob does exactly that —
+ * and that is the right shape when the statements must wait for objects TypeKro does not
+ * own (the OTel tables appear only after the collector migrates). Schema ownership is the
+ * other case: the statements are the deployment's own DDL, they should run once per
+ * converge rather than on a timer, a failure should fail the deploy instead of showing up
+ * in a Job log, and the applied state should be diffable so an unchanged schema costs
+ * nothing. That is a converge-time, stateful, ordered operation — an alchemy resource.
+ *
+ * ORDERING. A `ClickHouseSchema` depends on the ClickHouse instance the same way any
+ * alchemy resource depends on another: pass the instance's `KroResource` output through
+ * its props. Alchemy then deploys the instance (and waits for TypeKro's readiness
+ * evaluation) before this resource's first exec. See `docs/api/alchemy/clickhouse-schema.md`.
+ */
+import * as ProviderMod from 'alchemy/Provider';
+import * as ResourceMod from 'alchemy/Resource';
+import { type } from 'arktype';
+import { Effect } from 'effect';
+import { materializeSerializableKubeConfigOptions } from '../../core/deployment/shared-utilities.js';
+import { ValidationError } from '../../core/errors.js';
+import { clusterIdentity } from '../../core/kubernetes/api-capability.js';
+import { createKubernetesClientProvider } from '../../core/kubernetes/client-provider.js';
+import { getComponentLogger } from '../../core/logging/index.js';
+import { ensureError } from '../../core/errors.js';
+import { KubeExecClickHouseExecutor } from './executor.js';
+import { applyClickHouseSchema, computeFingerprint, deleteClickHouseSchema, needsApply, } from './runner.js';
+import { ClickHouseSchemaConfigSchema, } from './types.js';
+/** The alchemy resource type, following `KRO_RESOURCE_TYPE`'s `TypeKro.<Name>` convention. */
+export const CLICKHOUSE_SCHEMA_RESOURCE_TYPE = 'TypeKro.ClickHouseSchema';
+/**
+ * The declarative resource. Prefer the {@link clickHouseSchema} factory, which validates
+ * props against the ArkType schema before they reach alchemy state.
+ */
+export const ClickHouseSchema = ResourceMod.Resource(CLICKHOUSE_SCHEMA_RESOURCE_TYPE);
+/**
+ * Build the transport: the injected executor if present, else exec over the kube API.
+ *
+ * The cluster identity travels WITH the transport rather than being derived later,
+ * because they answer the same question — which API server this converge is talking to —
+ * and deriving it twice is how the two drift apart. `clusterIdentity` is the helper the
+ * per-cluster capability cache already keys on, reused rather than re-derived, so the two
+ * caches cannot disagree about what "the same cluster" means.
+ *
+ * An injected executor is still identified when a kubeConfig accompanies it: the caller
+ * supplying its own transport does not make the target cluster unknowable. Only an
+ * injected executor with no kubeConfig at all has no identity to record.
+ */
+function resolveTransport(props) {
+    const kubeConfig = props.executor && !props.kubeConfig
+        ? undefined
+        : createKubernetesClientProvider(props.kubeConfig ? materializeSerializableKubeConfigOptions(props.kubeConfig) : undefined).getKubeConfig();
+    return {
+        executor: props.executor ?? new KubeExecClickHouseExecutor(kubeConfig),
+        clusterId: kubeConfig ? clusterIdentity(kubeConfig) : undefined,
+    };
+}
+/**
+ * The provider `Layer` backing {@link ClickHouseSchema}. Merge it into the alchemy
+ * runtime's providers alongside `kroProvider`.
+ */
+export const clickHouseSchemaProvider = ProviderMod.effect(ClickHouseSchema, Effect.succeed({
+    // A schema is applied IN PLACE. Nothing about it is identity-stable: re-pointing the
+    // resource at another server must re-apply the DDL there, never delete it here.
+    stables: [],
+    // Not discoverable cluster-wide: a schema leaves no object carrying this resource's
+    // identity, so there is nothing for `alchemy nuke` to enumerate. Same stance as
+    // `kroProvider`.
+    list: () => Effect.succeed([]),
+    // `id` is the author's own name for THIS schema — the thing that distinguishes
+    // `orders-schema` from `billing-schema` in an error. The provider TYPE is the same
+    // constant for every instance and says nothing, which is why it is not used here.
+    reconcile: Effect.fn(function* ({ id, news, output }) {
+        return yield* Effect.tryPromise({
+            try: async (abortSignal) => {
+                const logger = getComponentLogger('alchemy-clickhouse-schema');
+                const { executor, clusterId } = resolveTransport(news);
+                if (!needsApply(news, output, clusterId)) {
+                    logger.debug('ClickHouse schema unchanged; verifying the server set', {
+                        resourceId: id,
+                        fingerprint: output?.fingerprint,
+                        statementCount: news.statements.length,
+                        clusterId,
+                    });
+                }
+                else {
+                    logger.info('Applying ClickHouse schema', {
+                        resourceId: id,
+                        namespace: news.target.namespace,
+                        statementCount: news.statements.length,
+                        fingerprint: computeFingerprint(news),
+                        executionMode: news.execution.mode,
+                        clusterId,
+                    });
+                }
+                return await applyClickHouseSchema({ executor, config: news, resourceId: id, clusterId, abortSignal }, output);
+            },
+            catch: ensureError,
+        });
+    }),
+    delete: Effect.fn(function* ({ id, olds }) {
+        // `retain` (the default) must not even reach the cluster, so the missing-spec case
+        // below is a no-op rather than a guess: reconstructing an unknown `onDelete` from
+        // persisted output could only ever guess `retain`, which is what happens anyway.
+        if (!olds || olds.onDelete !== 'run')
+            return;
+        yield* Effect.tryPromise({
+            try: (abortSignal) => {
+                const { executor, clusterId } = resolveTransport(olds);
+                return deleteClickHouseSchema({
+                    executor,
+                    config: olds,
+                    resourceId: id,
+                    clusterId,
+                    abortSignal,
+                });
+            },
+            catch: ensureError,
+        });
+    }),
+}));
+/**
+ * Declare a ClickHouse schema, validating its configuration first.
+ *
+ * ```ts
+ * const schema = yield* clickHouseSchema('orders-schema', {
+ *   target: { namespace: 'telemetry', podSelector: { 'clickhouse.altinity.com/chi': 'orders' } },
+ *   statements: [
+ *     'CREATE DATABASE IF NOT EXISTS orders',
+ *     'CREATE TABLE IF NOT EXISTS orders.events (id UUID, at DateTime) ENGINE = MergeTree ORDER BY at',
+ *   ],
+ * });
+ * ```
+ *
+ * @param id - Stable alchemy resource id
+ * @param props - Validated against {@link ClickHouseSchemaConfigSchema}
+ * @throws ValidationError when the configuration is invalid
+ */
+export function clickHouseSchema(id, props) {
+    // `kubeConfig`/`executor` are not part of the ArkType schema (see `types.ts`), so they
+    // are split off before validation and re-attached to the validated config afterwards.
+    const { kubeConfig, executor, readyBarrier, ...configurable } = props;
+    const validated = ClickHouseSchemaConfigSchema(configurable);
+    if (validated instanceof type.errors) {
+        throw new ValidationError(`Invalid ClickHouseSchema configuration for '${id}': ${validated.summary}`, 'ClickHouseSchema', id);
+    }
+    return ClickHouseSchema(id, {
+        ...validated,
+        ...(kubeConfig ? { kubeConfig } : {}),
+        ...(executor ? { executor } : {}),
+        // Passed through unvalidated and unresolved: this is an alchemy `Output` at
+        // declaration time, and alchemy resolves it before reconcile.
+        ...(readyBarrier !== undefined ? { readyBarrier } : {}),
+    });
+}
+//# sourceMappingURL=resource.js.map

package/dist/alchemy/clickhouse-schema/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/resource.ts"],"names":[],"mappings":"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"}

package/dist/alchemy/clickhouse-schema/runner.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Convergence logic for the `ClickHouseSchema` alchemy resource: fingerprinting,
+ * `clickhouse-client` command rendering, Ready-pod selection and statement execution.
+ *
+ * Kept free of alchemy and of `@kubernetes/client-node` so it can be exercised whole
+ * against an injected {@link ClickHouseExecutor}.
+ */
+import { type ClickHouseExecutor, type ClickHousePodSummary, type ClickHouseSchemaConfig, type ClickHouseSchemaState } from './types.js';
+/** The Altinity CHI server container name (see `clickHouseInstallation`'s pod template). */
+export declare const DEFAULT_CLICKHOUSE_CONTAINER = "clickhouse";
+/** ClickHouse's native protocol port, which `clickhouse-client` speaks. */
+export declare const DEFAULT_CLICKHOUSE_PORT = 9000;
+export declare const DEFAULT_CLICKHOUSE_USER = "default";
+export declare const DEFAULT_CLICKHOUSE_DATABASE = "default";
+/**
+ * Default environment variable read for the password INSIDE the container.
+ *
+ * This is the convention every in-repo ClickHouse workload already uses: the ClickStack
+ * retention CronJob reads `CLICKHOUSE_PASSWORD`, and `clickHouseS3BackupCronJob` sets
+ * that same variable from the credentials Secret. `clickhouse-client` also honours
+ * `CLICKHOUSE_PASSWORD` natively, but this resource does NOT depend on that: it passes
+ * `--password "${VAR:-}"` explicitly through `sh -c`, which behaves identically for a
+ * custom `passwordEnv` and on images whose client build predates the native support.
+ */
+export declare const DEFAULT_CLICKHOUSE_PASSWORD_ENV = "CLICKHOUSE_PASSWORD";
+export declare const DEFAULT_WAIT_FOR_POD_TIMEOUT_MS = 120000;
+export declare const DEFAULT_STATEMENT_TIMEOUT_MS = 300000;
+export declare const DEFAULT_MAX_ATTEMPTS = 3;
+export declare const DEFAULT_BACKOFF_MS = 1000;
+/**
+ * How many times a `fanout` apply re-lists and applies to newly appeared pods before it
+ * gives up and fails. Three covers the ordinary races — a scale-out or a replacement
+ * landing mid-apply — without letting a cluster that is genuinely churning stretch one
+ * converge indefinitely.
+ */
+export declare const DEFAULT_MAX_RECONCILE_PASSES = 3;
+/** Injected clock and sleep, so the wait/timeout and backoff paths are testable. */
+export interface ClickHouseSchemaRuntimeDeps {
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+}
+export declare const defaultRuntimeDeps: ClickHouseSchemaRuntimeDeps;
+export declare function resolveDatabase(config: ClickHouseSchemaConfig): string;
+export declare function resolveContainer(config: ClickHouseSchemaConfig): string;
+/**
+ * The `sh -c` command run inside the server container.
+ *
+ * The password is expanded from the container's OWN environment (`"${VAR:-}"`, a POSIX
+ * default expansion so an unset variable means the empty password the stock Altinity
+ * `default` user has) and is therefore never in props, never in alchemy state, never in
+ * this process's memory, and never echoed. `exec` replaces the shell so the client is
+ * the container's direct child and receives the statement on stdin unbuffered.
+ *
+ * `--host 127.0.0.1`: the exec already landed inside a server pod, so the connection
+ * never leaves it. There is no port-forward and no network path from the runner.
+ */
+export declare function renderClickHouseCommand(config: ClickHouseSchemaConfig): readonly string[];
+/**
+ * sha256 over the ordered statements, the settings, the client configuration and the
+ * execution model.
+ *
+ * The TARGET is deliberately NOT part of the fingerprint — it describes where to reach
+ * the server, not what is applied — so {@link needsApply} compares it separately and a
+ * re-pointed resource re-applies even though its DDL is byte-identical.
+ *
+ * The EXECUTION MODEL is part of it, because switching from `onCluster` to `fanout`
+ * changes which servers the identical statements reached, and that is a change to what is
+ * applied even though the SQL is untouched.
+ */
+export declare function computeFingerprint(config: ClickHouseSchemaConfig): string;
+/**
+ * Everything one converge needs, in one place.
+ *
+ * An options object rather than a parameter list: the execution model gives the runner
+ * several independent knobs, and `clusterId` is not derivable here at all — the runner is
+ * deliberately free of `@kubernetes/client-node`, so the identity of the cluster it is
+ * talking to has to arrive from the provider that built the transport.
+ */
+export interface ClickHouseSchemaRunContext {
+    readonly executor: ClickHouseExecutor;
+    readonly config: ClickHouseSchemaConfig;
+    /** The alchemy resource `id` — what every error and log line is attributed to. */
+    readonly resourceId: string;
+    /** Credential-free cluster identity; see {@link ClickHouseSchemaState.clusterId}. */
+    readonly clusterId?: string | undefined;
+    readonly deps?: ClickHouseSchemaRuntimeDeps | undefined;
+    readonly abortSignal?: AbortSignal | undefined;
+}
+/**
+ * Whether a converge must (re-)run the statements against this target.
+ *
+ * Three things are compared, and the third is the one that is easy to forget: the
+ * fingerprint (what is applied), the target strings (where, within a cluster), and the
+ * CLUSTER ITSELF. Namespace, selector and container are just strings — `telemetry` +
+ * `chi=orders` names a pod in staging exactly as well as it names one in production — so
+ * without the cluster identity, re-pointing a resource at a second cluster matches the
+ * recorded target, matches the fingerprint, and silently applies nothing there.
+ *
+ * The live pod SET is deliberately not compared here: it needs an API call, so
+ * {@link applyClickHouseSchema} checks it separately and only under `fanout`, by NAME AND
+ * UID ({@link samePodIdentitySet}) so a same-name replacement is not invisible.
+ */
+export declare function needsApply(config: ClickHouseSchemaConfig, previous: ClickHouseSchemaState | undefined, clusterId?: string): boolean;
+/**
+ * Poll until the server pods the execution model needs are Ready, or the budget runs out.
+ *
+ * A ClickHouse server accepts connections only once it is Ready, and a CHI rollout has a
+ * window where pods exist but are still replaying logs — exec'ing then produces a
+ * connection-refused that looks like a SQL failure. Waiting for readiness first is what
+ * makes "ordered after the instance is ready" true in practice as well as in the
+ * dependency graph.
+ *
+ * WHICH pods have to be Ready is the execution model's whole difference: `fanout` reaches
+ * every server itself and so needs all of them ({@link selectFanoutPods}); `onCluster`
+ * hands the statements to Keeper and so needs exactly one ({@link selectInitiatorPod}).
+ */
+export declare function selectExecutionPods(context: ClickHouseSchemaRunContext): Promise<readonly ClickHousePodSummary[]>;
+/**
+ * Run an ordered statement list against every selected pod, stopping at the first failure.
+ *
+ * Per POD, not per statement: each server receives the whole list in order, because the
+ * order is what makes the list meaningful (a table cannot be created before its database)
+ * and interleaving across pods would only make a partial failure harder to read.
+ */
+export declare function runStatements(context: ClickHouseSchemaRunContext, statements: readonly string[]): Promise<{
+    readonly podNames: readonly string[];
+    readonly pods: readonly ClickHousePodSummary[];
+}>;
+/**
+ * Converge the schema: no-op when nothing changed, otherwise re-run EVERY statement.
+ *
+ * There is no partial application. A fingerprint change re-runs the whole ordered list,
+ * which is only correct because every statement is required to be idempotent — and it is
+ * also what makes a failed converge recoverable: the fingerprint is recorded only after
+ * the last statement succeeds, so a run that dies at statement 7 re-runs 0..6 next time.
+ *
+ * Under `fanout` the POD SET is part of what "nothing changed" means, and the set is
+ * compared by NAME AND UID. A statement list applied to two replicas is not applied to the
+ * third one that a scale-out added, nor to the replacement a drain put back under the same
+ * name with an empty disk, and the fingerprint cannot see either — so an otherwise-unchanged
+ * converge still lists pods and re-applies when the set moved. That listing is one API call
+ * and no exec, so an unchanged, unchanged-topology converge stays free. When it does apply,
+ * it applies until the live set is COVERED; see {@link applyFanoutUntilCovered}.
+ *
+ * `onCluster` has no coverage to reconcile: one execution hands the DDL to Keeper's queue,
+ * which reaches the pods this converge never looked at, including ones that appear later.
+ */
+export declare function applyClickHouseSchema(context: ClickHouseSchemaRunContext, previous: ClickHouseSchemaState | undefined): Promise<ClickHouseSchemaState>;
+/**
+ * Teardown. `retain` touches nothing at all — not even the cluster — so a destroyed
+ * stack leaves the data and the schema exactly as they were.
+ */
+export declare function deleteClickHouseSchema(context: ClickHouseSchemaRunContext): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/alchemy/clickhouse-schema/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/alchemy/clickhouse-schema/runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAEzB,KAAK,sBAAsB,EAE3B,KAAK,qBAAqB,EAI3B,MAAM,YAAY,CAAC;AAEpB,4FAA4F;AAC5F,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,eAAO,MAAM,uBAAuB,YAAY,CAAC;AACjD,eAAO,MAAM,2BAA2B,YAAY,CAAC;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,wBAAwB,CAAC;AAErE,eAAO,MAAM,+BAA+B,SAAU,CAAC;AACvD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AACpD,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAG9C,oFAAoF;AACpF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,eAAO,MAAM,kBAAkB,EAAE,2BAMhC,CAAC;AAOF,wBAAgB,eAAe,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAEtE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,MAAM,EAAE,CAkBzF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAezE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAChD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,qBAAqB,GAAG,SAAS,EAC3C,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAgBT;AA+MD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAI1C;AA2ED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,0BAA0B,EACnC,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC;IACT,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAChD,CAAC,CAMD;AA4MD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,0BAA0B,EACnC,QAAQ,EAAE,qBAAqB,GAAG,SAAS,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CAyBhC;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/F"}