@portel/photon-core 2.9.3 → 2.10.0

package/src/schema-extractor.ts

@@ -10,7 +10,7 @@
 
 import * as fs from 'fs/promises';
 import * as ts from 'typescript';
-import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam, SettingsSchema, SettingsProperty } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam, SettingsSchema, SettingsProperty, NotificationSubscription } from './types.js';
 import { parseDuration, parseRate } from './utils/duration.js';
 import { builtinRegistry, type MiddlewareDeclaration } from './middleware.js';
 
@@ -22,6 +22,8 @@ export interface ExtractedMetadata {
   settingsSchema?: SettingsSchema;
   /** @deprecated Configuration schema from configure() method */
   configSchema?: ConfigSchema;
+  /** Notification subscription from @notify-on tag */
+  notificationSubscriptions?: NotificationSubscription;
 }
 
 /**
@@ -59,6 +61,9 @@ export class SchemaExtractor {
       params: [],
     };
 
+    // Notification subscriptions tracking (from @notify-on tag)
+    let notificationSubscriptions: NotificationSubscription | undefined;
+
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -75,7 +80,7 @@ export class SchemaExtractor {
       );
 
       // Helper to process a method declaration
-      const processMethod = (member: ts.MethodDeclaration) => {
+      const processMethod = (member: ts.MethodDeclaration, isStatefulClass: boolean = false) => {
         const methodName = member.name.getText(sourceFile);
 
         // Skip private methods (prefixed with _)
@@ -135,10 +140,15 @@ export class SchemaExtractor {
         const paramDocs = this.extractParamDocs(jsdoc);
         const paramConstraints = this.extractParamConstraints(jsdoc);
 
+        // Track which paramDocs/constraints were matched for fail-safe handling
+        const matchedDocs = new Set<string>();
+        const matchedConstraints = new Set<string>();
+
         // Merge descriptions and constraints into properties
         Object.keys(properties).forEach(key => {
           if (paramDocs.has(key)) {
             properties[key].description = paramDocs.get(key);
+            matchedDocs.add(key);
           }
 
           // Apply TypeScript-extracted metadata (before JSDoc, so JSDoc can override)
@@ -151,9 +161,54 @@ export class SchemaExtractor {
           if (paramConstraints.has(key)) {
             const constraints = paramConstraints.get(key)!;
             this.applyConstraints(properties[key], constraints);
+            matchedConstraints.add(key);
           }
         });
 
+        // Fail-safe: Handle mismatched parameter names from JSDoc
+        // If a @param name doesn't match any actual parameter, try fuzzy matching
+        const unmatchedDocs = Array.from(paramDocs.entries()).filter(([name]) => !matchedDocs.has(name));
+        if (unmatchedDocs.length > 0) {
+          const propKeys = Object.keys(properties);
+
+          // If there's only one parameter and one unmatched doc, assume it belongs to that parameter
+          if (propKeys.length === 1 && unmatchedDocs.length === 1) {
+            const paramKey = propKeys[0];
+            const [docName, docValue] = unmatchedDocs[0];
+            if (!properties[paramKey].description) {
+              properties[paramKey].description = `${docName}: ${docValue}`;
+              console.warn(
+                `Parameter name mismatch in JSDoc: @param ${docName} doesn't match ` +
+                `function parameter "${paramKey}". Using description from @param ${docName}.`
+              );
+            }
+          } else if (unmatchedDocs.length > 0) {
+            // Log warning for other mismatches (multiple parameters or multiple unmatched docs)
+            unmatchedDocs.forEach(([docName]) => {
+              console.warn(
+                `Parameter name mismatch in JSDoc: @param ${docName} doesn't match any function parameter. ` +
+                `Available parameters: ${propKeys.join(', ')}. Consider updating @param tag.`
+              );
+            });
+          }
+        }
+
+        // Similar fail-safe for constraints
+        const unmatchedConstraints = Array.from(paramConstraints.entries()).filter(([name]) => !matchedConstraints.has(name));
+        if (unmatchedConstraints.length > 0) {
+          const propKeys = Object.keys(properties);
+
+          if (propKeys.length === 1 && unmatchedConstraints.length === 1) {
+            const paramKey = propKeys[0];
+            const [constraintName, constraintValue] = unmatchedConstraints[0];
+            this.applyConstraints(properties[paramKey], constraintValue);
+            console.warn(
+              `Parameter name mismatch in JSDoc: constraint tag for ${constraintName} doesn't match ` +
+              `function parameter "${paramKey}". Applying constraint to "${paramKey}".`
+            );
+          }
+        }
+
         const description = this.extractDescription(jsdoc);
         const inputSchema = {
           type: 'object' as const,
@@ -208,7 +263,7 @@ export class SchemaExtractor {
           const throttled = this.extractThrottled(jsdoc);
           const debounced = this.extractDebounced(jsdoc);
           const queued = this.extractQueued(jsdoc);
-          const validations = this.extractValidations(jsdoc);
+          const validations = this.extractValidations(jsdoc, Object.keys(properties));
           const deprecated = this.extractDeprecated(jsdoc);
 
           // Build unified middleware declarations (single source of truth for runtime)
@@ -217,6 +272,19 @@ export class SchemaExtractor {
           // Check for static keyword on the method
           const isStaticMethod = member.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) || false;
 
+          // Event emission for @stateful classes: all public methods emit events automatically
+          const emitsEventData = isStatefulClass ? {
+            emitsEvent: true,
+            eventName: methodName,
+            eventPayload: {
+              method: 'string',
+              params: 'object',
+              result: 'any',
+              timestamp: 'string',
+              instance: 'string',
+            },
+          } : {};
+
           tools.push({
             name: methodName,
             description,
@@ -251,6 +319,8 @@ export class SchemaExtractor {
             ...(deprecated !== undefined ? { deprecated } : {}),
             // Unified middleware declarations (new — runtime uses this)
             ...(middleware.length > 0 ? { middleware } : {}),
+            // Event emission (for @stateful classes)
+            ...emitsEventData,
           });
         }
       };
@@ -353,6 +423,13 @@ export class SchemaExtractor {
       const visit = (node: ts.Node) => {
         // Look for class declarations
         if (ts.isClassDeclaration(node)) {
+          // Check if this class has @stateful decorator
+          const classJsdoc = this.getJSDocComment(node as any, sourceFile);
+          const isStatefulClass = /@stateful\b/i.test(classJsdoc);
+
+          // Extract notification subscriptions from @notify-on tag
+          notificationSubscriptions = this.extractNotifyOn(classJsdoc);
+
           node.members.forEach((member) => {
             // Detect `protected settings = { ... }` property
             if (ts.isPropertyDeclaration(member)) {
@@ -366,7 +443,7 @@ export class SchemaExtractor {
                 m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword
               );
               if (!isPrivate) {
-                processMethod(member);
+                processMethod(member, isStatefulClass);
               }
             }
           });
@@ -392,6 +469,11 @@ export class SchemaExtractor {
       result.configSchema = configSchema;
     }
 
+    // Include notification subscriptions if detected
+    if (notificationSubscriptions) {
+      result.notificationSubscriptions = notificationSubscriptions;
+    }
+
     return result;
   }
 
@@ -488,6 +570,24 @@ export class SchemaExtractor {
       } else {
         properties[paramName] = { type: 'string' };
       }
+
+      // Extract default value if initializer exists
+      if (param.initializer) {
+        const defaultValue = this.extractDefaultValue(param.initializer, sourceFile);
+        if (defaultValue !== undefined) {
+          // Validate default value type matches parameter type
+          const paramType = properties[paramName].type;
+          if (!this.isDefaultValueTypeCompatible(defaultValue, paramType)) {
+            const defaultType = typeof defaultValue;
+            console.warn(
+              `Default value type mismatch: parameter "${paramName}" is type "${paramType}" ` +
+              `but default value is type "${defaultType}" (${JSON.stringify(defaultValue)}). ` +
+              `This may cause runtime errors.`
+            );
+          }
+          properties[paramName].default = defaultValue;
+        }
+      }
     }
 
     return { properties, required, simpleParams: true };
@@ -842,6 +942,30 @@ export class SchemaExtractor {
   /**
    * Extract default value from initializer
    */
