@gravito/constellation 3.0.1 → 3.1.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { Job } from '@gravito/stream';
 import { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { Transform } from 'node:stream';
 
 /**
  * Supported change frequency values for sitemap entries.
@@ -176,11 +177,26 @@ interface SitemapProvider {
  * @since 3.0.0
  */
 interface SitemapStreamOptions {
-    /** Base domain used to normalize relative URLs. */
+    /**
+     * Base domain used to normalize relative URLs.
+     * Example: 'https://example.com'
+     */
     baseUrl: string;
     /** Whether to output formatted and indented XML. @default false */
     pretty?: boolean | undefined;
 }
+/**
+ * Options for stream-based write operations.
+ *
+ * @public
+ * @since 3.1.0
+ */
+interface WriteStreamOptions {
+    /** Whether to enable gzip compression for the output. @default false */
+    compress?: boolean | undefined;
+    /** Optional content type override. @default 'application/xml' */
+    contentType?: string | undefined;
+}
 /**
  * Persistence layer for storing generated sitemap files.
  *
@@ -198,6 +214,17 @@ interface SitemapStorage {
      * @param content - The raw XML content.
      */
     write(filename: string, content: string): Promise<void>;
+    /**
+     * Write sitemap content using a streaming approach to reduce memory usage.
+     *
+     * If implemented, this method will be preferred over `write()` for large sitemaps.
+     *
+     * @param filename - The destination filename.
+     * @param stream - An async iterable that yields XML string chunks.
+     * @param options - Optional write configuration including compression.
+     * @since 3.1.0
+     */
+    writeStream?(filename: string, stream: AsyncIterable<string>, options?: WriteStreamOptions): Promise<void>;
     /**
      * Read sitemap content from the storage backend.
      *
@@ -205,6 +232,7 @@ interface SitemapStorage {
      * @returns The XML content as a string, or null if not found.
      */
     read(filename: string): Promise<string | null>;
+    readStream?(filename: string): Promise<AsyncIterable<string> | null>;
     /**
      * Check if a sitemap file exists in storage.
      *
@@ -441,6 +469,33 @@ interface RedirectRule {
     /** Timestamp when the redirect rule was created. */
     createdAt?: Date;
 }
+/**
+ * Represents a manifest file that tracks URL-to-shard mappings.
+ *
+ * @public
+ * @since 3.0.1
+ */
+interface ShardManifest {
+    version: number;
+    generatedAt: Date | string;
+    baseUrl: string;
+    maxEntriesPerShard: number;
+    sort: string;
+    shards: ShardInfo[];
+}
+/**
+ * Metadata about a single sitemap shard.
+ *
+ * @public
+ * @since 3.0.1
+ */
+interface ShardInfo {
+    filename: string;
+    from: string;
+    to: string;
+    count: number;
+    lastmod: Date | string;
+}
 /**
  * Manager for registering and resolving redirect rules.
  *
@@ -483,6 +538,20 @@ interface RedirectManager {
      */
     resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
 }
+/**
+ * Compression configuration options.
+ *
+ * @public
+ * @since 3.1.0
+ */
+interface CompressionOptions {
+    /** Whether compression is enabled. @default false */
+    enabled: boolean;
+    /** Compression format. @default 'gzip' */
+    format?: 'gzip' | undefined;
+    /** Compression level (1-9, where 1 is fastest and 9 is best compression). @default 6 */
+    level?: number | undefined;
+}
 
 /**
  * Options for configuring the `MemoryChangeTracker`.
@@ -505,11 +574,34 @@ interface MemoryChangeTrackerOptions {
  */
 declare class MemoryChangeTracker implements ChangeTracker {
     private changes;
+    private urlIndex;
     private maxChanges;
     constructor(options?: MemoryChangeTrackerOptions);
+    /**
+     * Record a new site structure change in memory.
+     *
+     * @param change - The change event to record.
+     */
     track(change: SitemapChange): Promise<void>;
+    /**
+     * Retrieve all changes recorded in memory since a specific time.
+     *
+     * @param since - Optional start date for the query.
+     * @returns An array of change events.
+     */
     getChanges(since?: Date): Promise<SitemapChange[]>;
+    /**
+     * Retrieve the full change history for a specific URL from memory.
+     *
+     * @param url - The URL to query history for.
+     * @returns An array of change events.
+     */
     getChangesByUrl(url: string): Promise<SitemapChange[]>;
+    /**
+     * Purge old change records from memory storage.
+     *
+     * @param since - If provided, only records older than this date will be cleared.
+     */
     clear(since?: Date): Promise<void>;
 }
 /**
@@ -543,9 +635,31 @@ declare class RedisChangeTracker implements ChangeTracker {
     constructor(options: RedisChangeTrackerOptions);
     private getKey;
     private getListKey;
+    /**
+     * Record a new site structure change in Redis.
+     *
+     * @param change - The change event to record.
+     */
     track(change: SitemapChange): Promise<void>;
+    /**
+     * Retrieve all changes recorded in Redis since a specific time.
+     *
+     * @param since - Optional start date for the query.
+     * @returns An array of change events.
+     */
     getChanges(since?: Date): Promise<SitemapChange[]>;
+    /**
+     * Retrieve the full change history for a specific URL from Redis.
+     *
+     * @param url - The URL to query history for.
+     * @returns An array of change events.
+     */
     getChangesByUrl(url: string): Promise<SitemapChange[]>;
+    /**
+     * Purge old change records from Redis storage.
+     *
+     * @param since - If provided, only records older than this date will be cleared.
+     */
     clear(since?: Date): Promise<void>;
 }
 
@@ -587,19 +701,35 @@ declare class DiffCalculator {
     private batchSize;
     constructor(options?: DiffCalculatorOptions);
     /**
-     * 計算兩個 sitemap 狀態的差異
+     * Calculates the difference between two sets of sitemap entries.
+     *
+     * @param oldEntries - The previous set of sitemap entries.
+     * @param newEntries - The current set of sitemap entries.
+     * @returns A DiffResult containing added, updated, and removed entries.
      */
     calculate(oldEntries: SitemapEntry[], newEntries: SitemapEntry[]): DiffResult;
     /**
-     * 批次計算差異（用於大量 URL）
+     * Batch calculates differences for large datasets using async iterables.
+     *
+     * @param oldEntries - An async iterable of the previous sitemap entries.
+     * @param newEntries - An async iterable of the current sitemap entries.
+     * @returns A promise resolving to the DiffResult.
      */
     calculateBatch(oldEntries: AsyncIterable<SitemapEntry>, newEntries: AsyncIterable<SitemapEntry>): Promise<DiffResult>;
     /**
-     * 從變更記錄計算差異
+     * Calculates differences based on a sequence of change records.
+     *
+     * @param baseEntries - The base set of sitemap entries.
+     * @param changes - An array of change records to apply to the base set.
+     * @returns A DiffResult comparing the base set with the applied changes.
      */
     calculateFromChanges(baseEntries: SitemapEntry[], changes: SitemapChange[]): DiffResult;
     /**
-     * 檢查 entry 是否有變更
+     * Checks if a sitemap entry has changed by comparing its key properties.
+     *
+     * @param oldEntry - The previous sitemap entry.
+     * @param newEntry - The current sitemap entry.
+     * @returns True if the entry has changed, false otherwise.
      */
     private hasChanged;
 }
@@ -650,25 +780,34 @@ declare class ShadowProcessor {
     private options;
     private shadowId;
     private operations;
+    private mutex;
     constructor(options: ShadowProcessorOptions);
     /**
-     * 添加一個影子操作
+     * Adds a single file write operation to the current shadow session.
+     *
+     * If shadow processing is disabled, the file is written directly to the
+     * final destination in storage. Otherwise, it is written to the shadow staging area.
+     *
+     * @param operation - The shadow write operation details.
      */
     addOperation(operation: ShadowOperation): Promise<void>;
     /**
-     * 提交所有影子操作
+     * Commits all staged shadow operations to the final production location.
+     *
+     * Depending on the `mode`, this will either perform an atomic swap of all files
+     * or commit each file individually (potentially creating new versions).
      */
     commit(): Promise<void>;
     /**
-     * 取消所有影子操作
+     * Cancels all staged shadow operations without committing them.
      */
     rollback(): Promise<void>;
     /**
-     * 獲取當前影子 ID
+     * Returns the unique identifier for the current shadow session.
      */
     getShadowId(): string;
     /**
-     * 獲取所有操作
+     * Returns an array of all staged shadow operations.
      */
     getOperations(): ShadowOperation[];
 }
@@ -688,6 +827,8 @@ interface SitemapGeneratorOptions extends SitemapStreamOptions {
     maxEntriesPerFile?: number;
     /** The name of the main sitemap or sitemap index file. @default 'sitemap.xml' */
     filename?: string;
+    /** Whether to generate a shard manifest file. @default false */
+    generateManifest?: boolean;
     /** Configuration for staging files before atomic deployment. */
     shadow?: {
         /** Whether shadow processing is enabled. */
@@ -701,6 +842,8 @@ interface SitemapGeneratorOptions extends SitemapStreamOptions {
         total: number;
         percentage: number;
     }) => void;
+    /** Compression configuration for reducing sitemap file sizes. @since 3.1.0 */
+    compression?: CompressionOptions;
 }
 /**
  * SitemapGenerator is the primary orchestrator for creating sitemaps in Gravito.
@@ -726,9 +869,28 @@ declare class SitemapGenerator {
     private options;
     private shadowProcessor;
     constructor(options: SitemapGeneratorOptions);
+    /**
+     * Orchestrates the sitemap generation process.
+     *
+     * This method scans all providers, handles sharding, generates the XML files,
+     * and optionally creates a sitemap index and manifest.
+     */
     run(): Promise<void>;
     /**
-     * 獲取影子處理器（如果啟用）
+     * 統一的 sitemap 寫入方法，優先使用串流寫入以降低記憶體使用。
+     *
+     * @param stream - SitemapStream 實例
+     * @param filename - 檔案名稱（不含 .gz）
+     * @returns 實際寫入的檔名（可能包含 .gz）
+     * @since 3.1.0
+     */
+    private writeSitemap;
+    /**
+     * Normalizes a URL to an absolute URL using the base URL.
+     */
+    private normalizeUrl;
+    /**
+     * Returns the shadow processor instance if enabled.
      */
     getShadowProcessor(): ShadowProcessor | null;
 }
