@rc312/effect-snowflake 0.0.0-stage → 0.1.0

package/src/internal/configuration.ts

@@ -0,0 +1,63 @@
+import type { ConnectOptions } from "@apache-arrow/adbc-driver-manager";
+import { Redacted } from "effect";
+
+import type { SnowflakeOptions } from "../models.ts";
+
+export const configuration = (options: SnowflakeOptions): ConnectOptions => {
+  const databaseOptions = Object.fromEntries(
+    Object.entries(options.databaseOptions ?? {}).map(([key, value]) => [
+      key,
+      Redacted.value(value),
+    ])
+  );
+
+  const values = [
+    ["adbc.snowflake.sql.account", options.account],
+    ["username", options.username],
+    ["adbc.snowflake.sql.db", options.database],
+    ["adbc.snowflake.sql.schema", options.schema],
+    ["adbc.snowflake.sql.warehouse", options.warehouse],
+    ["adbc.snowflake.sql.role", options.role],
+    ["adbc.snowflake.sql.auth_type", options.authenticator],
+    [
+      "adbc.snowflake.sql.client_option.jwt_private_key",
+      options.privateKeyPath,
+    ],
+  ] as const;
+
+  for (const [key, value] of values) {
+    if (value !== undefined) {
+      databaseOptions[key] = value;
+    }
+  }
+
+  const secrets = [
+    ["password", options.password],
+    ["adbc.snowflake.sql.client_option.auth_token", options.token],
+    [
+      "adbc.snowflake.sql.client_option.jwt_private_key_pkcs8_value",
+      options.privateKey,
+    ],
+    [
+      "adbc.snowflake.sql.client_option.jwt_private_key_pkcs8_password",
+      options.privateKeyPass,
+    ],
+  ] as const;
+
+  for (const [key, value] of secrets) {
+    if (value !== undefined) {
+      databaseOptions[key] = Redacted.value(value);
+    }
+  }
+
+  const config: ConnectOptions = {
+    databaseOptions,
+    driver: options.driver ?? "snowflake",
+  };
+
+  if (options.manifestSearchPaths !== undefined) {
+    config.manifestSearchPaths = [...options.manifestSearchPaths];
+  }
+
+  return config;
+};

package/src/internal/connection.ts

@@ -0,0 +1,83 @@
+import type { Scope } from "effect";
+import { Effect, flow } from "effect";
+
+import { AdbcDriver } from "../adbc-driver.ts";
+import type { Connection as NativeConnection } from "../adbc-driver.ts";
+import type { SnowflakeOptions } from "../models.ts";
+import { failure } from "../snowflake-error.ts";
+import type { SnowflakeError } from "../snowflake-error.ts";
+import { configuration } from "./configuration.ts";
+import { asCleanup } from "./lifecycle.ts";
+import { call } from "./native.ts";
+
+/** One native connection and the lifetime shared by all of its sessions. */
+export interface Connection {
+  readonly native: NativeConnection;
+  readonly owner: Scope.Scope;
+  readonly isOpen: () => boolean;
+  readonly isHealthy: () => boolean;
+  readonly cleanup: <A>(
+    operation: string,
+    run: () => Promise<A>
+  ) => Effect.Effect<A>;
+  readonly setAutoCommit: (
+    enabled: boolean
+  ) => Effect.Effect<void, SnowflakeError>;
+}
+
+/** Called inside the client's private sequential scope. Dependencies are captured once. */
+export const make = Effect.fnUntraced(function* acquireConnection(
+  options: SnowflakeOptions
+) {
+  const driver = yield* AdbcDriver;
+  const owner = yield* Effect.scope;
+
+  const config = yield* Effect.try({
+    catch: failure("options"),
+    try: () => configuration(options),
+  });
+
+  let open = true;
+  let healthy = true;
+
+  const invalidate = Effect.sync(() => {
+    healthy = false;
+  });
+
+  const finalize = flow(
+    Effect.tapError(() => invalidate),
+    asCleanup
+  );
+
+  const cleanup: Connection["cleanup"] = (operation, run) =>
+    call(operation, run).pipe(finalize);
+
+  const database = yield* Effect.acquireRelease(
+    driver.open(config),
+    (resource) => cleanup("database.close", () => resource.close())
+  );
+
+  const native = yield* Effect.acquireRelease(
+    call("connect", () => database.connect()),
+    (resource) => cleanup("connection.close", () => resource.close())
+  );
+
+  yield* Effect.addFinalizer(() =>
+    Effect.sync(() => {
+      open = false;
+    })
+  );
+
+  return {
+    cleanup,
+    isHealthy: () => healthy,
+    isOpen: () => open && healthy,
+    native,
+    owner,
+    setAutoCommit: (enabled: boolean) =>
+      Effect.try({
+        catch: failure("transaction.autocommit"),
+        try: () => native.setAutoCommit(enabled),
+      }).pipe(Effect.tapError(() => invalidate)),
+  } satisfies Connection;
+});

