@canonry/canonry 4.177.0 → 4.177.1

package/README.md

@@ -18,7 +18,7 @@ Think PostHog, for AI search visibility. Canonry tracks what ChatGPT, Claude, Ge
 |---|---|
 | **Measure** | Track mentions and citations across Gemini, ChatGPT, Claude, Perplexity, and local models. Join them with GSC, GA4, Bing, server side traffic, Business Profile, and backlink data. |
 | **Diagnose** | Crawl the site, score Page Health, inspect evidence, compare competitors, and explain regressions. |
-| **Act** | Give your agent the context to make surgical on-site technical SEO changes and coordinate content, indexing, analytics, and paid media. |
+| **Act** | Give your agent the context + skills to make surgical on-site technical SEO changes and coordinate content, indexing, analytics, and paid media. |
 | **Operate** | Create automation workflows, schedule checks, sync data, send webhooks, and generate client-ready reports. |
 
 ### Built-in integrations and workflows

package/assets/agent-workspace/skills/canonry/SKILL.md

@@ -160,6 +160,13 @@ schedule interval. Use `cnry traffic events`, `cnry traffic sources`, and
 `cnry traffic status` for every adapter. See
 `references/server-side-traffic.md` for setup and smoke tests.
 
+**WordPress safety:** incremental pulls are fixed `[since, until)` windows; a
+new or idle source begins at the plugin's 365-day maximum retention horizon.
+Canonry rejects an endpoint that returns events outside that window. Keep
+existing WordPress rollups intact: generic replace-mode backfill is unavailable
+until a retention-aware repair can prove coverage and declare any unrecoverable
+span.
+
 **Vercel gotcha:** a freshly connected Vercel source captures only going-forward traffic — `lastSyncedAt` is seeded to NOW to avoid the 30-day default window exceeding Vercel's ~14-day request-logs retention (which would otherwise throw on every first sync). Use `cnry traffic backfill <project> --source <id> --days N` for historical recovery. If an idle Vercel/Cloud Run source has been failing long enough that `lastSyncedAt` aged past retention, unstick it with `cnry traffic reset <project> --source <id> --advance-to-now`.
 
 ## Local AEO (Google Business Profile)

package/assets/agent-workspace/skills/canonry/references/server-side-traffic.md

@@ -151,6 +151,38 @@ The plugin auto-prunes events older than the retention window (default
 90 days) once per day via WP-Cron. Operators who want a different
 window change it in `Settings → Canonry Traffic Logger`.
 
+### WordPress incremental-window safety
+
+Each incremental WordPress sync uses one fixed half-open `[since, until)`
+window. A fresh source, or an idle source without an explicit
+`--since-minutes`, starts with a 365-day horizon, matching the plugin's
+maximum configurable retention. A site configured for less retention simply
+returns its available tail. If the window needs more than one capped drain,
+Canonry persists both its lower and upper bounds with the continuation cursor
+and retries that exact interval until the plugin reports it is terminal. It
+then advances the normal watermark. Every returned event is validated against
+the requested interval; an older or custom extension that ignores `since` or
+`until` fails closed before any rollup is written. Update that extension to a
+bounded-window-capable Canonry traffic logger before syncing again.
+
+Do not run generic replace-mode backfill for a WordPress source. The plugin
+prunes retained events and cannot prove that it covers every bucket a replace
+transaction would delete, even when no continuation is pending. Canonry
+rejects that generic path universally. Keep existing rollups intact, use a
+retention-aware repair, and explicitly declare any unrecoverable portion before
+reporting a historical trend.
+
+After upgrading from the former unbounded WordPress sync, a source with an old
+continuation cursor is intentionally rejected rather than guessed at. Keep its
+schedule paused, record the ambiguous historical span, then use the explicit
+reset below to start fresh. Reset stops future replay; it does not repair past
+rollups. Generic WordPress replace-mode backfill remains unavailable until a
+retention-aware repair can establish coverage.
+
+Reconnecting with a different WordPress `baseUrl` archives the old source and
+creates a fresh one. Its existing rollups and any unrecovered marker remain
+with the old lineage rather than mixing with the new endpoint's traffic.
+
 ## Connecting a Vercel source
 
 The Vercel adapter pulls per-request logs from the Vercel API for a