@@ -736,25 +898,23 @@ declare class SitemapGenerator {
 /**
  * Options for configuring the `IncrementalGenerator`.
  *
- * Extends `SitemapGeneratorOptions` to include change tracking and difference
- * calculation components.
- *
  * @public
  * @since 3.0.0
  */
 interface IncrementalGeneratorOptions extends SitemapGeneratorOptions {
-    /** The change tracker used to store and retrieve sitemap changes. */
+    /** The change tracker used to retrieve and record structural site changes. */
     changeTracker: ChangeTracker;
-    /** Optional difference calculator. Defaults to a new `DiffCalculator` instance. */
+    /** Optional diff calculator to identify added, updated, or removed entries. */
     diffCalculator?: DiffCalculator;
-    /** Whether to automatically track changes during full generation. @default true */
+    /** Whether to automatically track new entries discovered during full generation. @default true */
     autoTrack?: boolean;
 }
 /**
- * IncrementalGenerator optimizes sitemap updates by processing only changed URLs.
+ * IncrementalGenerator manages partial updates to the sitemap based on detected changes.
  *
- * Instead of regenerating the entire sitemap from scratch, it uses a `ChangeTracker`
- * to identify new, updated, or removed URLs and updates the sitemap incrementally.
+ * It provides methods for performing both full and incremental generations,
+ * using a `ChangeTracker` to determine which parts of the sitemap need updating.
+ * This is particularly efficient for large sites where full regeneration is costly.
  *
  * @public
  * @since 3.0.0
@@ -764,33 +924,51 @@ declare class IncrementalGenerator {
     private changeTracker;
     private diffCalculator;
     private generator;
+    private mutex;
     constructor(options: IncrementalGeneratorOptions);
     /**
-     * 生成完整的 sitemap（首次生成）
+     * Performs a full sitemap generation and optionally records all entries in the change tracker.
      */
     generateFull(): Promise<void>;
     /**
-     * 增量生成（只更新變更的部分）
+     * Performs an incremental sitemap update based on changes recorded since a specific time.
+     *
+     * If the number of changes exceeds a certain threshold (e.g., 30% of total URLs),
+     * a full generation is triggered instead to ensure consistency.
+     *
+     * @param since - Optional start date for the incremental update.
      */
     generateIncremental(since?: Date): Promise<void>;
     /**
-     * 手動追蹤變更
+     * Internal implementation of full sitemap generation.
      */
-    trackChange(change: SitemapChange): Promise<void>;
+    private performFullGeneration;
     /**
-     * 獲取變更記錄
+     * Internal implementation of incremental sitemap generation.
      */
-    getChanges(since?: Date): Promise<SitemapChange[]>;
+    private performIncrementalGeneration;
+    /**
+     * Normalizes a URL to an absolute URL using the base URL.
+     */
+    private normalizeUrl;
+    /**
+     * Loads the sitemap shard manifest from storage.
+     */
+    private loadManifest;
+    /**
+     * Identifies which shards are affected by the given set of changes.
+     */
+    private getAffectedShards;
     /**
-     * 載入基礎 entries（從現有 sitemap）
+     * Updates the affected shards in storage.
      */
-    private loadBaseEntries;
+    private updateShards;
     /**
-     * 生成差異部分
+     * Applies changes to a set of sitemap entries and returns the updated, sorted list.
      */
-    private generateDiff;
+    private applyChanges;
     /**
-     * 將 AsyncIterable 轉換為陣列
+     * Helper to convert an async iterable into an array.
      */
     private toArray;
 }
@@ -823,31 +1001,44 @@ declare class ProgressTracker {
     private updateTimer;
     constructor(options: ProgressTrackerOptions);
     /**
-     * 初始化進度追蹤
+     * Initializes progress tracking for a new job.
+     *
+     * @param jobId - Unique identifier for the generation job.
+     * @param total - Total number of entries to be processed.
      */
     init(jobId: string, total: number): Promise<void>;
     /**
-     * 更新進度
+     * Updates the current progress of the job.
+     *
+     * Updates are debounced and flushed to storage at regular intervals
+     * specified by `updateInterval` to avoid excessive write operations.
+     *
+     * @param processed - Number of entries processed so far.
+     * @param status - Optional new status for the job.
      */
     update(processed: number, status?: SitemapProgress['status']): Promise<void>;
     /**
-     * 完成進度追蹤
+     * Marks the current job as successfully completed.
      */
     complete(): Promise<void>;
     /**
-     * 標記為失敗
+     * Marks the current job as failed with an error message.
+     *
+     * @param error - The error message describing why the job failed.
      */
     fail(error: string): Promise<void>;
     /**
-     * 刷新進度到儲存
+     * Flushes the current progress state to the storage backend.
      */
     private flush;
     /**
-     * 停止更新計時器
+     * Stops the periodic update timer.
      */
     private stop;
     /**
-     * 獲取當前進度
+     * Returns a copy of the current progress state.
+     *
+     * @returns The current SitemapProgress object, or null if no job is active.
      */
     getCurrentProgress(): SitemapProgress | null;
 }
@@ -873,9 +1064,29 @@ declare class SitemapIndex {
     private options;
     private entries;
     constructor(options: SitemapStreamOptions);
+    /**
+     * Adds a single entry to the sitemap index.
+     *
+     * @param entry - A sitemap filename or a `SitemapIndexEntry` object.
+     * @returns The `SitemapIndex` instance for chaining.
+     */
     add(entry: string | SitemapIndexEntry): this;
+    /**
+     * Adds multiple entries to the sitemap index.
+     *
+     * @param entries - An array of sitemap filenames or `SitemapIndexEntry` objects.
+     * @returns The `SitemapIndex` instance for chaining.
+     */
     addAll(entries: (string | SitemapIndexEntry)[]): this;
+    /**
+     * Generates the sitemap index XML content.
+     *
+     * @returns The complete XML string for the sitemap index.
+     */
     toXML(): string;
+    /**
+     * Escapes special XML characters in a string.
+     */
     private escape;
 }
 