package/src/internal/lifecycle.ts

@@ -0,0 +1,186 @@
+import type { RecordBatch } from "apache-arrow";
+import { Cause, Effect, Exit, Fiber, Scope, Stream } from "effect";
+
+import { failure } from "../snowflake-error.ts";
+import type { SnowflakeError } from "../snowflake-error.ts";
+
+const cleanupReason = <E>(reason: Cause.Reason<E>): Cause.Reason<never> =>
+  Cause.isFailReason(reason)
+    ? Cause.makeDieReason(reason.error).annotate(
+        Cause.reasonAnnotations(reason)
+      )
+    : reason;
+
+const cleanupCause = <E>(cause: Cause.Cause<E>) =>
+  Cause.fromReasons<never>(cause.reasons.map(cleanupReason));
+
+export const asCleanup = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  Effect.catchCause(effect, (cause) => Effect.failCause(cleanupCause(cause)));
+
+const cleanupExit = <A, E>(exit: Exit.Exit<A, E>) => {
+  if (Exit.isFailure(exit)) {
+    const reasons = exit.cause.reasons.filter(
+      (reason) => !Cause.isInterruptReason(reason)
+    );
+
+    if (reasons.length > 0) {
+      return Effect.failCause(Cause.fromReasons(reasons)).pipe(asCleanup);
+    }
+  }
+
+  return Effect.void;
+};
+
+const observeCleanup = <A, E>(fiber: Fiber.Fiber<A, E>) =>
+  Fiber.await(fiber).pipe(Effect.flatMap(cleanupExit));
+
+const stopOperation = Effect.fnUntraced(function* stopOwnedOperation<A, E>(
+  fiber: Fiber.Fiber<A, E>
+) {
+  if (fiber.pollUnsafe() !== undefined) {
+    return;
+  }
+
+  yield* Fiber.interrupt(fiber);
+  yield* observeCleanup(fiber);
+});
+
+interface Operation<A, E> {
+  readonly fiber: Fiber.Fiber<A, E>;
+  readonly lifetime: Scope.Closeable;
+  readonly stop: Effect.Effect<void>;
+}
+
+const acquireOperation = Effect.fnUntraced(function* acquireOwnedOperation<
+  A,
+  E,
+  R,
+>(effect: Effect.Effect<A, E, R>, scope: Scope.Scope) {
+  const lifetime = yield* Scope.fork(scope, "sequential");
+  const fiber = yield* Effect.forkIn(Effect.interruptible(effect), lifetime);
+  // forkIn joins on closure but discards the exit; observe cleanup failures too.
+  const stop = yield* stopOperation(fiber).pipe(Effect.cached);
+  yield* Scope.addFinalizer(lifetime, stop);
+
+  return { fiber, lifetime, stop } satisfies Operation<A, E>;
+});
+
+const releaseOperation = <A, E>(
+  { fiber, lifetime, stop }: Operation<A, E>,
+  exit: Exit.Exit<A, E>
+) =>
+  stop.pipe(
+    Effect.andThen(
+      Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)
+        ? observeCleanup(fiber)
+        : Effect.void
+    ),
+    Effect.ensuring(Scope.close(lifetime, exit))
+  );
+
+// Each operation belongs to both its caller and its client/session Scope. Closing
+// either interrupts AND joins it before the ADBC connection can be destroyed.
+export const owned = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  scope: Scope.Scope,
+  isOpen: () => boolean
+): Effect.Effect<A, E | SnowflakeError, R> =>
+  Effect.suspend<A, E | SnowflakeError, R>(() =>
+    isOpen()
+      ? Effect.acquireUseRelease(
+          acquireOperation(effect, scope),
+          ({ fiber }) => Fiber.join(fiber),
+          releaseOperation
+        )
+      : Effect.fail(failure("closed")())
+  );
+
+// Finalizers and concurrent callers must join the same teardown. Scope.close
+// marks a scope closed before its finalizers settle, so it cannot provide this
+// join by itself. Keep the parent registration attached until teardown finishes.
+const makeLifetime = Effect.fnUntraced(function* makeOwnedLifetime(
+  owner: Scope.Scope
+) {
+  const registration = yield* Scope.fork(owner, "sequential");
+  const scope = yield* Scope.make("sequential");
+  // Native resources must finalize after any fiber that can acquire or use them.
+  const resources = yield* Scope.fork(scope, "sequential");
+  let firstExit: Exit.Exit<unknown, unknown> | undefined;
+  let retired = false;
+  let open = true;
+
+  const retire = Effect.suspend(() => {
+    retired = true;
+
+    return Scope.close(registration, firstExit ?? Exit.void);
+  });
+
+  const teardown = yield* Effect.suspend(() => {
+    open = false;
+
+    return Scope.close(scope, firstExit ?? Exit.void);
+  }).pipe(Effect.ensuring(retire), Effect.uninterruptible, Effect.cached);
+
+  const close = (exit: Exit.Exit<unknown, unknown>) =>
+    Effect.suspend(() => {
+      firstExit ??= exit;
+
+      return teardown;
+    });
+
+  yield* Scope.addFinalizerExit(registration, (exit) =>
+    retired ? Effect.void : close(exit)
+  );
+
+  return { close, isOpen: () => open, resources, scope };
+});
+
+const acquireOwnedStream = Effect.fnUntraced(function* acquireStreamLifetime(
+  stream: Stream.Stream<RecordBatch, SnowflakeError>,
+  owner: Scope.Scope,
+  isOpen: () => boolean
+) {
+  if (!isOpen()) {
+    return yield* failure("closed")();
+  }
+
+  const lifetime = yield* Effect.acquireRelease(
+    makeLifetime(owner),
+    (resource, exit) => resource.close(exit)
+  );
+
+  const active = () => lifetime.isOpen() && isOpen();
+
+  const pull = yield* owned(
+    Stream.toPull(stream).pipe(Scope.provide(lifetime.resources)),
+    lifetime.scope,
+    active
+  );
+
+  return Stream.fromPull(Effect.succeed(owned(pull, lifetime.scope, active)));
+});
+
+export const ownedStream = (
+  stream: Stream.Stream<RecordBatch, SnowflakeError>,
+  owner: Scope.Scope,
+  isOpen: () => boolean
+) => Stream.unwrap(acquireOwnedStream(stream, owner, isOpen));
+
+/** Join interrupted acquisition before releasing its late native resources. */
+export const acquireOwner = Effect.fnUntraced(function* acquireClientOwner<
+  A,
+  E,
+  R,
+>(self: Effect.Effect<A, E, R>) {
+  return yield* Effect.acquireUseRelease(
+    makeLifetime(yield* Effect.scope),
+    (lifetime) =>
+      owned(
+        self.pipe(Scope.provide(lifetime.resources)),
+        lifetime.scope,
+        lifetime.isOpen
+      ),
+    (lifetime, exit) =>
+      Exit.isFailure(exit) ? lifetime.close(exit) : Effect.void
+  );
+});

