@vertesia/studio-utils 1.6.0-dev.20260918.115658Z → 1.6.0-dev.20261004.085740Z

package/src/prompts/extract-vars.ts

@@ -1,113 +1,254 @@
+import { HANDLEBARS_CONTEXT_HELPERS, isHandlebarsHelper, isTemplateSystemVariable } from '@vertesia/jst';
 import Handlebars from 'handlebars';
 
+/** A read of a root-level template variable. */
+export interface HandlebarsVariableReference {
+    /** Root identifier: `customer` for `{{customer.name}}`, `{{../customer}}` or `{{@root.customer}}`. */
+    name: string;
+    /** The path as written, e.g. `customer.name`. */
+    expression: string;
+    /** True when the path reads a property of the variable (`customer.name`). */
+    hasPath: boolean;
+    /** Source of the tag that contains the read, e.g. `{{#if customer}}`. */
+    tag: string;
+}
+
+/** A helper name used where Handlebars will not call it. */
+export interface HandlebarsHelperMisuse {
+    helper: string;
+    /**
+     * - `used_as_value`: passed as an argument (`{{#if stringify}}`), where Handlebars reads the data.
+     * - `missing_arguments`: called bare (`{{stringify}}`) with none of the arguments it needs.
+     */
+    problem: 'used_as_value' | 'missing_arguments';
+    tag: string;
+}
+
+export interface HandlebarsTemplateAnalysis {
+    references: HandlebarsVariableReference[];
+    helperMisuses: HandlebarsHelperMisuse[];
+}
+
+interface PathNode {
+    type: 'PathExpression';
+    original: string;
+    parts: string[];
+    depth: number;
+    data: boolean;
+}
+
+interface SourceLocation {
+    start: { line: number; column: number };
+}
+
+type Node = { type: string; loc?: SourceLocation } & Record<string, unknown>;
+
+/** Context a template section renders with: the input root, or an item whose shape is unknown. */
+type ContextKind = 'root' | 'item';
+
+function isPath(node: unknown): node is PathNode {
+    return !!node && typeof node === 'object' && (node as Node).type === 'PathExpression';
+}
+
+/** `this.x`, `./x` and `this` read the context explicitly — Handlebars never treats them as helpers. */
+function isScoped(path: PathNode): boolean {
+    return /^\.|this\b/.test(path.original);
+}
+
+/** A single bare identifier — the only form Handlebars may resolve to a helper. */
+function isSimpleId(path: PathNode): boolean {
+    return path.parts.length === 1 && !isScoped(path) && !path.data && path.depth === 0;
+}
+
+function lineOffsets(template: string): number[] {
+    const offsets = [0];
+    for (let i = 0; i < template.length; i++) {
+        if (template[i] === '\n') offsets.push(i + 1);
+    }
+    return offsets;
+}
+
 /**
- * Extract the set of root-level variable names referenced by a Handlebars template.
+ * Analyze the variables and helpers a Handlebars template uses, resolving names the way the
+ * prompt renderer does (helpers and system variables come from `@vertesia/jst`).
  *
- * - `{{foo}}` → `foo`
- * - `{{obj.bar.baz}}` → `obj` (only the root identifier; nested access doesn't add `bar` or `baz`)
- * - `{{#if cond}}{{name}}{{/if}}` → `cond`, `name`
- * - `{{#each items as |item|}}{{item.name}}{{/each}}` → `items` (NOT `item` — bound by `as |item|`)
- * - `{{lookup obj key}}` → `obj`, `key` (helper name skipped)
- * - `{{@index}}`, `{{this}}` → ignored (built-in data vars / self)
- *
- * Helper names in mustaches and block heads (`{{customHelper x}}`, `{{#if x}}`) are NOT added to
- * the set — only the arguments and inner template references are. This matches the typical use
- * case for prompt validation: detect which schema properties the template actually reads.
+ * Scoping rules:
+ * - Inside `{{#each}}` / `{{#with}}` (and `{{#section}}` over data), bare names read the current item,
+ *   whose shape the input schema does not describe — they are not reported. `../x` and `@root.x`
+ *   read the enclosing or root context and are reported.
+ * - `as |x|` block params are local bindings, not variables.
+ * - `{{@index}}` and other `@`-data (except `@root.x`) are runtime values, not variables.
  *
- * Returns an empty set on parse failure — callers should also run a syntactic render check
- * (e.g. `executeHandlebars`) to surface parse errors separately.
+ * Returns null when the template does not parse; the render check reports the syntax error.
  */
