@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,173 @@
+/**
+ * Detail readers that the engineering tools need and the legacy byte-compatible
+ * readers must not gain.
+ *
+ * The `l5x_*` tools mirror another server's JSON exactly, so a field added to
+ * `L5xTag` would break that contract. These readers answer from the same parsed
+ * document but are only used by the engineering tools: array dimensions, stored
+ * initial values, alias targets, BIT backing members and the full data-type
+ * table (which includes module-defined `AB:` types that `document.udts` omits).
+ */
+import { controllerElementOf } from "../model/parse.js";
+import { descriptionOf, programElements } from "../model/module.js";
+import { elementChildren, firstChild, nodeText, presentAttribute } from "../model/xml.js";
+/** Scalar types whose L5K data is a single readable literal. */
+const SCALARS = new Set(['BOOL', 'SINT', 'INT', 'DINT', 'LINT', 'USINT', 'UINT', 'UDINT', 'ULINT', 'REAL', 'LREAL']);
+const typeIndexes = new WeakMap();
+/** Every data type the export declares, including module-defined families. */
+export function typeIndex(document) {
+    const cached = typeIndexes.get(document);
+    if (cached !== undefined)
+        return cached;
+    const index = new Map();
+    const dataTypes = firstChild(controllerElementOf(document), 'DataTypes');
+    if (dataTypes !== undefined) {
+        for (const type of elementChildren(dataTypes, 'DataType')) {
+            const name = type.attrs['Name']?.toLowerCase();
+            if (name === undefined || name === '')
+                continue;
+            const members = new Map();
+            const declared = firstChild(type, 'Members');
+            if (declared !== undefined) {
+                for (const member of elementChildren(declared, 'Member')) {
+                    const memberName = member.attrs['Name'];
+                    if (memberName === undefined || memberName === '')
+                        continue;
+                    const bitNumber = member.attrs['BitNumber'] === undefined ? undefined : Number.parseInt(member.attrs['BitNumber'], 10);
+                    const target = presentAttribute(member, 'Target');
+                    members.set(memberName.toLowerCase(), {
+                        name: memberName,
+                        dataType: member.attrs['DataType'] ?? '',
+                        dimension: Number.parseInt(member.attrs['Dimension'] ?? '0', 10) || 0,
+                        ...(bitNumber === undefined || !Number.isFinite(bitNumber) ? {} : { bitNumber }),
+                        ...(target === undefined ? {} : { target }),
+                    });
+                }
+            }
+            index.set(name, members);
+        }
+    }
+    typeIndexes.set(document, index);
+    return index;
+}
+/** One declared type's member table, by case-insensitive name. */
+export function membersOf(document, typeName) {
+    return typeIndex(document).get(typeName.toLowerCase());
+}
+/** One member of a declared type. */
+export function memberOf(document, typeName, memberName) {
+    return membersOf(document, typeName)?.get(memberName.toLowerCase());
+}
+/** Every tag element of the controller or one program, in written order. */
+function tagElements(container) {
+    const tags = firstChild(container, 'Tags');
+    return tags === undefined ? [] : elementChildren(tags, 'Tag');
+}
+/** The exact `<Tag>` element for a scope and name. */
+export function tagElement(document, scope, name) {
+    const controller = controllerElementOf(document);
+    const match = (element) => element.attrs['Name']?.toLowerCase() === name.toLowerCase();
+    if (scope.toLowerCase() === 'controller')
+        return tagElements(controller).find(match);
+    const program = programElements(controller).find(entry => (entry.attrs['Name'] ?? '').toLowerCase() === scope.toLowerCase());
+    return program === undefined ? undefined : tagElements(program).find(match);
+}
+/** Dimensions, stored initial value and alias target of one tag. */
+export function tagDetail(document, tag) {
+    const element = tagElement(document, tag.scope, tag.name);
+    if (element === undefined)
+        return {};
+    const dimensions = presentAttribute(element, 'Dimensions');
+    const aliasFor = presentAttribute(element, 'AliasFor');
+    const detail = {};
+    if (dimensions !== undefined) {
+        detail.dimensions = dimensions;
+        const words = dimensions.split(/\s+/u).reduce((product, part) => product * (Number.parseInt(part, 10) || 1), 1);
+        if (Number.isFinite(words))
+            detail.words = words;
+    }
+    if (aliasFor !== undefined)
+        detail.aliasFor = aliasFor;
+    if (aliasFor === undefined && dimensions === undefined && SCALARS.has(tag.dataType.toUpperCase())) {
+        const data = elementChildren(element, 'Data').find(entry => (entry.attrs['Format'] ?? '').toUpperCase() === 'L5K')
+            ?? elementChildren(element, 'Data')[0];
+        const text = data === undefined ? undefined : nodeText(data);
+        if (text !== undefined)
+            detail.value = text.trim();
+    }
+    return detail;
+}
+/** One UDT's visible members with BIT placement and array length. */
+export function udtDetail(document, name) {
+    const dataTypes = firstChild(controllerElementOf(document), 'DataTypes');
+    if (dataTypes === undefined)
+        return undefined;
+    const type = elementChildren(dataTypes, 'DataType').find(entry => entry.attrs['Name'] === name);
+    if (type === undefined)
+        return undefined;
+    const declared = firstChild(type, 'Members');
+    const members = [];
+    if (declared !== undefined) {
+        for (const member of elementChildren(declared, 'Member')) {
+            if (member.attrs['Hidden'] === 'true')
+                continue;
+            const dimension = Number.parseInt(member.attrs['Dimension'] ?? '0', 10);
+            const description = descriptionOf(member);
+            const radix = presentAttribute(member, 'Radix');
+            const target = presentAttribute(member, 'Target');
+            const bitNumber = member.attrs['BitNumber'] === undefined ? undefined : Number.parseInt(member.attrs['BitNumber'], 10);
+            members.push({
+                name: member.attrs['Name'] ?? '',
+                dataType: member.attrs['DataType'] ?? '',
+                ...(dimension > 0 ? { dimension } : {}),
+                ...(description === '' ? {} : { description }),
+                ...(radix === undefined ? {} : { radix }),
+                ...(target === undefined ? {} : { target }),
+                ...(bitNumber === undefined || !Number.isFinite(bitNumber) ? {} : { bitNumber }),
+            });
+        }
+    }
+    return { name: type.attrs['Name'] ?? name, description: descriptionOf(type), members };
+}
+/** Whether one declared type reaches another through nested members. */
+function reaches(document, from, target, seen) {
+    const key = from.toLowerCase();
+    if (key === target.toLowerCase())
+        return true;
+    if (seen.has(key))
+        return false;
+    seen.add(key);
+    const members = membersOf(document, from);
+    if (members === undefined)
+        return false;
+    for (const member of members.values()) {
+        if (reaches(document, member.dataType, target, seen))
+            return true;
+    }
+    return false;
+}
+/**
+ * Every tag, AOI parameter and AOI local tag whose type tree contains the type.
+ *
+ * A UDT change rewrites the serialized data of every instance, including
+ * instances of types that nest it, so the whole-project change set only accepts
+ * a member change when this list is empty.
+ */
+export function typeInstances(document, typeName) {
+    const instances = [];
+    for (const tag of document.tags) {
+        if (reaches(document, tag.dataType, typeName, new Set()))
+            instances.push(`${tag.scope}::${tag.name}`);
+    }
+    for (const aoi of document.aois) {
+        for (const parameter of aoi.parameters) {
+            if (reaches(document, parameter.dataType, typeName, new Set()))
+                instances.push(`AOI::${aoi.name}.${parameter.name}`);
+        }
+        for (const tag of aoi.localTags) {
+            if (reaches(document, tag.dataType, typeName, new Set()))
+                instances.push(`AOI::${aoi.name}.${tag.name}`);
+        }
+    }
+    return instances;
+}

