lua-cli 3.31.0 → 3.32.1

package/template/examples/workflows/provision-tenant.ts

@@ -1,18 +1,35 @@
 // Nested workflow + sleep + signal.
-// Verbatim from workflows-spec 03 §3.2 (c) (WF-215 / WF-223 — the spec is normative).
+// From workflows-spec 03 §3.2 (c) (WF-215 / WF-223 — the spec is normative). LUA-635: the switch arms are the
+// createStep objects themselves — a STRING arm names an agentStep / specialistStep / toolStep / map / workflow
+// declaration elsewhere in the chain (03 §3.2.0); `.then(createStep({ id }))` places a step, it never declares one.
 import { z } from 'zod';
 import { createStep, createWorkflow, step, eq, lit, fromInit } from 'lua-cli';
 
+const finalize = createStep({
+  id: 'finalize',
+  inputSchema: z.any(),
+  outputSchema: z.object({ ready: z.boolean() }),
+  execute: async () => ({ ready: true }),
+});
+const rollback = createStep({
+  id: 'rollback',
+  inputSchema: z.any(),
+  outputSchema: z.object({ ready: z.boolean() }),
+  execute: async () => ({ ready: false }),
+});
+
 export const provision = createWorkflow({
   name: 'provision-tenant',
   inputSchema: z.object({ tenantId: z.string() }),
   outputSchema: z.object({ ready: z.boolean() }),
 })
-  .workflow('createResources', 'research-brief', { topic: fromInit('tenantId') })  // nested by name (same agent) or LuaWorkflow ref
-  .sleep(5 * 60 * 1000)                                                             // engine-side; holds no compute
-  .waitForSignal('vendorReady', { signal: 'vendor.ready', schema: z.object({ ok: z.boolean() }),
-    timeoutHours: 72, acceptedSources: ['webhook', 'api'] })
-  .switch([[eq(step('vendorReady').path('ok'), lit(true)), 'finalize']], 'rollback')
-  .then(createStep({ id: 'finalize', inputSchema: z.any(), outputSchema: z.object({ ready: z.boolean() }), execute: async () => ({ ready: true }) }))
-  .then(createStep({ id: 'rollback', inputSchema: z.any(), outputSchema: z.object({ ready: z.boolean() }), execute: async () => ({ ready: false }) }))
+  .workflow('createResources', 'research-brief', { topic: fromInit('tenantId') }) // nested by name (same agent) or LuaWorkflow ref
+  .sleep(5 * 60 * 1000) // engine-side; holds no compute
+  .waitForSignal('vendorReady', {
+    signal: 'vendor.ready',
+    schema: z.object({ ok: z.boolean() }),
+    timeoutHours: 72,
+    acceptedSources: ['webhook', 'api'],
+  })
+  .switch([[eq(step('vendorReady').path('ok'), lit(true)), finalize]], rollback) // inline code steps; the last entry is a conditional, so the taken arm's output is the run output
   .commit();

package/template/examples/workflows/refund-approval.ts

@@ -5,19 +5,26 @@ import { createStep, createWorkflow, template, Integrations } from 'lua-cli';
 
 const postRefund = createStep({
   id: 'postRefund',
-  inputSchema: z.object({ approved: z.boolean(), editedPayload: z.object({ ticketId: z.string(), amount: z.number() }).optional(),
-                          input: z.object({ ticketId: z.string(), amount: z.number() }) }),   // the approval node's output shape (04 §4.2.3)
+  inputSchema: z.object({
+    approved: z.boolean(),
+    editedPayload: z.object({ ticketId: z.string(), amount: z.number() }).optional(),
+    input: z.object({ ticketId: z.string(), amount: z.number() }),
+  }), // the approval node's output shape (04 §4.2.3)
   outputSchema: z.object({ refundId: z.string().nullable() }),
-  sideEffects: 'external',                                  // a platform-fault reclaim PARKS this step (never auto-retried); the run gates `exception` (§06 §6.3.5)
-  onError: 'park',                                          // a final customer-fault failure parks too — the operator retries / skips / supplies the refundId / fails it
-  requiredConnections: ['stripe'],                          // unmountable ⇒ failed{credentials_revoked, reason:'required_connection_unmountable'} → parked via onError:'park' (§11 §11.5.5)
+  sideEffects: 'external', // a platform-fault reclaim PARKS this step (never auto-retried); the run gates `exception` (§06 §6.3.5)
+  onError: 'park', // a final customer-fault failure parks too — the operator retries / skips / supplies the refundId / fails it
+  requiredConnections: ['stripe'], // the declared key below — resolved on the owner agent at run time (LUA-623); no connection of that type ⇒ failed{credentials_unresolved}, unmountable ⇒ failed{credentials_revoked, reason:'required_connection_unmountable'} → parked via onError:'park' (§11 §11.5.5)
   async execute({ inputData, occurrenceId }) {
     if (!inputData.approved) return { refundId: null };
     const r = inputData.editedPayload ?? inputData.input;
     // `occurrenceId` is `${lineageId}:${stepId}`: the same key on retry-step, on resume and on a REPAIR RUN — the refund collapses to one (§06 §6.3.3 (e)).
     // A key that must hold across INDEPENDENT runs (two runs for the same ticket) is the caller's: `refund:${r.ticketId}` (§06 §6.3.3 (f)).
-    const res = await Integrations.passthrough('stripe', { method: 'POST', path: '/v1/refunds',
-      headers: { 'Idempotency-Key': `refund:${r.ticketId}` }, body: { charge: r.ticketId, amount: r.amount } });
+    const res = await Integrations.passthrough('stripe', {
+      method: 'POST',
+      path: '/v1/refunds',
+      headers: { 'Idempotency-Key': `refund:${r.ticketId}` },
+      body: { charge: r.ticketId, amount: r.amount },
+    });
     return { refundId: res.body.id };
   },
 });
