seo 0.2.16 → 0.2.18

package/dist/mcp.js

@@ -1,5 +1,5 @@
 import { createRequire as __seoCreateRequire } from 'node:module'; const require = __seoCreateRequire(import.meta.url);
-import { n as load, t as version } from "./package-D_ix15KL.js";
+import { n as load, t as version } from "./package-DLnOXW-d.js";
 import { Headers, fetch as fetch$1 } from "undici";
 import { chmodSync, createReadStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { arch, homedir, platform, totalmem } from "node:os";
@@ -833,6 +833,111 @@ CREATE INDEX IF NOT EXISTS idx_keyword_set_tags_lookup
   ON keyword_set_tags(set_id, tag, normalized_keyword);
 `;
 //#endregion
+//#region packages/core/dist/rank-tracking/schema.js
+const RANK_TRACKING_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS rank_tracking_configs (
+  id TEXT PRIMARY KEY,
+  config_key TEXT NOT NULL UNIQUE,
+  project_id TEXT NOT NULL,
+  keyword_set_id TEXT NOT NULL,
+  target_domain TEXT NOT NULL,
+  tag TEXT,
+  market_json TEXT NOT NULL,
+  devices_json TEXT NOT NULL,
+  provider TEXT NOT NULL CHECK(provider IN ('dataforseo', 'semrush', 'ahrefs')),
+  collection_method TEXT NOT NULL CHECK(collection_method IN ('live', 'queued')),
+  cadence TEXT NOT NULL CHECK(cadence IN ('manual', 'daily', 'weekly', 'monthly')),
+  depth INTEGER NOT NULL CHECK(depth BETWEEN 1 AND 100),
+  keyword_limit INTEGER NOT NULL CHECK(keyword_limit BETWEEN 1 AND 1000),
+  next_run_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY(keyword_set_id) REFERENCES keyword_sets(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_rank_tracking_configs_project
+  ON rank_tracking_configs(project_id, updated_at DESC, id);
+CREATE INDEX IF NOT EXISTS idx_rank_tracking_configs_due
+  ON rank_tracking_configs(cadence, next_run_at, id);
+
+CREATE TABLE IF NOT EXISTS rank_tracking_runs (
+  id TEXT PRIMARY KEY,
+  config_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL UNIQUE,
+  state TEXT NOT NULL CHECK(state IN ('pending', 'partial', 'failed', 'complete')),
+  collection_method TEXT NOT NULL CHECK(collection_method IN ('live', 'queued')),
+  scheduled_for INTEGER NOT NULL,
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER,
+  keyword_count INTEGER NOT NULL,
+  task_count INTEGER NOT NULL,
+  snapshot_count INTEGER NOT NULL DEFAULT 0,
+  pending_count INTEGER NOT NULL,
+  failed_count INTEGER NOT NULL DEFAULT 0,
+  estimated_cost_micros INTEGER,
+  actual_cost_micros INTEGER,
+  config_snapshot_json TEXT NOT NULL,
+  error_summary TEXT,
+  FOREIGN KEY(config_id) REFERENCES rank_tracking_configs(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_rank_tracking_runs_config
+  ON rank_tracking_runs(config_id, started_at DESC, id DESC);
+DROP INDEX IF EXISTS idx_rank_tracking_active_run;
+CREATE UNIQUE INDEX idx_rank_tracking_active_run
+  ON rank_tracking_runs(config_id)
+  WHERE completed_at IS NULL;
+
+CREATE TABLE IF NOT EXISTS rank_tracking_tasks (
+  id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  normalized_keyword TEXT NOT NULL,
+  display_keyword TEXT NOT NULL,
+  device TEXT NOT NULL CHECK(device IN ('desktop', 'mobile')),
+  state TEXT NOT NULL CHECK(state IN ('pending', 'posting', 'posted', 'complete', 'failed')),
+  provider_task_id TEXT,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  posted_at INTEGER,
+  collected_at INTEGER,
+  error_code TEXT,
+  error_message TEXT,
+  UNIQUE(run_id, normalized_keyword, device),
+  UNIQUE(provider_task_id),
+  FOREIGN KEY(run_id) REFERENCES rank_tracking_runs(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_rank_tracking_tasks_run
+  ON rank_tracking_tasks(run_id, state, normalized_keyword, device);
+CREATE INDEX IF NOT EXISTS idx_rank_tracking_tasks_provider
+  ON rank_tracking_tasks(provider_task_id, state);
+
+CREATE TABLE IF NOT EXISTS rank_tracking_snapshots (
+  task_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  normalized_keyword TEXT NOT NULL,
+  display_keyword TEXT NOT NULL,
+  device TEXT NOT NULL CHECK(device IN ('desktop', 'mobile')),
+  observation_state TEXT NOT NULL CHECK(observation_state IN ('observed', 'not_observed_within_depth')),
+  organic_position INTEGER,
+  absolute_position INTEGER,
+  ranking_url TEXT,
+  observed_features_json TEXT NOT NULL,
+  checked_at TEXT NOT NULL,
+  provider TEXT NOT NULL CHECK(provider IN ('dataforseo', 'semrush', 'ahrefs')),
+  provider_task_id TEXT,
+  requested_depth INTEGER NOT NULL,
+  returned_rows INTEGER,
+  retained_rows INTEGER,
+  invalid_rows INTEGER NOT NULL,
+  completeness TEXT NOT NULL,
+  estimated_cost_micros INTEGER,
+  actual_cost_micros INTEGER,
+  warnings_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY(task_id) REFERENCES rank_tracking_tasks(id) ON DELETE CASCADE,
+  FOREIGN KEY(run_id) REFERENCES rank_tracking_runs(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_rank_tracking_snapshots_run
+  ON rank_tracking_snapshots(run_id, normalized_keyword, device);
+`;
+//#endregion
 //#region packages/core/dist/storage/cache-maintenance.js
 const MEBIBYTE$2 = 1024 * 1024;
 const CACHE_MAX_AGE_MS = 720 * 60 * 60 * 1e3;
@@ -1388,6 +1493,7 @@ function initDb(database, isNewDatabase) {
 	database.transaction(() => {
 		database.exec(CREATE_SQL);
 		database.exec(KEYWORD_SET_SCHEMA_SQL);
+		database.exec(RANK_TRACKING_SCHEMA_SQL);
 		database.exec(PROVIDER_SPEND_SCHEMA_SQL);
 		database.exec(`DELETE FROM semrush_cache WHERE request_json LIKE '%"key"%'`);
 		ensureColumn(database, "crawl_pages", "snapshot_json", "TEXT");
@@ -4533,7 +4639,7 @@ async function fetchPage(url, opts = {}, dependencies = {}) {
 }
 //#endregion
 //#region packages/core/dist/gsc/property-url.js
-function invalid$1(message) {
+function invalid$2(message) {
 	throw new SeoError("INVALID_INPUT", message);
 }
 function normalizeHttpUrl(value) {
@@ -4541,10 +4647,10 @@ function normalizeHttpUrl(value) {
 	try {
 		url = new URL(value.trim());
 	} catch {
-		return invalid$1(`Invalid URL: ${value}`);
+		return invalid$2(`Invalid URL: ${value}`);
 	}
-	if (url.protocol !== "http:" && url.protocol !== "https:") return invalid$1("The report URL must use http:// or https://.");
-	if (url.username || url.password) return invalid$1("The report URL must not contain embedded credentials.");
+	if (url.protocol !== "http:" && url.protocol !== "https:") return invalid$2("The report URL must use http:// or https://.");
+	if (url.username || url.password) return invalid$2("The report URL must not contain embedded credentials.");
 	url.hash = "";
 	return url.toString();
 }
@@ -4553,13 +4659,13 @@ function assertUrlMatchesGscProperty(property, value) {
 	const parsed = new URL(url);
 	if (property.startsWith("sc-domain:")) {
 		const domain = property.slice(10).trim().toLowerCase();
-		if (!domain || /[/:]/.test(domain)) return invalid$1(`Invalid Search Console domain property: ${property}`);
+		if (!domain || /[/:]/.test(domain)) return invalid$2(`Invalid Search Console domain property: ${property}`);
 		const hostname = parsed.hostname.toLowerCase();
-		if (hostname !== domain && !hostname.endsWith(`.${domain}`)) return invalid$1(`${url} is outside the Search Console property ${property}.`);
+		if (hostname !== domain && !hostname.endsWith(`.${domain}`)) return invalid$2(`${url} is outside the Search Console property ${property}.`);
 		return url;
 	}
 	const prefix = normalizeHttpUrl(property);
-	if (!url.startsWith(prefix)) return invalid$1(`${url} is outside the Search Console property ${property}.`);
+	if (!url.startsWith(prefix)) return invalid$2(`${url} is outside the Search Console property ${property}.`);
 	return url;
 }
 //#endregion
@@ -6643,7 +6749,7 @@ function selectBenchmarkRows$1(input) {
 function compareText$15(left, right) {
 	return left < right ? -1 : left > right ? 1 : 0;
 }
-function compareItems$1(left, right) {
+function compareItems$2(left, right) {
 	return (right.estimatedCtrClickShortfall ?? -1) - (left.estimatedCtrClickShortfall ?? -1) || right.impressions - left.impressions || left.position - right.position || compareText$15(left.query, right.query) || compareText$15(left.url, right.url);
 }
 function analyzeRow(input) {
@@ -6708,7 +6814,7 @@ function analyzePageOpportunitiesFromRows(input) {
 		reportInput: input,
 		benchmarkContext,
 		excludedTargetRows
-	})).sort(compareItems$1).slice(0, limit);
+	})).sort(compareItems$2).slice(0, limit);
 	const estimatedCtrClickShortfall = Number(items.reduce((sum, item) => sum + (item.estimatedCtrClickShortfall ?? 0), 0).toFixed(2));
 	return {
 		site: input.site,
@@ -16785,7 +16891,7 @@ function compareRetainedSegmentRows(input) {
 }
 //#endregion
 //#region packages/core/dist/analyze/segment-impact-analysis.js
-function verdict$4(input) {
+function verdict$5(input) {
 	if (input.status === "empty") return "Search Console returned no retained segment rows for either window.";
 	if (!input.matchedRows) return "No segment was retained in both windows, so no movement delta was inferred.";
 	const suffix = input.unmatchedRows ? ` ${input.unmatchedRows} one-window rows were kept as unmatched evidence and not converted to zero.` : "";
@@ -16878,7 +16984,7 @@ function analyzeSegmentRows(input) {
 			matchedRows: matched.length,
 			returnedRows: selection.returnedRows,
 			unmatchedRows: unmatched.length,
-			verdict: verdict$4({
+			verdict: verdict$5({
 				status: dataStatus,
 				matchedRows: matched.length,
 				returnedRows: selection.returnedRows,
@@ -17642,7 +17748,7 @@ const defaultDependencies$10 = {
 	searchAnalytics: querySearchAnalytics,
 	now: () => /* @__PURE__ */ new Date()
 };
-function verdict$3(input) {
+function verdict$4(input) {
 	if (input.status === "empty") return "Search Console returned no retained query/page rows for this window.";
 	if (!input.eligible) {
 		if (input.status === "partial") return "No material multi-URL query candidates remained in the validated retained rows, but partial evidence prevents an all-clear.";
@@ -17769,7 +17875,7 @@ async function cannibalReport(input, dependencies = defaultDependencies$10) {
 			returnedClusters: analysis.selection.returnedClusters,
 			suppressedQueries: analysis.selection.suppressedQueries,
 			brandFiltering: input.includeBrand ? "included" : "excluded",
-			verdict: verdict$3({
+			verdict: verdict$4({
 				status: dataStatus,
 				eligible: analysis.selection.eligibleClusters,
 				returned: analysis.selection.returnedClusters
@@ -18055,7 +18161,7 @@ const defaultDependencies$9 = {
 	searchAnalytics: querySearchAnalytics,
 	now: () => /* @__PURE__ */ new Date()
 };
-function verdict$2(report) {
+function verdict$3(report) {
 	if (report.dataStatus === "empty") return "Search Console returned no retained query/page rows for either comparison window.";
 	if (report.dataStatus === "partial" && report.selection.currentAggregatedRows === 0) return "The current retained-row window is empty, so no query/page losses were inferred.";
 	if (report.dataStatus === "partial" && report.selection.previousAggregatedRows === 0) return "The comparison retained-row window is empty, so query/page decay could not be measured.";
@@ -18200,7 +18306,7 @@ async function decayingReport(input, dependencies = defaultDependencies$9) {
 			observedRetainedQueryClickLoss: analysis.totals.eligibleObservedRetainedQueryClickLoss,
 			returnedObservedRetainedQueryClickLoss: analysis.totals.returnedObservedRetainedQueryClickLoss,
 			brandFiltering: input.includeBrand ? "included" : "excluded",
-			verdict: verdict$2(reportBase)
+			verdict: verdict$3(reportBase)
 		},
 		caveats: [
 			`Current window: ${currentRange.startDate} to ${currentRange.endDate}; comparison: ${previousRange.startDate} to ${previousRange.endDate}.`,
@@ -18994,7 +19100,7 @@ function templatesFromGroups(groups) {
 		sampleUrls: group.sampleUrls
 	}));
 }
-function verdict$1(analysis) {
+function verdict$2(analysis) {
 	if (analysis.dataStatus === "empty") return "Search Console returned no retained query/page rows for this date window.";
 	if (analysis.dataStatus === "filtered") return "No retained query/page rows met the report filters.";
 	return `${countLabel(analysis.summary.eligibleRows, "eligible query/page row")} found; ${countLabel(analysis.summary.returnedRows, "row")} returned for review.`;
@@ -19078,7 +19184,7 @@ async function strikingDistance(input, dependencies = defaultDependencies$7) {
 		summary: {
 			...analysis.summary,
 			brandFiltering: input.includeBrand ? "included" : "excluded",
-			verdict: verdict$1(analysis)
+			verdict: verdict$2(analysis)
 		},
 		caveats: [
 			`Date window: ${range.startDate} to ${range.endDate}, using final GSC data where available.`,
@@ -22178,7 +22284,10 @@ const userDataPriceSchema = z.object({
 		keyword_suggestions: livePriceSchema.optional(),
 		related_keywords: livePriceSchema.optional()
 	}).passthrough().optional(),
-	serp: z.object({ live: z.object({ advanced: normalPriorityPriceSchema.optional() }).passthrough().optional() }).passthrough().optional()
+	serp: z.object({
+		task_post: normalPriorityPriceSchema.optional(),
+		live: z.object({ advanced: normalPriorityPriceSchema.optional() }).passthrough().optional()
+	}).passthrough().optional()
 }).passthrough();
 const userDataResultSchema = z.object({
 	login: z.string().min(1).max(320),
@@ -22296,19 +22405,19 @@ const dataForSeoDiscoveryResponseSchema = z.object({
 }).passthrough();
 //#endregion
 //#region packages/core/dist/providers/dataforseo/paid-request.js
-function usdToMicros$1(value) {
+function usdToMicros(value) {
 	if (value === void 0) return null;
 	return Math.round(value * 1e6);
 }
 function responseTaskIds$1(response) {
 	return [...new Set(response.tasks.flatMap((task) => task.id ? [task.id] : []))].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
 }
-function responseCostMicros$1(response) {
-	if (response.cost !== void 0) return usdToMicros$1(response.cost);
+function responseCostMicros(response) {
+	if (response.cost !== void 0) return usdToMicros(response.cost);
 	if (response.tasks.some((task) => task.cost === void 0)) return null;
-	return response.tasks.reduce((sum, task) => sum + (usdToMicros$1(task.cost) ?? 0), 0);
+	return response.tasks.reduce((sum, task) => sum + (usdToMicros(task.cost) ?? 0), 0);
 }
-function taskErrorCode$1(statusCode) {
+function taskErrorCode(statusCode) {
 	if (statusCode >= 40100 && statusCode < 40200) return "authentication";
 	if (statusCode === 40202) return "rate-limit";
 	return "remote-error";
@@ -22398,7 +22507,7 @@ async function dataForSeoPaidPost(input) {
 		});
 		throw error;
 	}
-	const actualCostMicros = responseCostMicros$1(response);
+	const actualCostMicros = responseCostMicros(response);
 	const returnedRows = input.rowCount(response);
 	const taskIds = responseTaskIds$1(response);
 	const failedTasks = response.tasks.filter((task) => task.status_code !== 2e4);
@@ -22420,7 +22529,7 @@ async function dataForSeoPaidPost(input) {
 		throw new ProviderError({
 			provider: "dataforseo",
 			operation: input.operation,
-			code: taskErrorCode$1(statusCode),
+			code: taskErrorCode(statusCode),
 			message: `DataForSEO could not complete ${input.operation} (${statusCode}).`,
 			retryable: statusCode === 40202
 		});
@@ -22463,6 +22572,22 @@ async function dataForSeoPaidPost(input) {
 	};
 }
 //#endregion
+//#region packages/core/dist/providers/dataforseo/response.js
+function dataForSeoUsdToMicros(value) {
+	if (value === void 0) return null;
+	return Math.round(value * 1e6);
+}
+function dataForSeoTaskErrorCode(statusCode) {
+	if (statusCode >= 40100 && statusCode < 40200) return "authentication";
+	if (statusCode === 40202) return "rate-limit";
+	return "remote-error";
+}
+function dataForSeoResponseCostMicros(response) {
+	if (response.cost !== void 0) return dataForSeoUsdToMicros(response.cost);
+	if (response.tasks.some((task) => task.cost === void 0)) return null;
+	return response.tasks.reduce((sum, task) => sum + (dataForSeoUsdToMicros(task.cost) ?? 0), 0);
+}
+//#endregion
 //#region packages/core/dist/providers/dataforseo/serp-schema.js
 const serpItemSchema = z.object({
 	type: z.string().trim().min(1).max(100),
@@ -22507,6 +22632,237 @@ const dataForSeoSerpResponseSchema = z.object({
 	tasks: z.array(serpTaskSchema).max(10)
 }).passthrough();
 //#endregion
+//#region packages/core/dist/providers/dataforseo/serp-task-schema.js
+const taskPostItemSchema = z.object({
+	id: z.string().trim().min(1).max(100).optional(),
+	status_code: z.number().int(),
+	status_message: z.string().max(1e3),
+	cost: z.number().finite().nonnegative().optional(),
+	result_count: z.number().int().nonnegative().optional(),
+	data: z.object({ tag: z.string().trim().min(1).max(255).optional() }).passthrough().optional()
+}).passthrough();
+const dataForSeoSerpTaskPostResponseSchema = z.object({
+	status_code: z.number().int(),
+	status_message: z.string().max(1e3),
+	cost: z.number().finite().nonnegative().optional(),
+	tasks_count: z.number().int().nonnegative(),
+	tasks_error: z.number().int().nonnegative(),
+	tasks: z.array(taskPostItemSchema).max(100)
+}).passthrough();
+const readyResultSchema = z.object({
+	id: z.string().trim().min(1).max(100),
+	tag: z.string().trim().max(255).nullable().optional(),
+	se: z.string().trim().max(100).optional(),
+	se_type: z.string().trim().max(100).optional(),
+	endpoint_advanced: z.string().trim().max(2048).nullable().optional()
+}).passthrough();
+const readyTaskSchema = z.object({
+	id: z.string().trim().min(1).max(100).optional(),
+	status_code: z.number().int(),
+	status_message: z.string().max(1e3),
+	cost: z.number().finite().nonnegative().optional(),
+	result: z.array(readyResultSchema).max(1e3).nullable().optional()
+}).passthrough();
+const dataForSeoSerpTasksReadyResponseSchema = z.object({
+	status_code: z.number().int(),
+	status_message: z.string().max(1e3),
+	cost: z.number().finite().nonnegative().optional(),
+	tasks_count: z.number().int().nonnegative(),
+	tasks_error: z.number().int().nonnegative(),
+	tasks: z.array(readyTaskSchema).max(10)
+}).passthrough();
+//#endregion
+//#region packages/core/dist/providers/dataforseo/serp-tasks.js
+const SERP_TASK_POST_PATH = "v3/serp/google/organic/task_post";
+const SERP_TASKS_READY_PATH = "v3/serp/google/organic/tasks_ready";
+const SERP_TASK_GET_ADVANCED_PATH = "v3/serp/google/organic/task_get/advanced/";
+function dataForSeoSerpRows(response) {
+	return response.tasks.reduce((taskTotal, task) => taskTotal + (task.result ?? []).reduce((resultTotal, result) => resultTotal + (result.items?.length ?? 0), 0), 0);
+}
+function validateDataForSeoSerpTaskId(providerTaskId) {
+	if (!/^[a-zA-Z0-9-]{1,100}$/u.test(providerTaskId)) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-task-get",
+		code: "configuration",
+		message: "Use a valid queued SERP task id."
+	});
+}
+async function postDataForSeoSerpTasks(input, transport) {
+	const { price, requests } = input;
+	if (price.perRequestMicros === null || price.perResultMicros === null) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-task-post",
+		code: "invalid-response",
+		message: "DataForSEO Standard SERP pricing is unavailable, so queued tasks were not posted."
+	});
+	const requestUnits = requests.reduce((total, request) => total + Math.ceil(request.depth / 10), 0);
+	const estimatedCostMicros = price.perRequestMicros * requestUnits + price.perResultMicros * requests.length;
+	const reservation = reserveProviderSpend({
+		provider: "dataforseo",
+		capability: "serp-snapshot",
+		endpoint: SERP_TASK_POST_PATH,
+		projectId: input.context.projectId,
+		reportId: input.context.reportId,
+		reportRunId: input.context.reportRunId,
+		requestedRows: requests.length,
+		estimatedCostMicros
+	}, {
+		database: transport.database,
+		limits: transport.spendLimits,
+		now: transport.now().getTime()
+	});
+	let response;
+	try {
+		response = await providerRequestJson({
+			provider: "dataforseo",
+			operation: "serp-task-post",
+			url: new URL(SERP_TASK_POST_PATH, transport.baseUrl),
+			fetch: transport.fetch,
+			maxResponseBytes: transport.maxResponseBytes,
+			timeoutMs: transport.timeoutMs,
+			retry: "never",
+			schema: dataForSeoSerpTaskPostResponseSchema,
+			init: {
+				method: "POST",
+				headers: {
+					authorization: transport.authorization,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(requests)
+			}
+		});
+	} catch (error) {
+		finalizeProviderSpend(reservation.id, {
+			provider: "dataforseo",
+			state: "failed",
+			actualCostMicros: null,
+			returnedRows: null,
+			taskIds: []
+		}, {
+			database: transport.database,
+			limits: transport.spendLimits,
+			now: transport.now().getTime()
+		});
+		throw error;
+	}
+	const taskReceipts = response.tasks.flatMap((task) => task.id && task.data?.tag ? [{
+		providerTaskId: task.id,
+		tag: task.data.tag
+	}] : []);
+	const taskIds = taskReceipts.map((receipt) => receipt.providerTaskId);
+	const expectedTags = new Set(requests.map((request) => request.tag));
+	const returnedTags = new Set(taskReceipts.map((receipt) => receipt.tag));
+	const receiptsMatch = expectedTags.size === requests.length && returnedTags.size === expectedTags.size && [...expectedTags].every((tag) => returnedTags.has(tag));
+	const failedTasks = response.tasks.filter((task) => task.status_code !== 20100 || !task.id || !task.data?.tag);
+	const actualCostMicros = dataForSeoResponseCostMicros(response);
+	const state = failedTasks.length === 0 && response.tasks_error === 0 ? "succeeded" : failedTasks.length < response.tasks.length ? "partial" : "failed";
+	const spendNotice = finalizeProviderSpend(reservation.id, {
+		provider: "dataforseo",
+		state,
+		actualCostMicros,
+		returnedRows: taskIds.length,
+		taskIds
+	}, {
+		database: transport.database,
+		limits: transport.spendLimits,
+		now: transport.now().getTime()
+	});
+	if (response.status_code !== 2e4 || failedTasks.length > 0 || taskIds.length !== requests.length || !receiptsMatch) {
+		const statusCode = failedTasks[0]?.status_code ?? response.status_code;
+		throw new ProviderError({
+			provider: "dataforseo",
+			operation: "serp-task-post",
+			code: dataForSeoTaskErrorCode(statusCode),
+			message: `DataForSEO accepted ${taskIds.length} of ${requests.length} queued SERP tasks (${statusCode}).`
+		});
+	}
+	return {
+		taskIds,
+		taskReceipts,
+		estimatedCostMicros,
+		actualCostMicros,
+		spendNotice,
+		warnings: [],
+		observedAt: transport.now().toISOString()
+	};
+}
+async function listReadyDataForSeoSerpTasks(transport) {
+	const response = await providerRequestJson({
+		provider: "dataforseo",
+		operation: "serp-tasks-ready",
+		url: new URL(SERP_TASKS_READY_PATH, transport.baseUrl),
+		fetch: transport.fetch,
+		maxResponseBytes: transport.maxResponseBytes,
+		timeoutMs: transport.timeoutMs,
+		retry: "safe",
+		schema: dataForSeoSerpTasksReadyResponseSchema,
+		init: {
+			method: "GET",
+			headers: { authorization: transport.authorization }
+		}
+	});
+	const failedTask = response.tasks.find((task) => task.status_code !== 2e4);
+	if (response.status_code !== 2e4 || failedTask) {
+		const statusCode = failedTask?.status_code ?? response.status_code;
+		throw new ProviderError({
+			provider: "dataforseo",
+			operation: "serp-tasks-ready",
+			code: dataForSeoTaskErrorCode(statusCode),
+			message: `DataForSEO could not list ready SERP tasks (${statusCode}).`,
+			retryable: statusCode === 40202
+		});
+	}
+	return response.tasks.flatMap((task) => (task.result ?? []).map((result) => ({
+		providerTaskId: result.id,
+		tag: result.tag ?? null
+	})));
+}
+async function getDataForSeoSerpTask(providerTaskId, transport) {
+	const response = await providerRequestJson({
+		provider: "dataforseo",
+		operation: "serp-task-get",
+		url: new URL(`${SERP_TASK_GET_ADVANCED_PATH}${providerTaskId}`, transport.baseUrl),
+		fetch: transport.fetch,
+		maxResponseBytes: transport.maxResponseBytes,
+		timeoutMs: transport.timeoutMs,
+		retry: "safe",
+		schema: dataForSeoSerpResponseSchema,
+		init: {
+			method: "GET",
+			headers: { authorization: transport.authorization }
+		}
+	});
+	const failedTask = response.tasks.find((task) => task.status_code !== 2e4);
+	if (response.status_code !== 2e4 || failedTask) {
+		const statusCode = failedTask?.status_code ?? response.status_code;
+		throw new ProviderError({
+			provider: "dataforseo",
+			operation: "serp-task-get",
+			code: dataForSeoTaskErrorCode(statusCode),
+			message: `DataForSEO could not collect queued SERP task ${providerTaskId} (${statusCode}).`,
+			retryable: statusCode === 40202
+		});
+	}
+	return {
+		response,
+		observedAt: transport.now().toISOString(),
+		returnedRows: dataForSeoSerpRows(response),
+		cache: {
+			status: "bypass",
+			storedAt: null,
+			expiresAt: null
+		},
+		cost: {
+			currency: "USD",
+			estimatedMicros: 0,
+			actualMicros: dataForSeoResponseCostMicros(response) ?? 0,
+			taskIds: [providerTaskId]
+		},
+		spendNotice: null,
+		warnings: []
+	};
+}
+//#endregion
 //#region packages/core/dist/providers/dataforseo/client.js
 const DEFAULT_BASE_URL$1 = "https://api.dataforseo.com/";
 const USER_DATA_PATH = "v3/appendix/user_data";
@@ -22529,9 +22885,43 @@ const MAX_KEYWORD_WORDS = 10;
 const MAX_DISCOVERY_SEEDS$1 = 5;
 const MAX_DISCOVERY_ROWS$1 = 100;
 const MAX_SERP_DEPTH$1 = 100;
-function usdToMicros(value) {
-	if (value === void 0) return null;
-	return Math.round(value * 1e6);
+function validateSerpInput(input) {
+	const keyword = input.keyword.trim().replace(/\s+/gu, " ");
+	if (keyword.length < 1 || keyword.length > MAX_KEYWORD_CHARACTERS || keyword.split(/\s+/u).length > MAX_KEYWORD_WORDS) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-snapshot",
+		code: "configuration",
+		message: `SERP snapshots require a keyword of at most ${MAX_KEYWORD_CHARACTERS} characters and ${MAX_KEYWORD_WORDS} words.`
+	});
+	if (/(?:^|\s)(?:allinanchor|allintext|allintitle|allinurl|cache|define|definition|filetype|id|inanchor|info|intext|intitle|inurl|link|site):/iu.test(keyword)) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-snapshot",
+		code: "configuration",
+		message: "SERP snapshot keywords cannot contain search operators with multiplied provider pricing."
+	});
+	if (!Number.isSafeInteger(input.depth) || input.depth < 1 || input.depth > MAX_SERP_DEPTH$1) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-snapshot",
+		code: "configuration",
+		message: `SERP depth must be from 1 to ${MAX_SERP_DEPTH$1}.`
+	});
+	if (!/^[a-z]{2}$/.test(input.languageCode)) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-snapshot",
+		code: "configuration",
+		message: "DataForSEO language code must contain two lowercase letters."
+	});
+	const locationName = input.locationName?.trim();
+	if (input.locationCode !== void 0 === Boolean(locationName)) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-snapshot",
+		code: "configuration",
+		message: "DataForSEO SERP snapshots require exactly one location code or location name."
+	});
+	return {
+		keyword,
+		locationName
+	};
 }
 function unitPrice(components) {
 	const prices = components ?? [];
@@ -22557,19 +22947,12 @@ function keywordDiscoveryPrices(account) {
 function serpLiveAdvancedPrice(account) {
 	return unitPrice(account.price?.serp?.live?.advanced?.priority_normal);
 }
-function taskErrorCode(statusCode) {
-	if (statusCode >= 40100 && statusCode < 40200) return "authentication";
-	if (statusCode === 40202) return "rate-limit";
-	return "remote-error";
+function serpTaskPostPrice(account) {
+	return unitPrice(account.price?.serp?.task_post?.priority_normal);
 }
 function responseTaskIds(response) {
 	return [...new Set(response.tasks.flatMap((task) => task.id ? [task.id] : []))].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
 }
-function responseCostMicros(response) {
-	if (response.cost !== void 0) return usdToMicros(response.cost);
-	if (response.tasks.some((task) => task.cost === void 0)) return null;
-	return response.tasks.reduce((sum, task) => sum + (usdToMicros(task.cost) ?? 0), 0);
-}
 function responseRows$1(response) {
 	return response.tasks.reduce((taskTotal, task) => taskTotal + (task.result ?? []).reduce((resultTotal, result) => resultTotal + (result.items?.length ?? 0), 0), 0);
 }
@@ -22584,9 +22967,6 @@ function discoveryNextCursor(response) {
 	const cursors = response.tasks.flatMap((task) => (task.result ?? []).flatMap((result) => result.offset_token ? [result.offset_token] : []));
 	return cursors.length === 1 ? cursors[0] ?? null : null;
 }
-function serpRows(response) {
-	return response.tasks.reduce((taskTotal, task) => taskTotal + (task.result ?? []).reduce((resultTotal, result) => resultTotal + (result.items?.length ?? 0), 0), 0);
-}
 var DataForSeoClient = class {
 	fetch;
 	credentials;
@@ -22629,6 +23009,18 @@ var DataForSeoClient = class {
 	authorization(credentials) {
 		return `Basic ${Buffer.from(`${credentials.login}:${credentials.password}`).toString("base64")}`;
 	}
+	serpTaskTransport(credentials) {
+		return {
+			authorization: this.authorization(credentials),
+			baseUrl: this.baseUrl,
+			fetch: this.fetch,
+			maxResponseBytes: this.maxResponseBytes,
+			timeoutMs: this.timeoutMs,
+			now: this.now,
+			database: this.database,
+			spendLimits: this.spendLimits
+		};
+	}
 	async userDataForCredentials(credentials) {
 		let response;
 		try {
@@ -22663,7 +23055,7 @@ var DataForSeoClient = class {
 			throw new ProviderError({
 				provider: "dataforseo",
 				operation: "account-status",
-				code: taskErrorCode(statusCode),
+				code: dataForSeoTaskErrorCode(statusCode),
 				message: `DataForSEO could not return account status (${statusCode}).`,
 				retryable: statusCode === 40202
 			});
@@ -22679,18 +23071,19 @@ var DataForSeoClient = class {
 			provider: "dataforseo",
 			login: account.login,
 			timezone: account.timezone ?? null,
-			balanceMicros: usdToMicros(account.money?.balance),
-			depositedMicros: usdToMicros(account.money?.total),
-			accountDailySpendMicros: usdToMicros(account.money?.statistics?.day?.total),
+			balanceMicros: dataForSeoUsdToMicros(account.money?.balance),
+			depositedMicros: dataForSeoUsdToMicros(account.money?.total),
+			accountDailySpendMicros: dataForSeoUsdToMicros(account.money?.statistics?.day?.total),
 			accountDailySpendPeriod: account.money?.statistics?.day?.value ?? null,
-			accountDailyLimitMicros: usdToMicros(account.money?.limits?.day?.total),
+			accountDailyLimitMicros: dataForSeoUsdToMicros(account.money?.limits?.day?.total),
 			keywordOverviewPrice: keywordOverviewPrice(account),
 			keywordDiscoveryPrices: keywordDiscoveryPrices(account),
 			serpLiveAdvancedPrice: serpLiveAdvancedPrice(account),
+			serpTaskPostPrice: serpTaskPostPrice(account),
 			backlinksSubscriptionExpiresAt: account.backlinks_subscription_expiry_date ?? null,
 			aiMentionsSubscriptionExpiresAt: account.llm_mentions_subscription_expiry_date ?? null,
 			apiVersion: response.version ?? null,
-			requestCostMicros: usdToMicros(response.cost) ?? 0,
+			requestCostMicros: dataForSeoUsdToMicros(response.cost) ?? 0,
 			taskIds: response.tasks.flatMap((task) => task.id ? [task.id] : []),
 			observedAt: this.now().toISOString()
 		};
@@ -22866,7 +23259,7 @@ var DataForSeoClient = class {
 			});
 			throw error;
 		}
-		const actualCostMicros = responseCostMicros(response);
+		const actualCostMicros = dataForSeoResponseCostMicros(response);
 		const returnedRows = responseRows$1(response);
 		const taskIds = responseTaskIds(response);
 		const failedTasks = response.tasks.filter((task) => task.status_code !== 2e4);
@@ -22888,7 +23281,7 @@ var DataForSeoClient = class {
 			throw new ProviderError({
 				provider: "dataforseo",
 				operation: "keyword-metrics",
-				code: taskErrorCode(statusCode),
+				code: dataForSeoTaskErrorCode(statusCode),
 				message: `DataForSEO could not complete the keyword metrics task (${statusCode}).`,
 				retryable: statusCode === 40202
 			});
@@ -23000,38 +23393,7 @@ var DataForSeoClient = class {
 		};
 	}
 	async serpLive(input) {
-		const keyword = input.keyword.trim();
-		if (keyword.length < 1 || keyword.length > MAX_KEYWORD_CHARACTERS || keyword.split(/\s+/u).length > MAX_KEYWORD_WORDS) throw new ProviderError({
-			provider: "dataforseo",
-			operation: "serp-snapshot",
-			code: "configuration",
-			message: `SERP snapshots require a keyword of at most ${MAX_KEYWORD_CHARACTERS} characters and ${MAX_KEYWORD_WORDS} words.`
-		});
-		if (/(?:^|\s)(?:allinanchor|allintext|allintitle|allinurl|cache|define|definition|filetype|id|inanchor|info|intext|intitle|inurl|link|site):/iu.test(keyword)) throw new ProviderError({
-			provider: "dataforseo",
-			operation: "serp-snapshot",
-			code: "configuration",
-			message: "SERP snapshot keywords cannot contain search operators with multiplied provider pricing."
-		});
-		if (!Number.isSafeInteger(input.depth) || input.depth < 1 || input.depth > MAX_SERP_DEPTH$1) throw new ProviderError({
-			provider: "dataforseo",
-			operation: "serp-snapshot",
-			code: "configuration",
-			message: `SERP depth must be from 1 to ${MAX_SERP_DEPTH$1}.`
-		});
-		if (!/^[a-z]{2}$/.test(input.languageCode)) throw new ProviderError({
-			provider: "dataforseo",
-			operation: "serp-snapshot",
-			code: "configuration",
-			message: "DataForSEO language code must contain two lowercase letters."
-		});
-		const locationName = input.locationName?.trim();
-		if (input.locationCode !== void 0 === Boolean(locationName)) throw new ProviderError({
-			provider: "dataforseo",
-			operation: "serp-snapshot",
-			code: "configuration",
-			message: "DataForSEO SERP snapshots require exactly one location code or location name."
-		});
+		const { keyword, locationName } = validateSerpInput(input);
 		const request = {
 			keyword,
 			language_code: input.languageCode,
@@ -23052,9 +23414,56 @@ var DataForSeoClient = class {
 			context: input.context,
 			ttlMs: this.serpTtlMs,
 			refresh: input.refresh,
-			rowCount: serpRows
+			rowCount: dataForSeoSerpRows
+		});
+	}
+	async serpTaskPost(input) {
+		if (input.tasks.length < 1 || input.tasks.length > 100) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "serp-task-post",
+			code: "configuration",
+			message: `A queued SERP post requires 1 to 100 tasks.`
+		});
+		const requests = input.tasks.map((task) => {
+			const validated = validateSerpInput(task);
+			return {
+				keyword: validated.keyword,
+				language_code: task.languageCode,
+				...task.locationCode !== void 0 ? { location_code: task.locationCode } : { location_name: validated.locationName },
+				device: task.device,
+				depth: task.depth,
+				tag: task.tag,
+				priority: 1,
+				remove_from_url: ["srsltid"]
+			};
+		});
+		const credentials = await this.getCredentials("serp-task-post");
+		const credentialScope = providerCredentialScope("dataforseo", credentials.login);
+		const price = (await this.pricingForCredentials(credentials, credentialScope)).serpTaskPostPrice;
+		return postDataForSeoSerpTasks({
+			requests,
+			context: input.context,
+			price
+		}, {
+			authorization: this.authorization(credentials),
+			baseUrl: this.baseUrl,
+			fetch: this.fetch,
+			maxResponseBytes: this.maxResponseBytes,
+			timeoutMs: this.timeoutMs,
+			now: this.now,
+			database: this.database,
+			spendLimits: this.spendLimits
 		});
 	}
+	async serpTasksReady() {
+		const credentials = await this.getCredentials("serp-tasks-ready");
+		return listReadyDataForSeoSerpTasks(this.serpTaskTransport(credentials));
+	}
+	async serpTaskGet(providerTaskId) {
+		validateDataForSeoSerpTaskId(providerTaskId);
+		const credentials = await this.getCredentials("serp-task-get");
+		return getDataForSeoSerpTask(providerTaskId, this.serpTaskTransport(credentials));
+	}
 };
 //#endregion
 //#region packages/core/dist/providers/dataforseo/keyword-mapping.js
@@ -24338,7 +24747,7 @@ function pageItem(url, rows) {
 		recommendation: nextRecommendation
 	};
 }
-function compareItems(left, right) {
+function compareItems$1(left, right) {
 	return right.priority.score - left.priority.score || right.impressions - left.impressions || left.position - right.position || compareText$4(left.url, right.url);
 }
 function analyzeSecondPageRows(input) {
@@ -24383,7 +24792,7 @@ function analyzeSecondPageRows(input) {
 		if (item.impressions >= minImpressions) return true;
 		selection.belowMinimumPages++;
 		return false;
-	}).sort(compareItems);
+	}).sort(compareItems$1);
 	const items = eligibleItems.slice(0, limit);
 	selection.eligiblePages = eligibleItems.length;
 	selection.returnedPages = items.length;
@@ -25209,7 +25618,7 @@ async function defaultCandidates$1() {
 		priority: 10
 	}];
 }
-function providerError$1(error) {
+function providerError$2(error) {
 	if (!(error instanceof ProviderError)) throw error;
 	if (error.code === "rate-limit") throw new SeoError("RATE_LIMITED", error.message);
 	if (error.code === "configuration") throw new SeoError("INVALID_INPUT", error.message);
@@ -25277,7 +25686,7 @@ async function keywordResearchReport(input, dependencies = {}) {
 	try {
 		candidates = dependencies.candidates ?? await defaultCandidates$1();
 	} catch (error) {
-		return providerError$1(error);
+		return providerError$2(error);
 	}
 	const resolution = resolveProvider({
 		capability: "keyword-discovery",
@@ -25306,7 +25715,7 @@ async function keywordResearchReport(input, dependencies = {}) {
 			}
 		});
 	} catch (error) {
-		return providerError$1(error);
+		return providerError$2(error);
 	}
 	const analysis = evidence.data.map((idea) => ({
 		keyword: idea.keyword,
@@ -29852,6 +30261,96 @@ function checkedAt(value, fallback) {
 	const timestamp = Date.parse(value);
 	return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : fallback;
 }
+function mapDataForSeoSerpSnapshot(input, snapshot, endpoint = SERP_ENDPOINT) {
+	const market = searchMarketSchema.parse(input.market);
+	const keyword = normalizedKeyword$1(input.keyword);
+	const location = locationRequest(market, "serp-snapshot");
+	const result = snapshot.response.tasks.flatMap((task) => task.result ?? []).find((item) => normalizedKeyword$1(item.keyword) === keyword);
+	if (!result) throw new ProviderError({
+		provider: "dataforseo",
+		operation: "serp-snapshot",
+		code: "invalid-response",
+		message: "DataForSEO returned no matching SERP result."
+	});
+	const warnings = [...snapshot.warnings];
+	const items = result.items ?? [];
+	const organicItems = items.filter((item) => item.type === "organic");
+	const mappedOrganicResults = organicItems.flatMap((item) => {
+		const mapped = organicResult(item);
+		return mapped ? [mapped] : [];
+	}).sort((left, right) => left.rankAbsolute - right.rankAbsolute || left.rankGroup - right.rankGroup || compareCodepoints$3(left.url, right.url));
+	const organicResults = mappedOrganicResults.slice(0, input.depth);
+	const invalidRows = organicItems.length - mappedOrganicResults.length;
+	const resultCapped = mappedOrganicResults.length > input.depth;
+	const invalidResultCount = result.se_results_count !== null && result.se_results_count !== void 0 && result.se_results_count < organicResults.length;
+	if (invalidRows > 0) warnings.push({
+		code: "invalid-organic-results",
+		field: "organicResults",
+		message: `DataForSEO returned ${invalidRows} organic result${invalidRows === 1 ? "" : "s"} without a valid rank, domain, or URL.`
+	});
+	if (!Number.isFinite(Date.parse(result.datetime))) warnings.push({
+		code: "invalid-serp-observation-time",
+		field: "checkedAt",
+		message: "DataForSEO returned an invalid SERP observation time; the local response time was retained."
+	});
+	const checkUrl = safeUrl(result.check_url);
+	if (result.check_url && !checkUrl) warnings.push({
+		code: "invalid-serp-check-url",
+		field: "checkUrl",
+		message: "DataForSEO returned an invalid SERP check URL."
+	});
+	if (invalidResultCount) warnings.push({
+		code: "invalid-serp-result-count",
+		field: "resultCount",
+		message: "DataForSEO returned an estimated result count below the retained organic result count; the estimate was discarded."
+	});
+	const features = [.../* @__PURE__ */ new Set([...result.item_types ?? [], ...items.map((item) => item.type)])].sort(compareCodepoints$3);
+	return {
+		schemaVersion: 1,
+		provider: "dataforseo",
+		capability: "serp-snapshot",
+		data: {
+			keyword,
+			effectiveKeyword: normalizedKeyword$1(result.spell?.keyword ?? result.keyword),
+			searchEngineDomain: result.se_domain?.trim().toLowerCase() ?? null,
+			checkedAt: checkedAt(result.datetime, snapshot.observedAt),
+			checkUrl,
+			resultCount: invalidResultCount ? null : result.se_results_count ?? null,
+			pagesCount: result.pages_count === void 0 ? null : result.pages_count,
+			features,
+			organicResults
+		},
+		observedAt: snapshot.observedAt,
+		market: {
+			...market,
+			device: market.device ?? "desktop"
+		},
+		coverage: {
+			requestedRows: input.depth,
+			returnedRows: snapshot.returnedRows,
+			retainedRows: organicResults.length,
+			invalidRows,
+			providerTotalRows: invalidResultCount ? null : result.se_results_count ?? null,
+			completeness: invalidRows > 0 || invalidResultCount ? "partial" : resultCapped ? "capped" : "complete",
+			nextCursor: null
+		},
+		cache: snapshot.cache,
+		cost: snapshot.cost,
+		request: {
+			operation: "serp-snapshot",
+			endpoint,
+			limit: input.depth,
+			filters: {
+				countryCode: market.countryCode,
+				languageCode: market.languageCode,
+				device: market.device ?? "desktop",
+				...location.locationCode !== void 0 ? { locationCode: location.locationCode } : { locationName: location.locationName }
+			},
+			sort: ["rankAbsolute:ascending", "url:codepoint-ascending"]
+		},
+		warnings
+	};
+}
 var DataForSeoSerpSnapshotProvider = class {
 	provider = "dataforseo";
 	capabilitySupport = [{
@@ -29893,7 +30392,7 @@ var DataForSeoSerpSnapshotProvider = class {
 			reportRunId: randomUUID()
 		};
 		const location = locationRequest(market, "serp-snapshot");
-		const snapshot = await this.client.serpLive({
+		return mapDataForSeoSerpSnapshot(input, await this.client.serpLive({
 			keyword,
 			languageCode: market.languageCode.split("-")[0],
 			...location,
@@ -29901,92 +30400,7 @@ var DataForSeoSerpSnapshotProvider = class {
 			depth: input.depth,
 			refresh: input.refresh,
 			context
-		});
-		const result = snapshot.response.tasks.flatMap((task) => task.result ?? []).find((item) => normalizedKeyword$1(item.keyword) === keyword);
-		if (!result) throw new ProviderError({
-			provider: "dataforseo",
-			operation: "serp-snapshot",
-			code: "invalid-response",
-			message: "DataForSEO returned no matching SERP result."
-		});
-		const warnings = [...snapshot.warnings];
-		const items = result.items ?? [];
-		const organicItems = items.filter((item) => item.type === "organic");
-		const mappedOrganicResults = organicItems.flatMap((item) => {
-			const mapped = organicResult(item);
-			return mapped ? [mapped] : [];
-		}).sort((left, right) => left.rankAbsolute - right.rankAbsolute || left.rankGroup - right.rankGroup || compareCodepoints$3(left.url, right.url));
-		const organicResults = mappedOrganicResults.slice(0, input.depth);
-		const invalidRows = organicItems.length - mappedOrganicResults.length;
-		const resultCapped = mappedOrganicResults.length > input.depth;
-		const invalidResultCount = result.se_results_count !== null && result.se_results_count !== void 0 && result.se_results_count < organicResults.length;
-		if (invalidRows > 0) warnings.push({
-			code: "invalid-organic-results",
-			field: "organicResults",
-			message: `DataForSEO returned ${invalidRows} organic result${invalidRows === 1 ? "" : "s"} without a valid rank, domain, or URL.`
-		});
-		if (!Number.isFinite(Date.parse(result.datetime))) warnings.push({
-			code: "invalid-serp-observation-time",
-			field: "checkedAt",
-			message: "DataForSEO returned an invalid SERP observation time; the local response time was retained."
-		});
-		const checkUrl = safeUrl(result.check_url);
-		if (result.check_url && !checkUrl) warnings.push({
-			code: "invalid-serp-check-url",
-			field: "checkUrl",
-			message: "DataForSEO returned an invalid SERP check URL."
-		});
-		if (invalidResultCount) warnings.push({
-			code: "invalid-serp-result-count",
-			field: "resultCount",
-			message: "DataForSEO returned an estimated result count below the retained organic result count; the estimate was discarded."
-		});
-		const features = [.../* @__PURE__ */ new Set([...result.item_types ?? [], ...items.map((item) => item.type)])].sort(compareCodepoints$3);
-		return {
-			schemaVersion: 1,
-			provider: "dataforseo",
-			capability: "serp-snapshot",
-			data: {
-				keyword,
-				effectiveKeyword: normalizedKeyword$1(result.spell?.keyword ?? result.keyword),
-				searchEngineDomain: result.se_domain?.trim().toLowerCase() ?? null,
-				checkedAt: checkedAt(result.datetime, snapshot.observedAt),
-				checkUrl,
-				resultCount: invalidResultCount ? null : result.se_results_count ?? null,
-				pagesCount: result.pages_count === void 0 ? null : result.pages_count,
-				features,
-				organicResults
-			},
-			observedAt: snapshot.observedAt,
-			market: {
-				...market,
-				device: market.device ?? "desktop"
-			},
-			coverage: {
-				requestedRows: input.depth,
-				returnedRows: snapshot.returnedRows,
-				retainedRows: organicResults.length,
-				invalidRows,
-				providerTotalRows: invalidResultCount ? null : result.se_results_count ?? null,
-				completeness: invalidRows > 0 || invalidResultCount ? "partial" : resultCapped ? "capped" : "complete",
-				nextCursor: null
-			},
-			cache: snapshot.cache,
-			cost: snapshot.cost,
-			request: {
-				operation: "serp-snapshot",
-				endpoint: SERP_ENDPOINT,
-				limit: input.depth,
-				filters: {
-					countryCode: market.countryCode,
-					languageCode: market.languageCode,
-					device: market.device ?? "desktop",
-					...location.locationCode !== void 0 ? { locationCode: location.locationCode } : { locationName: location.locationName }
-				},
-				sort: ["rankAbsolute:ascending", "url:codepoint-ascending"]
-			},
-			warnings
-		};
+		}));
 	}
 };
 //#endregion
@@ -30005,7 +30419,7 @@ async function defaultCandidates() {
 		priority: 10
 	}];
 }
-function providerError(error) {
+function providerError$1(error) {
 	if (!(error instanceof ProviderError)) throw error;
 	if (error.code === "rate-limit") throw new SeoError("RATE_LIMITED", error.message);
 	if (error.code === "configuration") throw new SeoError("INVALID_INPUT", error.message);
@@ -30067,7 +30481,7 @@ async function serpResultsReport(input, dependencies = {}) {
 	try {
 		candidates = dependencies.candidates ?? await defaultCandidates();
 	} catch (error) {
-		return providerError(error);
+		return providerError$1(error);
 	}
 	const resolution = resolveProvider({
 		capability: "serp-snapshot",
@@ -30092,7 +30506,7 @@ async function serpResultsReport(input, dependencies = {}) {
 			}
 		});
 	} catch (error) {
-		return providerError(error);
+		return providerError$1(error);
 	}
 	const domains = domainSummaries(evidence.data);
 	const dataStatus = reportStatus$1(evidence);
@@ -30342,6 +30756,1110 @@ async function pseoOpportunitiesReport(input, dependencies = {}) {
 	};
 }
 //#endregion
+//#region packages/core/dist/keyword-sets/limits.js
+const KEYWORD_SET_LIMITS = {
+	setsPerProject: 25,
+	totalSets: 100,
+	keywordsPerSet: 1e4,
+	totalKeywords: 1e5,
+	mutationKeywords: 1e3,
+	tagsPerKeyword: 20,
+	outputRows: 1e3,
+	logicalBytes: 64 * 1024 * 1024
+};
+const KEYWORD_SET_FIELD_LIMITS = {
+	name: 80,
+	projectId: 80,
+	sourceReport: 100,
+	keyword: 80,
+	keywordWords: 10,
+	tag: 40,
+	url: 2048,
+	metricJsonBytes: 16 * 1024
+};
+//#endregion
+//#region packages/core/dist/keyword-sets/validation.js
+const unavailableValueSchema = z.strictObject({
+	state: z.enum([
+		"missing",
+		"unavailable",
+		"invalid"
+	]),
+	value: z.null(),
+	reason: z.string().min(1).max(500)
+});
+const providerValueNumberSchema = z.discriminatedUnion("state", [z.strictObject({
+	state: z.literal("observed"),
+	value: z.number().finite()
+}), unavailableValueSchema]);
+const providerValueStringSchema = z.discriminatedUnion("state", [z.strictObject({
+	state: z.literal("observed"),
+	value: z.string().max(500)
+}), unavailableValueSchema]);
+const monthlySearchSchema = z.strictObject({
+	year: z.number().int().min(2e3).max(2200),
+	month: z.number().int().min(1).max(12),
+	searchVolume: z.number().finite().nonnegative()
+});
+const providerValueMonthlySearchesSchema = z.discriminatedUnion("state", [z.strictObject({
+	state: z.literal("observed"),
+	value: z.array(monthlySearchSchema).max(24)
+}), unavailableValueSchema]);
+const keywordMetricSchema = z.strictObject({
+	keyword: z.string().min(1).max(KEYWORD_SET_FIELD_LIMITS.keyword),
+	monthlySearchVolume: providerValueNumberSchema,
+	monthlySearches: providerValueMonthlySearchesSchema,
+	searchVolumeUpdatedAt: providerValueStringSchema,
+	cpcUsd: providerValueNumberSchema,
+	paidCompetition: providerValueNumberSchema,
+	keywordDifficulty: providerValueNumberSchema,
+	intent: providerValueStringSchema,
+	resultCount: providerValueNumberSchema
+});
+const savedMetricSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	provider: providerIdSchema,
+	observedAt: z.iso.datetime(),
+	metric: keywordMetricSchema
+});
+function invalid$1(message) {
+	throw new SeoError("INVALID_INPUT", message);
+}
+function boundedText(value, label, max) {
+	const normalized = value.trim();
+	if (!normalized || normalized.length > max) invalid$1(`${label} must contain 1 to ${max} characters.`);
+	return normalized;
+}
+function normalizeSavedKeyword(value) {
+	const normalized = value.trim().replace(/\s+/gu, " ").toLowerCase();
+	if (!normalized || normalized.length > KEYWORD_SET_FIELD_LIMITS.keyword || normalized.split(" ").length > KEYWORD_SET_FIELD_LIMITS.keywordWords) invalid$1(`Keywords must contain 1 to ${KEYWORD_SET_FIELD_LIMITS.keyword} characters and at most ${KEYWORD_SET_FIELD_LIMITS.keywordWords} words.`);
+	return normalized;
+}
+function parseStoredJson(value, schema, label) {
+	let decoded;
+	try {
+		decoded = JSON.parse(value);
+	} catch {
+		throw new SeoError("INTERNAL_ERROR", `${label} contains invalid JSON.`);
+	}
+	const parsed = schema.safeParse(decoded);
+	if (!parsed.success) throw new SeoError("INTERNAL_ERROR", `${label} has an invalid shape.`);
+	return parsed.data;
+}
+//#endregion
+//#region packages/core/dist/keyword-sets/rows.js
+const SET_SELECT = `
+  SELECT sets.*,
+    (SELECT COUNT(*) FROM keyword_set_items items WHERE items.set_id = sets.id) AS keyword_count,
+    (SELECT COUNT(DISTINCT tags.tag) FROM keyword_set_tags tags WHERE tags.set_id = sets.id) AS tag_count
+  FROM keyword_sets sets`;
+function storeDatabase(options) {
+	return options.database ?? getDb();
+}
+function rowToSet(row) {
+	const provider = row.provider ? providerIdSchema.safeParse(row.provider) : void 0;
+	if (provider && !provider.success) throw new SeoError("INTERNAL_ERROR", "Saved keyword set provider is invalid.");
+	return {
+		schemaVersion: 1,
+		id: row.id,
+		projectId: row.project_id,
+		name: row.name,
+		market: parseStoredJson(row.market_json, searchMarketSchema, "Saved search market"),
+		provider: provider?.data ?? null,
+		sourceReport: row.source_report,
+		keywordCount: row.keyword_count,
+		tagCount: row.tag_count,
+		createdAt: new Date(row.created_at).toISOString(),
+		updatedAt: new Date(row.updated_at).toISOString(),
+		lastRefreshedAt: row.last_refreshed_at === null ? null : new Date(row.last_refreshed_at).toISOString()
+	};
+}
+function findSetRow(db, projectId, idOrName) {
+	return db.prepare(`${SET_SELECT}
+       WHERE sets.project_id = ?
+         AND (sets.id = ? OR sets.name = ? COLLATE NOCASE)
+       ORDER BY CASE WHEN sets.id = ? THEN 0 ELSE 1 END
+       LIMIT 1`).get(projectId, idOrName, idOrName, idOrName);
+}
+function requireSetRow(db, projectId, idOrName) {
+	const row = findSetRow(db, projectId, idOrName);
+	if (!row) invalid$1(`Keyword set not found: ${idOrName}`);
+	return row;
+}
+function rowCount(db, sql, ...params) {
+	return db.prepare(sql).get(...params).count;
+}
+//#endregion
+//#region packages/core/dist/keyword-sets/store.js
+function getKeywordSet(input, options = {}) {
+	const projectId = boundedText(input.projectId, "Project id", KEYWORD_SET_FIELD_LIMITS.projectId);
+	const idOrName = boundedText(input.idOrName, "Keyword set id or name", KEYWORD_SET_FIELD_LIMITS.name);
+	const tag = input.tag ? boundedText(input.tag, "Tag", KEYWORD_SET_FIELD_LIMITS.tag).toLowerCase() : null;
+	const limit = input.limit ?? 100;
+	const offset = input.offset ?? 0;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > KEYWORD_SET_LIMITS.outputRows) invalid$1(`Keyword set output limit must be from 1 to ${KEYWORD_SET_LIMITS.outputRows}.`);
+	if (!Number.isSafeInteger(offset) || offset < 0) invalid$1("Keyword set output offset must be zero or greater.");
+	const db = storeDatabase(options);
+	const setRow = requireSetRow(db, projectId, idOrName);
+	const filterSql = tag ? `AND EXISTS (
+        SELECT 1 FROM keyword_set_tags filter_tags
+        WHERE filter_tags.set_id = items.set_id
+          AND filter_tags.normalized_keyword = items.normalized_keyword
+          AND filter_tags.tag = ?
+      )` : "";
+	const params = tag ? [setRow.id, tag] : [setRow.id];
+	const total = rowCount(db, `SELECT COUNT(*) AS count FROM keyword_set_items items
+     WHERE items.set_id = ? ${filterSql}`, ...params);
+	const rows = db.prepare(`SELECT items.* FROM keyword_set_items items
+       WHERE items.set_id = ? ${filterSql}
+       ORDER BY items.normalized_keyword
+       LIMIT ? OFFSET ?`).all(...params, limit, offset);
+	const tagsByKeyword = loadTags(db, setRow.id, rows);
+	const items = rows.map((row) => itemFromRow(row, tagsByKeyword.get(row.normalized_keyword) ?? []));
+	return {
+		schemaVersion: 1,
+		set: rowToSet(setRow),
+		items,
+		pagination: {
+			offset,
+			limit,
+			returned: items.length,
+			total,
+			nextOffset: offset + items.length < total ? offset + items.length : null
+		},
+		filter: { tag }
+	};
+}
+function loadTags(db, setId, rows) {
+	if (rows.length === 0) return /* @__PURE__ */ new Map();
+	const tagRows = db.prepare(`SELECT normalized_keyword, tag FROM keyword_set_tags
+       WHERE set_id = ? AND normalized_keyword IN (${rows.map(() => "?").join(", ")})
+       ORDER BY normalized_keyword, tag`).all(setId, ...rows.map((row) => row.normalized_keyword));
+	const tagsByKeyword = /* @__PURE__ */ new Map();
+	for (const row of tagRows) {
+		const tags = tagsByKeyword.get(row.normalized_keyword) ?? [];
+		tags.push(row.tag);
+		tagsByKeyword.set(row.normalized_keyword, tags);
+	}
+	return tagsByKeyword;
+}
+function itemFromRow(row, tags) {
+	const latestMetric = row.metric_json ? parseStoredJson(row.metric_json, savedMetricSchema, "Saved keyword metric") : null;
+	if (latestMetric && (latestMetric.provider !== row.metric_provider || latestMetric.observedAt !== row.metric_observed_at || normalizeSavedKeyword(latestMetric.metric.keyword) !== row.normalized_keyword)) throw new SeoError("INTERNAL_ERROR", "Saved keyword metric metadata is inconsistent.");
+	const page = row.page_kind && row.page_url ? {
+		kind: row.page_kind,
+		url: row.page_url
+	} : null;
+	return {
+		keyword: row.display_keyword,
+		normalizedKeyword: row.normalized_keyword,
+		tags,
+		page,
+		latestMetric,
+		createdAt: new Date(row.created_at).toISOString(),
+		updatedAt: new Date(row.updated_at).toISOString()
+	};
+}
+//#endregion
+//#region packages/core/dist/rank-tracking/dataforseo-collector.js
+const QUEUED_RESULT_ENDPOINT = "v3/serp/google/organic/task_get/advanced/{taskId}";
+var DataForSeoRankTrackingCollector = class {
+	provider = "dataforseo";
+	client;
+	liveProvider;
+	constructor(options = {}) {
+		this.client = new DataForSeoClient(options);
+		this.liveProvider = new DataForSeoSerpSnapshotProvider({ client: this.client });
+	}
+	live(input) {
+		return this.liveProvider.serpSnapshot(input);
+	}
+	async post(input) {
+		const snapshot = await this.client.serpTaskPost({
+			tasks: input.tasks.map(({ taskKey, request }) => {
+				const market = request.market;
+				return {
+					tag: taskKey,
+					keyword: normalizedKeyword$1(request.keyword),
+					languageCode: market.languageCode.split("-")[0],
+					...locationRequest(market, "serp-snapshot"),
+					device: market.device ?? "desktop",
+					depth: request.depth
+				};
+			}),
+			context: input.context
+		});
+		return {
+			provider: this.provider,
+			receipts: snapshot.taskReceipts.map((receipt) => ({
+				taskKey: receipt.tag,
+				providerTaskId: receipt.providerTaskId
+			})),
+			estimatedCostMicros: snapshot.estimatedCostMicros,
+			actualCostMicros: snapshot.actualCostMicros,
+			warnings: snapshot.warnings
+		};
+	}
+	ready() {
+		return this.client.serpTasksReady().then((tasks) => tasks.map((task) => ({
+			providerTaskId: task.providerTaskId,
+			taskKey: task.tag
+		})));
+	}
+	async collect(input) {
+		const snapshot = await this.client.serpTaskGet(input.providerTaskId);
+		return mapDataForSeoSerpSnapshot(input.request, snapshot, QUEUED_RESULT_ENDPOINT);
+	}
+};
+//#endregion
+//#region packages/core/dist/rank-tracking/limits.js
+const RANK_TRACKING_LIMITS = {
+	configurationsPerProject: 25,
+	totalConfigurations: 100,
+	liveKeywordsPerRun: 50,
+	queuedKeywordsPerRun: 1e3,
+	devicesPerRun: 2,
+	tasksPerProviderPost: 100,
+	retainedRunsPerConfiguration: 90,
+	outputRows: 250,
+	logicalBytes: 256 * 1024 * 1024
+};
+//#endregion
+//#region packages/core/dist/rank-tracking/configuration-store.js
+function invalid(message) {
+	throw new SeoError("INVALID_INPUT", message);
+}
+function database(options) {
+	return options.database ?? getDb();
+}
+function parseJson(value, label) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		throw new SeoError("INTERNAL_ERROR", `${label} is corrupt.`);
+	}
+}
+function normalizeDomain(value) {
+	const raw = value.trim().toLowerCase();
+	if (!raw || raw.length > 253) invalid("Use a valid target domain.");
+	let hostname;
+	try {
+		hostname = new URL(raw.includes("://") ? raw : `https://${raw}`).hostname;
+	} catch {
+		invalid("Use a valid target domain.");
+	}
+	if (!hostname || hostname.length > 253 || hostname.includes("..") || !/^[a-z0-9.-]+$/u.test(hostname)) invalid("Use a valid target domain.");
+	return hostname.replace(/\.$/u, "");
+}
+function targetMatchesDomain(targetDomain, candidate) {
+	const target = normalizeDomain(targetDomain);
+	const host = normalizeDomain(candidate);
+	return host === target || host.endsWith(`.${target}`);
+}
+function configFromRow(row) {
+	const market = searchMarketSchema.safeParse(parseJson(row.market_json, "Saved rank market"));
+	const devices = parseJson(row.devices_json, "Saved rank devices");
+	const provider = providerIdSchema.safeParse(row.provider);
+	if (!market.success || market.data.device !== void 0 || !Array.isArray(devices) || devices.length < 1 || devices.length > 2 || devices.some((item) => item !== "desktop" && item !== "mobile") || !provider.success) throw new SeoError("INTERNAL_ERROR", "Saved rank tracking configuration is invalid.");
+	return {
+		schemaVersion: 1,
+		id: row.id,
+		projectId: row.project_id,
+		keywordSetId: row.keyword_set_id,
+		targetDomain: row.target_domain,
+		tag: row.tag,
+		market: market.data,
+		devices,
+		provider: provider.data,
+		collectionMethod: row.collection_method,
+		cadence: row.cadence,
+		depth: row.depth,
+		keywordLimit: row.keyword_limit,
+		nextRunAt: row.next_run_at === null ? null : new Date(row.next_run_at).toISOString(),
+		createdAt: new Date(row.created_at).toISOString(),
+		updatedAt: new Date(row.updated_at).toISOString()
+	};
+}
+function runFromRow(row) {
+	return {
+		schemaVersion: 1,
+		id: row.id,
+		configId: row.config_id,
+		state: row.state,
+		collectionMethod: row.collection_method,
+		scheduledFor: new Date(row.scheduled_for).toISOString(),
+		startedAt: new Date(row.started_at).toISOString(),
+		completedAt: row.completed_at === null ? null : new Date(row.completed_at).toISOString(),
+		keywordCount: row.keyword_count,
+		taskCount: row.task_count,
+		snapshotCount: row.snapshot_count,
+		pendingCount: row.pending_count,
+		failedCount: row.failed_count,
+		estimatedCostMicros: row.estimated_cost_micros,
+		actualCostMicros: row.actual_cost_micros,
+		errorSummary: row.error_summary
+	};
+}
+function taskFromRow(row) {
+	return {
+		id: row.id,
+		runId: row.run_id,
+		normalizedKeyword: row.normalized_keyword,
+		displayKeyword: row.display_keyword,
+		device: row.device,
+		state: row.state,
+		providerTaskId: row.provider_task_id,
+		attemptCount: row.attempt_count,
+		errorCode: row.error_code,
+		errorMessage: row.error_message
+	};
+}
+function observationFromRow(row) {
+	const provider = providerIdSchema.safeParse(row.provider);
+	if (!provider.success) throw new SeoError("INTERNAL_ERROR", "Saved rank provider is invalid.");
+	return {
+		taskId: row.task_id,
+		runId: row.run_id,
+		keyword: row.display_keyword,
+		normalizedKeyword: row.normalized_keyword,
+		device: row.device,
+		state: row.observation_state,
+		organicPosition: row.organic_position,
+		absolutePosition: row.absolute_position,
+		rankingUrl: row.ranking_url,
+		observedFeatures: parseJson(row.observed_features_json, "Saved rank features"),
+		checkedAt: row.checked_at,
+		provider: provider.data,
+		providerTaskId: row.provider_task_id,
+		requestedDepth: row.requested_depth,
+		returnedRows: row.returned_rows,
+		retainedRows: row.retained_rows,
+		invalidRows: row.invalid_rows,
+		completeness: row.completeness,
+		estimatedCostMicros: row.estimated_cost_micros,
+		actualCostMicros: row.actual_cost_micros,
+		warnings: parseJson(row.warnings_json, "Saved rank warnings")
+	};
+}
+function stableConfigKey(value) {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function nextRunAt(cadence, scheduledFor) {
+	if (cadence === "manual") return null;
+	const next = new Date(scheduledFor);
+	if (cadence === "daily") next.setUTCDate(next.getUTCDate() + 1);
+	if (cadence === "weekly") next.setUTCDate(next.getUTCDate() + 7);
+	if (cadence === "monthly") {
+		const desiredDay = next.getUTCDate();
+		next.setUTCDate(1);
+		next.setUTCMonth(next.getUTCMonth() + 1);
+		const lastDay = new Date(Date.UTC(next.getUTCFullYear(), next.getUTCMonth() + 1, 0)).getUTCDate();
+		next.setUTCDate(Math.min(desiredDay, lastDay));
+	}
+	return next.getTime();
+}
+function getOrCreateRankTrackingConfiguration(input, options = {}) {
+	const projectId = input.projectId.trim();
+	const keywordSetId = input.keywordSetId.trim();
+	const tag = input.tag?.trim().toLowerCase() || null;
+	if (!projectId || projectId.length > 80) invalid("Use a valid project id.");
+	if (!keywordSetId || keywordSetId.length > 80) invalid("Use a valid keyword set id.");
+	if (tag && tag.length > 40) invalid("Rank tracking tag is too long.");
+	const market = searchMarketSchema.safeParse(input.market);
+	if (!market.success) invalid("Use a valid rank tracking market.");
+	const { device: _ignoredDevice, ...marketWithoutDevice } = market.data;
+	const devices = [...new Set(input.devices)].sort();
+	if (devices.length < 1 || devices.length > 2 || devices.some((item) => item !== "desktop" && item !== "mobile")) invalid("Track desktop, mobile, or both devices.");
+	const provider = providerIdSchema.safeParse(input.provider);
+	if (!provider.success) invalid("Use a supported rank tracking provider.");
+	if (!["live", "queued"].includes(input.collectionMethod)) invalid("Use live or queued rank collection.");
+	if (![
+		"manual",
+		"daily",
+		"weekly",
+		"monthly"
+	].includes(input.cadence)) invalid("Use a supported rank tracking cadence.");
+	if (!Number.isSafeInteger(input.depth) || input.depth < 1 || input.depth > 100) invalid("Rank tracking depth must be from 1 to 100.");
+	const maxKeywords = input.collectionMethod === "live" ? RANK_TRACKING_LIMITS.liveKeywordsPerRun : RANK_TRACKING_LIMITS.queuedKeywordsPerRun;
+	if (!Number.isSafeInteger(input.keywordLimit) || input.keywordLimit < 1 || input.keywordLimit > maxKeywords) invalid(`${input.collectionMethod === "live" ? "Live" : "Queued"} rank tracking can collect 1 to ${maxKeywords} keywords per run.`);
+	const targetDomain = normalizeDomain(input.targetDomain);
+	const db = database(options);
+	const set = getKeywordSet({
+		projectId,
+		idOrName: keywordSetId,
+		limit: 1
+	}, { database: db }).set;
+	if (set.market.searchEngine !== marketWithoutDevice.searchEngine) invalid("The rank tracking search engine must match the keyword set.");
+	const configKey = stableConfigKey({
+		projectId,
+		keywordSetId: set.id,
+		targetDomain,
+		tag,
+		market: marketWithoutDevice,
+		devices,
+		provider: provider.data,
+		collectionMethod: input.collectionMethod,
+		cadence: input.cadence,
+		depth: input.depth,
+		keywordLimit: input.keywordLimit
+	});
+	const existing = db.prepare("SELECT * FROM rank_tracking_configs WHERE config_key = ?").get(configKey);
+	if (existing) return configFromRow(existing);
+	const total = db.prepare("SELECT COUNT(*) AS count FROM rank_tracking_configs").get().count;
+	const projectTotal = db.prepare("SELECT COUNT(*) AS count FROM rank_tracking_configs WHERE project_id = ?").get(projectId).count;
+	if (total >= RANK_TRACKING_LIMITS.totalConfigurations) invalid("Remove an unused rank tracking configuration before adding more.");
+	if (projectTotal >= RANK_TRACKING_LIMITS.configurationsPerProject) invalid("This project already has the maximum rank tracking configurations.");
+	const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	const id = (options.id ?? randomUUID)();
+	db.prepare(`INSERT INTO rank_tracking_configs
+     (id, config_key, project_id, keyword_set_id, target_domain, tag,
+      market_json, devices_json, provider, collection_method, cadence, depth,
+      keyword_limit, next_run_at, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, configKey, projectId, set.id, targetDomain, tag, JSON.stringify(marketWithoutDevice), JSON.stringify(devices), provider.data, input.collectionMethod, input.cadence, input.depth, input.keywordLimit, input.cadence === "manual" ? null : now, now, now);
+	return configFromRow(db.prepare("SELECT * FROM rank_tracking_configs WHERE id = ?").get(id));
+}
+//#endregion
+//#region packages/core/dist/rank-tracking/store.js
+function activeRankTrackingRun(configId, options = {}) {
+	const row = database(options).prepare(`SELECT * FROM rank_tracking_runs
+       WHERE config_id = ? AND completed_at IS NULL
+       ORDER BY scheduled_for DESC, id DESC LIMIT 1`).get(configId);
+	return row ? runFromRow(row) : null;
+}
+function startRankTrackingRun(input, options = {}) {
+	const db = database(options);
+	const active = activeRankTrackingRun(input.configuration.id, { database: db });
+	if (active) return active;
+	if (input.keywords.length < 1) invalid("The selected keyword set view is empty.");
+	const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	const scheduledFor = input.scheduledFor?.getTime() ?? now;
+	const runId = (options.id ?? randomUUID)();
+	const idempotencyKey = `${input.configuration.id}:${scheduledFor}`;
+	const taskCount = input.keywords.length * input.configuration.devices.length;
+	const create = db.transaction(() => {
+		db.prepare(`INSERT INTO rank_tracking_runs
+       (id, config_id, idempotency_key, state, collection_method, scheduled_for,
+        started_at, keyword_count, task_count, pending_count, config_snapshot_json)
+       VALUES (?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?)`).run(runId, input.configuration.id, idempotencyKey, input.configuration.collectionMethod, scheduledFor, now, input.keywords.length, taskCount, taskCount, JSON.stringify(input.configuration));
+		const insertTask = db.prepare(`INSERT INTO rank_tracking_tasks
+       (id, run_id, normalized_keyword, display_keyword, device, state)
+       VALUES (?, ?, ?, ?, ?, 'pending')`);
+		for (const keyword of input.keywords) for (const device of input.configuration.devices) insertTask.run((options.id ?? randomUUID)(), runId, keyword.normalizedKeyword, keyword.keyword, device);
+		db.prepare(`UPDATE rank_tracking_configs
+       SET next_run_at = ?, updated_at = ? WHERE id = ?`).run(nextRunAt(input.configuration.cadence, scheduledFor), now, input.configuration.id);
+	});
+	try {
+		create.immediate();
+	} catch (error) {
+		if (/unique constraint/i.test(String(error))) {
+			const recovered = activeRankTrackingRun(input.configuration.id, { database: db });
+			if (recovered) return recovered;
+		}
+		throw error;
+	}
+	return getRankTrackingRun(runId, { database: db });
+}
+function getRankTrackingRun(runId, options = {}) {
+	const row = database(options).prepare("SELECT * FROM rank_tracking_runs WHERE id = ?").get(runId);
+	if (!row) throw new SeoError("INTERNAL_ERROR", "Rank tracking run is missing.");
+	return runFromRow(row);
+}
+function rankTrackingTasks(runId, states, options = {}) {
+	const filter = states?.length ? ` AND state IN (${states.map(() => "?").join(", ")})` : "";
+	return database(options).prepare(`SELECT * FROM rank_tracking_tasks WHERE run_id = ?${filter}
+         ORDER BY normalized_keyword, device, id`).all(runId, ...states ?? []).map(taskFromRow);
+}
+function markRankTasksPosted(runId, receipts, cost, options = {}) {
+	const db = database(options);
+	const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	db.transaction(() => {
+		const statement = db.prepare(`UPDATE rank_tracking_tasks
+       SET state = 'posted', provider_task_id = ?, posted_at = ?,
+           attempt_count = attempt_count + 1, error_code = NULL,
+           error_message = NULL
+       WHERE id = ? AND run_id = ? AND state IN ('pending', 'posting')`);
+		for (const receipt of receipts) if (statement.run(receipt.providerTaskId, now, receipt.taskId, runId).changes !== 1) throw new SeoError("INTERNAL_ERROR", "A queued rank task changed before its receipt was saved.");
+		db.prepare(`UPDATE rank_tracking_runs
+       SET estimated_cost_micros = CASE
+             WHEN ? IS NULL THEN estimated_cost_micros
+             ELSE COALESCE(estimated_cost_micros, 0) + ? END,
+           actual_cost_micros = CASE
+             WHEN ? IS NULL THEN actual_cost_micros
+             ELSE COALESCE(actual_cost_micros, 0) + ? END
+       WHERE id = ?`).run(cost.estimatedMicros, cost.estimatedMicros, cost.actualMicros, cost.actualMicros, runId);
+	}).immediate();
+}
+function markRankTasksPosting(runId, taskIds, options = {}) {
+	if (taskIds.length === 0) return;
+	const db = database(options);
+	db.transaction(() => {
+		const statement = db.prepare(`UPDATE rank_tracking_tasks
+       SET state = 'posting', attempt_count = attempt_count + 1
+       WHERE id = ? AND run_id = ? AND state = 'pending'`);
+		for (const taskId of taskIds) if (statement.run(taskId, runId).changes !== 1) throw new SeoError("INTERNAL_ERROR", "A queued rank task changed before posting started.");
+	}).immediate();
+}
+function recoverRankTaskReceipt(input, options = {}) {
+	const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	database(options).prepare(`UPDATE rank_tracking_tasks
+       SET state = 'posted', provider_task_id = ?, posted_at = ?
+       WHERE id = ? AND state = 'posting'`).run(input.providerTaskId, now, input.taskId);
+}
+function saveRankObservations(observations, options = {}) {
+	if (observations.length === 0) return;
+	const runId = observations[0]?.runId;
+	if (!runId || observations.some((observation) => observation.runId !== runId)) throw new SeoError("INTERNAL_ERROR", "A rank observation batch must belong to one run.");
+	const db = database(options);
+	const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	db.transaction(() => {
+		const insertSnapshot = db.prepare(`INSERT OR IGNORE INTO rank_tracking_snapshots
+       (task_id, run_id, normalized_keyword, display_keyword, device,
+        observation_state, organic_position, absolute_position, ranking_url,
+        observed_features_json, checked_at, provider, provider_task_id,
+        requested_depth, returned_rows, retained_rows, invalid_rows,
+        completeness, estimated_cost_micros, actual_cost_micros, warnings_json,
+        created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+		const completeTask = db.prepare(`UPDATE rank_tracking_tasks
+       SET state = 'complete', collected_at = ?, error_code = NULL,
+           error_message = NULL WHERE id = ?`);
+		const addLiveCost = db.prepare(`UPDATE rank_tracking_runs
+       SET estimated_cost_micros = CASE
+             WHEN ? IS NULL THEN estimated_cost_micros
+             ELSE COALESCE(estimated_cost_micros, 0) + ? END,
+           actual_cost_micros = CASE
+             WHEN ? IS NULL THEN actual_cost_micros
+             ELSE COALESCE(actual_cost_micros, 0) + ? END
+       WHERE id = ? AND collection_method = 'live'`);
+		for (const observation of observations) {
+			const inserted = insertSnapshot.run(observation.taskId, observation.runId, observation.normalizedKeyword, observation.keyword, observation.device, observation.state, observation.organicPosition, observation.absolutePosition, observation.rankingUrl, JSON.stringify(observation.observedFeatures), observation.checkedAt, observation.provider, observation.providerTaskId, observation.requestedDepth, observation.returnedRows, observation.retainedRows, observation.invalidRows, observation.completeness, observation.estimatedCostMicros, observation.actualCostMicros, JSON.stringify(observation.warnings), now);
+			completeTask.run(now, observation.taskId);
+			if (inserted.changes === 1) addLiveCost.run(observation.estimatedCostMicros, observation.estimatedCostMicros, observation.actualCostMicros, observation.actualCostMicros, observation.runId);
+		}
+	}).immediate();
+	refreshRankTrackingRun(runId, {
+		database: db,
+		now: options.now
+	});
+}
+function failRankTrackingTask(input, options = {}) {
+	const db = database(options);
+	const row = db.prepare("SELECT run_id FROM rank_tracking_tasks WHERE id = ?").get(input.taskId);
+	if (!row) return;
+	db.prepare(`UPDATE rank_tracking_tasks
+     SET state = 'failed', attempt_count = attempt_count + 1,
+         error_code = ?, error_message = ? WHERE id = ?`).run(input.code.slice(0, 100), input.message.slice(0, 1e3), input.taskId);
+	refreshRankTrackingRun(row.run_id, {
+		database: db,
+		now: options.now
+	});
+}
+function refreshRankTrackingRun(runId, options = {}) {
+	const db = database(options);
+	const counts = db.prepare(`SELECT
+         SUM(CASE WHEN state = 'complete' THEN 1 ELSE 0 END) AS snapshots,
+         SUM(CASE WHEN state IN ('pending', 'posting', 'posted') THEN 1 ELSE 0 END) AS pending,
+         SUM(CASE WHEN state = 'failed' THEN 1 ELSE 0 END) AS failed
+       FROM rank_tracking_tasks WHERE run_id = ?`).get(runId);
+	const state = counts.pending > 0 ? counts.snapshots > 0 || counts.failed > 0 ? "partial" : "pending" : counts.failed > 0 ? counts.snapshots > 0 ? "partial" : "failed" : "complete";
+	const now = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	db.prepare(`UPDATE rank_tracking_runs
+     SET state = ?, snapshot_count = ?, pending_count = ?, failed_count = ?,
+         completed_at = CASE WHEN ? = 0 THEN ? ELSE NULL END,
+         error_summary = CASE WHEN ? > 0 THEN ? ELSE NULL END
+     WHERE id = ?`).run(state, counts.snapshots, counts.pending, counts.failed, counts.pending, now, counts.failed, `${counts.failed} rank task${counts.failed === 1 ? "" : "s"} failed.`, runId);
+	if (counts.pending === 0) pruneRankTrackingRuns(runId, {
+		...options,
+		database: db
+	});
+	return getRankTrackingRun(runId, { database: db });
+}
+function pruneRankTrackingRuns(runId, options = {}) {
+	const db = database(options);
+	const row = db.prepare("SELECT config_id FROM rank_tracking_runs WHERE id = ?").get(runId);
+	if (!row) return;
+	db.prepare(`DELETE FROM rank_tracking_runs
+     WHERE config_id = ? AND id IN (
+       SELECT id FROM rank_tracking_runs
+       WHERE config_id = ? AND completed_at IS NOT NULL
+       ORDER BY scheduled_for DESC, id DESC LIMIT -1 OFFSET ?
+     )`).run(row.config_id, row.config_id, RANK_TRACKING_LIMITS.retainedRunsPerConfiguration);
+	const maxBytes = options.maxLogicalBytes ?? RANK_TRACKING_LIMITS.logicalBytes;
+	while (rankTrackingLogicalBytes(db) > maxBytes) {
+		const oldest = db.prepare(`SELECT id FROM rank_tracking_runs
+         WHERE config_id = ? AND id <> ?
+           AND completed_at IS NOT NULL
+         ORDER BY scheduled_for, id LIMIT 1`).get(row.config_id, runId);
+		if (!oldest) break;
+		db.prepare("DELETE FROM rank_tracking_runs WHERE id = ?").run(oldest.id);
+	}
+	enforceRankTrackingLogicalBytes(db, maxBytes);
+}
+function latestRankTrackingRun(configId, options = {}) {
+	const row = database(options).prepare(`SELECT * FROM rank_tracking_runs WHERE config_id = ?
+       ORDER BY scheduled_for DESC, id DESC LIMIT 1`).get(configId);
+	return row ? runFromRow(row) : null;
+}
+function priorComparableRankTrackingRun(configId, currentRunId, options = {}) {
+	const row = database(options).prepare(`SELECT previous.* FROM rank_tracking_runs previous
+       JOIN rank_tracking_runs current ON current.id = ?
+       WHERE previous.config_id = ? AND previous.id <> current.id
+         AND previous.scheduled_for < current.scheduled_for
+         AND previous.snapshot_count > 0
+       ORDER BY previous.scheduled_for DESC, previous.id DESC LIMIT 1`).get(currentRunId, configId);
+	return row ? runFromRow(row) : null;
+}
+function rankObservations(runId, options = {}) {
+	return database(options).prepare(`SELECT * FROM rank_tracking_snapshots WHERE run_id = ?
+         ORDER BY normalized_keyword, device, task_id`).all(runId).map(observationFromRow);
+}
+function rankTrackingLogicalBytes(db = getDb()) {
+	return db.prepare(`SELECT
+       COALESCE((SELECT SUM(length(id) + length(config_key) + length(project_id) + length(keyword_set_id) + length(target_domain) + COALESCE(length(tag), 0) + length(market_json) + length(devices_json) + length(provider) + length(collection_method) + length(cadence)) FROM rank_tracking_configs), 0) +
+       COALESCE((SELECT SUM(length(id) + length(config_id) + length(idempotency_key) + length(state) + length(collection_method) + length(config_snapshot_json) + COALESCE(length(error_summary), 0)) FROM rank_tracking_runs), 0) +
+       COALESCE((SELECT SUM(length(id) + length(run_id) + length(normalized_keyword) + length(display_keyword) + length(device) + length(state) + COALESCE(length(provider_task_id), 0) + COALESCE(length(error_code), 0) + COALESCE(length(error_message), 0)) FROM rank_tracking_tasks), 0) +
+       COALESCE((SELECT SUM(length(task_id) + length(run_id) + length(normalized_keyword) + length(display_keyword) + length(device) + length(observation_state) + COALESCE(length(ranking_url), 0) + length(observed_features_json) + length(checked_at) + length(provider) + COALESCE(length(provider_task_id), 0) + length(completeness) + length(warnings_json)) FROM rank_tracking_snapshots), 0)
+       AS bytes`).get().bytes;
+}
+function enforceRankTrackingLogicalBytes(db, maxBytes = RANK_TRACKING_LIMITS.logicalBytes) {
+	if (rankTrackingLogicalBytes(db) > maxBytes) throw new SeoError("INVALID_INPUT", "Saved rank history reached its local storage limit. Remove an unused tracking configuration before collecting more.");
+}
+//#endregion
+//#region packages/core/dist/rank-tracking/run.js
+function providerError(error) {
+	if (!(error instanceof ProviderError)) return error instanceof SeoError ? error : new SeoError("INTERNAL_ERROR", "Rank collection failed unexpectedly.");
+	if (error.code === "rate-limit") return new SeoError("RATE_LIMITED", error.message);
+	if (error.code === "configuration") return new SeoError("INVALID_INPUT", error.message);
+	return new SeoError("PROVIDER_UNAVAILABLE", error.message);
+}
+async function defaultCollector(provider) {
+	if (provider !== "dataforseo") throw new SeoError("PROVIDER_UNAVAILABLE", `${provider} does not yet implement exact rank collection. Use DataForSEO for this report.`);
+	if (!await readDataForSeoCredentials()) throw new SeoError("PROVIDER_UNAVAILABLE", "DataForSEO is not connected. Run `seo providers dataforseo connect` first.");
+	return new DataForSeoRankTrackingCollector();
+}
+function requestForTask(configuration, task) {
+	return {
+		keyword: task.displayKeyword,
+		market: {
+			...configuration.market,
+			device: task.device
+		},
+		depth: configuration.depth,
+		refresh: true,
+		context: {
+			projectId: configuration.projectId,
+			reportId: "rank-tracking",
+			reportRunId: task.runId
+		}
+	};
+}
+function observationFromEvidence(configuration, task, evidence) {
+	const match = evidence.data.organicResults.find((result) => {
+		try {
+			return targetMatchesDomain(configuration.targetDomain, result.domain);
+		} catch {
+			return false;
+		}
+	});
+	return {
+		taskId: task.id,
+		runId: task.runId,
+		keyword: task.displayKeyword,
+		normalizedKeyword: task.normalizedKeyword,
+		device: task.device,
+		state: match ? "observed" : "not_observed_within_depth",
+		organicPosition: match?.rankGroup ?? null,
+		absolutePosition: match?.rankAbsolute ?? null,
+		rankingUrl: match?.url ?? null,
+		observedFeatures: evidence.data.features,
+		checkedAt: evidence.data.checkedAt,
+		provider: evidence.provider,
+		providerTaskId: task.providerTaskId,
+		requestedDepth: configuration.depth,
+		returnedRows: evidence.coverage.returnedRows,
+		retainedRows: evidence.coverage.retainedRows,
+		invalidRows: evidence.coverage.invalidRows,
+		completeness: evidence.coverage.completeness,
+		estimatedCostMicros: evidence.cost.estimatedMicros,
+		actualCostMicros: evidence.cost.actualMicros,
+		warnings: evidence.warnings
+	};
+}
+async function inBoundedParallel(items, concurrency, operation) {
+	let next = 0;
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+		while (next < items.length) {
+			const index = next;
+			next += 1;
+			const item = items[index];
+			if (item) await operation(item);
+		}
+	});
+	await Promise.all(workers);
+}
+async function collectLive(configuration, run, collector, dependencies) {
+	const tasks = rankTrackingTasks(run.id, ["pending"], dependencies);
+	const observations = [];
+	const warnings = [];
+	await inBoundedParallel(tasks, 3, async (task) => {
+		try {
+			const evidence = await collector.live(requestForTask(configuration, task));
+			observations.push(observationFromEvidence(configuration, task, evidence));
+		} catch (error) {
+			const mapped = providerError(error);
+			failRankTrackingTask({
+				taskId: task.id,
+				code: mapped.code,
+				message: mapped.message
+			}, dependencies);
+			warnings.push(`${task.displayKeyword} (${task.device}): ${mapped.message}`);
+		}
+	});
+	saveRankObservations(observations, dependencies);
+	return {
+		collected: observations.length,
+		warnings
+	};
+}
+async function collectQueued(configuration, run, collector, dependencies) {
+	if (!collector.post || !collector.ready || !collector.collect) throw new SeoError("PROVIDER_UNAVAILABLE", `${collector.provider} does not support queued rank collection. Use live collection or another provider.`);
+	const warnings = [];
+	const observations = [];
+	let posted = 0;
+	let ready = [];
+	try {
+		ready = await collector.ready();
+	} catch (error) {
+		const mapped = providerError(error);
+		warnings.push(`The provider ready list was unavailable; saved task IDs will still be checked: ${mapped.message}`);
+	}
+	const byTaskKey = new Map(ready.flatMap((item) => item.taskKey ? [[item.taskKey, item.providerTaskId]] : []));
+	for (const task of rankTrackingTasks(run.id, ["posting"], dependencies)) {
+		const providerTaskId = byTaskKey.get(task.id);
+		if (providerTaskId) recoverRankTaskReceipt({
+			taskId: task.id,
+			providerTaskId
+		}, dependencies);
+	}
+	await inBoundedParallel(rankTrackingTasks(run.id, ["posted"], dependencies).filter((task) => task.providerTaskId), 5, async (task) => {
+		try {
+			const evidence = await collector.collect?.({
+				providerTaskId: task.providerTaskId,
+				request: requestForTask(configuration, task)
+			});
+			if (!evidence) return;
+			observations.push(observationFromEvidence(configuration, task, evidence));
+		} catch (error) {
+			const mapped = providerError(error);
+			warnings.push(`${task.displayKeyword} (${task.device}): ${mapped.message}`);
+		}
+	});
+	saveRankObservations(observations, dependencies);
+	const pending = rankTrackingTasks(run.id, ["pending"], dependencies);
+	for (let offset = 0; offset < pending.length; offset += RANK_TRACKING_LIMITS.tasksPerProviderPost) {
+		const batch = pending.slice(offset, offset + RANK_TRACKING_LIMITS.tasksPerProviderPost);
+		markRankTasksPosting(run.id, batch.map((task) => task.id), dependencies);
+		try {
+			const result = await collector.post({
+				tasks: batch.map((task) => ({
+					taskKey: task.id,
+					request: requestForTask(configuration, task)
+				})),
+				context: {
+					projectId: configuration.projectId,
+					reportId: "rank-tracking",
+					reportRunId: run.id
+				}
+			});
+			const receiptByKey = new Map(result.receipts.map((receipt) => [receipt.taskKey, receipt]));
+			if (receiptByKey.size !== batch.length) throw new SeoError("PROVIDER_UNAVAILABLE", "The provider did not return one receipt for every queued rank task.");
+			markRankTasksPosted(run.id, batch.map((task) => ({
+				taskId: task.id,
+				providerTaskId: receiptByKey.get(task.id)?.providerTaskId ?? ""
+			})), {
+				estimatedMicros: result.estimatedCostMicros,
+				actualMicros: result.actualCostMicros
+			}, dependencies);
+			posted += batch.length;
+			warnings.push(...result.warnings.map((warning) => warning.message));
+		} catch (error) {
+			const mapped = providerError(error);
+			warnings.push(`${batch.length} queued task${batch.length === 1 ? "" : "s"} remain in recovery after posting was interrupted: ${mapped.message}`);
+			break;
+		}
+	}
+	return {
+		collected: observations.length,
+		posted,
+		warnings
+	};
+}
+function due(configuration, now) {
+	return configuration.cadence === "manual" || configuration.nextRunAt === null || Date.parse(configuration.nextRunAt) <= now.getTime();
+}
+async function executeRankTracking(input, dependencies = {}) {
+	const cadence = input.cadence ?? "manual";
+	const collectionMethod = input.collectionMethod ?? (cadence === "manual" ? "live" : "queued");
+	const keywordLimit = input.keywordLimit ?? (collectionMethod === "live" ? 25 : 100);
+	const set = getKeywordSet({
+		projectId: input.projectId,
+		idOrName: input.set,
+		tag: input.tag,
+		limit: keywordLimit
+	}, dependencies);
+	const provider = input.provider ?? set.set.provider ?? "dataforseo";
+	const defaultDevice = set.set.market.device ?? "desktop";
+	const configuration = getOrCreateRankTrackingConfiguration({
+		projectId: input.projectId,
+		keywordSetId: set.set.id,
+		targetDomain: input.targetDomain,
+		tag: input.tag,
+		market: set.set.market,
+		devices: input.devices ?? [defaultDevice],
+		provider,
+		collectionMethod,
+		cadence,
+		depth: input.depth ?? 100,
+		keywordLimit
+	}, dependencies);
+	const warnings = [];
+	let run = activeRankTrackingRun(configuration.id, dependencies);
+	let startedRun = false;
+	let collectedTasks = 0;
+	let postedTasks = 0;
+	if (!run && (input.start ?? true) && due(configuration, dependencies.now?.() ?? /* @__PURE__ */ new Date())) {
+		run = startRankTrackingRun({
+			configuration,
+			keywords: set.items.map((item) => ({
+				keyword: item.keyword,
+				normalizedKeyword: item.normalizedKeyword
+			}))
+		}, {
+			...dependencies,
+			id: dependencies.id ?? randomUUID
+		});
+		startedRun = true;
+	}
+	if (run) {
+		const collector = dependencies.collector ?? await (dependencies.collectorFactory ?? defaultCollector)(provider);
+		if (collector.provider !== provider) throw new SeoError("INTERNAL_ERROR", "The selected rank collector does not match the saved provider.");
+		if (configuration.collectionMethod === "live") {
+			const result = await collectLive(configuration, run, collector, dependencies);
+			collectedTasks += result.collected;
+			warnings.push(...result.warnings);
+		} else {
+			const result = await collectQueued(configuration, run, collector, dependencies);
+			collectedTasks += result.collected;
+			postedTasks += result.posted;
+			warnings.push(...result.warnings);
+		}
+		run = latestRankTrackingRun(configuration.id, dependencies);
+	} else run = latestRankTrackingRun(configuration.id, dependencies);
+	return {
+		configuration,
+		run,
+		startedRun,
+		collectedTasks,
+		postedTasks,
+		operationalWarnings: warnings.slice(0, 20)
+	};
+}
+//#endregion
+//#region packages/core/dist/analyze/rank-tracking.js
+function key$1(item) {
+	return `${item.normalizedKeyword}\u0000${item.device}`;
+}
+function changeFor(current, previous) {
+	if (!previous) return {
+		change: "no-history",
+		organicPositionDelta: null,
+		rankingUrlChanged: false
+	};
+	const rankingUrlChanged = current.state === "observed" && previous.state === "observed" && current.rankingUrl !== previous.rankingUrl;
+	if (current.state === "observed" && previous.state === "not_observed_within_depth") return {
+		change: "new",
+		organicPositionDelta: null,
+		rankingUrlChanged
+	};
+	if (current.state === "not_observed_within_depth" && previous.state === "observed") return {
+		change: "lost",
+		organicPositionDelta: null,
+		rankingUrlChanged
+	};
+	if (current.organicPosition !== null && previous.organicPosition !== null) {
+		const delta = previous.organicPosition - current.organicPosition;
+		return {
+			change: delta > 0 ? "improved" : delta < 0 ? "declined" : "unchanged",
+			organicPositionDelta: delta,
+			rankingUrlChanged
+		};
+	}
+	return {
+		change: "unchanged",
+		organicPositionDelta: null,
+		rankingUrlChanged
+	};
+}
+const CHANGE_ORDER = {
+	lost: 0,
+	declined: 1,
+	new: 2,
+	improved: 3,
+	unchanged: 4,
+	"no-history": 5
+};
+function compareItems(left, right) {
+	return CHANGE_ORDER[left.change] - CHANGE_ORDER[right.change] || Math.abs(right.organicPositionDelta ?? 0) - Math.abs(left.organicPositionDelta ?? 0) || (left.normalizedKeyword < right.normalizedKeyword ? -1 : left.normalizedKeyword > right.normalizedKeyword ? 1 : left.device < right.device ? -1 : left.device > right.device ? 1 : 0);
+}
+function reportItems(current, previous, pending) {
+	const previousByKey = new Map(previous.map((item) => [key$1(item), item]));
+	const items = current.map((item) => {
+		const prior = previousByKey.get(key$1(item));
+		const change = changeFor(item, prior);
+		return {
+			keyword: item.keyword,
+			normalizedKeyword: item.normalizedKeyword,
+			device: item.device,
+			state: item.state,
+			organicPosition: item.organicPosition,
+			absolutePosition: item.absolutePosition,
+			rankingUrl: item.rankingUrl,
+			checkedAt: item.checkedAt,
+			previous: prior ? {
+				state: prior.state,
+				organicPosition: prior.organicPosition,
+				absolutePosition: prior.absolutePosition,
+				rankingUrl: prior.rankingUrl,
+				checkedAt: prior.checkedAt
+			} : null,
+			...change,
+			error: null
+		};
+	});
+	const observedKeys = new Set(current.map(key$1));
+	for (const task of pending) {
+		if (observedKeys.has(key$1(task))) continue;
+		const prior = previousByKey.get(key$1(task));
+		items.push({
+			keyword: task.displayKeyword,
+			normalizedKeyword: task.normalizedKeyword,
+			device: task.device,
+			state: task.state === "failed" ? "failed" : "pending",
+			organicPosition: null,
+			absolutePosition: null,
+			rankingUrl: null,
+			checkedAt: null,
+			previous: prior ? {
+				state: prior.state,
+				organicPosition: prior.organicPosition,
+				absolutePosition: prior.absolutePosition,
+				rankingUrl: prior.rankingUrl,
+				checkedAt: prior.checkedAt
+			} : null,
+			change: "no-history",
+			organicPositionDelta: null,
+			rankingUrlChanged: false,
+			error: task.state === "failed" ? {
+				code: task.errorCode,
+				message: task.errorMessage
+			} : null
+		});
+	}
+	return items.sort(compareItems);
+}
+function verdict$1(run, counts) {
+	if (!run) return "No rank tracking run has started for this configuration.";
+	if (run.pendingCount > 0) return `${run.snapshotCount} of ${run.taskCount} market and device-specific snapshots are collected; ${run.pendingCount} remain pending.`;
+	if (run.failedCount > 0) return `${run.snapshotCount} snapshots were collected and ${run.failedCount} failed; use the completed rows as partial evidence.`;
+	if (counts.improved + counts.declined + counts.newCount + counts.lost > 0) return `${counts.improved} improved, ${counts.declined} declined, ${counts.newCount} became observed, and ${counts.lost} were no longer observed within the tracked depth.`;
+	return `${counts.observed} rankings were observed and ${counts.notObserved} were not observed within the tracked depth.`;
+}
+async function rankTrackingReport(input, dependencies = {}) {
+	const outputLimit = input.outputLimit ?? 100;
+	if (!Number.isSafeInteger(outputLimit) || outputLimit < 1 || outputLimit > 250) throw new SeoError("INVALID_INPUT", "Rank tracking output limit must be from 1 to 250.");
+	const execution = await executeRankTracking(input, dependencies);
+	const { configuration, run } = execution;
+	const current = run ? rankObservations(run.id, dependencies) : [];
+	const priorRun = run ? priorComparableRankTrackingRun(configuration.id, run.id, dependencies) : null;
+	const allItems = reportItems(current, priorRun ? rankObservations(priorRun.id, dependencies) : [], run ? rankTrackingTasks(run.id, void 0, dependencies) : []);
+	const count = (change) => allItems.filter((item) => item.change === change).length;
+	const observed = current.filter((item) => item.state === "observed").length;
+	const notObserved = current.length - observed;
+	const improved = count("improved");
+	const declined = count("declined");
+	const newCount = count("new");
+	const lost = count("lost");
+	const unchanged = count("unchanged");
+	const rankingUrlChanges = allItems.filter((item) => item.rankingUrlChanged).length;
+	const items = allItems.slice(0, outputLimit);
+	const dataStatus = !run ? "unavailable" : run.state === "complete" ? "complete" : run.state === "pending" ? "pending" : "partial";
+	return {
+		schemaVersion: 1,
+		generatedAt: (dependencies.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+		dataStatus,
+		configuration,
+		run,
+		comparison: {
+			priorRunId: priorRun?.id ?? null,
+			priorStartedAt: priorRun?.startedAt ?? null,
+			comparableItems: allItems.filter((item) => item.previous !== null).length
+		},
+		summary: {
+			trackedKeywords: run?.keywordCount ?? 0,
+			trackedDevices: configuration.devices.length,
+			expectedSnapshots: run?.taskCount ?? 0,
+			completedSnapshots: run?.snapshotCount ?? 0,
+			pendingSnapshots: run?.pendingCount ?? 0,
+			failedSnapshots: run?.failedCount ?? 0,
+			observed,
+			notObservedWithinDepth: notObserved,
+			new: newCount,
+			lost,
+			improved,
+			declined,
+			unchanged,
+			rankingUrlChanges,
+			verdict: verdict$1(run, {
+				observed,
+				notObserved,
+				improved,
+				declined,
+				newCount,
+				lost
+			})
+		},
+		items,
+		coverage: {
+			totalItems: allItems.length,
+			returnedItems: items.length,
+			outputLimit,
+			omittedItems: allItems.length - items.length,
+			requestedDepth: configuration.depth,
+			collectionMethod: configuration.collectionMethod,
+			runState: run?.state ?? "not-started"
+		},
+		cost: {
+			currency: "USD",
+			estimatedMicros: run?.estimatedCostMicros ?? null,
+			actualMicros: run?.actualCostMicros ?? null
+		},
+		operationalWarnings: execution.operationalWarnings,
+		caveats: [
+			`Not observed means the target domain was not retained within the first ${configuration.depth} organic results for that exact market and device. It is not proof that the domain does not rank elsewhere.`,
+			"Exact snapshots and Search Console average position answer different questions and should not be substituted for one another.",
+			"Local, national, desktop, and mobile snapshots remain separate configurations and are never blended into one position.",
+			"Search results can change between checks and may differ from signed-in or personalized results.",
+			...run?.state === "partial" || run?.state === "failed" ? ["Failed or pending tasks make this run partial; do not treat missing rows as losses."] : []
+		],
+		nextSteps: [
+			...run?.pendingCount ? ["Run the same report parameters again after queued tasks are ready; collection is free and resumes from saved task IDs."] : [],
+			"Use Search Console opportunity reports to add clicks, impressions, and average-position context before prioritising a ranking change.",
+			"Inspect ranking URL changes for intent drift or competing templates before changing content.",
+			configuration.cadence === "manual" ? "Use queued collection with a daily, weekly, or monthly cadence when this set needs recurring local tracking." : "Run this report from local cron at the configured cadence; overlapping runs are refused and schedule advancement is deterministic."
+		]
+	};
+}
+//#endregion
 //#region packages/core/dist/analyze/reports/dates.js
 function rangeDays(range) {
 	const start = Date.parse(`${range.startDate}T00:00:00Z`);
@@ -30807,211 +32325,6 @@ function reportPresentation(report) {
 	};
 }
 //#endregion
-//#region packages/core/dist/keyword-sets/limits.js
-const KEYWORD_SET_LIMITS = {
-	setsPerProject: 25,
-	totalSets: 100,
-	keywordsPerSet: 1e4,
-	totalKeywords: 1e5,
-	mutationKeywords: 1e3,
-	tagsPerKeyword: 20,
-	outputRows: 1e3,
-	logicalBytes: 64 * 1024 * 1024
-};
-const KEYWORD_SET_FIELD_LIMITS = {
-	name: 80,
-	projectId: 80,
-	sourceReport: 100,
-	keyword: 80,
-	keywordWords: 10,
-	tag: 40,
-	url: 2048,
-	metricJsonBytes: 16 * 1024
-};
-//#endregion
-//#region packages/core/dist/keyword-sets/validation.js
-const unavailableValueSchema = z.strictObject({
-	state: z.enum([
-		"missing",
-		"unavailable",
-		"invalid"
-	]),
-	value: z.null(),
-	reason: z.string().min(1).max(500)
-});
-const providerValueNumberSchema = z.discriminatedUnion("state", [z.strictObject({
-	state: z.literal("observed"),
-	value: z.number().finite()
-}), unavailableValueSchema]);
-const providerValueStringSchema = z.discriminatedUnion("state", [z.strictObject({
-	state: z.literal("observed"),
-	value: z.string().max(500)
-}), unavailableValueSchema]);
-const monthlySearchSchema = z.strictObject({
-	year: z.number().int().min(2e3).max(2200),
-	month: z.number().int().min(1).max(12),
-	searchVolume: z.number().finite().nonnegative()
-});
-const providerValueMonthlySearchesSchema = z.discriminatedUnion("state", [z.strictObject({
-	state: z.literal("observed"),
-	value: z.array(monthlySearchSchema).max(24)
-}), unavailableValueSchema]);
-const keywordMetricSchema = z.strictObject({
-	keyword: z.string().min(1).max(KEYWORD_SET_FIELD_LIMITS.keyword),
-	monthlySearchVolume: providerValueNumberSchema,
-	monthlySearches: providerValueMonthlySearchesSchema,
-	searchVolumeUpdatedAt: providerValueStringSchema,
-	cpcUsd: providerValueNumberSchema,
-	paidCompetition: providerValueNumberSchema,
-	keywordDifficulty: providerValueNumberSchema,
-	intent: providerValueStringSchema,
-	resultCount: providerValueNumberSchema
-});
-const savedMetricSchema = z.strictObject({
-	schemaVersion: z.literal(1),
-	provider: providerIdSchema,
-	observedAt: z.iso.datetime(),
-	metric: keywordMetricSchema
-});
-function invalid(message) {
-	throw new SeoError("INVALID_INPUT", message);
-}
-function boundedText(value, label, max) {
-	const normalized = value.trim();
-	if (!normalized || normalized.length > max) invalid(`${label} must contain 1 to ${max} characters.`);
-	return normalized;
-}
-function normalizeSavedKeyword(value) {
-	const normalized = value.trim().replace(/\s+/gu, " ").toLowerCase();
-	if (!normalized || normalized.length > KEYWORD_SET_FIELD_LIMITS.keyword || normalized.split(" ").length > KEYWORD_SET_FIELD_LIMITS.keywordWords) invalid(`Keywords must contain 1 to ${KEYWORD_SET_FIELD_LIMITS.keyword} characters and at most ${KEYWORD_SET_FIELD_LIMITS.keywordWords} words.`);
-	return normalized;
-}
-function parseStoredJson(value, schema, label) {
-	let decoded;
-	try {
-		decoded = JSON.parse(value);
-	} catch {
-		throw new SeoError("INTERNAL_ERROR", `${label} contains invalid JSON.`);
-	}
-	const parsed = schema.safeParse(decoded);
-	if (!parsed.success) throw new SeoError("INTERNAL_ERROR", `${label} has an invalid shape.`);
-	return parsed.data;
-}
-//#endregion
-//#region packages/core/dist/keyword-sets/rows.js
-const SET_SELECT = `
-  SELECT sets.*,
-    (SELECT COUNT(*) FROM keyword_set_items items WHERE items.set_id = sets.id) AS keyword_count,
-    (SELECT COUNT(DISTINCT tags.tag) FROM keyword_set_tags tags WHERE tags.set_id = sets.id) AS tag_count
-  FROM keyword_sets sets`;
-function storeDatabase(options) {
-	return options.database ?? getDb();
-}
-function rowToSet(row) {
-	const provider = row.provider ? providerIdSchema.safeParse(row.provider) : void 0;
-	if (provider && !provider.success) throw new SeoError("INTERNAL_ERROR", "Saved keyword set provider is invalid.");
-	return {
-		schemaVersion: 1,
-		id: row.id,
-		projectId: row.project_id,
-		name: row.name,
-		market: parseStoredJson(row.market_json, searchMarketSchema, "Saved search market"),
-		provider: provider?.data ?? null,
-		sourceReport: row.source_report,
-		keywordCount: row.keyword_count,
-		tagCount: row.tag_count,
-		createdAt: new Date(row.created_at).toISOString(),
-		updatedAt: new Date(row.updated_at).toISOString(),
-		lastRefreshedAt: row.last_refreshed_at === null ? null : new Date(row.last_refreshed_at).toISOString()
-	};
-}
-function findSetRow(db, projectId, idOrName) {
-	return db.prepare(`${SET_SELECT}
-       WHERE sets.project_id = ?
-         AND (sets.id = ? OR sets.name = ? COLLATE NOCASE)
-       ORDER BY CASE WHEN sets.id = ? THEN 0 ELSE 1 END
-       LIMIT 1`).get(projectId, idOrName, idOrName, idOrName);
-}
-function requireSetRow(db, projectId, idOrName) {
-	const row = findSetRow(db, projectId, idOrName);
-	if (!row) invalid(`Keyword set not found: ${idOrName}`);
-	return row;
-}
-function rowCount(db, sql, ...params) {
-	return db.prepare(sql).get(...params).count;
-}
-//#endregion
-//#region packages/core/dist/keyword-sets/store.js
-function getKeywordSet(input, options = {}) {
-	const projectId = boundedText(input.projectId, "Project id", KEYWORD_SET_FIELD_LIMITS.projectId);
-	const idOrName = boundedText(input.idOrName, "Keyword set id or name", KEYWORD_SET_FIELD_LIMITS.name);
-	const tag = input.tag ? boundedText(input.tag, "Tag", KEYWORD_SET_FIELD_LIMITS.tag).toLowerCase() : null;
-	const limit = input.limit ?? 100;
-	const offset = input.offset ?? 0;
-	if (!Number.isSafeInteger(limit) || limit < 1 || limit > KEYWORD_SET_LIMITS.outputRows) invalid(`Keyword set output limit must be from 1 to ${KEYWORD_SET_LIMITS.outputRows}.`);
-	if (!Number.isSafeInteger(offset) || offset < 0) invalid("Keyword set output offset must be zero or greater.");
-	const db = storeDatabase(options);
-	const setRow = requireSetRow(db, projectId, idOrName);
-	const filterSql = tag ? `AND EXISTS (
-        SELECT 1 FROM keyword_set_tags filter_tags
-        WHERE filter_tags.set_id = items.set_id
-          AND filter_tags.normalized_keyword = items.normalized_keyword
-          AND filter_tags.tag = ?
-      )` : "";
-	const params = tag ? [setRow.id, tag] : [setRow.id];
-	const total = rowCount(db, `SELECT COUNT(*) AS count FROM keyword_set_items items
-     WHERE items.set_id = ? ${filterSql}`, ...params);
-	const rows = db.prepare(`SELECT items.* FROM keyword_set_items items
-       WHERE items.set_id = ? ${filterSql}
-       ORDER BY items.normalized_keyword
-       LIMIT ? OFFSET ?`).all(...params, limit, offset);
-	const tagsByKeyword = loadTags(db, setRow.id, rows);
-	const items = rows.map((row) => itemFromRow(row, tagsByKeyword.get(row.normalized_keyword) ?? []));
-	return {
-		schemaVersion: 1,
-		set: rowToSet(setRow),
-		items,
-		pagination: {
-			offset,
-			limit,
-			returned: items.length,
-			total,
-			nextOffset: offset + items.length < total ? offset + items.length : null
-		},
-		filter: { tag }
-	};
-}
-function loadTags(db, setId, rows) {
-	if (rows.length === 0) return /* @__PURE__ */ new Map();
-	const tagRows = db.prepare(`SELECT normalized_keyword, tag FROM keyword_set_tags
-       WHERE set_id = ? AND normalized_keyword IN (${rows.map(() => "?").join(", ")})
-       ORDER BY normalized_keyword, tag`).all(setId, ...rows.map((row) => row.normalized_keyword));
-	const tagsByKeyword = /* @__PURE__ */ new Map();
-	for (const row of tagRows) {
-		const tags = tagsByKeyword.get(row.normalized_keyword) ?? [];
-		tags.push(row.tag);
-		tagsByKeyword.set(row.normalized_keyword, tags);
-	}
-	return tagsByKeyword;
-}
-function itemFromRow(row, tags) {
-	const latestMetric = row.metric_json ? parseStoredJson(row.metric_json, savedMetricSchema, "Saved keyword metric") : null;
-	if (latestMetric && (latestMetric.provider !== row.metric_provider || latestMetric.observedAt !== row.metric_observed_at || normalizeSavedKeyword(latestMetric.metric.keyword) !== row.normalized_keyword)) throw new SeoError("INTERNAL_ERROR", "Saved keyword metric metadata is inconsistent.");
-	const page = row.page_kind && row.page_url ? {
-		kind: row.page_kind,
-		url: row.page_url
-	} : null;
-	return {
-		keyword: row.display_keyword,
-		normalizedKeyword: row.normalized_keyword,
-		tags,
-		page,
-		latestMetric,
-		createdAt: new Date(row.created_at).toISOString(),
-		updatedAt: new Date(row.updated_at).toISOString()
-	};
-}
-//#endregion
 //#region packages/core/dist/analyze/saved-keywords.js
 const DEFAULT_STALE_DAYS = 45;
 function savedKeywordSetReport(input, dependencies = {}) {
@@ -34658,6 +35971,7 @@ const TELEMETRY_REPORTS = [
 	"pseo-opportunities",
 	"query-clusters",
 	"quick-wins",
+	"rank-tracking",
 	"redirect-trace",
 	"narrative-report",
 	"second-page",
@@ -36413,6 +37727,25 @@ const savedKeywordsInput = z$1.strictObject({
 	offset: z$1.number().int().min(0).max(1e5).default(0),
 	staleDays: z$1.number().int().min(1).max(365).default(45)
 });
+const rankTrackingInput = z$1.strictObject({
+	projectId: z$1.string().trim().min(1).max(80),
+	set: z$1.string().trim().min(1).max(80),
+	targetDomain: z$1.string().trim().min(1).max(253),
+	tag: z$1.string().trim().min(1).max(40).optional(),
+	devices: z$1.array(z$1.enum(["desktop", "mobile"])).min(1).max(2).refine((items) => new Set(items).size === items.length, { message: "Choose each device once." }).optional(),
+	provider: providerIdInput.optional(),
+	collectionMethod: z$1.enum(["live", "queued"]).optional(),
+	cadence: z$1.enum([
+		"manual",
+		"daily",
+		"weekly",
+		"monthly"
+	]).default("manual"),
+	depth: z$1.number().int().min(1).max(100).default(100),
+	keywordLimit: z$1.number().int().min(1).max(1e3).optional(),
+	start: z$1.boolean().default(true),
+	outputLimit: z$1.number().int().min(1).max(250).default(100)
+});
 function registerKeywordTools(server, dependencies = {}) {
 	server.registerTool("seo_saved_keywords", {
 		description: "Review one bounded local keyword set with metric freshness, tags, page mappings, and evidence limits",
@@ -36432,6 +37765,17 @@ function registerKeywordTools(server, dependencies = {}) {
 			return toolError(error);
 		}
 	});
+	server.registerTool("seo_rank_tracking", {
+		description: "Collect and compare exact market and device-specific ranks for one bounded saved keyword set, with local history, queued recovery, coverage, and cost evidence",
+		inputSchema: rankTrackingInput
+	}, async (input) => {
+		try {
+			const report = await (dependencies.rankTrackingReport ?? rankTrackingReport)(input);
+			return toolSuccess(report.summary.verdict, compactAgentWorkflowOutput(report));
+		} catch (error) {
+			return toolError(error);
+		}
+	});
 	server.registerTool("seo_keyword_metrics", {
 		description: "Compare bounded third-party keyword demand, cost, competition, difficulty, intent, result-count, and trend evidence",
 		inputSchema: {
@@ -38681,6 +40025,40 @@ const REPORT_DEPTH = {
 			}
 		]
 	},
+	"rank-tracking": {
+		readOrder: [
+			"dataStatus, configuration market, devices, targetDomain, depth, collection method, cadence, and run state",
+			"coverage, pending and failed counts, provider cost, warnings, and caveats",
+			"comparison prior run and per-item current and previous observation states",
+			"organic position change, absolute position, ranking URL changes, and checkedAt",
+			"nextSteps for first-party context, template review, or queued collection"
+		],
+		doNotClaim: [
+			"Not observed within the configured depth is not proof that the domain does not rank.",
+			"Exact snapshots must not be substituted for Search Console average position or blended across markets and devices.",
+			"A ranking change alone does not establish causation, traffic impact, or future performance.",
+			"Pending or failed tasks cannot be treated as losses or zero rankings."
+		],
+		verify: "Confirm the same market, device, depth, and target-domain scope, then inspect the ranking URL and Search Console evidence before acting.",
+		related: [
+			{
+				id: "serp-results",
+				reason: "Inspects the current result page."
+			},
+			{
+				id: "saved-keywords",
+				reason: "Reviews the tracked keyword set."
+			},
+			{
+				id: "quick-wins",
+				reason: "Adds first-party opportunity evidence."
+			},
+			{
+				id: "striking-distance",
+				reason: "Adds first-party average-position evidence."
+			}
+		]
+	},
 	"segment-impact": {
 		readOrder: [
 			"before, after, and rangeDays",
@@ -39324,6 +40702,17 @@ const REPORT_GUIDANCE = {
 		avoidWhen: ["You need rank history or scheduled tracking across many keywords.", "You want a domain strength, content quality, or ranking feasibility verdict."],
 		outcome: "A bounded result snapshot with exact retained ranks, domain repetition, query corrections, features, cost, and coverage."
 	},
+	"rank-tracking": {
+		name: "Exact rank tracking",
+		description: "Collect and compare exact organic positions for a saved keyword set without mixing markets, devices, or Search Console averages.",
+		useWhen: [
+			"You need repeatable exact-rank snapshots for a fixed market and device.",
+			"You want new, lost, improved, declined, or ranking URL change evidence over time.",
+			"A recurring set should use cheaper queued collection and local history."
+		],
+		avoidWhen: ["You need first-party clicks, impressions, or average position; use a Search Console report.", "One current query needs result-page inspection but no history; use live search results."],
+		outcome: "A bounded exact-rank comparison with explicit depth, pending and failed states, provider cost, and local retention evidence."
+	},
 	"segment-impact": {
 		name: "Search impact by segment",
 		description: "Compare page or query groups across equal periods to find which parts of a site moved.",
@@ -39830,6 +41219,7 @@ const reportGroups = [
 			"seo_keyword_metrics",
 			"seo_keyword_opportunities",
 			"seo_keyword_research",
+			"seo_rank_tracking",
 			"seo_saved_keywords",
 			"seo_serp_results"
 		]