@@ -902,16 +1113,73 @@ declare class SitemapIndex {
 declare class SitemapStream {
     private options;
     private entries;
+    private flags;
     constructor(options: SitemapStreamOptions);
+    /**
+     * Adds a single entry to the sitemap stream.
+     *
+     * @param entry - A URL string or a complete `SitemapEntry` object.
+     * @returns The `SitemapStream` instance for chaining.
+     */
     add(entry: string | SitemapEntry): this;
+    /**
+     * Adds multiple entries to the sitemap stream.
+     *
+     * @param entries - An array of URL strings or `SitemapEntry` objects.
+     * @returns The `SitemapStream` instance for chaining.
+     */
     addAll(entries: (string | SitemapEntry)[]): this;
+    /**
+     * Generates the sitemap XML content.
+     *
+     * Automatically includes the necessary XML namespaces for images, videos, news,
+     * and internationalization if the entries contain such metadata.
+     *
+     * @returns The complete XML string for the sitemap.
+     */
     toXML(): string;
+    /**
+     * 以 AsyncGenerator 方式產生 XML 內容。
+     * 每次 yield 一個邏輯區塊，適合串流寫入場景，可減少記憶體峰值。
+     *
+     * @returns AsyncGenerator 產生 XML 字串片段
+     *
+     * @example
+     * ```typescript
+     * const stream = new SitemapStream({ baseUrl: 'https://example.com' })
+     * stream.add({ url: '/page1' })
+     * stream.add({ url: '/page2' })
+     *
+     * for await (const chunk of stream.toAsyncIterable()) {
+     *   process.stdout.write(chunk)
+     * }
+     * ```
+     *
+     * @since 3.1.0
+     */
+    toAsyncIterable(): AsyncGenerator<string, void, unknown>;
+    /**
+     * 同步版本的 iterable，供 toXML() 使用。
+     */
+    private toSyncIterable;
+    /**
+     * 建立 urlset 開標籤與所有必要的 XML 命名空間。
+     */
+    private buildUrlsetOpenTag;
+    /**
+     * Renders a single sitemap entry into its XML representation.
+     */
     private renderUrl;
-    private hasImages;
-    private hasVideos;
-    private hasNews;
-    private hasAlternates;
+    /**
+     * Escapes special XML characters in a string.
+     */
     private escape;
+    /**
+     * Returns all entries currently in the stream.
+     *
+     * @returns An array of `SitemapEntry` objects.
+     */
+    getEntries(): SitemapEntry[];
 }
 
 /**
@@ -922,10 +1190,18 @@ type I18nSitemapEntryOptions = Omit<SitemapEntry, 'url' | 'alternates'>;
 /**
  * Generate fully cross-referenced SitemapEntries for multiple locales.
  *
- * @param path The path relative to the locale prefix (e.g. '/docs/intro')
- * @param locales List of supported locales (e.g. ['en', 'zh', 'jp'])
- * @param baseUrl The domain root (e.g. 'https://gravito.dev'). IF provided, URLs will be absolute. If not, they remain relative paths but include the locale prefix.
- * @param options Additional SitemapEntry options (lastmod, priority, etc.)
+ * This helper creates a set of sitemap entries where each entry represents a
+ * specific locale version of a page, and all entries are linked via `xhtml:link`
+ * alternate tags to satisfy Google's internationalization requirements.
+ *
+ * @param path - The path relative to the locale prefix (e.g., '/docs/intro').
+ * @param locales - List of supported language/region codes (e.g., ['en', 'zh-TW']).
+ * @param baseUrl - The domain root (e.g., 'https://example.com').
+ * @param options - Additional SitemapEntry properties like `lastmod` or `priority`.
+ * @returns An array of interconnected `SitemapEntry` objects.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare function generateI18nEntries(path: string, locales: string[], baseUrl?: string, options?: I18nSitemapEntryOptions): SitemapEntry[];
 
@@ -971,154 +1247,880 @@ declare class GenerateSitemapJob extends Job {
     private totalEntries;
     private processedEntries;
     constructor(options: GenerateSitemapJobOptions);
+    /**
+     * Main entry point for the job execution.
+     *
+     * Orchestrates the full lifecycle of sitemap generation, including progress
+     * initialization, generation, shadow commit, and error handling.
+     */
     handle(): Promise<void>;
     /**
-     * 計算總 URL 數
+     * Calculates the total number of URL entries from all providers.
+     *
+     * @returns A promise resolving to the total entry count.
      */
     private calculateTotal;
     /**
-     * 帶進度追蹤的生成
+     * Performs sitemap generation while reporting progress to the tracker and callback.
      */
     private generateWithProgress;
 }
 
 /**
- * Configuration for a dynamically generated sitemap that is built upon request.
- *
- * Useful for small to medium sites where fresh data is critical. Dynamic sitemaps
- * are generated on-the-fly and can be cached at the HTTP level.
- *
- * @public
- * @since 3.0.0
- */
-interface DynamicSitemapOptions extends SitemapStreamOptions {
-    /** The URL path where the sitemap will be exposed. @default '/sitemap.xml' */
-    path?: string | undefined;
-    /** List of sitemap entry providers to scan for content. */
-    providers: SitemapProvider[];
-    /** Cache duration in seconds for the HTTP response. @default undefined (no-cache) */
-    cacheSeconds?: number | undefined;
-    /** Persistence backend for cached XML files. Defaults to MemorySitemapStorage. */
-    storage?: SitemapStorage | undefined;
-    /** Optional distributed lock to prevent "cache stampede" during heavy generation. */
-    lock?: SitemapLock | undefined;
-}
-/**
- * Configuration for a statically pre-generated sitemap.
+ * In-memory lock implementation for single-instance sitemap generation.
  *
- * Recommended for large sites or high-traffic applications. Static sitemaps
- * are built (usually as part of a build process) and served as static files.
+ * Provides mutex-style mutual exclusion within a single Node.js process using a Map-based
+ * storage mechanism. Designed for development environments and single-instance deployments
+ * where distributed coordination is not required.
  *
- * @public
- * @since 3.0.0
- */
-interface StaticSitemapOptions extends SitemapStreamOptions {
-    /** Local directory where generated XML files will be saved. */
-    outDir: string;
-    /** The name of the root sitemap file. @default 'sitemap.xml' */
-    filename?: string | undefined;
-    /** List of sitemap entry providers to scan for content. */
-    providers: SitemapProvider[];
-    /** Custom storage backend. Defaults to DiskSitemapStorage using `outDir`. */
-    storage?: SitemapStorage | undefined;
-    /** Optional incremental generation settings to only update changed URLs. */
-    incremental?: {
-        /** Whether to enable incremental builds. */
-        enabled: boolean;
-        /** Backend for tracking structural site changes. */
-        changeTracker: ChangeTracker;
-        /** Whether to automatically record new changes during scan. @default false */
-        autoTrack?: boolean;
-    };
-    /** Optional SEO redirect orchestration settings. */
-    redirect?: {
-        /** Whether to automatically handle 301/302 redirects found in sitemap. */
-        enabled: boolean;
-        /** Backend for managing and resolving redirect rules. */
-        manager: RedirectManager;
-        /** Strategy for resolving conflicting or chained redirects. @default 'remove_old_add_new' */
-        strategy?: 'remove_old_add_new' | 'keep_relation' | 'update_url' | 'dual_mark';
-        /** Whether to resolve redirect chains into a single jump. @default false */
-        followChains?: boolean;
-        /** Maximum number of redirect jumps to follow. @default 5 */
-        maxChainLength?: number;
-    };
-    /** Deployment settings for atomic sitemap updates via shadow staging. */
-    shadow?: {
-        /** Whether to enable "shadow" (atomic staging) mode. */
-        enabled: boolean;
-        /** The update strategy: 'atomic' (full swap) or 'versioned' (archived). @default 'atomic' */
-        mode: 'atomic' | 'versioned';
-    };
-    /** Persistence backend for long-running job progress tracking. */
-    progressStorage?: SitemapProgressStorage;
-}
-/**
- * OrbitSitemap is the enterprise SEO orchestration module for Gravito.
+ * **When to use:**
+ * - Development and testing environments
+ * - Single-instance production deployments (e.g., single Docker container)
+ * - Scenarios where Redis infrastructure is unavailable
  *
- * It provides advanced sitemap generation supporting large-scale indexing,
- * automatic 301/302 redirect handling, and atomic sitemap deployments.
+ * **When NOT to use:**
+ * - Kubernetes or multi-instance deployments (use {@link RedisLock} instead)
+ * - Horizontally scaled applications
+ * - Any environment requiring cross-process synchronization
  *
- * It can operate in two modes:
- * 1. **Dynamic**: Sitemaps are generated on-the-fly and cached.
- * 2. **Static**: Sitemaps are pre-built (e.g., during CI/CD) and served from disk or cloud storage.
+ * **Design rationale:**
+ * - Zero external dependencies (no Redis, no database)
+ * - Automatic TTL-based lock expiration to prevent deadlocks
+ * - Synchronous cleanup of expired locks during read operations
+ * - Fast in-process performance with O(1) lock operations
  *
- * @example Dynamic Mode
+ * @example Basic usage with try-finally pattern
  * ```typescript
- * const sitemap = OrbitSitemap.dynamic({
- *   baseUrl: 'https://example.com',
- *   providers: [new PostSitemapProvider()]
- * });
- * core.addOrbit(sitemap);
+ * import { MemoryLock } from '@gravito/constellation'
+ *
+ * const lock = new MemoryLock()
+ *
+ * // Attempt to acquire lock with 60-second TTL
+ * const acquired = await lock.acquire('sitemap-generation', 60000)
+ * if (acquired) {
+ *   try {
+ *     // Perform exclusive operation
+ *     await generateSitemap()
+ *   } finally {
+ *     // Always release lock to prevent resource leakage
+ *     await lock.release('sitemap-generation')
+ *   }
+ * } else {
+ *   console.log('Another process is generating sitemap, skipping')
+ * }
  * ```
  *
- * @example Static Mode
+ * @example Handling lock contention
  * ```typescript
- * const sitemap = OrbitSitemap.static({
- *   baseUrl: 'https://example.com',
- *   outDir: './public',
- *   shadow: { enabled: true, mode: 'atomic' }
- * });
- * await sitemap.generate();
+ * const lock = new MemoryLock()
+ *
+ * if (!await lock.acquire('expensive-operation', 30000)) {
+ *   return new Response('Service busy, try again later', {
+ *     status: 503,
+ *     headers: { 'Retry-After': '30' }
+ *   })
+ * }
  * ```
  *
  * @public
- * @since 3.0.0
+ * @since 3.1.0
  */
