@gscdump/engine 1.4.4 → 1.4.6

package/dist/entities.d.mts

@@ -1,8 +1,8 @@
 import { DataSource } from "./storage.mjs";
 import { ScheduleState } from "./schedule.mjs";
-import { SitemapGenerationKey, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey } from "./entity-keys.mjs";
-import { SITEMAP_PROJECTION_GRACE_MS, SitemapProjectionFeed, SitemapProjectionFiles, SitemapProjectionManifest, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, parseSitemapProjectionManifest, selectSitemapProjectionFiles, withSitemapProjectionFeed } from "./sitemap-projection.mjs";
+import { SitemapGenerationKey, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, inspectionTransitionsMonthKey, inspectionTransitionsPrefix, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey } from "./entity-keys.mjs";
 import { QueryDimDeps, QueryDimMeta, QueryDimRecord, QueryDimStore, buildQueryDimRecords, createQueryDimStore } from "./query-dim.mjs";
+import { SITEMAP_PROJECTION_GRACE_MS, SitemapProjectionFeed, SitemapProjectionFiles, SitemapProjectionManifest, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, parseSitemapProjectionManifest, selectSitemapProjectionFiles, withSitemapProjectionFeed } from "./sitemap-projection.mjs";
 import { TenantCtx } from "@gscdump/contracts";
 /**
  * GSC URL inspection result fields we persist. Mirrors the
@@ -200,10 +200,17 @@ interface InspectionStore {
    *
    * No-op (no base rewrite) when there are zero outstanding events.
    */
