@microverse.ts/microverse-lua 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QADRAX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# `@microverse.ts/microverse-lua`
+
+**Lua microverse** facade for TypeScript applications: `MicroverseLua.create`, Wasm VM, script slots, and the fluent host surface builder.
+
+Monorepo overview: [root README](../../README.md).
+
+## What is a Lua microverse?
+
+One logical scripting universe in your process:
+
+- **One** Wasm-backed Lua VM (Wasmoon), shared for efficiency.
+- **Many** isolated **environment slots** — one per registered script.
+- **One** host **surface** (declarative bridges + optional workflow hooks).
+- **One** host **object** (your TypeScript services).
+- **Per-script capability allowlists** at registration.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  LuaMicroverse (MicroverseLua.create)                       │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  Shared Wasm Lua VM                                   │  │
+│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐     │  │
+│  │  │ slot: a     │ │ slot: b     │ │ slot: c     │     │  │
+│  │  │ caps: […]   │ │ caps: […]   │ │ caps: […]   │     │  │
+│  │  └─────────────┘ └─────────────┘ └─────────────┘     │  │
+│  └───────────────────────────────────────────────────────┘  │
+│         ▲ bridges from host surface + host services         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+pnpm add @microverse.ts/microverse-lua
+```
+
+Workspace: `"@microverse.ts/microverse-lua": "workspace:*"`.
+
+## Quick start
+
+```ts
+import { MicroverseLua, defineHostSurfaceFor } from '@microverse.ts/microverse-lua';
+import { z } from 'zod';
+
+type MyHost = { appName: string };
+
+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} from ${host.appName}`,
+  })
+  .build();
+
+const microverse = MicroverseLua.create({
+  host: { appName: 'Acme' },
+  surface,
+  defaultTimeoutMs: 30_000,
+});
+
+await microverse.registerScript({
+  scriptId: 'welcome',
+  script: `local msg = greet:hello({ name = "world" })`,
+  capabilities: surface.pickCapabilities('demo:greet'),
+});
+
+await microverse.dispose();
+```
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `MicroverseLua.create` | Create a Lua microverse (Wasm VM included). |
+| `registerScript` | New slot + optional preludes + main chunk. |
+| `emitToAllScripts` | Call `on{Kind}` on every script (workflow hooks). |
+| `defineHostSurfaceFor`, `defineHostSurface` | Fluent surface builder (`bridge` → `method` → `build`). |
+
+## IDE stubs
+
+```bash
+pnpm add -D @microverse.ts/cli
+pnpm exec microverse generate-lua-defs --surface src/mySurface.ts
+```
+
+Requires `export default` on the surface module (typically the result of `.build()`). Details: [`@microverse.ts/cli`](../cli/README.md).
+
+## Reference example
+
+[`examples/business-scripting-engine`](../../examples/business-scripting-engine) — rules engine with orders, billing, workflow Lua, and `BusinessScriptingEngine` wrapping this package.
+
+## Related
+
+- Async bridges: [`host-surface/docs/async-subroutines-components.md`](../host-surface/docs/async-subroutines-components.md)
+- Component-style Lua: [`examples/.../COMPONENT_PATTERN.md`](../../examples/business-scripting-engine/docs/COMPONENT_PATTERN.md)

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * **@microverse.ts/microverse-lua** — Lua microverse entry for consuming applications.
+ *
+ * Plug-and-play Lua scripting: **{@link MicroverseLua.create}** (built-in Wasm VM) and the fluent
+ * **{@link defineHostSurfaceFor}** builder (`bridge` → `method` → `build`).
+ */
+export { augmentHostWithCapabilityRegistry, BridgeBuilder, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, HostScriptSession, luaGlobalHookName, luaType, MICROVERSE_CAPABILITY_REGISTRY, pickSurfaceCapabilities, SurfaceBuilder, zodToLuaTypeRef, type AnyHostSurfaceMethod, type HostFnContext, type HostScriptSessionOptions, type HostSurface, type HostSurfaceCore, type HostSurfaceMethodEntry, type HostSurfaceSpec, type HostSurfaceSpecForHost, type HostWorkflowHooksSpec, type InferSurfaceCapabilities, type LuaDefManifestGeneratorOpts, type LuaGlobalHookName, type SchemaValidationPort, type SurfaceCapabilityString, type SurfaceMethodDef, type WithMicroverseCapabilityRegistry, type WorkflowHookInvokeArgs, type ZodToLuaTypeRefOptions, } from '@microverse.ts/host-surface';
+export * from '@microverse.ts/shared';
+export * from '@microverse.ts/runtime-core';
+export * from '@microverse.ts/runtime-lua';
+export * from '@microverse.ts/runtime-wasm';
+export * from '@microverse.ts/runtime-bridge';
+export * from '@microverse.ts/runtime-capabilities';
+export * from '@microverse.ts/runtime-zod';
+export { MicroverseLua } from './infrastructure/facade/microverseLuaNamespace.js';
+export { createLuaMicroverse, LuaMicroverse, type LuaMicroverseConfig, type InferScriptHooksFromHost, type InferScriptHooksFromSurface, type InferSurfaceCapabilitiesFromSurface, type TaggedLuaMicroverseHost, } from './infrastructure/facade/luaMicroverse.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,iCAAiC,EACjC,aAAa,EACb,0BAA0B,EAC1B,sCAAsC,EACtC,kBAAkB,EAClB,qBAAqB,EACrB,2CAA2C,EAC3C,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,EACP,8BAA8B,EAC9B,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,6BAA6B,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,4BAA4B,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,MAAM,mDAAmD,CAAC;AAClF,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,mCAAmC,EACxC,KAAK,uBAAuB,GAC7B,MAAM,0CAA0C,CAAC"}

