@aryacode/dsh-engineering 0.5.0 → 0.7.0

package/vendor/l5x/lib/engine/ladder.js

@@ -0,0 +1,209 @@
+/**
+ * Compose one ladder rung from a structure, never from prose.
+ *
+ * The composer is the generation half of the pair: the caller decides the logic,
+ * this module decides the NeutralText. Every instruction is checked against the
+ * catalog (or a declared AOI), every operand against the export, and the emitted
+ * text is re-parsed by the same parser `draft_rung` uses. A rung that fails any
+ * of those never reaches a draft.
+ *
+ * @module dsh-engineering-l5x/engine/ladder
+ */
+import { L5xError } from "../core/errors.js";
+import { resolveTag } from "./tag-resolution.js";
+import { instructionByName, nearestInstructions, NUMERIC_TYPES, TIMER_TYPES } from "./instructions.js";
+import { parseLadder } from "./logic-syntax.js";
+/** Named patterns the composer can expand. */
+export const PATTERNS = ['start_stop_latch', 'fault_latch', 'ton_delay', 'interlock'];
+const MAX_INSTRUCTIONS = 64;
+const MAX_DEPTH = 16;
+const LITERAL = /^-?(?:\d+\.?\d*|\.\d+)$/u;
+const TAG_TEXT = /^[A-Za-z_][A-Za-z0-9_:.[\]]*$/u;
+/** A numeric literal, which is not a declaration. */
+const isLiteral = (text) => LITERAL.test(text);
+/** A BOOL-ish check for the slot validation below uses this resolved operand. */
+function resolveOperand(document, text) {
+    const direct = resolveTag(document, 'controller', text);
+    if (direct.resolved)
+        return direct;
+    // A rung is written inside a program, so an unqualified program tag is the
+    // ordinary case. Resolve it when exactly one program declares the base name;
+    // two programs declaring it is an ambiguity the caller must settle.
+    const base = text.split(/[.[:]/u)[0] ?? text;
+    const declared = document.tags.filter(tag => tag.name.toUpperCase() === base.toUpperCase());
+    if (declared.length === 1)
+        return resolveTag(document, declared[0].scope, text);
+    if (declared.length > 1) {
+        throw new L5xError('AMBIGUOUS_TAG', `${base} is declared in ${declared.length} scopes.`, 'Declare the tag once, or stage the rung through a routine in the program that owns it.', declared.map(tag => tag.scope));
+    }
+    return direct;
+}
+/** One tag or literal operand, checked against its slot kind. */
+function checkOperand(project, text, kind, seen) {
+    if (isLiteral(text)) {
+        // A literal is a value, not an address: only the slots that take a value accept it.
+        if (kind === 'BOOL')
+            throw new L5xError('INVALID_OPERAND', `${text} is a number where a BOOL tag is required.`, 'Pass a declared BOOL tag.');
+        if (kind === 'TIMER')
+            throw new L5xError('INVALID_OPERAND', `${text} is a number where a timer is required.`, 'Pass a declared TIMER tag.');
+        const operand = { text, resolved: false };
+        seen.push(operand);
+        return operand;
+    }
+    if (!TAG_TEXT.test(text)) {
+        throw new L5xError('INVALID_OPERAND', `"${text}" is not a tag or a number.`, 'Pass a declared tag name, a member path, or a numeric literal; no spaces or quotes.');
+    }
+    const resolution = resolveOperand(project.document, text);
+    if (!resolution.resolved) {
+        const near = project.document.tags
+            .map(tag => tag.name)
+            .filter(name => name.toLowerCase().includes(text.split('.')[0].toLowerCase()))
+            .slice(0, 5);
+        throw new L5xError('TAG_NOT_FOUND', `No tag named "${text}" resolves in this export.`, near.length === 0 ? 'Call list_components kind="tag" to see the declared names.' : 'Retry with one of the candidates, or declare the tag first.', near);
+    }
+    const type = (resolution.data_type ?? '').toUpperCase();
+    const operand = { text, resolved: true, canonical: resolution.canonical ?? text, data_type: type === '' ? undefined : type };
+    seen.push(operand);
+    if (kind === 'BOOL' && type !== 'BOOL') {
+        throw new L5xError('INVALID_OPERAND', `${text} is ${type || 'an unknown type'}; this slot needs a BOOL tag.`, 'Use a BOOL tag, or an alias that resolves to BOOL.', []);
+    }
+    if (kind === 'NUMBER' && !NUMERIC_TYPES.has(type)) {
+        throw new L5xError('INVALID_OPERAND', `${text} is ${type || 'an unknown type'}; this slot needs a numeric value or tag.`, 'Pass a numeric literal or an INT, DINT, REAL or similar tag.', []);
+    }
+    if (kind === 'TIMER' && !TIMER_TYPES.has(type)) {
+        throw new L5xError('INVALID_OPERAND', `${text} is ${type || 'an unknown type'}; this slot needs a timer.`, 'Pass a declared TIMER tag (TON, TOF or RTO instance).', []);
+    }
+    return operand;
+}
+/** Resolve one instruction node and emit it. */
+function composeInstruction(project, node, operands, counter) {
+    const args = node.args ?? [];
+    counter.instructions += 1;
+    if (counter.instructions > MAX_INSTRUCTIONS) {
+        throw new L5xError('LADDER_TOO_LARGE', `One rung may hold at most ${MAX_INSTRUCTIONS} instructions.`, 'Split the logic across rungs.');
+    }
+    const instruction = instructionByName(node.instr);
+    if (instruction !== undefined) {
+        const required = instruction.operands.filter(slot => slot.optional !== true).length;
+        if (args.length < required || args.length > instruction.operands.length) {
+            const shape = instruction.operands.map(slot => `${slot.name}${slot.optional === true ? '?' : ''}`).join(', ');
+            throw new L5xError('INVALID_OPERAND', `${instruction.name} takes ${required === instruction.operands.length ? String(required) : `${required}-${instruction.operands.length}`} operand(s): ${shape}; ${args.length} were supplied.`, `Call list_instructions with filter "${instruction.name}" for the exact operand order.`);
+        }
+        for (const [index, argument] of args.entries())
+            checkOperand(project, argument, instruction.operands[index].kind, operands);
+        return { text: `${instruction.name}(${args.join(',')})`, grounding: 'catalog' };
+    }
+    const aoi = project.document.aois.find(entry => entry.name.toUpperCase() === node.instr.toUpperCase());
+    if (aoi === undefined) {
+        throw new L5xError('UNKNOWN_INSTRUCTION', `"${node.instr}" is neither a catalogued instruction nor an AOI declared in this export.`, 'Call list_instructions for the catalog; an AOI must be declared in the project.', nearestInstructions(node.instr));
+    }
+    // AOI pins are declared by the AOI, not by this catalog; the operand text is
+    // still resolved so a typo in a tag cannot reach the draft.
+    for (const argument of args)
+        checkOperand(project, argument, 'ANY', operands);
+    return { text: `${aoi.name}(${args.join(',')})`, grounding: 'aoi' };
+}
+/** Emit one node tree, validating as it goes. */
+function composeNode(project, node, operands, counter, depth, grounds) {
+    if (depth > MAX_DEPTH)
+        throw new L5xError('LADDER_TOO_LARGE', `Branch nesting exceeds ${MAX_DEPTH}.`, 'Flatten the branches.');
+    if ('parallel' in node) {
+        if (!Array.isArray(node.parallel) || node.parallel.length < 2) {
+            throw new L5xError('INVALID_LADDER_SPEC', 'A parallel branch needs at least two paths.', 'Wrap the alternative paths in "parallel": [[...],[...]].');
+        }
+        const paths = node.parallel.map(path => {
+            if (!Array.isArray(path) || path.length === 0)
+                throw new L5xError('INVALID_LADDER_SPEC', 'A parallel path cannot be empty.', 'Give every path at least one instruction.');
+            return path.map(entry => composeNode(project, entry, operands, counter, depth + 1, grounds)).join('');
+        });
+        return `[${paths.join(' ,')} ]`;
+    }
+    if ('series' in node) {
+        if (!Array.isArray(node.series) || node.series.length === 0) {
+            throw new L5xError('INVALID_LADDER_SPEC', 'A series cannot be empty.', 'Give the series at least one instruction.');
+        }
+        return node.series.map(entry => composeNode(project, entry, operands, counter, depth + 1, grounds)).join('');
+    }
+    const composed = composeInstruction(project, node, operands, counter);
+    grounds.add(composed.grounding);
+    return composed.text;
+}
+/** Validate the rung we just emitted with the parser the draft path uses. */
+function verify(project, text, operands, instructions, grounds) {
+    const parsed = parseLadder(text);
+    if (parsed.issues.length > 0) {
+        // The composer produced text its own parser rejects: a defect, never a draft.
+        throw new L5xError('COMPOSER_DEFECT', `The composed rung does not parse: ${parsed.issues[0]?.message ?? 'unknown issue'}`, 'This is a plugin defect; report the spec that produced it.');
+    }
+    const grounding = grounds.size === 2 ? 'mixed' : grounds.has('aoi') ? 'aoi' : 'catalog';
+    return { neutral_text: text, instructions, operands, grounding };
+}
+/**
+ * Compose one rung from a structure tree.
+ *
+ * @param project - Fresh export snapshot the operands are resolved against.
+ * @param spec - The composition tree.
+ * @returns The validated rung.
+ */
+export function composeRung(project, spec) {
+    const operands = [];
+    const counter = { instructions: 0 };
+    const grounds = new Set();
+    const text = `${composeNode(project, spec, operands, counter, 0, grounds)};`;
+    if (counter.instructions === 0)
+        throw new L5xError('INVALID_LADDER_SPEC', 'The specification contains no instruction.', 'Give the rung at least one instruction.');
+    return verify(project, text, operands, counter.instructions, grounds);
+}
+/** A required pattern argument. */
+function arg(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new L5xError('INVALID_ARGUMENT', `Pattern argument ${name} must be a non-empty string.`, `Pass ${name} as a declared tag name.`);
+    }
+    return value.trim();
+}
+/** A pattern's named tags, expanded to one or two rungs. */
+export function composePattern(project, pattern, args) {
+    const one = (spec) => ({ rungs: [composeRung(project, spec)], pattern });
+    if (pattern === 'start_stop_latch') {
+        const start = arg(args, 'start');
+        const stop = arg(args, 'stop');
+        const run = arg(args, 'run');
+        return one({ series: [
+                { parallel: [[{ instr: 'XIC', args: [start] }], [{ instr: 'XIC', args: [run] }]] },
+                { instr: 'XIO', args: [stop] },
+                { instr: 'OTE', args: [run] },
+            ] });
+    }
+    if (pattern === 'interlock') {
+        const conditions = args.conditions;
+        if (!Array.isArray(conditions) || conditions.length === 0) {
+            throw new L5xError('INVALID_ARGUMENT', 'interlock needs conditions: at least one tag.', 'Pass conditions as an array of declared BOOL tag names.');
+        }
+        const output = arg(args, 'output');
+        return one({ series: [
+                ...conditions.map(condition => ({ instr: 'XIC', args: [String(condition)] })),
+                { instr: 'OTE', args: [output] },
+            ] });
+    }
+    if (pattern === 'ton_delay') {
+        const enable = arg(args, 'enable');
+        const timer = arg(args, 'timer');
+        const preset = args.preset_ms;
+        if (typeof preset !== 'number' || !Number.isFinite(preset) || preset < 0) {
+            throw new L5xError('INVALID_ARGUMENT', 'ton_delay needs preset_ms as a non-negative number.', 'Pass the preset in milliseconds, for example 1500.');
+        }
+        return one({ series: [{ instr: 'XIC', args: [enable] }, { instr: 'TON', args: [timer, String(preset)] }] });
+    }
+    // fault_latch: set on the fault, clear on the reset — two rungs, never one.
+    const fault = arg(args, 'fault');
+    const reset = arg(args, 'reset');
+    const latched = arg(args, 'latched');
+    return {
+        pattern,
+        rungs: [
+            composeRung(project, { series: [{ instr: 'XIC', args: [fault] }, { instr: 'OTL', args: [latched] }] }),
+            composeRung(project, { series: [{ instr: 'XIC', args: [reset] }, { instr: 'OTU', args: [latched] }] }),
+        ],
+    };
+}

