@karmaniverous/smoz 0.2.3 → 0.2.5

package/dist/cjs/index.js

@@ -2,21 +2,9 @@
 
 var path = require('node:path');
 var node_url = require('node:url');
-var baseEventTypeMapSchema$1 = require('@/src/core/baseEventTypeMapSchema');
-var buildStageArtifacts = require('@/src/core/buildStageArtifacts');
-var httpTokens = require('@/src/core/httpTokens');
-var registry = require('@/src/core/registry');
-var serverlessConfig = require('@/src/core/serverlessConfig');
-var buildOpenApi = require('@/src/openapi/buildOpenApi');
-var buildServerless = require('@/src/serverless/buildServerless');
 var zod = require('zod');
-var stagesFactory = require('@/src/serverless/stagesFactory');
+var radash = require('radash');
 var middy = require('@middy/core');
-var defineFunctionConfig = require('@/src/core/defineFunctionConfig');
-var httpStackCustomization = require('@/src/http/middleware/httpStackCustomization');
-var envBuilder = require('@/src/runtime/envBuilder');
-require('@/src/http/middleware/combine');
-var transformUtils = require('@/src/http/middleware/transformUtils');
 var httpContentNegotiation = require('@middy/http-content-negotiation');
 var httpCors = require('@middy/http-cors');
 var httpErrorHandler = require('@middy/http-error-handler');
@@ -24,157 +12,7 @@ var httpEventNormalizer = require('@middy/http-event-normalizer');
 var httpHeaderNormalizer = require('@middy/http-header-normalizer');
 var httpJsonBodyParser = require('@middy/http-json-body-parser');
 var httpResponseSerializer = require('@middy/http-response-serializer');
