@ekairos/domain 1.22.37-beta.development.0 → 1.22.37

package/dist/index.js

@@ -1,23 +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");
-const EKAIROS_ACTION_STACK = Symbol.for("@ekairos/domain/action-stack");
 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")
@@ -50,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))
@@ -61,7 +63,7 @@ function getStoredActions(source) {
         typeof entry.execute === "function");
 }
 function getStoredActionMap(source) {
-    if (!source || typeof source !== "object")
+    if (!isObjectLike(source))
         return {};
     const raw = source[EKAIROS_ACTION_MAP];
     if (!raw || typeof raw !== "object")
@@ -69,7 +71,7 @@ function getStoredActionMap(source) {
     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, {
@@ -80,7 +82,7 @@ function setStoredActions(source, actions) {
     });
 }
 function setStoredActionMap(source, actionMap) {
-    if (!source || typeof source !== "object")
+    if (!isObjectLike(source))
         return;
     Object.defineProperty(source, EKAIROS_ACTION_MAP, {
         value: Object.freeze({ ...actionMap }),
@@ -89,29 +91,13 @@ function setStoredActionMap(source, actionMap) {
         writable: true,
     });
 }
-function readRuntimeActionStack(runtime) {
-    if (!runtime || typeof runtime !== "object")
-        return [];
-    const stack = runtime[EKAIROS_ACTION_STACK];
-    return Array.isArray(stack) ? [...stack] : [];
-}
-function cloneRuntimeWithActionStack(runtime, stack) {
-    if (!runtime || typeof runtime !== "object")
-        return runtime;
-    const scoped = Object.assign(Object.create(Object.getPrototypeOf(runtime)), runtime);
-    Object.defineProperty(scoped, EKAIROS_ACTION_STACK, {
-        value: [...stack],
-        enumerable: false,
-        configurable: true,
-        writable: true,
-    });
-    return scoped;
-}
 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() : "";
@@ -241,6 +227,17 @@ 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;
@@ -282,6 +279,48 @@ function assertSchemaIncludes(fullSchema, requiredSchema) {
         throw new Error(`ConcreteDomain: schema is missing required keys (${parts.join(" | ")})`);
     }
 }
+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);
@@ -292,8 +331,16 @@ function createConcreteDomain(domainInstance, db, fullSchema, bindings) {
         context: (options) => domainInstance.context(options),
         contextString: (options) => domainInstance.contextString(options),
     };
-    if (bindings?.env !== undefined && bindings?.runtime !== undefined) {
-        const inheritedStack = readRuntimeActionStack(bindings.runtime);
+    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) => {
@@ -305,25 +352,51 @@ function createConcreteDomain(domainInstance, db, fullSchema, bindings) {
                     throw new Error(`domain_action_cycle:${key}`);
                 }
                 const nextStack = [...stack, key];
-                const scopedRuntime = cloneRuntimeWithActionStack(bindings.runtime, nextStack);
+                const scopedRuntime = createActionRuntime(nextStack);
+                const parsedInput = action.input.parse(input);
                 const params = {
-                    env: bindings.env,
-                    input,
+                    input: parsedInput,
                     runtime: scopedRuntime,
                 };
-                return await execute(params);
+                const output = await execute(params);
+                return action.output.parse(output);
             },
         ]));
-        ;
-        concrete.env = bindings.env;
+        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);
 }
@@ -340,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)
@@ -370,7 +443,7 @@ function buildRegistryEntries(meta, options) {
         catch {
             child = null;
         }
-        if (!child || typeof child !== "object")
+        if (!isObjectLike(child))
             continue;
         if (seen.has(child))
             continue;
@@ -492,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)
@@ -500,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,
@@ -519,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({
@@ -576,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();
@@ -613,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;
@@ -628,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) {
@@ -640,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) {
@@ -648,14 +780,18 @@ 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 };
@@ -672,13 +808,13 @@ export function domain(arg) {
                         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) {
+                        for (const lazyGetter of pendingLazyIncludes) {
                             try {
                                 const other = lazyGetter();
                                 if (other) {
                                     const entities = other.entities;
                                     if (entities) {
-                                        finalEntities = { ...finalEntities, ...entities };
+                                        finalEntities = mergeRuntimeEntities(finalEntities, entities);
                                     }
                                     const links = other.links;
                                     if (links) {
@@ -730,7 +866,9 @@ export function domain(arg) {
                         }
                         return frozenSchema;
                     };
-                    const result = {
+                    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)),
@@ -739,22 +877,35 @@ export function domain(arg) {
                         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, bindings) => createConcreteDomain(result, db, resolveSchema(result), bindings);
-                    const reboundActions = seedActions.map((action) => bindAction(action, {
-                        name: action.name,
-                        domain: result,
-                        key: getActionBinding(action)?.key,
+                    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]);
-                    setStoredActionMap(result, { ...seedActionMap });
-                    result.actions = (actionsInput) => {
-                        if (actionsInput === undefined) {
-                            return [...getStoredActions(result)];
-                        }
+                    setStoredActionMap(result, reboundActionMap);
+                    result.actions = getStoredActionMap(result);
+                    result.withActions = (actionsInput) => {
                         const current = getStoredActions(result);
                         const currentMap = getStoredActionMap(result);
                         const additions = normalizeActionCollection(result, actionsInput);
@@ -762,11 +913,16 @@ export function domain(arg) {
                     };
                     result.getActions = () => [...getStoredActions(result)];
                     result.getActionMap = () => ({ ...getStoredActionMap(result) });
+                    result.definition = () => result;
                     return Object.freeze(result);
                 };
                 return createDomainResult([], {});
             },
+            schema(def) {
+                return this.withSchema(def);
+            },
         };
+        return builder;
     }
     if (typeof arg === "string" && !arg.trim()) {
         throw new Error("domain() requires a name");
@@ -779,21 +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 }) { "use step"; const domain = await runtime.use(myDomain); ... }`
+ * `async execute({ runtime, input }) { await runtime.db.transact([...]); }`
  *
- * Actions remain callable directly, from nested `runtime.use(domain).actions.*`
- * composition, and from higher-level workflows that orchestrate them.
+ * 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);
 }