@gscdump/engine 0.25.14 → 0.26.1

package/dist/errors.mjs

@@ -0,0 +1,202 @@
+const engineErrors = {
+	analyzerNotFound(tool) {
+		return {
+			kind: "analyzer-not-found",
+			tool,
+			message: `analyzer "${tool}" requires capabilities [executeSql] not provided by source`
+		};
+	},
+	analyzerCapabilityMissing(tool, missing) {
+		return {
+			kind: "analyzer-capability-missing",
+			tool,
+			missing,
+			message: `analyzer "${tool}" requires capabilities [${missing.join(", ")}] not provided by source`
+		};
+	},
+	nonFiniteNumberLiteral(value) {
+		return {
+			kind: "invalid-sql-literal",
+			message: `cannot inline non-finite number: ${value}`
+		};
+	},
+	controlCharsInLiteral() {
+		return {
+			kind: "invalid-sql-literal",
+			message: "string literal contains disallowed control characters"
+		};
+	},
+	uninlinableLiteralType(type) {
+		return {
+			kind: "invalid-sql-literal",
+			message: `cannot inline value of type ${type}`
+		};
+	},
+	morePlaceholdersThanParams(have) {
+		return {
+			kind: "placeholder-arity-mismatch",
+			message: `bindLiterals: more '?' placeholders than params (have ${have})`
+		};
+	},
+	dollarPlaceholderOutOfRange(n, have) {
+		return {
+			kind: "placeholder-arity-mismatch",
+			message: `bindLiterals: $${n} out of range (have ${have} params)`
+		};
+	},
+	mixedPlaceholderStyles() {
+		return {
+			kind: "placeholder-arity-mismatch",
+			message: "bindLiterals: cannot mix '?' and '$N' placeholders in the same query"
+		};
+	},
+	unusedParams(unused) {
+		return {
+			kind: "placeholder-arity-mismatch",
+			message: `bindLiterals: ${unused} params unused`
+		};
+	},
+	searchTypesNotArray() {
+		return {
+			kind: "invalid-search-types",
+			message: "enabledSearchTypes must be a non-empty array"
+		};
+	},
+	unknownSearchType(value) {
+		return {
+			kind: "invalid-search-types",
+			message: `enabledSearchTypes: unknown searchType ${String(value)}`
+		};
+	},
+	searchTypesMissingWeb() {
+		return {
+			kind: "invalid-search-types",
+			message: "enabledSearchTypes must include \"web\""
+		};
+	},
+	attachedTableMissing(missing) {
+		return {
+			kind: "attached-table-missing",
+			missing,
+			message: `attached-table source: required table(s) not attached: ${missing.join(", ")}`
+		};
+	},
+	manifestCasExhausted(siteId, table, attempts) {
+		return {
+			kind: "manifest-cas-exhausted",
+			siteId,
+			table,
+			attempts,
+			message: `R2 manifest CAS exceeded ${attempts} retries for ${siteId}/${table}`
+		};
+	},
+	invalidSnapshotFilename(fileName) {
+		return {
+			kind: "invalid-snapshot-filename",
+			fileName,
+			message: `snapshotAlias: unrecognised filename ${JSON.stringify(fileName)}`
+		};
+	},
+	unsupportedSnapshotIndexVersion(version) {
+		return {
+			kind: "unsupported-snapshot-index-version",
+			version,
+			message: `attachSnapshotIndex: unsupported snapshot index version ${String(version)}; expected 1`
+		};
+	},
+	invalidSchemaIdentifier(schema) {
+		return {
+			kind: "invalid-schema-identifier",
+			schema,
+			message: `attachSnapshotIndex: invalid schema identifier ${JSON.stringify(schema)}`
+		};
+	},
+	invalidYearMonth(value) {
+		return {
+			kind: "invalid-year-month",
+			value,
+			message: `attachSnapshotIndex: invalid YYYY-MM entry ${JSON.stringify(value)} in index.cold`
+		};
+	},
+	missingAttachUrl(fileName) {
+		return {
+			kind: "missing-attach-url",
+			fileName,
+			message: `attachSnapshotIndex: attachUrls missing entry for ${fileName}`
+		};
+	},
+	manifestCasRoundLost(siteId, table, attempt) {
+		return {
+			kind: "manifest-cas-round-lost",
+			siteId,
+			table,
+			attempt,
+			message: `R2 manifest CAS round ${attempt} lost the conditional-PUT race for ${siteId}/${table}`
+		};
+	},
+	icebergTableOpFailed(op, table, cause) {
+		return {
+			kind: "iceberg-table-op-failed",
+			op,
+			table,
+			cause,
+			message: String(cause)
+		};
+	},
+	sinkTableFlushFailed(table, cause) {
+		return {
+			kind: "sink-table-flush-failed",
+			table,
+			cause,
+			message: String(cause)
+		};
+	},
+	rollupBuildFailed(id, cause) {
+		return {
+			kind: "rollup-build-failed",
+			id,
+			cause,
+			message: cause instanceof Error ? cause.stack || cause.message : String(cause)
+		};
+	},
+	lockAcquireTimeout(scope, timeoutMs) {
+		return {
+			kind: "lock-acquire-timeout",
+			scope,
+			timeoutMs,
+			message: `withLock: timed out acquiring ${scope} after ${timeoutMs}ms`
+		};
+	}
+};
+const ENGINE_ERROR_KINDS = new Set([
+	"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"
+]);
+function isEngineError(value) {
+	return typeof value === "object" && value !== null && ENGINE_ERROR_KINDS.has(value.kind) && typeof value.message === "string";
+}
+function formatEngineError(error) {
+	return error.message;
+}
+function engineErrorToException(error) {
+	const exception = new Error(error.message);
+	if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+	exception.engineError = error;
+	return exception;
+}
+export { engineErrorToException, engineErrors, formatEngineError, isEngineError };