-var asApiMiddleware = require('@/src/http/middleware/asApiMiddleware');
-var httpZodValidator = require('@/src/http/middleware/httpZodValidator');
-var shortCircuitHead = require('@/src/http/middleware/shortCircuitHead');
-var wrapSerializer = require('@/src/http/middleware/wrapSerializer');
-
-/**
- * App (schema‑first)
- *
- * Central orchestrator for a SMOZ application. You provide:
- * - Global/stage parameter schemas and env exposure keys
- * - Serverless defaults (handler filename/export and context map)
- * - Event‑type map schema (extendable: e.g., add 'step')
- *
- * The instance:
- * - Validates configuration
- * - Exposes env and stage artifacts for Serverless (provider.environment and params)
- * - Provides a registry to define functions (HTTP and non‑HTTP)
- * - Aggregates artifacts:
- *   - buildAllServerlessFunctions(): AWS['functions']
- *   - buildAllOpenApiPaths(): ZodOpenApiPathsObject
- *
- * @remarks See README for a full quick‑start, and typedoc for detailed API docs.
- */
-/**
- * Application class. *
- * @typeParam GlobalParamsSchema - Zod object schema for global parameters
- * @typeParam StageParamsSchema  - Zod object schema for per‑stage parameters
- * @typeParam EventTypeMapSchema - Zod object schema mapping event tokens to runtime types
- */ class App {
-    /** Helper alias for stage artifacts type */
-    static _stageArtifactsType = null;
-    appRootAbs;
-    // Schemas
-    globalParamsSchema;
-    stageParamsSchema;
-    eventTypeMapSchema; // Serverless config
-    serverless;
-    // Env exposure
-    global;
-    stage;
-    // Derived stage artifacts
-    stages;
-    environment;
-    buildFnEnv;
-    http;
-    // HTTP tokens for runtime decision
-    httpEventTypeTokens;
-    // Registry (delegated to src/app/registry)
-    registry;
-    constructor(init) {
-        this.appRootAbs = init.appRootAbs.replace(/\\/g, '/');
-        this.globalParamsSchema = init.globalParamsSchema;
-        this.stageParamsSchema = init.stageParamsSchema;
-        // Default to base schema when omitted (apply default INSIDE the function)
-        this.eventTypeMapSchema = (init.eventTypeMapSchema ??
-            baseEventTypeMapSchema$1.baseEventTypeMapSchema);
-        // Parse serverless input internally
-        this.serverless = serverlessConfig.serverlessConfigSchema.parse(init.serverless);
-        // Validate that eventTypeMapSchema includes base keys at runtime
-        httpTokens.validateEventTypeMapSchemaIncludesBase(this.eventTypeMapSchema.shape);
-        // Env exposure nodes
-        this.global = {
-            paramsSchema: this.globalParamsSchema,
-            envKeys: init.global.envKeys,
-        };
-        this.stage = {
-            paramsSchema: this.stageParamsSchema,
-            envKeys: init.stage.envKeys,
-        };
-        // Build stages/environment/fn-env via helper (applies “stage extends global” and parsing)
-        const { stages, environment, buildFnEnv } = buildStageArtifacts.buildStageArtifacts(this.globalParamsSchema, this.stageParamsSchema, { params: init.global.params, envKeys: init.global.envKeys }, { params: init.stage.params, envKeys: init.stage.envKeys });
-        this.stages = stages;
-        this.environment = environment;
-        this.buildFnEnv = buildFnEnv;
-        // HTTP tokens (runtime decision)
-        this.httpEventTypeTokens = (init.httpEventTypeTokens ??
-            httpTokens.defaultHttpEventTypeTokens);
-        // App-level HTTP customization
-        this.http = init.http ?? {};
-        // Initialize function registry
-        this.registry = registry.createRegistry({
-            httpEventTypeTokens: this.httpEventTypeTokens,
-            env: { global: this.global, stage: this.stage },
-            http: this.http,
-            // With exactOptionalPropertyTypes, do not pass an explicit undefined.
-            ...(init.functionDefaults
-                ? { functionDefaults: init.functionDefaults }
-                : {}),
-        });
-    } /**
-     * Ergonomic constructor for schema‑first inference.
-     *
-     * @param init - initialization object (schemas, serverless defaults, params/envKeys)
-     * @returns a new App instance
-     */
-    static create(init) {
-        return new App(init);
-    }
-    /**
-     * Register a function (HTTP or non‑HTTP).
-     *
-     * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
-     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
-     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
-     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
-     * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
-     */
-    defineFunction(options) {
-        const functionName = options.functionName ??
-            (() => {
-                const callerDir = path.dirname(node_url.fileURLToPath(options.callerModuleUrl));
-                const rel = path.relative(this.appRootAbs, callerDir).split(path.sep).join('/');
-                const parts = rel.split('/').filter(Boolean);
-                // Drop leading 'app' segment if present, per repo convention
-                if (parts[0] === 'app')
-                    parts.shift();
-                return parts.join('_'); // underscore formatting
-            })();
-        return this.registry.defineFunction({
-            functionName,
-            eventType: options.eventType,
-            ...(options.method ? { method: options.method } : {}),
-            ...(options.basePath ? { basePath: options.basePath } : {}),
-            ...(options.httpContexts ? { httpContexts: options.httpContexts } : {}),
-            ...(options.contentType ? { contentType: options.contentType } : {}),
-            ...(options.eventSchema ? { eventSchema: options.eventSchema } : {}),
-            ...(options.responseSchema
-                ? { responseSchema: options.responseSchema }
-                : {}),
-            ...(options.fnEnvKeys ? { fnEnvKeys: options.fnEnvKeys } : {}),
-            callerModuleUrl: options.callerModuleUrl,
-            endpointsRootAbs: options.endpointsRootAbs,
-        });
-    }
-    /**
-     * Aggregate Serverless function definitions across the registry.
-     *
-     * @returns An AWS['functions'] object suitable for serverless.ts
-     */
-    buildAllServerlessFunctions() {
-        return buildServerless.buildAllServerlessFunctions(this.registry.values(), this.serverless, this.buildFnEnv);
-    }
-    /**
-     * Aggregate OpenAPI path items across the registry.
-     *
-     * @returns ZodOpenApiPathsObject to be embedded in a full OpenAPI document
-     */
-    buildAllOpenApiPaths() {
-        return buildOpenApi.buildAllOpenApiPaths(this.registry.values());
-    }
-}
+var packageDirectory = require('package-directory');
 
 const baseEventTypeMapSchema = zod.z.object({
     rest: zod.z.custom(),
@@ -200,234 +38,335 @@ const baseEventTypeMapSchema = zod.z.object({
 // - Only tokens listed in your App's httpEventTypeTokens are treated as HTTP by the runtime.
 
 /**
- * Define a complete application configuration from schemas and authoring input.
+ * Stage artifacts factory.
  *
- * @typeParam GlobalParamsSchema - Global params schema
- * @typeParam StageParamsSchema  - Per‑stage params schema
- * @param globalParamsSchema - schema for global params
- * @param stageParamsSchema  - schema for stage params
- * @param input - serverless defaults and concrete params + env exposure
- * @returns Typed configuration nodes and stage artifacts
- * * @throws Error if envKeys include keys not present in their corresponding schema
+ * Validates per‑stage configurations, composes them with global params,
+ * and produces:
+ *  - Serverless `stages` (params), *  - provider‑level `environment` mapping,
+ *  - a helper to build per‑function env mappings (excluding globally exposed keys).
  */
-function defineAppConfig(globalParamsSchema, stageParamsSchema, input) {
-    const assertKeysSubset = (schema, keys, label) => {
-        const allowed = new Set(Object.keys(schema.shape));
-        const bad = keys.filter((k) => !allowed.has(k));
-        if (bad.length)
-            throw new Error(`${label} contains unknown keys: ${bad.join(', ')}`);
+/**
+ * Create all stage artifacts from provided configs.  This is generic and can
+ * be used by both production and tests.
+ *
+ * @typeParam GlobalParams - global params record
+ * @typeParam StageParams  - stage params record
+ * @param input - schemas, concrete params, env exposure, and per‑stage values
+ * @returns stage params object, provider environment, and per‑function env builder
+ *
+ * @throws Error if a stage fails validation or a required global key is missing
+ */
+const stagesFactory = (input) => {
+    const { globalParamsSchema, stageParamsSchema, globalParams, globalEnvKeys, stageEnvKeys, stages, } = input;
+    // Validate each stage configuration:
+    // 1) Stage object conforms to stage schema
+    // 2) Stage merged with global satisfies required global keys
+    const entries = Object.entries(stages);
+    for (const [, stage] of entries) {
+        stageParamsSchema.parse(stage);
+        globalParamsSchema.strip().parse({ ...globalParams, ...stage });
+    }
+    // Build Serverless 'params' structure
+    const stagesOut = entries.reduce((acc, [name, params]) => {
+        acc[name] = { params };
+        return acc;
+    }, { default: { params: globalParams } });
+    // Build provider.environment mapping for globally exposed keys
+    const globallyExposed = radash.unique([].concat(globalEnvKeys, stageEnvKeys));
+    const environment = Object.fromEntries(globallyExposed.map((k) => [k, `\${param:${k}}`]));
+    // Helper for function-level environment: include only non-globally-exposed
+    const buildFnEnv = (fnEnvKeys = []) => {
+        const extras = radash.diff(fnEnvKeys, globallyExposed);
+        return Object.fromEntries(extras.map((k) => [k, `\${param:${k}}`]));
     };
-    assertKeysSubset(globalParamsSchema, input.global.envKeys, 'global.envKeys');
-    assertKeysSubset(stageParamsSchema, input.stage.envKeys, 'stage.envKeys');
-    const sf = stagesFactory.stagesFactory({
+    return { stages: stagesOut, environment, buildFnEnv };
+};
+
+/**
+ * Compose stage artifacts (effective schema + parsed stages + env helpers).
+ * Extracted from App.ts to keep the class focused on orchestration.
+ */
+function buildStageArtifacts(globalParamsSchema, stageParamsSchema, global, stage) {
+    const effectiveStageParamsSchema = globalParamsSchema
+        .partial()
+        .extend(stageParamsSchema.shape);
+    const typedStages = Object.fromEntries(Object.entries(stage.params).map(([name, params]) => {
+        const parsed = effectiveStageParamsSchema.parse(params);
+        return [name, parsed];
+    }));
+    return stagesFactory({
         globalParamsSchema,
-        stageParamsSchema,
-        globalParams: input.global.params,
-        globalEnvKeys: input.global.envKeys,
-        stageEnvKeys: input.stage.envKeys,
-        stages: input.stage.params,
+        stageParamsSchema: effectiveStageParamsSchema,
+        globalParams: global.params,
+        globalEnvKeys: global.envKeys,
+        stageEnvKeys: stage.envKeys,
+        stages: typedStages,
     });
-    return {
-        serverless: input.serverless,
-        global: { paramsSchema: globalParamsSchema, envKeys: input.global.envKeys },
-        stage: { paramsSchema: stageParamsSchema, envKeys: input.stage.envKeys },
-        stages: sf.stages,
-        environment: sf.environment,
-        buildFnEnv: sf.buildFnEnv,
-    };
 }
 
-/** Narrow to API Gateway v1 events with safe property checks. */
+/** Default HTTP event tokens used by the runtime. */
+const defaultHttpEventTypeTokens = [
+    'rest',
+    'http',
+];
+/** Base event type keys that MUST be present in any extended map schema. */
+const BASE_EVENT_TYPE_KEYS = ['rest', 'http', 'sqs'];
 /**
- * Type guard for API Gateway v1 events. *
- * @param evt - unknown event
- * @returns true if the event looks like a v1 APIGatewayProxyEvent
+ * Runtime guard: ensure an extended eventTypeMapSchema includes base keys.
+ * Pass the .shape object of a ZodObject for checking.
+ *
+ * @param shape - Zod object `shape` for an extended event type map
+ * @throws Error when any base key is missing from the shape
  */
-const isV1 = (evt) => {
-    if (typeof evt !== 'object' || evt === null)
-        return false;
-    return 'httpMethod' in evt && 'requestContext' in evt;
+const validateEventTypeMapSchemaIncludesBase = (shape) => {
+    for (const k of BASE_EVENT_TYPE_KEYS) {
+        if (!(k in shape))
+            throw new Error(`eventTypeMapSchema is missing base key "${k}". Ensure it extends baseEventTypeMapSchema.`);
+    }
 };
-/** Narrow to API Gateway v2 events with safe property checks. */
+
+const ENV_CONFIG = Symbol.for('szo.envConfig');
+/** @see {@link runtime/wrapHandler.wrapHandler | wrapHandler} */
+function getEnvFromFunctionConfig(fc) {
+    const env = fc[ENV_CONFIG];
+    if (!env) {
+        throw new Error('FunctionConfig is missing env attachment. Use defineFunctionConfig(env)(...) when authoring.');
+    }
+    return env;
+}
+
 /**
- * Type guard for API Gateway v2 events.
+ * Combine several middlewares into one (order-preserving).
+ *
+ * @param parts - middlewares to compose
+ * @returns a middleware that calls before/after/onError in sequence
+ * @remarks
+ * If a previous middleware sets `request.response` during `before`, the
+ * sequence will stop early so the base handler is skipped (e.g. HEAD).
  */
-const isV2 = (evt) => {
-    if (typeof evt !== 'object' || evt === null)
-        return false;
-    if (!('version' in evt) || !('requestContext' in evt))
-        return false;
-    const rc = evt.requestContext;
-    return (!!rc && typeof rc === 'object' && 'http' in rc);
-};
-/** Case-insensitive single-value header lookup. */
-const getHeader = (headers, key) => {
-    if (!headers)
-        return undefined;
-    const direct = headers[key];
-    if (typeof direct === 'string')
-        return direct;
-    const found = Object.keys(headers).find((k) => k.toLowerCase() === key.toLowerCase());
-    return found ? headers[found] : undefined;
+const combine = (...parts) => {
+    const befores = parts.map((m) => m.before).filter(Boolean);
+    const afters = parts.map((m) => m.after).filter(Boolean);
+    const onErrors = parts.map((m) => m.onError).filter(Boolean);
+    return {
+        before: async (request) => {
+            for (const fn of befores) {
+                await fn(request);
+                // If a prior middleware has produced a response (e.g., HEAD short-circuit),
+                // exit early so the base handler will be skipped by Middy.
+                if (request.response !== undefined)
+                    return;
+            }
+        },
+        after: async (request) => {
+            for (const fn of afters)
+                await fn(request);
+        },
+        onError: async (request) => {
+            for (const fn of onErrors)
+                await fn(request);
+        },
+    };
 };
-/** Case-insensitive multi-value header lookup. */
-const getMultiHeader = (headers, key) => {
-    if (!headers)
-        return undefined;
-    const direct = headers[key];
-    if (Array.isArray(direct) && direct.length > 0)
-        return direct[0];
-    const found = Object.keys(headers).find((k) => k.toLowerCase() === key.toLowerCase());
-    return found ? headers[found]?.[0] : undefined;
+
+const ID_PROP = '__id';
+/** Attach a non-enumerable __id to a middleware step. */
+const tagStep = (mw, id) => {
+    if (!Object.prototype.hasOwnProperty.call(mw, ID_PROP)) {
+        Object.defineProperty(mw, ID_PROP, { value: id, enumerable: false });
+    }
+    return mw;
 };
-/** Get a header value from either single- or multi-value maps. */
-const getHeaderFromEvent = (evt, key) => {
-    const single = getHeader(evt.headers, key);
-    if (typeof single === 'string')
-        return single;
-    const multi = getMultiHeader(evt
-        .multiValueHeaders, key);
-    return multi;
+/** Retrieve a step's id, if present. */
+const getId = (mw) => mw[ID_PROP];
+/** Find index of a step by id. */
+const findIndex = (list, id) => list.findIndex((m) => getId(m) === id);
+/** Insert a step before the step with given id. */
+const insertBefore = (list, id, mw) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    return [...list.slice(0, i), mw, ...list.slice(i)];
 };
-const hasAwsSig = (auth) => typeof auth === 'string' && auth.startsWith('AWS4-HMAC-SHA256');
-const hasV1AccessKey = (evt) => {
-    const rc = evt.requestContext;
-    const ak = rc.identity?.accessKey;
-    return typeof ak === 'string' && ak.length > 0;
+/** Insert a step after the step with given id. */
+const insertAfter = (list, id, mw) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    return [...list.slice(0, i + 1), mw, ...list.slice(i + 1)];
 };
-const hasAuthorizer = (evt) => {
-    // V1: any truthy authorizer object indicates an authenticated request
-    if (isV1(evt)) {
-        const rc = evt.requestContext;
-        return !!rc.authorizer;
-    }
-    // V2: authorizer may include jwt/iam/lambda shapes
-    const authHeader = getHeaderFromEvent(evt, 'authorization');
-    if (hasAwsSig(authHeader))
-        return true;
-    const rc = evt
-        .requestContext;
-    const { authorizer } = rc;
-    if (!authorizer || typeof authorizer !== 'object')
-        return false;
-    const a = authorizer;
-    return !!(a.jwt || a.iam || a.lambda);
+/** Replace a step with given id. */
+const replaceStep = (list, id, mw) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    const out = list.slice();
+    out[i] = mw;
+    return out;
 };
-/** Detect API key via header or v1 identity.apiKey. */
-const hasApiKey = (evt) => {
-    const fromHeader = getHeaderFromEvent(evt, 'x-api-key');
-    if (typeof fromHeader === 'string')
-        return true;
-    // Some v1 events surface API key on requestContext.identity.apiKey
-    if (isV1(evt)) {
-        const rc = evt.requestContext;
-        const identKey = rc.identity?.apiKey;
-        if (typeof identKey === 'string' && identKey.length > 0)
-            return true;
-        const identKeyId = rc.identity?.apiKeyId;
-        if (typeof identKeyId === 'string' && identKeyId.length > 0)
-            return true;
+/** Remove a step with given id. */
+const removeStep = (list, id) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    return [...list.slice(0, i), ...list.slice(i + 1)];
+};
+/** Invariant validation helpers */
+const assertInvariants = (phases) => {
+    const { before, after } = phases;
+    if (before.length === 0 || getId(before[0]) !== 'head') {
+        throw new Error("Invariant violation: 'head' must be first in before.");
+    }
+    if (after.length === 0 ||
+        getId(after[after.length - 1]) !== 'serializer') {
+        throw new Error("Invariant violation: 'serializer' must be last in after.");
+    }
+    const shapeIdx = findIndex(after, 'shape');
+    const serialIdx = findIndex(after, 'serializer');
+    if (shapeIdx < 0 || serialIdx < 0 || shapeIdx >= serialIdx) {
+        throw new Error("Invariant violation: 'shape' must precede 'serializer' in after.");
+    }
+    const illegal = (arr) => arr.find((m) => getId(m) === 'error-handler');
+    if (illegal(before) || illegal(after)) {
+        throw new Error("Illegal placement: 'error-handler' may only appear in onError phase.");
     }
-    return false;
 };
-/** Classify the security context from either API Gateway event version. */
+
 /**
- * Detect security context from API Gateway v1/v2 events.
+ * Coerce a generic Middy middleware into an API‑Gateway‑typed middleware.
  *
- * @param evt - unknown event
- * @returns 'my' when authorized (Cognito/JWT/IAM), 'private' when API key present, else 'public'
+ * @param m - middleware object (any event/context signature)
+ * @returns middleware object typed to (APIGatewayProxyEvent, Context) */
+const asApiMiddleware = (m) => m;
+
+/**
+ * Create a Plain‑Old‑JSON clone of an arbitrary input.
+ *
+ * - Drops non‑JSON scalars and containers (Map/Set/etc.)
+ * - Avoids circular references
+ * - Preserves Date via toJSON
  */
-const detectSecurityContext = (evt) => {
-    if (isV1(evt)) {
-        const auth = getHeaderFromEvent(evt, 'authorization');
-        if (hasAwsSig(auth) || hasV1AccessKey(evt) || hasAuthorizer(evt))
-            return 'my';
-        if (hasApiKey(evt))
-            return 'private';
-        return 'public';
-    }
-    if (isV2(evt)) {
-        const auth = getHeaderFromEvent(evt, 'authorization');
-        if (hasAwsSig(auth) || hasAuthorizer(evt))
-            return 'my';
-        if (hasApiKey(evt))
-            return 'private';
-        return 'public';
+const pojofy = (input) => {
+    const seen = new WeakSet();
+    const replacer = (_key, value) => {
+        if (value === null)
+            return null;
+        const t = typeof value;
+        if (t === 'string' || t === 'number' || t === 'boolean')
+            return value;
+        // Eliminate non-JSON scalars
+        if (t === 'undefined' ||
+            t === 'function' ||
+            t === 'symbol' ||
+            t === 'bigint') {
+            return undefined;
+        }
+        // Keep Date as ISO via its built-in toJSON
+        if (value instanceof Date)
+            return value;
+        // Drop common non-JSON containers
+        if (value instanceof Map ||
+            value instanceof Set ||
+            value instanceof WeakMap ||
+            value instanceof WeakSet) {
+            return undefined;
+        }
+        // Drop raw binary; convert typed arrays (incl. Buffer) to JSON-safe arrays
+        if (typeof ArrayBuffer !== 'undefined' && value instanceof ArrayBuffer)
+            return undefined;
+        if (ArrayBuffer.isView(value))
+            return Array.from(value);
+        const obj = value;
+        if (seen.has(obj))
+            return undefined; // eliminate circular refs
+        seen.add(obj);
+        return obj; // let JSON.stringify walk own-enumerable props
+    };
+    return JSON.parse(JSON.stringify(input, replacer));
+};
+
+const assertWithZod = (value, schema, logger, kind) => {
+    if (!schema)
+        return;
+    logger.debug('validating with zod', value);
+    const result = schema.safeParse(value);
+    if (result.success) {
+        logger.debug('zod validation succeeded', pojofy(result));
+        return;
     }
-    return 'public';
+    // Log a structured object for easier debugging.
+    logger.error('zod validation failed', pojofy(result));
+    // Throw a readable error that upstream layers can interpret.
+    // We intentionally use "Invalid event"/"Invalid response" so HTTP mode can map to 400,
+    // while internal mode simply throws.
+    const msg = kind === 'event' ? 'Invalid event' : 'Invalid response';
+    const err = Object.assign(new Error(msg), {
+        name: 'ZodError',
+        issues: result.error.issues,
+    });
+    throw err;
 };
+/**
+ * Validate the *incoming* event before business logic runs, and the *outgoing*
+ * response after it returns (unless a shaped HTTP envelope or a raw string).
+ */
+const httpZodValidator = ({ eventSchema, responseSchema, logger = console, }) => ({
+    before: async (request) => {
+        const event = request.event;
+        assertWithZod(event, eventSchema, logger, 'event');
+    },
+    after: async (request) => {
+        const container = request;
+        const res = container.response;
+        // Skip if the handler already returned a shaped HTTP response...
+        const looksShaped = typeof res === 'object' &&
+            res !== null &&
+            'statusCode' in res &&
+            'headers' in res &&
+            'body' in res;
+        // ...or a raw string (serializer will pass it through).
+        if (looksShaped || typeof res === 'string')
+            return;
+        assertWithZod(res, responseSchema, logger, 'response');
+    },
+});
 
 /**
- * Wrap a business handler with SMOZ runtime. *
- * - HTTP event tokens receive the full Middy pipeline (validation, shaping, CORS, etc.)
- * - Non‑HTTP tokens bypass Middy and call the business function directly.
+ * If the request is HEAD, short-circuit the handler and let the serializer
+ * produce an empty JSON body. This keeps tests and clients predictable.
  *
- * @typeParam GlobalParamsSchema - global params schema type
- * @typeParam StageParamsSchema  - stage params schema type
- * @typeParam EventTypeMap       - event token → runtime type map
- * @typeParam EventType          - a key of EventTypeMap
- * @typeParam EventSchema        - optional Zod schema for event (validated before handler)
- * @typeParam ResponseSchema     - optional Zod schema for response (validated after handler)
- * @param functionConfig - per‑function configuration (branded with env nodes)
- * @param business - the business handler implementation
- * @param opts - optional runtime overrides (e.g., widen HTTP tokens)
- * @returns a Lambda‑compatible handler function
+ * @remarks
+ * This is placed very early in the pipeline. When it sets `request.response`
+ * during `before`, the composed middleware sequence will skip the base handler.
  */
-function wrapHandler(functionConfig, business, opts) {
-    const assertKeysSubset = (schema, keys, label) => {
-        const allowed = new Set(Object.keys(schema.shape));
-        const bad = keys.filter((k) => !allowed.has(k));
-        if (bad.length)
-            throw new Error(`${label} contains unknown keys: ${bad.join(', ')}`);
-    };
-    const envConfig = defineFunctionConfig.getEnvFromFunctionConfig(functionConfig);
-    assertKeysSubset(envConfig.global.paramsSchema, envConfig.global.envKeys, 'global.envKeys');
-    assertKeysSubset(envConfig.stage.paramsSchema, envConfig.stage.envKeys, 'stage.envKeys');
-    return async (event, context) => {
-        // Compose typed env schema and parse process.env
-        const all = envBuilder.deriveAllKeys(envConfig.global.envKeys, envConfig.stage.envKeys, (functionConfig.fnEnvKeys ?? []));
-        const { globalPick, stagePick } = envBuilder.splitKeysBySchema(all, envConfig.global.paramsSchema, envConfig.stage.paramsSchema);
-        const envSchema = envBuilder.buildEnvSchema(globalPick, stagePick, envConfig.global.paramsSchema, envConfig.stage.paramsSchema);
-        const env = envBuilder.parseTypedEnv(envSchema, process.env);
-        const logger = console;
-        // Non-HTTP: call business directly
-        const httpTokens$1 = opts?.httpEventTypeTokens ??
-            httpTokens.defaultHttpEventTypeTokens;
-        const isHttp = httpTokens$1.includes(functionConfig.eventType);
-        if (!isHttp) {
-            return business(event, context, { env, logger });
+const shortCircuitHead = {
+    before: async (request) => {
+        const evt = request.event;
+        const method = (evt.httpMethod ??
+            evt.requestContext?.http?.method ??
+            '').toUpperCase();
+        if (method === 'HEAD') {
+            request.response = {
+                statusCode: 200,
+                headers: {},
+                body: {},
+            };
         }
-        // HTTP: build middleware stack
-        const fnHttp = functionConfig.http;
-        const maybeContentType = functionConfig
-            .contentType;
-        const args = {
-            functionName: functionConfig.functionName,
-            logger,
-            ...(functionConfig.eventSchema
-                ? { eventSchema: functionConfig.eventSchema }
-                : {}),
-            ...(functionConfig.responseSchema
-                ? { responseSchema: functionConfig.responseSchema }
-                : {}),
-            ...(typeof maybeContentType === 'string' && maybeContentType.length > 0
-                ? { contentType: maybeContentType }
-                : {}),
-            ...(opts?.httpConfig ? { app: opts.httpConfig } : {}),
-            ...(fnHttp ? { fn: fnHttp } : {}),
-        };
-        const http = httpStackCustomization.computeHttpMiddleware(args);
-        const wrapped = middy(async (e, c) => business(e, c, {
-            env,
-            logger,
-        })).use(http);
-        return wrapped(event, context);
-    };
-}
+    },
+};
+
+const wrapSerializer = (fn, opts) => {
+    return ((args) => {
+        opts.logger.debug(`serializing ${opts.label} response`);
+        const serialized = fn(args);
+        opts.logger.debug('serialized response', { serialized });
+        return serialized;
+    });
+};
 
-const makeHead = () => transformUtils.tagStep(shortCircuitHead.shortCircuitHead, 'head');
-const makeHeaderNormalizer = (opts) => transformUtils.tagStep(asApiMiddleware.asApiMiddleware(httpHeaderNormalizer(opts?.headerNormalizer ?? { canonical: true })), 'header-normalizer');
-const makeEventNormalizer = () => transformUtils.tagStep(asApiMiddleware.asApiMiddleware(httpEventNormalizer()), 'event-normalizer');
+const makeHead = () => tagStep(shortCircuitHead, 'head');
+const makeHeaderNormalizer = (opts) => tagStep(asApiMiddleware(httpHeaderNormalizer(opts?.headerNormalizer ?? { canonical: true })), 'header-normalizer');
+const makeEventNormalizer = () => tagStep(asApiMiddleware(httpEventNormalizer()), 'event-normalizer');
 const makeContentNegotiation = (contentType, opts) => {
     const availableMediaTypes = [contentType];
     const merged = {
@@ -437,10 +376,10 @@ const makeContentNegotiation = (contentType, opts) => {
         availableMediaTypes,
         ...(opts?.contentNegotiation ?? {}),
     };
-    return transformUtils.tagStep(asApiMiddleware.asApiMiddleware(httpContentNegotiation(merged)), 'content-negotiation');
+    return tagStep(asApiMiddleware(httpContentNegotiation(merged)), 'content-negotiation');
 };
 const makeJsonBodyParser = (opts) => {
-    const inner = asApiMiddleware.asApiMiddleware(httpJsonBodyParser({
+    const inner = asApiMiddleware(httpJsonBodyParser({
         disableContentTypeError: true,
         ...(opts?.jsonBodyParser ?? {}),
     }));
@@ -461,29 +400,29 @@ const makeJsonBodyParser = (opts) => {
         if (inner.before)
             await inner.before(request);
     };
-    return transformUtils.tagStep(mw, 'json-body-parser');
+    return tagStep(mw, 'json-body-parser');
 };
 const makeZodBefore = (logger, eventSchema) => {
-    const base = httpZodValidator.httpZodValidator({
+    const base = httpZodValidator({
         logger,
         ...(eventSchema ? { eventSchema } : {}),
     });
     const mw = {};
     if (base.before)
         mw.before = base.before;
-    return transformUtils.tagStep(mw, 'zod-before');
+    return tagStep(mw, 'zod-before');
 };
 const makeZodAfter = (logger, responseSchema) => {
-    const base = httpZodValidator.httpZodValidator({
+    const base = httpZodValidator({
         logger,
         ...(responseSchema ? { responseSchema } : {}),
     });
     const mw = {};
     if (base.after)
         mw.after = base.after;
-    return transformUtils.tagStep(mw, 'zod-after');
+    return tagStep(mw, 'zod-after');
 };
-const makeHeadFinalize = (contentType) => transformUtils.tagStep({
+const makeHeadFinalize = (contentType) => tagStep({
     after: (request) => {
         const evt = request
             .event;
@@ -501,7 +440,7 @@ const makeHeadFinalize = (contentType) => transformUtils.tagStep({
         };
     },
 }, 'head-finalize');
-const makePreferredMedia = (contentType) => transformUtils.tagStep({
+const makePreferredMedia = (contentType) => tagStep({
     before: (request) => {
         const req = request;
         if (!Array.isArray(req.preferredMediaTypes))
@@ -524,7 +463,7 @@ const makePreferredMedia = (contentType) => transformUtils.tagStep({
             req.preferredMediaTypes = [contentType];
     },
 }, 'preferred-media');
-const makeErrorExpose = (logger) => transformUtils.tagStep({
+const makeErrorExpose = (logger) => tagStep({
     onError: (request) => {
         const maybe = request.error;
         if (!(maybe instanceof Error))
@@ -539,7 +478,7 @@ const makeErrorExpose = (logger) => transformUtils.tagStep({
         }
     },
 }, 'error-expose');
-const makeErrorHandler = (opts) => transformUtils.tagStep(asApiMiddleware.asApiMiddleware(httpErrorHandler({
+const makeErrorHandler = (opts) => tagStep(asApiMiddleware(httpErrorHandler({
     ...(opts?.errorHandler ?? {}),
     logger: (o) => {
         const lg = opts?.logger ?? console;
@@ -547,12 +486,12 @@ const makeErrorHandler = (opts) => transformUtils.tagStep(asApiMiddleware.asApiM
             lg.error(o);
     },
 })), 'error-handler');
-const makeCors = (opts) => transformUtils.tagStep(asApiMiddleware.asApiMiddleware(httpCors({
+const makeCors = (opts) => tagStep(asApiMiddleware(httpCors({
     credentials: true,
     getOrigin: (o) => o,
     ...(opts?.cors ?? {}),
 })), 'cors');
-const makeShapeAndContentType = (contentType) => transformUtils.tagStep({
+const makeShapeAndContentType = (contentType) => tagStep({
     after: (request) => {
         const container = request;
         const current = container.response;
@@ -582,11 +521,11 @@ const makeShapeAndContentType = (contentType) => transformUtils.tagStep({
         request.response = res;
     },
 }, 'shape');
-const makeSerializer = (contentType, opts) => transformUtils.tagStep(asApiMiddleware.asApiMiddleware(httpResponseSerializer({
+const makeSerializer = (contentType, opts) => tagStep(asApiMiddleware(httpResponseSerializer({
     serializers: [
         {
             regex: /^application\/(?:[a-z0-9.+-]*\+)?json$/i,
-            serializer: wrapSerializer.wrapSerializer(({ body }) => typeof body === 'string'
+            serializer: wrapSerializer(({ body }) => typeof body === 'string'
                 ? body
                 : (opts?.serializer?.json?.stringify ?? JSON.stringify)(body), {
                 label: opts?.serializer?.json?.label ?? 'json',
@@ -620,47 +559,790 @@ const buildDefaultPhases = (args) => {
 };
 const buildSafeDefaults = (args) => buildDefaultPhases(args);
 
-const ID_PROP = '__id';
-/** Attach a non-enumerable __id to a middleware step. */
-const tagStep = (mw, id) => {
-    if (!Object.prototype.hasOwnProperty.call(mw, ID_PROP)) {
-        Object.defineProperty(mw, ID_PROP, { value: id, enumerable: false });
-    }
-    return mw;
+/** Shallow merge HttpStackOptions left→right. */
+const mergeOptions = (a, b) => ({ ...(a ?? {}), ...(b ?? {}) });
+/** Apply extend lists (append in order) */
+const applyExtend = (phases, ext) => {
+    if (!ext)
+        return;
+    if (ext.before?.length)
+        phases.before = [...phases.before, ...ext.before];
+    if (ext.after?.length)
+        phases.after = [...phases.after, ...ext.after];
+    if (ext.onError?.length)
+        phases.onError = [...phases.onError, ...ext.onError];
 };
-/** Retrieve a step's id, if present. */
-const getId = (mw) => mw[ID_PROP];
-/** Find index of a step by id. */
-const findIndex = (list, id) => list.findIndex((m) => getId(m) === id);
-/** Insert a step before the step with given id. */
-const insertBefore = (list, id, mw) => {
-    const i = findIndex(list, id);
-    if (i < 0)
-        return list.slice();
-    return [...list.slice(0, i), mw, ...list.slice(i)];
+/** Apply transform callback and validate invariants. */
+const applyTransform = (phases, transform) => {
+    if (!transform)
+        return phases;
+    const next = transform({
+        before: phases.before.slice(),
+        after: phases.after.slice(),
+        onError: phases.onError.slice(),
+    });
+    const out = {
+        before: next.before ?? phases.before,
+        after: next.after ?? phases.after,
+        onError: next.onError ?? phases.onError,
+    };
+    assertInvariants(out);
+    return out;
 };
-/** Insert a step after the step with given id. */
-const insertAfter = (list, id, mw) => {
-    const i = findIndex(list, id);
-    if (i < 0)
-        return list.slice();
-    return [...list.slice(0, i + 1), mw, ...list.slice(i + 1)];
+/** Zod enforcement per spec. */
+const enforceZod = (phases, hasSchemas, fnName) => {
+    if (!hasSchemas)
+        return;
+    const hasBefore = phases.before.some((m) => getId(m) === 'zod-before');
+    const hasAfter = phases.after.some((m) => getId(m) === 'zod-after');
+    if (!hasBefore || !hasAfter) {
+        throw new Error(`Zod validation is required (schemas provided) but is missing after stack customization on function '${fnName}'. ` +
+            `Include the standard httpZodValidator or tag your custom validator steps as 'zod-before' and 'zod-after'.`);
+    }
 };
-/** Replace a step with given id. */
-const replaceStep = (list, id, mw) => {
-    const i = findIndex(list, id);
-    if (i < 0)
-        return list.slice();
-    const out = list.slice();
-    out[i] = mw;
+/** Compute final stack given app-level and function-level customization. */
+const computeHttpMiddleware = (args) => {
+    const { functionName, eventSchema, responseSchema, logger: maybeLogger, contentType: maybeContentType, app, fn, } = args;
+    const baseContentType = (maybeContentType ?? 'application/json').toLowerCase();
+    let effective = {
+        contentType: baseContentType,
+        logger: maybeLogger ?? console,
+    };
+    // Layer A: app.defaults.options
+    effective = mergeOptions(effective, app?.defaults);
+    // Apply profile (options)
+    const profile = fn?.profile ? app?.profiles?.[fn.profile] : undefined;
+    effective = mergeOptions(effective, profile);
+    // Function-level options
+    effective = mergeOptions(effective, fn?.options);
+    const contentType = (effective.contentType ?? baseContentType).toLowerCase();
+    const logger = effective.logger ?? console;
+    // Build default phases with resolved options
+    let phases = buildDefaultPhases({
+        contentType,
+        logger,
+        opts: effective,
+        eventSchema,
+        responseSchema,
+    });
+    // Layer B: extend (app.defaults → profile → function)
+    applyExtend(phases, app?.defaults?.extend);
+    applyExtend(phases, profile?.extend);
+    applyExtend(phases, fn?.extend);
+    // Layer C: transform (app.defaults → profile → function)
+    phases = applyTransform(phases, app?.defaults?.transform);
+    phases = applyTransform(phases, profile?.transform);
+    phases = applyTransform(phases, fn?.transform);
+    // Invariants (pre-replace)
+    assertInvariants(phases);
+    // Zod enforcement (pre-replace)
+    enforceZod(phases, !!(eventSchema || responseSchema), functionName);
+    // Layer D: replace (full override)
+    if (fn?.replace?.stack) {
+        const rep = fn.replace.stack;
+        if (typeof rep === 'object' &&
+            'before' in rep) {
+            const p = rep;
+            const final = {
+                before: p.before ?? [],
+                after: p.after ?? [],
+                onError: p.onError ?? [],
+            };
+            assertInvariants(final);
+            enforceZod(final, !!(eventSchema || responseSchema), functionName);
+            return combine(...final.before, ...final.after, ...final.onError);
+        }
+        // Single middleware replacement: cannot validate presence of zod steps.
+        if (eventSchema || responseSchema) {
+            throw new Error(`Full replace provided as a single middleware object on function '${functionName}', but schemas are present. ` +
+                `To satisfy Zod enforcement, provide phased arrays including steps tagged as 'zod-before' and 'zod-after'.`);
+        }
+        return rep;
+    }
+    // Compose final combined stack
+    return combine(...phases.before, ...phases.after, ...phases.onError);
+};
+
+/** Union all env keys we plan to expose into a single set. */
+/**
+ * Derive the union of env keys we plan to expose.
+ *
+ * @param globalEnv - keys exposed from global params schema
+ * @param stageEnv  - keys exposed from stage params schema
+ * @param fnEnv     - optional per‑function extra keys
+ */
+const deriveAllKeys = (globalEnv, stageEnv, fnEnv = []) => {
+    const out = new Set();
+    globalEnv.forEach((k) => out.add(k));
+    stageEnv.forEach((k) => out.add(k));
+    fnEnv.forEach((k) => out.add(k));
     return out;
 };
-/** Remove a step with given id. */
-const removeStep = (list, id) => {
-    const i = findIndex(list, id);
-    if (i < 0)
-        return list.slice();
-    return [...list.slice(0, i), ...list.slice(i + 1)];
+/** Split the unioned keys by which Zod schema defines them. */
+/**
+ * Partition a union of env keys by which schema defines each key.
+ *
+ * @typeParam G - global params Zod object schema
+ * @typeParam S - stage params Zod object schema
+ * @param allKeys - union set from {@link deriveAllKeys}
+ * @param globalParamsSchema - global schema
+ * @param stageParamsSchema  - stage schema
+ * @returns lists of keys to pick from each schema
+ */
+const splitKeysBySchema = (allKeys, globalParamsSchema, stageParamsSchema) => {
+    const gKeySet = new Set(Object.keys(globalParamsSchema.shape));
+    const sKeySet = new Set(Object.keys(stageParamsSchema.shape));
+    const globalPick = [...allKeys].filter((k) => gKeySet.has(String(k)));
+    const stagePick = [...allKeys].filter((k) => {
+        const key = String(k);
+        return sKeySet.has(key) && !gKeySet.has(key);
+    });
+    return { globalPick, stagePick };
+};
+/** Build a Zod schema that picks only the requested keys from both schemas. */
+/**
+ * Build a composed Zod schema to parse process.env, selecting keys from global+stage schemas.
+ *
+ * @typeParam G - global params Zod schema
+ * @typeParam S - stage params Zod schema
+ * @param globalPick - keys to select from global schema
+ * @param stagePick  - keys to select from stage schema
+ * @param globalParamsSchema - global params schema
+ * @param stageParamsSchema  - stage params schema
+ * @returns Zod object schema accepting the union of selected keys
+ */
+const buildEnvSchema = (globalPick, stagePick, globalParamsSchema, stageParamsSchema) => {
+    const toPick = (keys) => Object.fromEntries(keys.map((k) => [k, true]));
+    const gPicked = globalParamsSchema.pick(toPick(globalPick));
+    const sPicked = stageParamsSchema.pick(toPick(stagePick));
+    return zod.z.object({}).extend(gPicked.shape).extend(sPicked.shape);
+};
+/** Parse an arbitrary source (e.g., process.env) with a provided env schema. */
+/**
+ * Parse an arbitrary env source (e.g., process.env) with a provided schema.
+ *
+ * @param envSchema - Zod schema from {@link buildEnvSchema}
+ * @param envSource - map of environment variables
+ */
+const parseTypedEnv = (envSchema, envSource) => envSchema.parse(envSource);
+
+/**
+ * Wrap a business handler with SMOZ runtime. *
+ * - HTTP event tokens receive the full Middy pipeline (validation, shaping, CORS, etc.)
+ * - Non‑HTTP tokens bypass Middy and call the business function directly.
+ *
+ * @typeParam GlobalParamsSchema - global params schema type
+ * @typeParam StageParamsSchema  - stage params schema type
+ * @typeParam EventTypeMap       - event token → runtime type map
+ * @typeParam EventType          - a key of EventTypeMap
+ * @typeParam EventSchema        - optional Zod schema for event (validated before handler)
+ * @typeParam ResponseSchema     - optional Zod schema for response (validated after handler)
+ * @param functionConfig - per‑function configuration (branded with env nodes)
+ * @param business - the business handler implementation
+ * @param opts - optional runtime overrides (e.g., widen HTTP tokens)
+ * @returns a Lambda‑compatible handler function
+ */
+function wrapHandler(functionConfig, business, opts) {
+    const assertKeysSubset = (schema, keys, label) => {
+        const allowed = new Set(Object.keys(schema.shape));
+        const bad = keys.filter((k) => !allowed.has(k));
+        if (bad.length)
+            throw new Error(`${label} contains unknown keys: ${bad.join(', ')}`);
+    };
+    const envConfig = getEnvFromFunctionConfig(functionConfig);
+    assertKeysSubset(envConfig.global.paramsSchema, envConfig.global.envKeys, 'global.envKeys');
+    assertKeysSubset(envConfig.stage.paramsSchema, envConfig.stage.envKeys, 'stage.envKeys');
+    return async (event, context) => {
+        // Compose typed env schema and parse process.env
+        const all = deriveAllKeys(envConfig.global.envKeys, envConfig.stage.envKeys, (functionConfig.fnEnvKeys ?? []));
+        const { globalPick, stagePick } = splitKeysBySchema(all, envConfig.global.paramsSchema, envConfig.stage.paramsSchema);
+        const envSchema = buildEnvSchema(globalPick, stagePick, envConfig.global.paramsSchema, envConfig.stage.paramsSchema);
+        const env = parseTypedEnv(envSchema, process.env);
+        const logger = console;
+        // Non-HTTP: call business directly
+        const httpTokens = opts?.httpEventTypeTokens ??
+            defaultHttpEventTypeTokens;
+        const isHttp = httpTokens.includes(functionConfig.eventType);
+        if (!isHttp) {
+            return business(event, context, { env, logger });
+        }
+        // HTTP: build middleware stack
+        const fnHttp = functionConfig.http;
+        const maybeContentType = functionConfig
+            .contentType;
+        const args = {
+            functionName: functionConfig.functionName,
+            logger,
+            ...(functionConfig.eventSchema
+                ? { eventSchema: functionConfig.eventSchema }
+                : {}),
+            ...(functionConfig.responseSchema
+                ? { responseSchema: functionConfig.responseSchema }
+                : {}),
+            ...(typeof maybeContentType === 'string' && maybeContentType.length > 0
+                ? { contentType: maybeContentType }
+                : {}),
+            ...(opts?.httpConfig ? { app: opts.httpConfig } : {}),
+            ...(fnHttp ? { fn: fnHttp } : {}),
+        };
+        const http = computeHttpMiddleware(args);
+        const wrapped = middy(async (e, c) => business(e, c, {
+            env,
+            logger,
+        })).use(http);
+        return wrapped(event, context);
+    };
+}
+
+const handlerFactory = (httpEventTypeTokens, httpConfig) => {
+    return (functionConfig, business) => wrapHandler(functionConfig, business, {
+        httpEventTypeTokens,
+        httpConfig,
+    });
+};
+
+const createRegistry = (deps) => {
+    const map = new Map();
+    return {
+        defineFunction(options) {
+            const key = options.functionName;
+            if (map.has(key)) {
+                const other = map.get(key);
+                throw new Error(`Duplicate functionName "${key}". Existing: ${other.callerModuleUrl}. New: ${options.callerModuleUrl}. Provide a unique functionName.`);
+            }
+            // Merge default fnEnvKeys with per-function keys (unique, preserve order).
+            const mergedFnEnvKeys = (() => {
+                const out = new Set();
+                (deps.functionDefaults?.fnEnvKeys ?? []).forEach((k) => out.add(k));
+                (options.fnEnvKeys ?? []).forEach((k) => out.add(k));
+                return Array.from(out);
+            })();
+            const brandedConfig = {
+                functionName: options.functionName,
+                eventType: options.eventType,
+                ...(options.method ? { method: options.method } : {}),
+                ...(options.basePath ? { basePath: options.basePath } : {}),
+                ...(options.httpContexts ? { httpContexts: options.httpContexts } : {}),
+                ...(options.contentType ? { contentType: options.contentType } : {}),
+                ...(mergedFnEnvKeys.length
+                    ? { fnEnvKeys: mergedFnEnvKeys }
+                    : {}),
+                ...(options.eventSchema ? { eventSchema: options.eventSchema } : {}),
+                ...(options.responseSchema
+                    ? { responseSchema: options.responseSchema }
+                    : {}),
+                [ENV_CONFIG]: {
+                    global: deps.env.global,
+                    stage: deps.env.stage,
+                },
+            };
+            map.set(key, {
+                functionName: options.functionName,
+                eventType: options.eventType,
+                ...(options.method ? { method: options.method } : {}),
+                ...(options.basePath ? { basePath: options.basePath } : {}),
+                ...(options.httpContexts ? { httpContexts: options.httpContexts } : {}),
+                ...(options.contentType ? { contentType: options.contentType } : {}),
+                ...(mergedFnEnvKeys.length
+                    ? { fnEnvKeys: mergedFnEnvKeys }
+                    : {}),
+                ...(options.eventSchema ? { eventSchema: options.eventSchema } : {}),
+                ...(options.responseSchema
+                    ? { responseSchema: options.responseSchema }
+                    : {}),
+                callerModuleUrl: options.callerModuleUrl,
+                endpointsRootAbs: options.endpointsRootAbs,
+                brandedConfig,
+            });
+            return {
+                handler: (business) => {
+                    const fnConfig = brandedConfig;
+                    const make = handlerFactory(deps.httpEventTypeTokens, deps.http);
+                    return make(fnConfig, business);
+                },
+                openapi: (baseOperation) => {
+                    const r = map.get(key);
+                    r.openapiBaseOperation = baseOperation;
+                },
+                serverless: (extras) => {
+                    const r = map.get(key);
+                    r.serverlessExtras = extras;
+                },
+            };
+        },
+        values() {
+            return map.values();
+        },
+    };
+};
+
+/**
+ * Zod schema for implementation-wide Serverless config.
+ *
+ * Extracted to keep App.ts slim and focused on orchestration.
+ */
+const serverlessConfigSchema = zod.z.object({
+    /** Context -> event fragment to merge into generated http events */
+    httpContextEventMap: zod.z.custom(),
+    /** Used to construct default handler string if missing on a function */
+    defaultHandlerFileName: zod.z.string().min(1),
+    defaultHandlerFileExport: zod.z.string().min(1),
+});
+
+const splitPath = (basePath) => basePath.split('/').filter(Boolean);
+/** Prefix non-public contexts and return path elements. */
+/**
+ * Build OpenAPI/serverless path elements from a base path and context.
+ *
+ * @param basePath - base path (e.g., 'users/:id')
+ * @param context  - 'my' | 'private' | 'public' (public is unprefixed)
+ * @returns array of path segments without leading/trailing slashes
+ */
+const buildPathElements = (basePath, context) => {
+    const parts = splitPath(sanitizeBasePath(basePath));
+    return context === 'public' ? parts : [context, ...parts];
+};
+const sanitizeBasePath = (p) => p.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+
+const HTTP_METHODS = new Set([
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace',
+]);
+/**
+ * Resolve `(method, basePath, contexts)` for an HTTP function definition.
+ *
+ * @typeParam EventSchema    - optional event Zod schema
+ * @typeParam ResponseSchema - optional response Zod schema
+ * @typeParam GlobalParams   - app global params type
+ * @typeParam StageParams    - app stage params type
+ * @typeParam EventTypeMap   - event type token map
+ * @typeParam EventType      - selected event token
+ * @param functionConfig - the per‑function config (may omit method/basePath)
+ * @param callerModuleUrl - import.meta.url of the registering module
+ * @param endpointsRootAbs - absolute root of endpoints
+ * @throws Error if method/basePath cannot be inferred under endpoints root
+ * @returns HTTP method key, basePath, and unique contexts list
+ */
+const resolveHttpFromFunctionConfig = (functionConfig, callerModuleUrl, endpointsRootAbs) => {
+    const { method: maybeMethod, basePath: maybeBase, httpContexts, } = functionConfig;
+    // Compute relative path from endpoints root to the caller directory
+    const relPath = path.relative(endpointsRootAbs, path.dirname(node_url.fileURLToPath(callerModuleUrl)))
+        .split(path.sep)
+        .join('/');
+    const underEndpointsRoot = !relPath.startsWith('..');
+    let method;
+    if (maybeMethod && HTTP_METHODS.has(maybeMethod)) {
+        method = maybeMethod;
+    }
+    else {
+        if (!underEndpointsRoot) {
+            throw new Error('resolveHttpFromFunctionConfig: method missing and caller is not under endpoints root; provide method explicitly.');
+        }
+        const segs = relPath.split('/').filter(Boolean);
+        const tail = segs[segs.length - 1]?.toLowerCase();
+        if (HTTP_METHODS.has(tail))
+            method = tail;
+        else
+            throw new Error('resolveHttpFromFunctionConfig: cannot infer method from folder; provide method explicitly.');
+    }
+    let basePath = sanitizeBasePath(maybeBase ?? '');
+    if (!basePath) {
+        if (!underEndpointsRoot) {
+            throw new Error('resolveHttpFromFunctionConfig: basePath missing and caller is not under endpoints root; provide basePath explicitly.');
+        }
+        const segs = relPath.split('/').filter(Boolean);
+        if (segs.length && segs[segs.length - 1]?.toLowerCase() === method)
+            segs.pop();
+        basePath = segs.join('/');
+    }
+    if (!basePath) {
+        throw new Error('resolveHttpFromFunctionConfig: derived basePath is empty; ensure file is under endpoints root or set config.basePath.');
+    }
+    const contexts = radash.unique(httpContexts ?? []);
+    return { method, basePath, contexts };
+};
+
+const buildAllOpenApiPaths = (registry) => {
+    const paths = {};
+    for (const r of registry) {
+        if (!r.openapiBaseOperation)
+            continue;
+        const { method, basePath, contexts } = resolveHttpFromFunctionConfig({
+            functionName: r.functionName,
+            eventType: r.eventType,
+            ...(r.method ? { method: r.method } : {}),
+            ...(r.basePath ? { basePath: r.basePath } : {}),
+            ...(r.httpContexts ? { httpContexts: r.httpContexts } : {}),
+        }, r.callerModuleUrl, r.endpointsRootAbs);
+        const ctxs = contexts.length > 0 ? contexts : ['public'];
+        for (const context of ctxs) {
+            const elems = buildPathElements(basePath, context);
+            const pathKey = `/${elems.join('/')}`;
+            const op = {
+                ...r.openapiBaseOperation,
+                operationId: [...elems, method].join('_'),
+                summary: `${r.openapiBaseOperation.summary} (${context})`,
+                tags: Array.from(new Set([...(r.openapiBaseOperation.tags ?? []), context])),
+            };
+            const existing = pathKey in paths ? paths[pathKey] : {};
+            paths[pathKey] = { ...existing, [method]: op };
+        }
+    }
+    return paths;
+};
+
+/**
+ * Registry → Serverless functions aggregator.
+ *
+ * @returns NonNullable<AWS['functions']> with HTTP/non‑HTTP events attached.
+ */
+const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
+    const out = {};
+    const repoRoot = packageDirectory.packageDirectorySync();
+    for (const r of registry) {
+        const callerDir = path.dirname(node_url.fileURLToPath(r.callerModuleUrl));
+        const handlerFileAbs = path.join(callerDir, serverless.defaultHandlerFileName);
+        const handlerFileRel = path.relative(repoRoot, handlerFileAbs)
+            .split(path.sep)
+            .join('/');
+        const handler = `${handlerFileRel}.${serverless.defaultHandlerFileExport}`;
+        let events = [];
+        try {
+            const { method, basePath, contexts } = resolveHttpFromFunctionConfig({
+                functionName: r.functionName,
+                eventType: r.eventType,
+                ...(r.method ? { method: r.method } : {}),
+                ...(r.basePath ? { basePath: r.basePath } : {}),
+                ...(r.httpContexts ? { httpContexts: r.httpContexts } : {}),
+            }, r.callerModuleUrl, r.endpointsRootAbs);
+            const path = `/${basePath.replace(/^\/+/, '')}`;
+            const ctxs = contexts.length > 0 ? contexts : ['public'];
+            events = ctxs.map(() => ({
+                http: { method, path },
+            }));
+        }
+        catch {
+            events = r.serverlessExtras ?? [];
+        }
+        const def = {
+            handler,
+            events,
+            environment: buildFnEnv((r.fnEnvKeys ?? [])),
+        };
+        out[r.functionName] = def;
+    }
+    return out;
+};
+
+/**
+ * App (schema‑first)
+ *
+ * Central orchestrator for a SMOZ application. You provide:
+ * - Global/stage parameter schemas and env exposure keys
+ * - Serverless defaults (handler filename/export and context map)
+ * - Event‑type map schema (extendable: e.g., add 'step')
+ *
+ * The instance:
+ * - Validates configuration
+ * - Exposes env and stage artifacts for Serverless (provider.environment and params)
+ * - Provides a registry to define functions (HTTP and non‑HTTP)
+ * - Aggregates artifacts:
+ *   - buildAllServerlessFunctions(): AWS['functions']
+ *   - buildAllOpenApiPaths(): ZodOpenApiPathsObject
+ *
+ * @remarks See README for a full quick‑start, and typedoc for detailed API docs.
+ */
+/**
+ * Application class. *
+ * @typeParam GlobalParamsSchema - Zod object schema for global parameters
+ * @typeParam StageParamsSchema  - Zod object schema for per‑stage parameters
+ * @typeParam EventTypeMapSchema - Zod object schema mapping event tokens to runtime types
+ */ class App {
+    /** Helper alias for stage artifacts type */
+    static _stageArtifactsType = null;
+    appRootAbs;
+    // Schemas
+    globalParamsSchema;
+    stageParamsSchema;
+    eventTypeMapSchema; // Serverless config
+    serverless;
+    // Env exposure
+    global;
+    stage;
+    // Derived stage artifacts
+    stages;
+    environment;
+    buildFnEnv;
+    http;
+    // HTTP tokens for runtime decision
+    httpEventTypeTokens;
+    // Registry (delegated to src/app/registry)
+    registry;
+    constructor(init) {
+        this.appRootAbs = init.appRootAbs.replace(/\\/g, '/');
+        this.globalParamsSchema = init.globalParamsSchema;
+        this.stageParamsSchema = init.stageParamsSchema;
+        // Default to base schema when omitted (apply default INSIDE the function)
+        this.eventTypeMapSchema = (init.eventTypeMapSchema ??
+            baseEventTypeMapSchema);
+        // Parse serverless input internally
+        this.serverless = serverlessConfigSchema.parse(init.serverless);
+        // Validate that eventTypeMapSchema includes base keys at runtime
+        validateEventTypeMapSchemaIncludesBase(this.eventTypeMapSchema.shape);
+        // Env exposure nodes
+        this.global = {
+            paramsSchema: this.globalParamsSchema,
+            envKeys: init.global.envKeys,
+        };
+        this.stage = {
+            paramsSchema: this.stageParamsSchema,
+            envKeys: init.stage.envKeys,
+        };
+        // Build stages/environment/fn-env via helper (applies “stage extends global” and parsing)
+        const { stages, environment, buildFnEnv } = buildStageArtifacts(this.globalParamsSchema, this.stageParamsSchema, { params: init.global.params, envKeys: init.global.envKeys }, { params: init.stage.params, envKeys: init.stage.envKeys });
+        this.stages = stages;
+        this.environment = environment;
+        this.buildFnEnv = buildFnEnv;
+        // HTTP tokens (runtime decision)
+        this.httpEventTypeTokens = (init.httpEventTypeTokens ??
+            defaultHttpEventTypeTokens);
+        // App-level HTTP customization
+        this.http = init.http ?? {};
+        // Initialize function registry
+        this.registry = createRegistry({
+            httpEventTypeTokens: this.httpEventTypeTokens,
+            env: { global: this.global, stage: this.stage },
+            http: this.http,
+            // With exactOptionalPropertyTypes, do not pass an explicit undefined.
+            ...(init.functionDefaults
+                ? { functionDefaults: init.functionDefaults }
+                : {}),
+        });
+    } /**
+     * Ergonomic constructor for schema‑first inference.
+     *
+     * @param init - initialization object (schemas, serverless defaults, params/envKeys)
+     * @returns a new App instance
+     */
+    static create(init) {
+        return new App(init);
+    }
+    /**
+     * Register a function (HTTP or non‑HTTP).
+     *
+     * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
+     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
+     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
+     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
+     * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
+     */
+    defineFunction(options) {
+        const functionName = options.functionName ??
+            (() => {
+                const callerDir = path.dirname(node_url.fileURLToPath(options.callerModuleUrl));
+                const rel = path.relative(this.appRootAbs, callerDir).split(path.sep).join('/');
+                const parts = rel.split('/').filter(Boolean);
+                // Drop leading 'app' segment if present, per repo convention
+                if (parts[0] === 'app')
+                    parts.shift();
+                return parts.join('_'); // underscore formatting
+            })();
+        return this.registry.defineFunction({
+            functionName,
+            eventType: options.eventType,
+            ...(options.method ? { method: options.method } : {}),
+            ...(options.basePath ? { basePath: options.basePath } : {}),
+            ...(options.httpContexts ? { httpContexts: options.httpContexts } : {}),
+            ...(options.contentType ? { contentType: options.contentType } : {}),
+            ...(options.eventSchema ? { eventSchema: options.eventSchema } : {}),
+            ...(options.responseSchema
+                ? { responseSchema: options.responseSchema }
+                : {}),
+            ...(options.fnEnvKeys ? { fnEnvKeys: options.fnEnvKeys } : {}),
+            callerModuleUrl: options.callerModuleUrl,
+            endpointsRootAbs: options.endpointsRootAbs,
+        });
+    }
+    /**
+     * Aggregate Serverless function definitions across the registry.
+     *
+     * @returns An AWS['functions'] object suitable for serverless.ts
+     */
+    buildAllServerlessFunctions() {
+        return buildAllServerlessFunctions(this.registry.values(), this.serverless, this.buildFnEnv);
+    }
+    /**
+     * Aggregate OpenAPI path items across the registry.
+     *
+     * @returns ZodOpenApiPathsObject to be embedded in a full OpenAPI document
+     */
+    buildAllOpenApiPaths() {
+        return buildAllOpenApiPaths(this.registry.values());
+    }
+}
+
+/**
+ * Define a complete application configuration from schemas and authoring input.
+ *
+ * @typeParam GlobalParamsSchema - Global params schema
+ * @typeParam StageParamsSchema  - Per‑stage params schema
+ * @param globalParamsSchema - schema for global params
+ * @param stageParamsSchema  - schema for stage params
+ * @param input - serverless defaults and concrete params + env exposure
+ * @returns Typed configuration nodes and stage artifacts
+ * * @throws Error if envKeys include keys not present in their corresponding schema
+ */
+function defineAppConfig(globalParamsSchema, stageParamsSchema, input) {
+    const assertKeysSubset = (schema, keys, label) => {
+        const allowed = new Set(Object.keys(schema.shape));
+        const bad = keys.filter((k) => !allowed.has(k));
+        if (bad.length)
+            throw new Error(`${label} contains unknown keys: ${bad.join(', ')}`);
+    };
+    assertKeysSubset(globalParamsSchema, input.global.envKeys, 'global.envKeys');
+    assertKeysSubset(stageParamsSchema, input.stage.envKeys, 'stage.envKeys');
+    const sf = stagesFactory({
+        globalParamsSchema,
+        stageParamsSchema,
+        globalParams: input.global.params,
+        globalEnvKeys: input.global.envKeys,
+        stageEnvKeys: input.stage.envKeys,
+        stages: input.stage.params,
+    });
+    return {
+        serverless: input.serverless,
+        global: { paramsSchema: globalParamsSchema, envKeys: input.global.envKeys },
+        stage: { paramsSchema: stageParamsSchema, envKeys: input.stage.envKeys },
+        stages: sf.stages,
+        environment: sf.environment,
+        buildFnEnv: sf.buildFnEnv,
+    };
+}
+
+/** Narrow to API Gateway v1 events with safe property checks. */
+/**
+ * Type guard for API Gateway v1 events. *
+ * @param evt - unknown event
+ * @returns true if the event looks like a v1 APIGatewayProxyEvent
+ */
+const isV1 = (evt) => {
+    if (typeof evt !== 'object' || evt === null)
+        return false;
+    return 'httpMethod' in evt && 'requestContext' in evt;
+};
+/** Narrow to API Gateway v2 events with safe property checks. */
+/**
+ * Type guard for API Gateway v2 events.
+ */
+const isV2 = (evt) => {
+    if (typeof evt !== 'object' || evt === null)
+        return false;
+    if (!('version' in evt) || !('requestContext' in evt))
+        return false;
+    const rc = evt.requestContext;
+    return (!!rc && typeof rc === 'object' && 'http' in rc);
+};
+/** Case-insensitive single-value header lookup. */
+const getHeader = (headers, key) => {
+    if (!headers)
+        return undefined;
+    const direct = headers[key];
+    if (typeof direct === 'string')
+        return direct;
+    const found = Object.keys(headers).find((k) => k.toLowerCase() === key.toLowerCase());
+    return found ? headers[found] : undefined;
+};
+/** Case-insensitive multi-value header lookup. */
+const getMultiHeader = (headers, key) => {
+    if (!headers)
+        return undefined;
+    const direct = headers[key];
+    if (Array.isArray(direct) && direct.length > 0)
+        return direct[0];
+    const found = Object.keys(headers).find((k) => k.toLowerCase() === key.toLowerCase());
+    return found ? headers[found]?.[0] : undefined;
+};
+/** Get a header value from either single- or multi-value maps. */
+const getHeaderFromEvent = (evt, key) => {
+    const single = getHeader(evt.headers, key);
+    if (typeof single === 'string')
+        return single;
+    const multi = getMultiHeader(evt
+        .multiValueHeaders, key);
+    return multi;
+};
+const hasAwsSig = (auth) => typeof auth === 'string' && auth.startsWith('AWS4-HMAC-SHA256');
+const hasV1AccessKey = (evt) => {
+    const rc = evt.requestContext;
+    const ak = rc.identity?.accessKey;
+    return typeof ak === 'string' && ak.length > 0;
+};
+const hasAuthorizer = (evt) => {
+    // V1: any truthy authorizer object indicates an authenticated request
+    if (isV1(evt)) {
+        const rc = evt.requestContext;
+        return !!rc.authorizer;
+    }
+    // V2: authorizer may include jwt/iam/lambda shapes
+    const authHeader = getHeaderFromEvent(evt, 'authorization');
+    if (hasAwsSig(authHeader))
+        return true;
+    const rc = evt
+        .requestContext;
+    const { authorizer } = rc;
+    if (!authorizer || typeof authorizer !== 'object')
+        return false;
+    const a = authorizer;
+    return !!(a.jwt || a.iam || a.lambda);
+};
+/** Detect API key via header or v1 identity.apiKey. */
+const hasApiKey = (evt) => {
+    const fromHeader = getHeaderFromEvent(evt, 'x-api-key');
+    if (typeof fromHeader === 'string')
+        return true;
+    // Some v1 events surface API key on requestContext.identity.apiKey
+    if (isV1(evt)) {
+        const rc = evt.requestContext;
+        const identKey = rc.identity?.apiKey;
+        if (typeof identKey === 'string' && identKey.length > 0)
+            return true;
+        const identKeyId = rc.identity?.apiKeyId;
+        if (typeof identKeyId === 'string' && identKeyId.length > 0)
+            return true;
+    }
+    return false;
+};
+/** Classify the security context from either API Gateway event version. */
+/**
+ * Detect security context from API Gateway v1/v2 events.
+ *
+ * @param evt - unknown event
+ * @returns 'my' when authorized (Cognito/JWT/IAM), 'private' when API key present, else 'public'
+ */
+const detectSecurityContext = (evt) => {
+    if (isV1(evt)) {
+        const auth = getHeaderFromEvent(evt, 'authorization');
+        if (hasAwsSig(auth) || hasV1AccessKey(evt) || hasAuthorizer(evt))
+            return 'my';
+        if (hasApiKey(evt))
+            return 'private';
+        return 'public';
+    }
+    if (isV2(evt)) {
+        const auth = getHeaderFromEvent(evt, 'authorization');
+        if (hasAwsSig(auth) || hasAuthorizer(evt))
+            return 'my';
+        if (hasApiKey(evt))
+            return 'private';
+        return 'public';
+    }
+    return 'public';
 };
 
 /**