@mxf-dev/core 2.0.5 → 3.1.0

package/src/services/orpar-memory/OrparMemoryCoordinator.ts

@@ -52,6 +52,7 @@
  */
 
 import { v4 as uuidv4 } from 'uuid';
+import type { Subscription } from 'rxjs';
 import { Logger } from '../../utils/Logger.js';
 import { EventBus } from '../../events/EventBus.js';
 import { Events, ControlLoopEvents } from '../../events/EventNames.js';
@@ -94,6 +95,8 @@ export class OrparMemoryCoordinator {
     private static instance: OrparMemoryCoordinator;
     private logger: Logger;
     private enabled: boolean = false;
+    private initialized: boolean = false;
+    private eventSubscriptions: Subscription[] = [];
 
     // Component services
     private phaseStrataRouter: PhaseStrataRouter;
@@ -112,6 +115,7 @@ export class OrparMemoryCoordinator {
         outcome: CycleOutcome;
         completedAt: number;
     }> = new Map();
+    private recentlyCompletedExpiryTimers: Map<string, NodeJS.Timeout> = new Map();
     private static readonly RECENTLY_COMPLETED_TTL_MS = 60_000;
 
     // Fix #2: Per-cycle locking to prevent race conditions
@@ -147,25 +151,36 @@ export class OrparMemoryCoordinator {
      * Initialize the coordinator and all component services
      */
     public initialize(): void {
+        if (this.initialized) {
+            return;
+        }
+
         this.enabled = isOrparMemoryIntegrationEnabled();
 
         if (this.enabled) {
-            // Initialize all component services
-            this.phaseStrataRouter.initialize();
-            this.surpriseAdapter.initialize();
-            this.phaseRewarder.initialize();
-            this.consolidationTrigger.initialize();
-            this.memoryOperations.initialize();
-
-            // Setup event listeners
-            this.setupEventListeners();
-
-            // Fix #3: Start stale cycle cleanup
-            this.startStaleCycleCleanup();
-
-            this.logger.info('[OrparMemoryCoordinator] Initialized with ORPAR-Memory integration ENABLED');
-            this.logger.info('[OrparMemoryCoordinator] All component services initialized');
+            try {
+                // Initialize all component services
+                this.phaseStrataRouter.initialize();
+                this.surpriseAdapter.initialize();
+                this.phaseRewarder.initialize();
+                this.consolidationTrigger.initialize();
+                this.memoryOperations.initialize();
+
+                // Setup event listeners
+                this.setupEventListeners();
+
+                // Fix #3: Start stale cycle cleanup
+                this.startStaleCycleCleanup();
+                this.initialized = true;
+
+                this.logger.info('[OrparMemoryCoordinator] Initialized with ORPAR-Memory integration ENABLED');
+                this.logger.info('[OrparMemoryCoordinator] All component services initialized');
+            } catch (error) {
+                this.shutdown();
+                throw error;
+            }
         } else {
+            this.initialized = true;
             this.logger.info(
                 '[OrparMemoryCoordinator] ORPAR-Memory integration is DISABLED. ' +
                 'Enable with ORPAR_MEMORY_INTEGRATION_ENABLED=true'
@@ -284,46 +299,58 @@ export class OrparMemoryCoordinator {
      */
     private setupEventListeners(): void {
         // Listen to control loop events to track cycle phases (server-side ControlLoop)
-        EventBus.server.on(ControlLoopEvents.OBSERVATION, (payload: any) => {
-            this.onPhaseEvent('observation', payload, 'controlLoop');
-        });
-
-        EventBus.server.on(ControlLoopEvents.REASONING, (payload: any) => {
-            this.onPhaseEvent('reasoning', payload, 'controlLoop');
-        });
-
-        EventBus.server.on(ControlLoopEvents.PLAN, (payload: any) => {
-            this.onPhaseEvent('planning', payload, 'controlLoop');
-        });
-
-        EventBus.server.on(ControlLoopEvents.EXECUTION, (payload: any) => {
-            this.onPhaseEvent('action', payload, 'controlLoop');
-        });
-
-        EventBus.server.on(ControlLoopEvents.REFLECTION, (payload: any) => {
-            this.onPhaseEvent('reflection', payload, 'controlLoop');
-        });
+        this.eventSubscriptions.push(
+            EventBus.server.on(ControlLoopEvents.OBSERVATION, payload => {
+                this.onPhaseEvent('observation', payload, 'controlLoop');
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(ControlLoopEvents.REASONING, payload => {
+                this.onPhaseEvent('reasoning', payload, 'controlLoop');
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(ControlLoopEvents.PLAN, payload => {
+                this.onPhaseEvent('planning', payload, 'controlLoop');
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(ControlLoopEvents.EXECUTION, payload => {
+                this.onPhaseEvent('action', payload, 'controlLoop');
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(ControlLoopEvents.REFLECTION, payload => {
+                this.onPhaseEvent('reflection', payload, 'controlLoop');
+            })
+        );
 
         // Listen to ORPAR tool events (agent-driven ORPAR tools)
-        EventBus.server.on(OrparEvents.OBSERVE, (payload: any) => {
-            this.onOrparToolEvent('observation', payload);
-        });
-
-        EventBus.server.on(OrparEvents.REASON, (payload: any) => {
-            this.onOrparToolEvent('reasoning', payload);
-        });
-
-        EventBus.server.on(OrparEvents.PLAN, (payload: any) => {
-            this.onOrparToolEvent('planning', payload);
-        });
-
-        EventBus.server.on(OrparEvents.ACT, (payload: any) => {
-            this.onOrparToolEvent('action', payload);
-        });
-
-        EventBus.server.on(OrparEvents.REFLECT, (payload: any) => {
-            this.onOrparToolEvent('reflection', payload);
-        });
+        this.eventSubscriptions.push(
+            EventBus.server.on(OrparEvents.OBSERVE, payload => {
+                this.onOrparToolEvent('observation', payload);
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(OrparEvents.REASON, payload => {
+                this.onOrparToolEvent('reasoning', payload);
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(OrparEvents.PLAN, payload => {
+                this.onOrparToolEvent('planning', payload);
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(OrparEvents.ACT, payload => {
+                this.onOrparToolEvent('action', payload);
+            })
+        );
+        this.eventSubscriptions.push(
+            EventBus.server.on(OrparEvents.REFLECT, payload => {
+                this.onOrparToolEvent('reflection', payload);
+            })
+        );
 
         // Fill phase memory usage from actual retrievals.
         //
@@ -333,19 +360,26 @@ export class OrparMemoryCoordinator {
         // therefore always empty, so PhaseWeightedRewarder returned no rewards and cycle
         // consolidation iterated zero memories. Subscribing here is what makes
         // phase-weighted rewards real.
-        EventBus.server.on(OrparMemoryEvents.PHASE_MEMORY_RETRIEVED, (payload: any) => {
-            if (this.enabled) {
-                this.onPhaseMemoryRetrieved(payload);
-            }
-        });
+        this.eventSubscriptions.push(
+            EventBus.server.on(OrparMemoryEvents.PHASE_MEMORY_RETRIEVED, payload => {
+                if (this.enabled) {
+                    this.onPhaseMemoryRetrieved(payload);
+                }
+            })
+        );
 
         // Listen for task completion to retroactively update rewards when
         // the ORPAR cycle completed before task_complete was called
-        EventBus.server.on(Events.Task.COMPLETED, (payload: any) => {
-            if (this.enabled) {
-                this.onTaskCompleted(payload);
-            }
-        });
+        this.eventSubscriptions.push(
+            EventBus.server.on(Events.Task.COMPLETED, (payload): Promise<void> | undefined => {
+                if (this.enabled) {
+                    // Return the persistence chain so EventBus.drain() keeps the
+                    // database open until retroactive Q-value updates finish.
+                    return this.onTaskCompleted(payload);
+                }
+                return undefined;
+            })
+        );
 
         this.logger.debug('[OrparMemoryCoordinator] Event listeners registered for ControlLoop, OrparTools, PhaseMemory, and TaskEvents');
     }
@@ -688,9 +722,7 @@ export class OrparMemoryCoordinator {
                 outcome,
                 completedAt: Date.now(),
             });
-            setTimeout(() => {
-                this.recentlyCompletedCycles.delete(cacheKey);
-            }, OrparMemoryCoordinator.RECENTLY_COMPLETED_TTL_MS);
+            this.scheduleRecentlyCompletedExpiry(cacheKey);
         }
 
         // Remove from active cycles
@@ -718,7 +750,7 @@ export class OrparMemoryCoordinator {
 
         // Already successful — no recalculation needed
         if (cached.outcome.success) {
-            this.recentlyCompletedCycles.delete(cacheKey);
+            this.clearRecentlyCompletedCycle(cacheKey);
             return;
         }
 
@@ -749,7 +781,30 @@ export class OrparMemoryCoordinator {
             );
         }
 
+        this.clearRecentlyCompletedCycle(cacheKey);
+    }
+
+    private scheduleRecentlyCompletedExpiry(cacheKey: string): void {
+        const existingTimer = this.recentlyCompletedExpiryTimers.get(cacheKey);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+
+        const expiryTimer = setTimeout(() => {
+            this.recentlyCompletedCycles.delete(cacheKey);
+            this.recentlyCompletedExpiryTimers.delete(cacheKey);
+        }, OrparMemoryCoordinator.RECENTLY_COMPLETED_TTL_MS);
+        expiryTimer.unref();
+        this.recentlyCompletedExpiryTimers.set(cacheKey, expiryTimer);
+    }
+
+    private clearRecentlyCompletedCycle(cacheKey: string): void {
         this.recentlyCompletedCycles.delete(cacheKey);
+        const expiryTimer = this.recentlyCompletedExpiryTimers.get(cacheKey);
+        if (expiryTimer) {
+            clearTimeout(expiryTimer);
+            this.recentlyCompletedExpiryTimers.delete(cacheKey);
+        }
     }
 
     // =========================================================================
@@ -1050,11 +1105,21 @@ export class OrparMemoryCoordinator {
         ].join('\n');
     }
 
-    /**
-     * Reset the coordinator (useful for testing)
-     */
-    public reset(): void {
+    /** Release all coordinator-owned process resources and runtime state. */
+    public shutdown(): void {
         this.enabled = false;
+        this.initialized = false;
+
+        for (const subscription of this.eventSubscriptions) {
+            subscription.unsubscribe();
+        }
+        this.eventSubscriptions = [];
+
+        for (const expiryTimer of this.recentlyCompletedExpiryTimers.values()) {
+            clearTimeout(expiryTimer);
+        }
+        this.recentlyCompletedExpiryTimers.clear();
+
         this.activeCycles.clear();
         this.recentlyCompletedCycles.clear();
 
@@ -1070,7 +1135,13 @@ export class OrparMemoryCoordinator {
         this.phaseRewarder.reset();
         this.consolidationTrigger.reset();
         this.memoryOperations.reset();
+    }
 
+    /**
+     * Reset the coordinator and its cached configuration (useful for testing).
+     */
+    public reset(): void {
+        this.shutdown();
         // Reset config
         resetOrparMemoryConfig();
     }

package/src/services/orpar-memory/SurpriseOrparAdapter.ts

@@ -35,6 +35,7 @@
  */
 
 import { createBaseEventPayload } from '../../schemas/EventPayloadSchema.js';
+import type { Subscription } from 'rxjs';
 import { Logger } from '../../utils/Logger.js';
 import { EventBus } from '../../events/EventBus.js';
 import {
@@ -87,6 +88,7 @@ export class SurpriseOrparAdapter {
     private logger: Logger;
     private enabled: boolean = false;
     private thresholds: SurpriseThresholds;
+    private graphSurpriseSubscription?: Subscription;
 
     // Track surprise momentum per agent/cycle
     private surpriseMomentum: Map<string, number[]> = new Map();
@@ -137,13 +139,18 @@ export class SurpriseOrparAdapter {
      * observation cycles.
      */
     private setupGraphSurpriseListener(): void {
+        if (this.graphSurpriseSubscription && !this.graphSurpriseSubscription.closed) {
+            return;
+        }
+        this.graphSurpriseSubscription = undefined;
+
         // Only set up listener if Knowledge Graph surprise detection is enabled
         if (!isKnowledgeGraphEnabled() || !isSurpriseDetectionEnabled()) {
             this.logger.debug('[SurpriseOrparAdapter] Knowledge Graph surprise integration disabled');
             return;
         }
 
-        EventBus.server.on(
+        this.graphSurpriseSubscription = EventBus.server.on(
             KnowledgeGraphEvents.HIGH_SURPRISE_RELATIONSHIP,
             (payload: { data: HighSurpriseRelationshipEventData; agentId?: AgentId; channelId?: ChannelId }) => {
                 this.handleGraphSurpriseEvent(payload);
@@ -567,6 +574,8 @@ export class SurpriseOrparAdapter {
      */
     public reset(): void {
         this.enabled = false;
+        this.graphSurpriseSubscription?.unsubscribe();
+        this.graphSurpriseSubscription = undefined;
         this.surpriseMomentum.clear();
     }
 }

package/src/types/ChannelContext.ts

@@ -272,12 +272,14 @@ export interface IChannelContextService {
      * @param channelId - Channel ID
      * @param context - Channel context to save
      * @param historyEntry - Optional history entry to record with this update
+     * @param expectedContextUpdatedAt - Persisted revision required for an update
      * @returns Observable of the saved context
      */
     saveContextToMemory(
         channelId: ChannelId,
         context: ChannelContextType,
-        historyEntry?: ChannelContextHistoryEntry
+        historyEntry?: ChannelContextHistoryEntry,
+        expectedContextUpdatedAt?: number
     ): Observable<ChannelContextType>;
     
     /**

package/src/types/EffectivenessTypes.ts

@@ -125,6 +125,9 @@ export interface TaskEffectivenessMetrics {
 export interface TaskDefinition {
     /** Unique task identifier */
     taskId: string;
+
+    /** Agent that owns this effectiveness record */
+    agentId: AgentId;
     
     /** Channel where task is executed */
     channelId: ChannelId;
@@ -267,9 +270,10 @@ export interface EffectivenessAnalytics {
 export interface TaskExecutionEvent {
     eventId: string;
     taskId: string;
+    agentId: AgentId;
+    channelId: ChannelId;
     timestamp: number;
     type: 'start' | 'step' | 'tool_use' | 'agent_join' | 'human_input' | 'error' | 'complete';
-    agentId?: AgentId;
     details: Record<string, any>;
 }
 
@@ -300,4 +304,4 @@ export interface EffectivenessConfig {
         enabled: boolean;
         defaultBaselineType?: 'human' | 'previous_run' | 'traditional_method';
     };
-}
+}

package/src/types/SystemLlmStanceTypes.ts

@@ -0,0 +1,162 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * 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.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * SystemLLM stance
+ *
+ * The stance decides how SystemLLM talks to agents, and in one case how it
+ * judges them:
+ *
+ * - `supportive` — the original behavior. Coordination hints are advisory and
+ *   nothing SystemLLM says asks for a reply.
+ * - `critical` — an honest skeptic. SystemLLM reads what agents did and
+ *   challenges completion claims, plans, and reflections it cannot square with
+ *   the evidence. The `systemllm-eval` completion judge demands evidence per
+ *   objective. If there is nothing wrong, it says nothing.
+ * - `hostile` — a test mode. SystemLLM issues plausible-but-wrong challenges
+ *   and hints so an operator can measure whether agents verify before acting
+ *   on system advice. Agents are told it is on; every hostile message is
+ *   tagged; it never touches a decision (judge verdicts, task assignment).
+ *
+ * The server default comes from `SYSTEMLLM_STANCE`; a channel can carry its
+ * own in `systemLlmStance`. These types are shared by the server (which
+ * applies the stance), the SDK (which tells agents about it), and the channel
+ * model (which persists it).
+ */
+
+/** Every stance, in the order the documentation lists them. */
+export const SYSTEMLLM_STANCES = ['supportive', 'critical', 'hostile'] as const;
+
+export type SystemLlmStance = typeof SYSTEMLLM_STANCES[number];
+
+/** The stance when nothing sets one: today's behavior. */
+export const DEFAULT_SYSTEMLLM_STANCE: SystemLlmStance = 'supportive';
+
+/**
+ * The ceiling when nothing sets one: no ceiling. `SYSTEMLLM_STANCE_MAX` lowers
+ * it server-wide so that no channel, whatever its own stance says, goes
+ * above it — `critical` keeps hostile out of production, `supportive` turns
+ * challenges off everywhere without touching channel documents.
+ */
+export const DEFAULT_SYSTEMLLM_STANCE_CEILING: SystemLlmStance = 'hostile';
+
+/** Stances from least to most adversarial; the index is the ordering. */
+const STANCE_RANK: Record<SystemLlmStance, number> = { supportive: 0, critical: 1, hostile: 2 };
+
+/** Whether `stance` is at or below `ceiling`. */
+export function isStanceWithin(stance: SystemLlmStance, ceiling: SystemLlmStance): boolean {
+    return STANCE_RANK[stance] <= STANCE_RANK[ceiling];
+}
+
+/** `stance`, lowered to `ceiling` when it is above it. */
+export function capStance(stance: SystemLlmStance, ceiling: SystemLlmStance): SystemLlmStance {
+    return isStanceWithin(stance, ceiling) ? stance : ceiling;
+}
+
+export function isSystemLlmStance(value: unknown): value is SystemLlmStance {
+    return typeof value === 'string' && (SYSTEMLLM_STANCES as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * Parse a stance from configuration text.
+ *
+ * @param value - Raw value, for example from an environment variable or a channel document
+ * @param sourceName - What the value came from, for the error message (`SYSTEMLLM_STANCE`, `systemLlmStance`)
+ * @throws Error when the value is blank or is not one of the stances
+ */
+export function parseSystemLlmStance(value: string, sourceName: string): SystemLlmStance {
+    const trimmed = value.trim().toLowerCase();
+    if (trimmed.length === 0) {
+        throw new Error(
+            `${sourceName} is set but blank. Name a stance (${SYSTEMLLM_STANCES.join(', ')}), or remove it.`
+        );
+    }
+    if (!isSystemLlmStance(trimmed)) {
+        throw new Error(
+            `Unsupported ${sourceName} '${value}'. Expected one of: ${SYSTEMLLM_STANCES.join(', ')}`
+        );
+    }
+    return trimmed;
+}
+
+/**
+ * What prompted a challenge.
+ *
+ * - `completion_claim` — the agent called `task_complete` reporting success
+ * - `plan_posted` — the agent recorded a plan with `orpar_plan`
+ * - `reflection_success` — the agent recorded a reflection with `orpar_reflect`
+ *   that did not say expectations were missed
+ */
+export const CHALLENGE_TRIGGERS = ['completion_claim', 'plan_posted', 'reflection_success'] as const;
+
+export type ChallengeTrigger = typeof CHALLENGE_TRIGGERS[number];
+
+/** How a challenge reached the agent. */
+export type ChallengeDelivery = 'tool_result' | 'channel_message';
+
+/** One thing SystemLLM disputes. */
+export interface SystemLlmChallengePoint {
+    /** The agent's claim, quoted or paraphrased. */
+    claim: string;
+    /** Why the evidence does not support it. */
+    problem: string;
+    /** What would settle it: a tool result, a file, a message. */
+    evidenceNeeded: string;
+}
+
+/** A challenge SystemLLM issued to one agent about one task. */
+export interface SystemLlmChallenge {
+    id: string;
+    channelId: string;
+    agentId: string;
+    taskId: string;
+    trigger: ChallengeTrigger;
+    stance: Exclude<SystemLlmStance, 'supportive'>;
+    delivery: ChallengeDelivery;
+    summary: string;
+    points: SystemLlmChallengePoint[];
+    createdAt: number;
+}
+
+/**
+ * Record kept on `task.metadata.systemLlmChallenges` so a trigger is
+ * challenged at most once per task, and so the history is auditable.
+ */
+export interface SystemLlmChallengeRecord {
+    id: string;
+    trigger: ChallengeTrigger;
+    stance: SystemLlmChallenge['stance'];
+    delivery: ChallengeDelivery;
+    summary: string;
+    points: SystemLlmChallengePoint[];
+    createdAt: number;
+}
+
+/** Key under `task.metadata` where challenge records are pushed. */
+export const TASK_METADATA_CHALLENGES_KEY = 'systemLlmChallenges';
+
+/**
+ * `context.messageType` on a channel message that carries a challenge.
+ * The SDK treats these as "answer this", unlike `coordination_suggestion`.
+ */
+export const SYSTEMLLM_CHALLENGE_MESSAGE_TYPE = 'systemllm_challenge';
+
+/** `status` returned by `task_complete` when the claim was challenged instead of accepted. */
+export const TASK_COMPLETION_CHALLENGED_STATUS = 'completion_challenged';

package/src/types/TaskCompletionTypes.ts

@@ -46,6 +46,7 @@ export interface SystemLLMEvalCompletion {
     objectives: string[];              // What needs to be achieved
     evaluationInterval: number;        // How often to check (ms)
     confidenceThreshold: number;       // 0-1, required confidence
+    maxEvaluations: number;             // Hard provider-call budget
 }
 
 export interface OutputBasedCompletion {
@@ -67,7 +68,7 @@ export interface TimeBasedCompletion {
 export interface EventBasedCompletion {
     type: 'event-based';
     eventName: string;                 // Event that triggers completion
-    eventData?: Record<string, any>;   // Optional data to match
+    eventData?: Record<string, unknown>;   // Optional data to match
 }
 
 export interface ConsensusCompletion {
@@ -79,7 +80,7 @@ export interface ConsensusCompletion {
 export interface CustomCompletion {
     type: 'custom';
     evaluatorFunction: string;         // Name of custom evaluator
-    parameters?: Record<string, any>;
+    parameters?: Record<string, unknown>;
 }
 
 export type TaskCompletionCriteria = 
@@ -98,12 +99,9 @@ export interface TaskCompletionConfig {
     // Primary completion strategy
     primary: TaskCompletionCriteria;
     
-    // Fallback strategies if primary doesn't complete
-    fallbacks?: TaskCompletionCriteria[];
-    
-    // Global timeout (applies to all strategies)
+    // Optional hard deadline. A deadline may fail a task; it can never manufacture completion.
     absoluteTimeout?: number;
-    timeoutBehavior?: 'complete' | 'fail' | 'alert';
+    timeoutBehavior?: 'fail';
     
     // Whether agents can still manually complete
     allowManualCompletion?: boolean;
@@ -111,6 +109,8 @@ export interface TaskCompletionConfig {
 
 export interface TaskMonitoringState {
     taskId: string;
+    channelId: string;
+    assignedAgentIds: string[];
     startTime: number;
     lastActivityTime: number;
     activityCount: number;
@@ -125,7 +125,7 @@ export interface TaskMonitoringState {
         toolCalls: Array<{
             agentId: string;
             toolName: string;
-            result: any;
+            result: unknown;
             timestamp: number;
         }>;
         planProgress?: {
@@ -160,4 +160,4 @@ export interface TaskCompletionEvent {
     confidence: number;
     reason: string;
     duration: number;
-}
+}

package/src/types/TaskTypes.ts

@@ -77,6 +77,7 @@ export interface ChannelTask {
     // Task coordination
     coordinationMode?: 'independent' | 'collaborative' | 'sequential' | 'hierarchical';
     leadAgentId?: AgentId;             // Primary coordinator for collaborative tasks
+    completionAgentId?: AgentId;       // Agent authorized to report the terminal outcome
     
     // Agent selection criteria
     agentSelectionCriteria?: {
@@ -147,6 +148,7 @@ export interface CreateTaskRequest {
     // Task coordination
     coordinationMode?: 'independent' | 'collaborative' | 'sequential' | 'hierarchical';
     leadAgentId?: AgentId;             // Primary coordinator for collaborative tasks
+    completionAgentId?: AgentId;       // Agent authorized to report the terminal outcome
     
     // Agent selection criteria
     agentSelectionCriteria?: {
@@ -176,6 +178,16 @@ export interface UpdateTaskRequest {
     tags?: string[];
 }
 
+/**
+ * Fields that may be changed without performing a task lifecycle transition.
+ * Status and assignment changes go through dedicated operations so actor
+ * authorization and legal-state predicates remain on the database write.
+ */
+export type NonLifecycleTaskUpdateRequest = Omit<
+    UpdateTaskRequest,
+    'status' | 'assignedAgentId'
+>;
+
 /**
  * Agent assignment analysis from SystemLLM
  */
@@ -275,7 +287,6 @@ export interface TaskOrchestrationConfig {
     // SystemLLM integration
     enableLlmAssignment: boolean;
     llmConfidenceThreshold: number;     // Minimum confidence for LLM assignments
-    fallbackStrategy: AssignmentStrategy;
     
     // Coordination behavior
     enableTaskDependencies: boolean;