-declare class OrbitSitemap implements GravitoOrbit {
-    private options;
-    private mode;
-    private constructor();
+declare class MemoryLock implements SitemapLock {
     /**
-     * Create a dynamic sitemap configuration.
+     * Internal map storing resource identifiers to their lock expiration timestamps.
      *
-     * @param options - The dynamic sitemap options.
-     * @returns An OrbitSitemap instance configured for dynamic generation.
+     * Keys represent unique resource identifiers (e.g., 'sitemap-generation').
+     * Values are Unix timestamps in milliseconds representing when the lock expires.
+     * Expired locks are automatically cleaned up during `acquire()` and `isLocked()` calls.
      */
-    static dynamic(options: DynamicSitemapOptions): OrbitSitemap;
+    private locks;
     /**
-     * Create a static sitemap configuration.
+     * Attempts to acquire an exclusive lock on the specified resource.
      *
-     * @param options - The static sitemap options.
-     * @returns An OrbitSitemap instance configured for static generation.
+     * Uses a test-and-set approach: checks if the lock exists and is valid, then atomically
+     * sets the lock if available. Expired locks are treated as available and automatically
+     * replaced during acquisition.
+     *
+     * **Behavior:**
+     * - Returns `true` if lock was successfully acquired
+     * - Returns `false` if resource is already locked by another caller
+     * - Automatically replaces expired locks (acts as self-healing mechanism)
+     * - Lock automatically expires after TTL milliseconds
+     *
+     * **Race condition handling:**
+     * Safe within a single process due to JavaScript's single-threaded event loop.
+     * NOT safe across multiple processes or instances (use RedisLock for that).
+     *
+     * @param resource - Unique identifier for the resource to lock (e.g., 'sitemap-generation', 'blog-index').
+     *                   Should be consistent across all callers attempting to lock the same resource.
+     * @param ttl - Time-to-live in milliseconds. Lock automatically expires after this duration.
+     *              Recommended: 2-5x the expected operation duration to prevent premature expiration.
+     * @returns Promise resolving to `true` if lock acquired, `false` if already locked.
+     *
+     * @example Preventing concurrent sitemap generation
+     * ```typescript
+     * const lock = new MemoryLock()
+     * const acquired = await lock.acquire('sitemap-generation', 60000)
+     *
+     * if (!acquired) {
+     *   console.log('Another process is already generating the sitemap')
+     *   return new Response('Generation in progress', { status: 503 })
+     * }
+     *
+     * try {
+     *   await generateSitemap()
+     * } finally {
+     *   await lock.release('sitemap-generation')
+     * }
+     * ```
+     *
+     * @example Setting appropriate TTL
+     * ```typescript
+     * // For fast operations (< 1 second), use short TTL
+     * await lock.acquire('cache-refresh', 5000)
+     *
+     * // For slow operations (minutes), use longer TTL
+     * await lock.acquire('full-reindex', 300000) // 5 minutes
+     * ```
      */
-    static static(options: StaticSitemapOptions): OrbitSitemap;
+    acquire(resource: string, ttl: number): Promise<boolean>;
     /**
-     * Install the sitemap module into PlanetCore.
+     * Releases the lock on the specified resource, allowing others to acquire it.
      *
-     * @param core - The PlanetCore instance.
+     * Immediately removes the lock from memory without any ownership validation.
+     * Unlike RedisLock, this does NOT verify that the caller is the lock owner,
+     * so callers must ensure they only release locks they acquired.
+     *
+     * **Best practices:**
+     * - Always call `release()` in a `finally` block to prevent lock leakage
+     * - Only release locks you successfully acquired
+     * - If operation fails, still release the lock to allow retry
+     *
+     * **Idempotency:**
+     * Safe to call multiple times on the same resource. Releasing a non-existent
+     * lock is a no-op.
+     *
+     * @param resource - The resource identifier to unlock. Must match the identifier
+     *                   used in the corresponding `acquire()` call.
+     *
+     * @example Proper release pattern with try-finally
+     * ```typescript
+     * const acquired = await lock.acquire('sitemap-generation', 60000)
+     * if (!acquired) return
+     *
+     * try {
+     *   await generateSitemap()
+     * } finally {
+     *   // Always release, even if operation throws
+     *   await lock.release('sitemap-generation')
+     * }
+     * ```
+     *
+     * @example Handling operation failures
+     * ```typescript
+     * const acquired = await lock.acquire('data-import', 120000)
+     * if (!acquired) return
+     *
+     * try {
+     *   await importData()
+     * } catch (error) {
+     *   console.error('Import failed:', error)
+     *   // Lock still released in finally block
+     *   throw error
+     * } finally {
+     *   await lock.release('data-import')
+     * }
+     * ```
+     */
+    release(resource: string): Promise<void>;
+    /**
+     * Checks whether a resource is currently locked and has not expired.
+     *
+     * Performs automatic cleanup by removing expired locks during the check,
+     * ensuring the internal map doesn't accumulate stale entries over time.
+     *
+     * **Use cases:**
+     * - Pre-flight checks before attempting expensive operations
+     * - Status monitoring and health checks
+     * - Implementing custom retry logic
+     * - Debugging and testing
+     *
+     * **Side effects:**
+     * Automatically deletes expired locks as a garbage collection mechanism.
+     * This is intentional to prevent memory leaks from abandoned locks.
+     *
+     * @param resource - The resource identifier to check for lock status.
+     * @returns Promise resolving to `true` if resource is actively locked (not expired),
+     *          `false` if unlocked or lock has expired.
+     *
+     * @example Pre-flight check before starting work
+     * ```typescript
+     * const lock = new MemoryLock()
+     *
+     * if (await lock.isLocked('sitemap-generation')) {
+     *   console.log('Sitemap generation already in progress')
+     *   return
+     * }
+     *
+     * // Safe to proceed
+     * await lock.acquire('sitemap-generation', 60000)
+     * ```
+     *
+     * @example Health check endpoint
+     * ```typescript
+     * app.get('/health/locks', async (c) => {
+     *   const isGenerating = await lock.isLocked('sitemap-generation')
+     *   const isIndexing = await lock.isLocked('search-indexing')
+     *
+     *   return c.json({
+     *     sitemapGeneration: isGenerating ? 'in-progress' : 'idle',
+     *     searchIndexing: isIndexing ? 'in-progress' : 'idle'
+     *   })
+     * })
+     * ```
+     *
+     * @example Custom retry logic
+     * ```typescript
+     * let attempts = 0
+     * while (attempts < 5) {
+     *   if (!await lock.isLocked('resource')) {
+     *     const acquired = await lock.acquire('resource', 10000)
+     *     if (acquired) break
+     *   }
+     *   await sleep(1000)
+     *   attempts++
+     * }
+     * ```
+     */
+    isLocked(resource: string): Promise<boolean>;
+    /**
+     * Clears all locks from memory, including both active and expired locks.
+     *
+     * **Use cases:**
+     * - Test cleanup between test cases to ensure isolation
+     * - Application shutdown to release all resources
+     * - Manual intervention during debugging
+     * - Resetting state after catastrophic errors
+     *
+     * **Warning:**
+     * This forcibly releases ALL locks without any ownership validation.
+     * Should not be called during normal operation in production environments.
+     *
+     * @example Test cleanup with beforeEach hook
+     * ```typescript
+     * import { describe, beforeEach, test } from 'vitest'
+     *
+     * const lock = new MemoryLock()
+     *
+     * beforeEach(async () => {
+     *   await lock.clear() // Ensure clean state for each test
+     * })
+     *
+     * test('lock acquisition', async () => {
+     *   const acquired = await lock.acquire('test-resource', 5000)
+     *   expect(acquired).toBe(true)
+     * })
+     * ```
+     *
+     * @example Graceful shutdown handler
+     * ```typescript
+     * process.on('SIGTERM', async () => {
+     *   console.log('Shutting down, releasing all locks...')
+     *   await lock.clear()
+     *   process.exit(0)
+     * })
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the number of lock entries currently stored in memory.
+     *
+     * **Important:** This includes BOTH active and expired locks. Expired locks
+     * are only cleaned up during `acquire()` or `isLocked()` calls, so this count
+     * may include stale entries.
+     *
+     * **Use cases:**
+     * - Monitoring memory usage and lock accumulation
+     * - Debugging lock leakage issues
+     * - Testing lock lifecycle behavior
+     * - Detecting abnormal lock retention patterns
+     *
+     * **Not suitable for:**
+     * - Determining number of ACTIVE locks (use `isLocked()` on each resource)
+     * - Production health checks (includes expired locks)
+     *
+     * @returns The total number of lock entries in the internal Map, including expired ones.
+     *
+     * @example Monitoring lock accumulation
+     * ```typescript
+     * const lock = new MemoryLock()
+     *
+     * setInterval(() => {
+     *   const count = lock.size()
+     *   if (count > 100) {
+     *     console.warn(`High lock count detected: ${count}`)
+     *     // May indicate lock leakage or missing release() calls
+     *   }
+     * }, 60000)
+     * ```
+     *
+     * @example Testing lock cleanup behavior
+     * ```typescript
+     * import { test, expect } from 'vitest'
+     *
+     * test('expired locks are cleaned up', async () => {
+     *   const lock = new MemoryLock()
+     *
+     *   await lock.acquire('resource', 10)
+     *   expect(lock.size()).toBe(1)
+     *
+     *   await sleep(20) // Wait for expiration
+     *   expect(lock.size()).toBe(1) // Still in map (not cleaned yet)
+     *
+     *   await lock.isLocked('resource') // Triggers cleanup
+     *   expect(lock.size()).toBe(0) // Now removed
+     * })
+     * ```
+     */
+    size(): number;
+}
+
+/**
+ * Minimal Redis client interface required for distributed locking operations.
+ *
+ * Designed to be compatible with popular Redis clients (node-redis, ioredis)
+ * while keeping dependencies minimal. Only requires SET NX EX and EVAL commands
+ * for atomic lock operations.
+ *
+ * @public
+ * @since 3.1.0
+ */
+interface RedisClient {
+    /**
+     * Atomically sets a key with value only if key doesn't exist (NX) and expires after TTL seconds (EX).
+     *
+     * This is the core primitive for distributed lock acquisition. The combination of
+     * NX (Not eXists) and EX (EXpiration) flags ensures atomicity and auto-release.
+     *
+     * @param key - Redis key for the lock (e.g., 'sitemap:lock:generation')
+     * @param value - Unique lock identifier (UUID) for ownership validation
+     * @param mode - Must be 'EX' for expiration in seconds
+     * @param ttl - Time-to-live in seconds before auto-release
+     * @param flag - Must be 'NX' to set only if not exists
+     * @returns 'OK' if lock acquired, null if key already exists
+     */
+    set(key: string, value: string, mode: 'EX', ttl: number, flag: 'NX'): Promise<string | null>;
+    /**
+     * Executes a Lua script atomically on the Redis server.
+     *
+     * Used for safe lock release: compares lock owner and deletes in a single atomic operation.
+     * This prevents accidentally releasing locks held by other instances.
+     *
+     * @param script - Lua script source code
+     * @param numKeys - Number of Redis keys referenced in the script
+     * @param args - Keys and arguments for the script (KEYS[], ARGV[])
+     * @returns Script execution result (1 if deleted, 0 if not owner)
+     */
+    eval(script: string, numKeys: number, ...args: string[]): Promise<number>;
+}
+/**
+ * Configuration options for RedisLock distributed locking.
+ *
+ * @public
+ * @since 3.1.0
+ */
+interface RedisLockOptions {
+    /**
+     * Connected Redis client instance.
+     *
+     * Must be already connected and ready for commands.
+     * Supports node-redis, ioredis, or any client implementing RedisClient interface.
+     */
+    client: RedisClient;
+    /**
+     * Prefix for all lock keys in Redis.
+     *
+     * Recommended to include namespace and entity type for clarity.
+     *
+     * @defaultValue 'sitemap:lock:'
+     * @example 'myapp:sitemap:lock:'
+     */
+    keyPrefix?: string;
+    /**
+     * Number of retry attempts if lock acquisition fails.
+     *
+     * Set to 0 for fail-fast behavior (no retries).
+     * Recommended: 3-5 retries for transient contention.
+     *
+     * @defaultValue 0
+     */
+    retryCount?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     *
+     * Should be tuned based on expected lock hold time.
+     * Too short: wastes CPU, too long: increases latency.
+     *
+     * @defaultValue 100
+     */
+    retryDelay?: number;
+}
+/**
+ * Redis-based distributed lock for multi-instance sitemap generation.
+ *
+ * Implements distributed mutual exclusion using Redis atomic operations (SET NX EX)
+ * and Lua scripts for safe ownership-validated release. Designed for production
+ * environments where multiple instances compete for exclusive access to resources.
+ *
+ * **When to use:**
+ * - Kubernetes or Docker Swarm multi-replica deployments
+ * - Horizontally scaled applications (multiple instances/VMs)
+ * - Any environment requiring cross-process/cross-machine synchronization
+ * - Production systems where cache stampede prevention is critical
+ *
+ * **When NOT to use:**
+ * - Single-instance deployments (use {@link MemoryLock} instead)
+ * - Development/testing environments without Redis infrastructure
+ * - Scenarios where eventual consistency is acceptable
+ *
+ * **Design rationale:**
+ * - Atomic operations prevent race conditions at Redis level
+ * - Unique lock ID (UUID) ensures only owner can release lock
+ * - Auto-expiration (TTL) prevents deadlocks from crashed instances
+ * - Retry mechanism handles transient contention gracefully
+ * - Lua scripts provide atomicity for compare-and-delete operations
+ *
+ * **Comparison with RedLock:**
+ * This implementation uses a single Redis instance. For Redis Cluster deployments,
+ * consider implementing the RedLock algorithm (multiple Redis masters) for higher
+ * availability. Current implementation trades off some availability for simplicity.
+ *
+ * @example Basic usage with node-redis
+ * ```typescript
+ * import { RedisLock } from '@gravito/constellation'
+ * import { createClient } from 'redis'
+ *
+ * const redisClient = createClient({ url: 'redis://localhost:6379' })
+ * await redisClient.connect()
+ *
+ * const lock = new RedisLock({
+ *   client: redisClient,
+ *   keyPrefix: 'sitemap:lock:',
+ *   retryCount: 3,
+ *   retryDelay: 100
+ * })
+ *
+ * const acquired = await lock.acquire('sitemap-generation', 60000)
+ * if (acquired) {
+ *   try {
+ *     await generateSitemap()
+ *   } finally {
+ *     await lock.release('sitemap-generation')
+ *   }
+ * }
+ * ```
+ *
+ * @example Production deployment with Kubernetes
+ * ```typescript
+ * // In Kubernetes, multiple pods compete for the lock
+ * const lock = new RedisLock({
+ *   client: redisClient,
+ *   keyPrefix: `${process.env.K8S_NAMESPACE}:sitemap:lock:`,
+ *   retryCount: 5,
+ *   retryDelay: 200
+ * })
+ *
+ * // Pod 1 acquires lock
+ * const acquired = await lock.acquire('generation', 300000)
+ * if (!acquired) {
+ *   // Pod 2, 3, ... receive 503 and retry later
+ *   return new Response('Another pod is generating sitemap', {
+ *     status: 503,
+ *     headers: { 'Retry-After': '60' }
+ *   })
+ * }
+ * ```
+ *
+ * @example Handling Redis connection failures
+ * ```typescript
+ * const lock = new RedisLock({ client: redisClient })
+ *
+ * try {
+ *   const acquired = await lock.acquire('resource', 30000)
+ *   // If Redis is down, acquire() returns false (logged internally)
+ *   if (!acquired) {
+ *     console.log('Lock acquisition failed (may be Redis connection issue)')
+ *   }
+ * } catch (error) {
+ *   // Network errors are caught and logged, not thrown
+ *   console.error('Unexpected error:', error)
+ * }
+ * ```
+ *
+ * @public
+ * @since 3.1.0
+ */
+declare class RedisLock implements SitemapLock {
+    private options;
+    /**
+     * Unique identifier for this lock instance.
+     *
+     * Generated once during construction and used for all locks acquired by this instance.
+     * Enables ownership validation: only the instance that acquired the lock can release it.
+     *
+     * **Security consideration:**
+     * UUIDs are sufficiently random to prevent lock hijacking across instances.
+     * However, they are stored in plain text in Redis (not encrypted).
+     */
+    private lockId;
+    /**
+     * Redis key prefix for all locks acquired through this instance.
+     *
+     * Combined with resource name to form full Redis key (e.g., 'sitemap:lock:generation').
+     * Allows namespace isolation and easier debugging in Redis CLI.
+     */
+    private keyPrefix;
+    /**
+     * Maximum number of retry attempts when lock is held by another instance.
+     *
+     * Set to 0 for fail-fast behavior. Higher values increase acquisition success
+     * rate but also increase latency under contention.
+     */
+    private retryCount;
+    /**
+     * Delay in milliseconds between consecutive retry attempts.
+     *
+     * Should be tuned based on expected lock hold time. Typical values: 50-500ms.
+     */
+    private retryDelay;
+    /**
+     * Constructs a new RedisLock instance with the specified configuration.
+     *
+     * @param options - Configuration including Redis client and retry parameters.
+     *
+     * @example With custom retry strategy
+     * ```typescript
+     * const lock = new RedisLock({
+     *   client: redisClient,
+     *   keyPrefix: 'app:locks:',
+     *   retryCount: 10,    // More retries for high-contention scenarios
+     *   retryDelay: 50     // Shorter delay for low-latency requirements
+     * })
+     * ```
+     */
+    constructor(options: RedisLockOptions);
+    /**
+     * Attempts to acquire a distributed lock using Redis SET NX EX command.
+     *
+     * Uses atomic Redis operations to ensure only one instance across your entire
+     * infrastructure can hold the lock at any given time. Implements retry logic
+     * with exponential backoff for handling transient contention.
+     *
+     * **Algorithm:**
+     * 1. Convert TTL from milliseconds to seconds (Redis requirement)
+     * 2. Attempt Redis SET key lockId EX ttl NX (atomic operation)
+     * 3. If successful (returns 'OK'), lock acquired
+     * 4. If failed (returns null), retry up to retryCount times with retryDelay
+     * 5. Return true if acquired, false if all attempts exhausted
+     *
+     * **Atomicity guarantee:**
+     * The combination of NX (set if Not eXists) and EX (set EXpiration) in a single
+     * Redis command ensures no race conditions. Either the lock is acquired or it isn't.
+     *
+     * **Error handling:**
+     * Redis connection errors are caught, logged to console, and treated as acquisition
+     * failure (returns false). This fail-safe behavior prevents exceptions from bubbling
+     * up to application code.
+     *
+     * **Performance:**
+     * - Single instance: O(1) Redis operation
+     * - With retry: O(retryCount) worst case
+     * - Network latency: ~1-5ms per attempt (depends on Redis location)
+     *
+     * @param resource - Unique identifier for the resource to lock.
+     *                   Combined with keyPrefix to form Redis key.
+     * @param ttl - Time-to-live in milliseconds. Lock auto-expires after this duration.
+     *              Recommended: 2-5x expected operation time to handle slowdowns.
+     *              Minimum: 1000ms (1 second) for practical use.
+     * @returns Promise resolving to `true` if lock acquired, `false` if held by another instance
+     *          or Redis connection failed.
+     *
+     * @example Basic acquisition in distributed environment
+     * ```typescript
+     * const lock = new RedisLock({ client: redisClient })
+     * const acquired = await lock.acquire('sitemap-generation', 60000)
+     *
+     * if (!acquired) {
+     *   // Another instance (e.g., different Kubernetes pod) holds the lock
+     *   console.log('Sitemap generation in progress on another instance')
+     *   return new Response('Service busy', {
+     *     status: 503,
+     *     headers: { 'Retry-After': '30' }
+     *   })
+     * }
+     *
+     * try {
+     *   await generateSitemap()
+     * } finally {
+     *   await lock.release('sitemap-generation')
+     * }
+     * ```
+     *
+     * @example With retry logic for transient contention
+     * ```typescript
+     * const lock = new RedisLock({
+     *   client: redisClient,
+     *   retryCount: 5,
+     *   retryDelay: 200
+     * })
+     *
+     * // Will retry 5 times with 200ms delay between attempts
+     * const acquired = await lock.acquire('data-import', 120000)
+     * ```
+     *
+     * @example Setting appropriate TTL
+     * ```typescript
+     * // Fast operation: short TTL
+     * await lock.acquire('cache-rebuild', 10000) // 10 seconds
+     *
+     * // Slow operation: longer TTL with buffer
+     * await lock.acquire('full-sitemap', 300000) // 5 minutes
+     *
+     * // Very slow operation: generous TTL
+     * await lock.acquire('data-migration', 1800000) // 30 minutes
+     * ```
+     */
+    acquire(resource: string, ttl: number): Promise<boolean>;
+    /**
+     * Releases the distributed lock using Lua script for atomic ownership validation.
+     *
+     * Uses a Lua script to atomically check if the current instance owns the lock
+     * (by comparing lockId) and delete it if so. This prevents accidentally releasing
+     * locks held by other instances, which could cause data corruption in distributed systems.
+     *
+     * **Lua script logic:**
+     * ```lua
+     * if redis.call("get", KEYS[1]) == ARGV[1] then
+     *   return redis.call("del", KEYS[1])  -- Delete only if owner matches
+     * else
+     *   return 0  -- Not owner or lock expired, do nothing
+     * end
+     * ```
+     *
+     * **Why Lua scripts?**
+     * - Atomicity: GET + comparison + DEL execute as one atomic operation
+     * - Prevents race conditions: Lock cannot change between check and delete
+     * - Server-side execution: No network round trips between steps
+     *
+     * **Error handling:**
+     * Errors during release (e.g., Redis connection loss) are logged but do NOT throw.
+     * This is intentional: if instance crashed or TTL expired, lock is already released.
+     * Silent failure here prevents cascading errors in finally blocks.
+     *
+     * **Idempotency:**
+     * Safe to call multiple times. Releasing an already-released or expired lock is a no-op.
+     *
+     * @param resource - The resource identifier to unlock. Must match the identifier
+     *                   used in the corresponding `acquire()` call.
+     *
+     * @example Proper release pattern with try-finally
+     * ```typescript
+     * const acquired = await lock.acquire('sitemap-generation', 60000)
+     * if (!acquired) return
+     *
+     * try {
+     *   await generateSitemap()
+     * } finally {
+     *   // Always release, even if operation throws
+     *   await lock.release('sitemap-generation')
+     * }
+     * ```
+     *
+     * @example Handling operation failures
+     * ```typescript
+     * const acquired = await lock.acquire('data-processing', 120000)
+     * if (!acquired) {
+     *   throw new Error('Could not acquire lock')
+     * }
+     *
+     * try {
+     *   await processData()
+     * } catch (error) {
+     *   console.error('Processing failed:', error)
+     *   // Lock still released in finally block
+     *   throw error
+     * } finally {
+     *   await lock.release('data-processing')
+     * }
+     * ```
+     *
+     * @example Why ownership validation matters
+     * ```typescript
+     * // Instance A acquires lock with 10-second TTL
+     * const lockA = new RedisLock({ client: redisClientA })
+     * await lockA.acquire('task', 10000)
+     *
+     * // ... 11 seconds pass, lock auto-expires ...
+     *
+     * // Instance B acquires the now-expired lock
+     * const lockB = new RedisLock({ client: redisClientB })
+     * await lockB.acquire('task', 10000)
+     *
+     * // Instance A tries to release (after slowdown/GC pause)
+     * await lockA.release('task')
+     * // ✅ Lua script detects lockId mismatch, does NOT delete B's lock
+     * // ❌ Without Lua: Would delete B's lock, causing data corruption
+     * ```
+     */
+    release(resource: string): Promise<void>;
+    /**
+     * Internal utility for sleeping between retry attempts.
+     *
+     * @param ms - Duration to sleep in milliseconds
+     */
+    private sleep;
+}
+
+/**
+ * Configuration for a dynamically generated sitemap that is built upon request.
+ *
+ * Useful for small to medium sites where fresh data is critical. Dynamic sitemaps
+ * are generated on-the-fly and can be cached at the HTTP level.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface DynamicSitemapOptions extends SitemapStreamOptions {
+    /** The URL path where the sitemap will be exposed. @default '/sitemap.xml' */
+    path?: string | undefined;
+    /** List of sitemap entry providers to scan for content. */
+    providers: SitemapProvider[];
+    /** Cache duration in seconds for the HTTP response. @default undefined (no-cache) */
+    cacheSeconds?: number | undefined;
+    /** Persistence backend for cached XML files. Defaults to MemorySitemapStorage. */
+    storage?: SitemapStorage | undefined;
+    /** Optional distributed lock to prevent "cache stampede" during heavy generation. */
+    lock?: SitemapLock | undefined;
+}
+/**
+ * Configuration for a statically pre-generated sitemap.
+ *
+ * Recommended for large sites or high-traffic applications. Static sitemaps
+ * are built (usually as part of a build process) and served as static files.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface StaticSitemapOptions extends SitemapStreamOptions {
+    /** Local directory where generated XML files will be saved. */
+    outDir: string;
+    /** The name of the root sitemap file. @default 'sitemap.xml' */
+    filename?: string | undefined;
+    /** List of sitemap entry providers to scan for content. */
+    providers: SitemapProvider[];
+    /** Custom storage backend. Defaults to DiskSitemapStorage using `outDir`. */
+    storage?: SitemapStorage | undefined;
+    /** Optional incremental generation settings to only update changed URLs. */
+    incremental?: {
+        /** Whether to enable incremental builds. */
+        enabled: boolean;
+        /** Backend for tracking structural site changes. */
+        changeTracker: ChangeTracker;
+        /** Whether to automatically record new changes during scan. @default false */
+        autoTrack?: boolean;
+    };
+    /** Optional SEO redirect orchestration settings. */
+    redirect?: {
+        /** Whether to automatically handle 301/302 redirects found in sitemap. */
+        enabled: boolean;
+        /** Backend for managing and resolving redirect rules. */
+        manager: RedirectManager;
+        /** Strategy for resolving conflicting or chained redirects. @default 'remove_old_add_new' */
+        strategy?: 'remove_old_add_new' | 'keep_relation' | 'update_url' | 'dual_mark';
+        /** Whether to resolve redirect chains into a single jump. @default false */
+        followChains?: boolean;
+        /** Maximum number of redirect jumps to follow. @default 5 */
+        maxChainLength?: number;
+    };
+    /** Deployment settings for atomic sitemap updates via shadow staging. */
+    shadow?: {
+        /** Whether to enable "shadow" (atomic staging) mode. */
+        enabled: boolean;
+        /** The update strategy: 'atomic' (full swap) or 'versioned' (archived). @default 'atomic' */
+        mode: 'atomic' | 'versioned';
+    };
+    /** Persistence backend for long-running job progress tracking. */
+    progressStorage?: SitemapProgressStorage;
+}
+/**
+ * OrbitSitemap is the enterprise SEO orchestration module for Gravito.
+ *
+ * It provides advanced sitemap generation supporting large-scale indexing,
+ * automatic 301/302 redirect handling, and atomic sitemap deployments.
+ *
+ * It can operate in two modes:
+ * 1. **Dynamic**: Sitemaps are generated on-the-fly and cached.
+ * 2. **Static**: Sitemaps are pre-built (e.g., during CI/CD) and served from disk or cloud storage.
+ *
+ * @example Dynamic Mode
+ * ```typescript
+ * const sitemap = OrbitSitemap.dynamic({
+ *   baseUrl: 'https://example.com',
+ *   providers: [new PostSitemapProvider()]
+ * });
+ * core.addOrbit(sitemap);
+ * ```
+ *
+ * @example Static Mode
+ * ```typescript
+ * const sitemap = OrbitSitemap.static({
+ *   baseUrl: 'https://example.com',
+ *   outDir: './public',
+ *   shadow: { enabled: true, mode: 'atomic' }
+ * });
+ * await sitemap.generate();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class OrbitSitemap implements GravitoOrbit {
+    private options;
+    private mode;
+    private constructor();
+    /**
+     * Create a dynamic sitemap configuration.
+     *
+     * @param options - The dynamic sitemap options.
+     * @returns An OrbitSitemap instance configured for dynamic generation.
+     */
+    static dynamic(options: DynamicSitemapOptions): OrbitSitemap;
+    /**
+     * Create a static sitemap configuration.
+     *
+     * @param options - The static sitemap options.
+     * @returns An OrbitSitemap instance configured for static generation.
+     */
+    static static(options: StaticSitemapOptions): OrbitSitemap;
+    /**
+     * Installs the sitemap module into PlanetCore.
+     *
+     * @param core - The PlanetCore instance.
      */
     install(core: PlanetCore): void;