-  compactInspections: (ctx: TenantCtx) => Promise<{
+  compactInspections: (ctx: TenantCtx, opts?: {
+    /**
+     * Also record state changes into the durable transitions sidecar.
+     * Default OFF so publishing this is inert until a canary opts in.
+     */
+    transitions?: boolean;
+  }) => Promise<{
     baseRowCount: number;
     eventsFolded: number;
     eventFilesDeleted: number;
+    transitionsWritten: number;
   }>;
   /**
    * DuckDB-resolvable URI for the materialised parquet sidecar, or
@@ -460,4 +467,4 @@ interface CreateEmptyTypesStoreOptions {
   now?: () => number;
 }
 declare function createEmptyTypesStore(opts: CreateEmptyTypesStoreOptions): EmptyTypesStore;
-export { CompactUrlsOptions, CompactUrlsResult, CompleteSitemapGeneration, CreateEmptyTypesStoreOptions, CreateIndexingMetadataStoreOptions, CreateInspectionStoreOptions, CreateSitemapReadStoreOptions, CreateSitemapStoreOptions, DateRange, DeltaEntry, EmptyTypesDoc, EmptyTypesStore, INSPECTION_HISTORY_MAX_BYTES, IndexingMetadataIndex, IndexingMetadataRecord, IndexingMetadataStore, InspectionEventRow, InspectionHistoryShard, InspectionIndex, InspectionParquetRow, InspectionRecord, InspectionStore, LoadUrlsOptions, ParsedUrl, QueryDimDeps, QueryDimMeta, QueryDimRecord, QueryDimStore, ReconcileResult, SITEMAP_PROJECTION_GRACE_MS, SitemapGenerationKey, SitemapHistoryDoc, SitemapIndex, SitemapMembershipEvent, SitemapMutation, SitemapProjectionFeed, SitemapProjectionFiles, SitemapProjectionManifest, SitemapReadStore, SitemapRecord, SitemapStore, SitemapUrlRecord, SnapshotUrlsResult, buildQueryDimRecords, createEmptyTypesStore, createIndexingMetadataStore, createInspectionStore, createQueryDimStore, createSitemapReadStore, createSitemapStore, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, parseSitemapProjectionManifest, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, selectSitemapProjectionFiles, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey, withSitemapProjectionFeed };
+export { CompactUrlsOptions, CompactUrlsResult, CompleteSitemapGeneration, CreateEmptyTypesStoreOptions, CreateIndexingMetadataStoreOptions, CreateInspectionStoreOptions, CreateSitemapReadStoreOptions, CreateSitemapStoreOptions, DateRange, DeltaEntry, EmptyTypesDoc, EmptyTypesStore, INSPECTION_HISTORY_MAX_BYTES, IndexingMetadataIndex, IndexingMetadataRecord, IndexingMetadataStore, InspectionEventRow, InspectionHistoryShard, InspectionIndex, InspectionParquetRow, InspectionRecord, InspectionStore, LoadUrlsOptions, ParsedUrl, QueryDimDeps, QueryDimMeta, QueryDimRecord, QueryDimStore, ReconcileResult, SITEMAP_PROJECTION_GRACE_MS, SitemapGenerationKey, SitemapHistoryDoc, SitemapIndex, SitemapMembershipEvent, SitemapMutation, SitemapProjectionFeed, SitemapProjectionFiles, SitemapProjectionManifest, SitemapReadStore, SitemapRecord, SitemapStore, SitemapUrlRecord, SnapshotUrlsResult, buildQueryDimRecords, createEmptyTypesStore, createIndexingMetadataStore, createInspectionStore, createQueryDimStore, createSitemapReadStore, createSitemapStore, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, inspectionTransitionsMonthKey, inspectionTransitionsPrefix, parseSitemapProjectionManifest, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, selectSitemapProjectionFiles, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey, withSitemapProjectionFeed };

package/dist/entities.mjs

@@ -1,4 +1,4 @@
-import { emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey } from "./entity-keys.mjs";
+import { emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, inspectionTransitionsMonthKey, inspectionTransitionsPrefix, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey } from "./entity-keys.mjs";
 import { decodeParquetToRows, encodeRowsToParquetFlex } from "./adapters/hyparquet.mjs";
 import { readOptional } from "./adapters/read-optional.mjs";
 import { SITEMAP_PROJECTION_GRACE_MS, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, parseSitemapProjectionManifest, selectSitemapProjectionFiles, withSitemapProjectionFeed } from "./sitemap-projection.mjs";
@@ -157,6 +157,99 @@ const INSPECTION_EVENT_COLUMNS = [
 		nullable: true
 	}
 ];
+const TRANSITION_STATE_FIELDS = [
+	"indexStatus",
+	"coverageState",
+	"robotsTxtState",
+	"indexingState",
+	"pageFetchState",
+	"googleCanonical"
+];
+const INSPECTION_TRANSITION_COLUMNS = [
+	{
+		name: "urlHash",
+		type: "VARCHAR",
+		nullable: false
+	},
+	{
+		name: "url",
+		type: "VARCHAR",
+		nullable: false
+	},
+	{
+		name: "changedAfter",
+		type: "VARCHAR",
+		nullable: false
+	},
+	{
+		name: "changedBefore",
+		type: "VARCHAR",
+		nullable: false
+	},
+	...TRANSITION_STATE_FIELDS.flatMap((field) => {
+		const capped = field[0].toUpperCase() + field.slice(1);
+		return [{
+			name: `from${capped}`,
+			type: "VARCHAR",
+			nullable: true
+		}, {
+			name: `to${capped}`,
+			type: "VARCHAR",
+			nullable: true
+		}];
+	})
+];
+function isStateTransition(before, after) {
+	return TRANSITION_STATE_FIELDS.some((field) => (before[field] ?? null) !== (after[field] ?? null));
+}
+function buildTransitionRow(before, after) {
+	const row = {
+		urlHash: String(after.urlHash),
+		url: String(after.url ?? before.url ?? ""),
+		changedAfter: String(before.inspectedAt ?? ""),
+		changedBefore: String(after.inspectedAt ?? "")
+	};
+	for (const field of TRANSITION_STATE_FIELDS) {
+		const capped = field[0].toUpperCase() + field.slice(1);
+		row[`from${capped}`] = before[field] ?? null;
+		row[`to${capped}`] = after[field] ?? null;
+	}
+	return row;
+}
+async function appendTransitions(ds, ctx, rows) {
+	if (rows.length === 0) return 0;
+	const byMonth = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const month = transitionMonth(row);
+		const bucket = byMonth.get(month);
+		if (bucket) bucket.push(row);
+		else byMonth.set(month, [row]);
+	}
+	let written = 0;
+	for (const [month, monthRows] of byMonth) {
+		const key = inspectionTransitionsMonthKey(ctx, month);
+		const existingBytes = await readOptional(ds, key);
+		const existing = existingBytes ? await decodeParquetToRows(existingBytes) : [];
+		const seen = new Set(existing.map((r) => `${String(r.urlHash)}\u0000${String(r.changedBefore)}`));
+		const fresh = monthRows.filter((r) => {
+			const id = `${String(r.urlHash)}\u0000${String(r.changedBefore)}`;
+			if (seen.has(id)) return false;
+			seen.add(id);
+			return true;
+		});
+		if (fresh.length === 0) continue;
+		const merged = [...existing, ...fresh];
+		await ds.write(key, encodeRowsToParquetFlex(merged, {
+			columns: INSPECTION_TRANSITION_COLUMNS,
+			sortKey: ["urlHash"]
+		}));
+		written += fresh.length;
+	}
+	return written;
+}
+function transitionMonth(row) {
+	return String(row.changedBefore ?? "").slice(0, 7) || "unknown";
+}
 function createInspectionStore(opts) {
 	const ds = opts.dataSource;
 	function shardFor(record) {
@@ -250,22 +343,27 @@ function createInspectionStore(opts) {
 				rowCount: rows.length
 			};
 		},
-		async compactInspections(ctx) {
+		async compactInspections(ctx, opts) {
 			const eventKeys = (await ds.list(`${inspectionEventsPrefix(ctx)}/`)).filter((k) => INSPECTION_EVENT_KEY_RE.test(k));
 			if (eventKeys.length === 0) return {
 				baseRowCount: 0,
 				eventsFolded: 0,
-				eventFilesDeleted: 0
+				eventFilesDeleted: 0,
+				transitionsWritten: 0
 			};
 			const baseKey = inspectionBaseKey(ctx);
 			const baseBytes = await readOptional(ds, baseKey);
 			const baseRows = baseBytes ? await decodeParquetToRows(baseBytes) : [];
 			const latest = /* @__PURE__ */ new Map();
 			const earliestChecked = /* @__PURE__ */ new Map();
+			const transitions = [];
 			const consider = (row) => {
 				const h = String(row.urlHash);
 				const prev = latest.get(h);
-				if (!prev || String(row.inspectedAt ?? "") > String(prev.inspectedAt ?? "")) latest.set(h, row);
+				if (!prev || String(row.inspectedAt ?? "") > String(prev.inspectedAt ?? "")) {
+					if (opts?.transitions && prev && isStateTransition(prev, row)) transitions.push(buildTransitionRow(prev, row));
+					latest.set(h, row);
+				}
 				const fc = row.firstCheckedAt;
 				if (fc != null) {
 					const fcStr = String(fc);
@@ -304,11 +402,13 @@ function createInspectionStore(opts) {
 				sortKey: ["urlHash"]
 			});
 			await ds.write(baseKey, bytes);
+			const transitionsWritten = opts?.transitions ? await appendTransitions(ds, ctx, transitions) : 0;
 			if (consumed.length > 0) await ds.delete(consumed);
 			return {
 				baseRowCount: merged.length,
 				eventsFolded,
-				eventFilesDeleted: consumed.length
+				eventFilesDeleted: consumed.length,
+				transitionsWritten
 			};
 		},
 		parquetUri(ctx) {
@@ -1239,4 +1339,4 @@ function createEmptyTypesStore(opts) {
 		}
 	};
 }