package/src/internal/native.ts

@@ -0,0 +1,9 @@
+import { Effect } from "effect";
+
+import { failure } from "../snowflake-error.ts";
+
+/** ADBC JS cannot cancel promises; settle before releasing or reusing resources. */
+export const call = <A>(operation: string, run: () => Promise<A>) =>
+  Effect.tryPromise({ catch: failure(operation), try: run }).pipe(
+    Effect.uninterruptible
+  );

package/src/internal/session.ts

@@ -0,0 +1,111 @@
+import { Table } from "apache-arrow";
+import type { RecordBatch } from "apache-arrow";
+import { Cause, Effect, flow, pipe, Stream } from "effect";
+import type { Scope, Semaphore } from "effect";
+
+import type { Statement } from "../adbc-driver.ts";
+import type { SnowflakeSession } from "../models.ts";
+import { failure } from "../snowflake-error.ts";
+import type { Connection } from "./connection.ts";
+import { owned, ownedStream } from "./lifecycle.ts";
+import { call } from "./native.ts";
+
+type Reader = Awaited<ReturnType<Statement["executeQuery"]>>;
+
+const executeStatement = (statement: Statement) =>
+  call("execute", () => statement.executeUpdate());
+
+const collectBatches = (source: Reader) =>
+  call("query.read", async () => {
+    await source.open();
+    const { schema } = source;
+    const batches: RecordBatch[] = [];
+
+    for await (const batch of source) {
+      batches.push(batch);
+    }
+
+    return new Table(schema, batches);
+  });
+
+// fromAsyncIterable installs an unsanitized iterator.return finalizer. The scoped
+// reader.cancel owns cleanup; this pull only reads on downstream demand.
+const streamBatches = (source: Reader) =>
+  pipe(
+    call("stream.read", () => Promise.resolve(source.next())),
+    Effect.flatMap((result) =>
+      result.done ? Cause.done() : Effect.succeed([result.value] as const)
+    ),
+    Effect.succeed,
+    Stream.fromPull
+  );
+
+/** Build session operations over a captured connection, permit, and owning scope. */
+export const make = (
+  connection: Connection,
+  owner: Scope.Scope,
+  mutex: Semaphore.Semaphore,
+  active: () => boolean
+): SnowflakeSession => {
+  const statement = Effect.fnUntraced(function* acquireStatement(
+    sql: string,
+    parameters?: Table
+  ) {
+    if (!active()) {
+      return yield* failure("closed")();
+    }
+
+    const resource = yield* Effect.acquireRelease(
+      call("statement.create", () => connection.native.createStatement()),
+      (value) => connection.cleanup("statement.close", () => value.close())
+    );
+
+    yield* call("statement.sql", () => resource.setSqlQuery(sql));
+
+    if (parameters !== undefined) {
+      yield* call("statement.bind", () => resource.bind(parameters));
+    }
+
+    return resource;
+  });
+
+  const reader = Effect.fnUntraced(function* acquireReader(
+    sql: string,
+    parameters?: Table
+  ) {
+    const resource = yield* statement(sql, parameters);
+
+    return yield* Effect.acquireRelease(
+      call("query", () => resource.executeQuery()),
+      (value) =>
+        connection.cleanup("reader.close", async () => {
+          await value.cancel();
+        })
+    );
+  });
+
+  const run = <A, E, R>(effect: Effect.Effect<A, E, R | Scope.Scope>) =>
+    pipe(effect, Effect.scoped, mutex.withPermit, (self) =>
+      owned(self, owner, active)
+    );
+
+  const permit = Effect.acquireRelease(mutex.take(1), () => mutex.release(1));
+
+  return {
+    execute: Effect.fn("Snowflake.execute")(
+      flow(statement, Effect.flatMap(executeStatement), run)
+    ),
+    query: Effect.fn("Snowflake.query")(
+      flow(reader, Effect.flatMap(collectBatches), run)
+    ),
+    stream: (sql, parameters) =>
+      pipe(
+        permit,
+        Effect.andThen(reader(sql, parameters)),
+        Effect.map(streamBatches),
+        Stream.unwrap,
+        (self) => ownedStream(self, owner, active),
+        Stream.withSpan("Snowflake.stream")
+      ),
+  };
+};