@@ -26,18 +33,24 @@ export const refund = createWorkflow({
   name: 'refund-approval',
   inputSchema: z.object({ ticketId: z.string(), amount: z.number(), requesterId: z.string() }),
   outputSchema: z.object({ refundId: z.string().nullable() }),
-  budget: { maxDurationSeconds: 14 * 24 * 3600 },          // long enough for two business-hours escalation hops (the compiler warns `deadline-clamped` otherwise)
+  budget: { maxDurationSeconds: 14 * 24 * 3600 }, // long enough for two business-hours escalation hops (the compiler warns `deadline-clamped` otherwise)
+  connections: [{ key: 'stripe', integrationType: 'stripe', required: true }], // the Stripe connection the refund step acts through, declared once by key — never a frozen connection id (LUA-623)
 })
   .approval('approveRefund', {
-    title: 'Refund request', details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
-    approver: { role: 'support-lead' },                      // org role, template-portable; `{users:[…]}` / `{group:'finance'}` are org data (§13 §13.3.3)
-    excludeInitiator: true,                                  // the requester who started the run can never approve it (maker-checker)
-    fourEyes: { edit: { role: 'support-lead' }, approve: { role: 'finance-controller' } },   // whoever edits the amount cannot be the one who approves it
-    timeoutHours: 8, businessHours: { tz: 'Europe/London', calendar: 'mon-fri' },            // 8 business hours, then…
-    onTimeout: [{ escalateTo: { role: 'finance-controller' }, timeoutHours: 16 },              // …hop 1: finance, 16 business hours, then…
-                { escalateTo: 'org-admins', timeoutHours: 24 },                                // …hop 2: org admins, then…
-                'deny'],                                                                        // …the node completes {approved:false, timedOut:true, escalations:2} — branchable data (§06 §6.4.11)
-    editable: true, editablePaths: ['amount'],               // the approver may lower the amount; the approve call echoes the fingerprint of the revision it saw (§06 §6.4.9)
+    title: 'Refund request',
+    details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
+    approver: { role: 'support-lead' }, // org role, template-portable; `{users:[…]}` / `{group:'finance'}` are org data (§13 §13.3.3)
+    excludeInitiator: true, // the requester who started the run can never approve it (maker-checker)
+    fourEyes: { edit: { role: 'support-lead' }, approve: { role: 'finance-controller' } }, // whoever edits the amount cannot be the one who approves it
+    timeoutHours: 8,
+    businessHours: { tz: 'Europe/London', calendar: 'mon-fri' }, // 8 business hours, then…
+    onTimeout: [
+      { escalateTo: { role: 'finance-controller' }, timeoutHours: 16 }, // …hop 1: finance, 16 business hours, then…
+      { escalateTo: 'org-admins', timeoutHours: 24 }, // …hop 2: org admins, then…
+      'deny',
+    ], // …the node completes {approved:false, timedOut:true, escalations:2} — branchable data (§06 §6.4.11)
+    editable: true,
+    editablePaths: ['amount'], // the approver may lower the amount; the approve call echoes the fingerprint of the revision it saw (§06 §6.4.9)
     editedPayloadSchema: z.object({ ticketId: z.string(), amount: z.number().positive().max(500) }),
   })
   .then(postRefund)

package/template/examples/workflows/support-triage.ts

@@ -1,44 +1,81 @@
 // Support triage from a customer channel — knowledge grounding, toolScope, dataset ref, ctx.artefacts.