-export { INSPECTION_HISTORY_MAX_BYTES, SITEMAP_PROJECTION_GRACE_MS, buildQueryDimRecords, createEmptyTypesStore, createIndexingMetadataStore, createInspectionStore, createQueryDimStore, createSitemapReadStore, createSitemapStore, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, parseSitemapProjectionManifest, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, selectSitemapProjectionFiles, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey, withSitemapProjectionFeed };
+export { INSPECTION_HISTORY_MAX_BYTES, SITEMAP_PROJECTION_GRACE_MS, buildQueryDimRecords, createEmptyTypesStore, createIndexingMetadataStore, createInspectionStore, createQueryDimStore, createSitemapReadStore, createSitemapStore, decodeSitemapProjectionManifest, emptySitemapProjectionManifest, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, inspectionTransitionsMonthKey, inspectionTransitionsPrefix, parseSitemapProjectionManifest, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, selectSitemapProjectionFiles, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey, withSitemapProjectionFeed };

package/dist/entity-keys.d.mts

@@ -5,6 +5,17 @@ declare function inspectionParquetKey(ctx: TenantCtx): string;
 declare function inspectionEventsPrefix(ctx: TenantCtx): string;
 declare function inspectionEventKey(ctx: TenantCtx, yearMonth: string, batchId: string): string;
 declare function inspectionBaseKey(ctx: TenantCtx): string;
