Phase 1: Add ExecutionContext schema and context field to all DataEngine options

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

Author: Copilot

packages/spec/src/data/data-engine.test.ts

@@ -644,6 +644,82 @@ describe('DataEngineRequestSchema', () => {
 });
 
 describe('Integration Tests', () => {
+  it('should support context in query options', () => {
+    const options = DataEngineQueryOptionsSchema.parse({
+      filter: { status: 'active' },
+      context: {
+        userId: 'user_123',
+        tenantId: 'org_456',
+        roles: ['admin'],
+      },
+    });
+
+    expect(options.context?.userId).toBe('user_123');
+    expect(options.context?.tenantId).toBe('org_456');
+    expect(options.context?.roles).toEqual(['admin']);
+  });
+
+  it('should support context in insert options', () => {
+    const options = DataEngineInsertOptionsSchema.parse({
+      returning: true,
+      context: { userId: 'user_1', isSystem: false },
+    });
+
+    expect(options.context?.userId).toBe('user_1');
+  });
+
+  it('should support context in update options', () => {
+    const options = DataEngineUpdateOptionsSchema.parse({
+      filter: { id: '1' },
+      context: { userId: 'user_1', tenantId: 'org_1' },
+    });
+
+    expect(options.context?.tenantId).toBe('org_1');
+  });
+
+  it('should support context in delete options', () => {
+    const options = DataEngineDeleteOptionsSchema.parse({
+      filter: { id: '1' },
+      context: { isSystem: true },
+    });
+
+    expect(options.context?.isSystem).toBe(true);
+  });
+
+  it('should support context in count options', () => {
+    const options = DataEngineCountOptionsSchema.parse({
+      filter: { status: 'active' },
+      context: { userId: 'u1' },
+    });
+
+    expect(options.context?.userId).toBe('u1');
+  });
+
+  it('should support context in aggregate options', () => {
+    const options = DataEngineAggregateOptionsSchema.parse({
+      groupBy: ['status'],
+      context: { userId: 'u1', roles: ['analyst'] },
+    });
+
+    expect(options.context?.roles).toEqual(['analyst']);
+  });
+
+  it('should accept options without context (backward compatible)', () => {
+    const queryOpts = DataEngineQueryOptionsSchema.parse({ filter: { x: 1 } });
+    const insertOpts = DataEngineInsertOptionsSchema.parse({ returning: true });
+    const updateOpts = DataEngineUpdateOptionsSchema.parse({ upsert: true });
+    const deleteOpts = DataEngineDeleteOptionsSchema.parse({ multi: true });
+    const countOpts = DataEngineCountOptionsSchema.parse({});
+    const aggOpts = DataEngineAggregateOptionsSchema.parse({ groupBy: ['a'] });
+
+    expect(queryOpts.context).toBeUndefined();
+    expect(insertOpts.context).toBeUndefined();
+    expect(updateOpts.context).toBeUndefined();
+    expect(deleteOpts.context).toBeUndefined();
+    expect(countOpts.context).toBeUndefined();
+    expect(aggOpts.context).toBeUndefined();
+  });
+
   it('should support complete CRUD workflow', () => {
     // Create
     const insertRequest = DataEngineInsertRequestSchema.parse({

packages/spec/src/data/data-engine.zod.ts

@@ -3,6 +3,7 @@
 import { z } from 'zod';
 import { FilterConditionSchema } from './filter.zod';
 import { SortNodeSchema } from './query.zod';
+import { ExecutionContextSchema } from '../kernel/execution-context.zod';
 
 /**
  * Data Engine Protocol
@@ -41,11 +42,26 @@ export const DataEngineSortSchema = z.union([
   z.array(SortNodeSchema)
 ]).describe('Sort order definition');
 
+// ==========================================================================
+// 1b. Base Engine Options (shared context)
+// ==========================================================================
+
+/**
+ * Base Engine Options
+ * 
+ * All Data Engine operation options extend this schema to carry
+ * an optional ExecutionContext for identity, tenant, and transaction propagation.
+ */
+export const BaseEngineOptionsSchema = z.object({
+  /** Execution context (identity, tenant, transaction) */
+  context: ExecutionContextSchema.optional(),
+});
+
 // ==========================================================================
 // 2. method: FIND
 // ==========================================================================
 
-export const DataEngineQueryOptionsSchema = z.object({
+export const DataEngineQueryOptionsSchema = BaseEngineOptionsSchema.extend({
   /** Filter conditions (WHERE) */
   filter: DataEngineFilterSchema.optional(),
 
@@ -78,7 +94,7 @@ export const DataEngineQueryOptionsSchema = z.object({
 // 3. method: INSERT
 // ==========================================================================
 
-export const DataEngineInsertOptionsSchema = z.object({
+export const DataEngineInsertOptionsSchema = BaseEngineOptionsSchema.extend({
   /** 
    * Return the inserted record(s)? 
    * Some drivers support RETURNING clause for efficiency.
@@ -91,7 +107,7 @@ export const DataEngineInsertOptionsSchema = z.object({
 // 4. method: UPDATE
 // ==========================================================================
 
-export const DataEngineUpdateOptionsSchema = z.object({
+export const DataEngineUpdateOptionsSchema = BaseEngineOptionsSchema.extend({
   /** Filter conditions to identify records to update */
   filter: DataEngineFilterSchema.optional(),
 
@@ -119,7 +135,7 @@ export const DataEngineUpdateOptionsSchema = z.object({
 // 5. method: DELETE
 // ==========================================================================
 
-export const DataEngineDeleteOptionsSchema = z.object({
+export const DataEngineDeleteOptionsSchema = BaseEngineOptionsSchema.extend({
   /** Filter conditions to identify records to delete */
   filter: DataEngineFilterSchema.optional(),
 
@@ -135,7 +151,7 @@ export const DataEngineDeleteOptionsSchema = z.object({
 // 6. method: AGGREGATE
 // ==========================================================================
 
-export const DataEngineAggregateOptionsSchema = z.object({
+export const DataEngineAggregateOptionsSchema = BaseEngineOptionsSchema.extend({
   /** Filter conditions (WHERE) */
   filter: DataEngineFilterSchema.optional(),
 
@@ -157,7 +173,7 @@ export const DataEngineAggregateOptionsSchema = z.object({
 // 7. method: COUNT
 // ==========================================================================
 
-export const DataEngineCountOptionsSchema = z.object({
+export const DataEngineCountOptionsSchema = BaseEngineOptionsSchema.extend({
   /** Filter conditions */
   filter: DataEngineFilterSchema.optional(),
 }).describe('Options for DataEngine.count operations');
@@ -335,6 +351,7 @@ export const DataEngineRequestSchema = z.discriminatedUnion('method', [
 
 export type DataEngineFilter = z.infer<typeof DataEngineFilterSchema>;
 export type DataEngineSort = z.infer<typeof DataEngineSortSchema>;
+export type BaseEngineOptions = z.infer<typeof BaseEngineOptionsSchema>;
 export type DataEngineQueryOptions = z.infer<typeof DataEngineQueryOptionsSchema>;
 export type DataEngineInsertOptions = z.infer<typeof DataEngineInsertOptionsSchema>;
 export type DataEngineUpdateOptions = z.infer<typeof DataEngineUpdateOptionsSchema>;

packages/spec/src/kernel/execution-context.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { ExecutionContextSchema } from './execution-context.zod';
+
+describe('ExecutionContextSchema', () => {
+  it('should accept empty context (all optional)', () => {
+    const ctx = ExecutionContextSchema.parse({});
+    expect(ctx.roles).toEqual([]);
+    expect(ctx.permissions).toEqual([]);
+    expect(ctx.isSystem).toBe(false);
+  });
+
+  it('should accept full context', () => {
+    const ctx = ExecutionContextSchema.parse({
+      userId: 'user_123',
+      tenantId: 'org_456',
+      roles: ['admin', 'editor'],
+      permissions: ['read:account', 'write:account'],
+      isSystem: false,
+      accessToken: 'Bearer abc',
+      traceId: 'trace-789',
+    });
+
+    expect(ctx.userId).toBe('user_123');
+    expect(ctx.tenantId).toBe('org_456');
+    expect(ctx.roles).toEqual(['admin', 'editor']);
+    expect(ctx.permissions).toEqual(['read:account', 'write:account']);
+    expect(ctx.isSystem).toBe(false);
+    expect(ctx.accessToken).toBe('Bearer abc');
+    expect(ctx.traceId).toBe('trace-789');
+  });
+
+  it('should default roles and permissions to empty arrays', () => {
+    const ctx = ExecutionContextSchema.parse({ userId: 'u1' });
+    expect(ctx.roles).toEqual([]);
+    expect(ctx.permissions).toEqual([]);
+  });
+
+  it('should default isSystem to false', () => {
+    const ctx = ExecutionContextSchema.parse({});
+    expect(ctx.isSystem).toBe(false);
+  });
+
+  it('should accept system context', () => {
+    const ctx = ExecutionContextSchema.parse({ isSystem: true });
+    expect(ctx.isSystem).toBe(true);
+  });
+
+  it('should accept transaction handle', () => {
+    const mockTx = { id: 'tx1', commit: () => {} };
+    const ctx = ExecutionContextSchema.parse({ transaction: mockTx });
+    expect(ctx.transaction).toBeDefined();
+  });
+});

packages/spec/src/kernel/execution-context.zod.ts

@@ -0,0 +1,46 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { z } from 'zod';
+
+/**
+ * Execution Context Schema
+ * 
+ * Defines the runtime context that flows from HTTP request → data operations.
+ * This is the "identity + environment" envelope that every data operation can carry.
+ * 
+ * Design:
+ * - All fields are optional for backward compatibility
+ * - `isSystem` bypasses permission checks (for internal/migration operations)
+ * - `transaction` carries the database transaction handle for atomicity
+ * - `traceId` enables distributed tracing across microservices
+ * 
+ * Usage:
+ *   engine.find('account', { context: { userId: '...', tenantId: '...' } })
+ */
+export const ExecutionContextSchema = z.object({
+  /** Current user ID (resolved from session) */
+  userId: z.string().optional(),
+  
+  /** Current organization/tenant ID (resolved from session.activeOrganizationId) */
+  tenantId: z.string().optional(),
+  
+  /** User role names (resolved from Member + Role) */
+  roles: z.array(z.string()).default([]),
+  
+  /** Aggregated permission names (resolved from PermissionSet) */
+  permissions: z.array(z.string()).default([]),
+  
+  /** Whether this is a system-level operation (bypasses permission checks) */
+  isSystem: z.boolean().default(false),
+  
+  /** Raw access token (for external API call pass-through) */
+  accessToken: z.string().optional(),
+  
+  /** Database transaction handle */
+  transaction: z.unknown().optional(),
+  
+  /** Request trace ID (for distributed tracing) */
+  traceId: z.string().optional(),
+});
+
+export type ExecutionContext = z.infer<typeof ExecutionContextSchema>;

packages/spec/src/kernel/index.ts

@@ -20,3 +20,4 @@ export * from './service-registry.zod';
 export * from './startup-orchestrator.zod';
 export * from './plugin-registry.zod';
 export * from './plugin-security.zod';
+export * from './execution-context.zod';