@gscdump/engine 0.25.14 → 0.26.0

package/dist/_chunks/errors.d.mts

@@ -0,0 +1,117 @@
+type EngineErrorKind = 'analyzer-not-found' | 'analyzer-capability-missing' | 'invalid-sql-literal' | 'placeholder-arity-mismatch' | 'invalid-search-types' | 'attached-table-missing' | 'manifest-cas-exhausted' | 'invalid-snapshot-filename' | 'unsupported-snapshot-index-version' | 'invalid-schema-identifier' | 'invalid-year-month' | 'missing-attach-url' | 'manifest-cas-round-lost' | 'iceberg-table-op-failed' | 'sink-table-flush-failed' | 'rollup-build-failed' | 'lock-acquire-timeout';
+type EngineError = {
+  kind: 'analyzer-not-found';
+  tool: string;
+  message: string;
+} | {
+  kind: 'analyzer-capability-missing';
+  tool: string;
+  missing: readonly string[];
+  message: string;
+} | {
+  kind: 'invalid-sql-literal';
+  message: string;
+} | {
+  kind: 'placeholder-arity-mismatch';
+  message: string;
+} | {
+  kind: 'invalid-search-types';
+  message: string;
+  cause?: unknown;
+} | {
+  kind: 'attached-table-missing';
+  missing: readonly string[];
+  message: string;
+} | {
+  kind: 'manifest-cas-exhausted';
+  message: string;
+  siteId: string;
+  table: string;
+  attempts: number;
+} | {
+  kind: 'invalid-snapshot-filename';
+  message: string;
+  fileName: string;
+} | {
+  kind: 'unsupported-snapshot-index-version';
+  message: string;
+  version: unknown;
+} | {
+  kind: 'invalid-schema-identifier';
+  message: string;
+  schema: string;
+} | {
+  kind: 'invalid-year-month';
+  message: string;
+  value: string;
+} | {
+  kind: 'missing-attach-url';
+  message: string;
+  fileName: string;
+} | {
+  kind: 'manifest-cas-round-lost';
+  message: string;
+  siteId: string;
+  table: string;
+  attempt: number;
+} | {
+  kind: 'iceberg-table-op-failed';
+  message: string;
+  op: 'create' | 'drop';
+  table: string;
+  cause?: unknown;
+} | {
+  kind: 'sink-table-flush-failed';
+  message: string;
+  table: string;
+  cause?: unknown;
+} | {
+  kind: 'rollup-build-failed';
+  message: string;
+  id: string;
+  cause?: unknown;
+} | {
+  kind: 'lock-acquire-timeout';
+  message: string;
+  scope: string;
+  timeoutMs: number;
+};
+declare const engineErrors: {
+  readonly analyzerNotFound: (tool: string) => EngineError;
+  readonly analyzerCapabilityMissing: (tool: string, missing: readonly string[]) => EngineError;
+  readonly nonFiniteNumberLiteral: (value: number) => EngineError;
+  readonly controlCharsInLiteral: () => EngineError;
+  readonly uninlinableLiteralType: (type: string) => EngineError;
+  readonly morePlaceholdersThanParams: (have: number) => EngineError;
+  readonly dollarPlaceholderOutOfRange: (n: number, have: number) => EngineError;
+  readonly mixedPlaceholderStyles: () => EngineError;
+  readonly unusedParams: (unused: number) => EngineError;
+  readonly searchTypesNotArray: () => EngineError;
+  readonly unknownSearchType: (value: unknown) => EngineError;
+  readonly searchTypesMissingWeb: () => EngineError;
+  readonly attachedTableMissing: (missing: readonly string[]) => EngineError;
+  readonly manifestCasExhausted: (siteId: string, table: string, attempts: number) => EngineError;
+  readonly invalidSnapshotFilename: (fileName: string) => EngineError;
+  readonly unsupportedSnapshotIndexVersion: (version: unknown) => EngineError;
+  readonly invalidSchemaIdentifier: (schema: string) => EngineError;
+  readonly invalidYearMonth: (value: string) => EngineError;
+  readonly missingAttachUrl: (fileName: string) => EngineError;
+  readonly manifestCasRoundLost: (siteId: string, table: string, attempt: number) => EngineError;
+  readonly icebergTableOpFailed: (op: "create" | "drop", table: string, cause: unknown) => EngineError;
+  readonly sinkTableFlushFailed: (table: string, cause: unknown) => EngineError;
+  readonly rollupBuildFailed: (id: string, cause: unknown) => EngineError;
+  readonly lockAcquireTimeout: (scope: string, timeoutMs: number) => EngineError;
+};
+declare function isEngineError(value: unknown): value is EngineError;
+/** The human-readable rendering of an `EngineError`, for logs and string sinks. */
+declare function formatEngineError(error: EngineError): string;
+/**
+ * Re-raises an `EngineError` value as a generic `Error`, stashing the union under
+ * `.engineError` for stack-walking. Used by the throwing wrappers over the
+ * `Result`-returning cores whose original throws were bare `Error`s (the SQL
+ * binder, sync-config). Modules that historically threw a *named* class
+ * (`AnalyzerCapabilityError`, `AttachedTableMissingError`) provide their own
+ * mapper so the class identity callers match on is preserved.
+ */
+declare function engineErrorToException(error: EngineError): Error;
+export { EngineError, EngineErrorKind, engineErrorToException, engineErrors, formatEngineError, isEngineError };

