@growth-labs/seo 0.1.5 → 0.2.0

package/README.md

@@ -1,80 +1,168 @@
 # @growth-labs/seo
 
-Astro integration for complete SEO infrastructure on Cloudflare. Handles JSON-LD structured data, meta tags, sitemaps, RSS/podcast feeds, AEO (Answer Engine Optimization), multilingual support, robots.txt, llms.txt, and build-time validation.
+Astro integration for complete SEO infrastructure on Cloudflare. Handles JSON-LD structured data, meta tags, sitemaps, RSS/podcast/Apple News feeds, AEO (Answer Engine Optimization) with crawler-class dispatch, multilingual support, robots.txt, llms.txt / llms-full.txt, and build-time validation.
 
-## Config
+## Quick start — prerendered content site (WarFronts pattern)
+
+For immutable-after-publish content (articles, docs, archived posts). Zero bindings required.
 
 ```typescript
 import seo from '@growth-labs/seo'
 
+export default defineConfig({
+  integrations: [
+    seo({
+      site: 'https://warfronts.channel',
+      organization: {
+        name: 'WarFronts',
+        logo: 'https://media.warfronts.channel/logos/header.png',
+      },
+      aeoTwins: true,  // → { mode: 'static' }
+      llmsTxt: true,
+      rss: true,
+      contentProvider: async ({ type, slugs }) => loadContent(type, slugs),
+    }),
+  ],
+})
+```
+
+`mode: 'static'` emits `.md` twin files at build time to `dist/client/article/<slug>.md`. Cloudflare Assets (or any static host) serves them directly. No Worker hop.
+
+## Premium publisher (fronts.co pattern) — SSR, gated content, Flexible Sampling
+
+For paid publications where members see the full body and verified Googlebot gets the paywall-marked full body under Google's Flexible Sampling policy.
+
+```typescript
 seo({
-  site: 'https://warfronts.channel',
-  schemaType: 'Article',                        // Default JSON-LD type
-  organization: {
-    name: 'WarFronts',
-    logo: 'https://media.warfronts.channel/logos/header.png',
-    sameAs: ['https://youtube.com/@warfronts'],
+  site: 'https://fronts.co',
+  organization: { name: 'Fronts', logo: 'https://fronts.co/logo.png' },
+  aeoTwins: {
+    mode: 'middleware',
+    onDemandRevalidation: true,
+    revalidateToken: import.meta.env.SEO_REVALIDATE_TOKEN,  // ≥32 random bytes
+    freshLayer: { bindingName: 'AEO_TWINS', type: 'r2' },
   },
-  googleNews: false,                             // Include in Google News sitemap
-  aeoTwins: true,                                // Accept: text/markdown content negotiation
-  llmsTxt: true,                                 // Serve /llms.txt
-  rss: true,                                     // Serve /feed.xml
-  contentSignal: {                               // Content-Signal HTTP header
-    aiTrain: 'no',
-    search: 'yes',
-    aiInput: 'yes',
-  },
-  defaults: {
-    titleSuffix: ' | WarFronts',
-    twitterSite: '@warfronts',
-  },
-  // Optional:
-  commerce: { enabled: true, currency: 'USD', returnPolicy: { ... } },
-  podcast: { enabled: true, title: '...', author: '...', ... },
-  audioNarration: { enabled: true, narratorName: '...', asPodcastFeed: true },
-  locales: [{ lang: 'en', region: 'US', default: true }],   // Multilingual
+  flexibleSampling: { enabled: true, sampleMode: 'lead-in', leadInParagraphs: 2 },
+  llmsTxt: true,
+  llmsFullTxt: true,
+  contentProvider: async ({ type, slugs }) => loadContent(type, slugs),
 })
 ```
 
-## What It Injects
+Gated articles need `prerender: false` on their route file — enforced at build time via the prerender-gated-content guard.
 
-**Middleware** (order: `post`):
-- Adds `Content-Signal` header to responses
-- Adds `Link` alternate header for hreflang
-- Handles `Accept: text/markdown` → returns markdown twin (AEO)
+## wrangler.toml (required for middleware/both modes)
 