-// Verbatim from workflows-spec 03 §3.2 (g) (WF-215 / WF-223 — the spec is normative).
-import { createWorkflow, createStep, fromInit, fromKnowledge, rows, template, stepOf, gt, lit } from 'lua-cli';
+// From workflows-spec 03 §3.2 (g) (WF-215 / WF-223 — the spec is normative). LUA-635: the listing's `.conditional([{ when, branch }])`
+// is not in the builder (03 §3.1 has `switch` / `branch` over `[predicate, StepRef]` arms) and it named an approval as an arm, which
+// v1 forbids (approvals are top-level only) — the gate is a `switch` whose confident arm is (e)'s `refund-approval` as a child run.
+// (The listing's `template(…)` approval title was the other drift: the grammar is `title: string`, bindings ride `details`.)
+import {
+  createWorkflow,
+  createStep,
+  fromInit,
+  fromStep,
+  fromKnowledge,
+  rows,
+  template,
+  stepOf,
+  gt,
+  lit,
+} from 'lua-cli';
 import { z } from 'zod';
 
-const pullHistory = createStep({                                       // array-typed output ⇒ oversize (> 8 MB) becomes a `{__datasetRef}` (NDJSON on CDN), never OUTPUT_TOO_LARGE
-  id: 'pullHistory', inputSchema: z.object({ customerId: z.string() }),
+const pullHistory = createStep({
+  // array-typed output ⇒ oversize (> 8 MB) becomes a `{__datasetRef}` (NDJSON on CDN), never OUTPUT_TOO_LARGE
+  id: 'pullHistory',
+  inputSchema: z.object({ customerId: z.string() }),
   outputSchema: z.object({ orders: z.array(z.object({ id: z.string(), total: z.number(), status: z.string() })) }),
   execute: async (ctx) => {
     const orders = await Orders.list({ customerId: ctx.inputData.customerId, limit: 50_000 });
     const csv = ['id,total,status', ...orders.map((o) => `${o.id},${o.total},${o.status}`)].join('\n');
-    const { artefactId } = await ctx.artefacts.put('orders.csv', csv, {                    // P1-8: journaled in script form; ≤ 50 per step
-      contentType: 'text/csv', kind: 'dataset', datasetSchema: { type: 'object', properties: { id: { type: 'string' }, total: { type: 'number' }, status: { type: 'string' } } } });
+    const { artefactId } = await ctx.artefacts.put('orders.csv', csv, {
+      // P1-8: journaled in script form; ≤ 50 per step
+      contentType: 'text/csv',
+      kind: 'dataset',
+      datasetSchema: {
+        type: 'object',
+        properties: { id: { type: 'string' }, total: { type: 'number' }, status: { type: 'string' } },
+      },
+    });
     ctx.log(`orders.csv → ${artefactId}`);
     return { orders };
   },
 });
 
-const classifyOut = z.object({ intent: z.enum(['refund', 'status', 'other']), confidence: z.number(), orderId: z.string().optional() });
+const classifyOut = z.object({
+  intent: z.enum(['refund', 'status', 'other']),
+  confidence: z.number(),
+  orderId: z.string().optional(),
+  amount: z.number().optional(),
+}); // `amount`: the order total a confident refund carries into (e)
 
 export default createWorkflow({
-  name: 'support-triage', inputSchema: z.object({ ticketId: z.string(), customerId: z.string(), message: z.string() }),
+  name: 'support-triage',
+  inputSchema: z.object({ ticketId: z.string(), customerId: z.string(), message: z.string() }),
 })
   .then(pullHistory)
-  .map({
-    refund: fromKnowledge({ source: 'org-docs', query: 'refund policy', maxChars: 4000, topK: 3 }),   // rendered at S2 with a provenance header per chunk
-    recent: rows('pullHistory', 'orders', { offset: 0, limit: 20 }),                                  // paged rows; the bare ref would be the {__datasetRef} object
-  }, { id: 'classifyInputs' })
+  .map(
+    {
+      refund: fromKnowledge({ source: 'org-docs', query: 'refund policy', maxChars: 4000, topK: 3 }), // rendered at S2 with a provenance header per chunk
+      recent: rows('pullHistory', 'orders', { offset: 0, limit: 20 }), // paged rows; the bare ref would be the {__datasetRef} object
+    },
+    { id: 'classifyInputs' }
+  )
   .agentStep('classify', {
     agentId: 'support-agent',
     // `${initData.message}` is customer-channel content and `refund` is a {knowledge} binding: this step is EXTERNAL-CONTENT — `toolScope` is mandatory.
-    prompt: template('Ticket ${initData.ticketId}: ${initData.message}\n\nRefund policy:\n${stepResults.classifyInputs.refund}\n\nRecent orders (first page):\n${stepResults.classifyInputs.recent}'),
-    toolScope: {},                                                          // `{}` = no tools; `defaultToolScopeMode:'deny'` would imply this when absent
+    prompt: template(
+      'Ticket ${initData.ticketId}: ${initData.message}\n\nRefund policy:\n${stepResults.classifyInputs.refund}\n\nRecent orders (first page):\n${stepResults.classifyInputs.recent}'
+    ),
+    toolScope: {}, // `{}` = no tools; `defaultToolScopeMode:'deny'` would imply this when absent
     outputSchema: classifyOut,
   })
-  .approval('refundGate', { title: template('Refund ${stepResults.classify.orderId}?'), approver: 'org-admins',   // NOT 'creator': `approver-is-run-principal` on a customer-channel workflow
-    details: template('${stepResults.classify.intent} @ ${stepResults.classify.confidence}'), timeoutHours: 24,
-    onTimeout: [{ escalateTo: 'org-admins', timeoutHours: 24 }, 'deny'] })                              // approvers re-resolved at suspend AND decision (§06 §6.11); the card previews `orders.csv` (name/size/rowCount + an R32 link)
-  .conditional([
-    { when: gt(stepOf<typeof classifyOut>('classify').path('confidence'), lit(0.8)), branch: 'refundGate' },
-    { when: lit(true), branch: 'handoff' },
-  ])
-  .agentStep('handoff', { agentId: 'support-agent', prompt: template('Summarise ${initData.message} for a human agent.'), toolScope: {} })
+  .switch([[gt(stepOf<typeof classifyOut>('classify').path('confidence'), lit(0.8)), 'refundGate']], 'handoff') // a confident refund goes to the gate, anything else to a human. An approval is TOP-LEVEL only (03 §3.1), so the gated one is a child run whose approval sits at its own top level — the same shape as a wait inside a loop (03 §3.2 (f))
+  .workflow('refundGate', 'refund-approval', {
+    ticketId: fromInit('ticketId'),
+    amount: fromStep('classify', 'amount'),
+    requesterId: fromInit('customerId'),
+  }) // (e)'s maker-checker run, nested by name on the same agent; declared here, placed inside the switch arm by the string ref above. Its approver is a role, NOT 'creator': `approver-is-run-principal` on a customer-channel workflow
+  .agentStep('handoff', {
+    agentId: 'support-agent',
+    prompt: template('Summarise ${initData.message} for a human agent.'),
+    toolScope: {},
+  }) // the switch's `otherwise`
   .commit();

package/template/examples/workflows/ticket-to-pr.ts

@@ -1,5 +1,8 @@
 // Linear label -> clone -> parallel worktree arms -> merge -> tests -> PR -> review loop -> approval -> merge.
-// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// From workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative). LUA-635: `openPr` is placed by `.then(openPr)` on
+// both test outcomes — the listing's `otherwise: 'openPr'` named a `.then(createStep)` placement, which never declares an id
+// (03 §3.2.0); a string arm names an agentStep / specialistStep / toolStep / map / workflow declaration. `mergeGate.title` is a
+// plain string — the grammar is `title: string` (03 §3.1) and bindings ride `details`.
 // src/workflows/ticket-to-pr.ts — Linear label → clone → parallel worktree arms → merge → test suite → PR → review loop → approval → merge
 import { z } from 'zod';
 import { createStep, createWorkflow, step, fromInit, fromStep, template, eq, lit } from 'lua-cli';
@@ -7,10 +10,14 @@ import { prReviewRound } from './pr-review-round';
 
 const runTests = createStep({
   id: 'runTests',
-  inputSchema: z.any(), outputSchema: z.object({ passed: z.boolean(), summary: z.string() }),
-  tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 3600, jobResources: 'large',   // a 15–40 min monorepo suite fits one 4 h segment (D19-r1); up to 86 400 s is legal since D19-r2 — see §3.2 (h) for a step that crosses the segment boundary
+  inputSchema: z.any(),
+  outputSchema: z.object({ passed: z.boolean(), summary: z.string() }),
+  tier: 'job',
+  workspace: { mount: 'rw' },
+  timeoutSeconds: 3600,
+  jobResources: 'large', // a 15–40 min monorepo suite fits one 4 h segment (D19-r1); up to 86 400 s is legal since D19-r2 — see §3.2 (h) for a step that crosses the segment boundary
   async execute({ workspace, log }) {
-    const r = await $`cd ${workspace!.path} && npm ci && npm test -- --maxWorkers=2`.nothrow();   // untracked node_modules were rebuilt on restore (05 §5.17.5, E12); `--maxWorkers=2` keeps a mongodb-memory-server-per-file suite inside `large`'s 8 GiB — over it the container is OOM-killed and the step fails `job_oom_killed` (customer fault, 05 §5.17.4; §3.12 note)
+    const r = await $`cd ${workspace!.path} && npm ci && npm test -- --maxWorkers=2`.nothrow(); // untracked node_modules were rebuilt on restore (05 §5.17.5, E12); `--maxWorkers=2` keeps a mongodb-memory-server-per-file suite inside `large`'s 8 GiB — over it the container is OOM-killed and the step fails `job_oom_killed` (customer fault, 05 §5.17.4; §3.12 note)
     log(r.stdout.slice(-4000));
     return { passed: r.exitCode === 0, summary: r.stdout.slice(-2000) };
   },
@@ -18,48 +25,113 @@ const runTests = createStep({
 
 const openPr = createStep({
   id: 'openPr',
-  inputSchema: z.object({ ticketId: z.string(), title: z.string() }), outputSchema: z.object({ prNumber: z.number(), url: z.string() }),
-  tier: 'job', workspace: { mount: 'ro' },
-  sideEffects: 'external', onError: 'park',                                                 // a PR is an external effect: a platform fault PARKS (06 §6.3.5); `gh` is idempotent on the branch anyway
+  inputSchema: z.object({ ticketId: z.string(), title: z.string() }),
+  outputSchema: z.object({ prNumber: z.number(), url: z.string() }),
+  tier: 'job',
+  workspace: { mount: 'ro' },
+  sideEffects: 'external',
+  onError: 'park', // a PR is an external effect: a platform fault PARKS (06 §6.3.5); `gh` is idempotent on the branch anyway
   async execute({ workspace, inputData, runId }) {
-    const out = await $`cd ${workspace!.path} && gh pr create --fill --title ${inputData.title} --body ${`Closes ${inputData.ticketId}\n\n<!-- lua-run:${runId} -->`}`;   // the run id in the PR body is what the GitHub webhook uses to route review signals (§3.7)
-    const url = out.stdout.trim(); return { prNumber: Number(url.split('/').pop()), url };
+    const out =
+      await $`cd ${workspace!.path} && gh pr create --fill --title ${inputData.title} --body ${`Closes ${inputData.ticketId}\n\n<!-- lua-run:${runId} -->`}`; // the run id in the PR body is what the GitHub webhook uses to route review signals (§3.7)
+    const url = out.stdout.trim();
+    return { prNumber: Number(url.split('/').pop()), url };
   },
 });
 
 const mergePr = createStep({
-  id: 'mergePr', inputSchema: z.object({ approved: z.boolean(), input: z.object({ prNumber: z.number() }) }), outputSchema: z.object({ merged: z.boolean() }),
-  tier: 'job', workspace: { mount: 'ro' }, jobTools: ['gh'], sideEffects: 'external', onError: 'park',   // `jobTools:['gh']` is what mints GH_TOKEN for a code step (11 §11.5.6: pull_requests:write + contents:write + issues:read, repo-scoped — merge is a contents write on GitHub)
+  id: 'mergePr',
+  inputSchema: z.object({ approved: z.boolean(), input: z.object({ prNumber: z.number() }) }),
+  outputSchema: z.object({ merged: z.boolean() }),
+  tier: 'job',
+  workspace: { mount: 'ro' },
+  jobTools: ['gh'],
+  sideEffects: 'external',
+  onError: 'park', // `jobTools:['gh']` is what mints GH_TOKEN for a code step (11 §11.5.6: pull_requests:write + contents:write + issues:read, repo-scoped — merge is a contents write on GitHub)
   async execute({ workspace, inputData }) {
     if (!inputData.approved) return { merged: false };
-    await $`cd ${workspace!.path} && gh pr merge ${inputData.input.prNumber} --squash --delete-branch`;   // succeeds only if the base branch's ruleset lets the App merge — human-only-merge orgs keep contents:write off the App (11 T21)
+    await $`cd ${workspace!.path} && gh pr merge ${inputData.input.prNumber} --squash --delete-branch`; // succeeds only if the base branch's ruleset lets the App merge — human-only-merge orgs keep contents:write off the App (11 T21)
     return { merged: true };
   },
 });
 
 export const ticketToPr = createWorkflow({
   name: 'ticket-to-pr',
-  description: 'Linear label → implement/tests/docs in parallel worktrees → merge → test suite → PR → review rounds → approval → merge',
-  inputSchema: z.object({ ticketId: z.string(), title: z.string(), spec: z.string(), repo: z.string(), baseRef: z.string().default('main') }),
+  description:
+    'Linear label → implement/tests/docs in parallel worktrees → merge → test suite → PR → review rounds → approval → merge',
+  inputSchema: z.object({
+    ticketId: z.string(),
+    title: z.string(),
+    spec: z.string(),
+    repo: z.string(),
+    baseRef: z.string().default('main'),
+  }),
   outputSchema: z.object({ merged: z.boolean(), prUrl: z.string().optional(), rounds: z.number() }),
-  workspace: { kind: 'git', repo: template('${initData.repo}'), ref: template('${initData.baseRef}'), credentialsRef: 'github-app', sizeGb: 20, verify: 'npm test' },   // `github-app` = the org's GitHub connection id (a template would use `connections[].key`, §13 §13.3.3)
-  budget: { maxCredits: 400, maxDurationSeconds: 21 * 24 * 3600 },                         // review rounds may wait a week each. Job seconds (wall, claim → terminal) worst case: 7200+5400+1800 arms + 3600 merge + 3600 tests + 3600 fixTests + 3600 openPr + 8 × (7200+600) rounds + 3600 merge ≈ 94 800 s — fits the org default maxJobSecondsPerRun 172 800 (48 h) with margin; the push-time `job-seconds-exceed-cap` BLOCKER (10 §10.7.6) refuses this file on an org that lowered the cap below the sum, and prints the R23 raise path. Declare `maxJobSeconds` explicitly only to narrow.
+  connections: [{ key: 'github', integrationType: 'github', required: true }], // the GitHub connection this workflow acts through, declared ONCE by key — resolved on the owner agent at run time (an agent-scoped GitHub connection first, then org-scoped; LUA-623), so the same definition runs on any agent: no frozen connection id in source, no per-agent build
+  workspace: {
+    kind: 'git',
+    repo: template('${initData.repo}'),
+    ref: template('${initData.baseRef}'),
+    credentialsRef: 'github',
+    sizeGb: 20,
+    verify: 'npm test',
+  }, // `credentialsRef` names the declared key above; an undeclared key fails `lua compile` / `lua push` with connection-key-undeclared
+  budget: { maxCredits: 400, maxDurationSeconds: 21 * 24 * 3600 }, // review rounds may wait a week each. Job seconds (wall, claim → terminal) worst case: 7200+5400+1800 arms + 3600 merge + 3600 tests + 3600 fixTests + 3600 openPr + 8 × (7200+600) rounds + 3600 merge ≈ 94 800 s — fits the org default maxJobSecondsPerRun 172 800 (48 h) with margin; the push-time `job-seconds-exceed-cap` BLOCKER (10 §10.7.6) refuses this file on an org that lowered the cap below the sum, and prints the R23 raise path. Declare `maxJobSeconds` explicitly only to narrow.
 })
-  .parallel(['implement', 'writeTests', 'updateDocs'], { merge: { strategy: 'rebase', onConflict: 'agent' } })   // three coding turns on three clone volumes + branches; the merge row rebases them onto the run branch and lets one resolver turn fix conflicts (05 §5.17.5)
-  .agentStep('implement', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 7200,
-    prompt: template('Implement ${initData.spec} for ticket ${initData.ticketId}. Do not touch tests or docs; commit as you go.'),
-    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] } })
-  .agentStep('writeTests', { agentId: 'swe-tester', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 5400,
-    prompt: template('Write tests for the behaviour described in ${initData.spec}; they may fail until implementation lands. Only touch test files.') })
-  .agentStep('updateDocs', { agentId: 'swe-writer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 1800, jobResources: 'small',
-    prompt: template('Update docs/ for ${initData.spec}. Only touch markdown files.') })
-  .then(runTests)                                                                          // shared mount, sequential — the merged run branch
-  .switch([[eq(step('runTests').path('passed'), lit(false)), 'fixTests']], 'openPr')
-  .agentStep('fixTests', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 3600,
-    prompt: template('The test suite failed:\n${stepResults.runTests.summary}\nFix the code (not the tests unless they are wrong) and re-run `npm test` until green.') })
+  .parallel(['implement', 'writeTests', 'updateDocs'], { merge: { strategy: 'rebase', onConflict: 'agent' } }) // three coding turns on three clone volumes + branches; the merge row rebases them onto the run branch and lets one resolver turn fix conflicts (05 §5.17.5)
+  .agentStep('implement', {
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'rw', isolation: 'worktree' },
+    timeoutSeconds: 7200,
+    prompt: template(
+      'Implement ${initData.spec} for ticket ${initData.ticketId}. Do not touch tests or docs; commit as you go.'
+    ),
+    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] },
+  })
+  .agentStep('writeTests', {
+    agentId: 'swe-tester',
+    tier: 'job',
+    workspace: { mount: 'rw', isolation: 'worktree' },
+    timeoutSeconds: 5400,
+    prompt: template(
+      'Write tests for the behaviour described in ${initData.spec}; they may fail until implementation lands. Only touch test files.'
+    ),
+  })
+  .agentStep('updateDocs', {
+    agentId: 'swe-writer',
+    tier: 'job',
+    workspace: { mount: 'rw', isolation: 'worktree' },
+    timeoutSeconds: 1800,
+    jobResources: 'small',
+    prompt: template('Update docs/ for ${initData.spec}. Only touch markdown files.'),
+  })
+  .then(runTests) // shared mount, sequential — the merged run branch
+  .switch([[eq(step('runTests').path('passed'), lit(false)), 'fixTests']]) // red ⇒ one fix turn (placed inside this arm by the string ref below); green falls through — no `otherwise`, `openPr` follows either way
+  .agentStep('fixTests', {
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'rw' },
+    timeoutSeconds: 3600,
+    prompt: template(
+      'The test suite failed:\n${stepResults.runTests.summary}\nFix the code (not the tests unless they are wrong) and re-run `npm test` until green.'
+    ),
+  })
   .then(openPr)