package/dist/index.js

@@ -0,0 +1,131 @@
+import { BridgeBuilder, HostScriptSession, HostScriptSession as HostScriptSession$1, MICROVERSE_CAPABILITY_REGISTRY, SurfaceBuilder, augmentHostWithCapabilityRegistry, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaGlobalHookName as luaGlobalHookName$1, luaType, pickSurfaceCapabilities, zodToLuaTypeRef } from "@microverse.ts/host-surface";
+import { createLuaEnvSlotKey, fixedTimeout } from "@microverse.ts/runtime-core";
+import { createWasmMicroverseRuntime } from "@microverse.ts/runtime-wasm";
+export * from "@microverse.ts/shared";
+export * from "@microverse.ts/runtime-core";
+export * from "@microverse.ts/runtime-lua";
+export * from "@microverse.ts/runtime-wasm";
+export * from "@microverse.ts/runtime-bridge";
+export * from "@microverse.ts/runtime-capabilities";
+export * from "@microverse.ts/runtime-zod";
+//#region src/infrastructure/facade/luaMicroverse.ts
+function resolveDefaultTimeout(config) {
+	if (config.defaultTimeout !== void 0) return config.defaultTimeout;
+	if (config.defaultTimeoutMs !== void 0) return fixedTimeout(config.defaultTimeoutMs);
+}
+/**
+* One **Lua microverse**: a shared built-in Wasm Lua VM, {@link HostScriptSession}s keyed by `scriptId`, and helpers to
+* register scripts and broadcast hook events. Capabilities per script come from the host surface
+* ({@link HostSurfaceCore.pickCapabilities} / {@link HostSurfaceCore.capabilities}). Created via {@link MicroverseLua.create}
+* or {@link createLuaMicroverse}.
+*/
+var LuaMicroverse = class {
+	config;
+	runtime;
+	sessions = /* @__PURE__ */ new Map();
+	host;
+	surface;
+	envSlotScope;
+	defaultTimeout;
+	sharedLuaChunks;
+	constructor(config) {
+		this.config = config;
+		this.host = config.host;
+		this.surface = config.surface;
+		this.defaultTimeout = resolveDefaultTimeout(config);
+		this.sharedLuaChunks = config.sharedLuaChunks ?? [];
+		this.runtime = createWasmMicroverseRuntime(this.defaultTimeout !== void 0 ? { defaultTimeout: this.defaultTimeout } : {});
+		this.envSlotScope = config.envSlotScope ?? "script";
+	}
+	/** Capability ids declared on the bound host surface. */
+	getSurfaceCapabilities = () => this.surface.capabilities;
+	/**
+	* Loads one Lua chunk in an isolated env slot; `scriptId` must be unique within this microverse.
+	*
+	* @param args.capabilities - Subset of {@link getSurfaceCapabilities}; use `surface.pickCapabilities(…)` at the call site.
+	*/
+	registerScript = async (args) => {
+		const { scriptId, script, capabilities, injectLuaChunks } = args;
+		const preludeChunks = [...this.sharedLuaChunks, ...injectLuaChunks ?? []];
+		if (this.sessions.has(scriptId)) throw new Error(`script already registered: ${scriptId}`);
+		const session = new HostScriptSession$1({
+			runtime: this.runtime,
+			surface: this.surface,
+			host: this.host,
+			slotKey: createLuaEnvSlotKey(`${this.envSlotScope}:${scriptId}`),
+			allowedCapabilities: capabilities,
+			defaultTimeout: this.defaultTimeout
+		});
+		await session.openSession();
+		for (const [index, chunk] of preludeChunks.entries()) {
+			const injected = await session.runChunk(chunk);
+			if (injected._tag !== "ok") {
+				await session.dispose();
+				const detail = injected._tag === "err" && injected.error._tag === "AdapterError" ? injected.error.message : JSON.stringify(injected.error);
+				const which = index < this.sharedLuaChunks.length ? `shared Lua prelude [${index}]` : `script injectLuaChunks [${index - this.sharedLuaChunks.length}]`;
+				throw new Error(`script "${scriptId}" failed injecting ${which}: ${detail}`);
+			}
+		}
+		const loaded = await session.runChunk(script);
+		if (loaded._tag !== "ok") {
+			await session.dispose();
+			const detail = loaded._tag === "err" && loaded.error._tag === "AdapterError" ? loaded.error.message : JSON.stringify(loaded.error);
+			throw new Error(`script "${scriptId}" failed to load: ${detail}`);
+		}
+		this.sessions.set(scriptId, session);
+	};
+	/** Invokes `on{Kind}` on every registered script with the same payload table (Lua literals only). */
+	emitToAllScripts = (async (kind, payload) => {
+		const hook = luaGlobalHookName$1(kind);
+		for (const [id, session] of this.sessions) {
+			const r = await session.invokeGlobalHookIfPresent(hook, payload);
+			if (r._tag !== "ok") {
+				const detail = r._tag === "err" && r.error._tag === "AdapterError" ? r.error.message : JSON.stringify(r.error);
+				throw new Error(`script "${id}" failed on emit: ${detail}`);
+			}
+		}
+	});
+	dispose = async () => {
+		for (const s of this.sessions.values()) await s.dispose();
+		this.sessions.clear();
+	};
+};
+/**
+* Creates a {@link LuaMicroverse} with a **built-in** Wasm Lua VM (Wasmoon). Type `host` with
+* {@link TaggedLuaMicroverseHost} so hook emits narrow correctly.
+*/
+function createLuaMicroverse(config) {
+	return new LuaMicroverse({
+		host: config.host,
+		surface: config.surface,
+		envSlotScope: config.envSlotScope,
+		defaultTimeout: config.defaultTimeout,
+		defaultTimeoutMs: config.defaultTimeoutMs,
+		sharedLuaChunks: config.sharedLuaChunks
+	});
+}
+//#endregion
+//#region src/infrastructure/facade/microverseLuaNamespace.ts
+/**
+* Plug-and-play **Lua microverse** entry point.
+*
+* A Wasmoon-backed VM is always created for you — pass only `host`, `surface`, and optional timeouts /
+* shared Lua preludes. Define bridges with {@link defineHostSurfaceFor} (`bridge` → `method` → `build`).
+*
+* @example
+* ```ts
+* const microverse = MicroverseLua.create({
+*   host: myHost,
+*   surface: mySurface,
+*   defaultTimeoutMs: 30_000,
+* });
+* await microverse.registerScript({ scriptId: 'ai', script: lua, capabilities: surface.pickCapabilities('demo:tick') });
+* ```
+*/
+var MicroverseLua = { 
+/** Creates a {@link LuaMicroverse} with a built-in Wasm Lua runtime. */
+create: createLuaMicroverse };
+//#endregion
+export { BridgeBuilder, HostScriptSession, LuaMicroverse, MICROVERSE_CAPABILITY_REGISTRY, MicroverseLua, SurfaceBuilder, augmentHostWithCapabilityRegistry, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, createLuaMicroverse, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaType, pickSurfaceCapabilities, zodToLuaTypeRef };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/infrastructure/facade/luaMicroverse.ts","../src/infrastructure/facade/microverseLuaNamespace.ts"],"sourcesContent":["import type { z } from 'zod';\n\nimport {\n  HostScriptSession,\n  luaGlobalHookName,\n  type HostSurface,\n  type HostSurfaceCore,\n  type HostWorkflowHooksSpec,\n} from '@microverse.ts/host-surface';\nimport type { CapabilityId } from '@microverse.ts/runtime-capabilities';\nimport {\n  createLuaEnvSlotKey,\n  fixedTimeout,\n  type MicroverseRuntime,\n  type TimeoutPolicy,\n} from '@microverse.ts/runtime-core';\nimport { createWasmMicroverseRuntime } from '@microverse.ts/runtime-wasm';\n\n/** Phantom key: optional on the host **type** so {@link InferScriptHooksFromHost} can recover hook Zod map typing. Never set at runtime. */\ndeclare const SCRIPT_HOOKS_TYPE: unique symbol;\n\n/**\n * Intersects `TBase` with an optional phantom field carrying `THooks` for {@link LuaMicroverse} / {@link createLuaMicroverse} inference.\n */\nexport type TaggedLuaMicroverseHost<\n  THooks extends HostWorkflowHooksSpec,\n  TBase = unknown,\n> = TBase & { readonly [SCRIPT_HOOKS_TYPE]?: THooks };\n\nexport type InferScriptHooksFromHost<THost> = THost extends TaggedLuaMicroverseHost<infer H, unknown>\n  ? H extends HostWorkflowHooksSpec\n    ? H\n    : undefined\n  : undefined;\n\nexport type InferScriptHooksFromSurface<S extends HostSurfaceCore> =\n  S extends HostSurfaceCore<CapabilityId> & { readonly workflowHooks: infer H extends HostWorkflowHooksSpec }\n    ? H\n    : S extends HostSurface<infer H extends HostWorkflowHooksSpec, CapabilityId>\n      ? H\n      : undefined;\n\nexport type InferSurfaceCapabilitiesFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<\n  infer C extends CapabilityId\n>\n  ? C\n  : CapabilityId;\n\ntype EffectiveScriptHooks<THost extends object, TSurface extends HostSurfaceCore> = [InferScriptHooksFromHost<THost>] extends [\n  undefined,\n]\n  ? InferScriptHooksFromSurface<TSurface>\n  : InferScriptHooksFromHost<THost>;\n\nexport type LuaMicroverseConfig<\n  THost extends object = object,\n  THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>,\n  TCapabilities extends CapabilityId = CapabilityId,\n> = {\n  readonly host: THost;\n  /** From {@link defineHostSurface} / {@link defineHostSurfaceFor}; hooks live on `surface.workflowHooks` when present. */\n  readonly surface: HostSurface<THooks, TCapabilities>;\n  /** Prefix for internal Lua env slot ids, default `script` (ids look like `script:my-id`). */\n  readonly envSlotScope?: string | undefined;\n  /** Wall-clock limit per `runChunk` / hook invocation (Wasm adapter + session forwarding). */\n  readonly defaultTimeout?: TimeoutPolicy | undefined;\n  /**\n   * Shorthand for {@link defaultTimeout} as `fixedTimeout(ms)`. Ignored when `defaultTimeout` is set.\n   */\n  readonly defaultTimeoutMs?: number | undefined;\n  /**\n   * Lua sources run in **every** script slot after {@link HostScriptSession.openSession} and before that\n   * script's main chunk. Define shared helpers/libraries here once instead of per {@link registerScript}.\n   */\n  readonly sharedLuaChunks?: readonly string[] | undefined;\n};\n\nfunction resolveDefaultTimeout<\n  THost extends object,\n  THooks extends HostWorkflowHooksSpec | undefined,\n  TCapabilities extends CapabilityId,\n>(config: LuaMicroverseConfig<THost, THooks, TCapabilities>): TimeoutPolicy | undefined {\n  if (config.defaultTimeout !== undefined) {\n    return config.defaultTimeout;\n  }\n  if (config.defaultTimeoutMs !== undefined) {\n    return fixedTimeout(config.defaultTimeoutMs);\n  }\n  return undefined;\n}\n\ntype EmitToAllScriptsFn<THooks extends HostWorkflowHooksSpec | undefined> = THooks extends HostWorkflowHooksSpec\n  ? <const K extends keyof THooks & string>(kind: K, payload: Readonly<z.infer<THooks[K]>>) => Promise<void>\n  : (\n      kind: string,\n      payload: Readonly<Record<string, string | number | boolean>>,\n    ) => Promise<void>;\n\n/**\n * One **Lua microverse**: a shared built-in Wasm Lua VM, {@link HostScriptSession}s keyed by `scriptId`, and helpers to\n * register scripts and broadcast hook events. Capabilities per script come from the host surface\n * ({@link HostSurfaceCore.pickCapabilities} / {@link HostSurfaceCore.capabilities}). Created via {@link MicroverseLua.create}\n * or {@link createLuaMicroverse}.\n */\nexport class LuaMicroverse<\n  THost extends object = object,\n  THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>,\n  TCapabilities extends CapabilityId = CapabilityId,\n> {\n  private readonly runtime: MicroverseRuntime;\n\n  private readonly sessions = new Map<string, HostScriptSession<THost, THooks>>();\n\n  private readonly host: THost;\n\n  private readonly surface: HostSurface<THooks, TCapabilities>;\n\n  private readonly envSlotScope: string;\n\n  private readonly defaultTimeout: TimeoutPolicy | undefined;\n\n  private readonly sharedLuaChunks: readonly string[];\n\n  constructor(private readonly config: LuaMicroverseConfig<THost, THooks, TCapabilities>) {\n    this.host = config.host;\n    this.surface = config.surface;\n    this.defaultTimeout = resolveDefaultTimeout(config);\n    this.sharedLuaChunks = config.sharedLuaChunks ?? [];\n    this.runtime = createWasmMicroverseRuntime(\n      this.defaultTimeout !== undefined ? { defaultTimeout: this.defaultTimeout } : {},\n    );\n    this.envSlotScope = config.envSlotScope ?? 'script';\n  }\n\n  /** Capability ids declared on the bound host surface. */\n  readonly getSurfaceCapabilities = (): readonly TCapabilities[] => this.surface.capabilities;\n\n  /**\n   * Loads one Lua chunk in an isolated env slot; `scriptId` must be unique within this microverse.\n   *\n   * @param args.capabilities - Subset of {@link getSurfaceCapabilities}; use `surface.pickCapabilities(…)` at the call site.\n   */\n  readonly registerScript = async (args: {\n    readonly scriptId: string;\n    readonly script: string;\n    readonly capabilities: readonly TCapabilities[];\n    readonly injectLuaChunks?: readonly string[] | undefined;\n  }): Promise<void> => {\n    const { scriptId, script, capabilities, injectLuaChunks } = args;\n    const preludeChunks = [...this.sharedLuaChunks, ...(injectLuaChunks ?? [])];\n    if (this.sessions.has(scriptId)) {\n      throw new Error(`script already registered: ${scriptId}`);\n    }\n    const session = new HostScriptSession<THost, THooks>({\n      runtime: this.runtime,\n      surface: this.surface,\n      host: this.host,\n      slotKey: createLuaEnvSlotKey(`${this.envSlotScope}:${scriptId}`),\n      allowedCapabilities: capabilities,\n      defaultTimeout: this.defaultTimeout,\n    });\n    await session.openSession();\n    for (const [index, chunk] of preludeChunks.entries()) {\n      const injected = await session.runChunk(chunk);\n      if (injected._tag !== 'ok') {\n        await session.dispose();\n        const detail =\n          injected._tag === 'err' && injected.error._tag === 'AdapterError'\n            ? injected.error.message\n            : JSON.stringify(injected.error);\n        const which =\n          index < this.sharedLuaChunks.length\n            ? `shared Lua prelude [${index}]`\n            : `script injectLuaChunks [${index - this.sharedLuaChunks.length}]`;\n        throw new Error(`script \"${scriptId}\" failed injecting ${which}: ${detail}`);\n      }\n    }\n    const loaded = await session.runChunk(script);\n    if (loaded._tag !== 'ok') {\n      await session.dispose();\n      const detail =\n        loaded._tag === 'err' && loaded.error._tag === 'AdapterError'\n          ? loaded.error.message\n          : JSON.stringify(loaded.error);\n      throw new Error(`script \"${scriptId}\" failed to load: ${detail}`);\n    }\n    this.sessions.set(scriptId, session);\n  };\n\n  /** Invokes `on{Kind}` on every registered script with the same payload table (Lua literals only). */\n  readonly emitToAllScripts = (async (\n    kind: string,\n    payload: Readonly<Record<string, string | number | boolean>>,\n  ) => {\n    const hook = luaGlobalHookName(kind);\n    for (const [id, session] of this.sessions) {\n      const r = await session.invokeGlobalHookIfPresent(hook, payload);\n      if (r._tag !== 'ok') {\n        const detail =\n          r._tag === 'err' && r.error._tag === 'AdapterError' ? r.error.message : JSON.stringify(r.error);\n        throw new Error(`script \"${id}\" failed on emit: ${detail}`);\n      }\n    }\n  }) as EmitToAllScriptsFn<THooks>;\n\n  readonly dispose = async (): Promise<void> => {\n    for (const s of this.sessions.values()) {\n      await s.dispose();\n    }\n    this.sessions.clear();\n  };\n}\n\n/**\n * Creates a {@link LuaMicroverse} with a **built-in** Wasm Lua VM (Wasmoon). Type `host` with\n * {@link TaggedLuaMicroverseHost} so hook emits narrow correctly.\n */\nexport function createLuaMicroverse<\n  THost extends object,\n  const TSurface extends HostSurfaceCore<CapabilityId>,\n>(config: {\n  readonly host: THost;\n  readonly surface: TSurface;\n  readonly envSlotScope?: string | undefined;\n  readonly defaultTimeout?: TimeoutPolicy | undefined;\n  readonly defaultTimeoutMs?: number | undefined;\n  readonly sharedLuaChunks?: readonly string[] | undefined;\n}): LuaMicroverse<THost, EffectiveScriptHooks<THost, TSurface>, InferSurfaceCapabilitiesFromSurface<TSurface>> {\n  type H = EffectiveScriptHooks<THost, TSurface>;\n  type C = InferSurfaceCapabilitiesFromSurface<TSurface>;\n  return new LuaMicroverse<THost, H, C>({\n    host: config.host,\n    surface: config.surface as unknown as HostSurface<H, C>,\n    envSlotScope: config.envSlotScope,\n    defaultTimeout: config.defaultTimeout,\n    defaultTimeoutMs: config.defaultTimeoutMs,\n    sharedLuaChunks: config.sharedLuaChunks,\n  });\n}\n","import { createLuaMicroverse } from './luaMicroverse.js';\n\n/**\n * Plug-and-play **Lua microverse** entry point.\n *\n * A Wasmoon-backed VM is always created for you — pass only `host`, `surface`, and optional timeouts /\n * shared Lua preludes. Define bridges with {@link defineHostSurfaceFor} (`bridge` → `method` → `build`).\n *\n * @example\n * ```ts\n * const microverse = MicroverseLua.create({\n *   host: myHost,\n *   surface: mySurface,\n *   defaultTimeoutMs: 30_000,\n * });\n * await microverse.registerScript({ scriptId: 'ai', script: lua, capabilities: surface.pickCapabilities('demo:tick') });\n * ```\n */\nexport const MicroverseLua = {\n  /** Creates a {@link LuaMicroverse} with a built-in Wasm Lua runtime. */\n  create: createLuaMicroverse,\n} as const;\n"],"mappings":"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"}