package/vendor/l5x/lib/engine/direct-polling.d.ts

@@ -0,0 +1,91 @@
+import { type ProjectSnapshot } from '../session.ts';
+import type { LogicSample } from './observations.ts';
+/** Deployment limits for SDK-independent controller reads. */
+export interface PollingConfig {
+    enabled: boolean;
+    minIntervalMs: number;
+    defaultIntervalMs: number;
+    maxTags: number;
+    maxSamples: number;
+    maxDurationMs: number;
+    requestTimeoutMs: number;
+    maxConcurrent: number;
+    allowedAddresses: readonly string[];
+    displayRefreshMs: number;
+    displayMaxSamples: number;
+}
+/** Explicit scalar operand and its project scope. */
+export interface PollTag {
+    name: string;
+    program?: string;
+    data_type: 'BOOL' | 'INT' | 'DINT' | 'REAL';
+}
+/** Resolved request passed to the isolated driver. */
+export interface PollRequest {
+    ip: string;
+    slot: number;
+    tags: PollTag[];
+    samples: number;
+    interval: number;
+    timeout: number;
+}
+/** Complete sampled sweep; bad values remain gaps. */
+export interface PollSample extends LogicSample {
+    index: number;
+    overrun: boolean;
+}
+/** Controller identity is observed over CIP, never inferred from an export. */
+export interface PollIdentity {
+    product_name: string;
+    serial_number: number;
+    revision: string;
+    status: number;
+}
+/** Validated frames retained or forwarded by the owning host. */
+export type PollFrame = {
+    type: 'identity';
+    controller: PollIdentity;
+} | ({
+    type: 'sample';
+} & PollSample);
+/** One worker's lifetime, cancelled only by its owner. */
+export interface PollHandle {
+    cancel(): void;
+    done: Promise<PollFrame[]>;
+}
+/**
+ * Resolve declared scalar tags and bounds before making any network connection.
+ * @param project - Fresh export snapshot.
+ * @param input - Model arguments.
+ * @param config - Resolved deployment limits.
+ * @returns Worker request and source-linked operand evidence.
+ */
+export declare function pollingRequest(project: ProjectSnapshot, input: Readonly<Record<string, unknown>>, config: PollingConfig): {
+    request: PollRequest;
+    evidence: {
+        tag: string;
+        scope: string;
+        references: import("./analysis.ts").Evidence[];
+        reference_completeness: string;
+    }[];
+};
+/** Validate frames crossing the worker boundary. @param value - Worker message. @returns A bounded scalar frame. */
+export declare function decodePollFrame(value: unknown): PollFrame;
+/** Own isolated connections across chats and await worker exit during disposal. */
+export declare class DirectPolling {
+    private readonly workerPath;
+    readonly config: PollingConfig;
+    private readonly active;
+    private disposed;
+    constructor(workerPath: string, config: PollingConfig);
+    /**
+     * Start one bounded read window; repeated sweeps reuse its connection.
+     * @param request - Validated request.
+     * @param onFrame - Synchronous logged-output consumer.
+     * @param signal - Optional foreground lifetime.
+     * @returns Owned cancellation and quiescent completion.
+     */
+    start(request: PollRequest, onFrame: (frame: PollFrame) => void, signal?: AbortSignal): PollHandle;
+    /** Stop only owned workers and await all exits. @returns Quiescent disposal. */
+    dispose(): Promise<void>;
+}