-  .dowhile('reviewRound', eq(step('reviewRound').path('state'), lit('changes_requested')), { maxIterations: 8 })   // ≤ 8 review rounds (the SWE_REVIEW_MAX_ROUNDS lesson)
-  .workflow('reviewRound', prReviewRound, { prNumber: fromStep('openPr', 'prNumber'), repo: fromInit('repo') }, { workspace: 'inherit' })   // each round is a child run on the SAME workspace; the parent's PVC is released while a round waits for the webhook (E12)
-  .approval('mergeGate', { title: template('Merge PR ${stepResults.openPr.url}?'), approver: { role: 'eng-lead' }, excludeInitiator: true, timeoutHours: 72, onTimeout: 'deny' })
+  .dowhile('reviewRound', eq(step('reviewRound').path('state'), lit('changes_requested')), { maxIterations: 8 }) // ≤ 8 review rounds (the SWE_REVIEW_MAX_ROUNDS lesson)
+  .workflow(
+    'reviewRound',
+    prReviewRound,
+    { prNumber: fromStep('openPr', 'prNumber'), repo: fromInit('repo') },
+    { workspace: 'inherit' }
+  ) // declared here, placed as the loop body by the string ref above; each round is a child run on the SAME workspace; the parent's PVC is released while a round waits for the webhook (E12)
+  .approval('mergeGate', {
+    title: 'Merge the PR?',
+    details: template('Merge ${stepResults.openPr.url} into ${initData.baseRef}?'),
+    approver: { role: 'eng-lead' },
+    excludeInitiator: true,
+    timeoutHours: 72,
+    onTimeout: 'deny',
+  })
   .then(mergePr)
   .commit();