package/vendor/l5x/lib/index.d.ts

@@ -31,6 +31,7 @@ export { ProjectSession } from './session.ts';
 export { readTools } from './tools/read.ts';
 export { referenceTools } from './tools/references.ts';
 export { checkTools } from './tools/checks.ts';
+export { documentTools } from './tools/document.ts';
 export { L5xError } from './core/errors.ts';
 export type { NextStep, Coverage, Success } from './core/result.ts';
 export type { ToolDefinition } from './core/tool.ts';

package/vendor/l5x/lib/index.js

@@ -12,6 +12,7 @@ import { ProjectSession } from "./session.js";
 import { readTools } from "./tools/read.js";
 import { referenceTools } from "./tools/references.js";
 import { checkTools } from "./tools/checks.js";
+import { documentTools } from "./tools/document.js";
 /** Plugin name in a composition. */
 export const name = 'l5x-read';
 /** Services this plugin cannot register without. */
@@ -31,7 +32,7 @@ export function apply(ctx, config = {}) {
     }
     const session = new ProjectSession(ctx.fs, maxFileBytes);
     ctx.provide?.(PROJECTS_SERVICE, session);
-    for (const definition of [...readTools(session), ...referenceTools(session), ...checkTools(session)]) {
+    for (const definition of [...readTools(session), ...referenceTools(session), ...checkTools(session), ...documentTools(session)]) {
         ctx.tools.register(definition);
     }
 }
