Refactor docs and add action/hook tests to core package

Removed several guide documents (logic-hooks-examples, sdk-reference, security-guide, visual-reporting) and updated logic-actions.md and logic-hooks.md for improved clarity and API alignment. Added jest config and new tests for actions and hooks in packages/core, including a MockDriver utility. Enhanced ObjectRepository with an execute method for custom actions. Updated metadata-format spec to document action definitions.

Author: hotlong

docs/guide/logic-actions.md

@@ -72,32 +72,28 @@ Similar to Triggers, expected convention is `*.actions.ts`.
 ### 3.1 Handler Signature
 
 ```typescript
-// objects/contracts/contracts.actions.ts
-import { defineAction } from '@objectql/core';
-
-export default defineAction({
-  object: 'contracts',
-  name: 'terminate', // Must match metadata key
-  
-  async handler({ ctx, id, params }) {
+// Registering action handler
+db.registerAction('contracts', 'terminate', async (ctx: ActionContext) => {
+    const { id, params } = ctx;
+    
     // 1. Validate Business Logic
-    const contract = await ctx.object('contracts').findOne(id);
-    if (contract.status === 'terminated') {
-      throw new Error("Contract is already terminated.");
-    }
+    // Access repository via db or generic find
+    // ...
+    
+    return { success: true };
+});
+```
 
-    // 2. Perform Updates (Atomic Transaction inherited from ctx)
-    await ctx.object('contracts').update(id, {
-      status: 'terminated',
-      termination_reason: params.reason,
-      termination_date: params.effective_date || new Date()
-    });
-
-    // 3. Create Related Records
-    if (params.penalty_amount > 0) {
-      await ctx.object('invoices').create({
-        contract_id: id,
-        amount: params.penalty_amount,
+### 3.2 Invocation
+
+You can execute actions using the Repository instance:
+
+```typescript
+const result = await db.object('contracts').execute('terminate', 'contract_123', {
+    reason: 'Client request',
+    effective_date: '2023-12-31'
+});
+```
         type: 'penalty'
       });
     }

docs/guide/logic-hooks-examples.md

@@ -11,42 +11,25 @@ The system provides a rich interception model (AOP) to inject business logic int
 Hooks receive a structured object containing the **Session Context** and the **Operation Payload**.
 
 ```typescript
-import { UnifiedQuery, ObjectQLContext } from './CORE_TYPES';
-
-export interface HookContext<T = any> {
-  // === 1. The Session Context ===
-  // Automatically propagates userId, spaceId, and Transaction.
-  ctx: ObjectQLContext;
-
-  // === 2. Operational Info ===
-  entity: string;
-  op: 'find' | 'create' | 'update' | 'delete' | 'count' | 'aggregate';
-  
-  // === 3. Data Payload (Mutable) ===
-  // - In beforeCreate/Update: The data to be written. 
-  // - In afterCreate/Update: The result record returned from DB.
-  doc?: T;              
-
-  // === 4. Query Context (Mutable, for 'find' only) ===
-  // Complies strictly with the UnifiedQuery JSON-DSL (AST).
-  // Developers can modify 'fields', 'sort', or wrap 'filters'.
-  query?: UnifiedQuery;
-  
-  // === 5. Helpers ===
-  getPreviousDoc: () => Promise<T>;
-  
-  // AST Manipulation Utilities
-  utils: {
-    /**
-     * Safely injects a new filter criterion into the existing AST.
-     * It wraps existing filters in a new group to preserve operator precedence.
-     * * Logic: (Existing_Filters) AND (New_Filter)
-     */
-    restrict: (criterion: [string, string, any]) => void;
-  };
+import { UnifiedQuery, ObjectQLContext, HookContext } from '@objectql/types';
+
+export interface HookContext extends ObjectQLContext {
+    // === 1. Target Info ===
+    objectName: string;
+    
+    // === 2. Operational Data (Mutable) ===
+    query?: UnifiedQuery; // For find/count
+    doc?: any;            // For create/update
+    id?: string | number; // For update/delete/findOne
+    
+    // === 3. Result (for after* hooks) ===
+    result?: any;
+    
+    // === 4. Shared Meta ===
+    meta?: any;           // To pass data between hooks or from main context
 }
 
-export type HookFunction = (context: HookContext) => Promise<void>;
+export type HookHandler = (ctx: HookContext) => Promise<void> | void;
 ```
 
 ## 3. Registering Hooks