package/dist/_chunks/index.d.mts

@@ -1,4 +1,5 @@
 import { Row, SearchType as SearchType$1, StorageEngine, TenantCtx } from "./storage.mjs";
+import { EngineError } from "./errors.mjs";
 import { AnalysisParams, AnalysisResult } from "./analysis-types.mjs";
 import { ResolverAdapter } from "./types.mjs";
 import { AnalysisQuerySource, AnalysisSourceKind, AnalyzerRegistry, FileSet, QueryRow, SourceCapabilities } from "./registry.mjs";
@@ -39,6 +40,7 @@ interface AttachedTableSourceOptions {
 }
 declare class AttachedTableMissingError extends Error {
   readonly missing: readonly string[];
+  readonly engineError: EngineError;
   constructor(missing: readonly string[]);
 }
 /**

package/dist/_chunks/registry.d.mts

@@ -2,8 +2,8 @@ import { Row as Row$1 } from "./storage.mjs";
 import { AnalysisParams } from "./analysis-types.mjs";
 import { ResolverAdapter } from "./types.mjs";
 import { PlannerCapabilities } from "gscdump/query/plan";
-import { TableName } from "@gscdump/contracts";
 import { BuilderState } from "gscdump/query";
+import { TableName } from "@gscdump/contracts";
 type QueryRow = Record<string, unknown>;
 interface FileSet {
   table: TableName;

package/dist/_chunks/sink.d.mts

@@ -1,4 +1,6 @@
 import { Row as Row$1, SearchType, TenantCtx as TenantCtx$1 } from "./storage.mjs";
+import { EngineError } from "./errors.mjs";
+import { Result } from "gscdump/result";
 import { icebergAppend, restCatalogConnect, s3SignedResolver } from "icebird";
 import { TableName } from "@gscdump/contracts";
 /**
@@ -209,12 +211,16 @@ declare function isCommitRateLimited(err: unknown): boolean;
  * coalescing) is assessed in the Phase-1.5 report.
  */
 declare function icebergAppendRetrying(args: Parameters<typeof icebergAppend>[0], options?: CommitRetryOptions): Promise<void>;
-/** Outcome of a single table create/drop. */
+/**
+ * Outcome of a single table create/drop: the table name plus a `Result` —
+ * `Ok(void)` on success, `Err(iceberg-table-op-failed)` carrying the failure
+ * message (and original `cause`) when the catalog rejects the op (e.g. "table
+ * already exists", a 5xx). Per-table so a partial provisioning run is fully
+ * observable; the human-readable string lives on `error.message`.
+ */
 interface IcebergTableOpResult {
   table: string;
-  ok: boolean;
-  /** Present when `ok` is false. */
-  error?: string;
+  outcome: Result<void, EngineError>;
 }
 /**
  * Ensure the catalog namespace exists. Idempotent — an "already exists"
@@ -229,7 +235,13 @@ declare function ensureIcebergNamespace(conn: IcebergConnection): Promise<void>;
  * as a failed result. Used by the app's one-off provisioning script.
  */
 declare function createIcebergTables(conn: IcebergConnection, tables?: readonly IcebergTableName[]): Promise<IcebergTableOpResult[]>;