package/template/examples/workflows/vendor-invoices.ts

@@ -1,30 +1,83 @@
 // Per-item review with an env overlay, a restricted output pane and a slack reply (Cluster K).
-// Verbatim from workflows-spec 03 §3.2 (j) (WF-215 / WF-223 — the spec is normative).
+// From workflows-spec 03 §3.2 (j) (WF-215 / WF-223 — the spec is normative). LUA-635: the approval `title` is a plain string
+// (03 §3.1 `approval(id, { title: string; details?: TemplateBinding })`); the listing's `template(…)` title moved into `details`.
+// The listing's `.foreach('pay', 'payInvoice', …)` is not the builder's `foreach(step, opts)` (03 §3.1) and declared no `payInvoice`
+// anywhere — the body is the `payInvoice` code step below.
 import { z } from 'zod';
 import { createStep, createWorkflow, env, fromInit, fromKnowledge, fromStep, template } from 'lua-cli';
 
-const invoiceSchema = z.object({ vendorId: z.string(), approverEmail: z.string().email(), amount: z.number(), pdf: z.object({ __artefactRef: z.string() }) });
+const invoiceSchema = z.object({
+  vendorId: z.string(),
+  approverEmail: z.string().email(),
+  amount: z.number(),
+  pdf: z.object({ __artefactRef: z.string() }),
+});
 