+    /**
+     * Internal method to set up dynamic sitemap routes.
+     */
     private installDynamic;
     /**
-     * Generate the sitemap (static mode only).
+     * Generates the sitemap (static mode only).
      *
      * @returns A promise that resolves when generation is complete.
      * @throws {Error} If called in dynamic mode.
      */
     generate(): Promise<void>;
     /**
-     * Generate incremental sitemap updates (static mode only).
+     * Generates incremental sitemap updates (static mode only).
      *
      * @param since - Only include items modified since this date.
      * @returns A promise that resolves when incremental generation is complete.
@@ -1126,7 +2128,7 @@ declare class OrbitSitemap implements GravitoOrbit {
      */
     generateIncremental(since?: Date): Promise<void>;
     /**
-     * Generate sitemap asynchronously in the background (static mode only).
+     * Generates sitemap asynchronously in the background (static mode only).
      *
      * @param options - Options for the async generation job.
      * @returns A promise resolving to the job ID.
@@ -1144,7 +2146,7 @@ declare class OrbitSitemap implements GravitoOrbit {
         onError?: (error: Error) => void;
     }): Promise<string>;
     /**
-     * Install API endpoints for triggering and monitoring sitemap generation.
+     * Installs API endpoints for triggering and monitoring sitemap generation.
      *
      * @param core - The PlanetCore instance.
      * @param basePath - The base path for the API endpoints (default: '/admin/sitemap').
@@ -1193,9 +2195,12 @@ declare class RouteScanner implements SitemapProvider {
     private options;
     constructor(router: any, options?: RouteScannerOptions);
     /**
-     * Scan the router and return discovered entries.
+     * Scans the router and returns discovered static GET routes as sitemap entries.
      *
-     * @returns An array of sitemap entries.
+     * This method iterates through all registered routes in the Gravito router,
+     * applying inclusion/exclusion filters and defaulting metadata for matching routes.
+     *
+     * @returns An array of `SitemapEntry` objects.
      */
     getEntries(): SitemapEntry[];
     private extractRoutes;