package/src/internal/transaction.ts

@@ -0,0 +1,88 @@
+import { Effect, Exit, Semaphore } from "effect";
+
+import type { SnowflakeClient, SnowflakeSession } from "../models.ts";
+import { failure } from "../snowflake-error.ts";
+import type { Connection } from "./connection.ts";
+import { asCleanup, owned } from "./lifecycle.ts";
+import { call } from "./native.ts";
+import * as Session from "./session.ts";
+
+/** The callback owns its session; closing its scope expires escaped operations. */
+const acquireSession = Effect.fnUntraced(function* acquireTransactionSession(
+  connection: Connection
+) {
+  let active = true;
+  const owner = yield* Effect.scope;
+  yield* Effect.addFinalizer(() =>
+    Effect.sync(() => {
+      active = false;
+    })
+  );
+  const lock = yield* Semaphore.make(1);
+
+  return Session.make(
+    connection,
+    owner,
+    lock,
+    () => active && connection.isOpen()
+  );
+});
+
+/** Serialize the whole transaction and finish native finalization before interruption. */
+export const make = (
+  connection: Connection,
+  mutex: Semaphore.Semaphore
+): SnowflakeClient["transaction"] => {
+  const begin = Effect.suspend(() =>
+    connection.isOpen()
+      ? connection.setAutoCommit(false)
+      : Effect.fail(failure("closed")())
+  );
+
+  const commit = Effect.suspend(() =>
+    connection.isHealthy()
+      ? call("transaction.commit", () => connection.native.commit())
+      : Effect.fail(failure("transaction.invalidated")())
+  );
+
+  const rollback = connection.cleanup("transaction.rollback", () =>
+    connection.native.rollback()
+  );
+
+  const restoreAutoCommit = Effect.suspend(() =>
+    connection.isHealthy()
+      ? connection.setAutoCommit(true).pipe(asCleanup)
+      : Effect.void
+  );
+
+  const rollbackOnFailure = (exit: Exit.Exit<unknown, unknown>) =>
+    Exit.isFailure(exit) ? rollback : Effect.void;
+
+  const complete = <A, E, R>(self: Effect.Effect<A, E, R>) =>
+    self.pipe(
+      Effect.tap(() => commit),
+      Effect.onExit((exit) => rollbackOnFailure(exit)),
+      Effect.ensuring(restoreAutoCommit)
+    );
+
+  const runBody = <A, E, R>(
+    use: (session: SnowflakeSession) => Effect.Effect<A, E, R>
+  ) => acquireSession(connection).pipe(Effect.flatMap(use), Effect.scoped);
+
+  const transact = <A, E, R>(
+    use: (session: SnowflakeSession) => Effect.Effect<A, E, R>
+  ) =>
+    Effect.uninterruptibleMask((restore) => {
+      // Only the callback is interruptible; its scope closes before commit.
+      const body = restore(runBody(use));
+
+      return begin.pipe(Effect.andThen(complete(body)));
+    });
+
+  return Effect.fn("Snowflake.transaction")(
+    <A, E, R>(use: (session: SnowflakeSession) => Effect.Effect<A, E, R>) =>
+      transact(use).pipe(mutex.withPermit, (self) =>
+        owned(self, connection.owner, connection.isOpen)
+      )
+  );
+};