-const loadInvoices = createStep({ id: 'loadInvoices', inputSchema: z.object({ batchId: z.string() }), outputSchema: z.object({ invoices: z.array(invoiceSchema) }),
+const loadInvoices = createStep({
+  id: 'loadInvoices',
+  inputSchema: z.object({ batchId: z.string() }),
+  outputSchema: z.object({ invoices: z.array(invoiceSchema) }),
   async execute(ctx) {
-    const src = await ctx.artefacts.get(ctx.inputData.batchId);                                   // B40: a multi-GB NDJSON batch — page it, never buffer it
-    const invoices = []; for (let offset = 0; ; offset += 1000) { const page = await src.rows({ offset, limit: 1000 }); invoices.push(...page.rows); if (page.nextOffset == null) break; }
+    const src = await ctx.artefacts.get(ctx.inputData.batchId); // B40: a multi-GB NDJSON batch — page it, never buffer it
+    const invoices = [];
+    for (let offset = 0; ; offset += 1000) {
+      const page = await src.rows({ offset, limit: 1000 });
+      invoices.push(...page.rows);
+      if (page.nextOffset == null) break;
+    }
     return { invoices };
-  } });
+  },
+});
+
+const payInvoice = createStep({
+  id: 'payInvoice',
+  inputSchema: invoiceSchema,
+  outputSchema: z.object({ vendorId: z.string(), paid: z.boolean() }),
+  sideEffects: 'external',
+  onError: 'park', // a payment is an external effect: a platform-fault reclaim PARKS it, never auto-retries (06 §6.3.5)
+  async execute({ inputData: inv, once }) {
+    // one approved row per iteration — the foreach body receives the raw item
+    await once(`pay:${inv.vendorId}:${inv.amount}`, () =>
+      Payments.transfer({ vendorId: inv.vendorId, amount: inv.amount })
+    ); // exactly-once per {occurrenceId, key}; `Payments` stands for your payment rail
+    return { vendorId: inv.vendorId, paid: true };
+  },
+});
 
 export const vendorInvoices = createWorkflow({
-  name: 'vendor-invoices', inputSchema: z.object({ batchId: z.string() }),
-  outputVisibility: { roles: ['finance', 'org-admin'] },                                          // B44: invoice payloads are readable by finance only; owner bypass on (default)
-  schedule: { cron: '0 6 * * 1-5', timezone: env.template('FINANCE_TZ') },                        // B33: one file, per-env timezone resolved at push
+  name: 'vendor-invoices',
+  inputSchema: z.object({ batchId: z.string() }),
+  outputVisibility: { roles: ['finance', 'org-admin'] }, // B44: invoice payloads are readable by finance only; owner bypass on (default)
+  schedule: { cron: '0 6 * * 1-5', timezone: env.template('FINANCE_TZ') }, // B33: one file, per-env timezone resolved at push
+  scheduleInput: { batchId: 'latest' }, // the 06:00 run reads the standing `latest` batch alias; a required input without a `scheduleInput` is `schedule-input-required`, a publish blocker. An ad-hoc run passes its own batch id
 })
   .then(loadInvoices, { batchId: fromInit('batchId') })
