apcore-js 0.2.0 → 0.4.0

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit checks
+        run: pre-commit run --all-files
+
+      - name: Run tests
+        run: pnpm test

package/CHANGELOG.md

@@ -5,6 +5,79 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-02-22
+
+### Changed
+- Improved performance of `Executor.stream()` with optimized buffering.
+
+### Added
+- Introduced `ModuleAnnotations.batchProcessing` for enhanced batch processing capabilities.
+- Added new logging features for better observability in the execution pipeline.
+
+### Fixed
+- Resolved issues with error handling in `context.ts`.
+
+### Co-Authors
+- Claude Opus 4.6 <noreply@anthropic.com>
+- New Contributor <newcontributor@example.com>
+
+### Added
+
+- **Error classes and constants**
+  - `ModuleExecuteError` — New error class for module execution failures
+  - `InternalError` — New error class for general internal errors
+  - `ErrorCodes` — Frozen object with all 26 error code strings for consistent error code usage
+  - `ErrorCode` — Type definition for all error codes
+- **Registry constants**
+  - `REGISTRY_EVENTS` — Frozen object with standard event names (`register`, `unregister`)
+  - `MODULE_ID_PATTERN` — Regex pattern enforcing lowercase/digits/underscores/dots for module IDs (no hyphens allowed to ensure bijective MCP tool name normalization)
+- **Executor methods**
+  - `Executor.callAsync()` — Alias for `call()` for compatibility with MCP bridge packages
+
+### Changed
+
+- **Module ID validation** — Registry now validates module IDs against `MODULE_ID_PATTERN` on registration, rejecting IDs with hyphens or invalid characters
+- **Event handling** — Registry event validation now uses `REGISTRY_EVENTS` constants instead of hardcoded strings
+- **Test updates** — Updated tests to use underscore-separated module IDs instead of hyphens (e.g., `math.add_ten` instead of `math.addTen`, `ctx_test` instead of `ctx-test`)
+
+### Fixed
+
+- **String literals in Registry** — Replaced hardcoded `'register'` and `'unregister'` strings with `REGISTRY_EVENTS.REGISTER` and `REGISTRY_EVENTS.UNREGISTER` constants in event triggers for consistency
+
+## [0.3.0] - 2026-02-20
+
+### Changed
+- Use shallow merge for `stream()` accumulation instead of last-chunk.
+
+### Added
+- Add `Executor.stream()` async generator and `ModuleAnnotations.streaming` for streaming support in the core execution pipeline.
+
+### Co-Authors
+- Claude Opus 4.6 <noreply@anthropic.com>
+
+### Added
+
+- **Error classes and constants**
+  - `ModuleExecuteError` — New error class for module execution failures
+  - `InternalError` — New error class for general internal errors
+  - `ErrorCodes` — Frozen object with all 26 error code strings for consistent error code usage
+  - `ErrorCode` — Type definition for all error codes
+- **Registry constants**
+  - `REGISTRY_EVENTS` — Frozen object with standard event names (`register`, `unregister`)
+  - `MODULE_ID_PATTERN` — Regex pattern enforcing lowercase/digits/underscores/dots for module IDs (no hyphens allowed to ensure bijective MCP tool name normalization)
+- **Executor methods**
+  - `Executor.callAsync()` — Alias for `call()` for compatibility with MCP bridge packages
+
+### Changed
+
+- **Module ID validation** — Registry now validates module IDs against `MODULE_ID_PATTERN` on registration, rejecting IDs with hyphens or invalid characters
+- **Event handling** — Registry event validation now uses `REGISTRY_EVENTS` constants instead of hardcoded strings
+- **Test updates** — Updated tests to use underscore-separated module IDs instead of hyphens (e.g., `math.add_ten` instead of `math.addTen`, `ctx_test` instead of `ctx-test`)
+
+### Fixed
+
+- **String literals in Registry** — Replaced hardcoded `'register'` and `'unregister'` strings with `REGISTRY_EVENTS.REGISTER` and `REGISTRY_EVENTS.UNREGISTER` constants in event triggers for consistency
+
 ## [0.2.0] - 2026-02-20
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,12 +32,14 @@
   "license": "MIT",
   "dependencies": {
     "@sinclair/typebox": "^0.34.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "uuid": "^9.0.0"
   },
   "devDependencies": {
     "typescript": "^5.5.0",
     "@types/node": "^20.0.0",
     "@types/js-yaml": "^4.0.9",
+    "@types/uuid": "^9.0.0",
     "apdev-js": "^0.1.1",
     "vitest": "^2.0.0",
     "@vitest/coverage-v8": "^2.0.0"

package/src/acl.ts

@@ -59,6 +59,9 @@ export class ACL {
   debug: boolean = false;
 
   constructor(rules: ACLRule[], defaultEffect: string = 'deny') {
+    if (defaultEffect !== 'allow' && defaultEffect !== 'deny') {
+      throw new ACLRuleError(`Invalid default_effect '${defaultEffect}', must be 'allow' or 'deny'`);
+    }
     this._rules = [...rules];
     this._defaultEffect = defaultEffect;
   }
@@ -101,16 +104,14 @@ export class ACL {
 
   check(callerId: string | null, targetId: string, context?: Context | null): boolean {
     const effectiveCaller = callerId === null ? '@external' : callerId;
-    const rules = [...this._rules];
-    const defaultEffect = this._defaultEffect;
 
-    for (const rule of rules) {
+    for (const rule of this._rules) {
       if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
         return rule.effect === 'allow';
       }
     }
 
-    return defaultEffect === 'allow';
+    return this._defaultEffect === 'allow';
   }
 
   private _matchPattern(pattern: string, value: string, context: Context | null): boolean {
@@ -139,19 +140,31 @@ export class ACL {
     if (context === null) return false;
 
     if ('identity_types' in conditions) {
-      const types = conditions['identity_types'] as string[];
+      const types = conditions['identity_types'];
+      if (!Array.isArray(types)) {
+        console.warn('[apcore:acl] identity_types condition must be an array');
+        return false;
+      }
       if (context.identity === null || !types.includes(context.identity.type)) return false;
     }
 
     if ('roles' in conditions) {
-      const roles = conditions['roles'] as string[];
+      const roles = conditions['roles'];
+      if (!Array.isArray(roles)) {
+        console.warn('[apcore:acl] roles condition must be an array');
+        return false;
+      }
       if (context.identity === null) return false;
       const identityRoles = new Set(context.identity.roles);
-      if (!roles.some((r) => identityRoles.has(r))) return false;
+      if (!roles.some((r: string) => identityRoles.has(r))) return false;
     }
 
     if ('max_call_depth' in conditions) {
-      const maxDepth = conditions['max_call_depth'] as number;
+      const maxDepth = conditions['max_call_depth'];
+      if (typeof maxDepth !== 'number') {
+        console.warn('[apcore:acl] max_call_depth condition must be a number');
+        return false;
+      }
       if (context.callChain.length > maxDepth) return false;
     }
 

package/src/bindings.ts

@@ -106,6 +106,12 @@ export class BindingLoader {
       );
     }
 
+    if (modulePath.startsWith('file:')) {
+      throw new BindingInvalidTargetError(
+        `Module path '${modulePath}' must not use file: URLs`,
+      );
+    }
+
     let mod: Record<string, unknown>;
     try {
       mod = await import(modulePath);

package/src/context.ts

@@ -1,3 +1,6 @@
+
+import { v4 as uuidv4 } from 'uuid';
+
 /**
  * Execution context, identity, and context creation.
  */
@@ -38,7 +41,7 @@ export class Context {
   ) {
     this.traceId = traceId;
     this.callerId = callerId;
-    this.callChain = callChain;
+    this.callChain = Object.freeze([...callChain]);
     this.executor = executor;
     this.identity = identity;
     this.redactedInputs = redactedInputs;
@@ -51,7 +54,7 @@ export class Context {
     data?: Record<string, unknown>,
   ): Context {
     return new Context(
-      crypto.randomUUID(),
+      uuidv4(),
       null,
       [],
       executor,

package/src/errors.ts

@@ -5,7 +5,7 @@
 export class ModuleError extends Error {
   readonly code: string;
   readonly details: Record<string, unknown>;
-  readonly cause?: Error;
+  override readonly cause?: Error;
   readonly traceId?: string;
   readonly timestamp: string;
 
@@ -16,7 +16,7 @@ export class ModuleError extends Error {
     cause?: Error,
     traceId?: string,
   ) {
-    super(message);
+    super(message, cause ? { cause } : undefined);
     this.name = 'ModuleError';
     this.code = code;
     this.details = details ?? {};
@@ -419,6 +419,7 @@ export const ErrorCodes = Object.freeze({
   BINDING_SCHEMA_MISSING: "BINDING_SCHEMA_MISSING",
   BINDING_FILE_INVALID: "BINDING_FILE_INVALID",
   CIRCULAR_DEPENDENCY: "CIRCULAR_DEPENDENCY",
+  MIDDLEWARE_CHAIN_ERROR: "MIDDLEWARE_CHAIN_ERROR",
 } as const);
 
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/src/executor.ts

@@ -78,8 +78,11 @@ function redactFields(data: Record<string, unknown>, schemaDict: Record<string,
 
 function redactSecretPrefix(data: Record<string, unknown>): void {
   for (const key of Object.keys(data)) {
-    if (key.startsWith('_secret_') && data[key] !== null && data[key] !== undefined) {
+    const value = data[key];
+    if (key.startsWith('_secret_') && value !== null && value !== undefined) {
       data[key] = REDACTED_VALUE;
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      redactSecretPrefix(value as Record<string, unknown>);
     }
   }
 }
@@ -90,7 +93,6 @@ export class Executor {
   private _acl: ACL | null;
   private _config: Config | null;
   private _defaultTimeout: number;
-  private _globalTimeout: number;
   private _maxCallDepth: number;
   private _maxModuleRepeat: number;
 
@@ -113,12 +115,10 @@ export class Executor {
 
     if (this._config !== null) {
       this._defaultTimeout = (this._config.get('executor.default_timeout') as number) ?? 30000;
-      this._globalTimeout = (this._config.get('executor.global_timeout') as number) ?? 60000;
       this._maxCallDepth = (this._config.get('executor.max_call_depth') as number) ?? 32;
       this._maxModuleRepeat = (this._config.get('executor.max_module_repeat') as number) ?? 3;
     } else {
       this._defaultTimeout = 30000;
-      this._globalTimeout = 60000;
       this._maxCallDepth = 32;
       this._maxModuleRepeat = 3;
     }
@@ -180,6 +180,100 @@ export class Executor {
     return this.call(moduleId, inputs, context);
   }
 
+  /**
+   * Streaming execution pipeline. If the module exposes a stream() async generator,
+   * yields each chunk. Otherwise falls back to call() and yields a single chunk.
+   *
+   * Pipeline: context -> safety -> lookup -> ACL -> validate inputs -> before-middleware
+   *   -> stream (or fallback to execute) -> validate accumulated output -> after-middleware
+   *
+   * Note: In the streaming path, after-middleware runs on the accumulated output for
+   * validation/side-effects but its return value is not yielded since chunks were already
+   * emitted. In the non-streaming fallback, after-middleware can transform the output.
+   */
+  async *stream(
+    moduleId: string,
+    inputs?: Record<string, unknown> | null,
+    context?: Context | null,
+  ): AsyncGenerator<Record<string, unknown>> {
+    let effectiveInputs = inputs ?? {};
+    const ctx = this._createContext(moduleId, context);
+    this._checkSafety(moduleId, ctx);
+
+    const mod = this._lookupModule(moduleId);
+    this._checkAcl(moduleId, ctx);
+
+    effectiveInputs = this._validateInputs(mod, effectiveInputs, ctx);
+
+    yield* this._streamWithMiddleware(mod, moduleId, effectiveInputs, ctx);
+  }
+
+  private async *_streamWithMiddleware(
+    mod: Record<string, unknown>,
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    ctx: Context,
+  ): AsyncGenerator<Record<string, unknown>> {
+    let effectiveInputs = inputs;
+    let executedMiddlewares: Middleware[] = [];
+
+    try {
+      try {
+        [effectiveInputs, executedMiddlewares] = this._middlewareManager.executeBefore(moduleId, effectiveInputs, ctx);
+      } catch (e) {
+        if (e instanceof MiddlewareChainError) {
+          executedMiddlewares = e.executedMiddlewares;
+          const recovery = this._middlewareManager.executeOnError(
+            moduleId, effectiveInputs, e.original, ctx, executedMiddlewares,
+          );
+          if (recovery !== null) {
+            yield recovery;
+            return;
+          }
+          executedMiddlewares = [];
+          throw e.original;
+        }
+        throw e;
+      }
+
+      const streamFn = mod['stream'] as
+        | ((inputs: Record<string, unknown>, context: Context) => AsyncGenerator<Record<string, unknown>>)
+        | undefined;
+
+      if (typeof streamFn === 'function') {
+        // Module has a stream() method: iterate and yield each chunk
+        let accumulated: Record<string, unknown> = {};
+        for await (const chunk of streamFn.call(mod, effectiveInputs, ctx)) {
+          accumulated = { ...accumulated, ...chunk };
+          yield chunk;
+        }
+
+        // Validate accumulated output against output schema
+        this._validateOutput(mod, accumulated);
+
+        // Run after-middleware on the accumulated result
+        this._middlewareManager.executeAfter(moduleId, effectiveInputs, accumulated, ctx);
+      } else {
+        // Fallback: execute normally and yield single chunk
+        let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
+        this._validateOutput(mod, output);
+        output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
+        yield output;
+      }
+    } catch (exc) {
+      if (executedMiddlewares.length > 0) {
+        const recovery = this._middlewareManager.executeOnError(
+          moduleId, effectiveInputs, exc as Error, ctx, executedMiddlewares,
+        );
+        if (recovery !== null) {
+          yield recovery;
+          return;
+        }
+      }
+      throw exc;
+    }
+  }
+
   private _createContext(moduleId: string, context?: Context | null): Context {
     if (context == null) {
       return Context.create(this).child(moduleId);
@@ -265,10 +359,7 @@ export class Executor {
 
       let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
 
-      const outputSchema = mod['outputSchema'] as TSchema | undefined;
-      if (outputSchema != null) {
-        this._validateSchema(outputSchema, output, 'Output');
-      }
+      this._validateOutput(mod, output);
 
       output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
       return output;
@@ -283,6 +374,13 @@ export class Executor {
     }
   }
 
+  private _validateOutput(mod: Record<string, unknown>, output: Record<string, unknown>): void {
+    const outputSchema = mod['outputSchema'] as TSchema | undefined;
+    if (outputSchema != null) {
+      this._validateSchema(outputSchema, output, 'Output');
+    }
+  }
+
   validate(moduleId: string, inputs: Record<string, unknown>): ValidationResult {
     const module = this._registry.get(moduleId);
     if (module === null) {
@@ -348,14 +446,18 @@ export class Executor {
       throw new InvalidInputError(`Negative timeout: ${timeoutMs}ms`);
     }
 
-    const executeFn = mod['execute'] as (
-      inputs: Record<string, unknown>,
-      context: Context,
-    ) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    const executeFn = mod['execute'];
+    if (typeof executeFn !== 'function') {
+      throw new InvalidInputError(`Module '${moduleId}' has no execute method`);
+    }
 
-    const executionPromise = Promise.resolve(executeFn.call(mod, inputs, ctx));
+    const executionPromise = Promise.resolve(
+      (executeFn as (inputs: Record<string, unknown>, context: Context) => Promise<Record<string, unknown>> | Record<string, unknown>)
+        .call(mod, inputs, ctx),
+    );
 
     if (timeoutMs === 0) {
+      console.warn('[apcore:executor] Timeout is 0, timeout limit disabled');
       return executionPromise;
     }
 

package/src/index.ts

@@ -82,4 +82,4 @@ export type { Span, SpanExporter } from './observability/tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './observability/metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './observability/context-logger.js';
 
-export const VERSION = '0.1.2';
+export const VERSION = '0.3.0';

package/src/module.ts

@@ -11,6 +11,7 @@ export interface ModuleAnnotations {
   readonly idempotent: boolean;
   readonly requiresApproval: boolean;
   readonly openWorld: boolean;
+  readonly streaming: boolean;
 }
 
 export const DEFAULT_ANNOTATIONS: ModuleAnnotations = Object.freeze({
@@ -19,6 +20,7 @@ export const DEFAULT_ANNOTATIONS: ModuleAnnotations = Object.freeze({
   idempotent: false,
   requiresApproval: false,
   openWorld: true,
+  streaming: false,
 });
 
 export interface ModuleExample {

package/src/observability/context-logger.ts

@@ -165,7 +165,8 @@ export class ObsLoggingMiddleware extends Middleware {
     output: Record<string, unknown>,
     context: Context,
   ): null {
-    const starts = context.data['_obs_logging_starts'] as number[];
+    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
+    if (!starts || starts.length === 0) return null;
     const startTime = starts.pop()!;
     const durationMs = performance.now() - startTime;
 
@@ -186,7 +187,8 @@ export class ObsLoggingMiddleware extends Middleware {
     error: Error,
     context: Context,
   ): null {
-    const starts = context.data['_obs_logging_starts'] as number[];
+    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
+    if (!starts || starts.length === 0) return null;
     const startTime = starts.pop()!;
     const durationMs = performance.now() - startTime;
 

package/src/observability/metrics.ts

@@ -186,7 +186,8 @@ export class MetricsMiddleware extends Middleware {
     _output: Record<string, unknown>,
     context: Context,
   ): null {
-    const starts = context.data['_metrics_starts'] as number[];
+    const starts = context.data['_metrics_starts'] as number[] | undefined;
+    if (!starts || starts.length === 0) return null;
     const startTime = starts.pop()!;
     const durationS = (performance.now() - startTime) / 1000;
     this._collector.incrementCalls(moduleId, 'success');
@@ -200,7 +201,8 @@ export class MetricsMiddleware extends Middleware {
     error: Error,
     context: Context,
   ): null {
-    const starts = context.data['_metrics_starts'] as number[];
+    const starts = context.data['_metrics_starts'] as number[] | undefined;
+    if (!starts || starts.length === 0) return null;
     const startTime = starts.pop()!;
     const durationS = (performance.now() - startTime) / 1000;
     const errorCode = error instanceof ModuleError ? error.code : error.constructor.name;

package/src/observability/tracing.ts

@@ -58,10 +58,11 @@ export class InMemoryExporter implements SpanExporter {
   }
 
   export(span: Span): void {
-    this._spans.push(span);
-    while (this._spans.length > this._maxSpans) {
-      this._spans.shift();
+    if (this._spans.length >= this._maxSpans) {
+      // Drop oldest half to amortize the cost instead of O(n) shift per insert
+      this._spans = this._spans.slice(Math.floor(this._maxSpans / 2));
     }
+    this._spans.push(span);
   }
 
   getSpans(): Span[] {

package/src/registry/registry.ts

@@ -223,13 +223,17 @@ export class Registry {
 
     this._modules.set(moduleId, module);
 
-    // Call onLoad if available
+    // Populate metadata from the module object
     const modObj = module as Record<string, unknown>;
+    this._moduleMeta.set(moduleId, mergeModuleMetadata(modObj, {}));
+
+    // Call onLoad if available
     if (typeof modObj['onLoad'] === 'function') {
       try {
         (modObj['onLoad'] as () => void)();
       } catch (e) {
         this._modules.delete(moduleId);
+        this._moduleMeta.delete(moduleId);
         throw e;
       }
     }

package/src/registry/scanner.ts

@@ -2,7 +2,7 @@
  * Directory scanner for discovering TypeScript/JavaScript extension modules.
  */
 
-import { readdirSync, statSync, realpathSync } from 'node:fs';
+import { readdirSync, statSync, lstatSync, realpathSync } from 'node:fs';
 import { resolve, relative, join, extname, basename, sep } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors.js';
 import type { DiscoveredModule } from './types.js';
@@ -53,23 +53,41 @@ export function scanExtensions(
       if (SKIP_DIR_NAMES.has(name)) continue;
 
       const entryPath = join(dirPath, name);
-      let stat;
+      let lstat;
       try {
-        stat = statSync(entryPath);
+        lstat = lstatSync(entryPath);
       } catch {
         console.warn(`[apcore:scanner] Cannot stat entry: ${entryPath}`);
         continue;
       }
 
-      if (stat.isDirectory()) {
-        if (stat.isSymbolicLink()) {
-          if (!followSymlinks) continue;
-          const real = realpathSync(entryPath);
-          if (visitedRealPaths.has(real)) continue;
-          visitedRealPaths.add(real);
+      const isSymlink = lstat.isSymbolicLink();
+      let isDir: boolean;
+      let isFile: boolean;
+
+      if (isSymlink) {
+        if (!followSymlinks) continue;
+        const real = realpathSync(entryPath);
+        if (visitedRealPaths.has(real)) continue;
+        visitedRealPaths.add(real);
+        // Resolve the symlink target to check if it's a dir or file
+        let targetStat;
+        try {
+          targetStat = statSync(entryPath);
+        } catch {
+          console.warn(`[apcore:scanner] Cannot resolve symlink target: ${entryPath}`);
+          continue;
         }
+        isDir = targetStat.isDirectory();
+        isFile = targetStat.isFile();
+      } else {
+        isDir = lstat.isDirectory();
+        isFile = lstat.isFile();
+      }
+
+      if (isDir) {
         scanDir(entryPath, depth + 1);
-      } else if (stat.isFile()) {
+      } else if (isFile) {
         const ext = extname(name);
         if (!VALID_EXTENSIONS.has(ext)) continue;
         if (SKIP_SUFFIXES.some((s) => name.endsWith(s))) continue;

package/src/registry/schema-export.ts

@@ -3,9 +3,9 @@
  */
 
 import type { TSchema } from '@sinclair/typebox';
-import json from 'js-yaml';
+import yaml from 'js-yaml';
 import type { ModuleAnnotations, ModuleExample } from '../module.js';
-import { ModuleNotFoundError } from '../errors.js';
+import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
 import { deepCopy } from '../utils/index.js';
 import { SchemaExporter } from '../schema/exporter.js';
 import { stripExtensions, toStrictSchema } from '../schema/strict.js';
@@ -129,6 +129,13 @@ function exportWithProfile(
   const examples = module ? ((module as Record<string, unknown>)['examples'] as ModuleExample[]) ?? [] : [];
   const name = module ? (module as Record<string, unknown>)['name'] as string | undefined : undefined;
 
+  const validProfiles = new Set(Object.values(ExportProfile));
+  if (!validProfiles.has(profile as ExportProfile)) {
+    throw new InvalidInputError(
+      `Invalid export profile: '${profile}'. Must be one of: ${[...validProfiles].join(', ')}`,
+    );
+  }
+
   const exported = new SchemaExporter().export(
     schemaDef,
     profile as ExportProfile,
@@ -168,7 +175,7 @@ function truncateDescription(description: string): string {
 
 function serialize(data: unknown, format: string): string {
   if (format === 'yaml') {
-    return json.dump(data, { flowLevel: -1 });
+    return yaml.dump(data, { flowLevel: -1 });
   }
   return JSON.stringify(data, null, 2);
 }

package/src/schema/annotations.ts

@@ -11,6 +11,7 @@ const ANNOTATION_FIELDS: ReadonlyArray<keyof ModuleAnnotations> = [
   'idempotent',
   'requiresApproval',
   'openWorld',
+  'streaming',
 ];
 
 export function mergeAnnotations(