package/dist/infrastructure/facade/luaMicroverse.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { HostSurface, HostSurfaceCore, HostWorkflowHooksSpec } from '@microverse.ts/host-surface';
+import { CapabilityId } from '@microverse.ts/runtime-capabilities';
+import { TimeoutPolicy } from '@microverse.ts/runtime-core';
+/** Phantom key: optional on the host **type** so {@link InferScriptHooksFromHost} can recover hook Zod map typing. Never set at runtime. */
+declare const SCRIPT_HOOKS_TYPE: unique symbol;
+/**
+ * Intersects `TBase` with an optional phantom field carrying `THooks` for {@link LuaMicroverse} / {@link createLuaMicroverse} inference.
+ */
+export type TaggedLuaMicroverseHost<THooks extends HostWorkflowHooksSpec, TBase = unknown> = TBase & {
+    readonly [SCRIPT_HOOKS_TYPE]?: THooks;
+};
+export type InferScriptHooksFromHost<THost> = THost extends TaggedLuaMicroverseHost<infer H, unknown> ? H extends HostWorkflowHooksSpec ? H : undefined : undefined;
+export type InferScriptHooksFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<CapabilityId> & {
+    readonly workflowHooks: infer H extends HostWorkflowHooksSpec;
+} ? H : S extends HostSurface<infer H extends HostWorkflowHooksSpec, CapabilityId> ? H : undefined;
+export type InferSurfaceCapabilitiesFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<infer C extends CapabilityId> ? C : CapabilityId;
+type EffectiveScriptHooks<THost extends object, TSurface extends HostSurfaceCore> = [InferScriptHooksFromHost<THost>] extends [
+    undefined
+] ? InferScriptHooksFromSurface<TSurface> : InferScriptHooksFromHost<THost>;
+export type LuaMicroverseConfig<THost extends object = object, THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>, TCapabilities extends CapabilityId = CapabilityId> = {
+    readonly host: THost;
+    /** From {@link defineHostSurface} / {@link defineHostSurfaceFor}; hooks live on `surface.workflowHooks` when present. */
+    readonly surface: HostSurface<THooks, TCapabilities>;
+    /** Prefix for internal Lua env slot ids, default `script` (ids look like `script:my-id`). */
+    readonly envSlotScope?: string | undefined;
+    /** Wall-clock limit per `runChunk` / hook invocation (Wasm adapter + session forwarding). */
+    readonly defaultTimeout?: TimeoutPolicy | undefined;
+    /**
+     * Shorthand for {@link defaultTimeout} as `fixedTimeout(ms)`. Ignored when `defaultTimeout` is set.
+     */
+    readonly defaultTimeoutMs?: number | undefined;
+    /**
+     * Lua sources run in **every** script slot after {@link HostScriptSession.openSession} and before that
+     * script's main chunk. Define shared helpers/libraries here once instead of per {@link registerScript}.
+     */
+    readonly sharedLuaChunks?: readonly string[] | undefined;
+};
+type EmitToAllScriptsFn<THooks extends HostWorkflowHooksSpec | undefined> = THooks extends HostWorkflowHooksSpec ? <const K extends keyof THooks & string>(kind: K, payload: Readonly<z.infer<THooks[K]>>) => Promise<void> : (kind: string, payload: Readonly<Record<string, string | number | boolean>>) => Promise<void>;
+/**
+ * One **Lua microverse**: a shared built-in Wasm Lua VM, {@link HostScriptSession}s keyed by `scriptId`, and helpers to
+ * register scripts and broadcast hook events. Capabilities per script come from the host surface
+ * ({@link HostSurfaceCore.pickCapabilities} / {@link HostSurfaceCore.capabilities}). Created via {@link MicroverseLua.create}
+ * or {@link createLuaMicroverse}.
+ */
+export declare class LuaMicroverse<THost extends object = object, THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>, TCapabilities extends CapabilityId = CapabilityId> {
+    private readonly config;
+    private readonly runtime;
+    private readonly sessions;
+    private readonly host;
+    private readonly surface;
+    private readonly envSlotScope;
+    private readonly defaultTimeout;
+    private readonly sharedLuaChunks;
+    constructor(config: LuaMicroverseConfig<THost, THooks, TCapabilities>);
+    /** Capability ids declared on the bound host surface. */
+    readonly getSurfaceCapabilities: () => readonly TCapabilities[];
+    /**
+     * Loads one Lua chunk in an isolated env slot; `scriptId` must be unique within this microverse.
+     *
+     * @param args.capabilities - Subset of {@link getSurfaceCapabilities}; use `surface.pickCapabilities(…)` at the call site.
+     */
+    readonly registerScript: (args: {
+        readonly scriptId: string;
+        readonly script: string;
+        readonly capabilities: readonly TCapabilities[];
+        readonly injectLuaChunks?: readonly string[] | undefined;
+    }) => Promise<void>;
+    /** Invokes `on{Kind}` on every registered script with the same payload table (Lua literals only). */
+    readonly emitToAllScripts: EmitToAllScriptsFn<THooks>;
+    readonly dispose: () => Promise<void>;
+}
+/**
+ * Creates a {@link LuaMicroverse} with a **built-in** Wasm Lua VM (Wasmoon). Type `host` with
+ * {@link TaggedLuaMicroverseHost} so hook emits narrow correctly.
+ */
+export declare function createLuaMicroverse<THost extends object, const TSurface extends HostSurfaceCore<CapabilityId>>(config: {
+    readonly host: THost;
+    readonly surface: TSurface;
+    readonly envSlotScope?: string | undefined;
+    readonly defaultTimeout?: TimeoutPolicy | undefined;
+    readonly defaultTimeoutMs?: number | undefined;
+    readonly sharedLuaChunks?: readonly string[] | undefined;
+}): LuaMicroverse<THost, EffectiveScriptHooks<THost, TSurface>, InferSurfaceCapabilitiesFromSurface<TSurface>>;
+export {};
+//# sourceMappingURL=luaMicroverse.d.ts.map