package/src/models.ts

@@ -0,0 +1,126 @@
+import type { RecordBatch, Table } from "apache-arrow";
+import type { Effect, Redacted, Stream } from "effect";
+
+import type { SnowflakeError } from "./snowflake-error.ts";
+
+/**
+ * Snowflake ADBC connection settings. Named fields override `databaseOptions`.
+ * Credentials are revealed only while constructing the native database options.
+ * @since 0.1.0
+ */
+export interface SnowflakeOptions {
+  /** Snowflake account identifier, for example `myorg-myaccount`. */
+  readonly account: string;
+  /** Login user. Some native authentication methods obtain identity elsewhere. */
+  readonly username?: string;
+  /** Login password, wrapped in `Redacted`. */
+  readonly password?: Redacted.Redacted<string>;
+  /** Default database for unqualified SQL names. */
+  readonly database?: string;
+  /** Default schema within the selected database. */
+  readonly schema?: string;
+  /** Compute warehouse used to execute queries. */
+  readonly warehouse?: string;
+  /** Snowflake role to activate for the session. */
+  readonly role?: string;
+  /** ADBC authentication name; the driver defaults to `auth_snowflake`. These differ from SDK authenticator names. */
+  readonly authenticator?:
+    | "auth_snowflake"
+    | "auth_oauth"
+    | "auth_ext_browser"
+    | "auth_okta"
+    | "auth_jwt"
+    | "auth_mfa"
+    | "auth_pat"
+    | "auth_wif";
+  /** Redacted authentication token, passed as the native `auth_token` option. */
+  readonly token?: Redacted.Redacted<string>;
+  /** Redacted inline PKCS#8 PEM used with `auth_jwt`. */
+  readonly privateKey?: Redacted.Redacted<string>;
+  /** Redacted passphrase for an encrypted inline PKCS#8 PEM. */
+  readonly privateKeyPass?: Redacted.Redacted<string>;
+  /** Path to a native-driver-supported private-key file; not inline PEM. */
+  readonly privateKeyPath?: string;
+  /** Driver name or absolute library/manifest path. Defaults to snowflake. */
+  readonly driver?: string;
+  /** Additional driver manifest directories, searched before standard locations. */
+  readonly manifestSearchPaths?: readonly string[];
+  /** Advanced native options. Redact every value, including connection URIs. */
+  readonly databaseOptions?: Readonly<
+    Record<string, Redacted.Redacted<string>>
+  >;
+}
+
+/**
+ * Serialized operations on a single connection. A transaction session expires
+ * when its callback exits. Fully consume a stream before reusing that session.
+ * @since 0.1.0
+ */
+export interface SnowflakeSession {
+  /**
+   * Collect a result into an Arrow table, preserving its schema for empty results.
+   * @param sql Trusted SQL text with `?` placeholders; values are never interpolated.
+   * @param parameters Arrow columns in placeholder order, normally one parameter row.
+   * @returns A lazy Effect that owns a fresh statement and reader until collection ends.
+   * Native errors become `SnowflakeError`; cleanup failures remain defects.
+   */
+  readonly query: (
+    sql: string,
+    parameters?: Table
+  ) => Effect.Effect<Table, SnowflakeError>;
+  /**
+   * Execute DDL or DML using a fresh, scoped statement.
+   * @param sql Trusted SQL text with optional `?` placeholders.
+   * @param parameters Arrow columns in placeholder order.
+   * @returns The affected row count, or `-1` when the native driver cannot report it.
+   * Snowflake DDL may implicitly commit; execute it outside transaction callbacks.
+   */
+  readonly execute: (
+    sql: string,
+    parameters?: Table
+  ) => Effect.Effect<number, SnowflakeError>;
+  /**
+   * Pull Arrow record batches lazily without collecting the full result.
+   * @param sql Trusted SQL text with optional `?` placeholders.
+   * @param parameters Arrow columns in placeholder order.
+   * @returns A stream that holds the connection until consumption and cleanup finish.
+   * Early termination releases the reader before its statement. In-flight native
+   * reads settle before interruption completes; ADBC JS provides no cancellation.
+   */
+  readonly stream: (
+    sql: string,
+    parameters?: Table
+  ) => Stream.Stream<RecordBatch, SnowflakeError>;
+}
+
+/**
+ * A scoped connection with exclusive transaction callbacks.
+ * @since 0.1.0
+ */
+export interface SnowflakeClient extends SnowflakeSession {
+  /**
+   * Run an Effect inside this client's transaction. Composes with `pipe` and
+   * preserves its success, errors, and environment. Captured repositories and
+   * client methods automatically use the active session on this fiber.
+   */
+  readonly withTransaction: <A, E, R>(
+    self: Effect.Effect<A, E, R>
+  ) => Effect.Effect<A, E | SnowflakeError, R>;
+
+  /**
+   * Disable autocommit, run `use`, and commit its success or roll back its failure.
+   * @param use Callback using the supplied session; await all work before returning.
+   * @returns The callback value, preserving its error and service requirements.
+   * Defects and callback interruption also roll back. Once commit starts, its
+   * outcome and autocommit restoration finish before interruption is accepted;
+   * an interrupted caller may therefore observe an already committed transaction.
+   * Failed commits attempt rollback. Recovered cleanup defects still prevent
+   * commit and fail with operation `transaction.invalidated`.
+   * Failed rollback or autocommit restoration invalidates the client, and cleanup
+   * defects accompany the original failure. Captured client methods resolve the
+   * active transaction session. Nested transactions fail with `transaction.nested`.
+   */
+  readonly transaction: <A, E, R>(
+    use: (session: SnowflakeSession) => Effect.Effect<A, E, R>
+  ) => Effect.Effect<A, E | SnowflakeError, R>;
+}

package/src/snowflake-error.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+
+/**
+ * Sanitized native failure with an operation label and a generic message.
+ * Raw native messages, SQL, bind values, credentials, and original causes are
+ * intentionally excluded. Operation failures use the typed error channel;
+ * cleanup failures are promoted to defects while preserving the original Cause.
+ * @since 0.1.0
+ */
+// oxlint-disable-next-line unicorn/throw-new-error -- Schema.TaggedError is a class factory.
+export class SnowflakeError extends Schema.TaggedError<
+  SnowflakeError,
+  { readonly brand: unique symbol }
+>()("SnowflakeError", { message: Schema.String, operation: Schema.String }) {}
+
+export const failure = (operation: string) => () =>
+  new SnowflakeError({ message: `Snowflake ${operation} failed`, operation });