yaml-flow 2.8.0 → 3.1.0

package/dist/{types-C2lOwquM.d.cts → types-BwvgvlOO.d.cts}

@@ -1,4 +1,4 @@
-import { G as GraphConfig, c as ExecutionState, T as TaskConfig, l as TaskState } from './types-DAI_a2as.cjs';
+import { G as GraphConfig, c as ExecutionState, T as TaskConfig, e as GraphEngineStore } from './types-DEj7OakX.cjs';
 
 /**
  * Continuous Event Graph — Types
@@ -77,7 +77,7 @@ interface NodeInfo {
     /** The task configuration */
     config: TaskConfig;
     /** The current runtime state */
-    state: TaskState;
+    state: GraphEngineStore;
 }
 interface LiveGraphSnapshot {
     /** Schema version for forward compatibility */

package/dist/{types-mS_pPftm.d.ts → types-ClRA8hzC.d.ts}

@@ -1,4 +1,4 @@
-import { G as GraphConfig, c as ExecutionState, T as TaskConfig, l as TaskState } from './types-DAI_a2as.js';
+import { G as GraphConfig, c as ExecutionState, T as TaskConfig, e as GraphEngineStore } from './types-DEj7OakX.js';
 
 /**
  * Continuous Event Graph — Types
@@ -77,7 +77,7 @@ interface NodeInfo {
     /** The task configuration */
     config: TaskConfig;
     /** The current runtime state */
-    state: TaskState;
+    state: GraphEngineStore;
 }
 interface LiveGraphSnapshot {
     /** Schema version for forward compatibility */

package/dist/{types-DAI_a2as.d.ts → types-DEj7OakX.d.cts}

@@ -16,6 +16,8 @@ interface GraphSettings {
     conflict_strategy?: ConflictStrategy;
     /** Execution mode */
     execution_mode?: ExecutionMode;
+    /** Default refresh strategy for all tasks (default: 'data-changed') */
+    refreshStrategy?: RefreshStrategy;
     /** Goal outputs — used with 'goal-reached' completion */
     goal?: string[];
     /** Max total scheduler iterations (safety limit, default: 1000) */
@@ -34,6 +36,8 @@ interface TaskConfig {
     on_failure?: string[];
     /** Task execution method (informational — driver concern) */
     method?: string;
+    /** Named task handler references — looked up in the handler registry at dispatch time */
+    taskHandlers?: string[];
     /** Arbitrary task configuration (driver concern) */
     config?: Record<string, unknown>;
     /** Task priority (higher = preferred in conflict resolution) */
@@ -46,8 +50,12 @@ interface TaskConfig {
     estimatedResources?: Record<string, number>;
     /** Retry configuration */
     retry?: TaskRetryConfig;
-    /** Repeatable task configuration */
-    repeatable?: boolean | RepeatableConfig;
+    /** Refresh strategy — controls when a completed task re-runs (default: 'data-changed') */
+    refreshStrategy?: RefreshStrategy;
+    /** Refresh interval in seconds — only used with 'time-based' strategy */
+    refreshInterval?: number;
+    /** Max executions cap (safety limit, optional) */
+    maxExecutions?: number;
     /** Circuit breaker: max executions before breaking */
     circuit_breaker?: TaskCircuitBreakerConfig;
     /** Description */
@@ -69,10 +77,6 @@ interface TaskRetryConfig {
     delay_ms?: number;
     backoff_multiplier?: number;
 }
-interface RepeatableConfig {
-    /** Max times this task can repeat (undefined = unlimited) */
-    max?: number;
-}
 interface TaskCircuitBreakerConfig {
     /** Max executions before injecting break tokens */
     max_executions: number;
@@ -83,7 +87,7 @@ interface ExecutionState {
     /** Current status of the execution */
     status: ExecutionStatus;
     /** Task states keyed by task name */
-    tasks: Record<string, TaskState>;
+    tasks: Record<string, GraphEngineStore>;
     /** Tokens currently available in the system */
     availableOutputs: string[];
     /** Stuck detection result */
@@ -100,11 +104,17 @@ interface ExecutionConfig {
     conflictStrategy: ConflictStrategy;
     completionStrategy: CompletionStrategy;
 }
-interface TaskState {
+interface GraphEngineStore {
     status: TaskStatus;
     executionCount: number;
     retryCount: number;
     lastEpoch: number;
+    /** Hash of this task's last output (for data-changed strategy) */
+    lastDataHash?: string;
+    /** The task's last output data payload */
+    data?: Record<string, unknown>;
+    /** Per-require token: the data hash consumed on last run */
+    lastConsumedHashes?: Record<string, string>;
     startedAt?: string;
     completedAt?: string;
     failedAt?: string;
@@ -124,7 +134,7 @@ interface StuckDetection {
     outputs_unresolvable: string[];
     tasks_blocked: string[];
 }
-type GraphEvent = TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | TaskProgressEvent | InjectTokensEvent | AgentActionEvent | TaskCreationEvent;
+type GraphEvent = TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | TaskProgressEvent | TaskRestartEvent | InjectTokensEvent | AgentActionEvent | TaskCreationEvent;
 interface TaskStartedEvent {
     type: 'task-started';
     taskName: string;
@@ -138,6 +148,8 @@ interface TaskCompletedEvent {
     result?: string;
     /** Data payload from task execution */
     data?: Record<string, unknown>;
+    /** Content hash of the output — used by 'data-changed' refresh strategy */
+    dataHash?: string;
     timestamp: string;
     executionId?: string;
 }
@@ -156,6 +168,12 @@ interface TaskProgressEvent {
     timestamp: string;
     executionId?: string;
 }
+interface TaskRestartEvent {
+    type: 'task-restart';
+    taskName: string;
+    timestamp: string;
+    executionId?: string;
+}
 interface InjectTokensEvent {
     type: 'inject-tokens';
     tokens: string[];
@@ -194,5 +212,6 @@ type ExecutionStatus = 'created' | 'running' | 'paused' | 'stopped' | 'completed
 type CompletionStrategy = 'all-tasks-done' | 'all-outputs-done' | 'only-resolved' | 'goal-reached' | 'manual';
 type ExecutionMode = 'dependency-mode' | 'eligibility-mode';
 type ConflictStrategy = 'alphabetical' | 'priority-first' | 'duration-first' | 'cost-optimized' | 'resource-aware' | 'random-select' | 'user-choice' | 'parallel-all' | 'skip-conflicts' | 'round-robin';
+type RefreshStrategy = 'data-changed' | 'epoch-changed' | 'time-based' | 'manual' | 'once';
 
-export type { AgentActionEvent as A, CompletionStrategy as C, ExecutionConfig as E, GraphConfig as G, InjectTokensEvent as I, RepeatableConfig as R, SchedulerResult as S, TaskConfig as T, ConflictStrategy as a, ExecutionMode as b, ExecutionState as c, ExecutionStatus as d, GraphEvent as e, GraphSettings as f, StuckDetection as g, TaskCompletedEvent as h, TaskCreationEvent as i, TaskFailedEvent as j, TaskStartedEvent as k, TaskState as l, TaskStatus as m, TaskCircuitBreakerConfig as n, TaskMessage as o, TaskProgressEvent as p, TaskRetryConfig as q };
+export type { AgentActionEvent as A, CompletionStrategy as C, ExecutionConfig as E, GraphConfig as G, InjectTokensEvent as I, RefreshStrategy as R, SchedulerResult as S, TaskConfig as T, ConflictStrategy as a, ExecutionMode as b, ExecutionState as c, ExecutionStatus as d, GraphEngineStore as e, GraphEvent as f, GraphSettings as g, StuckDetection as h, TaskCompletedEvent as i, TaskCreationEvent as j, TaskFailedEvent as k, TaskStartedEvent as l, TaskStatus as m, TaskCircuitBreakerConfig as n, TaskMessage as o, TaskProgressEvent as p, TaskRestartEvent as q, TaskRetryConfig as r };

package/dist/{types-DAI_a2as.d.cts → types-DEj7OakX.d.ts}

@@ -16,6 +16,8 @@ interface GraphSettings {
     conflict_strategy?: ConflictStrategy;
     /** Execution mode */
     execution_mode?: ExecutionMode;
+    /** Default refresh strategy for all tasks (default: 'data-changed') */
+    refreshStrategy?: RefreshStrategy;
     /** Goal outputs — used with 'goal-reached' completion */
     goal?: string[];
     /** Max total scheduler iterations (safety limit, default: 1000) */
@@ -34,6 +36,8 @@ interface TaskConfig {
     on_failure?: string[];
     /** Task execution method (informational — driver concern) */
     method?: string;
+    /** Named task handler references — looked up in the handler registry at dispatch time */
+    taskHandlers?: string[];
     /** Arbitrary task configuration (driver concern) */
     config?: Record<string, unknown>;
     /** Task priority (higher = preferred in conflict resolution) */
@@ -46,8 +50,12 @@ interface TaskConfig {
     estimatedResources?: Record<string, number>;
     /** Retry configuration */
     retry?: TaskRetryConfig;
-    /** Repeatable task configuration */
-    repeatable?: boolean | RepeatableConfig;
+    /** Refresh strategy — controls when a completed task re-runs (default: 'data-changed') */
+    refreshStrategy?: RefreshStrategy;
+    /** Refresh interval in seconds — only used with 'time-based' strategy */
+    refreshInterval?: number;
+    /** Max executions cap (safety limit, optional) */
+    maxExecutions?: number;
     /** Circuit breaker: max executions before breaking */
     circuit_breaker?: TaskCircuitBreakerConfig;
     /** Description */
@@ -69,10 +77,6 @@ interface TaskRetryConfig {
     delay_ms?: number;
     backoff_multiplier?: number;
 }
-interface RepeatableConfig {
-    /** Max times this task can repeat (undefined = unlimited) */
-    max?: number;
-}
 interface TaskCircuitBreakerConfig {
     /** Max executions before injecting break tokens */
     max_executions: number;
@@ -83,7 +87,7 @@ interface ExecutionState {
     /** Current status of the execution */
     status: ExecutionStatus;
     /** Task states keyed by task name */
-    tasks: Record<string, TaskState>;
+    tasks: Record<string, GraphEngineStore>;
     /** Tokens currently available in the system */
     availableOutputs: string[];
     /** Stuck detection result */
@@ -100,11 +104,17 @@ interface ExecutionConfig {
     conflictStrategy: ConflictStrategy;
     completionStrategy: CompletionStrategy;
 }
-interface TaskState {
+interface GraphEngineStore {
     status: TaskStatus;
     executionCount: number;
     retryCount: number;
     lastEpoch: number;
+    /** Hash of this task's last output (for data-changed strategy) */
+    lastDataHash?: string;
+    /** The task's last output data payload */
+    data?: Record<string, unknown>;
+    /** Per-require token: the data hash consumed on last run */
+    lastConsumedHashes?: Record<string, string>;
     startedAt?: string;
     completedAt?: string;
     failedAt?: string;
@@ -124,7 +134,7 @@ interface StuckDetection {
     outputs_unresolvable: string[];
     tasks_blocked: string[];
 }
-type GraphEvent = TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | TaskProgressEvent | InjectTokensEvent | AgentActionEvent | TaskCreationEvent;
+type GraphEvent = TaskStartedEvent | TaskCompletedEvent | TaskFailedEvent | TaskProgressEvent | TaskRestartEvent | InjectTokensEvent | AgentActionEvent | TaskCreationEvent;
 interface TaskStartedEvent {
     type: 'task-started';
     taskName: string;
@@ -138,6 +148,8 @@ interface TaskCompletedEvent {
     result?: string;
     /** Data payload from task execution */
     data?: Record<string, unknown>;
+    /** Content hash of the output — used by 'data-changed' refresh strategy */
+    dataHash?: string;
     timestamp: string;
     executionId?: string;
 }
@@ -156,6 +168,12 @@ interface TaskProgressEvent {
     timestamp: string;
     executionId?: string;
 }
+interface TaskRestartEvent {
+    type: 'task-restart';
+    taskName: string;
+    timestamp: string;
+    executionId?: string;
+}
 interface InjectTokensEvent {
     type: 'inject-tokens';
     tokens: string[];
@@ -194,5 +212,6 @@ type ExecutionStatus = 'created' | 'running' | 'paused' | 'stopped' | 'completed
 type CompletionStrategy = 'all-tasks-done' | 'all-outputs-done' | 'only-resolved' | 'goal-reached' | 'manual';
 type ExecutionMode = 'dependency-mode' | 'eligibility-mode';
 type ConflictStrategy = 'alphabetical' | 'priority-first' | 'duration-first' | 'cost-optimized' | 'resource-aware' | 'random-select' | 'user-choice' | 'parallel-all' | 'skip-conflicts' | 'round-robin';
+type RefreshStrategy = 'data-changed' | 'epoch-changed' | 'time-based' | 'manual' | 'once';
 
-export type { AgentActionEvent as A, CompletionStrategy as C, ExecutionConfig as E, GraphConfig as G, InjectTokensEvent as I, RepeatableConfig as R, SchedulerResult as S, TaskConfig as T, ConflictStrategy as a, ExecutionMode as b, ExecutionState as c, ExecutionStatus as d, GraphEvent as e, GraphSettings as f, StuckDetection as g, TaskCompletedEvent as h, TaskCreationEvent as i, TaskFailedEvent as j, TaskStartedEvent as k, TaskState as l, TaskStatus as m, TaskCircuitBreakerConfig as n, TaskMessage as o, TaskProgressEvent as p, TaskRetryConfig as q };
+export type { AgentActionEvent as A, CompletionStrategy as C, ExecutionConfig as E, GraphConfig as G, InjectTokensEvent as I, RefreshStrategy as R, SchedulerResult as S, TaskConfig as T, ConflictStrategy as a, ExecutionMode as b, ExecutionState as c, ExecutionStatus as d, GraphEngineStore as e, GraphEvent as f, GraphSettings as g, StuckDetection as h, TaskCompletedEvent as i, TaskCreationEvent as j, TaskFailedEvent as k, TaskStartedEvent as l, TaskStatus as m, TaskCircuitBreakerConfig as n, TaskMessage as o, TaskProgressEvent as p, TaskRestartEvent as q, TaskRetryConfig as r };

package/dist/validate-DEZ2Ymdb.d.ts

@@ -0,0 +1,53 @@
+import { G as GraphConfig } from './types-DEj7OakX.js';
+
+/**
+ * Event Graph — Semantic Graph Validation
+ *
+ * Validates the logical correctness of a static graph configuration.
+ * Unlike validateGraphConfig() which checks JSON structure, this checks:
+ *   - Dangling requires (tokens no task produces)
+ *   - Circular dependencies
+ *   - Provide conflicts (multiple tasks producing same token)
+ *   - Unreachable goal tokens
+ *   - Dead-end tasks (no provides)
+ *   - Self-dependencies
+ *   - Orphaned tasks (disconnected from the graph)
+ *
+ * Pure function — config in, diagnostics out.
+ */
+
+type IssueSeverity = 'error' | 'warning' | 'info';
+interface GraphIssue {
+    /** Severity: error = will break execution, warning = may cause problems, info = notable */
+    severity: IssueSeverity;
+    /** Machine-readable issue code */
+    code: string;
+    /** Human-readable description */
+    message: string;
+    /** Affected task names (if applicable) */
+    tasks?: string[];
+    /** Affected tokens (if applicable) */
+    tokens?: string[];
+}
+interface GraphValidationResult {
+    /** true if no errors (warnings/info are allowed) */
+    valid: boolean;
+    /** All issues found */
+    issues: GraphIssue[];
+    /** Just the errors */
+    errors: GraphIssue[];
+    /** Just the warnings */
+    warnings: GraphIssue[];
+}
+/**
+ * Validate the semantic correctness of a static event-graph configuration.
+ *
+ * Checks for logical issues that would cause execution failures, stuck states,
+ * or unexpected behavior. Does NOT check JSON structure (use validateGraphConfig for that).
+ *
+ * @param graph - The event-graph configuration to validate
+ * @returns Validation result with categorized issues
+ */
+declare function validateGraph(graph: GraphConfig): GraphValidationResult;
+
+export { type GraphIssue as G, type IssueSeverity as I, type GraphValidationResult as a, validateGraph as v };

package/dist/validate-DqKTZg_o.d.cts

@@ -0,0 +1,53 @@
+import { G as GraphConfig } from './types-DEj7OakX.cjs';
+
+/**
+ * Event Graph — Semantic Graph Validation
+ *
+ * Validates the logical correctness of a static graph configuration.
+ * Unlike validateGraphConfig() which checks JSON structure, this checks:
+ *   - Dangling requires (tokens no task produces)
+ *   - Circular dependencies
+ *   - Provide conflicts (multiple tasks producing same token)
+ *   - Unreachable goal tokens
+ *   - Dead-end tasks (no provides)
+ *   - Self-dependencies
+ *   - Orphaned tasks (disconnected from the graph)
+ *
+ * Pure function — config in, diagnostics out.
+ */
+
+type IssueSeverity = 'error' | 'warning' | 'info';
+interface GraphIssue {
+    /** Severity: error = will break execution, warning = may cause problems, info = notable */
+    severity: IssueSeverity;
+    /** Machine-readable issue code */
+    code: string;
+    /** Human-readable description */
+    message: string;
+    /** Affected task names (if applicable) */
+    tasks?: string[];
+    /** Affected tokens (if applicable) */
+    tokens?: string[];
+}
+interface GraphValidationResult {
+    /** true if no errors (warnings/info are allowed) */
+    valid: boolean;
+    /** All issues found */
+    issues: GraphIssue[];
+    /** Just the errors */
+    errors: GraphIssue[];
+    /** Just the warnings */
+    warnings: GraphIssue[];
+}
+/**
+ * Validate the semantic correctness of a static event-graph configuration.
+ *
+ * Checks for logical issues that would cause execution failures, stuck states,
+ * or unexpected behavior. Does NOT check JSON structure (use validateGraphConfig for that).
+ *
+ * @param graph - The event-graph configuration to validate
+ * @returns Validation result with categorized issues
+ */
+declare function validateGraph(graph: GraphConfig): GraphValidationResult;
+
+export { type GraphIssue as G, type IssueSeverity as I, type GraphValidationResult as a, validateGraph as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "2.8.0",
+  "version": "3.1.0",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",

package/schema/event-graph.schema.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/yaml-flow/schema/event-graph.json",
+  "title": "Event Graph Configuration",
+  "description": "Schema for stateless event-graph (DAG) workflow definitions in yaml-flow",
+  "type": "object",
+  "required": ["settings", "tasks"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Optional graph identifier"
+    },
+    "settings": {
+      "$ref": "#/definitions/settings"
+    },
+    "tasks": {
+      "type": "object",
+      "description": "Task definitions keyed by name",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/definitions/task"
+      }
+    }
+  },
+
+  "definitions": {
+
+    "settings": {
+      "type": "object",
+      "required": ["completion"],
+      "properties": {
+        "completion": {
+          "type": "string",
+          "enum": [
+            "all-tasks-done",
+            "all-outputs-done",
+            "only-resolved",
+            "goal-reached",
+            "manual"
+          ],
+          "description": "Completion strategy"
+        },
+        "conflict_strategy": {
+          "type": "string",
+          "enum": [
+            "alphabetical",
+            "priority-first",
+            "duration-first",
+            "cost-optimized",
+            "resource-aware",
+            "random-select",
+            "user-choice",
+            "parallel-all",
+            "skip-conflicts",
+            "round-robin"
+          ],
+          "description": "Conflict resolution strategy"
+        },
+        "execution_mode": {
+          "type": "string",
+          "enum": ["dependency-mode", "eligibility-mode"],
+          "description": "Execution mode"
+        },
+        "goal": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "description": "Goal outputs — required when completion is 'goal-reached'"
+        },
+        "max_iterations": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Max scheduler iterations (safety limit, default: 1000)"
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Timeout in ms (declared for drivers, not enforced by pure engine)"
+        },
+        "refreshStrategy": {
+          "$ref": "#/definitions/refresh_strategy",
+          "description": "Default refresh strategy for all tasks (default: 'data-changed')"
+        }
+      },
+      "additionalProperties": false,
+      "if": {
+        "properties": { "completion": { "const": "goal-reached" } }
+      },
+      "then": {
+        "required": ["completion", "goal"]
+      }
+    },
+
+    "task": {
+      "type": "object",
+      "required": ["provides"],
+      "properties": {
+        "requires": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tokens this task needs to become eligible"
+        },
+        "provides": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tokens this task produces on successful completion"
+        },
+        "on": {
+          "type": "object",
+          "description": "Conditional provides based on handler result key",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "on_failure": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tokens to inject when this task fails"
+        },
+        "method": {
+          "type": "string",
+          "description": "Task execution method (informational — driver concern)"
+        },
+        "config": {
+          "type": "object",
+          "description": "Arbitrary task configuration (driver concern)"
+        },
+        "priority": {
+          "type": "number",
+          "description": "Higher = preferred in conflict resolution"
+        },
+        "estimatedDuration": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Estimated duration in ms (used by duration-first strategy)"
+        },
+        "estimatedCost": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Estimated cost (used by cost-optimized strategy)"
+        },
+        "estimatedResources": {
+          "type": "object",
+          "additionalProperties": { "type": "number" },
+          "description": "Resource requirements (used by resource-aware strategy)"
+        },
+        "retry": {
+          "$ref": "#/definitions/task_retry"
+        },
+        "refreshStrategy": {
+          "$ref": "#/definitions/refresh_strategy",
+          "description": "Task-level refresh strategy (overrides settings default)"
+        },
+        "refreshInterval": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Interval in seconds for time-based refresh strategy"
+        },
+        "maxExecutions": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of times this task can execute"
+        },
+        "circuit_breaker": {
+          "$ref": "#/definitions/task_circuit_breaker"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "inference": {
+          "$ref": "#/definitions/inference_hints"
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "task_retry": {
+      "type": "object",
+      "required": ["max_attempts"],
+      "properties": {
+        "max_attempts": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum retry attempts"
+        },
+        "delay_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Delay between retries in ms"
+        },
+        "backoff_multiplier": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Backoff multiplier (e.g., 2 for exponential)"
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "refresh_strategy": {
+      "type": "string",
+      "enum": ["data-changed", "epoch-changed", "time-based", "manual", "once"],
+      "description": "Strategy for determining when a completed task should re-run"
+    },
+
+    "task_circuit_breaker": {
+      "type": "object",
+      "required": ["max_executions", "on_break"],
+      "properties": {
+        "max_executions": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Max executions before breaker trips"
+        },
+        "on_break": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "description": "Tokens to inject when breaker trips"
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "inference_hints": {
+      "type": "object",
+      "description": "LLM inference hints — opt-in metadata for AI-assisted completion detection",
+      "properties": {
+        "criteria": {
+          "type": "string",
+          "description": "Human-readable completion criteria"
+        },
+        "keywords": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Keywords to help the LLM understand the domain"
+        },
+        "suggestedChecks": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Suggested checks for verification"
+        },
+        "autoDetectable": {
+          "type": "boolean",
+          "description": "Whether the LLM should attempt to auto-detect completion (default: false)"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}