@portel/photon-core 2.20.0 → 2.22.0

package/src/memory.ts

@@ -55,6 +55,11 @@ export interface MemoryBackend {
    * uses a per-key promise chain.
    */
   update(namespace: string, key: string, updater: (current: any | null) => any): Promise<any>;
+  /**
+   * List all key-value pairs in the namespace, optionally filtered by key prefix.
+   * Aligns with Deno KV's list() surface for minimal, predictable enumeration.
+   */
+  list(namespace: string, prefix?: string): Promise<Array<{ key: string; value: any }>>;
 }
 
 // ════════════════════════════════════════════════════════════════════════════════
@@ -185,6 +190,26 @@ export class FileMemoryBackend implements MemoryBackend {
       return updated;
     });
   }
+
+  async list(namespace: string, prefix?: string): Promise<Array<{ key: string; value: any }>> {
+    let allKeys: string[];
+    try {
+      const files = await fs.readdir(namespace);
+      allKeys = files.filter(f => f.endsWith('.json') && !f.endsWith('.tmp')).map(f => f.slice(0, -5));
+    } catch (error: any) {
+      if (error.code === 'ENOENT') return [];
+      throw error;
+    }
+
+    const filtered = prefix ? allKeys.filter(k => k.startsWith(prefix)) : allKeys;
+    const entries = await Promise.all(
+      filtered.map(async key => {
+        const value = await this.get(namespace, key);
+        return { key, value };
+      })
+    );
+    return entries.filter(e => e.value !== null);
+  }
 }
 
 // ════════════════════════════════════════════════════════════════════════════════
@@ -331,6 +356,10 @@ export class MemoryProvider {
     return result;
   }
 
+  async list<T = any>(prefix?: string, scope: MemoryScope = 'photon'): Promise<Array<{ key: string; value: T }>> {
+    return this._backend.list(this.ns(scope), prefix) as Promise<Array<{ key: string; value: T }>>;
+  }
+
   async update<T = any>(
     key: string,
     updater: (current: T | null) => T,

package/src/middleware.ts

@@ -626,6 +626,54 @@ const retryableMiddleware = defineMiddleware<{ count: number; delay: number }>({
   },
 });
 
+// --- bulkhead (phase 15) ---
+// Caps concurrent in-flight executions per photon:instance:tool. Unlike
+// @throttled (which rate-limits over a time window), bulkhead protects
+// downstream resources from being overwhelmed by concurrent load.
+// Fast-fails when the cap is hit — callers should back off or queue.
+
+interface BulkheadStateEntry {
+  inFlight: number;
+}
+
+const bulkheadMiddleware = defineMiddleware<{ maxConcurrent: number }>({
+  name: 'bulkhead',
+  phase: 15,
+  parseShorthand(value: string) {
+    return { maxConcurrent: Math.max(1, parseInt(value.trim(), 10) || 1) };
+  },
+  parseConfig(raw) {
+    return {
+      maxConcurrent: Math.max(1, parseInt(raw.maxConcurrent || raw.max || '1', 10)),
+    };
+  },
+  create(config, state) {
+    return async (ctx, next) => {
+      const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+      let entry = state.get<BulkheadStateEntry>(key);
+      if (!entry) {
+        entry = { inFlight: 0 };
+        state.set(key, entry);
+      }
+
+      if (entry.inFlight >= config.maxConcurrent) {
+        const error = new Error(
+          `Bulkhead full: ${ctx.photon}.${ctx.tool} has ${entry.inFlight} concurrent executions (cap: ${config.maxConcurrent})`
+        );
+        error.name = 'PhotonBulkheadFullError';
+        throw error;
+      }
+
+      entry.inFlight++;
+      try {
+        return await next();
+      } finally {
+        entry.inFlight = Math.max(0, entry.inFlight - 1);
+      }
+    };
+  },
+});
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // GLOBAL BUILT-IN REGISTRY
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -634,6 +682,7 @@ export const builtinRegistry = new MiddlewareRegistry();
 builtinRegistry.register(fallbackMiddleware);
 builtinRegistry.register(loggedMiddleware);
 builtinRegistry.register(circuitBreakerMiddleware);
+builtinRegistry.register(bulkheadMiddleware);
 builtinRegistry.register(throttledMiddleware);
 builtinRegistry.register(debouncedMiddleware);
 builtinRegistry.register(cachedMiddleware);

package/src/schema-extractor.ts

@@ -1180,6 +1180,18 @@ export class SchemaExtractor {
       declarations.push({ name: 'circuitBreaker', config: circuitBreaker, phase: def?.phase ?? 8 });
     }
 
+    // @bulkhead
+    const bulkheadMatch = jsdocContent.match(/@bulkhead(?:\s+(\d+))?/i);
+    if (bulkheadMatch) {
+      const maxConcurrent = Math.max(1, parseInt(bulkheadMatch[1] || '1', 10));
+      const def = builtinRegistry.get('bulkhead');
+      declarations.push({
+        name: 'bulkhead',
+        config: { maxConcurrent },
+        phase: def?.phase ?? 15,
+      });
+    }
+
     // @cached
     const cached = this.extractCached(jsdocContent);
     if (cached) {

package/src/validation.ts

@@ -12,15 +12,27 @@
 // ERROR BASE CLASSES
 // ══════════════════════════════════════════════════════════════════════════════
 
+export interface PhotonErrorOptions {
+  /** Root cause per ECMAScript Error `cause` proposal. Preserved on the error
+   * so OTel `recordException` can capture the original stack trace. */
+  cause?: unknown;
+}
+
 export class PhotonError extends Error {
+  public readonly cause?: unknown;
+
   constructor(
     message: string,
     public readonly code: string,
     public readonly details?: Record<string, unknown>,
     public readonly suggestion?: string,
+    options?: PhotonErrorOptions,
   ) {
     super(message);
     this.name = 'PhotonError';
+    if (options?.cause !== undefined) {
+      this.cause = options.cause;
+    }
     Error.captureStackTrace?.(this, this.constructor);
   }
 }
@@ -30,8 +42,9 @@ export class ValidationError extends PhotonError {
     message: string,
     details?: Record<string, unknown>,
     suggestion?: string,
+    options?: PhotonErrorOptions,
   ) {
-    super(message, 'VALIDATION_ERROR', details, suggestion);
+    super(message, 'VALIDATION_ERROR', details, suggestion, options);
     this.name = 'ValidationError';
   }
 }