@@ -1305,27 +2310,33 @@ declare class RedirectDetector {
     private cache;
     constructor(options: RedirectDetectorOptions);
     /**
-     * 偵測單一 URL 的轉址
+     * Detects redirects for a single URL using multiple strategies.
+     *
+     * @param url - The URL path to probe for redirects.
+     * @returns A promise resolving to a `RedirectRule` if a redirect is found, or null.
      */
     detect(url: string): Promise<RedirectRule | null>;
     /**
-     * 批次偵測轉址
+     * Batch detects redirects for multiple URLs with concurrency control.
+     *
+     * @param urls - An array of URL paths to probe.
+     * @returns A promise resolving to a Map of URLs to their respective `RedirectRule` or null.
      */
     detectBatch(urls: string[]): Promise<Map<string, RedirectRule | null>>;
     /**
-     * 從資料庫偵測
+     * Detects a redirect from the configured database table.
      */
     private detectFromDatabase;
     /**
-     * 從設定檔偵測
+     * Detects a redirect from a static JSON configuration file.
      */
     private detectFromConfig;
     /**
-     * 自動偵測（透過 HTTP 請求）
+     * Auto-detects a redirect by sending an HTTP HEAD request.
      */
     private detectAuto;
     /**
-     * 快取結果
+     * Caches the detection result for a URL.
      */
     private cacheResult;
 }