-**Routes:**
-- `/sitemap-index.xml` — sitemap index
-- `/sitemap-articles.xml`, `/sitemap-pages.xml`, `/sitemap-videos.xml`
-- `/sitemap-products.xml` (if commerce enabled)
-- `/robots.txt` — with AI crawler blocking directives
-- `/llms.txt` (if enabled)
-- `/feed.xml` (if RSS enabled)
-- `/podcast.xml` (if podcast enabled)
-- `/listen.xml` (if audio narration podcast feed enabled)
+```toml
+# Fresh-twin storage (R2 preferred, KV acceptable)
+[[r2_buckets]]
+binding = "AEO_TWINS"
+bucket_name = "my-site-aeo-twins"
+
+# Revalidation Coordinator — rate limit + per-slug lock + idempotency
+[[durable_objects.bindings]]
+name = "AEO_REVALIDATION_COORD"
+class_name = "AeoRevalidationCoordinator"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["AeoRevalidationCoordinator"]
+
+# Version metadata (R2 key prefixing for rollback safety)
+[version_metadata]
+binding = "CF_VERSION_METADATA"
 
-## Standalone Utilities
+# Daily prune cron — deletes old-version R2 entries
+[triggers]
+crons = ["0 3 * * *"]
 
-Available without the integration:
+# Assets binding — MUST set not_found_handling to "none" or middleware's
+# env.ASSETS.fetch() for missing twins will return the SPA fallback.
+[assets]
+binding = "ASSETS"
+directory = "./dist/client"
+not_found_handling = "none"
+```
+
+Re-export the DO class + scheduled handler from your Worker entrypoint:
 
 ```typescript
-import { generateJsonLd, generateMeta } from '@growth-labs/seo/utils'
-import { articleJsonLd } from '@growth-labs/seo/utils/json-ld/article'
-import { productJsonLd } from '@growth-labs/seo/utils/json-ld/product'
+export { AeoRevalidationCoordinator } from '@growth-labs/seo/durable-objects'
+export { pruneAeoR2 } from '@growth-labs/seo/cron'
+
+export default {
+  async scheduled(event, env, ctx) {
+    await pruneAeoR2({ env })
+  },
+}
 ```
 
-**JSON-LD generators:** Article, NewsArticle, BlogPosting, FAQPage, VideoObject, AudioObject, Person, HowTo, Product, ProductGroup, Review, AggregateRating, BreadcrumbList, Organization, WebSite, ItemList, SpeakableSpecification
+## What it injects
 
-**Other utilities:** `generateMeta()` (OG + Twitter Card), sitemap XML, RSS/Atom, podcast RSS (iTunes namespace), hreflang tags, robots.txt, llms.txt
+**Middleware** (order: `post`):
+- Classifies every request: verified search crawler (BM fast path + FCrDNS fallback), LLM training crawler, user-directed LLM agent, anonymous.
+- Sets `Astro.locals.crawlerClass` + `effectiveAuthSegment` for consumer cache-key builders.
+- 403s LLM training crawlers on `access: 'members'` items.
+- Adds `Content-Signal` header on every response.
+- Adds `Vary: Accept, User-Agent, Cookie, CF-Connecting-IP` on every SSR response.
+- Adds `Link: rel="alternate"; type="text/markdown"` on HTML responses (suppressed for members items).
+- Serves `.md` twins via `Accept: text/markdown` content-negotiation in middleware/both modes (R2 → Assets → 503 stub + background render fallthrough).
 
-## Wrangler Bindings
+**Routes:**
+- `/sitemap-index.xml` + `sitemap-articles.xml`, `sitemap-pages.xml`, `sitemap-videos.xml`, `sitemap-products.xml`
+- `/sitemap-markdown.xml` — twin URL sitemap (static/both modes only)
+- `/robots.txt`
+- `/llms.txt`, `/llms-full.txt`
+- `/feed.xml` (RSS)
+- `/apple-news.xml` (Apple News Publisher RSS, if enabled)
+- `/podcast.xml`, `/listen.xml`
+- `POST /_seo/revalidate` — CMS webhook target (when `onDemandRevalidation: true`)
+
+**Build-time:**
+- Emits `.md` twins + summary twins for public items (static/both modes) under `dist/client/`.
+- Validates hreflang reciprocity.
+- Validates no prerendered route serves a members-gated item (when Flexible Sampling is enabled).
+- Per-page HTML validation (title length, meta description, canonical, H1, JSON-LD presence).
+
+## Crawler classes
+
+| Class | What they see | Notes |
+|---|---|---|
+| `verifiedSearchCrawler` | Full body (+ paywall JSON-LD on gated items under Flexible Sampling) | FCrDNS-verified Googlebot/Bingbot/Applebot. Cloudflare BM fast path when available. |
+| `llmTrainingCrawler` | 403 on members items, public body on public items | GPTBot, ClaudeBot, CCBot, PerplexityBot, Applebot-Extended, etc. |
+| `userDirectedLlmAgent` | Anonymous body only, regardless of cookies | ChatGPT-User, Claude-User, PerplexityBot-User, Google-NotebookLM. Load-bearing override prevents cookie-based leakage. |
+| `anonymous` | Public body or gate | Everything else. |
+
+## Standalone utilities
+
+All pure-function utilities are available without the integration:
 