-/** List the table names currently in the catalog namespace. */
+/**
+ * List the table names currently in the catalog namespace.
+ *
+ * A genuinely-empty namespace resolves to `[]`. A LIST *failure* (catalog
+ * unreachable, 401/403, 5xx) propagates rather than being masked as an empty
+ * list — callers must be able to tell "no tables" from "couldn't ask".
+ */
 declare function listIcebergTables(conn: IcebergConnection): Promise<string[]>;
 /** A data file in the current snapshot's manifest, scoped to one partition. */
 interface IcebergListedDataFile {
@@ -321,10 +333,14 @@ interface SinkCapabilities {
 interface SinkCloseResult {
   /** Tables whose buffered rows committed durably. */
   flushed: IcebergTableName[];
-  /** Tables whose flush failed — their slices must NOT be ledger-recorded. */
+  /**
+   * Tables whose flush failed — their slices must NOT be ledger-recorded. Each
+   * carries a typed `sink-table-flush-failed` `EngineError`; the human-readable
+   * cause is on `error.message`.
+   */
   failed: {
     table: IcebergTableName;
-    error: string;
+    error: EngineError;
   }[];
 }
 interface Sink {

package/dist/_chunks/source.mjs

@@ -1,4 +1,5 @@
 import "./layout.mjs";
+import { engineErrors } from "../errors.mjs";
 import { assertDimensionsSupported, getFilterDimensions, pgResolverAdapter, resolveToSQL } from "./resolver.mjs";
 import { runAnalyzerFromSource } from "./dispatch.mjs";
 function coerceRow(row) {
@@ -16,10 +17,13 @@ function coerceRows(rows) {
 }
 var AttachedTableMissingError = class extends Error {
 	missing;
+	engineError;
 	constructor(missing) {
-		super(`attached-table source: required table(s) not attached: ${missing.join(", ")}`);
+		const engineError = engineErrors.attachedTableMissing(missing);
+		super(engineError.message);
 		this.missing = missing;
 		this.name = "AttachedTableMissingError";
+		this.engineError = engineError;
 	}
 };
 const ATTACHED_TABLE_CAPABILITIES = {

package/dist/_chunks/storage.d.mts

@@ -1,5 +1,5 @@
-import { Grain, Grain as Grain$1, Row, Row as Row$1, TableName, TableName as TableName$1, TenantCtx, TenantCtx as TenantCtx$1 } from "@gscdump/contracts";
 import { BuilderState, SearchType, SearchType as SearchType$1 } from "gscdump/query";
+import { Grain, Grain as Grain$1, Row, Row as Row$1, TableName, TableName as TableName$1, TenantCtx, TenantCtx as TenantCtx$1 } from "@gscdump/contracts";
 /**
  * Per-tier age threshold in days. Default ladder collapses on these gates:
  * - raw → d7 once a daily file is older than `raw` days (default 7).

package/dist/adapters/filesystem.mjs

@@ -238,7 +238,9 @@ function createFilesystemManifestStore(opts) {
 					factor: 1.5
 				}
 			});
-			return await fn().finally(() => release().catch(() => {}));
+			return await fn().finally(() => release().catch((releaseErr) => {
+				console.warn(`[gscdump/engine] failed to release lock ${path}; it will go stale after 30000ms`, releaseErr);
+			}));
 		},
 		async purgeTenant(filter) {
 			return enqueue(async () => {

package/dist/adapters/node.d.mts

@@ -1,8 +1,10 @@
 import { DataSource, StorageEngine } from "../_chunks/storage.mjs";
 import { NodeDuckDBOptions, createNodeDuckDBHandle, resetNodeDuckDB } from "./duckdb-node.mjs";
+import { EngineError } from "../_chunks/errors.mjs";
 import { SnapshotIndex } from "../_chunks/snapshot.mjs";
-import { Row, TableName } from "@gscdump/contracts";
+import { Result } from "gscdump/result";
 import { SearchType } from "gscdump/query";
+import { Row, TableName } from "@gscdump/contracts";
 interface NodeHarnessOptions {
   dataDir: string;
   /** Tenant user id. Defaults to `'local'` for single-user CLI installs. */
@@ -72,6 +74,14 @@ interface AttachSnapshotResult {
  * `cold_2024_09`. `hot.duckdb` → `hot`.
  */
 declare function snapshotAlias(fileName: string): string;
+/**
+ * Errors-as-values core: validates the snapshot index and presigned-URL map,
+ * returning a typed `EngineError` for every modelled failure (bad index version,
+ * unsafe schema/YYYY-MM identifier, missing attach URL). Underlying DuckDB
+ * `runner` IO failures stay defects and propagate. `attachSnapshotIndex` is the
+ * throwing wrapper.
+ */
+declare function attachSnapshotIndexResult(runner: SnapshotQueryRunner, opts: AttachSnapshotOptions): Promise<Result<AttachSnapshotResult, EngineError>>;
 declare function attachSnapshotIndex(runner: SnapshotQueryRunner, opts: AttachSnapshotOptions): Promise<AttachSnapshotResult>;
 interface AttachParquetIndexOptions {
   /**
@@ -94,4 +104,4 @@ interface AttachParquetIndexResult {
   tables: string[];
 }
 declare function attachParquetIndex(runner: SnapshotQueryRunner, opts: AttachParquetIndexOptions): Promise<AttachParquetIndexResult>;
-export { type AttachParquetIndexOptions, type AttachParquetIndexResult, type AttachSnapshotOptions, type AttachSnapshotResult, type NodeDuckDBOptions, type NodeHarness, type NodeHarnessOptions, type SnapshotQueryRunner, attachParquetIndex, attachSnapshotIndex, createNodeDuckDBHandle, createNodeHarness, resetNodeDuckDB, snapshotAlias };
+export { type AttachParquetIndexOptions, type AttachParquetIndexResult, type AttachSnapshotOptions, type AttachSnapshotResult, type NodeDuckDBOptions, type NodeHarness, type NodeHarnessOptions, type SnapshotQueryRunner, attachParquetIndex, attachSnapshotIndex, attachSnapshotIndexResult, createNodeDuckDBHandle, createNodeHarness, resetNodeDuckDB, snapshotAlias };

package/dist/adapters/node.mjs

@@ -1,7 +1,9 @@
+import { engineErrors } from "../errors.mjs";
 import { createDuckDBCodec, createDuckDBExecutor, createStorageEngine } from "../_chunks/engine.mjs";
 import { createNodeDuckDBHandle, resetNodeDuckDB } from "./duckdb-node.mjs";
 import { createFilesystemDataSource, createFilesystemManifestStore } from "./filesystem.mjs";
 import { encodeSiteId } from "gscdump";
+import { err, ok, unwrapResult } from "gscdump/result";
 import path from "node:path";
 function createNodeHarness(opts) {
 	const dataDir = opts.dataDir;
@@ -72,20 +74,31 @@ function snapshotAlias(fileName) {
 	if (!m?.[1]) throw new TypeError(`snapshotAlias: unrecognised filename ${JSON.stringify(fileName)}`);
 	return `cold_${m[1].replace("-", "_")}`;
 }
-async function attachSnapshotIndex(runner, opts) {
+const SNAPSHOT_TYPE_ERROR_KINDS = new Set([
+	"invalid-snapshot-filename",
+	"unsupported-snapshot-index-version",
+	"invalid-schema-identifier",
+	"invalid-year-month"
+]);
+function snapshotAttachErrorToException(error) {
+	const exception = SNAPSHOT_TYPE_ERROR_KINDS.has(error.kind) ? new TypeError(error.message) : new Error(error.message);
+	exception.engineError = error;
+	return exception;
+}
+async function attachSnapshotIndexResult(runner, opts) {
 	const { index, attachUrls } = opts;
 	const schema = opts.schema ?? "main";
 	const forceDownload = opts.forceDownload !== false;
-	if (index?.version !== 1) throw new TypeError(`attachSnapshotIndex: unsupported snapshot index version ${String(index?.version)}; expected 1`);
-	if (!SCHEMA_IDENT_RE.test(schema)) throw new TypeError(`attachSnapshotIndex: invalid schema identifier ${JSON.stringify(schema)}`);
-	for (const ym of index.cold) if (!YEAR_MONTH_RE.test(ym)) throw new TypeError(`attachSnapshotIndex: invalid YYYY-MM entry ${JSON.stringify(ym)} in index.cold`);
+	if (index?.version !== 1) return err(engineErrors.unsupportedSnapshotIndexVersion(index?.version));
+	if (!SCHEMA_IDENT_RE.test(schema)) return err(engineErrors.invalidSchemaIdentifier(schema));
+	for (const ym of index.cold) if (!YEAR_MONTH_RE.test(ym)) return err(engineErrors.invalidYearMonth(ym));
 	await runner("LOAD httpfs").catch(() => void 0);
 	if (forceDownload) await runner("SET force_download=true");
 	const plan = [];
 	for (const ym of index.cold) {
 		const fileName = `cold-${ym}.duckdb`;
 		const url = attachUrls[fileName];
-		if (!url) throw new Error(`attachSnapshotIndex: attachUrls missing entry for ${fileName}`);
+		if (!url) return err(engineErrors.missingAttachUrl(fileName));
 		plan.push({
 			fileName,
 			alias: snapshotAlias(fileName),
@@ -95,7 +108,7 @@ async function attachSnapshotIndex(runner, opts) {
 	if (index.hot) {
 		const fileName = "hot.duckdb";
 		const url = attachUrls[fileName];
-		if (!url) throw new Error(`attachSnapshotIndex: attachUrls missing entry for ${fileName}`);
+		if (!url) return err(engineErrors.missingAttachUrl(fileName));
 		plan.push({
 			fileName,
 			alias: snapshotAlias(fileName),
@@ -125,10 +138,13 @@ async function attachSnapshotIndex(runner, opts) {
 		await runner(`CREATE OR REPLACE VIEW ${schema}.${table} AS ${aliases.filter((a) => dbsSet.has(a)).map((db) => `SELECT * FROM ${db}.${table}`).join(" UNION ALL BY NAME ")}`);
 		tables.push(table);
 	}
-	return {
+	return ok({
 		schema,
 		aliases,
 		tables
-	};
+	});
+}
+async function attachSnapshotIndex(runner, opts) {
+	return unwrapResult(await attachSnapshotIndexResult(runner, opts), snapshotAttachErrorToException);
 }
-export { attachParquetIndex, attachSnapshotIndex, createNodeDuckDBHandle, createNodeHarness, resetNodeDuckDB, snapshotAlias };
+export { attachParquetIndex, attachSnapshotIndex, attachSnapshotIndexResult, createNodeDuckDBHandle, createNodeHarness, resetNodeDuckDB, snapshotAlias };

package/dist/adapters/r2-manifest.mjs

@@ -1,4 +1,6 @@
 import { inferLegacyTier, inferSearchType } from "../_chunks/layout.mjs";
+import { engineErrorToException, engineErrors } from "../errors.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
 const SHARD_RE = /^u_[^/]+\/manifest\/(?<siteId>[^/]+)\/(?<table>[^/]+)\/HEAD$/;
 const CAS_BACKOFF_BASE_MS = 5;
 const CAS_BACKOFF_CAP_MS = 250;
@@ -83,14 +85,14 @@ function createR2ManifestStore(opts) {
 			headEtag: head.etag
 		};
 	}
-	async function writeShard(siteId, table, snapshot, headEtag) {
+	async function writeShardResult(siteId, table, snapshot, headEtag, attempt) {
 		const id = newSnapshotId();
 		const snapKey = snapshotKey(userId, siteId, table, id);
 		await bucket.put(snapKey, JSON.stringify(snapshot));
 		const conditional = headEtag ? { onlyIf: { etagMatches: headEtag } } : { onlyIf: { etagDoesNotMatch: "*" } };
-		return { ok: await bucket.put(headKey(userId, siteId, table), id, conditional) !== null };
+		return await bucket.put(headKey(userId, siteId, table), id, conditional) !== null ? ok(void 0) : err(engineErrors.manifestCasRoundLost(siteId, table, attempt));
 	}
-	async function mutateShard(siteId, table, mutate) {
+	async function mutateShardResult(siteId, table, mutate) {
 		let attempt = 0;
 		while (attempt < maxRetries) {
 			onEvent?.({
@@ -101,15 +103,15 @@ function createR2ManifestStore(opts) {
 			});
 			const { snapshot, headEtag } = await readShard(siteId, table);
 			await mutate(snapshot);
-			const { ok } = await writeShard(siteId, table, snapshot, headEtag);
-			if (ok) {
+			const round = await writeShardResult(siteId, table, snapshot, headEtag, attempt);
+			if (round.ok) {
 				onEvent?.({
 					kind: "cas-committed",
 					siteId,
 					table,
 					attempts: attempt + 1
 				});
-				return;
+				return round;
 			}
 			onEvent?.({
 				kind: "cas-rejected",
@@ -120,7 +122,10 @@ function createR2ManifestStore(opts) {
 			attempt++;
 			if (attempt < maxRetries) await casBackoff(attempt);
 		}
-		throw new Error(`R2 manifest CAS exceeded ${maxRetries} retries for ${siteId}/${table}`);
+		return err(engineErrors.manifestCasExhausted(siteId, table, maxRetries));
+	}
+	async function mutateShard(siteId, table, mutate) {
+		return unwrapResult(await mutateShardResult(siteId, table, mutate), engineErrorToException);
 	}
 	async function listShards() {
 		const shards = [];

package/dist/analyzer/index.d.mts

@@ -1,8 +1,10 @@
+import { EngineError } from "../_chunks/errors.mjs";
 import { AnalysisParams, AnalysisResult } from "../_chunks/analysis-types.mjs";
 import { AnalysisQuerySource, Analyzer, AnalyzerRegistry, AnalyzerRegistryInit, AnalyzerVariants, BuildContext, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, requireAdapter } from "../_chunks/registry.mjs";
 declare class AnalyzerCapabilityError extends Error {
   readonly tool: string;
   readonly missing: readonly RequiredCapability[];
+  readonly engineError: EngineError;
   constructor(tool: string, missing: readonly RequiredCapability[]);
 }
 /**