-  .agentStep('policyCheck', { agentId: env.template('FINANCE_AGENT_ID'),                          // B33: staging and prod route to different sub-agents; same graphHash
+  .agentStep('policyCheck', {
+    agentId: env.template('FINANCE_AGENT_ID'), // B33: staging and prod route to different sub-agents; same graphHash
     prompt: template('Flag any invoice that breaks policy.\n${knowledge.policy}\n${stepResults.loadInvoices.invoices}'),
     outputSchema: z.object({ flagged: z.array(z.string()) }),
-    input: { policy: fromKnowledge({ source: 'connection', connectionId: env.template('FINANCE_DRIVE_CONNECTION'), query: 'vendor payment policy', maxChars: 6000 }) },   // B41
-    toolScope: { connectionIds: [] } })                                                           // tainted by the connection knowledge ⇒ `toolScope` mandatory (P1-16); the knowledge connection is added by the compiler's overlay pass
-  .approval('reviewInvoices', { title: template('${stepResults.loadInvoices.invoices.length} vendor invoices'), details: template('Flagged: ${stepResults.policyCheck.flagged}'),
-    approver: { role: 'finance' }, itemsPath: 'invoices', itemApprover: { fromItem: 'approverEmail' },   // B20: every invoice goes to ITS approver; the parent link is the finance role's overview
-    itemTimeout: { timeoutHours: 48 }, editable: true, editablePaths: ['invoices[*].amount'], timeoutHours: 96 })
-  .foreach('pay', 'payInvoice', { items: fromStep('reviewInvoices', 'items'), concurrency: 4 })   // consumes `resumeData.items[]` — approved rows only
+    input: {
+      policy: fromKnowledge({
+        source: 'connection',
+        connectionId: env.template('FINANCE_DRIVE_CONNECTION'),
+        query: 'vendor payment policy',
+        maxChars: 6000,
+      }),
+    }, // B41
+    toolScope: { connectionIds: [] },
+  }) // tainted by the connection knowledge ⇒ `toolScope` mandatory (P1-16); the knowledge connection is added by the compiler's overlay pass
+  .approval('reviewInvoices', {
+    title: 'Vendor invoices to review',
+    details: template(
+      '${stepResults.loadInvoices.invoices.length} invoices; flagged: ${stepResults.policyCheck.flagged}'
+    ),
+    approver: { role: 'finance' },
+    itemsPath: 'invoices',
+    itemApprover: { fromItem: 'approverEmail' }, // B20: every invoice goes to ITS approver; the parent link is the finance role's overview
+    itemTimeout: { timeoutHours: 48 },
+    editable: true,
+    editablePaths: ['invoices[*].amount'],
+    timeoutHours: 96,
+  })
+  .foreach(payInvoice, { items: fromStep('reviewInvoices', 'items'), concurrency: 4 }) // `foreach(step, opts)`: consumes `resumeData.items[]` — approved rows only
   .commit();

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.31.0",
+    "lua-cli": "^3.32.1",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"