-None required.
+```typescript
+import { generateArticleJsonLd, generateProductJsonLd } from '@growth-labs/seo/utils'
+import { generateMeta } from '@growth-labs/seo/utils/meta'
+import { generateAppleNewsRss, generateAppleNewsAnf } from '@growth-labs/seo/utils'
+import { classifyRequest, createFcrdnsVerifier } from '@growth-labs/seo/utils'
+import { computeEffectiveAuthSegment } from '@growth-labs/seo/utils'
+```
 
-## Key Patterns
+**JSON-LD generators:** Article, NewsArticle, BlogPosting, FAQPage, VideoObject, AudioObject, Person, HowTo, Product, BreadcrumbList, Organization, WebSite, ItemList, SpeakableSpecification
+
+**Feed generators:** RSS, Apple News Publisher RSS, Apple News Format (ANF) JSON, podcast RSS, listen feed, llms.txt, llms-full.txt
+
+**Utilities:** OG + Twitter Card meta, sitemap XML, markdown sitemap, hreflang, robots.txt, AEO markdown generator with RAG chunk markers, summary twin generator, content-hash staleness.
+
+## Non-Cloudflare hosts
+
+`aeoTwins: { mode: 'static' }` works on any host that serves static files (Vercel, Netlify, GitHub Pages, S3+CloudFront). Other modes (`'middleware'`, `'both'`) and `onDemandRevalidation` require Cloudflare Workers + R2/KV + Durable Objects. See [packages-seo-SPEC-v2.md](../../packages-seo-SPEC-v2.md) "Deployment Targets" for details.
+
+## Key patterns
 
 - Virtual module: `virtual:growth-labs/seo/config`
-- AI crawler blocking happens at Cloudflare CDN level, NOT in this package
-- AEO twins: same content as markdown via `Accept: text/markdown` content negotiation
-- Build-time validation warns on missing titles, descriptions, JSON-LD issues (non-blocking)
-- `.astro` component files ship as source from `src/components/`
+- AI crawler blocking: enforced at `robots.txt` AND per-request 403 on members items
+- `.md` twin canonical: emitted with `X-Robots-Tag: noindex` + `Link: <html-url>; rel="canonical"` — prevents Google from clustering the `.md` as a duplicate of the HTML
+- Summary twins: `.summary.md` companion emitted when `summaryTwin: true` (default), with a 4-tier fallback (item.summary → bullets → first-sentence-per-section → description-only)
+- Build-time validation: non-blocking for per-page issues, FAILS the build for gated content on prerendered routes
+
+## Full spec
+
+See [packages-seo-SPEC-v2.md](../../packages-seo-SPEC-v2.md) for the complete 2,400-line specification including the test matrix, architectural rationale, and worked examples for every code path.

package/dist/bindings.d.ts