package/dist/infrastructure/facade/luaMicroverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"luaMicroverse.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/facade/luaMicroverse.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/facade/microverseLuaNamespace.d.ts

@@ -0,0 +1,22 @@
+import { createLuaMicroverse } from './luaMicroverse.js';
+/**
+ * Plug-and-play **Lua microverse** entry point.
+ *
+ * A Wasmoon-backed VM is always created for you — pass only `host`, `surface`, and optional timeouts /
+ * shared Lua preludes. Define bridges with {@link defineHostSurfaceFor} (`bridge` → `method` → `build`).
+ *
+ * @example
+ * ```ts
+ * const microverse = MicroverseLua.create({
+ *   host: myHost,
+ *   surface: mySurface,
+ *   defaultTimeoutMs: 30_000,
+ * });
+ * await microverse.registerScript({ scriptId: 'ai', script: lua, capabilities: surface.pickCapabilities('demo:tick') });
+ * ```
+ */
+export declare const MicroverseLua: {
+    /** Creates a {@link LuaMicroverse} with a built-in Wasm Lua runtime. */
+    readonly create: typeof createLuaMicroverse;
+};
+//# sourceMappingURL=microverseLuaNamespace.d.ts.map

package/dist/infrastructure/facade/microverseLuaNamespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"microverseLuaNamespace.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/facade/microverseLuaNamespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;IACxB,wEAAwE;;CAEhE,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@microverse.ts/microverse-lua",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "description": "Plug-and-play Lua microverse facade: Wasm VM, MicroverseLua, and re-exports for host surfaces and bridges.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QADRAX/Microverse.ts.git",
+    "directory": "packages/microverse-lua"
+  },
+  "bugs": "https://github.com/QADRAX/Microverse.ts/issues",
+  "homepage": "https://github.com/QADRAX/Microverse.ts/tree/main/packages/microverse-lua",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@microverse.ts/host-surface": "0.1.0",
+    "@microverse.ts/runtime-bridge": "0.1.0",
+    "@microverse.ts/runtime-capabilities": "0.1.0",
+    "@microverse.ts/runtime-core": "0.1.0",
+    "@microverse.ts/runtime-lua": "0.1.0",
+    "@microverse.ts/runtime-wasm": "0.1.0",
+    "@microverse.ts/runtime-zod": "0.1.0",
+    "@microverse.ts/shared": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.1.4"
+  },
+  "scripts": {
+    "build": "vite build",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}