refactor: reduce any type usage in @objectql/types from ~86 to 2 justified instances

Replace `any` with type-safe alternatives across all type definition files:
- Use `Record<string, unknown>` for data objects (create/update payloads)
- Use `object` for parameters accepting interfaces (queries, filters, configs)
- Use `unknown` for opaque values (transaction handles, return values)
- Use generics with `Record<string, unknown>` defaults for hook/action contexts
- Make IObjectRepository generic with `<T = Record<string, unknown>>`
- Type MetadataRegistry storage with proper Record types

Remaining `any` (2 instances in api.ts captureStackTrace) is justified for V8 API compatibility.

All downstream builds maintain same error count (pre-existing only).
All 1723 tests continue to pass.

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

Author: Copilot

packages/foundation/types/src/action.ts

@@ -43,7 +43,7 @@ export type ActionInputDefinition = Record<string, FieldConfig>;
  * 
  * RUNTIME TYPE: Used during action execution.
  */
-export interface ActionContext<_BaseT = any, InputT = any> {
+export interface ActionContext<_BaseT = Record<string, unknown>, InputT = Record<string, unknown>> {
     /** The object this action belongs to. */
     objectName: string;
 
@@ -71,7 +71,7 @@ export interface ActionContext<_BaseT = any, InputT = any> {
      */
     user?: {
         id: string | number;
-        [key: string]: any;
+        [key: string]: unknown;
     };
 }
 
@@ -122,11 +122,11 @@ export interface ActionConfig {
  * 
  * RUNTIME TYPE: Includes the handler function for execution.
  */
-export interface ActionDefinition<BaseT = any, InputT = any, ReturnT = any> extends ActionConfig {
+export interface ActionDefinition<BaseT = Record<string, unknown>, InputT = Record<string, unknown>, ReturnT = unknown> extends ActionConfig {
     /**
      * The business logic implementation.
      */
     handler: (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;
 }
 
-export type ActionHandler<BaseT = any, InputT = any, ReturnT = any> = (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;
+export type ActionHandler<BaseT = Record<string, unknown>, InputT = Record<string, unknown>, ReturnT = unknown> = (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;

packages/foundation/types/src/app.ts

@@ -27,11 +27,11 @@ export interface IObjectQL {
     triggerHook(event: HookName, objectName: string, ctx: HookContext): Promise<void>;
 
     registerAction(objectName: string, actionName: string, handler: ActionHandler): void;
-    executeAction(objectName: string, actionName: string, ctx: ActionContext): Promise<any>;
+    executeAction(objectName: string, actionName: string, ctx: ActionContext): Promise<unknown>;
 
     /**
      * Get the underlying ObjectKernel instance
      * @returns The ObjectKernel instance
      */
-    getKernel(): any; // Using 'any' to avoid circular dependency with @objectstack/runtime
+    getKernel(): unknown; // Using 'unknown' to avoid circular dependency with @objectstack/runtime
 }

packages/foundation/types/src/application.ts

@@ -50,5 +50,5 @@ export interface AppConfig {
     /**
      * Custom metadata/settings
      */
-    [key: string]: any;
+    [key: string]: unknown;
 }

packages/foundation/types/src/context.ts

@@ -31,7 +31,7 @@ export interface ObjectQLContext {
      * Execute a function within a transaction.
      * The callback receives a new context 'trxCtx' which inherits userId, spaceId from this context.
      */
-    transaction(callback: (trxCtx: ObjectQLContext) => Promise<any>): Promise<any>;
+    transaction(callback: (trxCtx: ObjectQLContext) => Promise<unknown>): Promise<unknown>;
 
     /**
      * Returns a new context with system privileges (isSystem: true).
@@ -42,7 +42,7 @@ export interface ObjectQLContext {
     /**
      * Internal: Driver-specific transaction handle.
      */
-    transactionHandle?: any;
+    transactionHandle?: unknown;
 }
 
 export interface ObjectQLContextOptions {

packages/foundation/types/src/driver.ts

@@ -17,7 +17,7 @@ export interface IntrospectedColumn {
     /** Whether the column is nullable */
     nullable: boolean;
     /** Default value if any */
-    defaultValue?: any;
+    defaultValue?: unknown;
     /** Whether this is a primary key */
     isPrimary?: boolean;
     /** Whether this column has a unique constraint */
@@ -178,41 +178,41 @@ export interface Driver {
     readonly supports?: DriverCapabilities;
 
     // Core CRUD methods
-    find(objectName: string, query: any, options?: any): Promise<any[]>;
-    findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
-    create(objectName: string, data: any, options?: any): Promise<any>;
-    update(objectName: string, id: string | number, data: any, options?: any): Promise<any>;
-    delete(objectName: string, id: string | number, options?: any): Promise<any>;
-    count(objectName: string, filters: any, options?: any): Promise<number>;
+    find(objectName: string, query: object, options?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    findOne(objectName: string, id: string | number, query?: object, options?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    create(objectName: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    update(objectName: string, id: string | number, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(objectName: string, id: string | number, options?: Record<string, unknown>): Promise<unknown>;
+    count(objectName: string, filters: object, options?: Record<string, unknown>): Promise<number>;
 
     // Lifecycle methods
     connect?(): Promise<void>;
     disconnect?(): Promise<void>;
     checkHealth?(): Promise<boolean>;
 
     // Bulk operations
-    execute?(command: any, parameters?: any[], options?: any): Promise<any>;
-    bulkCreate?(objectName: string, data: any[], options?: any): Promise<any>;
-    bulkUpdate?(objectName: string, updates: Array<{id: string | number, data: any}>, options?: any): Promise<any>;
-    bulkDelete?(objectName: string, ids: Array<string | number>, options?: any): Promise<any>;
+    execute?(command: object, parameters?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
+    bulkCreate?(objectName: string, data: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
+    bulkUpdate?(objectName: string, updates: Array<{id: string | number, data: Record<string, unknown>}>, options?: Record<string, unknown>): Promise<unknown>;
+    bulkDelete?(objectName: string, ids: Array<string | number>, options?: Record<string, unknown>): Promise<unknown>;
 
     // Query extensions
-    distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
-    aggregate?(objectName: string, query: any, options?: any): Promise<any[]>;
+    distinct?(objectName: string, field: string, filters?: object, options?: Record<string, unknown>): Promise<unknown[]>;
+    aggregate?(objectName: string, query: object, options?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
 
     // Transaction support
-    beginTransaction?(): Promise<any>;
+    beginTransaction?(): Promise<unknown>;
     /** @deprecated Use `commit` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */
-    commitTransaction?(transaction: any): Promise<void>;
+    commitTransaction?(transaction: unknown): Promise<void>;
     /** @deprecated Use `rollback` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */
-    rollbackTransaction?(transaction: any): Promise<void>;
+    rollbackTransaction?(transaction: unknown): Promise<void>;
     /** Commit a transaction (spec-aligned name) */
-    commit?(transaction: any): Promise<void>;
+    commit?(transaction: unknown): Promise<void>;
     /** Rollback a transaction (spec-aligned name) */
-    rollback?(transaction: any): Promise<void>;
+    rollback?(transaction: unknown): Promise<void>;
 
     // Schema / Lifecycle
-    init?(objects: any[]): Promise<void>;
+    init?(objects: object[]): Promise<void>;
 
     /**
      * Introspect the database schema to discover existing tables, columns, and relationships.
@@ -221,32 +221,32 @@ export interface Driver {
     introspectSchema?(): Promise<IntrospectedSchema>;
 
     // Bulk / Atomic (alternative signatures)
-    createMany?(objectName: string, data: any[], options?: any): Promise<any>;
-    updateMany?(objectName: string, filters: any, data: any, options?: any): Promise<any>;
-    deleteMany?(objectName: string, filters: any, options?: any): Promise<any>;
-    findOneAndUpdate?(objectName: string, filters: any, update: any, options?: any): Promise<any>;
+    createMany?(objectName: string, data: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
+    updateMany?(objectName: string, filters: object, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+    deleteMany?(objectName: string, filters: object, options?: Record<string, unknown>): Promise<unknown>;
+    findOneAndUpdate?(objectName: string, filters: object, update: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
 
     // DriverInterface v4.0 methods
     /**
      * Execute a query using QueryAST format (DriverInterface v4.0)
      */
-    executeQuery?(ast: any, options?: any): Promise<{ value: any[]; count?: number }>;
+    executeQuery?(ast: object, options?: Record<string, unknown>): Promise<{ value: Record<string, unknown>[]; count?: number }>;
 
     /**
      * Execute a command using Command format (DriverInterface v4.0)
      */
-    executeCommand?(command: any, options?: any): Promise<{ success: boolean; data?: any; affected: number }>;
+    executeCommand?(command: object, options?: Record<string, unknown>): Promise<{ success: boolean; data?: unknown; affected: number }>;
 
     /**
      * Alternative method name for findOne (some drivers use 'get')
      */
-    get?(objectName: string, id: string, options?: any): Promise<any>;
+    get?(objectName: string, id: string, options?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
 
     /**
      * Direct query execution (legacy)
      */
-    directQuery?(sql: string, params?: any[]): Promise<any[]>;
-    query?(sql: string, params?: any[]): Promise<any[]>;
+    directQuery?(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    query?(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
 
     // ========================================================================
     // Methods from @objectstack/spec DriverInterfaceSchema
@@ -261,7 +261,7 @@ export interface Driver {
      * @param options - Driver options.
      * @returns The upserted record.
      */
-    upsert?(objectName: string, data: Record<string, unknown>, options?: any): Promise<any>;
+    upsert?(objectName: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
 
     /**
      * Stream records matching the structured query.
@@ -272,7 +272,7 @@ export interface Driver {
      * @param options - Driver options.
      * @returns AsyncIterable/ReadableStream of records.
      */
-    findStream?(objectName: string, query: any, options?: any): AsyncIterable<any> | any;
+    findStream?(objectName: string, query: object, options?: Record<string, unknown>): AsyncIterable<Record<string, unknown>> | unknown;
 
     /**
      * Get connection pool statistics.
@@ -289,15 +289,15 @@ export interface Driver {
      * @param objects - Object definitions to synchronize.
      * @param options - Driver options.
      */
-    syncSchema?(objects: any[], options?: any): Promise<void>;
+    syncSchema?(objects: object[], options?: Record<string, unknown>): Promise<void>;
 
     /**
      * Drop a table/collection by name.
      * 
      * @param objectName - The name of the object/table to drop.
      * @param options - Driver options.
      */
-    dropTable?(objectName: string, options?: any): Promise<void>;
+    dropTable?(objectName: string, options?: Record<string, unknown>): Promise<void>;
 
     /**
      * Explain the execution plan for a query.
@@ -308,6 +308,6 @@ export interface Driver {
      * @param options - Driver options.
      * @returns Execution plan details.
      */
-    explain?(objectName: string, query: any, options?: any): Promise<any>;
+    explain?(objectName: string, query: object, options?: Record<string, unknown>): Promise<unknown>;
 }
 

packages/foundation/types/src/gateway.ts

@@ -16,15 +16,15 @@ export interface ApiRequest {
     path: string;
     method: ApiMethod;
     headers: Record<string, string | string[] | undefined>;
-    query: Record<string, any>;
-    body?: any;
+    query: Record<string, unknown>;
+    body?: unknown;
     protocol?: string; // e.g. 'rest', 'graphql'
 }
 
 export interface ApiResponse {
     status: number;
     headers?: Record<string, string | string[]>;
-    body: any;
+    body: unknown;
 }
 
 export interface GatewayProtocol {

packages/foundation/types/src/hook.ts

@@ -21,20 +21,18 @@ export type HookTiming = 'before' | 'after';
  * Minimal API surface exposed to hooks for performing side-effects or checks.
  */
 export interface HookAPI {
-    // We use 'any' here to avoid circular dependencies with core/ObjectQL
-    // In practice, this is the ObjectQL instance.
-    find(objectName: string, query?: any): Promise<any[]>;
-    findOne(objectName: string, id: string | number): Promise<any>;
-    count(objectName: string, query?: any): Promise<number>;
-    create(objectName: string, data: any): Promise<any>;
-    update(objectName: string, id: string | number, data: any): Promise<any>;
-    delete(objectName: string, id: string | number): Promise<any>;
+    find(objectName: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    findOne(objectName: string, id: string | number): Promise<Record<string, unknown> | null>;
+    count(objectName: string, query?: Record<string, unknown>): Promise<number>;
+    create(objectName: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    update(objectName: string, id: string | number, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(objectName: string, id: string | number): Promise<Record<string, unknown>>;
 }
 
 /**
  * Base context available in all hooks.
  */
-export interface BaseHookContext<_T = any> {
+export interface BaseHookContext<_T = Record<string, unknown>> {
     /** The name of the object (entity) being acted upon. */
     objectName: string;
 
@@ -47,24 +45,24 @@ export interface BaseHookContext<_T = any> {
     /** User/Session context (Authentication info). */
     user?: {
         id: string | number;
-        [key: string]: any;
+        [key: string]: unknown;
     };
 
     /** 
      * Shared state for passing data between matching 'before' and 'after' hooks.
      * e.g. Calculate a diff in 'beforeUpdate' and read it in 'afterUpdate'.
      */
-    state: Record<string, any>;
+    state: Record<string, unknown>;
 }
 
 /**
  * Context for Retrieval operations (Find, Count).
  */
-export interface RetrievalHookContext<T = any> extends BaseHookContext<T> {
+export interface RetrievalHookContext<T = Record<string, unknown>> extends BaseHookContext<T> {
     operation: 'find' | 'count';
 
     /** The query criteria being executed. Modifiable in 'before' hooks. */
-    query: any;
+    query: object;
 
     /** The result of the query. Only available in 'after' hooks. */
     result?: T[] | number;
@@ -73,7 +71,7 @@ export interface RetrievalHookContext<T = any> extends BaseHookContext<T> {
 /**
  * Context for Modification operations (Create, Update, Delete).
  */
-export interface MutationHookContext<T = any> extends BaseHookContext<T> {
+export interface MutationHookContext<T = Record<string, unknown>> extends BaseHookContext<T> {
     operation: 'create' | 'update' | 'delete';
 
     /** The record ID. Undefined for 'create'. */
@@ -103,7 +101,7 @@ export interface MutationHookContext<T = any> extends BaseHookContext<T> {
 /**
  * Specialized context for Updates, including change tracking.
  */
-export interface UpdateHookContext<T = any> extends MutationHookContext<T> {
+export interface UpdateHookContext<T = Record<string, unknown>> extends MutationHookContext<T> {
     operation: 'update';
 
     /**
@@ -116,7 +114,7 @@ export interface UpdateHookContext<T = any> extends MutationHookContext<T> {
 /**
  * Definition interface for a set of hooks for a specific object.
  */
-export interface ObjectHookDefinition<T = any> {
+export interface ObjectHookDefinition<T = Record<string, unknown>> {
     beforeFind?: (ctx: RetrievalHookContext<T>) => Promise<void> | void;
     afterFind?: (ctx: RetrievalHookContext<T>) => Promise<void> | void;
 
@@ -134,5 +132,5 @@ export interface ObjectHookDefinition<T = any> {
 }
 
 export type HookName = keyof ObjectHookDefinition;
-export type HookContext<T = any> = RetrievalHookContext<T> | MutationHookContext<T> | UpdateHookContext<T>;
-export type HookHandler<T = any> = (ctx: HookContext<T>) => Promise<void> | void;
+export type HookContext<T = Record<string, unknown>> = RetrievalHookContext<T> | MutationHookContext<T> | UpdateHookContext<T>;
+export type HookHandler<T = Record<string, unknown>> = (ctx: HookContext<T>) => Promise<void> | void;

packages/foundation/types/src/loader.ts

@@ -21,5 +21,5 @@ export interface LoaderPlugin {
     name: string;
     glob: string[];
     handler: LoaderHandler;
-    options?: any;
+    options?: Record<string, unknown>;
 }

packages/foundation/types/src/object.ts

@@ -196,5 +196,5 @@ export interface ObjectDoc {
     _id?: string | number;
     created_at?: Date | string;
     updated_at?: Date | string;
-    [key: string]: any;
+    [key: string]: unknown;
 }

packages/foundation/types/src/permission.ts

@@ -101,7 +101,7 @@ export interface SimpleCondition {
     /** Comparison operator */
     operator: PermissionOperator;
     /** Value to compare against (can include variables like $current_user.id) */
-    value: any;
+    value: unknown;
 }
 
 /**
@@ -110,7 +110,7 @@ export interface SimpleCondition {
 export interface ConditionElement {
     field: string;
     operator: PermissionOperator;
-    value: any;
+    value: unknown;
 }
 
 /**
@@ -266,7 +266,7 @@ export interface ActionCondition {
     /** Comparison operator */
     operator: PermissionOperator;
     /** Value to compare */
-    value: any;
+    value: unknown;
 }
 
 /**
@@ -458,7 +458,7 @@ export interface PermissionCheckContext {
         roles?: string[];
         department_id?: string;
         team_id?: string;
-        [key: string]: any;
+        [key: string]: unknown;
     };
     /** Object name */
     object: string;
@@ -469,7 +469,7 @@ export interface PermissionCheckContext {
     /** Field name (for field-level checks) */
     field?: string;
     /** Record data (for condition evaluation) */
-    record?: any;
+    record?: Record<string, unknown>;
 }
 
 /**