chore: decision for lua added

Co-authored-by: Copilot <copilot@github.com>

README.md

@@ -22,6 +22,18 @@ The following are intentionally not part of the behavioral contract:
 - ORM choice.
 - Internal state management, concurrency model, or runtime libraries.
 
+## Scripting Direction
+
+bDS2 should use Lua as its user-facing scripting language.
+
+The reason is host fit, not language fashion: Lua has a better embedding story for the BEAM than Python does, while still being small, expressive, and suitable for user-authored macros, transforms, and utility scripts. The current direction is:
+
+- Lua script files as the persisted user script format.
+- A BEAM-hosted execution boundary with explicit host capabilities instead of unrestricted runtime access.
+- Bounded script execution for user-authored code.
+
+This keeps the scripting surface lightweight and aligned with the Elixir host application. Python remains a possible integration boundary for specialized tasks, but it is no longer the default scripting model for the rewrite.
+
 ## Repository Layout
 
 - [mix.exs](/Users/gb/Projects/bDS2/mix.exs): Mix project definition.

specs/editor_script.allium

@@ -16,7 +16,7 @@ value ScriptEditorView {
     title: String                       -- editable text input
     slug: String                        -- editable text input, auto-generated from title
     kind: String                        -- select: utility | macro | transform
-    entrypoint: String                  -- select: dynamically discovered functions, "main" always first
+    entrypoint: String                  -- select: discovered Lua functions available as entrypoints
     enabled: Boolean                    -- checkbox
     content: String                     -- code editor content
     created_at: String                  -- locale-formatted date
@@ -50,11 +50,11 @@ surface ScriptEditorSurface {
         -- Two rows of metadata fields above the editor.
         -- Row 1: Title (text input), Slug (text input, auto-generated from title).
         -- Row 2: Kind (select: utility/macro/transform),
-        --   Entrypoint (select: dynamically discovered functions with "main" always first),
+        --   Entrypoint (select: discovered Lua functions exposed by the script),
         --   Enabled (checkbox).
 
     @guarantee EditorBody
-        -- Code editor with syntax highlighting for the configured scripting language.
+        -- Code editor with Lua syntax highlighting.
         -- Toolbar: "Content" label.
         -- Syntax errors shown as inline markers in editor gutter.
 
@@ -66,23 +66,23 @@ surface ScriptEditorSurface {
 
 rule ScriptSave {
     when: ScriptSaveRequested(script_id)
-    -- Syntax check first using the configured scripting runtime semantics
+    -- Lua syntax check first using the configured runtime semantics
     -- If syntax error: blocks save, shows error inline in editor gutter
     -- If valid: bumps version, saves to DB + rewrites the published script file
-    -- Entrypoint list re-discovered from AST after save
+    -- Entrypoint list re-discovered from Lua source after save
 }
 
 rule ScriptCheckSyntax {
     when: ScriptCheckSyntaxRequested(script_id)
-    -- Validates script syntax without saving
+    -- Validates Lua syntax without saving
     -- Shows errors inline in editor gutter
     -- Success shown as toast or status indicator
 }
 
 rule ScriptRun {
     when: ScriptRunRequested(script_id)
-    -- Executes script in the configured runtime
+    -- Executes the script in the configured Lua runtime
-    -- Calls configured entrypoint function (default: main)
+    -- Calls the configured Lua entrypoint function
     -- stdout/stderr directed to Output panel tab
     -- Output panel auto-opens if not already visible
     -- Errors shown in Output panel with line numbers

specs/frontmatter.allium

@@ -79,7 +79,7 @@ surface MenuOpmlSurface {
 }
 
 config {
-    script_extension: String = "script"
+    script_extension: String = "lua"
 }
 
 -- ============================================================================
@@ -202,7 +202,7 @@ value ScriptFrontmatter {
     slug: String
     title: String
     kind: macro | utility | transform
-    entrypoint: String      -- Default: "render"
+    entrypoint: String      -- Named Lua function used when invoking the script
     enabled: Boolean
     version: Integer
     created_at: Timestamp

specs/script.allium

@@ -2,11 +2,12 @@
 -- bDS Scripting System
 -- Scope: core (Wave 6 — scripting behaviour and file contracts)
 -- Distilled from: src/main/engine/ScriptEngine.ts, schema.ts
--- The scripting runtime is intentionally unspecified here; only behavioural
+-- Lua is the normative scripting language for user-authored scripts in the
--- contracts are normative.
+-- rewrite. The concrete embedding strategy remains an implementation choice;
+-- only the behavioural contract is normative here.
 
 config {
-    script_extension: String = "script"
+    script_extension: String = "lua"
 }
 
 enum ScriptStatus {
@@ -18,7 +19,7 @@ entity Script {
     slug: String
     title: String
     kind: macro | utility | transform
-    entrypoint: String          -- default: "render" for macros
+    entrypoint: String          -- named Lua function used as the script entrypoint
     enabled: Boolean
     status: ScriptStatus
     content: String?
@@ -139,7 +140,7 @@ rule PublishScript {
     when: PublishScriptRequested(script)
     requires: script.status = draft
     requires: ValidateScript(script.content) = valid
-        -- AST parsing must succeed
+        -- Lua parsing must succeed before a script can be published
     ensures: script.status = published
     ensures: ScriptFileWritten(script)
     ensures: script.content = null
@@ -160,6 +161,8 @@ rule ExecuteMacro {
     -- Macro scripts are invoked during template rendering
     -- via [[slug param1=value1 param2=value2]] syntax in post content
     -- They receive named parameters and the template context, return HTML
+    -- from a bounded Lua execution environment that exposes only approved
+    -- host capabilities
     ensures: MacroOutputProduced(script, html_output)
 }
 
@@ -167,7 +170,8 @@ rule ExecuteUtility {
     when: RunUtilityRequested(script)
     requires: script.kind = utility
     requires: script.enabled = true
-    -- Runs on-demand from the UI, produces stdout output
+    -- Runs on-demand from the UI in a bounded Lua execution environment,
+    -- produces stdout output
     ensures: UtilityOutputProduced(script, stdout)
 }
 
@@ -175,7 +179,8 @@ rule ExecuteTransform {
     when: BlogmarkReceived(data)
     -- Transform scripts run sequentially on blogmark deep link data
     -- Input: title, content, tags, categories, source url
-    -- Each transform can modify the data before post creation
+    -- Each transform can modify the data before post creation.
+    -- Execution uses the same bounded Lua host API contract as other scripts.
     let transforms = Scripts where kind = transform and enabled = true
     for t in ordered_by(transforms, s => s.slug):
         ensures: TransformApplied(t, data)