@@ -1374,23 +2385,26 @@ declare class RedirectHandler {
     private options;
     constructor(options: RedirectHandlerOptions);
     /**
-     * 處理 entries 中的轉址
+     * Processes a list of sitemap entries and handles redirects according to the configured strategy.
+     *
+     * @param entries - The original list of sitemap entries.
+     * @returns A promise resolving to the processed list of entries.
      */
     processEntries(entries: SitemapEntry[]): Promise<SitemapEntry[]>;
     /**
-     * 策略一：移除舊 URL，加入新 URL
+     * Strategy 1: Remove old URL and add the new destination URL.
      */
     private handleRemoveOldAddNew;
     /**
-     * 策略二：保留關聯，使用 canonical link
+     * Strategy 2: Keep the original URL but mark the destination as canonical.
      */
     private handleKeepRelation;
     /**
-     * 策略三：僅更新 URL
+     * Strategy 3: Silently update the URL to the destination.
      */
     private handleUpdateUrl;
     /**
-     * 策略四：雙重標記
+     * Strategy 4: Include both the original and destination URLs.
      */
     private handleDualMark;
 }
@@ -1418,10 +2432,39 @@ declare class MemoryRedirectManager implements RedirectManager {
     private rules;
     private maxRules;
     constructor(options?: MemoryRedirectManagerOptions);
+    /**
+     * Registers a single redirect rule in memory.
+     *
+     * @param redirect - The redirect rule to add.
+     */
     register(redirect: RedirectRule): Promise<void>;
+    /**
+     * Registers multiple redirect rules in memory.
+     *
+     * @param redirects - An array of redirect rules.
+     */
     registerBatch(redirects: RedirectRule[]): Promise<void>;
+    /**
+     * Retrieves a specific redirect rule by its source path from memory.
+     *
+     * @param from - The source path.
+     * @returns A promise resolving to the redirect rule, or null if not found.
+     */
     get(from: string): Promise<RedirectRule | null>;
+    /**
+     * Retrieves all registered redirect rules from memory.
+     *
+     * @returns A promise resolving to an array of all redirect rules.
+     */
     getAll(): Promise<RedirectRule[]>;
+    /**
+     * Resolves a URL to its final destination through the redirect table.
+     *
+     * @param url - The URL to resolve.
+     * @param followChains - Whether to recursively resolve chained redirects.
+     * @param maxChainLength - Maximum depth for chain resolution.
+     * @returns A promise resolving to the final destination URL.
+     */
     resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
 }
 /**
@@ -1455,10 +2498,39 @@ declare class RedisRedirectManager implements RedirectManager {
     constructor(options: RedisRedirectManagerOptions);
     private getKey;
     private getListKey;
+    /**
+     * Registers a single redirect rule in Redis.
+     *
+     * @param redirect - The redirect rule to add.
+     */
     register(redirect: RedirectRule): Promise<void>;
+    /**
+     * Registers multiple redirect rules in Redis.
+     *
+     * @param redirects - An array of redirect rules.
+     */
     registerBatch(redirects: RedirectRule[]): Promise<void>;
+    /**
+     * Retrieves a specific redirect rule by its source path from Redis.
+     *
+     * @param from - The source path.
+     * @returns A promise resolving to the redirect rule, or null if not found.
+     */
     get(from: string): Promise<RedirectRule | null>;
+    /**
+     * Retrieves all registered redirect rules from Redis.
+     *
+     * @returns A promise resolving to an array of all redirect rules.
+     */
     getAll(): Promise<RedirectRule[]>;
+    /**
+     * Resolves a URL to its final destination through the Redis redirect table.
+     *
+     * @param url - The URL to resolve.
+     * @param followChains - Whether to recursively resolve chained redirects.
+     * @param maxChainLength - Maximum depth for chain resolution.
+     * @returns A promise resolving to the final destination URL.
+     */
     resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
 }
 
@@ -1482,9 +2554,51 @@ declare class DiskSitemapStorage implements SitemapStorage {
     private outDir;
     private baseUrl;
     constructor(outDir: string, baseUrl: string);
+    /**
+     * Writes sitemap content to a file on the local disk.
+     *
+     * @param filename - The name of the file to write.
+     * @param content - The XML or JSON content.
+     */
     write(filename: string, content: string): Promise<void>;
+    /**
+     * 使用串流方式寫入 sitemap 檔案，可選擇性啟用 gzip 壓縮。
+     * 此方法可大幅降低大型 sitemap 的記憶體峰值。
+     *
+     * @param filename - 檔案名稱
+     * @param stream - XML 內容的 AsyncIterable
+     * @param options - 寫入選項（如壓縮、content type）
+     *
+     * @since 3.1.0
+     */
+    writeStream(filename: string, stream: AsyncIterable<string>, options?: WriteStreamOptions): Promise<void>;
+    /**
+     * Reads sitemap content from a file on the local disk.
+     *
+     * @param filename - The name of the file to read.
+     * @returns A promise resolving to the file content as a string, or null if not found.
+     */
     read(filename: string): Promise<string | null>;
+    /**
+     * Returns a readable stream for a sitemap file on the local disk.
+     *
+     * @param filename - The name of the file to stream.
+     * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+     */
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
+    /**
+     * Checks if a sitemap file exists on the local disk.
+     *
+     * @param filename - The name of the file to check.
+     * @returns A promise resolving to true if the file exists, false otherwise.
+     */
     exists(filename: string): Promise<boolean>;
+    /**
+     * Returns the full public URL for a sitemap file.
+     *
+     * @param filename - The name of the sitemap file.
+     * @returns The public URL as a string.
+     */
     getUrl(filename: string): string;
 }
 
@@ -1542,26 +2656,125 @@ declare class GCPSitemapStorage implements SitemapStorage {
     constructor(options: GCPSitemapStorageOptions);
     private getStorageClient;
     private getKey;
+    /**
+     * Writes sitemap content to a Google Cloud Storage object.
+     *
+     * @param filename - The name of the file to write.
+     * @param content - The XML or JSON content.
+     */
     write(filename: string, content: string): Promise<void>;
+    /**
+     * 使用串流方式寫入 sitemap 至 GCP Cloud Storage，可選擇性啟用 gzip 壓縮。
+     *
+     * @param filename - 檔案名稱
+     * @param stream - XML 內容的 AsyncIterable
+     * @param options - 寫入選項（如壓縮、content type）
+     *
+     * @since 3.1.0
+     */
+    writeStream(filename: string, stream: AsyncIterable<string>, options?: WriteStreamOptions): Promise<void>;
+    /**
+     * Reads sitemap content from a Google Cloud Storage object.
+     *
+     * @param filename - The name of the file to read.
+     * @returns A promise resolving to the file content as a string, or null if not found.
+     */
     read(filename: string): Promise<string | null>;
+    /**
+     * Returns a readable stream for a Google Cloud Storage object.
+     *
+     * @param filename - The name of the file to stream.
+     * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+     */
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
+    /**
+     * Checks if a Google Cloud Storage object exists.
+     *
+     * @param filename - The name of the file to check.
+     * @returns A promise resolving to true if the file exists, false otherwise.
+     */
     exists(filename: string): Promise<boolean>;
+    /**
+     * Returns the full public URL for a Google Cloud Storage object.
+     *
+     * @param filename - The name of the sitemap file.
+     * @returns The public URL as a string.
+     */
     getUrl(filename: string): string;
+    /**
+     * Writes content to a shadow (staged) location in Google Cloud Storage.
+     *
+     * @param filename - The name of the file to write.
+     * @param content - The XML or JSON content.
+     * @param shadowId - Optional unique session identifier.
+     */
     writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
+    /**
+     * Commits all staged shadow objects in a session to production in Google Cloud Storage.
+     *
+     * @param shadowId - The identifier of the session to commit.
+     */
     commitShadow(shadowId: string): Promise<void>;
+    /**
+     * Lists all archived versions of a specific sitemap in Google Cloud Storage.
+     *
+     * @param filename - The sitemap filename.
+     * @returns A promise resolving to an array of version identifiers.
+     */
     listVersions(filename: string): Promise<string[]>;
+    /**
+     * Reverts a sitemap to a previously archived version in Google Cloud Storage.
+     *
+     * @param filename - The sitemap filename.
+     * @param version - The version identifier to switch to.
+     */
     switchVersion(filename: string, version: string): Promise<void>;
 }
 
 /**
- * 記憶體進度儲存實作
- * 適用於單一進程或開發環境
+ * MemoryProgressStorage is a non-persistent, in-memory implementation of the `SitemapProgressStorage`.
+ *
+ * It is suitable for single-process applications or development environments where
+ * persistence of job progress across application restarts is not required.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class MemoryProgressStorage implements SitemapProgressStorage {
     private storage;
+    /**
+     * Retrieves the progress of a specific generation job from memory.
+     *
+     * @param jobId - Unique identifier for the job.
+     * @returns A promise resolving to the `SitemapProgress` object, or null if not found.
+     */
     get(jobId: string): Promise<SitemapProgress | null>;
+    /**
+     * Initializes or overwrites a progress record in memory.
+     *
+     * @param jobId - Unique identifier for the job.
+     * @param progress - The initial or current state of the job progress.
+     */
     set(jobId: string, progress: SitemapProgress): Promise<void>;