@@ -39,4 +40,5 @@ export { ProjectSession } from "./session.js";
 export { readTools } from "./tools/read.js";
 export { referenceTools } from "./tools/references.js";
 export { checkTools } from "./tools/checks.js";
+export { documentTools } from "./tools/document.js";
 export { L5xError } from "./core/errors.js";

package/vendor/l5x/lib/model/routines.js

@@ -175,7 +175,12 @@ function decodeLines(routine) {
 function decodeRung(rung) {
     const textElement = firstChild(rung, 'Text');
     const text = textElement === undefined ? '' : (nodeText(textElement) ?? '').trim();
-    const comment = optionalAttribute(rung, 'Comment', '');
+    // Current exports write the comment as a <Comment> child (CDATA); older ones
+    // used the attribute. Reading only the attribute dropped 572 real comments in
+    // one project, which is what a documentation pass needs most.
+    const commentElement = firstChild(rung, 'Comment');
+    const fromChild = commentElement === undefined ? undefined : nodeText(commentElement);
+    const comment = (fromChild ?? optionalAttribute(rung, 'Comment', '')).trim();
     const number = Number.parseInt(attribute(rung, 'Number'), 10);
     if (comment === '')
         return { number, text };

package/vendor/l5x/lib/session.d.ts

@@ -101,6 +101,26 @@ export declare class ProjectSession {
      * @returns The resolved path.
      */
     resolvePath(requestedPath: string, exec?: ExecContext): Promise<string>;
+    /**
+     * Whether one path already exists.
+     *
+     * @param requestedPath - Path as the caller supplied it.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns True when the provider reports a file or folder there.
+     */
+    exists(requestedPath: string, exec?: ExecContext): Promise<boolean>;
+    /**
+     * Write one text file at an exact path, without the `.L5X` restriction.
+     *
+     * Used by the documentation bundle: the provider creates missing parent
+     * folders, so a new `output_root` needs no separate mkdir.
+     *
+     * @param requestedPath - Destination as the caller supplied it.
+     * @param text - File contents.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved destination.
+     */
+    writeTextAt(requestedPath: string, text: string, exec?: ExecContext): Promise<string>;
     /**
      * Write one prepared draft to a new path, never overwriting.
      *

package/vendor/l5x/lib/session.js

@@ -144,6 +144,42 @@ export class ProjectSession {
         });
         return target.displayPath;
     }
+    /**
+     * Whether one path already exists.
+     *
+     * @param requestedPath - Path as the caller supplied it.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns True when the provider reports a file or folder there.
+     */
+    async exists(requestedPath, exec) {
+        const target = await this.fs.resolve(requestedPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        return (await this.fs.stat(target, exec?.signal)) !== undefined;
+    }
+    /**
+     * Write one text file at an exact path, without the `.L5X` restriction.
+     *
+     * Used by the documentation bundle: the provider creates missing parent
+     * folders, so a new `output_root` needs no separate mkdir.
+     *
+     * @param requestedPath - Destination as the caller supplied it.
+     * @param text - File contents.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved destination.
+     */
+    async writeTextAt(requestedPath, text, exec) {
+        if (this.fs.writeText === undefined) {
+            throw new L5xError('OUTPUT_UNAVAILABLE', 'The filesystem provider in this profile cannot write files.', 'Use a profile whose filesystem provider allows writes.');
+        }
+        const target = await this.fs.resolve(requestedPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        await this.fs.writeText(target, text, { kind: 'createIfAbsent' }, exec?.signal);
+        return target.displayPath;
+    }
     /**
      * Write one prepared draft to a new path, never overwriting.
      *

package/vendor/l5x/lib/tools/document.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The documentation and generation-reference tools.
+ *
+ * `list_instructions` is the catalog the composer validates against, exposed so a
+ * caller can read operand order instead of guessing it. `document_project` builds
+ * the handover bundle into a new folder: it writes documents, never the project.
+ *
+ * @module dsh-engineering-l5x/tools/document
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+/**
+ * The documentation tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function documentTools(session: ProjectSession): readonly ToolDefinition[];

package/vendor/l5x/lib/tools/document.js

@@ -0,0 +1,119 @@
+/**
+ * The documentation and generation-reference tools.
+ *
+ * `list_instructions` is the catalog the composer validates against, exposed so a
+ * caller can read operand order instead of guessing it. `document_project` builds
+ * the handover bundle into a new folder: it writes documents, never the project.
+ *
+ * @module dsh-engineering-l5x/tools/document
+ */
+import { DOCUMENT_PARTS, buildDocumentation } from "../engine/documentation.js";
+import { INSTRUCTIONS } from "../engine/instructions.js";
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { choice, integer, list, object, string } from "../core/params.js";
+import { PROJECT_ID, optionalString, requiredString, tool } from "./common.js";
+/** What a catalog listing cannot establish. */
+const CATALOG_COVERAGE = {
+    complete: false,
+    unverified: [
+        'vendor instructions outside this catalog',
+        'operand coercion the controller applies at compile time',
+        'runtime behavior',
+    ],
+};
+/** What a generated document bundle cannot establish. */
+const DOCUMENT_COVERAGE = {
+    complete: false,
+    unverified: [
+        'narrative prose: the bundle carries structure, citations and existing descriptions only',
+        'cause-and-effect and FAT/SAT documents are not generated',
+        'runtime behavior and anything outside the export (HMI, produced/consumed tags, drivers)',
+    ],
+};
+/** One catalog row as the tool returns it. */
+function catalogRow(instruction) {
+    return {
+        name: instruction.name,
+        category: instruction.category,
+        summary: instruction.summary,
+        operands: instruction.operands.map(slot => ({ name: slot.name, kind: slot.kind, required: slot.optional !== true })),
+    };
+}
+/**
+ * The documentation tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function documentTools(session) {
+    return [
+        tool({
+            name: 'list_instructions',
+            description: 'List the ladder instructions the composer validates: mnemonic, category, summary and operand slots with their kinds. Read it before composing a rung instead of guessing operand order.',
+            parameters: object({
+                filter: string('Case-insensitive substring matched against the instruction name, category or summary.'),
+                category: string('Only instructions in this category, for example "Comparison".'),
+                limit: integer('Maximum rows to return.', { minimum: 1, maximum: 200, default: 100 }),
+            }, []),
+            async run(args) {
+                const filter = (optionalString(args, 'filter') ?? '').toLowerCase();
+                const category = (optionalString(args, 'category') ?? '').toLowerCase();
+                const limit = typeof args.limit === 'number' ? Math.min(Math.max(Math.trunc(args.limit), 1), 200) : 100;
+                const rows = INSTRUCTIONS
+                    .filter(instruction => category === '' || instruction.category.toLowerCase() === category)
+                    .filter(instruction => filter === '' || instruction.name.toLowerCase().includes(filter)
+                    || instruction.category.toLowerCase().includes(filter)
+                    || instruction.summary.toLowerCase().includes(filter));
+                return success(`${rows.length} instruction(s)${category === '' ? '' : ` in ${category}`}${filter === '' ? '' : ` matching ${JSON.stringify(filter)}`}; showing ${Math.min(rows.length, limit)}.`, {
+                    total: rows.length,
+                    categories: [...new Set(INSTRUCTIONS.map(instruction => instruction.category))],
+                    rows: rows.slice(0, limit).map(catalogRow),
+                }, [{ tool: 'compose_rung', why: 'Compose a rung from the instruction and its operand order.' }], CATALOG_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'document_project',
+            description: 'Write a documentation bundle for the open project into a NEW folder: project summary, I/O list, tag CSVs (including the Studio Tags and Comments shape) and per-program rung documentation with comments and referenced tags. Never writes to the export.',
+            parameters: object({
+                output_root: string('New folder for the bundle. It must not exist. Example: "C:/Projects/Line/documentation".'),
+                include: list('Optional parts to produce; default all. One of project, io, tags, rungs.', choice('One part.', DOCUMENT_PARTS)),
+                programs: list('Optional program names to restrict the bundle to.', string('Program name.')),
+                routines: list('Optional routine names to restrict the rung documentation to.', string('Routine name.')),
+                rungs_per_file: integer('Most rungs per rung-documentation file before a continuation file is written. Defaults to 200.', { minimum: 1, maximum: 2000 }),
+                project_id: PROJECT_ID,
+            }, ['output_root']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const outputRoot = requiredString(args, 'output_root');
+                const include = Array.isArray(args.include) && args.include.length > 0
+                    ? args.include.map(String)
+                    : undefined;
+                const unknown = include?.filter(part => !DOCUMENT_PARTS.includes(part));
+                if (unknown !== undefined && unknown.length > 0) {
+                    throw new L5xError('INVALID_ARGUMENT', `Unknown part(s): ${unknown.join(', ')}.`, `Pass any of: ${DOCUMENT_PARTS.join(', ')}.`);
+                }
+                if (await session.exists(outputRoot, exec)) {
+                    throw new L5xError('OUTPUT_EXISTS', `A file or folder already exists at ${outputRoot}.`, 'Pass a new output_root; the generator never merges into an existing folder.');
+                }
+                const bundle = buildDocumentation(project, {
+                    ...(include === undefined ? {} : { include }),
+                    ...(Array.isArray(args.programs) ? { programs: args.programs.map(String) } : {}),
+                    ...(Array.isArray(args.routines) ? { routines: args.routines.map(String) } : {}),
+                    ...(typeof args.rungs_per_file === 'number' ? { rungsPerFile: args.rungs_per_file } : {}),
+                });
+                const written = [];
+                for (const [path, text] of bundle.files) {
+                    const destination = await session.writeTextAt(`${outputRoot.replace(/[\\/]+$/u, '')}/${path}`, text, exec);
+                    written.push({ path: destination, bytes: new TextEncoder().encode(text).length });
+                }
+                return success(`Wrote ${written.length} file(s) for ${bundle.counts.programs} program(s), ${bundle.counts.routines} routine(s), ${bundle.counts.rungs} rung(s) (${bundle.counts.comments} commented) to ${outputRoot}.`, {
+                    output_root: outputRoot,
+                    files: written,
+                    counts: bundle.counts,
+                    excluded: bundle.excluded,
+                }, [{ tool: 'draft_rung_comment', why: 'Write the approved narrative back as rung comments, then apply the draft.' }], DOCUMENT_COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/l5x/lib/tools/drafts.js

@@ -9,6 +9,7 @@
  * @module dsh-engineering-l5x/tools/drafts
  */
 import { prepareChangeSet } from "../engine/change-set.js";
+import { composePattern, composeRung, PATTERNS } from "../engine/ladder.js";
 import { L5xError } from "../core/errors.js";
 import { success } from "../core/result.js";
 import { choice, integer, object, string } from "../core/params.js";
@@ -26,6 +27,30 @@ const DRAFT_COVERAGE = {
 function requestOf(draft) {
     return JSON.stringify({ version: 1, operations: draft.operations });
 }
+/** What a composed rung does not prove. */
+const COMPOSED_COVERAGE = {
+    complete: false,
+    unverified: [
+        'compiled behaviour: the composer validates instruction names, operand counts and operand types only',
+        'Studio 5000 import and build are not performed by this surface',
+        'runtime behavior',
+    ],
+};
+/** Parse one JSON-object argument, refusing anything else. */
+function jsonObject(value, name) {
+    if (value === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalid(name, `${name} is not valid JSON.`, `Pass a JSON object, for example {"start":"Start"}.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw invalid(name, `${name} must be a JSON object.`, 'Pass a JSON object.');
+    return parsed;
+}
 /** The success document every append answers with. */
 function appended(draft, operation) {
     return success(`Draft ${draft.id}: ${draft.operations.length} ${draft.operations.length === 1 ? 'operation' : 'operations'}.`, { draft_id: draft.id, operation_count: draft.operations.length, last_operation: operation }, [{ tool: 'draft_validate', args: { draft_id: draft.id }, why: 'Validate the whole draft before writing anything.' }]);
@@ -43,7 +68,7 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
     return [
         tool({
             name: 'draft_rung',
-            description: 'Append one ladder rung operation to the chat draft: replace, insert or delete. Nothing is written until draft_apply.',
+            description: 'Append one ladder rung operation to the chat draft: replace, insert or delete. Optionally carries the rung comment. Nothing is written until draft_apply.',
             parameters: object({
                 program: string('Program that owns the routine. Example: "MainProgram".'),
                 routine: string('Routine the rung belongs to. Example: "MainRoutine".'),
@@ -51,6 +76,7 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 rung: integer('Rung number the operation targets. Required for replace and delete; for insert it is the new rung number.', { minimum: 0 }),
                 text: string('NeutralText for replace or insert. Omit for delete. Example: "XIC(Start)OTE(Run);"'),
                 before_rung: integer('For insert only: insert before this rung number instead of after rung.', { minimum: 0 }),
+                comment: string('Optional rung comment, written above the rung in Studio. Omit to leave an existing comment unchanged.'),
                 project_id: PROJECT_ID,
             }, ['program', 'routine', 'mode']),
             async run(args, exec) {
@@ -61,6 +87,7 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 const text = optionalString(args, 'text');
                 const rung = optionalInteger(args, 'rung');
                 const before = optionalInteger(args, 'before_rung');
+                const comment = args.comment === undefined ? undefined : String(args.comment);
                 let operation;
                 if (mode === 'delete') {
                     if (rung === undefined)
@@ -70,12 +97,12 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 else if (mode === 'replace') {
                     if (rung === undefined || text === undefined)
                         throw invalid('rung and text', 'Required when mode is replace.', 'Pass the rung number and its new NeutralText.');
-                    operation = { operation: 'replace_rung', program, routine, rung, text };
+                    operation = { operation: 'replace_rung', program, routine, rung, text, ...(comment === undefined ? {} : { comment }) };
                 }
                 else if (mode === 'insert') {
                     if (rung === undefined || text === undefined)
                         throw invalid('rung and text', 'Required when mode is insert.', 'Pass the new rung number and its NeutralText.');
-                    operation = { operation: 'insert_rung', program, routine, rung, text, ...(before === undefined ? {} : { before_rung: before }) };
+                    operation = { operation: 'insert_rung', program, routine, rung, text, ...(before === undefined ? {} : { before_rung: before }), ...(comment === undefined ? {} : { comment }) };
                 }
                 else {
                     throw invalid('mode', `Unknown mode ${JSON.stringify(mode)}.`, 'Pass one of: replace, insert, delete.');
@@ -83,6 +110,85 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
             },
         }),
+        tool({
+            name: 'draft_rung_comment',
+            description: 'Append one rung-comment change to the chat draft. Sets or clears the comment Studio shows above a rung; the logic is untouched. Nothing is written until draft_apply.',
+            parameters: object({
+                program: string('Program that owns the routine. Example: "MainProgram".'),
+                routine: string('Ladder routine the rung belongs to. Example: "MainRoutine".'),
+                rung: integer('Rung number whose comment changes.', { minimum: 0 }),
+                comment: string('New comment text. Pass an empty string to clear an existing comment.'),
+                project_id: PROJECT_ID,
+            }, ['program', 'routine', 'rung', 'comment']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const operation = {
+                    operation: 'set_rung_comment',
+                    program: requiredString(args, 'program'),
+                    routine: requiredString(args, 'routine'),
+                    rung: optionalInteger(args, 'rung') ?? 0,
+                    comment: typeof args.comment === 'string' ? args.comment : '',
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'compose_rung',
+            description: 'Compose one validated ladder rung from a structure or a named pattern, checking every instruction and operand against the export, and optionally stage it in the draft. Never emits text that fails the ladder parser.',
+            parameters: object({
+                pattern: choice('Named pattern to expand. fault_latch produces two rungs.', PATTERNS),
+                spec_json: string('Composition tree as JSON, for example {"series":[{"instr":"XIC","args":["Start"]},{"instr":"OTE","args":["Run"]}]}.'),
+                arguments_json: string('Pattern arguments as JSON, for example {"start":"Start","stop":"Stop","run":"Run"}.'),
+                program: string('Program to stage into. Omit to return the composed text only.'),
+                routine: string('Routine to stage into. Required with program.'),
+                mode: choice('insert adds a rung; replace rewrites one.', ['insert', 'replace']),
+                rung: integer('Rung number for a staged operation. For a two-rung pattern, the second uses rung + 1.', { minimum: 0 }),
+                before_rung: integer('For insert: insert before this rung number instead of after rung.', { minimum: 0 }),
+                comment: string('Optional rung comment for the staged rung.'),
+                draft_id: string('Draft handle to append to. Omit when exactly one draft exists in this chat.'),
+                project_id: PROJECT_ID,
+            }, []),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const pattern = optionalString(args, 'pattern');
+                const specJson = optionalString(args, 'spec_json');
+                if ((pattern === undefined) === (specJson === undefined)) {
+                    throw invalid('pattern or spec_json', 'Pass exactly one of a named pattern or a composition tree.', 'Use pattern + arguments_json for a common shape, or spec_json for explicit logic.');
+                }
+                let composed;
+                if (pattern !== undefined) {
+                    if (!PATTERNS.includes(pattern))
+                        throw invalid('pattern', `Unknown pattern ${JSON.stringify(pattern)}.`, `Pass one of: ${PATTERNS.join(', ')}.`);
+                    composed = composePattern(project, pattern, jsonObject(typeof args.arguments_json === 'string' ? args.arguments_json : undefined, 'arguments_json'));
+                }
+                else {
+                    const spec = jsonObject(specJson, 'spec_json');
+                    composed = { rungs: [composeRung(project, spec)] };
+                }
+                const program = optionalString(args, 'program');
+                const routine = optionalString(args, 'routine');
+                const mode = optionalString(args, 'mode');
+                const rung = optionalInteger(args, 'rung');
+                const staged = program !== undefined || routine !== undefined || mode !== undefined || rung !== undefined;
+                if (!staged) {
+                    return success(`Composed ${composed.rungs.length} rung(s)${composed.pattern === undefined ? '' : ` from ${composed.pattern}`}; pass program and routine to stage it.`, { pattern: composed.pattern, rungs: composed.rungs }, [{ tool: 'compose_rung', args: { spec_json: '{"series":[]}' }, why: 'Adjust the structure, or stage this text with draft_rung.' }], COMPOSED_COVERAGE);
+                }
+                if (program === undefined || routine === undefined || mode === undefined || rung === undefined) {
+                    throw invalid('program, routine, mode and rung', 'Staging needs all four.', 'Pass program, routine, mode and rung together, or none of them.');
+                }
+                if (composed.rungs.length > 1 && mode === 'replace')
+                    throw invalid('mode', 'A two-rung pattern cannot replace one rung.', 'Use mode insert, or compose a single rung.');
+                let draft;
+                for (const [index, composedRung] of composed.rungs.entries()) {
+                    const operation = mode === 'replace'
+                        ? { operation: 'replace_rung', program, routine, rung, text: composedRung.neutral_text, ...(typeof args.comment === 'string' ? { comment: args.comment } : {}) }
+                        : { operation: 'insert_rung', program, routine, rung: rung + index, text: composedRung.neutral_text, ...(index === 0 && args.before_rung !== undefined ? { before_rung: optionalInteger(args, 'before_rung') } : {}), ...(typeof args.comment === 'string' ? { comment: args.comment } : {}) };
+                    draft = drafts.append(exec, project.id, operation, maxOperations);
+                }
+                const stagedDraft = draft;
+                return success(`Composed and staged ${composed.rungs.length} rung(s)${composed.pattern === undefined ? '' : ` from ${composed.pattern}`}. Draft ${stagedDraft.id}: ${stagedDraft.operations.length} operation(s).`, { draft_id: stagedDraft.id, operation_count: stagedDraft.operations.length, pattern: composed.pattern, rungs: composed.rungs }, [{ tool: 'draft_validate', args: { draft_id: stagedDraft.id }, why: 'Validate the whole draft before writing anything.' }], COMPOSED_COVERAGE);
+            },
+        }),
         tool({
             name: 'draft_st',
             description: 'Append one Structured Text body replacement to the chat draft. Nothing is written until draft_apply.',