package/vendor/l5x/lib/engine/direct-polling.js

@@ -0,0 +1,193 @@
+/** Read-only EtherNet/IP sampling isolated from Studio SDK and shared host lifetimes. */
+import { Worker } from 'node:worker_threads';
+import { isIPv4 } from 'node:net';
+import { EngineeringError } from "../session.js";
+import { aliasesOf } from "./configuration.js";
+import { findReferences } from "./analysis.js";
+import { controllerElementOf } from "../model/parse.js";
+import { elementChildren, firstChild } from "../model/xml.js";
+/**
+ * Resolve declared scalar tags and bounds before making any network connection.
+ * @param project - Fresh export snapshot.
+ * @param input - Model arguments.
+ * @param config - Resolved deployment limits.
+ * @returns Worker request and source-linked operand evidence.
+ */
+export function pollingRequest(project, input, config) {
+    if (!config.enabled)
+        throw new EngineeringError('DIRECT_POLLING_DISABLED', 'Enable directPollingEnabled to use SDK-independent reads');
+    const ip = input.ip_address;
+    if (typeof ip !== 'string' || !isIPv4(ip) || (config.allowedAddresses.length > 0 && !config.allowedAddresses.includes(ip)))
+        throw new EngineeringError('INVALID_CONTROLLER', 'Select an explicit IPv4 address allowed by this profile');
+    const integer = (key, fallback, min, max) => {
+        const value = input[key] ?? fallback;
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max)
+            throw new EngineeringError('INVALID_POLL', `${key} must be between ${min} and ${max}`);
+        return value;
+    };
+    const slot = integer('slot', 0, 0, 31);
+    const samples = integer('sample_count', 1, 1, config.maxSamples);
+    const interval = integer('interval_ms', config.defaultIntervalMs, config.minIntervalMs, config.maxDurationMs);
+    if ((samples - 1) * interval > config.maxDurationMs)
+        throw new EngineeringError('INVALID_POLL', 'Requested window exceeds directPollingMaxDurationMs');
+    const raw = typeof input.tags_json === 'string' ? JSON.parse(input.tags_json) : null;
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > config.maxTags)
+        throw new EngineeringError('INVALID_POLL', `tags_json must contain 1 through ${config.maxTags} declared scalar tags`);
+    const seen = new Set();
+    const tags = raw.map((entry) => {
+        if (!entry || typeof entry !== 'object' || !('name' in entry) || typeof entry.name !== 'string'
+            || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name) || !Object.keys(entry).every(key => key === 'name' || key === 'scope'))
+            throw new EngineeringError('INVALID_POLL', 'Each tag needs an exact scalar name and optional scope only');
+        const scope = 'scope' in entry ? entry.scope : 'controller';
+        if (typeof scope !== 'string' || (scope !== 'controller' && !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(scope)))
+            throw new EngineeringError('INVALID_POLL', 'scope must be controller or an exact program name');
+        const declared = project.document.tags.find(tag => tag.name === entry.name && tag.scope === scope);
+        const controller = controllerElementOf(project.document);
+        const programs = firstChild(controller, 'Programs');
+        const container = scope === 'controller' ? controller : programs === undefined ? undefined
+            : elementChildren(programs, 'Program').find(program => program.attrs.Name === scope);
+        const tagContainer = container === undefined ? undefined : firstChild(container, 'Tags');
+        const declaration = tagContainer === undefined ? undefined : elementChildren(tagContainer, 'Tag').find(tag => tag.attrs.Name === entry.name);
+        const dimensions = declaration?.attrs.Dimensions ?? declaration?.attrs.Dimension ?? '';
+        if (!declared || aliasesOf(project.document).has(`${scope}::${declared.name}`)
+            || !['BOOL', 'INT', 'DINT', 'REAL'].includes(declared.dataType)
+            || dimensions !== '' && dimensions !== '0' || declaration?.attrs.ExternalAccess === 'None')
+            throw new EngineeringError('UNSUPPORTED_POLL_TAG', 'Select a declared non-alias scalar BOOL, INT, DINT, or REAL');
+        const key = `${scope}::${declared.name}`.toLowerCase();
+        if (seen.has(key))
+            throw new EngineeringError('INVALID_POLL', 'Duplicate watch tag');
+        seen.add(key);
+        return { name: declared.name, ...(scope === 'controller' ? {} : { program: scope }), data_type: declared.dataType };
+    });
+    const request = { ip, slot, tags, samples, interval, timeout: config.requestTimeoutMs };
+    return { request, evidence: tags.map(tag => ({ tag: tag.name, scope: tag.program ?? 'controller',
+            references: findReferences(project, tag.name).filter(reference => reference.resolved?.toLowerCase() === `${tag.program ?? 'controller'}::${tag.name}`.toLowerCase()),
+            reference_completeness: 'static_partial' })) };
+}
+/** Validate frames crossing the worker boundary. @param value - Worker message. @returns A bounded scalar frame. */
+export function decodePollFrame(value) {
+    if (!value || typeof value !== 'object' || !('type' in value))
+        throw new Error('Invalid polling frame');
+    if (value.type === 'failure' && 'message' in value && typeof value.message === 'string')
+        throw new Error(value.message);
+    if (value.type === 'identity' && 'controller' in value) {
+        const controller = value.controller;
+        if (controller && typeof controller === 'object' && 'product_name' in controller && typeof controller.product_name === 'string'
+            && 'serial_number' in controller && typeof controller.serial_number === 'number' && Number.isInteger(controller.serial_number)
+            && 'revision' in controller && typeof controller.revision === 'string' && 'status' in controller && typeof controller.status === 'number')
+            return { type: 'identity', controller: { product_name: controller.product_name, serial_number: controller.serial_number, revision: controller.revision, status: controller.status } };
+    }
+    if (value.type === 'sample' && 'index' in value && 'elapsed_ms' in value && 'sweep_ms' in value && 'overrun' in value && 'values' in value
+        && typeof value.index === 'number' && Number.isInteger(value.index) && value.index >= 0
+        && typeof value.elapsed_ms === 'number' && Number.isFinite(value.elapsed_ms) && value.elapsed_ms >= 0
+        && typeof value.sweep_ms === 'number' && Number.isFinite(value.sweep_ms) && value.sweep_ms >= 0
+        && typeof value.overrun === 'boolean' && Array.isArray(value.values) && value.values.length <= 256) {
+        const values = value.values.map((item) => {
+            if (!item || typeof item !== 'object' || !('tag' in item) || typeof item.tag !== 'string' || !('value' in item)
+                || !(item.value === null || typeof item.value === 'boolean' || typeof item.value === 'number' && Number.isFinite(item.value))
+                || !('quality' in item) || !['good', 'bad'].includes(String(item.quality))
+                || !('observed_at' in item) || typeof item.observed_at !== 'string' || !Number.isFinite(Date.parse(item.observed_at)))
+                throw new Error('Invalid polling value');
+            return { tag: item.tag, value: item.value, quality: String(item.quality), observed_at: item.observed_at,
+                ...('error' in item && typeof item.error === 'string' ? { error: item.error.slice(0, 1000) } : {}) };
+        });
+        return { type: 'sample', index: value.index, elapsed_ms: value.elapsed_ms, sweep_ms: value.sweep_ms, overrun: value.overrun, values };
+    }
+    throw new Error('Invalid polling frame');
+}
+/** Own isolated connections across chats and await worker exit during disposal. */
+export class DirectPolling {
+    workerPath;
+    config;
+    active = new Map();
+    disposed = false;
+    constructor(workerPath, config) {
+        this.workerPath = workerPath;
+        this.config = config;
+        if (config.minIntervalMs > config.defaultIntervalMs || config.defaultIntervalMs > config.maxDurationMs
+            || config.allowedAddresses.some(address => !isIPv4(address)))
+            throw new Error('Invalid direct polling interval or IPv4 allowlist');
+    }
+    /**
+     * Start one bounded read window; repeated sweeps reuse its connection.
+     * @param request - Validated request.
+     * @param onFrame - Synchronous logged-output consumer.
+     * @param signal - Optional foreground lifetime.
+     * @returns Owned cancellation and quiescent completion.
+     */
+    start(request, onFrame, signal) {
+        const key = `${request.ip}:${request.slot}`;
+        if (this.disposed || this.active.has(key) || this.active.size >= this.config.maxConcurrent)
+            throw new EngineeringError('POLL_BUSY', 'Controller polling capacity is occupied or the plugin is stopping');
+        signal?.throwIfAborted();
+        const worker = new Worker(this.workerPath, { workerData: request, env: {}, stdout: true, stderr: true });
+        // Only structured frames enter tool/job output; drain private driver diagnostics.
+        worker.stdout.resume();
+        worker.stderr.resume();
+        const frames = [];
+        let identified = false;
+        let sampleIndex = 0;
+        let lastElapsed = -1;
+        let failure;
+        const cancel = () => { failure ??= new EngineeringError('POLL_CANCELLED', 'Polling was cancelled'); void worker.terminate(); };
+        const timer = setTimeout(() => { failure = new EngineeringError('POLL_TIMEOUT', 'Polling exceeded its configured deadline'); void worker.terminate(); }, this.config.maxDurationMs + this.config.requestTimeoutMs);
+        const connecting = setTimeout(() => { failure = new EngineeringError('POLL_TIMEOUT', 'Controller connection exceeded its configured deadline'); void worker.terminate(); }, this.config.requestTimeoutMs);
+        signal?.addEventListener('abort', cancel, { once: true });
+        const done = new Promise((resolve, reject) => {
+            worker.on('message', (message) => {
+                if (failure)
+                    return;
+                try {
+                    const frame = decodePollFrame(message);
+                    if (frame.type === 'identity') {
+                        if (identified || frames.length !== 0)
+                            throw new Error('Unexpected controller identity frame');
+                        identified = true;
+                        clearTimeout(connecting);
+                    }
+                    else {
+                        if (!identified || frame.index !== sampleIndex || frame.elapsed_ms < lastElapsed || frame.values.length !== request.tags.length
+                            || frame.values.some((value, index) => value.tag !== (request.tags[index].program ? `Program:${request.tags[index].program}.${request.tags[index].name}` : request.tags[index].name)))
+                            throw new Error('Polling samples do not match the requested watch');
+                        sampleIndex++;
+                        lastElapsed = frame.elapsed_ms;
+                    }
+                    if (frames.length >= request.samples + 1)
+                        throw new Error('Polling frame limit exceeded');
+                    frames.push(frame);
+                    onFrame(frame);
+                }
+                catch (error) {
+                    failure = error instanceof Error ? error : new Error('Polling frame failed');
+                    void worker.terminate();
+                }
+            });
+            worker.once('error', error => { failure = error; });
+            worker.once('exit', code => {
+                clearTimeout(timer);
+                clearTimeout(connecting);
+                signal?.removeEventListener('abort', cancel);
+                this.active.delete(key);
+                if (failure)
+                    reject(failure);
+                else if (code !== 0 || frames.filter(frame => frame.type === 'sample').length !== request.samples)
+                    reject(new Error('Polling ended without all requested samples'));
+                else
+                    resolve(frames);
+            });
+        });
+        const handle = { cancel, done };
+        this.active.set(key, handle);
+        // A just-returned background handle may be collected on a later turn.
+        void done.catch(() => { });
+        return handle;
+    }
+    /** Stop only owned workers and await all exits. @returns Quiescent disposal. */
+    async dispose() {
+        this.disposed = true;
+        const handles = [...this.active.values()];
+        for (const handle of handles)
+            handle.cancel();
+        await Promise.allSettled(handles.map(handle => handle.done));
+    }
+}

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