package/dist/iceberg/index.mjs

@@ -1,4 +1,6 @@
+import { engineErrors } from "../errors.mjs";
 import { ICEBERG_FIELD_ID_BASE, ICEBERG_PARTITION_COLUMNS, ICEBERG_PARTITION_SPEC, ICEBERG_SCHEMAS, ICEBERG_TABLES, assertIcebergTable, icebergTableSpec, isIcebergTable } from "../_chunks/schema2.mjs";
+import { err, ok } from "gscdump/result";
 import { icebergAppend, icebergCreateTable, icebergDropTable, icebergManifests, restCatalogConnect, restCatalogCreateNamespace, restCatalogListTables, restCatalogLoadTable, s3SignedResolver } from "icebird";
 const ICEBERG_TYPE_MAP = {
 	STRING: "string",
@@ -88,16 +90,15 @@ async function createIcebergTables(conn, tables = ICEBERG_TABLES) {
 		partitionSpec: icebergPartitionSpecFor(table)
 	}).then(() => results.push({
 		table,
-		ok: true
+		outcome: ok(void 0)
 	}), (e) => results.push({
 		table,
-		ok: false,
-		error: String(e)
+		outcome: err(engineErrors.icebergTableOpFailed("create", table, e))
 	}));
 	return results;
 }
 async function listIcebergTables(conn) {
-	return restCatalogListTables(conn.catalog, { namespace: conn.namespace }).then((list) => list.map((t) => t.name).sort(), () => []);
+	return (await restCatalogListTables(conn.catalog, { namespace: conn.namespace })).map((t) => t.name).sort();
 }
 function monthsInRange(range) {
 	const [sy, sm] = range.start.split("-").map(Number);
@@ -156,7 +157,7 @@ async function listIcebergDataFiles(conn, opts) {
 	return out;
 }
 async function dropIcebergTables(conn, tables) {
-	const targets = tables ?? await restCatalogListTables(conn.catalog, { namespace: conn.namespace }).then((list) => list.map((t) => t.name), () => []);
+	const targets = tables ?? (await restCatalogListTables(conn.catalog, { namespace: conn.namespace })).map((t) => t.name);
 	const results = [];
 	for (const table of targets) await icebergDropTable({
 		catalog: conn.catalog,
@@ -165,11 +166,10 @@ async function dropIcebergTables(conn, tables) {
 		purgeRequested: true
 	}).then(() => results.push({
 		table,
-		ok: true
+		outcome: ok(void 0)
 	}), (e) => results.push({
 		table,
-		ok: false,
-		error: String(e)
+		outcome: err(engineErrors.icebergTableOpFailed("drop", table, e))
 	}));
 	return results;
 }
@@ -226,14 +226,14 @@ function createIcebergAppendSink(options) {
 				flushed,
 				failed
 			};
-			const conn = await connect().then((c) => c, (err) => {
+			const conn = await connect().then((c) => c, (cause) => {
 				connection = void 0;
-				return { error: String(err) };
+				return { connectError: cause };
 			});
-			if ("error" in conn) {
+			if ("connectError" in conn) {
 				for (const [table, records] of buffers) if (records.length > 0) failed.push({
 					table,
-					error: conn.error
+					error: engineErrors.sinkTableFlushFailed(table, conn.connectError)
 				});
 				buffers.clear();
 				return {
@@ -251,10 +251,10 @@ function createIcebergAppendSink(options) {
 					records
 				}, options.commitRetry).then(() => {
 					flushed.push(table);
-				}, (err) => {
+				}, (cause) => {
 					failed.push({
 						table,
-						error: String(err)
+						error: engineErrors.sinkTableFlushFailed(table, cause)
 					});
 				});
 			}

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { CodecCtx, CompactionThresholds, CompactionTier, DataSource, EngineOptions, FileSetRef, GcCtx, Grain, ListLiveFilter, LockScope, ManifestEntry, ManifestPurgeResult, ManifestStore, ParquetCodec, PurgeFilter, PurgeResult, PurgeUrlsResult, QueryCtx, QueryExecuteOptions, QueryExecuteResult, QueryExecutor, QueryResult, Row, RunSQLOptions, SearchType, StorageEngine, SyncState, SyncStateDetail, SyncStateFilter, SyncStateKind, SyncStateScope, TableName, TenantCtx, Watermark, WatermarkFilter, WatermarkScope, WriteCtx, WriteResult, enumeratePartitions } from "./_chunks/storage.mjs";
 import { DuckDBFactory, DuckDBHandle, canonicalEmptyParquetSchema, createDuckDBCodec, createDuckDBExecutor } from "./_chunks/duckdb.mjs";
 import { ColumnDef, ColumnType, DrizzleSchema, SCHEMAS, TABLE_METADATA, TableSchema, allTables, countries, currentSchemaVersion, dates, dimensionToColumn, drizzleSchema, hourly_pages, inferTable, page_queries, pages, queries } from "./_chunks/schema.mjs";
+import { EngineError, EngineErrorKind, engineErrorToException, engineErrors, formatEngineError, isEngineError } from "./_chunks/errors.mjs";
 import { InspectionVerdict, SchedulePolicy, ScheduleState, fixedPolicy, inspectionPolicy, sitemapPolicy } from "./schedule.mjs";
 import { IcebergTableName, Sink, SinkCapabilities, SinkCloseResult, SinkOptions, SinkSlice, SinkWriteResult } from "./_chunks/sink.mjs";
 import { GscApiRow, IngestOptions, RowAccumulator, RowAccumulatorOptions, assembleDatesRow, createRowAccumulator, toPath, toSumPosition, transformGscRow } from "./ingest.mjs";
@@ -9,8 +10,9 @@ import { createIcebergResolverAdapter, createParquetResolverAdapter, pgResolverA
 import { rebuildDailyFromHourly } from "./rollups.mjs";
 import { ENGINE_QUERY_CAPABILITIES, createSqlQuerySource } from "./_chunks/index.mjs";
 import { bindLiterals, formatLiteral } from "./sql-bind.mjs";
-import { Grain as Grain$1, Row as Row$1, TableName as TableName$1, TenantCtx as TenantCtx$1 } from "@gscdump/contracts";
+import { Result } from "gscdump/result";
 import { SearchType as SearchType$1 } from "gscdump/query";
+import { Grain as Grain$1, Row as Row$1, TableName as TableName$1, TenantCtx as TenantCtx$1 } from "@gscdump/contracts";
 declare function coerceRow(row: Row$1): Row$1;
 declare function coerceRows(rows: readonly Row$1[]): Row$1[];
 declare const MAX_DAY_BYTES: number;
@@ -160,6 +162,12 @@ declare function createInMemorySink(): InMemorySink;
 type SyncTableName = Extract<TableName$1, 'pages' | 'queries' | 'countries' | 'page_queries' | 'dates'>;
 declare const TABLES_BY_SEARCH_TYPE: Record<SearchType, readonly SyncTableName[]>;
 declare function parseEnabledSearchTypes(raw: string | null | undefined): SearchType[];
+/**
+ * Errors-as-values core for {@link validateEnabledSearchTypes}: returns a typed
+ * `invalid-search-types` `EngineError` instead of throwing, so a host saving the
+ * persisted config can map a bad value to a 4xx rather than a 500.
+ */
+declare function validateEnabledSearchTypesResult(value: unknown): Result<SearchType[], EngineError>;
 declare function validateEnabledSearchTypes(value: unknown): SearchType[];
 declare const TABLE_TIERS: {
   readonly pages: "critical";
@@ -182,4 +190,4 @@ declare const MIN_SYNC_IMPRESSIONS = 1;
 declare const MIN_COUNTRY_IMPRESSIONS = 10;
 declare const MAX_SITEMAP_URLS_PER_SITE = 50000;
 declare const MAX_TRACKED_URLS_PER_SITE = 200000;
-export { type CodecCtx, type ColumnDef, type ColumnType, type CompactionThresholds, type CompactionTier, type CreateIngestAccumulatorOptions, DEFAULT_SEARCH_TYPE, type DataSource, type DateWeight, type DrizzleSchema, type DuckDBFactory, type DuckDBHandle, ENGINE_QUERY_CAPABILITIES, type EngineOptions, FILES_PLACEHOLDER, type FileSetRef, type FinalizeOptions, type FinalizeResult, type GcCtx, type Grain, type GscApiRow, type InMemorySink, type IngestAccumulator, type IngestAccumulatorCtx, type IngestAccumulatorEngine, type IngestAccumulatorHooks, type IngestOptions, type InspectionVerdict, type ListLiveFilter, type LockScope, MAX_DAY_BYTES, MAX_GSC_PAGES_R2, MAX_SITEMAP_URLS_PER_SITE, MAX_TRACKED_URLS_PER_SITE, MIN_COUNTRY_IMPRESSIONS, MIN_SYNC_IMPRESSIONS, type ManifestEntry, type ManifestPurgeResult, type ManifestStore, type ParquetCodec, type PurgeFilter, type PurgeResult, type PurgeUrlsResult, type QueryCtx, type QueryExecuteOptions, type QueryExecuteResult, type QueryExecutor, type QueryResult, ROW_LIMIT_R2, type ResolvedQuery, type Row, type RowAccumulator, type RowAccumulatorOptions, type RunSQLOptions, SCHEMAS, type SchedulePolicy, type ScheduleState, type SearchType, type Sink, type SinkCapabilities, type SinkCloseResult, type SinkOptions, type SinkSlice, type SinkWriteResult, type StorageEngine, type StoredRow, type SyncState, type SyncStateDetail, type SyncStateFilter, type SyncStateKind, type SyncStateScope, type SyncTableName, TABLES_BY_SEARCH_TYPE, TABLE_METADATA, TABLE_TIERS, TIER_PRIORITY, type TableName, type TableSchema, type TableTier, type TenantCtx, type TieredTableName, WEIGHT_PRIORITY, type Watermark, type WatermarkFilter, type WatermarkScope, type WriteCtx, type WriteResult, allTables, assembleDatesRow, bindLiterals, canonicalEmptyParquetSchema, coerceRow, coerceRows, countries, createDuckDBCodec, createDuckDBExecutor, createIcebergResolverAdapter, createInMemorySink, createIngestAccumulator, createNoopIngestAccumulator, createParquetResolverAdapter, createRowAccumulator, createSqlQuerySource, createStorageEngine, currentSchemaVersion, dates, dayPartition, dimensionToColumn, drizzleSchema, enumeratePartitions, fixedPolicy, formatLiteral, getDateWeight, getTableTier, getTablesForTier, hourPartition, hourly_pages, inferLegacyTier, inferSearchType, inferTable, inspectionPolicy, objectKey, page_queries, pages, parseEnabledSearchTypes, pgResolverAdapter, queries, rebuildDailyFromHourly, resolveParquetSQL, sitemapPolicy, substituteNamedFiles, toPath, toSumPosition, transformGscRow, validateEnabledSearchTypes };
+export { type CodecCtx, type ColumnDef, type ColumnType, type CompactionThresholds, type CompactionTier, type CreateIngestAccumulatorOptions, DEFAULT_SEARCH_TYPE, type DataSource, type DateWeight, type DrizzleSchema, type DuckDBFactory, type DuckDBHandle, ENGINE_QUERY_CAPABILITIES, EngineError, EngineErrorKind, type EngineOptions, FILES_PLACEHOLDER, type FileSetRef, type FinalizeOptions, type FinalizeResult, type GcCtx, type Grain, type GscApiRow, type InMemorySink, type IngestAccumulator, type IngestAccumulatorCtx, type IngestAccumulatorEngine, type IngestAccumulatorHooks, type IngestOptions, type InspectionVerdict, type ListLiveFilter, type LockScope, MAX_DAY_BYTES, MAX_GSC_PAGES_R2, MAX_SITEMAP_URLS_PER_SITE, MAX_TRACKED_URLS_PER_SITE, MIN_COUNTRY_IMPRESSIONS, MIN_SYNC_IMPRESSIONS, type ManifestEntry, type ManifestPurgeResult, type ManifestStore, type ParquetCodec, type PurgeFilter, type PurgeResult, type PurgeUrlsResult, type QueryCtx, type QueryExecuteOptions, type QueryExecuteResult, type QueryExecutor, type QueryResult, ROW_LIMIT_R2, type ResolvedQuery, type Row, type RowAccumulator, type RowAccumulatorOptions, type RunSQLOptions, SCHEMAS, type SchedulePolicy, type ScheduleState, type SearchType, type Sink, type SinkCapabilities, type SinkCloseResult, type SinkOptions, type SinkSlice, type SinkWriteResult, type StorageEngine, type StoredRow, type SyncState, type SyncStateDetail, type SyncStateFilter, type SyncStateKind, type SyncStateScope, type SyncTableName, TABLES_BY_SEARCH_TYPE, TABLE_METADATA, TABLE_TIERS, TIER_PRIORITY, type TableName, type TableSchema, type TableTier, type TenantCtx, type TieredTableName, WEIGHT_PRIORITY, type Watermark, type WatermarkFilter, type WatermarkScope, type WriteCtx, type WriteResult, allTables, assembleDatesRow, bindLiterals, canonicalEmptyParquetSchema, coerceRow, coerceRows, countries, createDuckDBCodec, createDuckDBExecutor, createIcebergResolverAdapter, createInMemorySink, createIngestAccumulator, createNoopIngestAccumulator, createParquetResolverAdapter, createRowAccumulator, createSqlQuerySource, createStorageEngine, currentSchemaVersion, dates, dayPartition, dimensionToColumn, drizzleSchema, engineErrorToException, engineErrors, enumeratePartitions, fixedPolicy, formatEngineError, formatLiteral, getDateWeight, getTableTier, getTablesForTier, hourPartition, hourly_pages, inferLegacyTier, inferSearchType, inferTable, inspectionPolicy, isEngineError, objectKey, page_queries, pages, parseEnabledSearchTypes, pgResolverAdapter, queries, rebuildDailyFromHourly, resolveParquetSQL, sitemapPolicy, substituteNamedFiles, toPath, toSumPosition, transformGscRow, validateEnabledSearchTypes, validateEnabledSearchTypesResult };

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { DEFAULT_SEARCH_TYPE, dayPartition, hourPartition, inferLegacyTier, infe
 import { SCHEMAS, TABLE_METADATA, allTables, countries, currentSchemaVersion, dates, dimensionToColumn, drizzleSchema, hourly_pages, inferTable, page_queries, pages, queries } from "./_chunks/schema.mjs";
 import { enumeratePartitions } from "./_chunks/compaction.mjs";
 import { FILES_PLACEHOLDER, resolveParquetSQL, substituteNamedFiles } from "./_chunks/parquet-plan.mjs";
+import { engineErrorToException, engineErrors, formatEngineError, isEngineError } from "./errors.mjs";
 import { bindLiterals, formatLiteral } from "./sql-bind.mjs";
 import { MAX_DAY_BYTES, canonicalEmptyParquetSchema, createDuckDBCodec, createDuckDBExecutor, createStorageEngine } from "./_chunks/engine.mjs";
 import { assembleDatesRow, createRowAccumulator, toPath, toSumPosition, transformGscRow } from "./ingest.mjs";
@@ -10,6 +11,7 @@ import "./planner.mjs";
 import { createIcebergResolverAdapter, createParquetResolverAdapter, pgResolverAdapter } from "./_chunks/resolver.mjs";
 import { rebuildDailyFromHourly } from "./rollups.mjs";
 import { fixedPolicy, inspectionPolicy, sitemapPolicy } from "./schedule.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
 const NOOP_RESULT = {
 	flushed: 0,
 	recovered: 0,
@@ -228,18 +230,21 @@ function parseEnabledSearchTypes(raw) {
 	if (!valid.includes("web")) valid.unshift("web");
 	return valid;
 }
-function validateEnabledSearchTypes(value) {
-	if (!Array.isArray(value) || value.length === 0) throw new Error("enabledSearchTypes must be a non-empty array");
+function validateEnabledSearchTypesResult(value) {
+	if (!Array.isArray(value) || value.length === 0) return err(engineErrors.searchTypesNotArray());
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
 	for (const v of value) {
-		if (typeof v !== "string" || !(v in TABLES_BY_SEARCH_TYPE)) throw new Error(`enabledSearchTypes: unknown searchType ${String(v)}`);
+		if (typeof v !== "string" || !(v in TABLES_BY_SEARCH_TYPE)) return err(engineErrors.unknownSearchType(v));
 		if (seen.has(v)) continue;
 		seen.add(v);
 		out.push(v);
 	}
-	if (!out.includes("web")) throw new Error("enabledSearchTypes must include \"web\"");
-	return out;
+	if (!out.includes("web")) return err(engineErrors.searchTypesMissingWeb());
+	return ok(out);
+}
+function validateEnabledSearchTypes(value) {
+	return unwrapResult(validateEnabledSearchTypesResult(value), engineErrorToException);
 }
 const TABLE_TIERS = {
 	pages: "critical",
@@ -277,4 +282,4 @@ const MIN_SYNC_IMPRESSIONS = 1;
 const MIN_COUNTRY_IMPRESSIONS = 10;
 const MAX_SITEMAP_URLS_PER_SITE = 5e4;
 const MAX_TRACKED_URLS_PER_SITE = 2e5;
-export { DEFAULT_SEARCH_TYPE, ENGINE_QUERY_CAPABILITIES, FILES_PLACEHOLDER, MAX_DAY_BYTES, MAX_GSC_PAGES_R2, MAX_SITEMAP_URLS_PER_SITE, MAX_TRACKED_URLS_PER_SITE, MIN_COUNTRY_IMPRESSIONS, MIN_SYNC_IMPRESSIONS, ROW_LIMIT_R2, SCHEMAS, TABLES_BY_SEARCH_TYPE, TABLE_METADATA, TABLE_TIERS, TIER_PRIORITY, WEIGHT_PRIORITY, allTables, assembleDatesRow, bindLiterals, canonicalEmptyParquetSchema, coerceRow, coerceRows, countries, createDuckDBCodec, createDuckDBExecutor, createIcebergResolverAdapter, createInMemorySink, createIngestAccumulator, createNoopIngestAccumulator, createParquetResolverAdapter, createRowAccumulator, createSqlQuerySource, createStorageEngine, currentSchemaVersion, dates, dayPartition, dimensionToColumn, drizzleSchema, enumeratePartitions, fixedPolicy, formatLiteral, getDateWeight, getTableTier, getTablesForTier, hourPartition, hourly_pages, inferLegacyTier, inferSearchType, inferTable, inspectionPolicy, objectKey, page_queries, pages, parseEnabledSearchTypes, pgResolverAdapter, queries, rebuildDailyFromHourly, resolveParquetSQL, sitemapPolicy, substituteNamedFiles, toPath, toSumPosition, transformGscRow, validateEnabledSearchTypes };
+export { DEFAULT_SEARCH_TYPE, ENGINE_QUERY_CAPABILITIES, FILES_PLACEHOLDER, MAX_DAY_BYTES, MAX_GSC_PAGES_R2, MAX_SITEMAP_URLS_PER_SITE, MAX_TRACKED_URLS_PER_SITE, MIN_COUNTRY_IMPRESSIONS, MIN_SYNC_IMPRESSIONS, ROW_LIMIT_R2, SCHEMAS, TABLES_BY_SEARCH_TYPE, TABLE_METADATA, TABLE_TIERS, TIER_PRIORITY, WEIGHT_PRIORITY, allTables, assembleDatesRow, bindLiterals, canonicalEmptyParquetSchema, coerceRow, coerceRows, countries, createDuckDBCodec, createDuckDBExecutor, createIcebergResolverAdapter, createInMemorySink, createIngestAccumulator, createNoopIngestAccumulator, createParquetResolverAdapter, createRowAccumulator, createSqlQuerySource, createStorageEngine, currentSchemaVersion, dates, dayPartition, dimensionToColumn, drizzleSchema, engineErrorToException, engineErrors, enumeratePartitions, fixedPolicy, formatEngineError, formatLiteral, getDateWeight, getTableTier, getTablesForTier, hourPartition, hourly_pages, inferLegacyTier, inferSearchType, inferTable, inspectionPolicy, isEngineError, objectKey, page_queries, pages, parseEnabledSearchTypes, pgResolverAdapter, queries, rebuildDailyFromHourly, resolveParquetSQL, sitemapPolicy, substituteNamedFiles, toPath, toSumPosition, transformGscRow, validateEnabledSearchTypes, validateEnabledSearchTypesResult };

package/dist/resolver/index.d.mts

@@ -3,8 +3,8 @@ import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, Resol
 import { PgTableKey, createIcebergResolverAdapter, createParquetResolverAdapter, pgResolverAdapter } from "../_chunks/pg-adapter.mjs";
 import { LogicalDataset, LogicalDataset as LogicalDataset$1, PlannerCapabilities, UnresolvableDatasetError, inferDataset as inferLogicalDataset, isDatasetResolvable } from "gscdump/query/plan";
 import { SQL } from "drizzle-orm";
-import { Grain, TableName } from "@gscdump/contracts";
 import { BuilderState, Dimension, FilterInput, InternalFilter, Metric } from "gscdump/query";
+import { Grain, TableName } from "@gscdump/contracts";
 type DimensionSurface = 'api' | 'stored' | 'derived';
 interface DimensionBinding {
   column: string;

package/dist/rollups.d.mts

@@ -1,7 +1,8 @@
 import { DataSource, FileSetRef, Row as Row$1 } from "./_chunks/storage.mjs";
 import { ColumnDef } from "./_chunks/schema.mjs";
-import { TenantCtx } from "@gscdump/contracts";
+import { EngineError } from "./_chunks/errors.mjs";
 import { SearchType } from "gscdump/query";
+import { TenantCtx } from "@gscdump/contracts";
 interface RollupCtx extends TenantCtx {
   /** When the rollup was built. Stamped into payload + filename. */
   builtAt: number;
@@ -181,9 +182,10 @@ interface RebuildRollupResult {
   /**
    * Set when this def's build/encode/write failed. The runner records the
    * failure and continues with the remaining defs so one bad rollup never
-   * aborts the rest. Successful defs have no `error`.
+   * aborts the rest. Successful defs have no `error`. The human-readable
+   * message (including the stack when available) lives on `error.message`.
    */
-  error?: string;
+  error?: EngineError;
 }
 declare function rebuildRollups(opts: RebuildRollupsOptions): Promise<RebuildRollupResult[]>;
 /**

package/dist/rollups.mjs

@@ -1,6 +1,7 @@
 import "./_chunks/layout.mjs";
+import { engineErrors } from "./errors.mjs";
 import { encodeRowsToParquetFlex } from "./adapters/hyparquet.mjs";
-import { createIndexingMetadataStore, createSitemapStore, inspectionParquetKey, sitemapUrlsIndexPrefix } from "./entities.mjs";
+import { createIndexingMetadataStore, createSitemapStore, inspectionParquetKey, sitemapUrlsIndexPrefix } from "./_chunks/entities.mjs";
 import { MS_PER_DAY } from "gscdump";
 function rollupPrefix(ctx, searchType) {
 	const base = ctx.siteId ? `u_${ctx.userId}/${ctx.siteId}/rollups` : `u_${ctx.userId}/rollups`;
@@ -21,8 +22,7 @@ async function readLatestRollup(bucket, ctx, id, searchType) {
 		const listing = await bucket.list({
 			prefix,
 			cursor
-		}).catch(() => null);
-		if (!listing) return null;
+		});
 		for (const obj of listing.objects) {
 			const m = ROLLUP_FILE_RE.exec(obj.key.slice(prefix.length));
 			if (!m?.groups || m.groups.id !== id) continue;
@@ -35,7 +35,7 @@ async function readLatestRollup(bucket, ctx, id, searchType) {
 		cursor = listing.truncated ? listing.cursor : void 0;
 	} while (cursor !== void 0);
 	if (!newest) return null;
-	const obj = await bucket.get(newest.key).catch(() => null);
+	const obj = await bucket.get(newest.key);
 	if (!obj) return null;
 	return JSON.parse(await obj.text());
 }
@@ -111,7 +111,7 @@ async function rebuildRollups(opts) {
 				objectKey: "",
 				bytes: 0,
 				builtAt,
-				error: err instanceof Error ? err.stack || err.message : String(err)
+				error: engineErrors.rollupBuildFailed(def.id, err)
 			});
 		}
 	}

package/dist/sql-bind.d.mts

@@ -1,5 +1,12 @@
+import { EngineError } from "./_chunks/errors.mjs";
+import { Result } from "gscdump/result";
 /** Escape single quotes for inlining inside a SQL string literal (SQL-standard `''` escaping). */
 declare function sqlEscape(s: string): string;
+/**
+ * Errors-as-values core for {@link formatLiteral}: returns a typed
+ * `invalid-sql-literal` `EngineError` for values that can't be safely inlined.
+ */
+declare function formatLiteralResult(value: unknown): Result<string, EngineError>;
 declare function formatLiteral(value: unknown): string;
 /**
  * Replace `?` and `$N` placeholders with inline SQL literals. Single-quoted
@@ -15,5 +22,12 @@ declare function formatLiteral(value: unknown): string;
  * Throws when placeholder count and params length disagree, or when a `$N`
  * index is out of range.
  */
+/**
+ * Errors-as-values core for {@link bindLiterals}: returns a typed
+ * `placeholder-arity-mismatch` / `invalid-sql-literal` `EngineError` instead of
+ * throwing, so the edge RPC / proxy callers that build SQL from untrusted params
+ * can branch on the failure.
+ */
+declare function bindLiteralsResult(sql: string, params: readonly unknown[]): Result<string, EngineError>;
 declare function bindLiterals(sql: string, params: readonly unknown[]): string;
-export { bindLiterals, formatLiteral, sqlEscape };
+export { bindLiterals, bindLiteralsResult, formatLiteral, formatLiteralResult, sqlEscape };

package/dist/sql-bind.mjs

@@ -1,3 +1,5 @@
+import { engineErrorToException, engineErrors } from "./errors.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
 function containsDisallowedControlChars(value) {
 	for (let i = 0; i < value.length; i++) {
 		const code = value.charCodeAt(i);
@@ -8,23 +10,26 @@ function containsDisallowedControlChars(value) {
 function sqlEscape(s) {
 	return s.replace(/'/g, "''");
 }
-function formatLiteral(value) {
-	if (value == null) return "NULL";
+function formatLiteralResult(value) {
+	if (value == null) return ok("NULL");
 	if (typeof value === "number") {
-		if (!Number.isFinite(value)) throw new Error(`cannot inline non-finite number: ${value}`);
-		return String(value);
+		if (!Number.isFinite(value)) return err(engineErrors.nonFiniteNumberLiteral(value));
+		return ok(String(value));
 	}
-	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
-	if (typeof value === "bigint") return value.toString();
-	if (value instanceof Date) return `'${value.toISOString()}'`;
+	if (typeof value === "boolean") return ok(value ? "TRUE" : "FALSE");
+	if (typeof value === "bigint") return ok(value.toString());
+	if (value instanceof Date) return ok(`'${value.toISOString()}'`);
 	if (typeof value === "string") {
-		if (containsDisallowedControlChars(value)) throw new Error("string literal contains disallowed control characters");
-		return `'${value.replace(/'/g, "''")}'`;
+		if (containsDisallowedControlChars(value)) return err(engineErrors.controlCharsInLiteral());
+		return ok(`'${value.replace(/'/g, "''")}'`);
 	}
-	throw new Error(`cannot inline value of type ${typeof value}`);
+	return err(engineErrors.uninlinableLiteralType(typeof value));
 }
-function bindLiterals(sql, params) {
-	if (params.length === 0) return sql;
+function formatLiteral(value) {
+	return unwrapResult(formatLiteralResult(value), engineErrorToException);
+}
+function bindLiteralsResult(sql, params) {
+	if (params.length === 0) return ok(sql);
 	let out = "";
 	let i = 0;
 	let qmarkIdx = 0;
@@ -66,8 +71,10 @@ function bindLiterals(sql, params) {
 			continue;
 		}
 		if (c === "?") {
-			if (qmarkIdx >= params.length) throw new Error(`bindLiterals: more '?' placeholders than params (have ${params.length})`);
-			out += formatLiteral(params[qmarkIdx++]);
+			if (qmarkIdx >= params.length) return err(engineErrors.morePlaceholdersThanParams(params.length));
+			const literal = formatLiteralResult(params[qmarkIdx++]);
+			if (!literal.ok) return literal;
+			out += literal.value;
 			i++;
 			continue;
 		}
@@ -75,18 +82,23 @@ function bindLiterals(sql, params) {
 			let j = i + 1;
 			while (j < sql.length && sql[j] >= "0" && sql[j] <= "9") j++;
 			const n = Number(sql.slice(i + 1, j));
-			if (n < 1 || n > params.length) throw new Error(`bindLiterals: $${n} out of range (have ${params.length} params)`);
+			if (n < 1 || n > params.length) return err(engineErrors.dollarPlaceholderOutOfRange(n, params.length));
 			usedDollar.add(n - 1);
-			out += formatLiteral(params[n - 1]);
+			const literal = formatLiteralResult(params[n - 1]);
+			if (!literal.ok) return literal;
+			out += literal.value;
 			i = j;
 			continue;
 		}
 		out += c;
 		i++;
 	}
-	if (qmarkIdx > 0 && usedDollar.size > 0) throw new Error("bindLiterals: cannot mix '?' and '$N' placeholders in the same query");
+	if (qmarkIdx > 0 && usedDollar.size > 0) return err(engineErrors.mixedPlaceholderStyles());
 	const used = qmarkIdx > 0 ? qmarkIdx : usedDollar.size;
-	if (used !== params.length) throw new Error(`bindLiterals: ${params.length - used} params unused`);
-	return out;
+	if (used !== params.length) return err(engineErrors.unusedParams(params.length - used));
+	return ok(out);
+}
+function bindLiterals(sql, params) {
+	return unwrapResult(bindLiteralsResult(sql, params), engineErrorToException);
 }
-export { bindLiterals, formatLiteral, sqlEscape };
+export { bindLiterals, bindLiteralsResult, formatLiteral, formatLiteralResult, sqlEscape };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine",
   "type": "module",
-  "version": "0.25.14",
+  "version": "0.26.1",
   "description": "Append-only Parquet/DuckDB storage engine + planner + adapters for the gscdump pipeline. Node + edge runtimes; opt-in heavy peers.",
   "author": {
     "name": "Harlan Wilton",
@@ -31,6 +31,11 @@
       "import": "./dist/contracts.mjs",
       "default": "./dist/contracts.mjs"
     },
+    "./errors": {
+      "types": "./dist/errors.d.mts",
+      "import": "./dist/errors.mjs",
+      "default": "./dist/errors.mjs"
+    },
     "./snapshot": {
       "types": "./dist/snapshot.d.mts",
       "import": "./dist/snapshot.mjs",
@@ -185,8 +190,8 @@
     "drizzle-orm": "1.0.0-rc.3",
     "icebird": "^0.8.8",
     "proper-lockfile": "^4.1.2",
-    "@gscdump/contracts": "0.25.14",
-    "gscdump": "0.25.14"
+    "@gscdump/contracts": "0.26.1",
+    "gscdump": "0.26.1"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",