@microverse.ts/host-surface 0.1.0

package/dist/index.js

@@ -0,0 +1,848 @@
+import { buildDeclarativeBridgeTable } from "@microverse.ts/runtime-bridge";
+import { validateWithZodSchema } from "@microverse.ts/runtime-zod";
+import { z } from "zod";
+import { InMemoryCapabilityRegistry, createAllowlist, createCapabilityId } from "@microverse.ts/runtime-capabilities";
+import { createMicroverseScript } from "@microverse.ts/runtime-core";
+//#region src/infrastructure/builders/bridgeMergeEnv.ts
+/**
+* Builds a frozen `mergeEnv` table: bridge name → API object, ready for `MicroverseSlot.run({ mergeEnv })`.
+*
+* @param host - Your host context, already extended with the capability registry symbol from `@microverse.ts/host-surface`.
+* @param slotKey - Same slot key passed to `buildDeclarativeBridgeTable` (string form of `MicroverseId` is fine).
+* @param surface - Result of {@link defineHostSurface} (implements {@link HostSurfaceCore}).
+*/
+function buildBridgeMergeEnvForHost(host, slotKey, surface) {
+	return buildDeclarativeBridgeTable(host, slotKey, [...surface.toBridgeDeclarations()]);
+}
+//#endregion
+//#region src/infrastructure/adapters/zodSchemaValidationAdapter.ts
+function createZodSchemaValidationPort() {
+	return { validateWithZodSchema };
+}
+//#endregion
+//#region src/domain/luaGlobalHook.ts
+/**
+* Builds the `on{Kind}` method name dispatched on the slot’s workflow handler for a PascalCase event `kind`
+* (e.g. `InventoryLow` → `onInventoryLow`).
+* Throws if `kind` is not a safe Lua identifier fragment.
+*/
+function luaGlobalHookName(kind) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(kind)) throw new Error(`unsafe Lua identifier for event kind: ${kind}`);
+	return `on${kind}`;
+}
+//#endregion
+//#region src/domain/luaTypeAtoms.ts
+/** Lua / LuaCATS type atoms: never emit `---@alias` for these names from `lua.paramTypes` / `lua.returns` tokens. */
+var LUA_TYPE_ATOMS = new Set([
+	"any",
+	"boolean",
+	"false",
+	"integer",
+	"nil",
+	"never",
+	"number",
+	"self",
+	"string",
+	"table",
+	"true",
+	"unknown"
+]);
+function isLuaTypeAtom(name) {
+	return LUA_TYPE_ATOMS.has(name);
+}
+//#endregion
+//#region src/domain/zodLuaType.ts
+var aliasBySchema = /* @__PURE__ */ new WeakMap();
+/**
+* Registers a nominal LuaCATS name for a Zod schema. {@link zodToLuaTypeRef} emits the name;
+* `.d.lua` generation adds a matching `---@alias` with the structural shape.
+*
+* @example
+* ```ts
+* export const orderDto = luaType('OrderDto', z.object({ id: z.string() }));
+* // bridge: output: orderDto.optional()  →  returns `OrderDto|nil` in manifest
+* ```
+*/
+function luaType(name, schema) {
+	if (!/^[A-Za-z_]\w*$/.test(name)) throw new Error(`luaType: invalid alias name: ${name}`);
+	aliasBySchema.set(schema, name);
+	return schema;
+}
+/** @internal Root schema that carries a {@link luaType} registration (after unwrapping optional/nullable/…). */
+function getLuaTypeRegistrationRoot(schema) {
+	let cur = schema;
+	for (;;) {
+		if (aliasBySchema.get(cur) !== void 0) return cur;
+		const next = unwrapOneLayer(cur);
+		if (next === void 0) return;
+		cur = next;
+	}
+}
+/** @internal Nominal LuaCATS name for this schema, if registered via {@link luaType}. */
+function resolveZodLuaTypeAlias(schema) {
+	const root = getLuaTypeRegistrationRoot(schema);
+	return root === void 0 ? void 0 : aliasBySchema.get(root);
+}
+function getRegisteredLuaTypeName(root) {
+	return aliasBySchema.get(root);
+}
+function unwrapOneLayer(schema) {
+	if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) return schema.unwrap();
+	if (schema instanceof z.ZodDefault) return schema.removeDefault();
+	if (schema instanceof z.ZodReadonly) return schema.unwrap();
+	if (schema instanceof z.ZodEffects) return schema.innerType();
+	if (schema instanceof z.ZodPipeline) return schema._def.in;
+	if (schema instanceof z.ZodLazy) return schema.schema;
+	if (schema instanceof z.ZodBranded) return schema.unwrap();
+}
+//#endregion
+//#region src/domain/zodToLuaTypeRef.ts
+/**
+* Maps a Zod schema to a LuaCATS type reference string for manifest emission.
+*
+* @remarks
+* Register nominal types with {@link luaType} on shared Zod schemas (e.g. `orderDto`, `orderId`).
+* Prefer that over per-method `lua.paramTypes` / `lua.returns` escape hatches on bridge methods.
+*/
+function zodToLuaTypeRef(schema, options) {
+	const emitAliasNames = options?.emitAliasNames !== false;
+	if (schema instanceof z.ZodOptional) return `${zodToLuaTypeRef(schema.unwrap(), options)}|nil`;
+	if (schema instanceof z.ZodNullable) return `${zodToLuaTypeRef(schema.unwrap(), options)}|nil`;
+	if (schema instanceof z.ZodDefault) return zodToLuaTypeRef(schema.removeDefault(), options);
+	if (schema instanceof z.ZodReadonly) return zodToLuaTypeRef(schema.unwrap(), options);
+	if (schema instanceof z.ZodCatch) return zodToLuaTypeRef(schema._def.innerType, options);
+	if (schema instanceof z.ZodPipeline) return zodToLuaTypeRef(schema._def.out, options);
+	if (schema instanceof z.ZodEffects) return zodToLuaTypeRef(schema.innerType(), options);
+	if (schema instanceof z.ZodLazy) return zodToLuaTypeRef(schema.schema, options);
+	if (schema instanceof z.ZodBranded) return zodToLuaTypeRef(schema.unwrap(), options);
+	if (emitAliasNames) {
+		const alias = resolveZodLuaTypeAlias(schema);
+		if (alias !== void 0) return alias;
+	}
+	if (schema instanceof z.ZodString) return "string";
+	if (schema instanceof z.ZodNumber) return zodNumberToLua(schema);
+	if (schema instanceof z.ZodBoolean) return "boolean";
+	if (schema instanceof z.ZodBigInt) return "integer";
+	if (schema instanceof z.ZodUndefined) return "nil";
+	if (schema instanceof z.ZodNull) return "nil";
+	if (schema instanceof z.ZodVoid) return "nil";
+	if (schema instanceof z.ZodUnknown || schema instanceof z.ZodAny) return "unknown";
+	if (schema instanceof z.ZodLiteral) {
+		const v = schema.value;
+		if (typeof v === "string") return `"${v}"`;
+		if (typeof v === "number" || typeof v === "boolean") return String(v);
+		return "unknown";
+	}
+	if (schema instanceof z.ZodEnum) return schema.options.map((o) => `"${String(o)}"`).join("|");
+	if (schema instanceof z.ZodNativeEnum) return "string|number";
+	if (schema instanceof z.ZodArray) return "table";
+	if (schema instanceof z.ZodRecord) return "table";
+	if (schema instanceof z.ZodObject) {
+		const shape = schema.shape;
+		const keys = Object.keys(shape);
+		if (keys.length === 0) return "{}";
+		return `{ ${keys.map((k) => `${k}: ${zodToLuaTypeRef(shape[k], options)}`).join("; ")} }`;
+	}
+	if (schema instanceof z.ZodUnion) return schema.options.map((o) => zodToLuaTypeRef(o, options)).join("|");
+	if (schema instanceof z.ZodDiscriminatedUnion) return schema.options.map((o) => zodToLuaTypeRef(o, options)).join("|");
+	if (schema instanceof z.ZodIntersection) return "table";
+	if (schema instanceof z.ZodTuple) return "table";
+	return "unknown";
+}
+function zodNumberToLua(schema) {
+	if (schema._def.checks.some((c) => c.kind === "int")) return "integer";
+	return "number";
+}
+//#endregion
+//#region src/domain/hostSurfaceManifest.ts
+function asyncHandleClassName(bridgeName, methodName) {
+	const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+	return `${cap(bridgeName)}${cap(methodName)}Handle`;
+}
+function buildWorkflowHookManifestFields(kinds, workflowHooks, selfType, fieldDescriptionSuffix) {
+	const out = [];
+	for (const kind of kinds) {
+		if (!(workflowHooks[kind] instanceof z.ZodObject)) throw new Error(`defineHostSurface workflowHooks: "${kind}" must be a z.object(...)`);
+		const payloadName = `MicroverseWorkflowEvt_${kind}`;
+		const hookName = luaGlobalHookName(kind);
+		out.push({
+			name: hookName,
+			description: `${fieldDescriptionSuffix} Payload: \`${payloadName}\`.`,
+			luaType: `fun(self: ${selfType}, evt: ${payloadName})`
+		});
+	}
+	return out;
+}
+function pushWorkflowPayloadManifestClasses(kinds, workflowHooks, classes) {
+	for (const kind of kinds) {
+		const schema = workflowHooks[kind];
+		if (!(schema instanceof z.ZodObject)) throw new Error(`defineHostSurface workflowHooks: "${kind}" must be a z.object(...)`);
+		const name = `MicroverseWorkflowEvt_${kind}`;
+		const shape = schema.shape;
+		classes.push({
+			name,
+			description: `Workflow hook payload for \`${luaGlobalHookName(kind)}\` (Zod → LuaCATS fields).`,
+			fields: Object.keys(shape).map((k) => ({
+				name: k,
+				luaType: zodToLuaTypeRef(shape[k])
+			})),
+			emitSingleton: false
+		});
+	}
+}
+function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks) {
+	const classes = [];
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		const manifestMethods = [];
+		for (const methodName of Object.keys(methods)) {
+			const entry = methods[methodName];
+			const resultLua = entry.lua?.returns ?? zodToLuaTypeRef(entry.output);
+			if (entry.async === true) {
+				const handleName = asyncHandleClassName(bridgeName, methodName);
+				const payloadParams = zodInputToManifestParams(entry.input, entry.lua?.paramTypes) ?? [];
+				manifestMethods.push({
+					name: methodName,
+					description: entry.description,
+					callStyle: "asyncBridge",
+					params: [...payloadParams, {
+						name: "onComplete",
+						luaType: `fun(result: ${resultLua})|nil`
+					}],
+					returns: handleName
+				});
+				classes.push({
+					name: handleName,
+					description: `Async handle for \`${bridgeName}:${methodName}\`. Call \`:await()\` for the resolved value.`,
+					fields: [{
+						name: "await",
+						luaType: `fun(self: ${handleName}): ${resultLua}`
+					}],
+					emitSingleton: false
+				});
+			} else manifestMethods.push({
+				name: methodName,
+				description: entry.description,
+				params: zodInputToManifestParams(entry.input, entry.lua?.paramTypes),
+				returns: resultLua
+			});
+		}
+		classes.push({
+			name: bridgeName,
+			methods: manifestMethods
+		});
+	}
+	const fromLuaType = collectLuaTypeAliasesFromHostSpec(spec);
+	const fromOverrides = inferLuaTypeAliasesFromHostSpec(spec);
+	const merged = new Map([...fromLuaType.map((a) => [a.name, a.definition]), ...fromOverrides.map((a) => [a.name, a.definition])]);
+	if (opts.luaTypeAliases !== void 0) for (const [k, v] of Object.entries(opts.luaTypeAliases)) merged.set(k, v);
+	if (workflowHooks !== void 0) {
+		const kinds = Object.keys(workflowHooks).sort((a, b) => a.localeCompare(b));
+		pushWorkflowPayloadManifestClasses(kinds, workflowHooks, classes);
+		const abstractFields = buildWorkflowHookManifestFields(kinds, workflowHooks, "Workflow", "Host invokes this method on your table (from `workflow:extend()`) when the matching domain event fires.");
+		classes.push({
+			name: "Workflow",
+			description: "Abstract workflow handler type. Call `local w = workflow:extend()` then define `function w:onOrderPlaced(evt) … end` (etc.). Each Lua slot has its own `workflow` helper and handler table.",
+			fields: abstractFields,
+			emitSingleton: false
+		});
+		classes.push({
+			name: "workflow",
+			description: "Per-slot helper injected by the host (not a TS bridge). Creates the active handler table for this sandbox slot.",
+			methods: [{
+				name: "extend",
+				description: "Returns a new handler table with default no-op hooks; registers it for host → Lua dispatch in this slot.",
+				params: [],
+				returns: "Workflow"
+			}]
+		});
+	}
+	const aliases = merged.size === 0 ? void 0 : [...merged.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, definition]) => ({
+		name,
+		definition
+	}));
+	return {
+		schemaVersion: 1,
+		output: opts.output,
+		headerNote: opts.headerNote,
+		aliases,
+		classes
+	};
+}
+function nominalTokensFromLuaReturnString(retLua) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const segment of retLua.split("|")) {
+		const s = segment.trim();
+		if (!/^[A-Za-z_]\w*$/.test(s)) continue;
+		if (isLuaTypeAtom(s)) continue;
+		if (seen.has(s)) continue;
+		seen.add(s);
+		out.push(s);
+	}
+	return out;
+}
+function unwrapOutputBaseForAlias(schema) {
+	let cur = schema;
+	for (;;) {
+		if (cur instanceof z.ZodOptional || cur instanceof z.ZodNullable) {
+			cur = cur.unwrap();
+			continue;
+		}
+		if (cur instanceof z.ZodDefault) {
+			cur = cur.removeDefault();
+			continue;
+		}
+		if (cur instanceof z.ZodReadonly) {
+			cur = cur.unwrap();
+			continue;
+		}
+		if (cur instanceof z.ZodEffects) {
+			cur = cur.innerType();
+			continue;
+		}
+		if (cur instanceof z.ZodPipeline) {
+			cur = cur._def.out;
+			continue;
+		}
+		break;
+	}
+	return cur;
+}
+function collectLuaTypeAliasesFromHostSpec(spec) {
+	const byName = /* @__PURE__ */ new Map();
+	const seenRoots = /* @__PURE__ */ new Set();
+	const consider = (schema) => {
+		const root = getLuaTypeRegistrationRoot(schema);
+		if (root === void 0 || seenRoots.has(root)) return;
+		const name = getRegisteredLuaTypeName(root);
+		if (name === void 0) return;
+		seenRoots.add(root);
+		const definition = zodToLuaTypeRef(root, { emitAliasNames: false });
+		if (definition !== name) byName.set(name, definition);
+	};
+	const walk = (schema) => {
+		consider(schema);
+		const base = unwrapInputSchema(schema);
+		if (base instanceof z.ZodObject) {
+			const shape = base.shape;
+			for (const field of Object.values(shape)) consider(field);
+		}
+	};
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		for (const methodName of Object.keys(methods)) {
+			const entry = methods[methodName];
+			walk(entry.input);
+			walk(entry.output);
+		}
+	}
+	return [...byName.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, definition]) => ({
+		name,
+		definition
+	}));
+}
+function inferLuaTypeAliasesFromHostSpec(spec) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		for (const methodName of Object.keys(methods)) {
+			const entry = methods[methodName];
+			const luaParams = entry.lua?.paramTypes;
+			if (luaParams !== void 0) {
+				const baseInput = unwrapInputSchema(entry.input);
+				if (baseInput instanceof z.ZodObject) {
+					const shape = baseInput.shape;
+					for (const [key, L] of Object.entries(luaParams)) {
+						if (typeof L !== "string") continue;
+						if (!/^[A-Za-z_]\w*$/.test(L) || isLuaTypeAtom(L)) continue;
+						const field = shape[key];
+						if (field === void 0) continue;
+						const def = zodToLuaTypeRef(field);
+						if (L !== def) byName.set(L, def);
+					}
+				}
+			}
+			const retLua = entry.lua?.returns;
+			if (typeof retLua === "string" && retLua.length > 0) for (const T of nominalTokensFromLuaReturnString(retLua)) {
+				const def = zodToLuaTypeRef(unwrapOutputBaseForAlias(entry.output));
+				if (T !== def) byName.set(T, def);
+			}
+		}
+	}
+	return [...byName.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, definition]) => ({
+		name,
+		definition
+	}));
+}
+function zodInputToManifestParams(input, luaParamTypes) {
+	const base = unwrapInputSchema(input);
+	if (base instanceof z.ZodObject) {
+		const shape = base.shape;
+		return Object.keys(shape).map((name) => ({
+			name,
+			luaType: luaParamTypes?.[name] ?? zodToLuaTypeRef(shape[name])
+		}));
+	}
+	return [{
+		name: "value",
+		luaType: luaParamTypes?.value ?? zodToLuaTypeRef(base)
+	}];
+}
+function unwrapInputSchema(schema) {
+	let cur = schema;
+	if (cur instanceof z.ZodEffects) cur = cur.innerType();
+	if (cur instanceof z.ZodPipeline) cur = cur._def.in;
+	return cur;
+}
+//#endregion
+//#region src/domain/surfaceCapabilities.ts
+/** Runtime list of capability ids declared on a compiled surface spec. */
+function collectCapabilitiesFromHostSurfaceSpec(spec) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		for (const methodName of Object.keys(methods)) {
+			const id = methods[methodName].capability;
+			const key = String(id);
+			if (!seen.has(key)) {
+				seen.add(key);
+				out.push(id);
+			}
+		}
+	}
+	return out;
+}
+/** Narrows `capabilities` to those declared on the surface (runtime check). */
+function pickSurfaceCapabilities(surfaceCapabilities, ...capabilities) {
+	const allowed = new Set(surfaceCapabilities.map((c) => String(c)));
+	for (const id of capabilities) if (!allowed.has(String(id))) throw new Error(`capability not declared on host surface: ${String(id)} (surface has: ${[...allowed].join(", ")})`);
+	return capabilities;
+}
+//#endregion
+//#region src/domain/capabilityRegistrySymbol.ts
+/**
+* Well-known symbol key used to attach a {@link CapabilityRegistryPort} on the host object
+* while surface bridge methods run. Populated by {@link augmentHostWithCapabilityRegistry} or
+* internally by {@link HostScriptSession}.
+*/
+var MICROVERSE_CAPABILITY_REGISTRY = Symbol.for("microverse:capabilityRegistry");
+//#endregion
+//#region src/application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.ts
+function isThenable(value) {
+	if (value === null || value === void 0) return false;
+	if (typeof value !== "object" && typeof value !== "function") return false;
+	return typeof value.then === "function";
+}
+/**
+* Builds declarative bridge declarations from a host surface spec, using the schema validation port for Lua ↔ host payloads.
+*/
+function createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec) {
+	const out = [];
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		out.push({
+			name: bridgeName,
+			perEntity: true,
+			createApi: (host, slotKey) => {
+				const api = {};
+				for (const methodName of Object.keys(methods)) {
+					const entry = methods[methodName];
+					api[methodName] = (...args) => {
+						const payload = args.length >= 2 ? args[1] : args[0];
+						const registry = host[MICROVERSE_CAPABILITY_REGISTRY];
+						const capability = entry.capability;
+						if (!registry.isAllowed(capability)) throw new Error(`capability denied: ${String(capability)}`);
+						const parsedIn = schemaValidation.validateWithZodSchema(entry.input, payload);
+						if (parsedIn._tag === "err") throw new Error(parsedIn.error);
+						const raw = entry.handler({
+							host,
+							slotKey: String(slotKey)
+						}, parsedIn.value);
+						if (isThenable(raw)) return raw.then((resolved) => {
+							const parsedOut = schemaValidation.validateWithZodSchema(entry.output, resolved);
+							if (parsedOut._tag === "err") throw new Error(parsedOut.error);
+							return parsedOut.value;
+						});
+						const parsedOut = schemaValidation.validateWithZodSchema(entry.output, raw);
+						if (parsedOut._tag === "err") throw new Error(parsedOut.error);
+						return parsedOut.value;
+					};
+				}
+				return Object.freeze(api);
+			}
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/application/useCases/compileHostSurface.ts
+function buildHostSurfaceCore(schemaValidation, spec, workflowHooks) {
+	const capabilities = collectCapabilitiesFromHostSurfaceSpec(spec);
+	return {
+		toBridgeDeclarations: () => createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec),
+		toLuaDefManifest: (opts) => buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks),
+		capabilities,
+		pickCapabilities: (...picked) => pickSurfaceCapabilities(capabilities, ...picked)
+	};
+}
+function compileHostSurface(ports, spec, workflowHooks) {
+	const [schemaValidation] = ports;
+	const core = buildHostSurfaceCore(schemaValidation, spec, workflowHooks);
+	if (workflowHooks === void 0) return core;
+	return {
+		...core,
+		workflowHooks
+	};
+}
+/**
+* Same as {@link compileHostSurface}, but requires every bridge method to be typed with the same `THost`.
+*/
+function compileHostSurfaceFor(ports, spec, workflowHooks) {
+	return workflowHooks === void 0 ? compileHostSurface(ports, spec) : compileHostSurface(ports, spec, workflowHooks);
+}
+//#endregion
+//#region src/domain/inferMethodAsync.ts
+/** Infers {@link HostSurfaceMethodEntry.async} from handler shape unless overridden explicitly. */
+function inferMethodAsync(def) {
+	if (def.async === true) return true;
+	if (def.async === false) return false;
+	return def.handler.constructor.name === "AsyncFunction";
+}
+//#endregion
+//#region src/domain/surfaceMethodDef.ts
+/**
+* Converts a {@link SurfaceMethodDef} into a compiled {@link HostSurfaceMethodEntry}.
+*/
+function normalizeMethodDef(def) {
+	return {
+		capability: createCapabilityId(def.requires),
+		input: def.input,
+		output: def.output,
+		handler: def.handler,
+		async: inferMethodAsync(def),
+		...def.description !== void 0 ? { description: def.description } : {},
+		...def.lua !== void 0 ? { lua: def.lua } : {}
+	};
+}
+//#endregion
+//#region src/domain/safeObjectKey.ts
+/** Keys that must not be used as dynamic property names on ordinary objects. */
+var FORBIDDEN_OBJECT_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Rejects bridge/method names that could trigger prototype pollution when used as object keys.
+*/
+function assertSafeObjectKey(kind, name) {
+	if (FORBIDDEN_OBJECT_KEYS.has(name)) throw new Error(`Invalid surface ${kind} name "${name}": reserved key`);
+}
+/** Record with no inherited prototype — safe for dynamic string keys at runtime. */
+function createNullPrototypeRecord() {
+	return Object.create(null);
+}
+//#endregion
+//#region src/infrastructure/builders/surfaceBuilder.ts
+/**
+* Fluent builder for a host surface. Created via {@link defineHostSurfaceFor} / {@link defineHostSurface} factory overloads.
+*/
+var SurfaceBuilder = class SurfaceBuilder {
+	spec = createNullPrototypeRecord();
+	workflowHooksSpec;
+	ports;
+	constructor(ports, workflowHooks, initialSpec) {
+		this.ports = ports;
+		this.workflowHooksSpec = workflowHooks;
+		if (initialSpec !== void 0) for (const bridgeName of Object.keys(initialSpec)) {
+			assertSafeObjectKey("bridge", bridgeName);
+			const srcBridge = initialSpec[bridgeName];
+			const bridge = createNullPrototypeRecord();
+			for (const methodName of Object.keys(srcBridge)) {
+				assertSafeObjectKey("method", methodName);
+				bridge[methodName] = srcBridge[methodName];
+			}
+			this.spec[bridgeName] = bridge;
+		}
+	}
+	/** Opens a Lua bridge table (e.g. `orders`, `greet`). */
+	bridge(name) {
+		return new BridgeBuilder(this, name);
+	}
+	/** Attaches workflow hook Zod schemas (emitted into `.d.lua` as `on*` methods). */
+	workflowHooks(hooks) {
+		return new SurfaceBuilder(this.ports, hooks, this.spec);
+	}
+	/** Compiles the accumulated spec into a {@link HostSurface}. */
+	build() {
+		const spec = this.spec;
+		return compileHostSurfaceFor(this.ports, spec, this.workflowHooksSpec);
+	}
+	/** @internal */
+	addMethod(bridgeName, methodName, entry) {
+		assertSafeObjectKey("bridge", bridgeName);
+		assertSafeObjectKey("method", methodName);
+		let bridge = this.spec[bridgeName];
+		if (bridge === void 0) {
+			bridge = createNullPrototypeRecord();
+			this.spec[bridgeName] = bridge;
+		}
+		bridge[methodName] = entry;
+		return this;
+	}
+};
+/**
+* Per-bridge step in the fluent surface DSL. Return to {@link SurfaceBuilder} via `.method(…)`.
+*/
+var BridgeBuilder = class {
+	parent;
+	bridgeName;
+	constructor(parent, bridgeName) {
+		this.parent = parent;
+		this.bridgeName = bridgeName;
+	}
+	/** Registers one method on the current bridge and returns the root builder for chaining. */
+	method(name, def) {
+		return this.parent.addMethod(this.bridgeName, name, normalizeMethodDef(def));
+	}
+};
+//#endregion
+//#region src/infrastructure/builders/defineHostSurfaceFacade.ts
+var defaultPorts = [createZodSchemaValidationPort()];
+function createSurfaceBuilder() {
+	return new SurfaceBuilder(defaultPorts);
+}
+/**
+* Declares a **host surface** via the fluent builder (`bridge` → `method` → `build`).
+*
+* @example
+* ```ts
+* const surface = defineHostSurface()
+*   .bridge('time')
+*   .method('delta', {
+*     requires: 'engine:time',
+*     input: z.object({}),
+*     output: z.number(),
+*     handler: ({ host }) => host.clock.dt,
+*   })
+*   .build();
+* ```
+*/
+function defineHostSurface() {
+	return createSurfaceBuilder();
+}
+/**
+* Same as {@link defineHostSurface}, but every `handler` is typed against a single `THost`
+* (the engine context passed to {@link HostScriptSession} / {@link MicroverseLua.create}).
+*
+* @example
+* ```ts
+* const surface = defineHostSurfaceFor<MyHost>()
+*   .bridge('greet')
+*   .method('hello', {
+*     requires: 'demo:greet',
+*     input: z.object({ name: z.string() }),
+*     output: z.string(),
+*     handler: ({ host }, { name }) => `Hello, ${name}`,
+*   })
+*   .build();
+* ```
+*/
+function defineHostSurfaceFor() {
+	return createSurfaceBuilder();
+}
+//#endregion
+//#region src/infrastructure/adapters/augmentHostWithCapabilityRegistry.ts
+/**
+* Returns a shallow copy of `host` with {@link MICROVERSE_CAPABILITY_REGISTRY} set to `registry`.
+* Bridge handlers read the registry to enforce per-session capability allowlists.
+*
+* @param host - Your engine / service context passed into `buildDeclarativeBridgeTable`.
+* @param registry - Typically an {@link InMemoryCapabilityRegistry} from `@microverse.ts/runtime-capabilities`.
+*/
+function augmentHostWithCapabilityRegistry(host, registry) {
+	return Object.assign(host, { [MICROVERSE_CAPABILITY_REGISTRY]: registry });
+}
+//#endregion
+//#region src/infrastructure/components/hostScriptSession.ts
+/**
+* Binds one **Lua slot** to a {@link HostSurface}: capability allowlist, Zod validation, and `mergeEnv` wiring.
+*
+* @remarks
+* - **Lua → host (bridges):** tables/methods from {@link defineHostSurface} on `_ENV` call into TypeScript with Zod validation.
+* - **Host → Lua (hooks):** when the surface defines `workflowHooks`, {@link HostScriptSession.openSession} installs
+*   a small `workflow` helper (`workflow:extend()` → handler table + slot registration) and
+*   {@link HostScriptSession.invokeGlobalHookIfPresent} dispatches `on…` methods on that table. Each session has its own
+*   slot env, so many workflows run concurrently without sharing Lua globals. Without `workflowHooks`, hooks are optional
+*   globals (`onSmoke`, …) invoked as plain functions.
+* - Call {@link HostScriptSession.openSession} once before running chunks or invocations; {@link HostScriptSession.dispose} when the slot is torn down.
+*
+* @typeParam THost - Same host type as your surface handlers.
+* @typeParam THooks - Align with {@link HostSurface} `workflowHooks` on the surface you pass in (or `undefined` when the surface has no workflow hooks).
+*/
+var HostScriptSession = class {
+	opts;
+	sandbox;
+	registry;
+	constructor(opts) {
+		this.opts = opts;
+		this.registry = new InMemoryCapabilityRegistry(createAllowlist([...opts.allowedCapabilities]));
+	}
+	/**
+	* Allocates the underlying {@link MicroverseSlot} for this `slotKey` on the shared runtime.
+	*/
+	openSession = async () => {
+		this.sandbox = await this.opts.runtime.createMicroverse({ slotKey: this.opts.slotKey });
+		const hooks = readWorkflowHooks(this.opts.surface);
+		if (hooks !== void 0) {
+			const prelude = buildWorkflowStubPreludeLua(hooks);
+			await this.requireMicroverseSlot().run({
+				script: createMicroverseScript(prelude),
+				mergeEnv: this.mergeEnv(),
+				timeout: this.opts.defaultTimeout
+			});
+		}
+	};
+	/**
+	* Exposes the in-memory registry (e.g. to mutate allowlists in advanced tests).
+	*/
+	getCapabilityRegistry = () => this.registry;
+	requireMicroverseSlot() {
+		if (this.sandbox === void 0) throw new Error("HostScriptSession: openSession() was not called");
+		return this.sandbox;
+	}
+	mergeEnv() {
+		return buildBridgeMergeEnvForHost(augmentHostWithCapabilityRegistry(this.opts.host, this.registry), String(this.opts.slotKey), this.opts.surface);
+	}
+	/**
+	* Executes Lua source in the slot environment with surface bridges on `_ENV`.
+	*
+	* @param source - Full Lua chunk (compiled with `load(..., "t", env)` in the Wasm adapter).
+	*/
+	runChunk = async (source) => {
+		return this.requireMicroverseSlot().run({
+			script: createMicroverseScript(source),
+			mergeEnv: this.mergeEnv(),
+			timeout: this.opts.defaultTimeout
+		});
+	};
+	/**
+	* Host → Lua: when the surface has `workflowHooks`, invokes `impl:onHook(evt)` on the handler table registered by
+	* `workflow:extend()` in this slot. Otherwise invokes `_ENV[globalName](evt)` when that entry is a function.
+	*
+	* @param globalName - Hook method name, e.g. `onOrderPlaced` (same as {@link luaGlobalHookName}).
+	* @param payload - Table fields: only string, finite number, or boolean (Lua literals).
+	*/
+	invokeGlobalHookIfPresent = (async (globalName, payload) => {
+		assertSafeLuaGlobalName(globalName);
+		const sb = this.requireMicroverseSlot();
+		const tbl = luaTableLiteralFromPlainRecord(payload);
+		const src = readWorkflowHooks(this.opts.surface) !== void 0 ? buildWorkflowHookInvokeLuaSource(globalName, tbl) : buildGlobalHookInvokeLuaSource(globalName, tbl);
+		return sb.run({
+			script: createMicroverseScript(src),
+			mergeEnv: this.mergeEnv(),
+			timeout: this.opts.defaultTimeout
+		});
+	});
+	/**
+	* Host → Lua: invokes `_ENV[tableName][methodName](literalTable)` where `literalTable` is built only from
+	* string, finite number, or boolean fields in `payload`.
+	*
+	* @param tableName - Global table name in the slot env.
+	* @param methodName - Function field on that table.
+	* @param payload - Plain serializable fields for the Lua table literal.
+	*/
+	call = async (tableName, methodName, payload) => {
+		const sb = this.requireMicroverseSlot();
+		const tbl = luaTableLiteralFromUnknownRecord(payload);
+		const src = [
+			`local t = _ENV[${JSON.stringify(tableName)}]`,
+			`local f = type(t) == "table" and t[${JSON.stringify(methodName)}] or nil`,
+			`if type(f) == "function" then`,
+			`  f(${tbl})`,
+			`end`
+		].join("\n");
+		return sb.run({
+			script: createMicroverseScript(src),
+			mergeEnv: this.mergeEnv(),
+			timeout: this.opts.defaultTimeout
+		});
+	};
+	/**
+	* Releases the slot in the runtime adapter and clears the session handle.
+	*/
+	dispose = async () => {
+		if (this.sandbox !== void 0) {
+			await this.sandbox.dispose();
+			this.sandbox = void 0;
+		}
+	};
+};
+function assertSafeLuaGlobalName(name) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe Lua global name: ${name}`);
+}
+function readWorkflowHooks(surface) {
+	if (!("workflowHooks" in surface)) return;
+	return surface.workflowHooks;
+}
+function buildWorkflowStubPreludeLua(hooks) {
+	return [
+		"local Base = {}",
+		"for _, name in ipairs({",
+		...Object.keys(hooks).sort((a, b) => a.localeCompare(b)).map((kind) => {
+			if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(kind)) throw new Error(`unsafe workflow hook kind: ${kind}`);
+			return JSON.stringify(luaGlobalHookName(kind));
+		}).map((h) => `  ${h},`),
+		"}) do",
+		"  rawset(Base, name, function() end)",
+		"end",
+		"rawset(_ENV, \"workflow\", {",
+		"  extend = function(_)",
+		"    local w = setmetatable({}, { __index = Base })",
+		"    rawset(_ENV, \"__microverse_lua_WorkflowImpl\", w)",
+		"    return w",
+		"  end,",
+		"})"
+	].join("\n");
+}
+function buildWorkflowHookInvokeLuaSource(methodName, evtLiteral) {
+	return [
+		`local impl = rawget(_ENV, "__microverse_lua_WorkflowImpl")`,
+		`if type(impl) == "table" then`,
+		`  local m = rawget(impl, ${JSON.stringify(methodName)})`,
+		`  if type(m) == "function" then`,
+		`    m(impl, ${evtLiteral})`,
+		`  end`,
+		`end`
+	].join("\n");
+}
+function buildGlobalHookInvokeLuaSource(globalName, evtLiteral) {
+	return [
+		`local f = rawget(_ENV, ${JSON.stringify(globalName)})`,
+		`if type(f) == "function" then`,
+		`  f(${evtLiteral})`,
+		`end`
+	].join("\n");
+}
+function luaTableLiteralFromPlainRecord(o) {
+	const parts = [];
+	for (const [k, v] of Object.entries(o)) if (typeof v === "string") parts.push(`${k} = ${JSON.stringify(v)}`);
+	else if (typeof v === "number" && Number.isFinite(v)) parts.push(`${k} = ${v}`);
+	else if (typeof v === "boolean") parts.push(`${k} = ${v ? "true" : "false"}`);
+	else throw new Error(`HostScriptSession: unsupported value type for key ${k}`);
+	return `{ ${parts.join(", ")} }`;
+}
+function luaTableLiteralFromUnknownRecord(o) {
+	const parts = [];
+	for (const [k, v] of Object.entries(o)) if (typeof v === "string") parts.push(`${k} = ${JSON.stringify(v)}`);
+	else if (typeof v === "number" && Number.isFinite(v)) parts.push(`${k} = ${v}`);
+	else if (typeof v === "boolean") parts.push(`${k} = ${v ? "true" : "false"}`);
+	else throw new Error(`HostScriptSession.call: unsupported value type for key ${k}`);
+	return `{ ${parts.join(", ")} }`;
+}
+//#endregion
+export { BridgeBuilder, HostScriptSession, MICROVERSE_CAPABILITY_REGISTRY, SurfaceBuilder, augmentHostWithCapabilityRegistry, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaType, pickSurfaceCapabilities, zodToLuaTypeRef };
+
+//# sourceMappingURL=index.js.map