Handbook

LMeta v4 execution

AutomationFlow v4 (automationFlowVersion ≤ 4) is the only supported production executor for orchestrated LCDL work in Forge consumers. Higher automationFlowVersion values are rejected at validation time.

Updated

Mental model

  1. Flow document — JSON (.lmeta) with states, transitions, forgeLcdlRun, and optional forgeConsumerHook / forgeDecide actions.
  2. Consumer hooks — product-owned Python functions registered by name (closed allowlist). Hooks own SQLite, paths, and domain policy; LCDL runs tasks only.
  3. FlowExecutor — forge_lcdl.flow.executor.FlowExecutor walks the graph, resolves ${ … } templates, and enforces per-state budget blocks.
  4. Fast-path budget — opt-in budget.max_calls on states that invoke governed LLM tasks; exhausted budgets fail closed (no post-call slow fallback).

When to use v4 directly

Use v4 hand-authored JSON Prefer v5-alpha compile ladder
Stable recipe with known hooks Maintainer edits GoalSpec / profile
Router / dispatch with literal branches CI emits pinned v4 from source
Pack-in regression fixtures Soak before replacing hand rollback

See LMeta v5-alpha authoring for the source ladder.

Consumer hooks

Register hooks in a dict passed to FlowExecutor(consumer_hooks=…). Each hook receives a bounded payload dict; return JSON-serializable dicts only.

Invariant: user utterances must not select hook names, SQL, or filesystem paths — routing and hook allowlists are server-owned.

Decision break-in (optional v4 primitive)

Governed LLM arbitration (forgeDecide, forgeConsensus, guard, budget) is opt in per flow. See Decision break-in.

Verification

  • Validate flows: forge_lcdl.flow.schema.validate_flow / consumer flow_validate modules.
  • Run offline parity: Python handler vs FlowExecutor on the same params (see consumer appendix).
  • Keep automationFlowVersion ≤ 4 in CI pins.