refactor: add JSDoc comments explaining object vs Record<string, unknown> type strategy

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/foundation/types/src/driver.ts

@@ -169,6 +169,15 @@ export interface BaseDriverConfig {
 // Driver Interface
 // ============================================================================
 
+/**
+ * Database driver interface. All storage backends implement this contract.
+ * 
+ * Type strategy:
+ * - `Record<string, unknown>` for data payloads (plain field-value maps)
+ * - `object` for query/filter/command parameters that may receive named interfaces
+ *   (e.g., UnifiedQuery, Filter) which lack implicit index signatures
+ * - `unknown` for opaque values (transaction handles, heterogeneous returns)
+ */
 export interface Driver {
     /** Driver identifier (e.g., 'memory', 'sql', 'mongo') */
     readonly name?: string;

packages/foundation/types/src/hook.ts

@@ -61,7 +61,11 @@ export interface BaseHookContext<_T = Record<string, unknown>> {
 export interface RetrievalHookContext<T = Record<string, unknown>> extends BaseHookContext<T> {
     operation: 'find' | 'count';
 
-    /** The query criteria being executed. Modifiable in 'before' hooks. */
+    /** 
+     * The query criteria being executed. Modifiable in 'before' hooks.
+     * Typed as `object` (not `Record<string, unknown>`) because named interfaces
+     * like UnifiedQuery lack index signatures and aren't assignable to Record types.
+     */
     query: object;
 
     /** The result of the query. Only available in 'after' hooks. */

packages/foundation/types/src/repository.ts

@@ -8,6 +8,15 @@
 
 import { UnifiedQuery, Filter } from "./query";
 
+/**
+ * Repository interface for CRUD operations on a single object type.
+ * 
+ * Note: `object` is used for filter/query parameters instead of `Record<string, unknown>`
+ * because named TypeScript interfaces (e.g., UnifiedQuery, Filter) lack implicit index
+ * signatures and are not assignable to `Record<string, unknown>`.
+ * 
+ * @typeParam T - The document shape returned by queries. Defaults to `Record<string, unknown>`.
+ */
 export interface IObjectRepository<T = Record<string, unknown>> {
     find(query?: UnifiedQuery): Promise<T[]>;
     findOne(idOrQuery: string | number | UnifiedQuery): Promise<T | null>;