+/**
+ * Append-only record of URL-inspection STATE CHANGES, partitioned by month.
+ *
+ * Distinct from `events/`, which compaction deletes. Google exposes no API for
+ * historical index-coverage state, so a verdict change observed once is gone
+ * the moment the event file folds — this is the only durable record that a URL
+ * ever left (or entered) the index.
+ */
+declare function inspectionTransitionsPrefix(ctx: TenantCtx): string;
+/** One file per calendar month (`YYYY-MM`), rewritten in place as it fills. */
+declare function inspectionTransitionsMonthKey(ctx: TenantCtx, yearMonth: string): string;
 declare function inspectionHistoryPrefix(ctx: TenantCtx, yearMonth: string): string;
 declare function inspectionHistoryShardKey(ctx: TenantCtx, yearMonth: string, batchId: string): string;
 /** Stable, URL-safe FNV-1a hash used for entity keys. */
@@ -40,4 +51,4 @@ declare function hashSortedUrlList(locs: readonly string[]): string;
 declare function indexingMetadataIndexKey(ctx: TenantCtx): string;
 declare function queryDimParquetKey(ctx: TenantCtx): string;
 declare function queryDimMetaKey(ctx: TenantCtx): string;
-export { SitemapGenerationKey, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey };
+export { SitemapGenerationKey, emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, inspectionTransitionsMonthKey, inspectionTransitionsPrefix, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey };

package/dist/entity-keys.mjs