@@ -869,15 +901,14 @@ cnry traffic reset <project> --source <id> --advance-to-now
 
 `--advance-to-now` is required — there is no implicit reset.
 
-`reset` accepts any **non-archived** source type. The `lastSyncedAt`
-advance is meaningful for time-windowed sources (Vercel, Cloud Run)
-where it determines the next sync window. Cursor-based sources
-(WordPress) keep their `last_cursor` intact, so the `lastSyncedAt`
-advance is informational — the next WordPress drain still resumes
-from the cursor. The primary use case is the retention-trap recovery
-above; clearing `lastError` for a transient WordPress failure also
-works. Archived sources are rejected — re-connect them with
-`cnry traffic connect ...` instead.
+`reset` accepts any **non-archived** source type. A WordPress reset clears
+its `last_cursor` and pending-window marker as well as advancing
+`lastSyncedAt`, so the next bounded drain begins at the reset watermark
+instead of combining it with an old cursor. The primary use case is the
+retention-trap recovery above; clearing `lastError` for a transient WordPress
+failure also works. Reset deliberately abandons any ambiguous pending history;
+it is not a historical repair. Archived sources are rejected — re-connect them
+with `cnry traffic connect ...` instead.
 
 Time-window and cursor adapters use the `last_event_ids` overlap ring. Queue
 pull uses durable event receipts sized to Queue retention. Both paths make a

package/dist/{chunk-F4ZZKGAC.js → chunk-6XUWDSLN.js}

@@ -91,7 +91,7 @@ import {
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema,
   trafficSeriesGranularitySchema
-} from "./chunk-UXXXKDW4.js";
+} from "./chunk-PQT3ECM3.js";
 
 // src/config.ts
 import fs from "fs";