-export function extractHandlebarsVariables(template: string): Set<string> {
+export function analyzeHandlebarsTemplate(template: string): HandlebarsTemplateAnalysis | null {
     let ast: hbs.AST.Program;
     try {
         ast = Handlebars.parse(template);
     } catch {
-        return new Set();
+        return null;
     }
 
-    const variables = new Set<string>();
-    const localScopes: Array<Set<string>> = [];
+    const offsets = lineOffsets(template);
+    const tagAt = (loc: SourceLocation | undefined): string => {
+        if (!loc) return '';
+        const start = (offsets[loc.start.line - 1] ?? 0) + loc.start.column;
+        const end = template.indexOf('}}', start);
+        if (end < 0) return template.slice(start);
+        return template.slice(start, template[end + 2] === '}' ? end + 3 : end + 2);
+    };
 
-    const isLocal = (name: string): boolean => localScopes.some((scope) => scope.has(name));
+    const references: HandlebarsVariableReference[] = [];
+    const helperMisuses: HandlebarsHelperMisuse[] = [];
+    const contexts: ContextKind[] = ['root'];
+    const blockParams: Array<Set<string>> = [];
+    let tag = '';
 
-    const visit = (node: unknown): void => {
-        if (!node || typeof node !== 'object') return;
-        const n = node as { type: string } & Record<string, unknown>;
+    const isBlockParam = (name: string): boolean => blockParams.some((scope) => scope.has(name));
 
-        switch (n.type) {
-            case 'Program': {
-                const body = n.body as unknown[] | undefined;
-                if (body) for (const stmt of body) visit(stmt);
-                break;
+    /** Record a data read of `path`, if it reads the root input. */
+    const readData = (path: PathNode): void => {
+        if (path.data) {
+            // `@root.x` reads the input root; `@index`, `@key`, ... are runtime values.
+            if (path.parts[0] === 'root' && path.parts.length > 1) {
+                references.push({
+                    name: path.parts[1],
+                    expression: path.original,
+                    hasPath: path.parts.length > 2,
+                    tag,
+                });
             }
+            return;
+        }
+        if (path.parts.length === 0) return; // `this` / `.`
+        const root = path.parts[0];
+        if (path.depth === 0 && !isScoped(path) && isBlockParam(root)) return;
+        // Handlebars stops at the root context when `../` goes past it.
+        const context = contexts[Math.max(0, contexts.length - 1 - path.depth)];
+        if (context !== 'root') return;
+        references.push({ name: root, expression: path.original, hasPath: path.parts.length > 1, tag });
+    };
 
-            case 'BlockStatement': {
-                // n.path is the helper name (`#if`, `#each`, `#customBlock`) — never a variable.
-                // Visit params + hash to capture variables passed to the block helper.
-                const params = n.params as unknown[] | undefined;
-                if (params) for (const p of params) visit(p);
-                visit(n.hash);
+    /** A path in argument position (params, hash values): Handlebars reads data, never calls a helper. */
+    const visitArgument = (node: unknown): void => {
+        if (isPath(node)) {
+            const name = node.parts[0];
+            // System variables are injected as data too, so they resolve as arguments.
+            if (
+                isSimpleId(node) &&
+                !isBlockParam(name) &&
+                isHandlebarsHelper(name) &&
+                !isTemplateSystemVariable(name)
+            ) {
+                helperMisuses.push({ helper: name, problem: 'used_as_value', tag });
+                return;
+            }
+            readData(node);
+            return;
+        }
+        visit(node);
+    };
 
-                // Track `as |x y|` block params — these are local bindings, not variables.
-                const program = n.program as { blockParams?: string[] } | undefined;
-                const inverse = n.inverse as { blockParams?: string[] } | undefined;
-                const scope = new Set<string>([...(program?.blockParams ?? []), ...(inverse?.blockParams ?? [])]);
-                localScopes.push(scope);
+    const visitCall = (n: Node): void => {
+        const params = (n.params as unknown[] | undefined) ?? [];
+        for (const p of params) visitArgument(p);
+        const pairs = (n.hash as { pairs?: Array<{ value: unknown }> } | undefined)?.pairs ?? [];
+        for (const pair of pairs) visitArgument(pair.value);
+    };
 
-                visit(n.program);
-                visit(n.inverse);
+    const hasArguments = (n: Node): boolean =>
+        ((n.params as unknown[] | undefined)?.length ?? 0) > 0 ||
+        ((n.hash as { pairs?: unknown[] } | undefined)?.pairs?.length ?? 0) > 0;
 
-                localScopes.pop();
+    const visit = (node: unknown): void => {
+        if (!node || typeof node !== 'object') return;
+        const n = node as Node;
+
+        switch (n.type) {
+            case 'Program': {
+                for (const stmt of (n.body as unknown[] | undefined) ?? []) visit(stmt);
                 break;
             }
 
             case 'MustacheStatement': {
-                // Bare mustache (no params, no hash) → it's a variable reference.
-                // With params/hash, it's a helper call — skip the path (helper name), visit args.
-                const params = n.params as unknown[] | undefined;
-                const hash = n.hash as { pairs?: unknown[] } | undefined;
-                const isHelperCall = (params?.length ?? 0) > 0 || (hash?.pairs?.length ?? 0) > 0;
-                // The renderer registers _now as a zero-argument helper. Only the bare
-                // helper invocation is implicit; paths such as this._now remain data reads.
-                const path = n.path as { original?: string } | undefined;
-                if (!isHelperCall && path?.original !== '_now') {
-                    visit(n.path);
+                tag = tagAt(n.loc);
+                const path = n.path;
+                if (hasArguments(n)) {
+                    // `{{helper arg}}`: the head is a helper name (a missing one fails the render check).
+                    visitCall(n);
+                } else if (isPath(path)) {
+                    // A bare `{{name}}` calls a helper of that name when there is one, else reads data.
+                    // System variables are helpers returning their injected value, meant to be used bare.
+                    const name = path.parts[0];
+                    if (isSimpleId(path) && !isBlockParam(name) && isHandlebarsHelper(name)) {
+                        if (!isTemplateSystemVariable(name)) {
+                            helperMisuses.push({ helper: name, problem: 'missing_arguments', tag });
+                        }
+                    } else {
+                        readData(path);
+                    }
+                } else {
+                    visit(path);
                 }
-                if (params) for (const p of params) visit(p);
-                visit(hash);
                 break;
             }
 
-            case 'SubExpression': {
-                // (helper arg1 arg2) — helper name in path is skipped, args carry variables.
-                const params = n.params as unknown[] | undefined;
-                if (params) for (const p of params) visit(p);
-                visit(n.hash);
-                break;
-            }
+            case 'BlockStatement': {
+                tag = tagAt(n.loc);
+                const path = n.path;
+                const helper = isPath(path) && isSimpleId(path) ? path.parts[0] : undefined;
+                let itemContext: boolean;
+                if (hasArguments(n) || (helper && isHandlebarsHelper(helper))) {
+                    visitCall(n);
+                    itemContext = !!helper && HANDLEBARS_CONTEXT_HELPERS.includes(helper);
+                } else {
+                    // `{{#section}}…{{/section}}` over data: iterates or enters `section`.
+                    if (isPath(path)) readData(path);
+                    itemContext = true;
+                }
+
+                const program = n.program as { blockParams?: string[] } | undefined;
+                const inverse = n.inverse as { blockParams?: string[] } | undefined;
+                blockParams.push(new Set(program?.blockParams ?? []));
+                contexts.push(itemContext ? 'item' : contexts[contexts.length - 1]);
+                visit(n.program);
+                contexts.pop();
+                blockParams.pop();
 
-            case 'PathExpression': {
-                if (n.data) break; // `@-data` references (@index, @key, etc.)
-                const parts = n.parts as string[] | undefined;
-                if (!parts || parts.length === 0) break; // `this` / `.`
-                const root = parts[0];
-                if (isLocal(root)) break;
-                variables.add(root);
+                // `{{else}}` renders with the enclosing context.
+                blockParams.push(new Set(inverse?.blockParams ?? []));
+                visit(n.inverse);
+                blockParams.pop();
                 break;
             }
 
-            case 'Hash': {
-                const pairs = n.pairs as Array<{ value: unknown }> | undefined;
-                if (pairs) for (const pair of pairs) visit(pair.value);
+            case 'SubExpression': {
+                // `(helper arg)`: the head is a call, like a bare `{{helper}}`.
+                visitCall(n);
                 break;
             }
 
-            // ContentStatement, CommentStatement, *Literal, PartialStatement — no variables to extract.
+            // ContentStatement, CommentStatement, literals, partials — no variables.
             default:
                 break;
         }
     };
 
     visit(ast);
-    return variables;
+    return { references, helperMisuses };
+}
+
+/**
+ * Extract the set of root-level input variable names a Handlebars template reads.
+ *
+ * - `{{foo}}` → `foo`; `{{obj.bar.baz}}` → `obj`
+ * - `{{#each items as |item|}}{{item.name}}{{/each}}` → `items` (`item` is a block param)
+ * - `{{lookup obj key}}` → `obj`, `key` (helper name skipped)
+ * - `{{@index}}`, `{{this}}`, and bare names inside `#each`/`#with` → ignored
+ *
+ * Returns an empty set on parse failure.
+ */
+export function extractHandlebarsVariables(template: string): Set<string> {
+    const analysis = analyzeHandlebarsTemplate(template);
+    return new Set(analysis?.references.map((r) => r.name) ?? []);
 }

package/src/prompts/render.ts

@@ -1,6 +1,12 @@
 import type { JSONObject, JSONSchema, PromptSegment } from '@llumiverse/common';
 import { type PromptSegmentDef, PromptSegmentDefType, type PromptTemplate, TemplateType } from '@vertesia/common';
-import { CompositeError, renderHandlebarsTemplate, renderJsTemplate } from '@vertesia/jst';
+import {
+    CompositeError,
+    renderHandlebarsTemplate,
+    renderJsTemplate,
+    type TemplateSystemContext,
+    withTemplateSystemVariables,
+} from '@vertesia/jst';
 
 export interface SegmentPreview {
     error?: Error;
@@ -12,29 +18,32 @@ export interface SegmentPreview {
 /**
  * Render a prompt template with the given input data.
  *
- * Handlebars templates use {{variable}} interpolation against `data`.
- * JST (JavaScript template) bodies evaluate against `data` with the schema's top-level
- * property names exposed as globals, plus `_model` — the active model id, which the
- * studio-server executor injects into the input as `{ ..._model: run.modelId }` when
- * executing an interaction (see `apps/studio-server/src/executor/ExecutionRequest.ts`
- * and `apps/studio-server/src/executor/rendering/template.ts`). Listing it here keeps
- * the Playground preview and `validatePrompt` in sync with runtime resolution — a JST
- * template referencing `_model` validates fine here and renders fine in production.
+ * Handlebars templates use {{variable}} interpolation against `data`. JST (JavaScript template)
+ * bodies evaluate against `data` with the schema's top-level property names exposed as globals.
+ * Both see the system variables (`TEMPLATE_SYSTEM_VARIABLES` in `@vertesia/jst`), added here the
+ * same way the studio-server executor adds them, so a preview renders what an execution would.
+ * `_model` is only set when the caller passes `system.model` or the data already carries it.
  *
  * For `TemplateType.text`, the content is returned verbatim — it is static text, not a
  * template — matching the studio-server executor (see `apps/studio-server/src/executor/
  * rendering/template.ts`). Routing it through the JST evaluator would compile the prose as
  * JavaScript and throw on any plain sentence (e.g. "You are a helpful assistant.").
  */
-export function renderTemplate(code: string, contentType: TemplateType, schema: JSONSchema, data: JSONObject): string {
-    if (contentType === TemplateType.handlebars) {
-        return renderHandlebarsTemplate(code, data);
-    }
+export function renderTemplate(
+    code: string,
+    contentType: TemplateType,
+    schema: JSONSchema,
+    data: JSONObject,
+    system?: TemplateSystemContext,
+): string {
     if (contentType === TemplateType.text) {
         return code;
     }
-    const globals = [...(schema.properties ? Object.keys(schema.properties) : []), '_model'];
-    return renderJsTemplate(code, globals, data);
+    const input = withTemplateSystemVariables(data, system);
+    if (contentType === TemplateType.handlebars) {
+        return renderHandlebarsTemplate(code, input);
+    }
+    return renderJsTemplate(code, schema.properties ? Object.keys(schema.properties) : [], input);
 }
 
 /**

package/src/prompts/validate.ts

@@ -1,13 +1,25 @@
 import type { JSONObject } from '@llumiverse/common';
 import { type JSONSchema, TemplateType } from '@vertesia/common';
-import { getFreeVariables, renderJsTemplate } from '@vertesia/jst';
-import { extractHandlebarsVariables } from './extract-vars.js';
+import {
+    describeTemplateSystemVariables,
+    getFreeVariables,
+    isTemplateSystemVariable,
+    JST_TEMPLATE_GLOBALS,
+    renderJsTemplate,
+    TEMPLATE_SYSTEM_VARIABLES,
+    withTemplateSystemVariables,
+} from '@vertesia/jst';
+import { analyzeHandlebarsTemplate } from './extract-vars.js';
 import { generateMockData } from './mock-data.js';
 import { executeHandlebars } from './render.js';
 
 export type PromptValidationIssueType =
     | 'undeclared_template_variable'
     | 'unused_schema_variable'
+    | 'reserved_variable_declared'
+    | 'system_variable_property_access'
+    | 'helper_used_as_value'
+    | 'helper_missing_arguments'
     | 'handlebars_render_error'
     | 'jst_unsafe_construct'
     | 'jst_render_error';
@@ -43,16 +55,6 @@ export interface PromptValidationInput {
     inputSchema?: JSONSchema;
 }
 
-// JST's renderJsTemplate auto-adds `_` (helpers object) and runtime injects `Set` and `Array`
-// — treat them as globals so they don't appear as free vars in user templates.
-// Globals always available to JST templates regardless of schema:
-//  - `_`, `Array`, `Set`: runtime-injected by `renderJsTemplate` (jst library)
-//  - `_model`: runtime-injected by the studio-server executor as `{ ..._model: run.modelId }`
-//    (see ExecutionRequest.ts:313 and executor/rendering/template.ts:13)
-// Keeping these in sync with `renderTemplate` in ./render.ts so a JST template that runs in
-// production also passes the validator.
-const JST_AUTO_GLOBALS = ['_', 'Array', 'Set', '_model'];
-
 function countSeverities(issues: PromptValidationIssue[]): { error_count: number; warning_count: number } {
     let error_count = 0;
     let warning_count = 0;
@@ -66,43 +68,110 @@ function countSeverities(issues: PromptValidationIssue[]): { error_count: number
     return { error_count, warning_count };
 }
 
-function validateHandlebarsPrompt(content: string, inputSchema?: JSONSchema): PromptValidationIssue[] {
-    const issues: PromptValidationIssue[] = [];
-    const usedVars = extractHandlebarsVariables(content);
-    const declaredVars = new Set<string>(inputSchema?.properties ? Object.keys(inputSchema.properties) : []);
+/** Mock data for the render smoke test: schema-shaped input plus the runtime system values. */
+function buildMockInput(inputSchema: JSONSchema): Record<string, unknown> {
+    const mockData = generateMockData(inputSchema);
+    const mockObject: JSONObject =
+        typeof mockData === 'object' && mockData !== null && !Array.isArray(mockData) ? (mockData as JSONObject) : {};
+    return withTemplateSystemVariables(mockObject, { model: 'validation-model' });
+}
 
-    for (const used of usedVars) {
-        // The execution request injects _model for both template languages.
-        if (!declaredVars.has(used) && used !== '_model') {
+/**
+ * Issues shared by both template languages: reserved names declared in the schema, and
+ * unused schema properties. `usedVars` holds the input variables the template reads.
+ */
+function checkDeclarations(
+    declaredVars: Set<string>,
+    usedVars: Set<string>,
+    usageHint: (name: string) => string,
+): PromptValidationIssue[] {
+    const issues: PromptValidationIssue[] = [];
+    for (const declared of declaredVars) {
+        if (isTemplateSystemVariable(declared)) {
             issues.push({
-                type: 'undeclared_template_variable',
-                severity: 'error',
-                variable: used,
-                message: `Template references variable '{{${used}}}' but it is not declared in input_schema.properties. Add '${used}' to the schema with an appropriate type.`,
+                type: 'reserved_variable_declared',
+                severity: 'warning',
+                variable: declared,
+                message: `Schema declares '${declared}', a system variable the runtime supplies and overrides. Remove it from input_schema.`,
             });
-        }
-    }
-
-    for (const declared of declaredVars) {
-        if (!usedVars.has(declared)) {
+        } else if (!usedVars.has(declared)) {
             issues.push({
                 type: 'unused_schema_variable',
                 severity: 'warning',
                 variable: declared,
-                message: `Schema declares property '${declared}' but the template never references it. Remove it from input_schema or use it via {{${declared}}}.`,
+                message: `Schema declares property '${declared}' but the template never references it. Remove it from input_schema or ${usageHint(declared)}.`,
             });
         }
     }
+    return issues;
+}
+
+function undeclaredVariableIssue(name: string, where: string): PromptValidationIssue {
+    return {
+        type: 'undeclared_template_variable',
+        severity: 'error',
+        variable: name,
+        message:
+            `Template reads variable '${name}' ${where} but it is not declared in input_schema.properties. ` +
+            `Add '${name}' to the schema with an appropriate type. ` +
+            `System variables need no declaration: ${describeTemplateSystemVariables()}.`,
+    };
+}
+
+function validateHandlebarsPrompt(content: string, inputSchema?: JSONSchema): PromptValidationIssue[] {
+    const issues: PromptValidationIssue[] = [];
+    const analysis = analyzeHandlebarsTemplate(content);
+    const declaredVars = new Set<string>(inputSchema?.properties ? Object.keys(inputSchema.properties) : []);
+    const usedVars = new Set<string>();
+    const reported = new Set<string>();
+
+    for (const ref of analysis?.references ?? []) {
+        if (isTemplateSystemVariable(ref.name)) {
+            const variable = TEMPLATE_SYSTEM_VARIABLES.find((v) => v.name === ref.name);
+            if (ref.hasPath && variable?.type === 'string' && !reported.has(`path:${ref.expression}`)) {
+                reported.add(`path:${ref.expression}`);
+                issues.push({
+                    type: 'system_variable_property_access',
+                    severity: 'error',
+                    variable: ref.name,
+                    message: `'${ref.expression}' in ${ref.tag} reads a property of system variable '${ref.name}', which is a string (${variable.description}). Use '${ref.name}' directly.`,
+                });
+            }
+            continue;
+        }
+        usedVars.add(ref.name);
+        if (!declaredVars.has(ref.name) && !reported.has(ref.name)) {
+            reported.add(ref.name);
+            issues.push(undeclaredVariableIssue(ref.name, `in ${ref.tag}`));
+        }
+    }
+
+    for (const misuse of analysis?.helperMisuses ?? []) {
+        issues.push(
+            misuse.problem === 'used_as_value'
+                ? {
+                      type: 'helper_used_as_value',
+                      severity: 'error',
+                      variable: misuse.helper,
+                      message: `'${misuse.helper}' in ${misuse.tag} is a helper, but as an argument Handlebars reads it as data, which is empty. Call it as a subexpression: (${misuse.helper} ...).`,
+                  }
+                : {
+                      type: 'helper_missing_arguments',
+                      severity: 'error',
+                      variable: misuse.helper,
+                      message: `${misuse.tag} calls helper '${misuse.helper}' without arguments. Pass the value it operates on, e.g. {{${misuse.helper} value}}.`,
+                  },
+        );
+    }
+
+    issues.push(...checkDeclarations(declaredVars, usedVars, (name) => `use it via {{${name}}}`));
 
     // Render-time smoke test — always runs so syntax errors and failing helper calls are
     // surfaced even when undeclared-variable errors are already in the list. Handlebars renders
     // missing vars as empty strings (non-strict by default), so the render check does NOT echo
     // the var errors — anything it reports is a distinct template problem worth showing.
     const renderSchema = inputSchema ?? ({} as JSONSchema);
-    const mockData = generateMockData(renderSchema);
-    const mockObject: JSONObject =
-        typeof mockData === 'object' && mockData !== null && !Array.isArray(mockData) ? (mockData as JSONObject) : {};
-    const renderResult = executeHandlebars(content, renderSchema, mockObject);
+    const renderResult = executeHandlebars(content, renderSchema, buildMockInput(renderSchema) as JSONObject);
     if (!renderResult.success) {
         issues.push({
             type: 'handlebars_render_error',
@@ -121,7 +190,7 @@ function validateJstPrompt(content: string, inputSchema?: JSONSchema): PromptVal
     let referenced: Set<string>;
     try {
         const result = getFreeVariables(content, {
-            globals: JST_AUTO_GLOBALS,
+            globals: [...JST_TEMPLATE_GLOBALS],
             acorn: { allowReturnOutsideFunction: true, locations: true },
         });
         referenced = result.vars;
@@ -144,38 +213,19 @@ function validateJstPrompt(content: string, inputSchema?: JSONSchema): PromptVal
 
     for (const used of referenced) {
         if (!declaredVars.has(used)) {
-            issues.push({
-                type: 'undeclared_template_variable',
-                severity: 'error',
-                variable: used,
-                message: `Template references variable '${used}' but it is not declared in input_schema.properties. Add '${used}' to the schema with an appropriate type.`,
-            });
+            issues.push(undeclaredVariableIssue(used, 'in the template'));
         }
     }
 
-    for (const declared of declaredVars) {
-        if (!referenced.has(declared)) {
-            issues.push({
-                type: 'unused_schema_variable',
-                severity: 'warning',
-                variable: declared,
-                message: `Schema declares property '${declared}' but the template never references it. Remove it from input_schema or use it in the template.`,
-            });
-        }
-    }
+    issues.push(...checkDeclarations(declaredVars, referenced, () => 'use it in the template'));
 
     // Render-time smoke test — only if there are no blocking errors so far, otherwise
     // the failure mode would just echo what we already reported.
     const blockingSoFar = issues.some((i) => i.severity === 'error');
     if (!blockingSoFar) {
         const renderSchema = inputSchema ?? ({} as JSONSchema);
-        const mockData = generateMockData(renderSchema);
-        const mockObject: JSONObject =
-            typeof mockData === 'object' && mockData !== null && !Array.isArray(mockData)
-                ? (mockData as JSONObject)
-                : {};
         try {
-            renderJsTemplate(content, [...declaredVars], mockObject);
+            renderJsTemplate(content, [...declaredVars], buildMockInput(renderSchema));
         } catch (renderError) {
             issues.push({
                 type: 'jst_render_error',
@@ -193,9 +243,15 @@ function validateJstPrompt(content: string, inputSchema?: JSONSchema): PromptVal
  *
  * For `handlebars` and `jst` templates, the following checks are performed:
  *  1. Every variable referenced in the template must be declared as a top-level property
- *     in `inputSchema.properties` (else → `undeclared_template_variable` error).
+ *     in `inputSchema.properties` (else → `undeclared_template_variable` error). System variables
+ *     (`TEMPLATE_SYSTEM_VARIABLES` in `@vertesia/jst`) are supplied at runtime and need no declaration;
+ *     declaring one → `reserved_variable_declared` warning, reading a property of one →
+ *     `system_variable_property_access` error.
  *  2. Every property declared in `inputSchema.properties` should be referenced by the template
  *     (else → `unused_schema_variable` warning — non-blocking).
+ *  For Handlebars only: a helper passed as an argument (`{{#if stringify}}`) →
+ *     `helper_used_as_value` error; a helper called bare without the arguments it needs
+ *     (`{{stringify}}`) → `helper_missing_arguments` error.
  *  3. The template must render successfully against schema-derived mock data
  *     (else → `handlebars_render_error` / `jst_render_error` error).
  *  4. For JST only: unsafe constructs (`with`, `for`, `while`, `import`, class, `this`,