@@ -19,6 +19,12 @@ function inspectionEventKey(ctx, yearMonth, batchId) {
 function inspectionBaseKey(ctx) {
 	return `${tenantEntityPrefix(ctx)}/inspections/base.parquet`;
 }
+function inspectionTransitionsPrefix(ctx) {
+	return `${tenantEntityPrefix(ctx)}/inspections/transitions`;
+}
+function inspectionTransitionsMonthKey(ctx, yearMonth) {
+	return `${inspectionTransitionsPrefix(ctx)}/${yearMonth}.parquet`;
+}
 function inspectionHistoryPrefix(ctx, yearMonth) {
 	return `${tenantEntityPrefix(ctx)}/inspections/history/${yearMonth}`;
 }
@@ -125,4 +131,4 @@ function queryDimParquetKey(ctx) {
 function queryDimMetaKey(ctx) {
 	return `${queryDimPrefix(ctx)}/index.json`;
 }
-export { emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey };
+export { emptyTypesKey, hashSortedUrlList, hashUrl, hashUrlList, indexingMetadataIndexKey, inspectionBaseKey, inspectionEventKey, inspectionEventsPrefix, inspectionHistoryPrefix, inspectionHistoryShardKey, inspectionIndexKey, inspectionParquetKey, inspectionTransitionsMonthKey, inspectionTransitionsPrefix, parseSitemapUrlsDeltaKey, queryDimMetaKey, queryDimParquetKey, sitemapHistoryKey, sitemapIndexKey, sitemapUrlsDeltaKey, sitemapUrlsEventKey, sitemapUrlsEventSeedKey, sitemapUrlsEventsPrefix, sitemapUrlsGenerationKey, sitemapUrlsIndexKey, sitemapUrlsIndexPrefix, sitemapUrlsPendingGenerationKey, sitemapUrlsPendingGenerationsPrefix, sitemapUrlsPrefix, sitemapUrlsProjectionManifestKey, sitemapUrlsReconcileGenerationKey };

package/dist/report/types.d.mts

@@ -2,7 +2,13 @@ import { AnalysisParams, AnalysisResult } from "../analysis-types.mjs";
 import { ComparisonMode, ResolvedWindow, WindowPreset } from "../period/index.mjs";
 /** Status vocabulary mirrors `ActionPrioritySourceStatus`. */
 type ReportStepStatus = 'pending' | 'running' | 'done' | 'skipped' | 'error';
-type ReportSeverity = 'info' | 'low' | 'medium' | 'high';
+/**
+ * `unknown` is not a rung on the info→high ladder: it means the section's
+ * backing analyzer(s) failed, so no severity could be assessed. The report
+ * runtime is the only writer — a report's `reduce` never returns it. See
+ * `ReportPlanStep.feeds`.
+ */
+type ReportSeverity = 'info' | 'low' | 'medium' | 'high' | 'unknown';
 type ReportEntityKind = 'page' | 'query';
 type ReportActionKind = 'analyzer' | 'cli' | 'indexing' | 'fix';
 type ReportCoverage = 'full' | 'partial';
@@ -72,6 +78,23 @@ interface ReportPlanStep {
   params: Omit<AnalysisParams, 'type'>;
   /** Required steps fail the report; optional steps degrade `coverage`. */
   required?: boolean;
+  /**
+   * Ids of the `ReportSection`s this step's result feeds. Defaults to
+   * `[key]`, which is the common case (section id === step key).
+   *
+   * This is what lets the runtime tell "the analyzer failed" apart from "the
+   * analyzer returned zero rows": a section whose feeding steps ALL errored
+   * carries no information, and the runtime replaces it with an explicit
+   * `severity: 'unknown'` shape instead of letting `reduce` publish
+   * aggregates computed over an empty array. A section fed by a mix of
+   * failed and successful steps still has real content and is left alone
+   * (its `coverage` stays `partial`).
+   *
+   * Declare it whenever a section id differs from the step key, or a step
+   * feeds several sections. `report-unavailable.test.ts` fails on any
+   * emitted section no step claims.
+   */
+  feeds?: readonly string[];
 }
 interface ReportStepStateMeta {
   key: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine",
   "type": "module",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Append-only Parquet/DuckDB storage engine + planner + adapters for the gscdump pipeline. Node + edge runtimes; opt-in heavy peers.",
   "author": {
     "name": "Harlan Wilton",
@@ -181,9 +181,9 @@
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
     "proper-lockfile": "^4.1.2",
-    "@gscdump/lakehouse": "^1.4.4",
-    "gscdump": "^1.4.4",
-    "@gscdump/contracts": "^1.4.4"
+    "@gscdump/contracts": "^1.4.6",
+    "gscdump": "^1.4.6",
+    "@gscdump/lakehouse": "^1.4.6"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "1.33.1-dev57.0",