@ekairos/domain 1.22.34-beta.development.0 → 1.22.35

package/dist/index.js

@@ -1,20 +1,25 @@
 import { i } from "@instantdb/core";
-import { filterDomainDoc, parseDomainDoc, renderDomainDoc, } from "./domain-doc.js";
-export { parseDomainDoc, renderDomainDoc, filterDomainDoc, } from "./domain-doc.js";
+import { z } from "zod";
+export { EkairosRuntime, } from "./runtime-handle.js";
 let domainDocLoader = null;
+let domainDocNormalizer = null;
 export function configureDomainDocLoader(loader) {
     domainDocLoader = loader ?? null;
 }
+export function configureDomainDocNormalizer(normalizer) {
+    domainDocNormalizer = normalizer ?? null;
+}
 const EKAIROS_META = Symbol.for("@ekairos/domain/meta");
 const EKAIROS_ACTIONS = Symbol.for("@ekairos/domain/actions");
+const EKAIROS_ACTION_MAP = Symbol.for("@ekairos/domain/action-map");
 const EKAIROS_ACTION_BINDING = Symbol.for("@ekairos/domain/action-binding");
 function getMeta(source) {
-    if (!source || typeof source !== "object")
+    if (!isObjectLike(source))
         return null;
     return source[EKAIROS_META] ?? null;
 }
 function getActionBinding(source) {
-    if (!source || typeof source !== "object")
+    if (!isObjectLike(source))
         return null;
     const binding = source[EKAIROS_ACTION_BINDING];
     if (!binding || typeof binding !== "object")
@@ -22,7 +27,12 @@ function getActionBinding(source) {
     const name = typeof binding.name === "string" ? binding.name.trim() : "";
     if (!name)
         return null;
-    return { name, domain: binding.domain };
+    const key = typeof binding.key === "string" ? binding.key.trim() : "";
+    return {
+        name,
+        domain: binding.domain,
+        ...(key ? { key } : {}),
+    };
 }
 function bindAction(action, params) {
     const registration = {
@@ -33,6 +43,7 @@ function bindAction(action, params) {
         value: {
             name: params.name,
             domain: params.domain,
+            key: params.key,
         },
         enumerable: false,
         configurable: false,
@@ -41,7 +52,7 @@ function bindAction(action, params) {
     return registration;
 }
 function getStoredActions(source) {
-    if (!source || typeof source !== "object")
+    if (!isObjectLike(source))
         return [];
     const raw = source[EKAIROS_ACTIONS];
     if (!Array.isArray(raw))
@@ -51,8 +62,16 @@ function getStoredActions(source) {
         typeof entry.name === "string" &&
         typeof entry.execute === "function");
 }
+function getStoredActionMap(source) {
+    if (!isObjectLike(source))
+        return {};
+    const raw = source[EKAIROS_ACTION_MAP];
+    if (!raw || typeof raw !== "object")
+        return {};
+    return raw;
+}
 function setStoredActions(source, actions) {
-    if (!source || typeof source !== "object")
+    if (!isObjectLike(source))
         return;
     const frozenActions = Object.freeze([...actions]);
     Object.defineProperty(source, EKAIROS_ACTIONS, {
@@ -62,11 +81,23 @@ function setStoredActions(source, actions) {
         writable: true,
     });
 }
+function setStoredActionMap(source, actionMap) {
+    if (!isObjectLike(source))
+        return;
+    Object.defineProperty(source, EKAIROS_ACTION_MAP, {
+        value: Object.freeze({ ...actionMap }),
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+}
 function normalizeActionLike(value, params) {
-    const action = typeof value === "function"
-        ? { execute: value }
-        : value;
-    if (!action || typeof action !== "object" || typeof action.execute !== "function") {
+    const action = value;
+    if (!action ||
+        typeof action !== "object" ||
+        typeof action.execute !== "function" ||
+        !action.input ||
+        !action.output) {
         throw new Error(`Invalid domain action definition: ${params.fallbackName}`);
     }
     const explicitName = typeof action.name === "string" ? action.name.trim() : "";
@@ -76,16 +107,27 @@ function normalizeActionLike(value, params) {
         throw new Error(`Domain action is missing a name: ${params.fallbackName}`);
     }
     const domain = bound?.domain ?? params.domain;
-    return bindAction(action, { name, domain });
+    return bindAction(action, { name, domain, key: params.key ?? params.fallbackName });
 }
 function normalizeActionCollection(source, input) {
     const current = getStoredActions(source);
+    const currentActionMap = getStoredActionMap(source);
     const byName = new Set(current.map((action) => action.name));
+    const byKey = new Set(Object.keys(currentActionMap));
     const normalized = [];
-    const push = (candidate) => {
+    const actionMap = {};
+    const push = (candidate, key) => {
         if (byName.has(candidate.name)) {
             throw new Error(`Duplicate domain action name: ${candidate.name}`);
         }
+        const localKey = String(key ?? candidate?.name ?? "").trim();
+        if (localKey) {
+            if (byKey.has(localKey)) {
+                throw new Error(`Duplicate domain action key: ${localKey}`);
+            }
+            byKey.add(localKey);
+            actionMap[localKey] = candidate;
+        }
         byName.add(candidate.name);
         normalized.push(candidate);
     };
@@ -97,18 +139,19 @@ function normalizeActionCollection(source, input) {
                     : "",
                 domain: source,
             });
-            push(normalizedEntry);
+            push(normalizedEntry, normalizedEntry?.name);
         }
-        return normalized;
+        return { actions: normalized, actionMap };
     }
     for (const [key, value] of Object.entries(input ?? {})) {
         const normalizedEntry = normalizeActionLike(value, {
             fallbackName: key,
             domain: source,
+            key,
         });
-        push(normalizedEntry);
+        push(normalizedEntry, key);
     }
-    return normalized;
+    return { actions: normalized, actionMap };
 }
 function attachMeta(target, meta) {
     Object.defineProperty(target, EKAIROS_META, {
@@ -184,9 +227,22 @@ function listKeys(value) {
         return [];
     return Object.keys(value).filter((key) => !key.startsWith("$"));
 }
+function isObjectLike(value) {
+    return !!value && (typeof value === "object" || typeof value === "function");
+}
+function isMaterializedDomainSource(value) {
+    if (!isObjectLike(value))
+        return false;
+    const source = value;
+    return (typeof source.instantSchema === "function" ||
+        typeof source.toInstantSchema === "function" ||
+        ("entities" in source && "links" in source && "rooms" in source));
+}
 function resolveSchema(source) {
     if (!source)
         return null;
+    if (typeof source.instantSchema === "function")
+        return source.instantSchema();
     if (typeof source.toInstantSchema === "function")
         return source.toInstantSchema();
     if (typeof source.schema === "function")
@@ -223,22 +279,127 @@ function assertSchemaIncludes(fullSchema, requiredSchema) {
         throw new Error(`ConcreteDomain: schema is missing required keys (${parts.join(" | ")})`);
     }
 }
-function createConcreteDomain(domainInstance, db, fullSchema) {
+function collectTransitiveDomainNames(source, seen = new Set()) {
+    const names = new Set();
+    if (!isObjectLike(source))
+        return names;
+    if (seen.has(source))
+        return names;
+    seen.add(source);
+    const meta = getMeta(source);
+    if (!meta)
+        return names;
+    if (meta.name)
+        names.add(meta.name);
+    for (const getter of meta.includes ?? []) {
+        if (!getter)
+            continue;
+        let child = null;
+        try {
+            child = getter();
+        }
+        catch {
+            child = null;
+        }
+        for (const name of collectTransitiveDomainNames(child, seen)) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+function assertDomainNamesInclude(rootDomain, requiredDomain) {
+    const rootMeta = getMeta(rootDomain);
+    const requiredMeta = getMeta(requiredDomain);
+    if (!rootMeta || !requiredMeta)
+        return;
+    const rootNames = collectTransitiveDomainNames(rootDomain);
+    const requiredNames = collectTransitiveDomainNames(requiredDomain);
+    if (rootNames.size === 0 || requiredNames.size === 0)
+        return;
+    const missing = Array.from(requiredNames).filter((name) => !rootNames.has(name));
+    if (missing.length > 0) {
+        throw new Error(`ConcreteDomain: domain is missing required names (${missing.join(", ")})`);
+    }
+}
+function createConcreteDomain(domainInstance, db, fullSchema, bindings) {
     const baseSchema = fullSchema ?? resolveSchema(domainInstance);
+    const actionMap = getStoredActionMap(domainInstance);
     const concrete = {
         domain: domainInstance,
         db,
         schema: resolveSchema(domainInstance),
         context: (options) => domainInstance.context(options),
         contextString: (options) => domainInstance.contextString(options),
-        fromDomain(subdomain) {
-            const requiredSchema = resolveSchema(subdomain);
-            assertSchemaIncludes(baseSchema, requiredSchema);
-            return createConcreteDomain(subdomain, db, baseSchema);
-        },
     };
+    if (bindings?.runtime !== undefined) {
+        const inheritedStack = [];
+        const createActionRuntime = (stack) => {
+            const runtime = {
+                ...concrete,
+                ...(bindings.env !== undefined ? { env: bindings.env } : {}),
+            };
+            runtime.actions = buildActions(stack);
+            return runtime;
+        };
+        const buildActions = (stack) => Object.fromEntries(Object.entries(actionMap).map(([key, action]) => [
+            key,
+            async (input) => {
+                const execute = action?.execute;
+                if (typeof execute !== "function") {
+                    throw new Error(`domain_action_not_executable:${key}`);
+                }
+                if (stack.includes(key)) {
+                    throw new Error(`domain_action_cycle:${key}`);
+                }
+                const nextStack = [...stack, key];
+                const scopedRuntime = createActionRuntime(nextStack);
+                const parsedInput = action.input.parse(input);
+                const params = {
+                    input: parsedInput,
+                    runtime: scopedRuntime,
+                };
+                const output = await execute(params);
+                return action.output.parse(output);
+            },
+        ]));
+        if (bindings.env !== undefined) {
+            ;
+            concrete.env = bindings.env;
+        }
+        ;
+        concrete.actions = buildActions(inheritedStack);
+    }
     return concrete;
 }
+function promoteRuntimeDomainScope(scoped) {
+    const promoted = { ...scoped };
+    const db = scoped?.db;
+    if (db && typeof db.query === "function") {
+        promoted.query = db.query.bind(db);
+    }
+    const actions = scoped?.actions;
+    if (actions && typeof actions === "object") {
+        for (const [key, action] of Object.entries(actions)) {
+            if (key in promoted)
+                continue;
+            promoted[key] = action;
+        }
+    }
+    return promoted;
+}
+async function callDomainRuntimeScope(domainInstance, runtime, options) {
+    if (!runtime || typeof runtime.use !== "function") {
+        throw new Error("domain(runtime) requires an Ekairos runtime with use(domain).");
+    }
+    return promoteRuntimeDomainScope(await runtime.use(domainInstance, options));
+}
+export function materializeDomain(params) {
+    const baseSchema = resolveSchema(params.rootDomain);
+    const requiredSchema = resolveSchema(params.subdomain);
+    assertDomainNamesInclude(params.rootDomain, params.subdomain);
+    assertSchemaIncludes(baseSchema, requiredSchema);
+    return createConcreteDomain(params.subdomain, params.db, baseSchema, params.bindings);
+}
 function loadDomainDoc(scope, meta) {
     if (!domainDocLoader)
         return null;
@@ -252,18 +413,18 @@ function loadDomainDoc(scope, meta) {
 function normalizeDoc(docInfo, options) {
     if (!docInfo?.doc)
         return { doc: null, docPath: docInfo?.docPath };
-    const parsed = parseDomainDoc(docInfo.doc);
-    if (!parsed)
-        return { doc: docInfo.doc, docPath: docInfo.docPath };
-    const filtered = filterDomainDoc(parsed.data, {
-        subdomains: options.subdomains,
-        entities: options.entities,
-    });
-    const rendered = renderDomainDoc(filtered, {
-        titlePrefix: options.titlePrefix,
-        includeSubdomains: options.includeSubdomains,
-    });
-    return { doc: rendered, docPath: docInfo.docPath };
+    if (domainDocNormalizer) {
+        try {
+            const normalized = domainDocNormalizer({ docInfo, options });
+            if (normalized)
+                return normalized;
+        }
+        catch {
+            // Fall through to raw docs. Domain context must remain usable without the
+            // optional markdown/YAML parser in workflow bundles.
+        }
+    }
+    return { doc: docInfo.doc, docPath: docInfo.docPath };
 }
 function buildRegistryEntries(meta, options) {
     if (!meta)
@@ -282,7 +443,7 @@ function buildRegistryEntries(meta, options) {
         catch {
             child = null;
         }
-        if (!child || typeof child !== "object")
+        if (!isObjectLike(child))
             continue;
         if (seen.has(child))
             continue;
@@ -404,7 +565,7 @@ function resolveIncludeNames(meta) {
         catch {
             child = null;
         }
-        if (!child || typeof child !== "object")
+        if (!isObjectLike(child))
             continue;
         const childMeta = getMeta(child);
         if (childMeta?.name)
@@ -412,6 +573,64 @@ function resolveIncludeNames(meta) {
     }
     return Array.from(names);
 }
+function isRuntimeEntityDef(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "attrs" in value &&
+        value.attrs &&
+        typeof value.attrs === "object");
+}
+function stripRuntimeEntityLinks(entity) {
+    if (!isRuntimeEntityDef(entity))
+        return entity;
+    return i.entity({ ...entity.attrs });
+}
+function normalizeRuntimeAttrDef(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    const sorted = {};
+    for (const key of Object.keys(record).sort()) {
+        sorted[key] = normalizeRuntimeAttrDef(record[key]);
+    }
+    return sorted;
+}
+function stableRuntimeAttrDef(value) {
+    return JSON.stringify(normalizeRuntimeAttrDef(value));
+}
+function areRuntimeAttrDefsEquivalent(baseAttr, nextAttr) {
+    if (baseAttr === nextAttr)
+        return true;
+    return stableRuntimeAttrDef(baseAttr) === stableRuntimeAttrDef(nextAttr);
+}
+function mergeRuntimeEntityDefs(entityName, baseEntity, nextEntity) {
+    if (!isRuntimeEntityDef(baseEntity) || !isRuntimeEntityDef(nextEntity)) {
+        return stripRuntimeEntityLinks(nextEntity);
+    }
+    const conflictingAttrs = Object.keys(nextEntity.attrs).filter((attr) => Object.prototype.hasOwnProperty.call(baseEntity.attrs, attr) &&
+        !areRuntimeAttrDefsEquivalent(baseEntity.attrs[attr], nextEntity.attrs[attr]));
+    if (conflictingAttrs.length > 0) {
+        throw new Error(`domain_duplicate_entity_attr:${entityName}.${conflictingAttrs.join(",")}`);
+    }
+    return i.entity({
+        ...baseEntity.attrs,
+        ...nextEntity.attrs,
+    });
+}
+function mergeRuntimeEntities(baseEntities, nextEntities) {
+    const merged = {};
+    for (const [entityName, entity] of Object.entries(baseEntities)) {
+        merged[entityName] = stripRuntimeEntityLinks(entity);
+    }
+    for (const [entityName, entity] of Object.entries(nextEntities)) {
+        merged[entityName] =
+            entityName in merged
+                ? mergeRuntimeEntityDefs(entityName, merged[entityName], entity)
+                : stripRuntimeEntityLinks(entity);
+    }
+    return merged;
+}
 function makeInstance(def, metaIncludes = []) {
     const meta = {
         name: def.name,
@@ -431,7 +650,7 @@ function makeInstance(def, metaIncludes = []) {
         const otherDef = "schema" in other
             ? { entities: other.entities, links: other.links, rooms: other.rooms }
             : other;
-        const mergedEntities = { ...def.entities, ...otherDef.entities };
+        const mergedEntities = mergeRuntimeEntities(def.entities, otherDef.entities);
         const mergedLinks = { ...def.links, ...otherDef.links };
         const mergedRooms = { ...def.rooms, ...otherDef.rooms };
         const composed = makeInstance({
@@ -488,10 +707,10 @@ export function domain(arg) {
     // Support lazy includes for circular dependencies by storing references and resolving at schema()/toInstantSchema() time
     // AL preserves literal link keys from included domains
     function createBuilder(deps, linkDeps, lazyIncludes = [], meta) {
-        return {
+        const builder = {
             includes(other) {
                 // Support lazy includes via function for circular dependencies
-                if (typeof other === 'function') {
+                if (typeof other === 'function' && !isMaterializedDomainSource(other)) {
                     const lazyGetter = () => {
                         try {
                             return other();
@@ -525,7 +744,7 @@ export function domain(arg) {
                         return createBuilder(deps, linkDeps, [...lazyIncludes, lazyGetter], nextMeta);
                     }
                     const links = other.links;
-                    const mergedEntities = { ...deps, ...entities };
+                    const mergedEntities = mergeRuntimeEntities(deps, entities);
                     // Preserve literal link keys by merging directly (not casting to LinksDef)
                     const mergedLinks = (links ? { ...linkDeps, ...links } : { ...linkDeps });
                     const includeRef = () => other;
@@ -540,10 +759,11 @@ export function domain(arg) {
                     return createBuilder(deps, linkDeps, [...lazyIncludes, lazyGetter], nextMeta);
                 }
             },
-            schema(def) {
+            withSchema(def) {
                 // Resolve lazy includes at schema() time (when all domains should be initialized)
                 // This handles circular dependencies by deferring entity resolution
                 let resolvedDeps = { ...deps };
+                const pendingLazyIncludes = [];
                 // Preserve literal link keys from accumulated links
                 let resolvedLinks = { ...linkDeps };
                 for (const lazyGetter of lazyIncludes) {
@@ -552,7 +772,7 @@ export function domain(arg) {
                         if (other) {
                             const entities = other.entities;
                             if (entities) {
-                                resolvedDeps = { ...resolvedDeps, ...entities };
+                                resolvedDeps = mergeRuntimeEntities(resolvedDeps, entities);
                             }
                             const links = other.links;
                             if (links) {
@@ -560,113 +780,149 @@ export function domain(arg) {
                                 resolvedLinks = { ...resolvedLinks, ...links };
                             }
                         }
+                        else {
+                            pendingLazyIncludes.push(lazyGetter);
+                        }
                     }
                     catch (e) {
                         // If lazy resolution fails, continue - entities might be available via string references
                         // This is expected for circular dependencies that will be resolved when all domains are composed
+                        pendingLazyIncludes.push(lazyGetter);
                     }
                 }
                 // Runtime merge for output; compile-time validation handled by types above
-                const allEntities = { ...resolvedDeps, ...def.entities };
+                const allEntities = mergeRuntimeEntities(resolvedDeps, def.entities);
                 // allLinks contains merged links from included domains + current domain
                 // Preserve literal link keys (owner, related, parent, etc.) by using MergeLinks
                 const allLinks = { ...resolvedLinks, ...def.links };
-                const createDomainResult = (seedActions = []) => {
+                const createDomainResult = (seedActions = [], seedActionMap = {}) => {
                     const capturedEntities = { ...allEntities };
                     const capturedLinks = cloneLinksDef(allLinks);
                     const capturedRooms = cloneRoomsDef(def.rooms);
                     let cachedInstantSchema = null;
-                    const result = {
-                        entities: Object.freeze({ ...allEntities }),
-                        // Strip base phantom from public type so it's assignable to i.schema()
-                        links: Object.freeze(cloneLinksDef(allLinks)),
-                        rooms: Object.freeze(cloneRoomsDef(def.rooms)),
-                        // Add originalEntities for type-safe access to original entity definitions
-                        originalEntities: Object.freeze({ ...allEntities }),
-                        toInstantSchema: () => {
-                            if (cachedInstantSchema) {
-                                return cachedInstantSchema;
-                            }
-                            let finalEntities = { ...capturedEntities };
-                            let finalLinks = cloneLinksDef(capturedLinks);
-                            let hasUnresolvedIncludes = false;
-                            // Try to resolve lazy includes one more time (domains should be initialized by now)
-                            for (const lazyGetter of lazyIncludes) {
-                                try {
-                                    const other = lazyGetter();
-                                    if (other) {
-                                        const entities = other.entities;
-                                        if (entities) {
-                                            finalEntities = { ...finalEntities, ...entities };
-                                        }
-                                        const links = other.links;
-                                        if (links) {
-                                            finalLinks = { ...finalLinks, ...links };
-                                        }
+                    const instantSchema = () => {
+                        if (cachedInstantSchema) {
+                            return cachedInstantSchema;
+                        }
+                        let finalEntities = { ...capturedEntities };
+                        let finalLinks = cloneLinksDef(capturedLinks);
+                        let hasUnresolvedIncludes = false;
+                        // Try to resolve lazy includes one more time (domains should be initialized by now)
+                        for (const lazyGetter of pendingLazyIncludes) {
+                            try {
+                                const other = lazyGetter();
+                                if (other) {
+                                    const entities = other.entities;
+                                    if (entities) {
+                                        finalEntities = mergeRuntimeEntities(finalEntities, entities);
                                     }
-                                    else {
-                                        hasUnresolvedIncludes = true;
+                                    const links = other.links;
+                                    if (links) {
+                                        finalLinks = { ...finalLinks, ...links };
                                     }
                                 }
-                                catch {
-                                    // If still can't resolve, entities should already be in allEntities from app domain composition
+                                else {
                                     hasUnresolvedIncludes = true;
                                 }
                             }
-                            assertNoDuplicateLinkAttributes(finalLinks);
-                            // Include base entities ($users, $files, $streams) that InstantDB manages
-                            // These need to be explicitly included since InstantDB doesn't auto-add them
-                            const baseEntities = {
-                                $users: i.entity({
-                                    email: i.string().optional().indexed(),
-                                }),
-                                $files: i.entity({
-                                    path: i.string(),
-                                    url: i.string().optional(),
-                                    contentType: i.string().optional(),
-                                    size: i.number().optional(),
-                                }),
-                                $streams: i.entity({
-                                    clientId: i.string().optional().indexed(),
-                                    size: i.number().optional(),
-                                    createdAt: i.date().optional().indexed(),
-                                    updatedAt: i.date().optional().indexed(),
-                                }),
-                            };
-                            // Merge base entities with user entities, user entities take precedence
-                            const allEntitiesWithBase = {
-                                ...baseEntities,
-                                ...finalEntities,
-                            };
-                            const schemaResult = i.schema({
-                                entities: allEntitiesWithBase,
-                                links: cloneLinksDef(finalLinks),
-                                rooms: cloneRoomsDef(capturedRooms),
-                            });
-                            const frozenSchema = Object.freeze(schemaResult);
-                            if (!hasUnresolvedIncludes) {
-                                cachedInstantSchema = frozenSchema;
+                            catch {
+                                // If still can't resolve, entities should already be in allEntities from app domain composition
+                                hasUnresolvedIncludes = true;
                             }
-                            return frozenSchema;
-                        },
+                        }
+                        assertNoDuplicateLinkAttributes(finalLinks);
+                        // Include base entities ($users, $files, $streams) that InstantDB manages
+                        // These need to be explicitly included since InstantDB doesn't auto-add them
+                        const baseEntities = {
+                            $users: i.entity({
+                                email: i.string().optional().indexed(),
+                            }),
+                            $files: i.entity({
+                                path: i.string(),
+                                url: i.string().optional(),
+                                contentType: i.string().optional(),
+                                size: i.number().optional(),
+                            }),
+                            $streams: i.entity({
+                                clientId: i.string().optional().indexed(),
+                                size: i.number().optional(),
+                                createdAt: i.date().optional().indexed(),
+                                updatedAt: i.date().optional().indexed(),
+                            }),
+                        };
+                        // Merge base entities with user entities, user entities take precedence
+                        const allEntitiesWithBase = {
+                            ...baseEntities,
+                            ...finalEntities,
+                        };
+                        const schemaResult = i.schema({
+                            entities: allEntitiesWithBase,
+                            links: cloneLinksDef(finalLinks),
+                            rooms: cloneRoomsDef(capturedRooms),
+                        });
+                        const frozenSchema = Object.freeze(schemaResult);
+                        if (!hasUnresolvedIncludes) {
+                            cachedInstantSchema = frozenSchema;
+                        }
+                        return frozenSchema;
                     };
+                    let result;
+                    const callableResult = (runtime, options) => callDomainRuntimeScope(result, runtime, options);
+                    result = Object.assign(callableResult, {
+                        entities: Object.freeze({ ...allEntities }),
+                        // Strip base phantom from public type so it's assignable to i.schema()
+                        links: Object.freeze(cloneLinksDef(allLinks)),
+                        rooms: Object.freeze(cloneRoomsDef(def.rooms)),
+                        // Add originalEntities for type-safe access to original entity definitions
+                        originalEntities: Object.freeze({ ...allEntities }),
+                        instantSchema,
+                        toInstantSchema: instantSchema,
+                    });
                     attachMeta(result, freezeMeta(meta));
                     result.context = (options) => buildContext(result, options);
                     result.contextString = (options) => contextToString(buildContext(result, options));
-                    result.fromDB = (db) => createConcreteDomain(result, db, resolveSchema(result));
-                    const reboundActions = seedActions.map((action) => bindAction(action, { name: action.name, domain: result }));
+                    result.fromDB = (db, bindings) => createConcreteDomain(result, db, resolveSchema(result), bindings);
+                    const reboundByAction = new Map();
+                    const reboundActionMap = Object.fromEntries(Object.entries(seedActionMap).map(([key, action]) => {
+                        const rebound = bindAction(action, {
+                            name: action.name,
+                            domain: result,
+                            key,
+                        });
+                        reboundByAction.set(action, rebound);
+                        return [key, rebound];
+                    }));
+                    const reboundActions = seedActions.map((action) => {
+                        const rebound = reboundByAction.get(action);
+                        if (rebound)
+                            return rebound;
+                        return bindAction(action, {
+                            name: action.name,
+                            domain: result,
+                            key: getActionBinding(action)?.key,
+                        });
+                    });
                     setStoredActions(result, [...reboundActions]);
-                    result.actions = (actionsInput) => {
+                    setStoredActionMap(result, reboundActionMap);
+                    result.actions = getStoredActionMap(result);
+                    result.withActions = (actionsInput) => {
                         const current = getStoredActions(result);
+                        const currentMap = getStoredActionMap(result);
                         const additions = normalizeActionCollection(result, actionsInput);
-                        return createDomainResult([...current, ...additions]);
+                        return createDomainResult([...current, ...additions.actions], { ...currentMap, ...additions.actionMap });
                     };
                     result.getActions = () => [...getStoredActions(result)];
+                    result.getActionMap = () => ({ ...getStoredActionMap(result) });
+                    result.definition = () => result;
                     return Object.freeze(result);
                 };
-                return createDomainResult();
+                return createDomainResult([], {});
+            },
+            schema(def) {
+                return this.withSchema(def);
             },
         };
+        return builder;
     }
     if (typeof arg === "string" && !arg.trim()) {
         throw new Error("domain() requires a name");
@@ -679,11 +935,34 @@ export function composeDomain(name, includes = []) {
     for (const include of includes) {
         builder = builder.includes(include);
     }
-    return builder.schema({ entities: {}, links: {}, rooms: {} });
+    return builder.withSchema({ entities: {}, links: {}, rooms: {} });
+}
+/**
+ * Define a domain action without changing the public action contract.
+ *
+ * Convention for new actions:
+ *
+ * `async execute({ runtime, input }) { await runtime.db.transact([...]); }`
+ *
+ * Actions receive a runtime already scoped to the declaring domain. Nested
+ * action composition is available through `runtime.actions.*`.
+ */
+function toJsonSchema(schema) {
+    try {
+        return z.toJSONSchema(schema, { target: "draft-7" });
+    }
+    catch {
+        return undefined;
+    }
 }
 export function defineDomainAction(action) {
-    return action;
+    return Object.freeze({
+        ...action,
+        inputSchema: toJsonSchema(action.input),
+        outputSchema: toJsonSchema(action.output),
+    });
 }
+export const defineAction = defineDomainAction;
 export function getDomainActions(source) {
     return getStoredActions(source);
 }