feat(#3305): add DocumentSyncService for content hash tracking (#3570)

* feat(#3305): add DocumentSyncService for content hash tracking

Implement DocumentSyncService (task 1.4) as a cache-backed service
that tracks content hashes for RAG pipeline document change detection.
Uses Backstage coreServices.cache with a 365-day TTL per the
cache-migration spec requirement for effectively no expiry.

The service provides setHash, getHash, deleteHash, and hasChanged
methods with namespaced cache keys (doc-sync:<documentId>), enabling
the RAG pipeline to detect which documents have changed and only
re-ingest modified files. Content hashes are shared across instances
for consistent sync behavior.

Follows the established cache service pattern (ConversationRegistry,
BackendApprovalStore) with full test coverage (8 tests, 100%
coverage on DocumentSyncService.ts).

Closes #3305

* fix: add warning log for unexpected cache value types in DocumentSyncService

Log a warning when getHash receives a non-string, non-undefined value
from the cache, making cache corruption distinguishable from a cache
miss. Adds corresponding test coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Co-authored-by: gabemontero <gmontero@redhat.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

workspaces/boost/plugins/boost-backend/report.api.md

@@ -334,6 +334,22 @@ export function createToolResourceLoader(): ResourceLoader;
 // @public
 export function createToolRoutes(options: ToolRoutesOptions): Router;
 
+// @public
+export class DocumentSyncService {
+  constructor(options: DocumentSyncServiceOptions);
+  deleteHash(documentId: string): Promise<void>;
+  getHash(documentId: string): Promise<string | undefined>;
+  hasChanged(documentId: string, currentHash: string): Promise<boolean>;
+  setHash(documentId: string, hash: string): Promise<void>;
+  static readonly TTL_MS: number;
+}
+
+// @public
+export interface DocumentSyncServiceOptions {
+  cache: CacheService;
+  logger: LoggerService;
+}
+
 // @public
 export function isDbWritable(key: BoostConfigKey): boolean;
 

workspaces/boost/plugins/boost-backend/src/documents/DocumentSyncService.test.ts

@@ -0,0 +1,117 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type {
+  CacheService,
+  LoggerService,
+} from '@backstage/backend-plugin-api';
+import { DocumentSyncService } from './DocumentSyncService';
+
+function createMockLogger(): LoggerService {
+  return {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    debug: jest.fn(),
+    child: jest.fn().mockReturnThis(),
+  };
+}
+
+function createMockCache(): CacheService {
+  const store = new Map<string, unknown>();
+  return {
+    get: jest.fn(async (key: string) => store.get(key)) as CacheService['get'],
+    set: jest.fn(async (key: string, value: unknown) => {
+      store.set(key, value);
+    }),
+    delete: jest.fn(async (key: string) => {
+      store.delete(key);
+    }),
+    withOptions: jest.fn().mockReturnThis(),
+  };
+}
+
+describe('DocumentSyncService', () => {
+  let service: DocumentSyncService;
+  let mockCache: CacheService;
+  let mockLogger: LoggerService;
+
+  beforeEach(() => {
+    mockCache = createMockCache();
+    mockLogger = createMockLogger();
+    service = new DocumentSyncService({
+      cache: mockCache,
+      logger: mockLogger,
+    });
+  });
+
+  it('uses cacheService with 365-day TTL', () => {
+    expect(mockCache.withOptions).toHaveBeenCalledWith({
+      defaultTtl: 365 * 24 * 60 * 60 * 1000,
+    });
+  });
+
+  it('sets and gets a content hash', async () => {
+    await service.setHash('doc-1', 'abc123');
+    const result = await service.getHash('doc-1');
+    expect(result).toBe('abc123');
+  });
+
+  it('returns undefined for unknown document ID', async () => {
+    const result = await service.getHash('unknown');
+    expect(result).toBeUndefined();
+  });
+
+  it('deletes a content hash', async () => {
+    await service.setHash('doc-1', 'abc123');
+    await service.deleteHash('doc-1');
+    const result = await service.getHash('doc-1');
+    expect(result).toBeUndefined();
+  });
+
+  it('warns on unexpected non-string cache value', async () => {
+    (mockCache.get as jest.Mock).mockResolvedValueOnce(42);
+    const result = await service.getHash('doc-1');
+    expect(result).toBeUndefined();
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Unexpected cache value type'),
+    );
+  });
+
+  it('uses namespaced cache keys', async () => {
+    await service.setHash('doc-1', 'abc123');
+    expect(mockCache.set).toHaveBeenCalledWith('doc-sync:doc-1', 'abc123');
+  });
+
+  describe('hasChanged', () => {
+    it('returns true for a new document', async () => {
+      const result = await service.hasChanged('doc-new', 'hash1');
+      expect(result).toBe(true);
+    });
+
+    it('returns false when hash matches', async () => {
+      await service.setHash('doc-1', 'hash1');
+      const result = await service.hasChanged('doc-1', 'hash1');
+      expect(result).toBe(false);
+    });
+
+    it('returns true when hash differs', async () => {
+      await service.setHash('doc-1', 'hash1');
+      const result = await service.hasChanged('doc-1', 'hash2');
+      expect(result).toBe(true);
+    });
+  });
+});

workspaces/boost/plugins/boost-backend/src/documents/DocumentSyncService.ts

@@ -0,0 +1,113 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type {
+  CacheService,
+  LoggerService,
+} from '@backstage/backend-plugin-api';
+
+/**
+ * Options for creating a DocumentSyncService.
+ *
+ * @public
+ */
+export interface DocumentSyncServiceOptions {
+  /** The Backstage cache service. */
+  cache: CacheService;
+  /** The Backstage logger service. */
+  logger: LoggerService;
+}
+
+/**
+ * Cache-backed service that tracks content hashes for document change detection.
+ * Uses Backstage cacheService with a long TTL per the cache-migration spec (task 1.4).
+ *
+ * Content hashes are shared across instances for consistent sync behavior,
+ * enabling the RAG pipeline to detect which documents have changed and
+ * only re-ingest modified files.
+ *
+ * @public
+ */
+export class DocumentSyncService {
+  private readonly cache: CacheService;
+  private readonly logger: LoggerService;
+
+  /** Cache TTL for content hashes: 365 days (effectively no expiry). */
+  static readonly TTL_MS = 365 * 24 * 60 * 60 * 1000;
+
+  constructor(options: DocumentSyncServiceOptions) {
+    this.cache = options.cache.withOptions({
+      defaultTtl: DocumentSyncService.TTL_MS,
+    });
+    this.logger = options.logger;
+  }
+
+  /**
+   * Stores a content hash for a document.
+   *
+   * @param documentId - The unique document identifier.
+   * @param hash - The content hash of the document.
+   */
+  async setHash(documentId: string, hash: string): Promise<void> {
+    const key = `doc-sync:${documentId}`;
+    await this.cache.set(key, hash);
+    this.logger.debug(`Stored content hash for document ${documentId}`);
+  }
+
+  /**
+   * Retrieves the stored content hash for a document.
+   *
+   * @param documentId - The unique document identifier.
+   * @returns The content hash or undefined if not cached.
+   */
+  async getHash(documentId: string): Promise<string | undefined> {
+    const key = `doc-sync:${documentId}`;
+    const value = await this.cache.get(key);
+    if (typeof value === 'string') {
+      return value;
+    }
+    if (value !== undefined) {
+      this.logger.warn(
+        `Unexpected cache value type for document ${documentId}: ${typeof value}`,
+      );
+    }
+    return undefined;
+  }
+
+  /**
+   * Removes the content hash for a document.
+   *
+   * @param documentId - The unique document identifier.
+   */
+  async deleteHash(documentId: string): Promise<void> {
+    const key = `doc-sync:${documentId}`;
+    await this.cache.delete(key);
+    this.logger.debug(`Removed content hash for document ${documentId}`);
+  }
+
+  /**
+   * Checks whether a document has changed by comparing its current content
+   * hash against the stored hash.
+   *
+   * @param documentId - The unique document identifier.
+   * @param currentHash - The current content hash to compare.
+   * @returns True if the document is new or has changed, false otherwise.
+   */
+  async hasChanged(documentId: string, currentHash: string): Promise<boolean> {
+    const storedHash = await this.getHash(documentId);
+    return storedHash !== currentHash;
+  }
+}

workspaces/boost/plugins/boost-backend/src/documents/index.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {
+  DocumentSyncService,
+  type DocumentSyncServiceOptions,
+} from './DocumentSyncService';

workspaces/boost/plugins/boost-backend/src/index.ts

@@ -77,6 +77,10 @@ export {
   BackendApprovalStore,
   type BackendApprovalStoreOptions,
 } from './approval';
+export {
+  DocumentSyncService,
+  type DocumentSyncServiceOptions,
+} from './documents';
 export {
   createChatRoutes,
   ConversationAgentCache,

workspaces/boost/plugins/boost-backend/src/plugin.ts

@@ -50,6 +50,7 @@ import { ConversationRegistry } from './chat/ConversationRegistry';
 import { ConversationStore } from './chat/ConversationStore';
 import { RateLimiter } from './chat/RateLimiter';
 import { BackendApprovalStore } from './approval/BackendApprovalStore';
+import { DocumentSyncService } from './documents/DocumentSyncService';
 
 /**
  * The ProviderManager instance shared between the plugin and the
@@ -227,6 +228,16 @@ export const boostPlugin = createBackendPlugin({
           logger,
         });
 
+        // Initialize document sync service — tracks content hashes
+        // for RAG pipeline change detection (task 1.4). Available for
+        // document ingestion and sync features.
+        // @ts-ignore TS6133 — retained for RAG pipeline / document sync
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const _documentSyncService = new DocumentSyncService({
+          cache,
+          logger,
+        });
+
         // Register all boost permissions with the framework
         permissionsRegistry.addPermissions([...boostPermissions]);
         logger.info(`Registered ${boostPermissions.length} boost permissions`);