Lua-Semantic

Lua-Semantic is a Lua 5.4.8 fork for AI-native scripting.

It keeps normal Lua behavior first, then adds embedding-backed lookup where the language benefits from it:

• semantic field fallback with .
• semantic method fallback with :
• runtime descendant search with ->
• semantic named arguments and default parameter values
• semantic module loading with find
• a continuity runtime for selected recoverable failures

Current label: 0.5.0-preview

Requirements

You need all of these for the semantic features and bundled previews:

• Windows with MinGW/GCC for the current build flow
• Node.js on PATH
• a Node build that supports node:sqlite
• OPENAI_API_KEY for live embeddings

The repo already includes luavibe.luav, which points luav at the bundled semantic and continuity tools.

Project docs:

• docs index: docs/README.md
• project status: docs/project-status.md
• upstream and attribution: docs/upstream.md
• release bundle: docs/release-bundle.md
• license: LICENSE

What Makes It Different

This fork is trying to make Lua feel natural in a world where embeddings and AI tooling are always nearby.

The design is intentionally pragmatic:

• exact Lua lookup still wins first
• semantic behavior is fallback-oriented, not replacement-oriented
• ordinary variables stay ordinary Lua variables
• the language keeps small, readable syntax changes instead of turning into prompt glue

Included Features

Core language/runtime features in this version:

• semantic field fallback
• semantic method fallback
• runtime -> search
• named semantic arguments
• default parameter values
• local semantic find
• module-local isolation for find

Additional features available in this version:

• continuity runtime
• coordinator-driven retry
• remote registry/server workflow

Quick Start

1. Build the runtime

Windows / MinGW:

cd src
make mingw

That produces:

• src/luav.exe
• src/luavc.exe

2. Make sure Node is available

node --version

Lua-Semantic launches the bundled Node sidecar and coordinator scripts at runtime.

3. Set your API key

$env:OPENAI_API_KEY="..."

4. Run an example script

.\src\luav.exe preview\overview.luav
.\src\luav.exe preview\find_and_isolation.luav

If you want to confirm the full setup before trying your own scripts, also run:

.\src\luav.exe preview\run_all.luav

Examples

• preview/README.md
  • example scripts for the bundled language features
• docs/project-config.md
  • project config and local override file layout

Feature Overview

Semantic Field Fallback

local stats = { health = 42 }
print(stats.hp)

Behavior:

• exact key lookup first
• semantic fallback only on exact miss
• if semantic fallback also misses, normal Lua behavior continues

Semantic Method Fallback

local actor = {
  doAttack = function(self, target, criticalChance)
    return target, criticalChance
  end,
}

local enemyTarget = "orc"
local critRate = 0.25
print(actor:attack(enemyTarget, critRate))

Method matching uses the method name only. Argument labels are used for parameter binding after the callee is selected.

Named Semantic Arguments and Defaults

local function summon(kind, health = 10, position = "center")
  return kind, health, position
end

local enemyType = "slime"
local hp = 33
local pos = "north"

print(summon(kind = enemyType, hp + 0, position = pos))

Rules:

• bare identifiers contribute source labels at semantic call sites
• simple dotted paths contribute their full path
• explicit name = expr overrides the inferred label
• unlabeled complex expressions stay positional
• labels that do not match parameters are ignored
• missing parameters remain nil unless defaults fill them

Runtime Descendant Search

local player = {
  inventory = {
    sword = "bronze sword"
  }
}

print(player->sword)

-> searches named nodes throughout the descendant tree at runtime and returns the best semantic match or nil. It can return intermediate tables as well as leaf values.

Semantic Module Loading With find

local gear = find "gear"
local same = find("inventory")

find keeps classic require unchanged. Local metadata-backed modules are searched first; remote registries are a later fallback.

Module metadata uses a restricted top-of-file header:

@modulemeta {
  key = "inventory gear equipment items loadout",
  description = "Player inventory helpers",
  version = "1.0.0"
}

Current metadata rules:

• key is required and is the only functional semantic field
• description is optional and non-functional
• version is optional and used for remote fetch identity
• metadata is parsed, not executed

Modules loaded through find run in their own module _ENV, so top-level assignments do not mutate the caller's global table.

Continuity Runtime

continuity.config{
  enabled = true,
  coordinator_script = "semantic/continuityd.mjs",
}

Continuity is the recovery runtime for selected failures such as:

• using nil as the receiver of another object-like step
• calling a nil target

The bundled coordinator supports manual resolution out of the box:

• it writes a structured issue file
• waits for a response file
• then returns nil, retries the current statement, or aborts

Start here:

• docs/continuity-user-guide.md
• docs/continuity.md

Project Config

The fork auto-loads project config from:

• luavibe.luav
• luavibe.local.luav

luavibe.luav is intended for checked-in project defaults. luavibe.local.luav is optional, local-only, and ignored by git.

Compatibility fallback:

• luavibe.lua
• luavibe.local.lua

See docs/project-config.md.

What The Runtime Uses

At runtime, luav uses:

• the custom luav executable you build from src/
• the bundled Node scripts under semantic/
• project config from luavibe.luav
• live embedding calls through OPENAI_API_KEY

So the normal workflow is:

1. build luav
2. keep node available on PATH
3. set OPENAI_API_KEY
4. run a file-backed .luav script from the project

Runtime Helpers

The semantic library is opened automatically.

Useful surfaces:

semantic.config{
  threshold = 0.78,
  ambiguity_margin = 0.03,
  arrow_max_depth = 4,
  cache_path = ".lua-semantic/cache.sqlite",
  debug_log_path = ".lua-semantic/debug.log",
}

local hp = semantic.dot(stats, "hp", 0.65)
local sword = semantic.arrow(player, "sword", 0.75)

semantic.override{
  on_miss = function(info)
    return false
  end,
}

Current Limits

• semantic C interop is disabled in this version
• semantic labels on C-defined functions raise an error
• semantic . and : only search immediate members
• -> currently traverses Lua value graphs, not userdata-backed object graphs
• . and : require embeddings during compilation/loading
• -> requires embeddings only when executed

Repo Layout

• src/
  • Lua core plus parser, bytecode, VM, and runtime changes
• semantic/
  • Node sidecar and registry/coordinator scripts
• preview/
  • bundled example scripts
• docs/
  • project-specific guides
• doc/
  • upstream Lua documentation

License

This repository is distributed under the MIT License.

It is an independent fork built on top of upstream Lua 5.4.8. For attribution details, see NOTICE, docs/upstream.md, and doc/readme.html.

This is an independent fork built on top of upstream Lua 5.4.8. For attribution and upstream context, see docs/upstream.md. For the original Lua distribution notes, see doc/readme.html.