@@ -0,0 +1,15 @@
+import { type Change } from './review.ts';
+import { type ProjectSnapshot } from '../session.ts';
+export interface DownloadReview {
+    readonly baseline_sha256: string;
+    readonly source_sha256: string;
+    readonly controller: string;
+    readonly processor_type: string;
+    readonly change_count: number;
+    readonly changes: readonly Change[];
+    readonly safety_changed: boolean;
+    readonly eligible: boolean;
+    readonly blockers: readonly string[];
+}
+/** This review is a release gate, not a claim that the machine is safe to run. */
+export declare function reviewDownloadSource(baseline: ProjectSnapshot, source: ProjectSnapshot): DownloadReview;

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

@@ -0,0 +1,63 @@
+import { compareProjects } from "./review.js";
+import { EngineeringError } from "../session.js";
+function safetyPrograms(project) {
+    const names = new Set(project.document.programs.filter(program => /safety/iu.test(program.name)).map(program => program.name));
+    for (const task of project.document.tasks) {
+        if (/safety/iu.test(task.name))
+            for (const name of task.programs)
+                names.add(name);
+    }
+    for (const match of project.xml.matchAll(/<Program\b([^>]*)>/gu)) {
+        if (!/\bClass=["']Safety["']/iu.test(match[1] ?? ''))
+            continue;
+        const name = /\bName=["']([^"']+)["']/u.exec(match[1] ?? '')?.[1];
+        if (name !== undefined)
+            names.add(name);
+    }
+    return [...names].sort();
+}
+function safetyState(project) {
+    const programs = safetyPrograms(project);
+    const safetyInfo = /<SafetyInfo\b[\s\S]*?(?:\/>|<\/SafetyInfo>)/u.exec(project.xml)?.[0] ?? '';
+    const safetyTags = [...project.xml.matchAll(/<Tag\b[^>]*(?:\bClass=["']Safety["']|\bSafety=["']true["'])[^>]*(?:\/>|>[\s\S]*?<\/Tag>)/giu)].map(match => match[0]);
+    const safetyMappings = [...project.xml.matchAll(/<SafetyTagMap(?:ping)?\b[\s\S]*?(?:\/>|<\/SafetyTagMap(?:ping)?>)/giu)].map(match => match[0]);
+    return JSON.stringify({
+        safetyInfo,
+        safetyTags,
+        safetyMappings,
+        programs,
+        tasks: project.document.tasks.filter(task => /safety/iu.test(task.name) || task.programs.some(name => programs.includes(name))),
+        definitions: project.document.programs.filter(program => programs.includes(program.name)),
+        routines: project.document.routines.filter(routine => programs.includes(routine.program)),
+        tags: project.document.tags.filter(tag => programs.includes(tag.scope)),
+    });
+}
+function encodedDefinitions(project) {
+    return [...project.xml.matchAll(/<EncodedData\b[\s\S]*?<\/EncodedData>|<EncodedData\b[^>]*\/>/gu)].map(match => match[0]);
+}
+/** This review is a release gate, not a claim that the machine is safe to run. */
+export function reviewDownloadSource(baseline, source) {
+    if (baseline.exportKind !== 'controller' || source.exportKind !== 'controller')
+        throw new EngineeringError('CONTROLLER_EXPORT_REQUIRED', 'Both baseline and source must be full controller exports');
+    const differences = compareProjects(baseline, source);
+    const safetyChanged = safetyState(baseline) !== safetyState(source);
+    const blockers = [];
+    if (baseline.document.controller.name !== source.document.controller.name || baseline.document.controller.processorType !== source.document.controller.processorType)
+        blockers.push('Controller identity or processor type differs from baseline');
+    if (baseline.softwareRevision !== source.softwareRevision)
+        blockers.push('Studio project revision differs from baseline');
+    if (differences.changes.length === 0)
+        blockers.push('No engineering change was found relative to baseline; refusing an unchanged backup download');
+    if (safetyChanged)
+        blockers.push('Safety task, program, routine, tag, or safety metadata differs; use Studio 5000 safety review');
+    if (differences.changes.some(change => change.component === 'module'))
+        blockers.push('I/O module configuration differs from baseline; review in Studio 5000');
+    if (JSON.stringify(encodedDefinitions(baseline)) !== JSON.stringify(encodedDefinitions(source)))
+        blockers.push('Encoded or source-protected definition changed');
+    return {
+        baseline_sha256: baseline.sha256, source_sha256: source.sha256,
+        controller: source.document.controller.name, processor_type: source.document.controller.processorType,
+        change_count: differences.changes.length, changes: differences.changes,
+        safety_changed: safetyChanged, eligible: blockers.length === 0, blockers,
+    };
+}

package/vendor/l5x/lib/engine/logic-syntax.d.ts

@@ -0,0 +1,60 @@
+/** Source-positioned Logix tokens and NeutralText structure for static analysis. */
+/** Offsets refer to UTF-16 positions in the original source, with an exclusive end. */
+export interface LogicToken {
+    readonly kind: 'identifier' | 'number' | 'string' | 'punctuation';
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+    readonly line: number;
+}
+/** An unsupported or malformed source region; partial analysis retains its location. */
+export interface SyntaxIssue {
+    readonly offset: number;
+    readonly message: string;
+}
+/** A ladder instruction or parallel branch retains its exact source extent. */
+export type LadderNode = {
+    readonly kind: 'instruction';
+    readonly name: string;
+    readonly operands: readonly (readonly LogicToken[])[];
+    readonly start: number;
+    readonly end: number;
+} | {
+    readonly kind: 'branch';
+    readonly paths: readonly (readonly LadderNode[])[];
+    readonly start: number;
+    readonly end: number;
+};
+/** Tokenize Logix source without treating comments or quoted literals as symbols.
+ * @param source - Original routine or rung text.
+ * @returns Source tokens and lexical issues; newlines in comments and literals retain their positions.
+ */
+export declare function lexLogic(source: string): {
+    tokens: readonly LogicToken[];
+    issues: readonly SyntaxIssue[];
+};
+/** Parse standard NeutralText instructions and nested parallel branches.
+ * @param source - One complete rung, including its terminator.
+ * @returns Parsed nodes and located issues; malformed structure is never silently complete.
+ */
+export declare function parseLadder(source: string): {
+    nodes: readonly LadderNode[];
+    issues: readonly SyntaxIssue[];
+};
+/** One address token sequence, including indices and its source occurrence. */
+export interface AddressOccurrence {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+    readonly line: number;
+    readonly indexTokens: readonly LogicToken[];
+}
+/** Read an identifier with optional program qualification, member paths and indices.
+ * @param tokens - Source-positioned tokens.
+ * @param offset - Index of the address's first identifier.
+ * @returns The address and next token index, or undefined for malformed indices.
+ */
+export declare function addressAt(tokens: readonly LogicToken[], offset: number): {
+    address: AddressOccurrence;
+    next: number;
+} | undefined;