Add optional schema validation at function boundaries

Introduces an opt-in validation hook so Composable functions can declare
input and output schemas. When declared, the ServiceManager validates the
event body before handleEvent() is invoked and the resolved return value
after, surfacing failures as AppException(400) and AppException(500)
respectively. Functions without schemas are unaffected (single truthy
check per dispatch, no behaviour change).

The protocol is intentionally library-agnostic: a minimal Validator<T>
interface requiring only a .parse(value) method that throws on invalid
input. Zod schemas satisfy it natively, and hand-rolled validators or
TypeBox adapters work with zero framework changes. No new runtime
dependencies are added.

- src/models/composable.ts: add Validator<T> and Infer<V>; extend
  Composable with optional inputSchema and outputSchema
- src/system/function-registry.ts: capture schemas into metadata at save()
- src/system/platform.ts: ServiceManager accepts schemas, validates input
  before dispatch and output after; interceptors skip output validation
  (their return value is already discarded); EventEnvelope returns have
  their body validated in place
- src/index.ts: export Validator and Infer
- tests/po.test.ts: add SchemaValidatedService with hand-rolled validators
  and three tests covering happy path, 400 on bad input, 500 on bad output

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ernestojballon

dist/index.d.ts

@@ -9,7 +9,7 @@ export { MultiLevelMap } from './util/multi-level-map.js';
 export { EventEnvelope } from './models/event-envelope.js';
 export { AsyncHttpRequest } from './models/async-http-request.js';
 export { AppException } from './models/app-exception.js';
-export { Composable, preload } from './models/composable.js';
+export { Composable, Validator, Infer, preload } from './models/composable.js';
 export { ObjectStreamIO, ObjectStreamWriter, ObjectStreamReader } from './system/object-stream.js';
 export { AppConfig, ConfigReader } from './util/config-reader.js';
 export { TemplateLoader } from './util/template-loader.js';

dist/index.js.map

@@ -1,4 +1,20 @@
 import { EventEnvelope } from "./event-envelope.js";
+/**
+ * Minimal library-agnostic validator protocol.
+ *
+ * Any object exposing a `parse(value) => T` method that throws on invalid input
+ * satisfies this interface. Zod schemas satisfy it natively. TypeBox users can
+ * wrap a schema with a small adapter:
+ *
+ *     const v: Validator<T> = { parse: (x) => { if (!Check(schema, x)) throw new Error(...); return x as T; } };
+ */
+export interface Validator<T = unknown> {
+    parse(value: unknown): T;
+}
+/**
+ * Type helper: extract the parsed type of a Validator (akin to z.infer).
+ */
+export type Infer<V> = V extends Validator<infer T> ? T : never;
 export interface Composable {
     /**
      * Annotation for the initialize() method to tell the system to preload this composable function:
@@ -25,6 +41,21 @@ export interface Composable {
      * @param evt is the incoming event containing headers and body (payload)
      */
     handleEvent(evt: EventEnvelope): Promise<string | boolean | number | object | EventEnvelope | null>;
+    /**
+     * Optional input schema. When set, the event body is validated BEFORE
+     * handleEvent() is invoked. Validation failure throws AppException(400).
+     * The parsed (and potentially coerced) value replaces evt.getBody().
+     */
+    inputSchema?: Validator;
+    /**
+     * Optional output schema. When set, the handler's resolved return value
+     * is validated AFTER handleEvent() completes. Validation failure is
+     * reported as AppException(500). Skipped for interceptors (their return
+     * value is not forwarded anyway).
+     *
+     * If the handler returns an EventEnvelope, the envelope's body is validated.
+     */
+    outputSchema?: Validator;
 }
 /**
  * Annotation for a composable class

dist/models/composable.d.ts

@@ -9,7 +9,7 @@ export { MultiLevelMap } from './util/multi-level-map.js';
 export { EventEnvelope } from './models/event-envelope.js';
 export { AsyncHttpRequest } from './models/async-http-request.js';
 export { AppException } from './models/app-exception.js';
-export { Composable, preload } from './models/composable.js';
+export { Composable, Validator, Infer, preload } from './models/composable.js';
 export { ObjectStreamIO, ObjectStreamWriter, ObjectStreamReader } from './system/object-stream.js';
 export { AppConfig, ConfigReader } from './util/config-reader.js';
 export { TemplateLoader } from './util/template-loader.js';