@spine-event-engine/server 2.0.0-snapshot.2

package/dist/handler/generated-handler-registry.js

@@ -0,0 +1,223 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { isEntitySchema } from "../entity/entity-metadata.js";
+import { HandlerMetadataValues, HandlerMetadataRegistry, } from "./handler-metadata.js";
+import { RejectionSources } from "./rejection-source.js";
+/**
+ * Framework-owned ingestion adapter for generated handler registries.
+ */
+export class HandlerRegistryIngestor {
+    // prettier-ignore
+    /**
+     * Converts generated registry records into canonical entity handler metadata.
+     *
+     * @param registry Generated registry metadata to validate and materialize.
+     * @returns Frozen canonical entity-handler metadata.
+     */
+    ingest(registry) {
+        GeneratedRegistry.assert(registry);
+        GeneratedRegistry.validateVersion(registry);
+        return Object.freeze(registry.entities.map((entity) => GeneratedRegistry.materialize(entity)));
+    }
+    /**
+     * Registers generated registry records in a caller-owned metadata registry.
+     *
+     * @param generated Generated registry metadata to validate and register.
+     * @param registry Metadata registry to update.
+     * @returns The updated metadata registry.
+     */
+    register(generated, registry = new HandlerMetadataRegistry()) {
+        GeneratedRegistry.assert(generated);
+        const entityHandlers = this.ingest(generated);
+        new HandlerMetadataRegistry([...registry.listEntityHandlers(), ...entityHandlers]);
+        for (const metadata of entityHandlers) {
+            registry.register(metadata);
+        }
+        return registry;
+    }
+}
+/**
+ * Error thrown when generated handler registry metadata cannot be ingested.
+ */
+export class HandlerRegistryIngestionError extends Error {
+    // prettier-ignore
+    /**
+     * Stable code for callers/tests that need structured failure handling.
+     */
+    code;
+    /**
+     * Creates an ingestion error.
+     *
+     * @param code Stable code that identifies the failed validation.
+     * @param message Human-readable failure description.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = "HandlerRegistryIngestionError";
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+const registryVersion = 3;
+const GeneratedRegistry = Object.freeze({
+    assert(registry) {
+        if (registry === null || typeof registry !== "object") {
+            throw new HandlerRegistryIngestionError("UNSUPPORTED_REGISTRY_VERSION", "Generated handler registry must be an object.");
+        }
+    },
+    validateVersion(registry) {
+        const version = registry.version;
+        if (version === registryVersion) {
+            return;
+        }
+        throw new HandlerRegistryIngestionError("UNSUPPORTED_REGISTRY_VERSION", `Generated handler registry version ${String(version)} is not supported.`);
+    },
+    materialize(entity) {
+        GeneratedRegistry.validateSchema(entity.stateSchema, "entity state schema");
+        entity.handlers.forEach((handler) => {
+            GeneratedRegistry.validateHandler(handler);
+        });
+        return HandlerMetadataValues.defineArity(entity.entityType, entity.stateSchema, (builder) => entity.handlers.map((handler) => GeneratedRegistry.build(builder, handler)), entity.handlers.map((handler) => ({
+            kind: handler.kind,
+            methodName: handler.methodName,
+            ...(handler.kind === "event-subscription" || handler.kind === "state-subscription"
+                ? {}
+                : { emittedSchemas: Object.freeze([...handler.emittedSchemas]) }),
+            parameterCount: handler.parameterCount,
+            origin: handler.origin,
+            ...(handler.where === undefined ? {} : { where: Object.freeze({ ...handler.where }) }),
+        })));
+    },
+    build(builder, handler) {
+        switch (handler.kind) {
+            case "command-assignment":
+                return builder.assign(handler.signalSchema, handler.methodName);
+            case "command-reaction":
+                return builder.command(handler.signalSchema, handler.methodName);
+            case "event-subscription":
+                return builder.subscribe(handler.signalSchema, handler.methodName);
+            case "state-subscription":
+                return builder.subscribe(handler.signalSchema, handler.methodName);
+            case "event-reaction":
+                return builder.react(handler.signalSchema, handler.methodName);
+            default:
+                throw new HandlerRegistryIngestionError("UNSUPPORTED_HANDLER_KIND", `Generated handler kind "${String(handler.kind)}" is not supported.`);
+        }
+    },
+    validateHandler(handler) {
+        if (!GeneratedRegistry.isKind(handler.kind)) {
+            throw new HandlerRegistryIngestionError("UNSUPPORTED_HANDLER_KIND", `Generated handler kind "${String(handler.kind)}" is not supported.`);
+        }
+        const origin = handler.origin;
+        if (origin !== "domestic" && origin !== "external") {
+            throw new HandlerRegistryIngestionError("INVALID_SIGNAL_ORIGIN", `Generated handler "${handler.methodName}" declares an invalid signal origin.`);
+        }
+        if (handler.origin === "external" &&
+            (handler.kind === "command-assignment" ||
+                (handler.kind === "command-reaction" &&
+                    !GeneratedRegistry.isEventInputSchema(handler.signalSchema)))) {
+            throw new HandlerRegistryIngestionError("EXTERNAL_COMMAND_RECEIVER", `Generated command receiver "${handler.methodName}" cannot accept external commands.`);
+        }
+        const parameterCount = handler.parameterCount;
+        if (parameterCount !== 1 && parameterCount !== 2) {
+            throw new HandlerRegistryIngestionError("INVALID_PARAMETER_COUNT", `Generated handler "${handler.methodName}" declares unsupported parameter count ` +
+                `${String(parameterCount)}.`);
+        }
+        GeneratedRegistry.validateSchema(handler.signalSchema, `signal schema for generated handler "${handler.methodName}"`);
+        handler.emittedSchemas.forEach((schema, index) => {
+            GeneratedRegistry.validateSchema(schema, `emitted schema ${String(index)} for generated handler "${handler.methodName}"`);
+        });
+        GeneratedRegistry.validateWhere(handler);
+        if (handler.kind === "event-subscription" || handler.kind === "state-subscription") {
+            GeneratedRegistry.validateSubscription(handler);
+            if (handler.kind === "state-subscription" && !isEntitySchema(handler.signalSchema)) {
+                throw new HandlerRegistryIngestionError("INVALID_SCHEMA", `Generated state subscription handler "${handler.methodName}" must declare an entity state schema.`);
+            }
+            if (handler.kind === "event-subscription" && isEntitySchema(handler.signalSchema)) {
+                throw new HandlerRegistryIngestionError("INVALID_SCHEMA", `Generated event subscription handler "${handler.methodName}" must not declare an entity state schema.`);
+            }
+            return;
+        }
+        if (handler.kind === "command-assignment" || handler.kind === "command-reaction") {
+            GeneratedRegistry.validateEmits(handler);
+        }
+    },
+    validateSchema(schema, label) {
+        const value = schema;
+        if (value === null || typeof value !== "object") {
+            throw new HandlerRegistryIngestionError("INVALID_SCHEMA", `Generated handler registry ${label} must be an object with a non-empty typeName.`);
+        }
+        const typeName = value.typeName;
+        if (typeof typeName === "string" && typeName.trim().length > 0) {
+            return;
+        }
+        throw new HandlerRegistryIngestionError("INVALID_SCHEMA", `Generated handler registry ${label} must be an object with a non-empty typeName.`);
+    },
+    validateEmits(handler) {
+        if (handler.emittedSchemas.length > 0) {
+            return;
+        }
+        throw new HandlerRegistryIngestionError("MISSING_EMITTED_SCHEMAS", `Generated handler "${handler.methodName}" must declare at least one emitted schema.`);
+    },
+    validateSubscription(handler) {
+        if (handler.emittedSchemas.length === 0) {
+            return;
+        }
+        throw new HandlerRegistryIngestionError("UNEXPECTED_EMITTED_SCHEMAS", `Generated event subscription handler "${handler.methodName}" must not declare emitted schemas.`);
+    },
+    validateWhere(handler) {
+        const where = handler.where;
+        if (where === undefined)
+            return;
+        if (typeof where !== "object" ||
+            where === null ||
+            Array.isArray(where) ||
+            (Reflect.getPrototypeOf(where) !== Object.prototype && Reflect.getPrototypeOf(where) !== null)) {
+            throw new HandlerRegistryIngestionError("INVALID_SCHEMA", `Generated handler "${handler.methodName}" declares an invalid Event field filter.`);
+        }
+        const keys = Object.keys(where);
+        const filter = where;
+        if (keys.length !== 2 ||
+            !keys.includes("eventField") ||
+            !keys.includes("equals") ||
+            typeof filter.eventField !== "string" ||
+            filter.eventField.trim().length === 0 ||
+            typeof filter.equals !== "string" ||
+            !GeneratedRegistry.isEventInputSchema(handler.signalSchema) ||
+            (handler.kind !== "event-subscription" &&
+                handler.kind !== "event-reaction" &&
+                handler.kind !== "command-reaction")) {
+            throw new HandlerRegistryIngestionError("INVALID_SCHEMA", `Generated handler "${handler.methodName}" declares an invalid Event field filter.`);
+        }
+    },
+    isEventInputSchema(schema) {
+        const fileName = schema.file.name.split(/[\\/]/u).at(-1);
+        return (fileName === "events" ||
+            fileName === "events.proto" ||
+            fileName?.endsWith("_events") === true ||
+            fileName?.endsWith("_events.proto") === true ||
+            fileName === "rejections" ||
+            fileName?.endsWith("_rejections") === true ||
+            RejectionSources.matches(schema.file.name) ||
+            schema.typeName === "spine.core.Event");
+    },
+    isKind(kind) {
+        return (kind === "command-assignment" ||
+            kind === "command-reaction" ||
+            kind === "event-subscription" ||
+            kind === "state-subscription" ||
+            kind === "event-reaction");
+    },
+});
+//# sourceMappingURL=generated-handler-registry.js.map

package/dist/handler/generated-handler-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-handler-registry.js","sourceRoot":"","sources":["../../src/handler/generated-handler-registry.ts"],"names":[],"mappings":"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"}

package/dist/handler/generated-registry-discovery.d.ts

@@ -0,0 +1,94 @@
+import { HandlerRegistryIngestor } from "./generated-handler-registry.js";
+import { HandlerMetadataRegistry } from "./handler-metadata.js";
+/**
+ * Stable error code for generated registry discovery failures.
+ */
+export type RegistryDiscoveryErrorCode = "MODULE_IMPORT_FAILED" | "MISSING_REGISTRY_EXPORT" | "INVALID_REGISTRY_MODULE" | "REGISTRY_INGESTION_FAILED" | "UNSUPPORTED_MODULE_SCHEME" | "INVALID_MODULE_REF" | "DUPLICATE_REGISTRY_MODULE";
+/**
+ * Options for loading one or more generated registry modules.
+ */
+export interface GeneratedRegistryDiscoveryOptions {
+    /**
+     * Explicit filesystem paths or file: URLs to load.
+     */
+    readonly modules: readonly (string | URL)[];
+    /**
+     * Export name expected from each generated module.
+     */
+    readonly exportName?: string;
+    /**
+     * Optional retry token used to bypass Node's dynamic import cache for canonical modules.
+     */
+    readonly cacheBust?: string;
+}
+/**
+ * Error thrown when generated registry discovery or loading fails.
+ */
+export declare class GeneratedRegistryDiscoveryError extends Error {
+    /**
+     * Stable code for callers/tests that need structured failure handling.
+     */
+    readonly code: RegistryDiscoveryErrorCode;
+    /**
+     * Normalized imported module identifier.
+     */
+    readonly moduleId: string;
+    /**
+     * Optional underlying import or ingestion error.
+     */
+    readonly cause: unknown;
+    /**
+     * Creates a registry discovery error.
+     *
+     * @param code Stable code that identifies the failed operation.
+     * @param message Human-readable failure description.
+     * @param moduleId Normalized identifier of the affected module.
+     * @param cause Underlying import or ingestion failure.
+     */
+    constructor(code: RegistryDiscoveryErrorCode, message: string, moduleId: string, cause?: unknown);
+}
+/**
+ * Framework-owned runtime loader for generated handler registry modules.
+ */
+export declare class GeneratedRegistryDiscovery {
+    #private;
+    /**
+     * Creates a generated-registry loader.
+     *
+     * @param ingestor Adapter that validates and registers loaded metadata.
+     */
+    constructor(ingestor?: HandlerRegistryIngestor);
+    /**
+     * Builds the conventional generated registry module path for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns Absolute path to the conventional registry module.
+     */
+    static conventionalModulePath(root: string): string;
+    /**
+     * Builds the conventional generated registry module URL for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns File URL for the conventional registry module.
+     */
+    static conventionalModuleUrl(root: string): URL;
+    /**
+     * Loads generated handler registries from explicit filesystem paths or file URLs.
+     *
+     * @param options Module references and optional load configuration.
+     * @returns Frozen loaded registry values in module order.
+     */
+    load(options: GeneratedRegistryDiscoveryOptions): Promise<readonly unknown[]>;
+    /**
+     * Loads generated handler registries and ingests them into a caller-owned metadata registry.
+     *
+     * Registration stages all new metadata before mutating the caller-owned registry.
+     *
+     * @param options Module references and optional load configuration.
+     * @param registry Metadata registry to update, if one already exists.
+     * @returns Registry containing the loaded generated metadata.
+     */
+    register(options: GeneratedRegistryDiscoveryOptions, registry?: HandlerMetadataRegistry): Promise<HandlerMetadataRegistry>;
+    private loadModules;
+}
+//# sourceMappingURL=generated-registry-discovery.d.ts.map

package/dist/handler/generated-registry-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-registry-discovery.d.ts","sourceRoot":"","sources":["../../src/handler/generated-registry-discovery.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,uBAAuB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAOhE;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,sBAAsB,GACtB,yBAAyB,GACzB,yBAAyB,GACzB,2BAA2B,GAC3B,2BAA2B,GAC3B,oBAAoB,GACpB,2BAA2B,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAGhD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IAGxD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,SAAkB,KAAK,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;gBAED,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,OAAO;CASlB;AAED;;GAEG;AACH,qBAAa,0BAA0B;;IAGrC;;;;OAIG;gBACS,QAAQ,GAAE,uBAAuD;IAI7E;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAInD;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAI/C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,iCAAiC,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC;IAMnF;;;;;;;;OAQG;IACG,QAAQ,CACZ,OAAO,EAAE,iCAAiC,EAC1C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,OAAO,CAAC,uBAAuB,CAAC;YA8BrB,WAAW;CAqB1B"}

package/dist/handler/generated-registry-discovery.js

@@ -0,0 +1,228 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { HandlerRegistryIngestor, } from "./generated-handler-registry.js";
+import { HandlerMetadataRegistry } from "./handler-metadata.js";
+const defaultExportName = "generatedHandlerRegistry";
+const generatedRegistryFile = "generated/handler/generated-handler-registry.js";
+const moduleSchemeRe = /^[A-Za-z][A-Za-z\d+.-]*:/;
+const registryVersion = 3;
+/**
+ * Error thrown when generated registry discovery or loading fails.
+ */
+export class GeneratedRegistryDiscoveryError extends Error {
+    // prettier-ignore
+    /**
+     * Stable code for callers/tests that need structured failure handling.
+     */
+    code;
+    /**
+     * Normalized imported module identifier.
+     */
+    moduleId;
+    /**
+     * Optional underlying import or ingestion error.
+     */
+    cause;
+    /**
+     * Creates a registry discovery error.
+     *
+     * @param code Stable code that identifies the failed operation.
+     * @param message Human-readable failure description.
+     * @param moduleId Normalized identifier of the affected module.
+     * @param cause Underlying import or ingestion failure.
+     */
+    constructor(code, message, moduleId, cause) {
+        super(message);
+        this.name = "GeneratedRegistryDiscoveryError";
+        this.code = code;
+        this.moduleId = moduleId;
+        this.cause = cause;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Framework-owned runtime loader for generated handler registry modules.
+ */
+export class GeneratedRegistryDiscovery {
+    #ingestor;
+    /**
+     * Creates a generated-registry loader.
+     *
+     * @param ingestor Adapter that validates and registers loaded metadata.
+     */
+    constructor(ingestor = new HandlerRegistryIngestor()) {
+        this.#ingestor = ingestor;
+    }
+    /**
+     * Builds the conventional generated registry module path for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns Absolute path to the conventional registry module.
+     */
+    static conventionalModulePath(root) {
+        return resolve(root, generatedRegistryFile);
+    }
+    /**
+     * Builds the conventional generated registry module URL for one package or app root.
+     *
+     * @param root Package or application root directory.
+     * @returns File URL for the conventional registry module.
+     */
+    static conventionalModuleUrl(root) {
+        return pathToFileURL(GeneratedRegistryDiscovery.conventionalModulePath(root));
+    }
+    /**
+     * Loads generated handler registries from explicit filesystem paths or file URLs.
+     *
+     * @param options Module references and optional load configuration.
+     * @returns Frozen loaded registry values in module order.
+     */
+    async load(options) {
+        const loaded = await this.loadModules(options);
+        return Object.freeze(loaded.map((entry) => entry.registry));
+    }
+    /**
+     * Loads generated handler registries and ingests them into a caller-owned metadata registry.
+     *
+     * Registration stages all new metadata before mutating the caller-owned registry.
+     *
+     * @param options Module references and optional load configuration.
+     * @param registry Metadata registry to update, if one already exists.
+     * @returns Registry containing the loaded generated metadata.
+     */
+    async register(options, registry) {
+        const loaded = await this.loadModules(options);
+        const target = registry ?? new HandlerMetadataRegistry();
+        const existing = target.listEntityHandlers();
+        const staged = new HandlerMetadataRegistry(existing);
+        for (const entry of loaded) {
+            try {
+                this.#ingestor.register(entry.registry, staged);
+            }
+            catch (error) {
+                throw new GeneratedRegistryDiscoveryError("REGISTRY_INGESTION_FAILED", `Generated handler registry module "${entry.moduleId}" could not be ingested.`, entry.moduleId, error);
+            }
+        }
+        if (registry === undefined) {
+            return staged;
+        }
+        for (const metadata of staged.listEntityHandlers().slice(existing.length)) {
+            registry.register(metadata);
+        }
+        return registry;
+    }
+    async loadModules(options) {
+        const exportName = options.exportName ?? defaultExportName;
+        const moduleRefs = [...options.modules];
+        const moduleIds = moduleRefs.map((moduleRef) => RegistryModules.normalize(moduleRef));
+        const loaded = [];
+        RegistryModules.assertUnique(moduleIds);
+        for (const moduleId of moduleIds) {
+            const exports = await RegistryModules.import(RegistryModules.cacheable(moduleId, options));
+            loaded.push({
+                moduleId,
+                registry: RegistryModules.registry(exports, moduleId, exportName),
+            });
+        }
+        return Object.freeze(loaded);
+    }
+}
+const RegistryModules = Object.freeze({
+    async import(moduleId) {
+        try {
+            return await import(moduleId);
+        }
+        catch (error) {
+            throw new GeneratedRegistryDiscoveryError("MODULE_IMPORT_FAILED", `Could not import generated handler registry module "${moduleId}".`, moduleId, error);
+        }
+    },
+    cacheable(moduleId, options) {
+        if (options.cacheBust === undefined || options.cacheBust.length === 0) {
+            return moduleId;
+        }
+        const moduleUrl = new URL(moduleId);
+        moduleUrl.searchParams.set("spine-registry-cache", options.cacheBust);
+        return moduleUrl.href;
+    },
+    registry(exports, moduleId, exportName) {
+        const value = RegistryModules.export(exports, exportName);
+        if (value === undefined) {
+            throw new GeneratedRegistryDiscoveryError("MISSING_REGISTRY_EXPORT", `Generated handler registry module "${moduleId}" does not export "${exportName}".`, moduleId);
+        }
+        if (RegistryModules.isRegistry(value)) {
+            return value;
+        }
+        throw new GeneratedRegistryDiscoveryError("INVALID_REGISTRY_MODULE", `Generated handler registry module "${moduleId}" exports invalid "${exportName}" metadata.`, moduleId);
+    },
+    export(exports, exportName) {
+        if (exports === null || typeof exports !== "object") {
+            return undefined;
+        }
+        return exports[exportName];
+    },
+    isRegistry(value) {
+        if (value === null || typeof value !== "object") {
+            return false;
+        }
+        const version = value.version;
+        const entities = value.entities;
+        return version === registryVersion && Array.isArray(entities);
+    },
+    normalize(moduleRef) {
+        if (moduleRef instanceof URL) {
+            return RegistryModules.url(moduleRef);
+        }
+        if (RegistryModules.isUrl(moduleRef)) {
+            return RegistryModules.url(RegistryModules.parse(moduleRef));
+        }
+        return pathToFileURL(resolve(moduleRef)).href;
+    },
+    url(moduleUrl) {
+        if (moduleUrl.protocol !== "file:") {
+            throw new GeneratedRegistryDiscoveryError("UNSUPPORTED_MODULE_SCHEME", `Generated handler registry module "${moduleUrl.href}" must use the file: URL scheme.`, moduleUrl.href);
+        }
+        if (moduleUrl.search.length > 0 || moduleUrl.hash.length > 0) {
+            throw new GeneratedRegistryDiscoveryError("INVALID_MODULE_REF", `Generated handler registry module "${moduleUrl.href}" must not include a query or hash.`, moduleUrl.href);
+        }
+        try {
+            return pathToFileURL(resolve(fileURLToPath(moduleUrl))).href;
+        }
+        catch (error) {
+            throw new GeneratedRegistryDiscoveryError("INVALID_MODULE_REF", `Generated handler registry module "${moduleUrl.href}" is not a valid file URL.`, moduleUrl.href, error);
+        }
+    },
+    isUrl(moduleRef) {
+        return moduleSchemeRe.test(moduleRef) && !/^[A-Za-z]:[\\/]/.test(moduleRef);
+    },
+    parse(moduleRef) {
+        try {
+            return new URL(moduleRef);
+        }
+        catch (error) {
+            throw new GeneratedRegistryDiscoveryError("INVALID_MODULE_REF", `Generated handler registry module "${moduleRef}" is not a valid URL.`, moduleRef, error);
+        }
+    },
+    assertUnique(moduleIds) {
+        const seen = new Set();
+        for (const moduleId of moduleIds) {
+            if (seen.has(moduleId)) {
+                throw new GeneratedRegistryDiscoveryError("DUPLICATE_REGISTRY_MODULE", `Generated handler registry module "${moduleId}" was listed more than once.`, moduleId);
+            }
+            seen.add(moduleId);
+        }
+    },
+});
+//# sourceMappingURL=generated-registry-discovery.js.map

package/dist/handler/generated-registry-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-registry-discovery.js","sourceRoot":"","sources":["../../src/handler/generated-registry-discovery.ts"],"names":[],"mappings":"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"}

package/dist/handler/generated-registry-writer.d.ts

@@ -0,0 +1,58 @@
+import type { BuildHandlerAnalysis } from "./build-time-handler-analyzer.js";
+/**
+ * Options for deterministic generated-registry source rendering.
+ */
+export interface RegistryRenderOptions {
+    /**
+     * Absolute or caller-owned output file used for relative import rendering.
+     */
+    readonly outputFile: string;
+    /**
+     * Type-only module specifier used for the generated registry contract.
+     */
+    readonly registryModuleSpecifier?: string;
+    /**
+     * Exported constant name for the generated registry object.
+     */
+    readonly registryName?: string;
+}
+/**
+ * Options for guarded generated-registry file writing.
+ */
+export interface RegistryWriteOptions extends RegistryRenderOptions {
+    /**
+     * Repository root used for Git-ignore and symlink validation.
+     */
+    readonly repoRoot: string;
+    /**
+     * Explicit generated directory that must own the output file.
+     */
+    readonly generatedRoot: string;
+    /**
+     * Published output path used for relative imports when writing to staging.
+     */
+    readonly publishedOutputFile?: string;
+}
+/**
+ * Build-time writer for version-3 generated handler registry source.
+ */
+export declare class GeneratedRegistryWriter {
+    /**
+     * Renders generated registry source without writing to disk.
+     *
+     * @param analysis Analyzed entity handlers to render.
+     * @param options Caller-owned output and registry naming options.
+     * @returns Deterministic generated TypeScript source.
+     */
+    render(analysis: BuildHandlerAnalysis, options: RegistryRenderOptions): string;
+    /**
+     * Validates and writes generated registry source only when explicitly invoked.
+     *
+     * @param analysis Analyzed entity handlers to render and validate.
+     * @param options Guarded output location and registry naming options.
+     * @returns Generated TypeScript source written to the output file.
+     */
+    write(analysis: BuildHandlerAnalysis, options: RegistryWriteOptions): string;
+}
+export type { BuildHandlerAnalysis } from "./build-time-handler-analyzer.js";
+//# sourceMappingURL=generated-registry-writer.d.ts.map

package/dist/handler/generated-registry-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-registry-writer.d.ts","sourceRoot":"","sources":["../../src/handler/generated-registry-writer.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEV,oBAAoB,EAErB,MAAM,kCAAkC,CAAC;AAsE1C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAGpC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IAGjE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAGlC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM;IAkB9E;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM;CAkB7E;AAydD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC"}