@@ -9487,17 +9487,17 @@ var trafficConnectVercelInputSchema = z3.object({
 var trafficSyncInputSchema = z3.object({
   project: projectNameSchema,
   sourceId: z3.string().min(1).describe("Traffic source ID returned by canonry_traffic_connect_cloud_run or canonry_traffic_sources_list."),
-  sinceMinutes: z3.number().int().positive().max(7 * 24 * 60).optional().describe("Lookback window in minutes. Defaults to the source's configured window (60 min) when omitted; clamped forward to lastSyncedAt to avoid double-counting.")
+  sinceMinutes: z3.number().int().positive().max(365 * 24 * 60).optional().describe("Optional lookback in minutes. Defaults are adapter-specific and clamp forward to lastSyncedAt; a new or idle WordPress source uses 365d to cover the plugin\u2019s maximum configurable retention.")
 });
 var trafficBackfillInputSchema = z3.object({
   project: projectNameSchema,
   sourceId: z3.string().min(1).describe("Traffic source ID returned by canonry_traffic_sources_list."),
-  days: z3.number().int().positive().max(30).optional().describe("Lookback window in days. Default 30, capped server-side at the upstream log retention ceiling (Cloud Logging _Default = 30d).")
+  days: z3.number().int().positive().max(90).optional().describe("Lookback window in days. Default 30, capped by the adapter at 90d. Generic WordPress replace backfill is unavailable because retained coverage is unproven.")
 });
 var trafficResetInputSchema = z3.object({
   project: projectNameSchema,
   sourceId: z3.string().min(1).describe("Traffic source ID returned by canonry_traffic_sources_list."),
-  advanceToNow: z3.literal(true).describe("Must be `true`. Explicit gate against accidental resets. Advances lastSyncedAt to NOW and clears the source's error state.")
+  advanceToNow: z3.literal(true).describe("Must be `true`. Explicit gate against accidental resets. Advances lastSyncedAt to NOW and clears the source's error state; WordPress also clears its continuation state and records an unrecovered span that needs retention-aware repair.")
 });
 var trafficEventsInputSchema = z3.object({
   project: projectNameSchema,
@@ -10650,7 +10650,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_traffic_connect_wordpress",
     title: "Connect WordPress traffic-logger source",
-    description: "Connect a WordPress site (running the canonry traffic-logger plugin) as a server-side traffic source. Probes the plugin endpoint with the supplied Application Password before persisting \u2014 a bad credential or unreachable host surfaces as a 502 error. Reconnecting updates the existing active WordPress source in place. The Application Password is stored in ~/.canonry/config.yaml (not the DB) and never echoed back.",
+    description: "Connect a WordPress site (running the canonry traffic-logger plugin) as a server-side traffic source. Probes the plugin endpoint with the supplied Application Password before persisting; a bad credential or unreachable host surfaces as a 502 error. Reconnecting the same endpoint updates the active source in place. Changing baseUrl archives the old lineage and creates a fresh source so rollups cannot mix across endpoints. The Application Password is stored in ~/.canonry/config.yaml (not the DB) and never echoed back.",
     access: "write",
     tier: "traffic",
     inputSchema: trafficConnectWordpressInputSchema,
@@ -10671,8 +10671,8 @@ var canonryMcpTools = [
   }),
   defineTool({
     name: "canonry_traffic_sync",
-    title: "Sync Cloud Run traffic source",
-    description: "Pull the most recent Cloud Logging entries for a Cloud Run traffic source, classify them as crawler / AI-referral / unknown, and upsert hourly rollups + raw samples. Returns totals, bucket counts, and the run id. The window auto-clamps forward to lastSyncedAt to avoid double-counting on back-to-back calls.",
+    title: "Sync traffic source",
+    description: "Pull a Cloud Run, WordPress, Vercel, or Cloudflare Queue traffic source, classify crawler / AI-referral / unknown traffic, and upsert hourly rollups plus raw samples. Time-window pulls clamp forward to lastSyncedAt. WordPress uses a fixed bounded window, defaults a new or idle source to 365d, validates the returned events remain inside that window, and serializes syncs with a source lease.",
     access: "write",
     tier: "traffic",
     inputSchema: trafficSyncInputSchema,
@@ -10682,8 +10682,8 @@ var canonryMcpTools = [
   }),
   defineTool({
     name: "canonry_traffic_backfill",
-    title: "Backfill Cloud Run traffic source",
-    description: 'Async one-shot reclassification of historical Cloud Run logs. Pulls the last `days` of request logs (capped at the 30d Cloud Logging retention ceiling), classifies them with current rules, and replaces the hourly rollup buckets + sample slice in the window. Returns immediately with `{ runId, status: "running" }`; poll canonry_run_get for completion. lastSyncedAt only advances forward \u2014 a backfill never undoes incremental sync progress that ran ahead of it.',
+    title: "Backfill traffic source",
+    description: 'Async one-shot reclassification for Cloud Run or Vercel traffic. It replaces the selected window\u2019s rollups with a fresh bounded pull and current classifier output. WordPress generic replace backfill is unavailable because the endpoint cannot prove retained coverage; use a retention-aware repair that explicitly declares any unrecoverable span. Returns `{ runId, status: "running" }`; poll canonry_run_get for completion.',
     access: "write",
     tier: "traffic",
     inputSchema: trafficBackfillInputSchema,
@@ -10694,7 +10694,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_traffic_reset",
     title: "Advance traffic source lastSyncedAt to NOW",
-    description: "Operator recovery for a stuck traffic source. Advances `lastSyncedAt` to NOW, sets `status` back to `connected`, and clears `last_error`. Accepts any non-archived source: the `lastSyncedAt` advance determines the next sync window for time-windowed sources (Vercel, Cloud Run); cursor-based sources (WordPress) keep their `last_cursor` so the advance is informational. Common trigger: an idle Vercel/Cloud Run source whose `lastSyncedAt` aged past the upstream retention boundary and every sync now throws a retention error. Historical events in the gap are unrecoverable from the sync path; run canonry_traffic_backfill separately if any of them are needed. Archived sources are rejected \u2014 re-connect via the appropriate canonry_traffic_connect_* tool instead.",
+    description: "Operator recovery for a stuck traffic source. Advances `lastSyncedAt` to NOW, sets `status` back to `connected`, and clears `last_error`. A WordPress reset also clears its continuation state and records an unrecovered span so its next bounded drain cannot combine an old cursor with a new window. That stops replay but is not historical repair. Generic WordPress replace-mode backfill is unavailable because retained coverage is unproven; use a retention-aware repair that explicitly declares any unrecoverable span. Archived sources are rejected; reconnect them with the appropriate canonry_traffic_connect_* tool.",
     access: "write",
     tier: "traffic",
     inputSchema: trafficResetInputSchema,