@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/content/ArtifactStore.ts

@@ -1,782 +0,0 @@
-import type Keyv from 'keyv';
-import { ContentStore } from './ContentStore';
-import type {
-  StoreEntry,
-  StoredEntry,
-  ContentMetadata,
-  EditResult,
-  ReadResult,
-  ReadAllResult,
-  SearchMatch,
-} from './types';
-
-/**
- * Minimal logger surface. Callers inject any winston/pino/console-like
- * logger that honors the four level methods; defaults to a no-op so the
- * library runs without a configured logger.
- */
-export interface Logger {
-  debug(...args: unknown[]): void;
-  info(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-}
-
-const noopLogger: Logger = {
-  debug: () => {},
-  info: () => {},
-  warn: () => {},
-  error: () => {},
-};
-
-/**
- * Callback interface for S3 operations.
- * Injected at construction so ArtifactStore stays host-agnostic — the
- * consumer wires this to its own S3 strategy / presigner.
- */
-export interface S3Strategy {
-  /** Upload a buffer to S3, return the stored filepath (signed URL or key). */
-  saveBuffer(params: {
-    userId: string;
-    buffer: Buffer;
-    fileName: string;
-    basePath: string;
-  }): Promise<string>;
-
-  /** Download file content from S3 as a readable stream. */
-  getFileStream(filePath: string): Promise<NodeJS.ReadableStream>;
-
-  /** Delete a file from S3. Requires userId for ownership validation. */
-  deleteFile(userId: string, filePath: string): Promise<void>;
-}
-
-/**
- * Callback interface for MongoDB File model operations.
- * Injected to keep ArtifactStore decoupled from Mongoose models.
- */
-export interface FileModel {
-  /** Create or upsert a File document. */
-  createFile(
-    data: Record<string, unknown>,
-    disableTTL: boolean
-  ): Promise<Record<string, unknown>>;
-
-  /** Find a single File by filter. */
-  findFile(
-    filter: Record<string, unknown>
-  ): Promise<Record<string, unknown> | null>;
-
-  /** Find multiple Files by filter. */
-  findFiles(
-    filter: Record<string, unknown>
-  ): Promise<Record<string, unknown>[]>;
-
-  /** Update a File document (must include file_id). */
-  updateFile(
-    data: Record<string, unknown>
-  ): Promise<Record<string, unknown> | null>;
-
-  /** Delete a File by file_id. */
-  deleteFile(fileId: string): Promise<Record<string, unknown> | null>;
-
-  /**
-   * Get the file_ids linked to a conversation via the Conversation.files array.
-   * Returns an empty array if the conversation is not found or has no files.
-   * This is the primary source of truth for "which files belong to this conversation".
-   */
-  getConversationFileIds(conversationId: string): Promise<string[]>;
-
-  /**
-   * Link file_ids to a conversation via $addToSet on Conversation.files.
-   * Idempotent — calling with already-linked file_ids is a no-op.
-   * Used after creating a File record to ensure it appears in "Files in Context".
-   */
-  addFilesToConversation(
-    conversationId: string,
-    fileIds: string[]
-  ): Promise<void>;
-}
-
-/** S3 base path for all artifact files. */
-const ARTIFACTS_BASE_PATH = 'artifacts';
-
-/**
- * Sanitize a filename for safe S3 key usage.
- * Replaces non-alphanumeric characters (except . _ - /) with underscores.
- */
-export function sanitizeName(name: string): string {
-  return name.replace(/[^a-zA-Z0-9._\-/]/g, '_');
-}
-
-/**
- * Constructs the canonical S3 file name for an artifact.
- * Format: `{contentId}__{sanitizedName}` — contentId prefix ensures uniqueness.
- */
-function buildS3FileName(contentId: string, name: string): string {
-  return `${contentId}__${sanitizeName(name)}`;
-}
-
-/**
- * Constructs the S3 base path scoped to a conversation.
- * Pattern: `artifacts/{conversationId}`
- * The S3 strategy prepends userId internally via getS3Key().
- */
-function buildS3BasePath(conversationId: string): string {
-  return `${ARTIFACTS_BASE_PATH}/${conversationId}`;
-}
-
-/**
- * File-backed artifact store extending ContentStore with S3 persistence.
- *
- * Every write immediately persists to Redis (fast cache) AND S3 (permanent store).
- * S3 writes are fire-and-forget async — the agent gets an instant response from Redis.
- * On Redis cache miss, content is transparently restored from S3 via MongoDB lookup.
- *
- * Key structure (consistent across all layers):
- * - Redis:   `CONTENT_STORE::{conversationId}::{contentId}`
- * - S3:      `artifacts/{conversationId}/{userId}/{contentId}__{name}`
- * - MongoDB: `file_id: "artifact-{contentId}"`, `metadata.contentId: "{contentId}"`
- *
- * @example
- * ```ts
- * import Keyv from 'keyv';
- * import { ArtifactStore, CONTENT_TTL_MS } from '@illuma-ai/agents/content';
- *
- * const cache = new Keyv({ namespace: `content-store::${conversationId}`, ttl: CONTENT_TTL_MS });
- * const store = new ArtifactStore(cache, conversationId, userId, s3Strategy, fileModel, logger);
- * const id = await store.store({ name: 'App.tsx', type: 'text/x-typescript', content: code, source: 'agent' });
- * // Content is in the cache immediately; S3 + the injected FileModel persist in background.
- * const result = await store.readLines(id, 1, 50);
- * ```
- */
-export class ArtifactStore extends ContentStore {
-  protected logger: Logger;
-
-  constructor(
-    cache: Keyv,
-    protected conversationId: string,
-    protected userId: string,
-    protected s3: S3Strategy,
-    protected fileModel: FileModel,
-    logger: Logger = noopLogger
-  ) {
-    super(cache);
-    this.logger = logger;
-  }
-
-  /** File ID prefix for MongoDB file_id. Override in subclasses. */
-  protected getFileIdPrefix(): string {
-    return 'artifact-';
-  }
-
-  /** Context label stored on MongoDB File records. Override in subclasses. */
-  protected getContextLabel(): string {
-    return 'artifact';
-  }
-
-  /** S3 base path prefix. Override in subclasses. */
-  protected getS3BasePath(): string {
-    return buildS3BasePath(this.conversationId);
-  }
-
-  /** Build S3 file name. Override in subclasses. */
-  protected getS3FileName(contentId: string, name: string): string {
-    return buildS3FileName(contentId, name);
-  }
-
-  /** Build the canonical file_id for a content entry. */
-  protected buildFileId(contentId: string): string {
-    return `${this.getFileIdPrefix()}${contentId}`;
-  }
-
-  /**
-   * Store new content in Redis and persist to S3 + MongoDB in background.
-   * Returns immediately after Redis write — agent doesn't wait for S3.
-   *
-   * @param entry - The content to store.
-   * @returns The generated content ID.
-   */
-  async store(entry: StoreEntry): Promise<string> {
-    // 1. Fast path: store in Redis via parent (agent gets instant response)
-    const contentId = await super.store(entry);
-
-    // 2. Update Redis metadata with ownership info for S3 restore path
-    const stored = await this.getStored(contentId);
-    if (stored) {
-      stored.metadata.userId = this.userId;
-      stored.metadata.conversationId = this.conversationId;
-      stored.metadata.fileId = this.buildFileId(contentId);
-      await this.cache.set(contentId, JSON.stringify(stored));
-
-      // Update index with enriched metadata
-      const index = await this.getIndex();
-      if (index[contentId]) {
-        index[contentId] = stored.metadata;
-        await this.cache.set(this.indexKey, JSON.stringify(index));
-      }
-    }
-
-    // 3. Background: persist to S3 + MongoDB (fire-and-forget)
-    this.persistToS3(contentId, entry).catch((err) => {
-      this.logger.warn(
-        `[ArtifactStore] S3 persist failed for ${contentId}:`,
-        (err as Error).message
-      );
-    });
-
-    return contentId;
-  }
-
-  /**
-   * Overwrite content for an existing entry. Updates Redis + syncs to S3.
-   *
-   * @param contentId - The content entry ID.
-   * @param content - New content to write.
-   * @throws If content ID is not found in Redis or S3.
-   */
-  async write(contentId: string, content: string): Promise<void> {
-    // Ensure content is loaded into Redis (may need S3 fallback)
-    await this.ensureLoaded(contentId);
-
-    // Update Redis via parent
-    await super.write(contentId, content);
-
-    // Background: sync updated content to S3
-    this.syncToS3(contentId).catch((err) => {
-      this.logger.warn(
-        `[ArtifactStore] S3 sync failed for write on ${contentId}:`,
-        (err as Error).message
-      );
-    });
-  }
-
-  /**
-   * Surgical string replacement. Updates Redis + syncs to S3.
-   *
-   * @param contentId - The content entry ID.
-   * @param oldStr - Exact string to find.
-   * @param newStr - Replacement string.
-   * @returns Edit result with diff and affected line info.
-   */
-  async strReplace(
-    contentId: string,
-    oldStr: string,
-    newStr: string
-  ): Promise<EditResult> {
-    // Ensure content is loaded into Redis (may need S3 fallback)
-    await this.ensureLoaded(contentId);
-
-    // Edit in Redis via parent
-    const result = await super.strReplace(contentId, oldStr, newStr);
-
-    if (result.success) {
-      // Background: sync updated content to S3
-      this.syncToS3(contentId).catch((err) => {
-        this.logger.warn(
-          `[ArtifactStore] S3 sync failed for edit on ${contentId}:`,
-          (err as Error).message
-        );
-      });
-    }
-
-    return result;
-  }
-
-  /**
-   * Read lines with S3 fallback. If Redis has expired, loads from S3 first.
-   *
-   * @param contentId - The content entry ID.
-   * @param startLine - First line to read (1-based).
-   * @param endLine - Last line to read (inclusive).
-   * @returns Read result or null if not found in any layer.
-   */
-  async readLines(
-    contentId: string,
-    startLine?: number,
-    endLine?: number
-  ): Promise<ReadResult | null> {
-    // Try Redis first via parent
-    let result = await super.readLines(contentId, startLine, endLine);
-    if (result) {
-      return result;
-    }
-
-    // Redis miss — try S3 fallback
-    const restored = await this.restoreFromS3(contentId);
-    if (!restored) {
-      return null;
-    }
-
-    // Retry read from Redis (now populated)
-    result = await super.readLines(contentId, startLine, endLine);
-    return result;
-  }
-
-  /**
-   * Read full content with S3 fallback. If Redis has expired, loads from S3 first.
-   * No line cap — returns raw content for frontend display (e.g., CodeViz).
-   *
-   * @param contentId - The content entry ID.
-   * @returns Raw content with total line/char counts, or null if not found in any layer.
-   */
-  async readAll(contentId: string): Promise<ReadAllResult | null> {
-    // Try Redis first via parent
-    let result = await super.readAll(contentId);
-    if (result) {
-      return result;
-    }
-
-    // Redis miss — try S3 fallback
-    const restored = await this.restoreFromS3(contentId);
-    if (!restored) {
-      return null;
-    }
-
-    // Retry read from Redis (now populated)
-    result = await super.readAll(contentId);
-    return result;
-  }
-
-  /**
-   * Search with S3 fallback. If Redis has expired, loads from S3 first.
-   *
-   * @param contentId - The content entry ID.
-   * @param pattern - Text or regex pattern to match.
-   * @param maxResults - Maximum matches to return.
-   * @returns Array of matches or null if not found.
-   */
-  async search(
-    contentId: string,
-    pattern: string,
-    maxResults?: number
-  ): Promise<SearchMatch[] | null> {
-    // Try Redis first via parent
-    let result = await super.search(contentId, pattern, maxResults);
-    if (result) {
-      return result;
-    }
-
-    // Redis miss — try S3 fallback
-    const restored = await this.restoreFromS3(contentId);
-    if (!restored) {
-      return null;
-    }
-
-    result = await super.search(contentId, pattern, maxResults);
-    return result;
-  }
-
-  /**
-   * Get metadata with S3 fallback.
-   *
-   * @param contentId - The content entry ID.
-   * @returns Metadata or null if not found in any layer.
-   */
-  async info(contentId: string): Promise<ContentMetadata | null> {
-    // Try Redis first via parent
-    let result = await super.info(contentId);
-    if (result) {
-      return result;
-    }
-
-    // Redis miss — try S3 fallback
-    const restored = await this.restoreFromS3(contentId);
-    if (!restored) {
-      return null;
-    }
-
-    result = await super.info(contentId);
-    return result;
-  }
-
-  /**
-   * Delete an artifact from all layers: Redis + S3 + MongoDB.
-   *
-   * @param contentId - The content entry ID.
-   */
-  async deleteFile(contentId: string): Promise<void> {
-    // 1. Delete from Redis
-    await super.delete(contentId);
-
-    // 2. Delete from MongoDB + S3 (background, best-effort)
-    const fileId = this.buildFileId(contentId);
-    try {
-      const fileRecord = await this.fileModel.findFile({
-        file_id: fileId,
-        user: this.userId,
-      });
-
-      if (fileRecord && fileRecord.filepath) {
-        // Delete from S3
-        try {
-          await this.s3.deleteFile(this.userId, fileRecord.filepath as string);
-        } catch (err) {
-          this.logger.warn(
-            `[ArtifactStore] S3 delete failed for ${contentId}:`,
-            (err as Error).message
-          );
-        }
-
-        // Delete from MongoDB
-        await this.fileModel.deleteFile(fileId);
-      }
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] MongoDB cleanup failed for ${contentId}:`,
-        (err as Error).message
-      );
-    }
-  }
-
-  /**
-   * List all files in this conversation. Merges Redis index with MongoDB File
-   * records found via `Conversation.files` (the single source of truth).
-   *
-   * Query flow:
-   * 1. Redis index — fast cache of recently-accessed content entries (in-memory, no DB hit)
-   * 2. Conversation.files — canonical file_id list via `getConversationFileIds()`
-   *    SCALE: Single indexed `findOne` on `{ conversationId }` — O(1)
-   * 3. Backward compat fallback — `File.find({ conversationId, user })` for pre-migration
-   *    data not yet in `Conversation.files`. Uses index `{ user, conversationId, updatedAt }`.
-   *    Can be removed once all File records are migrated.
-   * 4. Batch fetch — `File.find({ file_id: { $in: mergedIds }, user })` to hydrate full
-   *    File documents. Uses index `{ file_id, user }`.
-   *
-   * Deduplication: Redis entries win — if a contentId is already in Redis, the MongoDB
-   * record is skipped. Non-artifact files are keyed by `file:{file_id}` to avoid dupes.
-   *
-   * @returns Array of metadata for all files in this conversation.
-   */
-  async listFiles(): Promise<ContentMetadata[]> {
-    // 1. Redis entries — fast cache of content store entries
-    const redisEntries = await super.list();
-    const seen = new Set<string>(redisEntries.map((e) => e.id));
-
-    // 2. Conversation.files — the primary source of truth
-    // SCALE: Single indexed findOne on { conversationId } — O(1)
-    let convoFileIds: string[] = [];
-    try {
-      convoFileIds = await this.fileModel.getConversationFileIds(
-        this.conversationId
-      );
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] getConversationFileIds failed for ${this.conversationId}:`,
-        (err as Error).message
-      );
-    }
-    const convoFileIdSet = new Set(convoFileIds);
-
-    // 3. Backward compat fallback — files with File.conversationId set directly
-    // (pre-migration artifacts/code executor files not yet in Conversation.files).
-    // SCALE: Uses compound index { user: 1, conversationId: 1, updatedAt: -1 }
-    let fallbackFileIds: string[] = [];
-    try {
-      const directFiles = await this.fileModel.findFiles({
-        conversationId: this.conversationId,
-        user: this.userId,
-      });
-      fallbackFileIds = directFiles
-        .map((f) => f.file_id as string)
-        .filter((fid) => fid && !convoFileIdSet.has(fid));
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] Fallback conversationId query failed for ${this.conversationId}:`,
-        (err as Error).message
-      );
-    }
-
-    // 4. Merge into single set and batch fetch File records
-    // SCALE: Uses compound index { file_id: 1, user: 1 }
-    const allFileIds = [...new Set([...convoFileIds, ...fallbackFileIds])];
-    if (allFileIds.length === 0) {
-      return redisEntries;
-    }
-
-    try {
-      const files = await this.fileModel.findFiles({
-        file_id: { $in: allFileIds } as unknown,
-        user: this.userId,
-      });
-
-      for (const file of files) {
-        const existingContentId = file.metadata
-          ? ((file.metadata as Record<string, unknown>).contentId as string)
-          : undefined;
-
-        // Artifact file (has contentId) — add as content entry if not already in Redis
-        if (existingContentId) {
-          if (seen.has(existingContentId)) {
-            continue;
-          }
-          seen.add(existingContentId);
-          redisEntries.push({
-            id: existingContentId,
-            name: (file.filename as string) || 'unknown',
-            type: (file.type as string) || 'text/plain',
-            source:
-              ((file.metadata as Record<string, unknown>)
-                .artifactSource as string) || 'unknown',
-            totalLines: 0,
-            totalChars: (file.bytes as number) || 0,
-            createdAt: file.createdAt
-              ? new Date(file.createdAt as string).getTime()
-              : Date.now(),
-            fileId: file.file_id as string,
-            userId: this.userId,
-            conversationId: this.conversationId,
-          });
-          continue;
-        }
-
-        // Non-artifact file (attachment, code executor output, etc.)
-        const fileId = file.file_id as string;
-        if (seen.has(`file:${fileId}`)) {
-          continue;
-        }
-        seen.add(`file:${fileId}`);
-
-        // Determine source label from file context/metadata
-        const context = file.context as string | undefined;
-        const hasFileIdentifier = !!(file.metadata as Record<string, unknown>)
-          .fileIdentifier;
-        let source = 'attachment';
-        if (context === 'artifact') {
-          source = 'agent';
-        } else if (hasFileIdentifier) {
-          source = 'code_executor';
-        }
-
-        const hasText = !!(file.text && (file.text as string).length > 0);
-
-        redisEntries.push({
-          id: `file:${fileId}`,
-          name: (file.filename as string) || 'unknown',
-          type: (file.type as string) || 'text/plain',
-          source,
-          totalLines: 0,
-          totalChars: (file.bytes as number) || 0,
-          createdAt: file.createdAt
-            ? new Date(file.createdAt as string).getTime()
-            : Date.now(),
-          fileId,
-          userId: this.userId,
-          conversationId: this.conversationId,
-          needsIngestion: hasText,
-        });
-      }
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] File batch fetch failed for ${this.conversationId}:`,
-        (err as Error).message
-      );
-    }
-
-    return redisEntries;
-  }
-
-  /**
-   * Persist a new content entry to S3 and create a MongoDB File record.
-   * Called in background after Redis store — agent doesn't wait for this.
-   *
-   * @param contentId - The content entry ID.
-   * @param entry - The original store entry with content and metadata.
-   */
-  protected async persistToS3(
-    contentId: string,
-    entry: StoreEntry
-  ): Promise<void> {
-    const buffer = Buffer.from(entry.content, 'utf-8');
-    const fileName = this.getS3FileName(contentId, entry.name);
-    const basePath = this.getS3BasePath();
-
-    const filepath = await this.s3.saveBuffer({
-      userId: this.userId,
-      buffer,
-      fileName,
-      basePath,
-    });
-
-    const fileId = this.buildFileId(contentId);
-    await this.fileModel.createFile(
-      {
-        user: this.userId,
-        file_id: fileId,
-        conversationId: this.conversationId,
-        filename: entry.name,
-        filepath,
-        type: entry.type || 'text/plain',
-        bytes: buffer.length,
-        source: 's3',
-        context: this.getContextLabel(),
-        object: 'file',
-        usage: 0,
-        metadata: {
-          contentId,
-          artifactSource: entry.source,
-        },
-      },
-      /* disableTTL */ true
-    );
-
-    // Link artifact to Conversation.files — the single source of truth for
-    // which files belong to a conversation. Fire-and-forget: non-critical
-    // because the fallback query in listFiles() will still find via File.conversationId.
-    try {
-      await this.fileModel.addFilesToConversation(this.conversationId, [
-        fileId,
-      ]);
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] addFilesToConversation failed for ${fileId}:`,
-        (err as Error).message
-      );
-    }
-
-    // Update Redis metadata with the S3-backed fileId
-    const stored = await this.getStored(contentId);
-    if (stored) {
-      stored.metadata.fileId = fileId;
-      await this.cache.set(contentId, JSON.stringify(stored));
-
-      // Update index
-      const index = await this.getIndex();
-      if (index[contentId]) {
-        index[contentId] = stored.metadata;
-        await this.cache.set(this.indexKey, JSON.stringify(index));
-      }
-    }
-  }
-
-  /**
-   * Sync updated Redis content to S3 (overwrite same key).
-   * Called in background after write/edit operations.
-   *
-   * @param contentId - The content entry ID to sync.
-   */
-  protected async syncToS3(contentId: string): Promise<void> {
-    const stored = await this.getStored(contentId);
-    if (!stored) {
-      return;
-    }
-
-    const buffer = Buffer.from(stored.content, 'utf-8');
-    const fileName = this.getS3FileName(contentId, stored.metadata.name);
-    const basePath = this.getS3BasePath();
-
-    const filepath = await this.s3.saveBuffer({
-      userId: this.userId,
-      buffer,
-      fileName,
-      basePath,
-    });
-
-    // Update MongoDB File record with new bytes and filepath
-    const fileId = this.buildFileId(contentId);
-    try {
-      await this.fileModel.updateFile({
-        file_id: fileId,
-        bytes: buffer.length,
-        filepath,
-      });
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] MongoDB update failed for ${contentId}:`,
-        (err as Error).message
-      );
-    }
-  }
-
-  /**
-   * Restore content from S3 into Redis on cache miss.
-   * Looks up the MongoDB File record to find the S3 path, downloads content,
-   * and re-populates the Redis cache with the same key structure.
-   *
-   * @param contentId - The content entry ID to restore.
-   * @returns The restored StoredEntry, or null if not found in S3/MongoDB.
-   */
-  protected async restoreFromS3(
-    contentId: string
-  ): Promise<StoredEntry | null> {
-    const fileId = this.buildFileId(contentId);
-
-    try {
-      // Find the MongoDB record for this artifact
-      const fileRecord = await this.fileModel.findFile({
-        file_id: fileId,
-        user: this.userId,
-      });
-
-      if (!fileRecord || !fileRecord.filepath) {
-        return null;
-      }
-
-      // Download content from S3
-      const stream = await this.s3.getFileStream(fileRecord.filepath as string);
-      const chunks: Buffer[] = [];
-      for await (const chunk of stream) {
-        chunks.push(
-          Buffer.isBuffer(chunk)
-            ? chunk
-            : Buffer.from(chunk as unknown as Uint8Array)
-        );
-      }
-      const content = Buffer.concat(chunks).toString('utf-8');
-
-      // Reconstruct metadata from MongoDB record + content
-      const metadata: ContentMetadata = {
-        id: contentId,
-        name: (fileRecord.filename as string) || 'unknown',
-        type: (fileRecord.type as string) || 'text/plain',
-        source:
-          ((fileRecord.metadata as Record<string, unknown>)
-            .artifactSource as string) || 'unknown',
-        totalLines: content.split('\n').length,
-        totalChars: content.length,
-        createdAt: fileRecord.createdAt
-          ? new Date(fileRecord.createdAt as string).getTime()
-          : Date.now(),
-        fileId,
-        userId: this.userId,
-        conversationId: this.conversationId,
-      };
-
-      // Re-populate Redis cache
-      const stored: StoredEntry = { content, metadata };
-      await this.cache.set(contentId, JSON.stringify(stored));
-
-      // Update index
-      const index = await this.getIndex();
-      index[contentId] = metadata;
-      await this.cache.set(this.indexKey, JSON.stringify(index));
-
-      return stored;
-    } catch (err) {
-      this.logger.warn(
-        `[ArtifactStore] S3 restore failed for ${contentId}:`,
-        (err as Error).message
-      );
-      return null;
-    }
-  }
-
-  /**
-   * Ensure content is loaded into Redis. If not in Redis, attempt S3 restore.
-   * Used before write/edit operations that need content to be present.
-   *
-   * @param contentId - The content entry ID.
-   * @throws If content is not found in Redis or S3.
-   */
-  protected async ensureLoaded(contentId: string): Promise<void> {
-    const existing = await this.getStored(contentId);
-    if (existing) {
-      return;
-    }
-
-    // Try S3 restore
-    const restored = await this.restoreFromS3(contentId);
-    if (!restored) {
-      throw new Error(`Content "${contentId}" not found in Redis or S3`);
-    }
-  }
-}