@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/l5x/lib/engine/project-analysis.js

@@ -0,0 +1,314 @@
+import { resolveTag } from "./tag-resolution.js";
+import { addressAt, lexLogic, parseLadder } from "./logic-syntax.js";
+/** Registry version changes when operand roles change. It does not certify controller availability. */
+export const SEMANTICS_VERSION = 1;
+const roles = {
+    XIC: ['read'], XIO: ['read'], OTE: ['write'], OTL: ['write'], OTU: ['write'], CLR: ['write'],
+    MOV: ['read', 'write'], MOVE: ['read', 'write'], COP: ['read', 'write', 'read'], CPS: ['read', 'write', 'read'], FLL: ['read', 'write', 'read'],
+    ADD: ['read', 'read', 'write'], SUB: ['read', 'read', 'write'], MUL: ['read', 'read', 'write'], DIV: ['read', 'read', 'write'],
+    EQU: ['read', 'read'], EQ: ['read', 'read'], NEQ: ['read', 'read'], NE: ['read', 'read'], GRT: ['read', 'read'], GT: ['read', 'read'],
+    GEQ: ['read', 'read'], GE: ['read', 'read'], LES: ['read', 'read'], LT: ['read', 'read'], LEQ: ['read', 'read'], LE: ['read', 'read'],
+    LIM: ['read', 'read', 'read'], LIMIT: ['read', 'read', 'read'], TON: ['read_write', 'read', 'read'], TOF: ['read_write', 'read', 'read'], RTO: ['read_write', 'read', 'read'],
+    CTU: ['read_write', 'read', 'read'], CTD: ['read_write', 'read', 'read'], RES: ['read_write'], ONS: ['read_write'], NOP: [], AFI: [],
+};
+const keywords = new Set('IF THEN ELSE ELSIF END_IF FOR TO BY DO END_FOR WHILE END_WHILE REPEAT UNTIL END_REPEAT CASE OF END_CASE RETURN EXIT TRUE FALSE NOT AND OR XOR MOD'.split(' '));
+const cache = new WeakMap();
+/** Build source-positioned references and conservative local dependency edges once per snapshot.
+ * @param project - Immutable export snapshot.
+ * @param bounds - Inclusive reference and edge limits; truncation makes coverage incomplete.
+ * @returns Shared analysis with located limitations and source identity.
+ */
+export function analyzeProject(project, bounds) {
+    const cacheKey = `${bounds.references}:${bounds.edges}`;
+    const cached = cache.get(project)?.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const references = [];
+    const dependencies = [];
+    const limitations = [];
+    const truncated = new Set();
+    const location = (routine, token, rung) => ({ scope: routine.program, routine: routine.name, language: routine.type, ...(rung === undefined ? { line: token.line } : { rung }), start: token.start, end: token.end });
+    const limit = (routine, reason, rung, offset) => {
+        if (limitations.length < bounds.references)
+            limitations.push({ scope: routine.program, routine: routine.name, ...(rung === undefined ? {} : { rung }), ...(offset === undefined ? {} : { offset }), reason });
+        else
+            truncated.add('Limitation report limit reached');
+    };
+    const addAddresses = (routine, tokens, access, source, rung, instruction) => {
+        const indices = [];
+        for (let cursor = 0; cursor < tokens.length;) {
+            if (references.length >= bounds.references) {
+                truncated.add('Reference analysis limit reached');
+                break;
+            }
+            const token = tokens[cursor];
+            if (token.kind !== 'identifier' || keywords.has(token.text.toUpperCase())) {
+                cursor++;
+                continue;
+            }
+            const found = addressAt(tokens, cursor);
+            if (found === undefined) {
+                limit(routine, 'Malformed symbol address', rung, token.start);
+                cursor++;
+                continue;
+            }
+            cursor = found.next;
+            const call = tokens[cursor]?.text === '(';
+            const resolution = resolveTag(project.document, routine.program, found.address.text);
+            const role = call ? 'unknown' : access;
+            const index = references.length;
+            references.push({ ...location(routine, token, rung), end: found.address.end, symbol: found.address.text,
+                ...(resolution.canonical === undefined ? {} : { canonical: resolution.canonical }), access: role,
+                ...(instruction === undefined ? {} : { instruction }), indices_verified: resolution.indices_verified,
+                context: rung === undefined ? source.split('\n')[token.line] ?? '' : source });
+            indices.push(index);
+            if (!resolution.resolved)
+                limit(routine, `${found.address.text}: ${resolution.reason}`, rung, token.start);
+            if (!resolution.indices_verified)
+                limit(routine, `Dynamic subscript in ${found.address.text}`, rung, token.start);
+            if (role === 'unknown')
+                limit(routine, `Unresolved operand effects for ${found.address.text}`, rung, token.start);
+            if (found.address.indexTokens.length > 0)
+                indices.push(...addAddresses(routine, found.address.indexTokens, 'read', source, rung, instruction));
+        }
+        return indices;
+    };
+    const connect = (indices, kind) => {
+        const reads = indices.filter(index => ['read', 'read_write'].includes(references[index].access));
+        const writes = indices.filter(index => ['write', 'read_write'].includes(references[index].access));
+        for (const read of reads)
+            for (const write of writes) {
+                const from = references[read].canonical;
+                const to = references[write].canonical;
+                if (from !== undefined && to !== undefined) {
+                    if (dependencies.length >= bounds.edges) {
+                        truncated.add('Dependency analysis limit reached');
+                        return;
+                    }
+                    dependencies.push({ from, to, kind, evidence: [read, write] });
+                }
+            }
+    };
+    const analyzeLadder = (routine, source, rung) => {
+        const parsed = parseLadder(source);
+        for (const issue of parsed.issues)
+            limit(routine, issue.message, rung, issue.offset);
+        const rungIndices = [];
+        const visit = (nodes) => {
+            for (const node of nodes) {
+                if (references.length >= bounds.references) {
+                    truncated.add('Reference analysis limit reached');
+                    break;
+                }
+                if (node.kind === 'branch') {
+                    for (const path of node.paths)
+                        visit(path);
+                    continue;
+                }
+                const name = node.name.toUpperCase();
+                if (name === 'JSR') {
+                    const target = node.operands[0]?.map(token => token.text).join('') ?? '';
+                    const called = routines.find(entry => entry.program.toLowerCase() === routine.program.toLowerCase() && entry.name.toLowerCase() === target.toLowerCase());
+                    references.push({ scope: routine.program, routine: routine.name, language: routine.type, rung, start: node.start, end: node.end, symbol: target, ...(called === undefined ? {} : { canonical: `routine::${called.program}::${called.name}` }), access: 'call', instruction: node.name, indices_verified: true, context: source });
+                    limit(routine, 'JSR parameter transfer and called-routine effects require interprocedural analysis', rung, node.start);
+                    for (const operand of node.operands.slice(1))
+                        rungIndices.push(...addAddresses(routine, operand, 'unknown', source, rung, node.name));
+                    continue;
+                }
+                const aoi = project.document.aois.find(entry => entry.name.toUpperCase() === name);
+                let operandRoles = roles[name];
+                if (aoi !== undefined) {
+                    references.push({ scope: routine.program, routine: routine.name, language: routine.type, rung, start: node.start, end: node.end, symbol: aoi.name, canonical: `AOI::${aoi.name}`, access: 'call', instruction: node.name, indices_verified: true, context: source });
+                    const parameters = aoi.parameters.filter(parameter => parameter.visible !== false && !['EnableIn', 'EnableOut'].includes(parameter.name));
+                    operandRoles = ['read_write', ...parameters.map(parameter => parameter.usage === 'Input' ? 'read' : parameter.usage === 'Output' ? 'write' : parameter.usage === 'InOut' ? 'read_write' : 'unknown')];
+                    limit(routine, 'AOI parameter usage is known; instance execution effects remain partial', rung, node.start);
+                }
+                if (operandRoles === undefined || operandRoles.length !== node.operands.length) {
+                    limit(routine, `Unsupported instruction or operand count: ${node.name}`, rung, node.start);
+                    operandRoles = node.operands.map(() => 'unknown');
+                }
+                const instructionIndices = node.operands.flatMap((operand, index) => addAddresses(routine, operand, operandRoles[index], source, rung, node.name));
+                rungIndices.push(...instructionIndices);
+                connect(instructionIndices, 'operand');
+            }
+        };
+        visit(parsed.nodes);
+        connect(rungIndices, 'condition_candidate');
+    };
+    const analyzeSt = (routine, source) => {
+        const parsed = lexLogic(source);
+        for (const issue of parsed.issues)
+            limit(routine, issue.message, undefined, issue.offset);
+        let statement = [];
+        const visit = () => {
+            if (statement.length === 0)
+                return;
+            const assignment = statement.findIndex(token => token.text === ':=');
+            const hasControl = statement.some(token => keywords.has(token.text.toUpperCase()) && !['TRUE', 'FALSE', 'AND', 'OR', 'XOR', 'NOT', 'MOD'].includes(token.text.toUpperCase()));
+            if (hasControl)
+                limit(routine, 'ST control-flow dependencies are partial', undefined, statement[0].start);
+            if (assignment < 0) {
+                addAddresses(routine, statement, 'read', source);
+                return;
+            }
+            const prefix = statement.slice(0, assignment);
+            let targetOffset = -1;
+            for (let cursor = 0; cursor < prefix.length; cursor++) {
+                const target = addressAt(prefix, cursor);
+                if (target?.next === prefix.length && !keywords.has(prefix[cursor].text.toUpperCase())) {
+                    targetOffset = cursor;
+                    break;
+                }
+            }
+            if (targetOffset < 0 || statement.slice(assignment + 1).some(token => token.text === ':=')) {
+                addAddresses(routine, statement, 'unknown', source);
+                limit(routine, 'Unsupported assignment target or chained assignment', undefined, statement[0].start);
+                return;
+            }
+            const inputs = addAddresses(routine, prefix.slice(0, targetOffset), 'read', source);
+            const outputs = addAddresses(routine, prefix.slice(targetOffset), 'write', source);
+            const sources = addAddresses(routine, statement.slice(assignment + 1), 'read', source);
+            connect([...inputs, ...outputs, ...sources], 'operand');
+        };
+        for (const token of parsed.tokens) {
+            if (token.text === ';') {
+                visit();
+                statement = [];
+            }
+            else
+                statement.push(token);
+        }
+        if (statement.length > 0) {
+            visit();
+            limit(routine, 'Source ends without a statement terminator', undefined, statement[0].start);
+        }
+    };
+    const routines = [...project.document.routines, ...project.document.aois.flatMap(aoi => aoi.routines.map(routine => ({ ...routine, program: `AOI::${aoi.name}` })))];
+    for (const routine of routines) {
+        if (routine.body.type === 'RLL')
+            for (const rung of routine.body.rungs)
+                analyzeLadder(routine, rung.text, rung.number);
+        else if (routine.body.type === 'ST')
+            analyzeSt(routine, routine.body.code);
+        else
+            limit(routine, `${routine.type} execution analysis is unsupported`);
+    }
+    if (project.features.protectedContent === 'unsupported')
+        limitations.push({ scope: 'controller', routine: '', reason: 'Protected content is not analyzed' });
+    for (const reason of truncated)
+        limitations.push({ scope: 'controller', routine: '', reason });
+    const result = { project_id: project.id, source_sha256: project.sha256, references, dependencies, limitations, static_complete: limitations.length === 0, runtime_causality_verified: false };
+    const ownedCache = cache.get(project) ?? new Map();
+    ownedCache.set(cacheKey, result);
+    cache.set(project, ownedCache);
+    return result;
+}
+/** Read exported task scheduling, program entry routines and parsed JSR/AOI call locations.
+ * @param project - Immutable selected export.
+ * @param limits - Deployment bounds for graph size and source analysis.
+ * @returns A bounded execution graph; declared scheduling is not observed scan execution.
+ */
+export function executionGraph(project, limits) {
+    const analysis = analyzeProject(project, limits.analysis);
+    const nodes = new Map();
+    const edges = [];
+    let truncated = false;
+    const add = (identity, kind, declared) => {
+        if (nodes.has(identity))
+            return true;
+        if (nodes.size >= limits.nodes) {
+            truncated = true;
+            return false;
+        }
+        nodes.set(identity, { identity, kind, declared });
+        return true;
+    };
+    const edge = (from, to, kind, evidence) => {
+        if (!nodes.has(from) || !nodes.has(to) || edges.length >= limits.edges) {
+            truncated = true;
+            return;
+        }
+        edges.push({ from, to, kind, ...(evidence === undefined ? {} : { evidence }) });
+    };
+    for (const program of project.document.programs) {
+        const id = `program::${program.name}`;
+        add(id, 'program', true);
+        if (program.mainRoutine !== '') {
+            const entry = project.document.routines.find(routine => routine.program === program.name && routine.name.toLowerCase() === program.mainRoutine.toLowerCase());
+            const target = `routine::${program.name}::${entry?.name ?? program.mainRoutine}`;
+            add(target, 'routine', entry !== undefined);
+            edge(id, target, 'entry');
+        }
+    }
+    for (const task of project.document.tasks) {
+        const id = `task::${task.name}`;
+        add(id, 'task', true);
+        for (const scheduled of task.programs) {
+            const program = project.document.programs.find(program => program.name.toLowerCase() === scheduled.toLowerCase());
+            const target = `program::${program?.name ?? scheduled}`;
+            add(target, 'program', program !== undefined);
+            edge(id, target, 'schedules');
+        }
+    }
+    for (const reference of analysis.references)
+        if (reference.access === 'call') {
+            const caller = `routine::${reference.scope}::${reference.routine}`;
+            add(caller, 'routine', true);
+            const target = reference.canonical ?? `routine::${reference.scope}::${reference.symbol}`;
+            add(target, target.startsWith('AOI::') ? 'aoi' : 'routine', reference.canonical !== undefined);
+            edge(caller, target, 'call', reference);
+        }
+    return { project_id: project.id, source_sha256: project.sha256, nodes: [...nodes.values()], edges, truncated,
+        unscheduled_programs: project.document.programs.filter(program => !project.document.tasks.some(task => task.programs.some(name => name.toLowerCase() === program.name.toLowerCase()))).slice(0, limits.nodes).map(program => program.name),
+        static_complete: analysis.static_complete && !truncated && [...nodes.values()].every(node => node.declared), runtime_execution_verified: false };
+}
+/** Trace dependencies or dependents, returning every stopping reason.
+ * @param project - Immutable selected source.
+ * @param symbol - Selected tag address.
+ * @param scope - Its resolution scope.
+ * @param direction - Upstream sources or downstream impact.
+ * @param limits - Validated deployment bounds.
+ * @returns Bounded graph with source-linked edges, coverage and truncation indicators.
+ */
+export function traceDependencies(project, symbol, scope, direction, limits) {
+    const analysis = analyzeProject(project, limits.analysis);
+    const resolution = resolveTag(project.document, scope, symbol);
+    const root = resolution.canonical;
+    const coverage = { limitations: analysis.limitations.slice(0, limits.edges), limitations_total: analysis.limitations.length, limitations_truncated: analysis.limitations.length > limits.edges };
+    if (root === undefined)
+        return { project_id: project.id, source_sha256: project.sha256, resolution, nodes: [], edges: [], ...coverage, truncated: false, static_complete: false, runtime_causality_verified: false };
+    const nodes = new Map([[root, 0]]);
+    const queue = [root];
+    const edges = [];
+    const seenEdges = new Set();
+    const adjacency = new Map();
+    for (const edge of analysis.dependencies) {
+        const key = direction === 'upstream' ? edge.to : edge.from;
+        const existing = adjacency.get(key);
+        if (existing === undefined)
+            adjacency.set(key, [edge]);
+        else
+            existing.push(edge);
+    }
+    let truncated = false;
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const current = queue[cursor];
+        const depth = nodes.get(current);
+        for (const edge of adjacency.get(current) ?? []) {
+            const next = direction === 'upstream' ? edge.from : edge.to;
+            if (seenEdges.has(edge))
+                continue;
+            if (depth >= limits.depth || edges.length >= limits.edges || (!nodes.has(next) && nodes.size >= limits.nodes)) {
+                truncated = true;
+                continue;
+            }
+            seenEdges.add(edge);
+            edges.push(edge);
+            if (!nodes.has(next)) {
+                nodes.set(next, depth + 1);
+                queue.push(next);
+            }
+        }
+    }
+    return { project_id: project.id, source_sha256: project.sha256, resolution, direction, nodes: [...nodes].map(([symbol, depth]) => ({ symbol, depth })), edges: edges.map(edge => ({ ...edge, evidence: edge.evidence.map(index => analysis.references[index]) })), ...coverage, truncated, static_complete: analysis.static_complete && !truncated, runtime_causality_verified: false };
+}