+    /**
+     * Updates specific fields of an existing progress record in memory.
+     *
+     * @param jobId - Unique identifier for the job.
+     * @param updates - Object containing the fields to update.
+     */
     update(jobId: string, updates: Partial<SitemapProgress>): Promise<void>;
+    /**
+     * Deletes a progress record from memory.
+     *
+     * @param jobId - Unique identifier for the job to remove.
+     */
     delete(jobId: string): Promise<void>;
+    /**
+     * Lists the most recent sitemap generation jobs from memory.
+     *
+     * @param limit - Maximum number of records to return.
+     * @returns A promise resolving to an array of `SitemapProgress` objects, sorted by start time.
+     */
     list(limit?: number): Promise<SitemapProgress[]>;
 }
 
@@ -1584,9 +2797,51 @@ declare class MemorySitemapStorage implements SitemapStorage {
     private baseUrl;
     private files;
     constructor(baseUrl: string);
+    /**
+     * Writes sitemap content to memory.
+     *
+     * @param filename - The name of the file to store.
+     * @param content - The XML or JSON content.
+     */
     write(filename: string, content: string): Promise<void>;
+    /**
+     * 使用串流方式寫入 sitemap 至記憶體，可選擇性啟用 gzip 壓縮。
+     * 記憶體儲存會收集串流為完整字串。
+     *
+     * @param filename - 檔案名稱
+     * @param stream - XML 內容的 AsyncIterable
+     * @param options - 寫入選項（如壓縮）
+     *
+     * @since 3.1.0
+     */
+    writeStream(filename: string, stream: AsyncIterable<string>, options?: WriteStreamOptions): Promise<void>;
+    /**
+     * Reads sitemap content from memory.
+     *
+     * @param filename - The name of the file to read.
+     * @returns A promise resolving to the file content as a string, or null if not found.
+     */
     read(filename: string): Promise<string | null>;
+    /**
+     * Returns a readable stream for a sitemap file in memory.
+     *
+     * @param filename - The name of the file to stream.
+     * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+     */
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
+    /**
+     * Checks if a sitemap file exists in memory.
+     *
+     * @param filename - The name of the file to check.
+     * @returns A promise resolving to true if the file exists, false otherwise.
+     */
     exists(filename: string): Promise<boolean>;
+    /**
+     * Returns the full public URL for a sitemap file.
+     *
+     * @param filename - The name of the sitemap file.
+     * @returns The public URL as a string.
+     */
     getUrl(filename: string): string;
 }
 
@@ -1620,10 +2875,39 @@ declare class RedisProgressStorage implements SitemapProgressStorage {
     constructor(options: RedisProgressStorageOptions);
     private getKey;
     private getListKey;
+    /**
+     * Retrieves the progress of a specific generation job from Redis.
+     *
+     * @param jobId - Unique identifier for the job.
+     * @returns A promise resolving to the `SitemapProgress` object, or null if not found.
+     */
     get(jobId: string): Promise<SitemapProgress | null>;
+    /**
+     * Initializes or overwrites a progress record in Redis.
+     *
+     * @param jobId - Unique identifier for the job.
+     * @param progress - The initial or current state of the job progress.
+     */
     set(jobId: string, progress: SitemapProgress): Promise<void>;
+    /**
+     * Updates specific fields of an existing progress record in Redis.
+     *
+     * @param jobId - Unique identifier for the job.
+     * @param updates - Object containing the fields to update.
+     */
     update(jobId: string, updates: Partial<SitemapProgress>): Promise<void>;
+    /**
+     * Deletes a progress record from Redis.
+     *
+     * @param jobId - Unique identifier for the job to remove.
+     */
     delete(jobId: string): Promise<void>;
+    /**
+     * Lists the most recent sitemap generation jobs from Redis.
+     *
+     * @param limit - Maximum number of records to return.
+     * @returns A promise resolving to an array of `SitemapProgress` objects, sorted by start time.
+     */
     list(limit?: number): Promise<SitemapProgress[]>;
 }
 
@@ -1684,14 +2968,156 @@ declare class S3SitemapStorage implements SitemapStorage {
     constructor(options: S3SitemapStorageOptions);
     private getS3Client;
     private getKey;
+    /**
+     * Writes sitemap content to an S3 object.
+     *
+     * @param filename - The name of the file to write.
+     * @param content - The XML or JSON content.
+     */
     write(filename: string, content: string): Promise<void>;
+    /**
+     * 使用串流方式寫入 sitemap 至 S3，可選擇性啟用 gzip 壓縮。
+     * S3 需要知道 Content-Length，因此會先收集串流為 Buffer。
+     *
+     * @param filename - 檔案名稱
+     * @param stream - XML 內容的 AsyncIterable
+     * @param options - 寫入選項（如壓縮、content type）
+     *
+     * @since 3.1.0
+     */
+    writeStream(filename: string, stream: AsyncIterable<string>, options?: WriteStreamOptions): Promise<void>;
+    /**
+     * Reads sitemap content from an S3 object.
+     *
+     * @param filename - The name of the file to read.
+     * @returns A promise resolving to the file content as a string, or null if not found.
+     */
     read(filename: string): Promise<string | null>;
+    /**
+     * Returns a readable stream for an S3 object.
+     *
+     * @param filename - The name of the file to stream.
+     * @returns A promise resolving to an async iterable of file chunks, or null if not found.
+     */
+    readStream(filename: string): Promise<AsyncIterable<string> | null>;
+    /**
+     * Checks if an S3 object exists.
+     *
+     * @param filename - The name of the file to check.
+     * @returns A promise resolving to true if the file exists, false otherwise.
+     */
     exists(filename: string): Promise<boolean>;
+    /**
+     * Returns the full public URL for an S3 object.
+     *
+     * @param filename - The name of the sitemap file.
+     * @returns The public URL as a string.
+     */
     getUrl(filename: string): string;
+    /**
+     * Writes content to a shadow (staged) location in S3.
+     *
+     * @param filename - The name of the file to write.
+     * @param content - The XML or JSON content.
+     * @param shadowId - Optional unique session identifier.
+     */
     writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
+    /**
+     * Commits all staged shadow objects in a session to production.
+     *
+     * @param shadowId - The identifier of the session to commit.
+     */
     commitShadow(shadowId: string): Promise<void>;
+    /**
+     * Lists all archived versions of a specific sitemap in S3.
+     *
+     * @param filename - The sitemap filename.
+     * @returns A promise resolving to an array of version identifiers.
+     */
     listVersions(filename: string): Promise<string[]>;
+    /**
+     * Reverts a sitemap to a previously archived version in S3.
+     *
+     * @param filename - The sitemap filename.
+     * @param version - The version identifier to switch to.
+     */
     switchVersion(filename: string, version: string): Promise<void>;
 }
 
-export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, generateI18nEntries, routeScanner };
+/**
+ * @gravito/constellation - Compression utilities
+ * @module utils/Compression
+ * @since 3.1.0
+ */
+
+/**
+ * Compression configuration.
+ */
+interface CompressionConfig {
+    /** Compression format. @default 'gzip' */
+    format?: 'gzip' | undefined;
+    /** Compression level (1-9). @default 6 */
+    level?: number | undefined;
+}
+/**
+ * 將 AsyncIterable<string> 壓縮為 Buffer。
+ * 適用於需要完整壓縮結果的場景（如 S3 Upload）。
+ *
+ * @param source - 輸入的字串串流
+ * @param config - 壓縮設定
+ * @returns 壓縮後的 Buffer
+ *
+ * @example
+ * ```typescript
+ * const source = (async function*() {
+ *   yield '<?xml version="1.0"?>'
+ *   yield '<urlset>...</urlset>'
+ * })()
+ * const compressed = await compressToBuffer(source)
+ * ```
+ */
+declare function compressToBuffer(source: AsyncIterable<string>, config?: CompressionConfig): Promise<Buffer>;
+/**
+ * 回傳壓縮串流 Transform。
+ * 適用於可直接 pipe 的場景（如 Disk write）。
+ *
+ * @param config - 壓縮設定
+ * @returns Transform stream
+ *
+ * @example
+ * ```typescript
+ * const readable = Readable.from(source)
+ * const gzip = createCompressionStream({ level: 9 })
+ * const writeStream = createWriteStream('output.xml.gz')
+ * await pipeline(readable, gzip, writeStream)
+ * ```
+ */
+declare function createCompressionStream(config?: CompressionConfig): Transform;
+/**
+ * 將檔名轉換為 gzip 格式（加上 .gz 副檔名）。
+ *
+ * @param filename - 原始檔名
+ * @returns 帶有 .gz 副檔名的檔名
+ *
+ * @example
+ * ```typescript
+ * toGzipFilename('sitemap.xml') // 'sitemap.xml.gz'
+ * toGzipFilename('sitemap.xml.gz') // 'sitemap.xml.gz' (不重複添加)
+ * ```
+ */
+declare function toGzipFilename(filename: string): string;
+/**
+ * 移除檔名的 .gz 副檔名。
+ *
+ * @param filename - gzip 檔名
+ * @returns 移除 .gz 後的檔名
+ *
+ * @example
+ * ```typescript
+ * fromGzipFilename('sitemap.xml.gz') // 'sitemap.xml'
+ * fromGzipFilename('sitemap.xml') // 'sitemap.xml'
+ * ```
+ */
+declare function fromGzipFilename(filename: string): string;
+
+export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, type CompressionConfig, type CompressionOptions, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryLock, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, type RedisClient, RedisLock, type RedisLockOptions, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type ShardInfo, type ShardManifest, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, type WriteStreamOptions, compressToBuffer, createCompressionStream, fromGzipFilename, generateI18nEntries, routeScanner, toGzipFilename };