+  /**
+   * Check if a default value's type is compatible with the parameter type
+   */
+  private isDefaultValueTypeCompatible(defaultValue: any, paramType: string): boolean {
+    const valueType = typeof defaultValue;
+
+    // Type must match (number → number, boolean → boolean, etc.)
+    switch (paramType) {
+      case 'string':
+        return valueType === 'string';
+      case 'number':
+        // Number params need number defaults, not strings
+        return valueType === 'number';
+      case 'boolean':
+        return valueType === 'boolean';
+      case 'array':
+        return Array.isArray(defaultValue);
+      case 'object':
+        return valueType === 'object';
+      default:
+        return true;  // Unknown types are assumed compatible
+    }
+  }
+
   private extractDefaultValue(initializer: ts.Expression, sourceFile: ts.SourceFile): any {
     // String literals
     if (ts.isStringLiteral(initializer)) {
@@ -861,8 +985,25 @@ export class SchemaExtractor {
       return false;
     }
 
-    // For complex expressions (function calls, etc.), return as string
-    return initializer.getText(sourceFile);
+    // Detect complex expressions
+    const expressionText = initializer.getText(sourceFile);
+    const isComplexExpression =
+      ts.isCallExpression(initializer) ||  // Function calls: Math.max(10, 100)
+      ts.isObjectLiteralExpression(initializer) ||  // Objects: { key: 'value' }
+      ts.isArrayLiteralExpression(initializer) ||  // Arrays: [1, 2, 3]
+      ts.isBinaryExpression(initializer) ||  // Binary ops: 10 + 20
+      ts.isConditionalExpression(initializer);  // Ternary: x ? a : b
+
+    if (isComplexExpression) {
+      console.warn(
+        `Complex default value cannot be reliably serialized: "${expressionText}". ` +
+        `Default will not be applied to schema. Consider using a simple literal value instead.`
+      );
+      return undefined;
+    }
+
+    // For other expressions, return as string
+    return expressionText;
   }
 
   // ═══════════════════════════════════════════════════════════════════════════════
@@ -1181,7 +1322,17 @@ export class SchemaExtractor {
       // Extract {@format formatName} - use lookahead to match until tag-closing }
       const formatMatch = description.match(/\{@format\s+(.+?)\}(?=\s|$|{@)/);
       if (formatMatch) {
-        paramConstraints.format = formatMatch[1].trim();
+        const format = formatMatch[1].trim();
+        // Validate format is in whitelist (JSON Schema + custom formats)
+        const validFormats = ['email', 'date', 'date-time', 'time', 'duration', 'uri', 'uri-reference', 'uuid', 'ipv4', 'ipv6', 'hostname', 'json', 'table'];
+        if (!validFormats.includes(format)) {
+          console.warn(
+            `Invalid @format value: "${format}". ` +
+            `Valid formats: ${validFormats.join(', ')}. Format not applied.`
+          );
+        } else {
+          paramConstraints.format = format;
+        }
       }
 
       // Extract {@choice value1,value2,...} - converts to enum in schema
@@ -1210,6 +1361,18 @@ export class SchemaExtractor {
         }
       }
 
+      // Extract {@minItems value} - for arrays
+      const minItemsMatch = description.match(/\{@minItems\s+(-?\d+(?:\.\d+)?)\}/);
+      if (minItemsMatch) {
+        paramConstraints.minItems = parseInt(minItemsMatch[1], 10);
+      }
+
+      // Extract {@maxItems value} - for arrays
+      const maxItemsMatch = description.match(/\{@maxItems\s+(-?\d+(?:\.\d+)?)\}/);
+      if (maxItemsMatch) {
+        paramConstraints.maxItems = parseInt(maxItemsMatch[1], 10);
+      }
+
       // Extract {@unique} or {@uniqueItems} - for arrays
       if (description.match(/\{@unique(?:Items)?\s*\}/)) {
         paramConstraints.unique = true;
@@ -1244,11 +1407,19 @@ export class SchemaExtractor {
         paramConstraints.deprecated = deprecatedMatch[1]?.trim() || true;
       }
 
-      // Extract {@readOnly} and {@writeOnly} - track which comes last
-      // They are mutually exclusive, so last one wins
+      // Extract {@readOnly} and {@writeOnly} - detect conflicts
+      // They are mutually exclusive, so warn if both present
       const readOnlyMatch = description.match(/\{@readOnly\s*\}/);
       const writeOnlyMatch = description.match(/\{@writeOnly\s*\}/);
 
+      if (readOnlyMatch && writeOnlyMatch) {
+        // Warn about conflict
+        console.warn(
+          `Conflicting constraints: @readOnly and @writeOnly cannot both be applied. ` +
+          `Keeping @${readOnlyMatch && writeOnlyMatch ? (description.lastIndexOf('@readOnly') > description.lastIndexOf('@writeOnly') ? 'readOnly' : 'writeOnly') : 'readOnly'}.`
+        );
+      }
+
       if (readOnlyMatch || writeOnlyMatch) {
         // Find positions to determine which comes last
         const readOnlyPos = readOnlyMatch ? description.indexOf(readOnlyMatch[0]) : -1;
@@ -1292,6 +1463,22 @@ export class SchemaExtractor {
         paramConstraints.accept = acceptMatch[1].trim();
       }
 
+      // Validate no unknown {@...} tags (typos in constraint names)
+      const allKnownTags = ['min', 'max', 'pattern', 'format', 'choice', 'field', 'default', 'unique', 'uniqueItems',
+                             'example', 'multipleOf', 'deprecated', 'readOnly', 'writeOnly', 'label', 'placeholder',
+                             'hint', 'hidden', 'accept', 'minItems', 'maxItems'];
+      const unknownTagRegex = /\{@([\w-]+)\s*(?:\s+[^}]*)?\}/g;
+      let unknownMatch;
+      while ((unknownMatch = unknownTagRegex.exec(description)) !== null) {
+        const tagName = unknownMatch[1];
+        if (!allKnownTags.includes(tagName)) {
+          console.warn(
+            `unknown constraint/hint: @${tagName}. ` +
+            `Valid hints: ${allKnownTags.slice(0, 8).join(', ')}, etc. This tag will be ignored.`
+          );
+        }
+      }
+
       if (Object.keys(paramConstraints).length > 0) {
         constraints.set(paramName, paramConstraints);
       }
@@ -1307,8 +1494,54 @@ export class SchemaExtractor {
    * Works with both simple types and anyOf schemas
    */
   private applyConstraints(schema: any, constraints: any) {
+    // Validate constraint values before applying (fail-safe)
+    if (constraints.min !== undefined && constraints.max !== undefined) {
+      if (constraints.min > constraints.max) {
+        console.warn(
+          `Invalid constraint: @min (${constraints.min}) > @max (${constraints.max}). ` +
+          `Using only @min. Remove @max or use a larger value.`
+        );
+        delete constraints.max;
+      }
+    }
+
     // Helper to apply constraints to a single schema based on type
     const applyToSchema = (s: any) => {
+      // Validate constraint-type compatibility
+      if (!s.enum) {
+        // Warn for incompatible constraints
+        if ((constraints.min !== undefined || constraints.max !== undefined) &&
+            s.type !== 'number' && s.type !== 'string' && s.type !== 'array') {
+          const constraintType = constraints.min !== undefined ? '@min' : '@max';
+          console.warn(
+            `Constraint ${constraintType} not applicable to type "${s.type || 'unknown'}". ` +
+            `This constraint applies to number, string, or array types only.`
+          );
+        }
+
+        if (constraints.pattern !== undefined && s.type !== 'string') {
+          console.warn(
+            `Constraint @pattern not applicable to type "${s.type || 'unknown'}". ` +
+            `Pattern only applies to string types.`
+          );
+        }
+
+        if ((constraints.minItems !== undefined || constraints.maxItems !== undefined) && s.type !== 'array') {
+          const constraintType = constraints.minItems !== undefined ? '@minItems' : '@maxItems';
+          console.warn(
+            `Constraint ${constraintType} not applicable to type "${s.type || 'unknown'}". ` +
+            `This constraint applies to array types only.`
+          );
+        }
+
+        if (constraints.multipleOf !== undefined && s.type !== 'number') {
+          console.warn(
+            `Constraint @multipleOf not applicable to type "${s.type || 'unknown'}". ` +
+            `This constraint applies to number types only.`
+          );
+        }
+      }
+
       if (s.enum) {
         // Skip enum types for most constraints (but still apply deprecated, examples, etc.)
         if (constraints.examples !== undefined) {
@@ -1320,7 +1553,7 @@ export class SchemaExtractor {
         return;
       }
 
-      // Apply min/max based on type
+      // Apply min/max based on type (skip if type is incompatible)
       if (s.type === 'number') {
         if (constraints.min !== undefined) {
           s.minimum = constraints.min;
@@ -1329,7 +1562,15 @@ export class SchemaExtractor {
           s.maximum = constraints.max;
         }
         if (constraints.multipleOf !== undefined) {
-          s.multipleOf = constraints.multipleOf;
+          // Validate multipleOf is positive (JSON schema requires > 0)
+          if (constraints.multipleOf <= 0) {
+            console.warn(
+              `Invalid @multipleOf value: ${constraints.multipleOf}. ` +
+              `Must be positive and non-zero. Constraint not applied.`
+            );
+          } else {
+            s.multipleOf = constraints.multipleOf;
+          }
         }
       } else if (s.type === 'string') {
         if (constraints.min !== undefined) {
@@ -1339,7 +1580,24 @@ export class SchemaExtractor {
           s.maxLength = constraints.max;
         }
         if (constraints.pattern !== undefined) {
-          s.pattern = constraints.pattern;
+          // Check for pattern+enum conflict
+          if (s.enum || constraints.enum) {
+            console.warn(
+              `Conflicting constraints: @pattern cannot be used with enum/choices. ` +
+              `Pattern is ignored when specific values are defined via enum or @choice.`
+            );
+          } else {
+            // Validate pattern is valid regex before applying (fail-safe)
+            try {
+              new RegExp(constraints.pattern);
+              s.pattern = constraints.pattern;
+            } catch (e) {
+              console.warn(
+                `Invalid regex in @pattern constraint: "${constraints.pattern}". ` +
+                `${e instanceof Error ? e.message : String(e)}. Pattern not applied.`
+              );
+            }
+          }
         }
       } else if (s.type === 'array') {
         if (constraints.min !== undefined) {
@@ -1348,10 +1606,27 @@ export class SchemaExtractor {
         if (constraints.max !== undefined) {
           s.maxItems = constraints.max;
         }
+        if (constraints.minItems !== undefined) {
+          s.minItems = constraints.minItems;
+        }
+        if (constraints.maxItems !== undefined) {
+          s.maxItems = constraints.maxItems;
+        }
         if (constraints.unique === true) {
           s.uniqueItems = true;
         }
+      } else if (s.type && s.type !== 'boolean' && s.type !== 'object') {
+        // For other compatible types, apply min/max as needed
+        if (['integer', 'number'].includes(s.type)) {
+          if (constraints.min !== undefined) {
+            s.minimum = constraints.min;
+          }
+          if (constraints.max !== undefined) {
+            s.maximum = constraints.max;
+          }
+        }
       }
+      // Note: For boolean and object types, we skip min/max constraints (already warned above)
 
       // Apply type-agnostic constraints
       if (constraints.format !== undefined) {
@@ -1463,6 +1738,30 @@ export class SchemaExtractor {
     return /@async\b/i.test(jsdocContent);
   }
 
+  /**
+   * Extract notification subscriptions from @notify-on tag
+   * Specifies which event types this photon is interested in
+   * Format: @notify-on mentions, deadlines, errors
+   */
+  private extractNotifyOn(jsdocContent: string): NotificationSubscription | undefined {
+    const notifyMatch = jsdocContent.match(/@notify-on\s+([^\n]+)/i);
+    if (!notifyMatch) {
+      return undefined;
+    }
+
+    // Parse comma-separated event types
+    const watchFor = notifyMatch[1]
+      .split(',')
+      .map(s => s.trim())
+      .filter(s => s.length > 0);
+
+    if (watchFor.length === 0) {
+      return undefined;
+    }
+
+    return { watchFor };
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════════
   // DAEMON FEATURE EXTRACTION
   // ═══════════════════════════════════════════════════════════════════════════════
@@ -1606,10 +1905,27 @@ export class SchemaExtractor {
    * - @retryable 3 2s → 3 retries, 2s delay
    */
   private extractRetryable(jsdocContent: string): { count: number; delay: number } | undefined {
-    const match = jsdocContent.match(/@retryable(?:\s+(\d+))?(?:\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
+    const match = jsdocContent.match(/@retryable(?:\s+([-\d]+))?(?:\s+([-\d]+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
     if (!match) return undefined;
-    const count = match[1] ? parseInt(match[1], 10) : 3;
-    const delay = match[2] ? parseDuration(match[2]) : 1_000;
+    let count = match[1] ? parseInt(match[1], 10) : 3;
+    let delay = match[2] ? parseDuration(match[2]) : 1_000;
+
+    // Validate retryable configuration
+    if (count <= 0) {
+      console.warn(
+        `Invalid @retryable count: ${count}. ` +
+        `Count must be positive (> 0). Using default count 3.`
+      );
+      count = 3;
+    }
+    if (delay <= 0) {
+      console.warn(
+        `Invalid @retryable delay: ${delay}ms. ` +
+        `Delay must be positive (> 0). Using default delay 1000ms.`
+      );
+      delay = 1_000;
+    }
+
     return { count, delay };
   }
 
@@ -1619,9 +1935,45 @@ export class SchemaExtractor {
    * - @throttled 100/h → 100 calls per hour
    */
   private extractThrottled(jsdocContent: string): { count: number; windowMs: number } | undefined {
+    // First check if @throttled is present at all
+    const hasThrottled = /@throttled\b/i.test(jsdocContent);
     const match = jsdocContent.match(/@throttled\s+(\d+\/(?:s|sec|m|min|h|hr|d|day))/i);
-    if (!match) return undefined;
-    return parseRate(match[1]);
+
+    if (!match) {
+      if (hasThrottled) {
+        // @throttled is present but format is invalid
+        const invalidMatch = jsdocContent.match(/@throttled\s+([^\s]+)/i);
+        if (invalidMatch) {
+          console.warn(
+            `Invalid @throttled rate format: "${invalidMatch[1]}". ` +
+            `Expected format: count/unit (e.g., 10/min, 100/h). Rate not applied.`
+          );
+        }
+      }
+      return undefined;
+    }
+
+    const rateStr = match[1];
+    const rate = parseRate(rateStr);
+
+    // Validate throttled configuration
+    if (!rate) {
+      console.warn(
+        `Invalid @throttled rate format: "${rateStr}". ` +
+        `Expected format: count/unit (e.g., 10/min, 100/h). Rate not applied.`
+      );
+      return undefined;
+    }
+
+    if (rate.count <= 0) {
+      console.warn(
+        `Invalid @throttled count: ${rate.count}. ` +
+        `Count must be positive (> 0). Rate not applied.`
+      );
+      return undefined;
+    }
+
+    return rate;
   }
 
   /**
@@ -1654,13 +2006,24 @@ export class SchemaExtractor {
    * - @validate params.email must be a valid email
    * - @validate params.amount must be positive
    */
-  private extractValidations(jsdocContent: string): Array<{ field: string; rule: string }> | undefined {
+  private extractValidations(jsdocContent: string, validParamNames?: string[]): Array<{ field: string; rule: string }> | undefined {
     const validations: Array<{ field: string; rule: string }> = [];
     const regex = /@validate\s+([\w.]+)\s+(.+)/g;
     let match;
     while ((match = regex.exec(jsdocContent)) !== null) {
+      const fieldName = match[1].replace(/^params\./, ''); // strip params. prefix
+
+      // Fail-safe: Validate that referenced field exists (if validParamNames provided)
+      if (validParamNames && !validParamNames.includes(fieldName)) {
+        console.warn(
+          `@validate references non-existent parameter "${fieldName}". ` +
+          `Available parameters: ${validParamNames.join(', ')}. Validation rule ignored.`
+        );
+        continue;
+      }
+
       validations.push({
-        field: match[1].replace(/^params\./, ''), // strip params. prefix
+        field: fieldName,
         rule: match[2].trim().replace(/\*\/$/, '').trim(), // strip JSDoc closing
       });
     }

package/src/types.ts

@@ -191,6 +191,26 @@ export interface ExtractedSchema {
 
   /** When true, method uses individual params instead of a single params object */
   simpleParams?: boolean;
+
+  // ═══ EVENT EMISSION ═══
+
+  /**
+   * True if this method automatically emits an event on execution
+   * (for @stateful classes, all public methods emit automatically)
+   */
+  emitsEvent?: boolean;
+
+  /**
+   * Event name that will be emitted when this method is called
+   * For @stateful classes, defaults to the method name (e.g., 'add', 'done')
+   */
+  eventName?: string;
+
+  /**
+   * Event payload structure — what data will be sent with the event
+   * Typically mirrors the return type of the method
+   */
+  eventPayload?: Record<string, string>;
 }
 
 export interface PhotonClass {
@@ -725,3 +745,31 @@ export interface ConfigSchema {
   /** Description from configure() JSDoc */
   description?: string;
 }
+
+// ══════════════════════════════════════════════════════════════════════════════
+// NOTIFICATION SUBSCRIPTIONS (@notify-on tag)
+// ══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Notification subscription declaration extracted from @notify-on tag
+ * Specifies which event types this photon cares about for notifications
+ */
+export interface NotificationSubscription {
+  /** Event types this photon wants to be notified about */
+  watchFor: string[];
+}
+
+/**
+ * Notification metadata attached to method return values via __notification property
+ * Specifies priority and type of notification when an event occurs
+ */
+export interface NotificationMetadata {
+  /** Type of notification (mentions, deadline, error, etc.) */
+  type: string;
+  /** Priority level for display and handling */
+  priority: 'critical' | 'warning' | 'info';
+  /** Optional message to display */
+  message?: string;
+  /** Optional tags for additional filtering */
+  tags?: string[];
+}