package/vendor/l5x/lib/engine/review-evidence.d.ts

@@ -0,0 +1,8 @@
+/** Exact source-citation checks for model-authored engineering findings. */
+import { type ProjectSnapshot } from '../session.ts';
+/** Verify exact names, locations and quotes without certifying their interpretation.
+ * @param project - hash-checked export snapshot.
+ * @param request - JSON array of program/routine/quote citations with rung or zero-based ST line; AOI programs use AOI::Name.
+ * @returns source identity and per-citation results; no controller or network contact.
+ */
+export declare function verifyReviewEvidence(project: ProjectSnapshot, request: string): object;

package/vendor/l5x/lib/engine/review-evidence.js

@@ -0,0 +1,49 @@
+/** Exact source-citation checks for model-authored engineering findings. */
+import { EngineeringError } from "../session.js";
+function citation(value) {
+    if (typeof value !== 'object' || value === null || !('program' in value) || typeof value.program !== 'string'
+        || !('routine' in value) || typeof value.routine !== 'string' || !('quote' in value) || typeof value.quote !== 'string'
+        || value.program.trim() === '' || value.routine.trim() === '' || value.quote.trim() === '') {
+        throw new EngineeringError('INVALID_CITATION', 'Each citation requires program, routine and a nonempty verbatim quote');
+    }
+    const rung = 'rung' in value ? value.rung : undefined;
+    const line = 'line' in value ? value.line : undefined;
+    if ((rung === undefined) === (line === undefined)
+        || (rung !== undefined && (typeof rung !== 'number' || !Number.isInteger(rung) || rung < 0))
+        || (line !== undefined && (typeof line !== 'number' || !Number.isInteger(line) || line < 0))) {
+        throw new EngineeringError('INVALID_CITATION', 'Specify exactly one nonnegative integer rung or zero-based ST line');
+    }
+    return { program: value.program, routine: value.routine, quote: value.quote,
+        ...(typeof rung === 'number' ? { rung } : {}), ...(typeof line === 'number' ? { line } : {}) };
+}
+/** Verify exact names, locations and quotes without certifying their interpretation.
+ * @param project - hash-checked export snapshot.
+ * @param request - JSON array of program/routine/quote citations with rung or zero-based ST line; AOI programs use AOI::Name.
+ * @returns source identity and per-citation results; no controller or network contact.
+ */
+export function verifyReviewEvidence(project, request) {
+    let parsed;
+    try {
+        parsed = JSON.parse(request);
+    }
+    catch (error) {
+        throw new EngineeringError('INVALID_CITATION', `Citations must be JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0)
+        throw new EngineeringError('INVALID_CITATION', 'Citations must be a nonempty JSON array');
+    const citations = parsed.map(citation);
+    const results = citations.map(item => {
+        const routine = item.program.startsWith('AOI::')
+            ? project.document.aois.find(aoi => `AOI::${aoi.name}` === item.program)?.routines.find(r => r.name === item.routine)
+            : project.document.routines.find(r => r.program === item.program && r.name === item.routine);
+        const text = routine?.body.type === 'RLL' && item.rung !== undefined
+            ? routine.body.rungs.find(r => r.number === item.rung)?.text
+            : routine?.body.type === 'ST' && item.line !== undefined ? routine.body.code.split('\n')[item.line] : undefined;
+        const reason = routine === undefined ? 'routine_not_found' : text === undefined ? 'location_not_found'
+            : !text.includes(item.quote) ? 'quote_mismatch' : 'matched';
+        return { ...item, verified: reason === 'matched', reason, ...(text === undefined ? {} : { source_text: text }) };
+    });
+    return { project_id: project.id, sha256: project.sha256, results, all_citations_verified: results.every(result => result.verified),
+        interpretation_verified: false, controller_contacted: false,
+        note: 'Matching text verifies a citation only. It does not establish runtime behavior, absence of other references, instruction semantics or whole-machine safety.' };
+}

package/vendor/l5x/lib/engine/review.d.ts

@@ -0,0 +1,18 @@
+import type { ProjectSnapshot } from '../session.ts';
+export interface Change {
+    readonly kind: 'added' | 'removed' | 'changed';
+    readonly component: string;
+    readonly key: string;
+    readonly before?: unknown;
+    readonly after?: unknown;
+}
+/** Compare parsed engineering content; timestamps and XML presentation never enter the comparison. */
+export declare function compareProjects(before: ProjectSnapshot, after: ProjectSnapshot): object;
+export interface Finding {
+    readonly rule: string;
+    readonly severity: 'info' | 'warning' | 'critical';
+    readonly message: string;
+    readonly evidence: unknown;
+    readonly confidence: 'high' | 'medium' | 'low';
+}
+export declare function runChecks(project: ProjectSnapshot, baseline?: ProjectSnapshot): object;

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

@@ -0,0 +1,123 @@
+import { evidenceOf } from "./analysis.js";
+import { engineeringTags, moduleConfigurations } from "./configuration.js";
+function changes(component, before, after, key) {
+    const old = new Map(before.map(value => [key(value), value]));
+    const next = new Map(after.map(value => [key(value), value]));
+    const result = [];
+    for (const [name, value] of old) {
+        const other = next.get(name);
+        if (other === undefined)
+            result.push({ kind: 'removed', component, key: name, before: value });
+        else if (JSON.stringify(value) !== JSON.stringify(other))
+            result.push({ kind: 'changed', component, key: name, before: value, after: other });
+    }
+    for (const [name, value] of next)
+        if (!old.has(name))
+            result.push({ kind: 'added', component, key: name, after: value });
+    return result;
+}
+function allRoutines(document) {
+    return [...document.routines, ...document.aois.flatMap(aoi => aoi.routines.map(routine => ({ ...routine, program: `AOI::${aoi.name}` })))];
+}
+/** Compare parsed engineering content; timestamps and XML presentation never enter the comparison. */
+export function compareProjects(before, after) {
+    const a = before.document;
+    const b = after.document;
+    const oldRoutines = allRoutines(a);
+    const newRoutines = allRoutines(b);
+    const result = [
+        ...changes('program', a.programs, b.programs, v => v.name),
+        ...changes('task', a.tasks, b.tasks, v => v.name),
+        ...changes('tag', engineeringTags(a), engineeringTags(b), v => `${v.scope}::${v.name}`),
+        ...changes('udt', a.udts, b.udts, v => v.name),
+        ...changes('aoi', a.aois.map(({ routines: _routines, ...rest }) => rest), b.aois.map(({ routines: _routines, ...rest }) => rest), v => v.name),
+        ...changes('module', moduleConfigurations(a), moduleConfigurations(b), v => v.name),
+        ...changes('alarm', a.alarms, b.alarms, v => v.name),
+        ...changes('routine', oldRoutines.map(({ body: _body, ...rest }) => rest), newRoutines.map(({ body: _body, ...rest }) => rest), v => `${v.program}::${v.name}`),
+    ];
+    const oldRungs = oldRoutines.flatMap(r => r.body.type === 'RLL' ? r.body.rungs.map(v => ({ program: r.program, routine: r.name, ...v })) : []);
+    const newRungs = newRoutines.flatMap(r => r.body.type === 'RLL' ? r.body.rungs.map(v => ({ program: r.program, routine: r.name, ...v })) : []);
+    result.push(...changes('rung', oldRungs, newRungs, v => `${v.program}::${v.routine}::${v.number}`));
+    const oldSt = oldRoutines.filter(r => r.body.type === 'ST').map(r => ({ program: r.program, routine: r.name, code: r.body.type === 'ST' ? r.body.code : '' }));
+    const newSt = newRoutines.filter(r => r.body.type === 'ST').map(r => ({ program: r.program, routine: r.name, code: r.body.type === 'ST' ? r.body.code : '' }));
+    result.push(...changes('structured_text', oldSt, newSt, v => `${v.program}::${v.routine}`));
+    const oldDiagrams = oldRoutines.filter(r => r.body.type === 'FBD' || r.body.type === 'SFC').map(r => ({ program: r.program, routine: r.name, type: r.type, nodes: r.body.type === 'FBD' || r.body.type === 'SFC' ? r.body.nodes : [] }));
+    const newDiagrams = newRoutines.filter(r => r.body.type === 'FBD' || r.body.type === 'SFC').map(r => ({ program: r.program, routine: r.name, type: r.type, nodes: r.body.type === 'FBD' || r.body.type === 'SFC' ? r.body.nodes : [] }));
+    result.push(...changes('diagram', oldDiagrams, newDiagrams, v => `${v.program}::${v.routine}`));
+    return { before: before.sha256, after: after.sha256, changes: result, count: result.length, coverage: { before: before.features, after: after.features } };
+}
+export function runChecks(project, baseline) {
+    const doc = project.document;
+    const references = evidenceOf(project);
+    const findings = [];
+    const report = (rule, severity, message, evidence, confidence = 'high') => { findings.push({ rule, severity, message, evidence, confidence }); };
+    const used = new Set();
+    for (const ref of references) {
+        if (ref.resolved !== undefined) {
+            const resolved = ref.resolved.toLowerCase();
+            used.add(resolved);
+            used.add(resolved.split('.')[0] ?? resolved);
+        }
+        const rawBase = ref.symbol.split('.')[0] ?? ref.symbol;
+        used.add(`${ref.scope}::${rawBase}`.toLowerCase());
+        used.add(`controller::${rawBase}`.toLowerCase());
+    }
+    for (const tag of doc.tags) {
+        const key = `${tag.scope}::${tag.name}`.toLowerCase();
+        if (!used.has(key))
+            report('UNUSED_TAG', 'info', `No indexed logic reference to ${tag.scope}::${tag.name}`, { scope: tag.scope, tag: tag.name }, 'low');
+    }
+    const unresolved = new Map();
+    for (const ref of references) {
+        if (ref.resolved !== undefined || ref.access === 'call' || ref.access === 'unknown')
+            continue;
+        const key = `${ref.scope}::${ref.symbol}`;
+        unresolved.set(key, [...unresolved.get(key) ?? [], ref]);
+    }
+    for (const [symbol, locations] of unresolved)
+        report('UNRESOLVED_REFERENCE', 'info', `Symbol ${symbol} could not be resolved in this export`, { occurrences: locations.length, examples: locations.slice(0, 3) }, 'low');
+    const scheduled = new Map();
+    for (const task of doc.tasks)
+        for (const program of task.programs)
+            scheduled.set(program, [...scheduled.get(program) ?? [], task.name]);
+    for (const program of doc.programs) {
+        const tasks = scheduled.get(program.name) ?? [];
+        if (tasks.length === 0)
+            report('UNSCHEDULED_PROGRAM', 'warning', `Program ${program.name} is not scheduled`, { program: program.name });
+        if (tasks.length > 1)
+            report('MULTIPLE_SCHEDULES', 'warning', `Program ${program.name} is scheduled more than once`, { program: program.name, tasks });
+        if (program.description.trim() === '')
+            report('UNDOCUMENTED_PROGRAM', 'info', `Program ${program.name} has no description`, { program: program.name });
+    }
+    for (const routine of doc.routines) {
+        if (routine.description.trim() === '')
+            report('UNDOCUMENTED_ROUTINE', 'info', `Routine ${routine.name} has no description`, { program: routine.program, routine: routine.name });
+        if (routine.body.type === 'RLL') {
+            // One finding per routine, not per rung: a large export otherwise buries
+            // every substantive finding under thousands of documentation rows.
+            const undocumented = routine.body.rungs.filter(rung => (rung.comment ?? '').trim() === '');
+            if (undocumented.length > 0)
+                report('UNDOCUMENTED_RUNG', 'info', `${undocumented.length} rung(s) in ${routine.program}::${routine.name} have no comment`, { program: routine.program, routine: routine.name, count: undocumented.length, rungs: undocumented.slice(0, 20).map(rung => rung.number), truncated: undocumented.length > 20 }, 'high');
+        }
+    }
+    const writers = new Map();
+    for (const ref of references)
+        if (ref.resolved !== undefined && (ref.access === 'write' || ref.access === 'read_write'))
+            writers.set(ref.resolved, [...writers.get(ref.resolved) ?? [], ref]);
+    for (const [symbol, locations] of writers)
+        if (locations.length > 1 && /(?:^|::|\.)[^.]*:(?:O|Output)|_Output|\.O\./iu.test(symbol))
+            report('MULTIPLE_OUTPUT_WRITES', 'warning', `Multiple indexed writes to output-like symbol ${symbol}`, locations, 'medium');
+    if (baseline !== undefined) {
+        const difference = compareProjects(baseline, project);
+        for (const change of difference.changes)
+            if (change.component === 'module')
+                report('IO_MODULE_CHANGED', 'warning', `I/O module ${change.key} ${change.kind}`, change);
+    }
+    const byRule = {};
+    const bySeverity = {};
+    for (const finding of findings) {
+        byRule[finding.rule] = (byRule[finding.rule] ?? 0) + 1;
+        bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
+    }
+    return { project_id: project.id, baseline_id: baseline?.id, findings, count: findings.length, summary: { byRule, bySeverity }, coverage: project.features, note: 'Heuristic findings require engineering review; absence of findings does not prove controller safety.' };
+}

package/vendor/l5x/lib/engine/studio-sdk.d.ts

@@ -0,0 +1,101 @@
+import { type ProjectSnapshot } from '../session.ts';
+import type { LogicSample } from './observations.ts';
+export interface SdkStatus {
+    available: boolean;
+    reason: string;
+    sdk_service_status?: string;
+    activation_service_status?: string;
+    communication_services?: {
+        readonly factorytalk_linx: string;
+        readonly factorytalk_linx_02: string;
+        readonly rslinx_classic: string;
+    };
+    live_communications_available?: boolean;
+    sdk_root: string;
+    client_package?: string;
+    bridge_built: boolean;
+    /** Minimum project revision the SDK can open. */
+    open_supported_project_revisions: '31+';
+    /** Minimum project revision whose Logix Designer engine supports Build. */
+    build_supported_project_revisions: '37+';
+    /** Highest installed Logix Designer release, which is the SDK release axis. */
+    sdk_release: number | null;
+    installed_studio_versions: readonly number[];
+}
+export declare function parseSdkServiceState(output: string): string;
+export declare function hasLiveCommunicationsService(states: readonly string[]): boolean;
+export declare function sdkDiagnosticLines(output: string): string[];
+export declare function studioSdkStatus(): Promise<SdkStatus>;
+/** Export one existing ACD as a new full L5X; this never connects to a controller. */
+export declare function exportAcdToL5x(acdPath: string, outputPath: string, signal?: AbortSignal): Promise<object>;
+export declare function verifyOfflineL5x(project: ProjectSnapshot, outputPath: string, signal?: AbortSignal, options?: {
+    readonly probeBuild?: boolean;
+}): Promise<object>;
+/** Work only on a fresh ACD copy; this bridge command has no controller route. */
+export declare function editOfflineAcd(acdPath: string, draft: ProjectSnapshot, program: string, routine: string, outputPath: string, exportPath: string, signal?: AbortSignal): Promise<{
+    offline_build: string;
+    source_acd_sha256: string;
+    output_path: string | null;
+    output_sha256: string | null;
+    result_export_path: string | null;
+    log: string;
+    partial_output_path: string | null;
+    failure_stage: string | null;
+    import_errors: number | null;
+}>;
+export declare function readControllerMode(project: ProjectSnapshot, commPath: string, signal?: AbortSignal, snapshotPath?: string): Promise<object>;
+/** Read the exported Controller attribute, never an instruction string or a guessed route. */
+export declare function savedL5xCommPath(xml: string): string;
+/** Inspect the path recorded in one project, without browsing drivers or going online. */
+export declare function readProjectCommPath(inputPath: string, signal?: AbortSignal): Promise<object>;
+export declare function rememberControllerRoute(ip: string, projectPath: string, route: string): Promise<void>;
+export declare function inheritControllerRoute(sourcePath: string, targetPath: string): Promise<void>;
+export declare function validateControllerIp(ip: string): string;
+/** A saved Linx route is usable only when its final IP hop is the user's exact target. */
+export declare function validateControllerRoute(ip: string, route: string): string;
+/** Resolve a route from the named project and cache it only while that exact file hash is unchanged. */
+export declare function resolveControllerRoute(ip: string, projectPath: string, signal?: AbortSignal): Promise<string>;
+export type LiveScalarType = 'BOOL' | 'INT' | 'DINT' | 'REAL';
+export interface LiveWatchTag {
+    readonly name: string;
+    readonly data_type: LiveScalarType;
+}
+/** Wire result from the bounded read-only SDK sampler. */
+export interface LiveSamplingResult {
+    snapshot_path: string;
+    snapshot_sha256: string;
+    communications_path: string;
+    requested_interval_ms: number;
+    sample_count: number;
+    tags: readonly LiveWatchTag[];
+    samples: LogicSample[];
+    timing: {
+        average_sweep_ms: number;
+        max_sweep_ms: number;
+        average_observed_interval_ms: number | null;
+    };
+    operation: 'read_only';
+    note: string;
+}
+/** Validate SDK sample wire data, including identity, per-tag type, quality and timestamps.
+ * @param text - JSON emitted by the owned bridge.
+ * @param tags - exact requested watch list.
+ * @returns a validated sweep.
+ */
+export declare function decodeLogicSample(text: string, tags: readonly LiveWatchTag[]): LogicSample;
+export declare function validateLiveSampling(tags: readonly LiveWatchTag[], sampleCount: number, intervalMs: number): void;
+/** Read repeated sweeps through one open SDK project. Actual sweep timing is returned; the requested interval is not guaranteed. */
+export declare function sampleLiveTags(snapshotPath: string, commPath: string, tags: readonly LiveWatchTag[], sampleCount: number, intervalMs: number, signal?: AbortSignal): Promise<LiveSamplingResult>;
+export declare function readLiveTag(snapshotPath: string, commPath: string, tag: string, dataType: LiveScalarType, signal?: AbortSignal): Promise<object>;
+export declare function readLiveDint(snapshotPath: string, commPath: string, tag: string, signal?: AbortSignal): Promise<object>;
+export declare function captureControllerSnapshot(commPath: string, outputPath: string, signal?: AbortSignal): Promise<object>;
+export declare function controllerUploadPreflight(commPath: string, outputPath: string): Promise<string>;
+export interface ControllerActionFile {
+    path: string;
+    sha256: string;
+}
+export declare function controllerActionPreflight(acdPath: string, commPath: string): Promise<ControllerActionFile>;
+export declare function goOnline(acdPath: string, commPath: string, signal?: AbortSignal): Promise<object>;
+export declare function readControllerModeForAction(file: ControllerActionFile, commPath: string, signal?: AbortSignal): Promise<string>;
+export declare function changeControllerMode(file: ControllerActionFile, commPath: string, mode: string, expectedMode: string, signal?: AbortSignal): Promise<object>;
+export declare function downloadProject(file: ControllerActionFile, commPath: string, signal?: AbortSignal): Promise<object>;