@@ -0,0 +1,127 @@
+/**
+ * R2 bucket binding for the fresh-twin layer.
+ * Subset of the R2Bucket API we actually use.
+ */
+export interface R2BucketLike {
+    get(key: string): Promise<R2ObjectLike | null>;
+    put(key: string, value: ReadableStream | ArrayBuffer | string, options?: R2PutOptions): Promise<unknown>;
+    delete(keys: string | string[]): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<R2ListResult>;
+}
+export interface R2ObjectLike {
+    readonly key: string;
+    readonly size: number;
+    readonly uploaded: Date;
+    readonly httpMetadata?: R2HTTPMetadata;
+    readonly customMetadata?: Record<string, string>;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    body: ReadableStream | null;
+    bodyUsed: boolean;
+}
+export interface R2PutOptions {
+    httpMetadata?: R2HTTPMetadata;
+    customMetadata?: Record<string, string>;
+}
+export interface R2HTTPMetadata {
+    contentType?: string;
+    contentLanguage?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    cacheControl?: string;
+    cacheExpiry?: Date;
+}
+export interface R2ListResult {
+    objects: R2ObjectLike[];
+    truncated: boolean;
+    cursor?: string;
+}
+/**
+ * KV namespace binding — acceptable alternative to R2 for the fresh-twin layer.
+ * Subset of the KVNamespace API we actually use.
+ */
+export interface KVNamespaceLike {
+    get(key: string): Promise<string | null>;
+    get(key: string, options: {
+        type: 'text';
+    }): Promise<string | null>;
+    get(key: string, options: {
+        type: 'arrayBuffer';
+    }): Promise<ArrayBuffer | null>;
+    put(key: string, value: string | ArrayBuffer, options?: {
+        expiration?: number;
+        expirationTtl?: number;
+        metadata?: unknown;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+        }>;
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/**
+ * Assets binding — reads static files from the Worker's deployment bundle without
+ * re-entering the Worker's request routing. Use:
+ *   env.ASSETS.fetch(new Request('https://assets.local/path/to/file.md'))
+ * The hostname is ignored by the assets runtime; only pathname matters.
+ * Set `assets.not_found_handling = "none"` in wrangler.toml to prevent SPA fallback
+ * from serving index.html when the requested path is missing.
+ */
+export interface AssetsBinding {
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Durable Object namespace binding for the Revalidation Coordinator. The actual DO
+ * class is exported from `@growth-labs/seo/durable-objects` and wired by the consumer
+ * in their Worker entrypoint.
+ */
+export interface DurableObjectNamespaceLike {
+    idFromName(name: string): DurableObjectIdLike;
+    get(id: DurableObjectIdLike): DurableObjectStubLike;
+}
+export interface DurableObjectIdLike {
+    toString(): string;
+    equals(other: DurableObjectIdLike): boolean;
+}
+export interface DurableObjectStubLike {
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Version metadata binding. Injected into `env` as `CF_VERSION_METADATA`.
+ * Used for rollback-safe R2 key prefixing (`twin/<id>/<slug>.md`).
+ * `id` is an opaque version UUID that rotates on every new deployment.
+ * `tag` is an optional user-supplied annotation via `workers/tag`.
+ * `timestamp` is the version's creation time (ISO 8601 string).
+ * Ref: https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/
+ */
+export interface VersionMetadata {
+    readonly id: string;
+    readonly tag?: string;
+    readonly timestamp: string;
+}
+/**
+ * The minimal Worker env shape the SEO package depends on. Consumers will have many
+ * more bindings than this; we only declare what we read.
+ *
+ * All fields are optional because the package's `mode: 'static'` code path runs without
+ * any Worker bindings. Runtime binding resolvers throw structured errors when required
+ * bindings are missing.
+ */
+export interface SeoEnv {
+    AEO_TWINS?: R2BucketLike | KVNamespaceLike;
+    AEO_REVALIDATION_COORD?: DurableObjectNamespaceLike;
+    ASSETS?: AssetsBinding;
+    CF_VERSION_METADATA?: VersionMetadata;
+}
+//# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"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"}

package/dist/bindings.js

@@ -0,0 +1,11 @@
+// Cloudflare binding declarations used by the SEO integration at request and build time.
+//
+// These types are not Astro-specific. They describe the subset of `env` the package
+// touches when running inside a Cloudflare Worker. Consumers provide the actual bindings
+// in wrangler.toml; this file gives us a narrow structural type so utility and middleware
+// code can be type-checked without a hard dependency on `@cloudflare/workers-types`.
+//
+// If `@cloudflare/workers-types` is in the consumer's project, their stricter types will
+// widen-compatibly overlap these interfaces.
+export {};
+//# sourceMappingURL=bindings.js.map

package/dist/bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,EAAE;AACF,oFAAoF;AACpF,yFAAyF;AACzF,0FAA0F;AAC1F,qFAAqF;AACrF,EAAE;AACF,yFAAyF;AACzF,6CAA6C"}

package/dist/cron/prune-aeo-r2.d.ts

@@ -0,0 +1,36 @@
+import type { SeoEnv } from '../bindings.js';
+export interface PruneAeoR2Options {
+    env: SeoEnv;
+    /** Binding name to read from env. Matches aeoTwins.freshLayer.bindingName. */
+    bindingName?: string;
+    /** 'r2' (default) or 'kv'. Matches aeoTwins.freshLayer.type. */
+    type?: 'r2' | 'kv';
+    /** Retention in days. Matches aeoTwins.freshLayer.retentionDays. */
+    retentionDays?: number;
+    /** Optional structured-log sink. */
+    log?: (event: Record<string, unknown>) => void;
+}
+export interface PruneResult {
+    deploymentsScanned: number;
+    deploymentsPruned: string[];
+    keysDeleted: number;
+    errors: string[];
+}
+/**
+ * Sweep the fresh layer for entries belonging to deployments that are no longer
+ * current AND older than `retentionDays`. Keys from the current deployment are
+ * untouched regardless of age.
+ *
+ * Algorithm:
+ *   1. Determine the current versionId from env.CF_VERSION_METADATA.id.
+ *   2. List all deployment IDs present in the fresh layer.
+ *   3. For each non-current deployment, list its keys; if the oldest matches
+ *      the retention cutoff, delete all keys under that prefix.
+ *
+ * "Oldest matches retention cutoff" is approximated by R2's `uploaded` timestamp
+ * (R2-only). For KV there's no per-key mtime, so the retention check degrades
+ * to "delete everything not matching the current deployment" — adjust the
+ * binding to R2 if you need retentionDays fidelity.
+ */
+export declare function pruneAeoR2(options: PruneAeoR2Options): Promise<PruneResult>;
+//# sourceMappingURL=prune-aeo-r2.d.ts.map

package/dist/cron/prune-aeo-r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune-aeo-r2.d.ts","sourceRoot":"","sources":["../../src/cron/prune-aeo-r2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAW5C,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IAClB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oCAAoC;IACpC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAC9C;AAED,MAAM,WAAW,WAAW;IAC3B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,EAAE,CAAA;CAChB;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAkFjF"}

package/dist/cron/prune-aeo-r2.js

@@ -0,0 +1,94 @@
+import { deleteFreshTwin, listDeploymentIds, listKeysByDeployment } from '../utils/fresh-layer.js';
+const DEFAULT_RETENTION_DAYS = 7;
+/**
+ * Sweep the fresh layer for entries belonging to deployments that are no longer
+ * current AND older than `retentionDays`. Keys from the current deployment are
+ * untouched regardless of age.
+ *
+ * Algorithm:
+ *   1. Determine the current versionId from env.CF_VERSION_METADATA.id.
+ *   2. List all deployment IDs present in the fresh layer.
+ *   3. For each non-current deployment, list its keys; if the oldest matches
+ *      the retention cutoff, delete all keys under that prefix.
+ *
+ * "Oldest matches retention cutoff" is approximated by R2's `uploaded` timestamp
+ * (R2-only). For KV there's no per-key mtime, so the retention check degrades
+ * to "delete everything not matching the current deployment" — adjust the
+ * binding to R2 if you need retentionDays fidelity.
+ */
+export async function pruneAeoR2(options) {
+    const { env, bindingName = 'AEO_TWINS', type = 'r2', retentionDays = DEFAULT_RETENTION_DAYS, log, } = options;
+    const currentVersion = env.CF_VERSION_METADATA?.id;
+    const errors = [];
+    const deploymentsPruned = [];
+    let keysDeleted = 0;
+    if (!currentVersion) {
+        errors.push('missing_CF_VERSION_METADATA_id');
+        log?.({ event: 'prune_skipped', reason: 'missing_CF_VERSION_METADATA_id' });
+        return { deploymentsScanned: 0, deploymentsPruned, keysDeleted, errors };
+    }
+    const binding = env[bindingName];
+    if (!binding) {
+        errors.push(`missing_binding_${bindingName}`);
+        log?.({ event: 'prune_skipped', reason: 'missing_binding', bindingName });
+        return { deploymentsScanned: 0, deploymentsPruned, keysDeleted, errors };
+    }
+    const impl = binding;
+    const freshLayer = { type, impl, deploymentId: currentVersion };
+    const cutoffMs = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    const allDeployments = await listDeploymentIds(freshLayer);
+    const deploymentsScanned = allDeployments.size;
+    for (const deploymentId of allDeployments) {
+        if (deploymentId === currentVersion)
+            continue;
+        let deletedForThisDeployment = 0;
+        let shouldDelete = true;
+        // R2-only: peek the first object's uploaded time to gate on retentionDays.
+        // KV falls through to "delete everything non-current" since no mtime is available.
+        if (type === 'r2') {
+            const r2 = impl;
+            const peek = await r2.list({ prefix: `twin/${deploymentId}/`, limit: 1 });
+            const oldest = peek.objects[0];
+            if (oldest && oldest.uploaded.getTime() > cutoffMs) {
+                // Inside retention window — skip.
+                shouldDelete = false;
+                log?.({
+                    event: 'prune_skipped_within_retention',
+                    deploymentId,
+                    oldestUploaded: oldest.uploaded.toISOString(),
+                    retentionDays,
+                });
+            }
+        }
+        if (!shouldDelete)
+            continue;
+        try {
+            for await (const key of listKeysByDeployment(freshLayer, deploymentId)) {
+                await deleteFreshTwin({ ...freshLayer, deploymentId }, keyToPath(deploymentId, key));
+                deletedForThisDeployment++;
+            }
+            keysDeleted += deletedForThisDeployment;
+            deploymentsPruned.push(deploymentId);
+            log?.({
+                event: 'prune_deployment',
+                deploymentId,
+                keysDeleted: deletedForThisDeployment,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`deployment_${deploymentId}: ${msg}`);
+            log?.({ event: 'prune_error', deploymentId, message: msg });
+        }
+    }
+    return { deploymentsScanned, deploymentsPruned, keysDeleted, errors };
+}
+/**
+ * Convert a full R2/KV key back to the URL-path form used by deleteFreshTwin.
+ * Inverse of fresh-layer buildKey.
+ */
+function keyToPath(deploymentId, key) {
+    const prefix = `twin/${deploymentId}/`;
+    return key.startsWith(prefix) ? `/${key.slice(prefix.length)}` : `/${key}`;
+}
+//# sourceMappingURL=prune-aeo-r2.js.map

package/dist/cron/prune-aeo-r2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune-aeo-r2.js","sourceRoot":"","sources":["../../src/cron/prune-aeo-r2.ts"],"names":[],"mappings":"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"}

package/dist/durable-objects/aeo-revalidation-coord.d.ts

@@ -0,0 +1,69 @@
+export interface DurableObjectStorageLike {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    list<T = unknown>(options: {
+        prefix: string;
+    }): Promise<Map<string, T>>;
+    setAlarm(scheduledTime: number): Promise<void>;
+    getAlarm(): Promise<number | null>;
+}
+export interface DurableObjectStateLike {
+    storage: DurableObjectStorageLike;
+}
+export type CoordRequest = {
+    action: 'rate-check';
+    token: string;
+    limitRpm: number;
+} | {
+    action: 'acquire-lock';
+    slug: string;
+    leaseMs?: number;
+} | {
+    action: 'release-lock';
+    slug: string;
+    leaseId: string;
+} | {
+    action: 'idempotency-check';
+    key: string;
+} | {
+    action: 'idempotency-set';
+    key: string;
+    result: Record<string, unknown>;
+    ttlMs?: number;
+};
+export type CoordResponse = {
+    ok: true;
+    [k: string]: unknown;
+} | {
+    ok: false;
+    error: string;
+    [k: string]: unknown;
+};
+export declare class AeoRevalidationCoordinator {
+    readonly ctx: DurableObjectStateLike;
+    constructor(ctx: DurableObjectStateLike);
+    /**
+     * Dispatch a JSON-encoded CoordRequest. Returns a JSON response. Not a
+     * public HTTP API — called from the consumer's Worker via the namespace
+     * binding: `await stub.fetch(new Request('https://internal/', { method: 'POST', body: JSON.stringify(req) }))`.
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Alarm handler: runs every 5 minutes, sweeps expired entries across all
+     * three namespaces. Self-re-arming.
+     */
+    alarm(): Promise<void>;
+    private rateCheck;
+    private acquireLock;
+    private releaseLock;
+    private idempotencyCheck;
+    private idempotencySet;
+    private ensureAlarm;
+}
+export declare const _internals: {
+    LOCK_DEFAULT_LEASE_MS: number;
+    IDEMPOTENCY_DEFAULT_TTL_MS: number;
+    ALARM_INTERVAL_MS: number;
+};
+//# sourceMappingURL=aeo-revalidation-coord.d.ts.map

package/dist/durable-objects/aeo-revalidation-coord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aeo-revalidation-coord.d.ts","sourceRoot":"","sources":["../../src/durable-objects/aeo-revalidation-coord.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,wBAAwB;IACxC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IACrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,wBAAwB,CAAA;CACjC;AAID,MAAM,MAAM,YAAY,GACrB;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9F,MAAM,MAAM,aAAa,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAyBrD,qBAAa,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,sBAAsB;gBAA3B,GAAG,EAAE,sBAAsB;IAEhD;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmChD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA6Bd,SAAS;YAuBT,WAAW;YAaX,WAAW;YAaX,gBAAgB;YAShB,cAAc;YAad,WAAW;CAMzB;AAmBD,eAAO,MAAM,UAAU;;;;CAItB,CAAA"}