@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/l5x/lib/core/params.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Parameter schemas that always describe themselves.
+ *
+ * The port's first measured failure was 132 parameters with no description.
+ * These helpers make an undescribed parameter impossible to write: the
+ * description is a required argument, not an optional field.
+ *
+ * @module dsh-engineering-l5x/core/params
+ */
+/** One JSON Schema property, with the description that is mandatory here. */
+export interface ParameterSchema {
+    readonly type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    readonly description: string;
+    readonly enum?: readonly string[];
+    readonly items?: ParameterSchema;
+    readonly default?: unknown;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly properties?: Readonly<Record<string, ParameterSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+/** A string parameter. */
+export declare function string(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
+/** An integer parameter with an optional range. */
+export declare function integer(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
+/** A string parameter restricted to a known set. */
+export declare function choice(description: string, values: readonly string[], extra?: Partial<ParameterSchema>): ParameterSchema;
+/** An array of one parameter type. */
+export declare function list(description: string, items: ParameterSchema, extra?: Partial<ParameterSchema>): ParameterSchema;
+/** One object element of an array parameter. */
+export declare function objectItem(description: string, properties: Readonly<Record<string, ParameterSchema>>, required?: readonly string[]): ParameterSchema;
+/** The `parameters` object of one tool. */
+export interface Parameters {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ParameterSchema>>;
+    readonly required: readonly string[];
+    readonly additionalProperties: false;
+}
+/**
+ * Build a tool's parameter object.
+ *
+ * @param properties - Named parameters, every one already described.
+ * @param required - Names the caller must supply.
+ * @returns The schema object a tool definition declares.
+ */
+export declare function object(properties: Readonly<Record<string, ParameterSchema>>, required?: readonly string[]): Parameters;

package/vendor/l5x/lib/core/params.js

@@ -0,0 +1,39 @@
+/**
+ * Parameter schemas that always describe themselves.
+ *
+ * The port's first measured failure was 132 parameters with no description.
+ * These helpers make an undescribed parameter impossible to write: the
+ * description is a required argument, not an optional field.
+ *
+ * @module dsh-engineering-l5x/core/params
+ */
+/** A string parameter. */
+export function string(description, extra = {}) {
+    return { type: 'string', description, ...extra };
+}
+/** An integer parameter with an optional range. */
+export function integer(description, extra = {}) {
+    return { type: 'integer', description, ...extra };
+}
+/** A string parameter restricted to a known set. */
+export function choice(description, values, extra = {}) {
+    return { type: 'string', description, enum: values, ...extra };
+}
+/** An array of one parameter type. */
+export function list(description, items, extra = {}) {
+    return { type: 'array', description, items, ...extra };
+}
+/** One object element of an array parameter. */
+export function objectItem(description, properties, required = []) {
+    return { type: 'object', description, properties, required, additionalProperties: false };
+}
+/**
+ * Build a tool's parameter object.
+ *
+ * @param properties - Named parameters, every one already described.
+ * @param required - Names the caller must supply.
+ * @returns The schema object a tool definition declares.
+ */
+export function object(properties, required = []) {
+    return { type: 'object', properties, required, additionalProperties: false };
+}

package/vendor/l5x/lib/core/result.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The model-facing success document.
+ *
+ * Every read answers with a summary first and concrete next calls last. The
+ * summary lets a small model decide whether it got what it asked for without
+ * reading the whole payload; `next` is the recovery path when its plan is thin.
+ *
+ * @module dsh-engineering-l5x/core/result
+ */
+/** One call the reader can make next, with the reason it is useful. */
+export interface NextStep {
+    /** Tool name registered by this plugin. */
+    readonly tool: string;
+    /** Why this call answers the current question. */
+    readonly why: string;
+    /** Arguments worth passing; omitted when the tool needs none. */
+    readonly args?: Readonly<Record<string, unknown>>;
+}
+/** How much of the requested question the answer actually covers. */
+export interface Coverage {
+    /** Whether the requested scope was answered in full. */
+    readonly complete: boolean;
+    /** What this answer cannot establish, named rather than implied. */
+    readonly unverified: readonly string[];
+}
+/** A successful tool answer. */
+export interface Success<T> {
+    /** One sentence the reader can act on. */
+    readonly summary: string;
+    /** Tool-specific payload. */
+    readonly data: T;
+    /** Present when the answer has limits worth stating. */
+    readonly coverage?: Coverage;
+    /** Concrete next calls, most useful first. */
+    readonly next: readonly NextStep[];
+}
+/**
+ * Build a success document.
+ *
+ * @param summary - One sentence naming what was read.
+ * @param data - Tool-specific payload.
+ * @param next - Concrete next calls; may be empty when the answer is terminal.
+ * @param coverage - Limits of the answer, when it has any.
+ * @returns The document the tool returns.
+ */
+export declare function success<T>(summary: string, data: T, next?: readonly NextStep[], coverage?: Coverage): Success<T>;

package/vendor/l5x/lib/core/result.js

@@ -0,0 +1,21 @@
+/**
+ * The model-facing success document.
+ *
+ * Every read answers with a summary first and concrete next calls last. The
+ * summary lets a small model decide whether it got what it asked for without
+ * reading the whole payload; `next` is the recovery path when its plan is thin.
+ *
+ * @module dsh-engineering-l5x/core/result
+ */
+/**
+ * Build a success document.
+ *
+ * @param summary - One sentence naming what was read.
+ * @param data - Tool-specific payload.
+ * @param next - Concrete next calls; may be empty when the answer is terminal.
+ * @param coverage - Limits of the answer, when it has any.
+ * @returns The document the tool returns.
+ */
+export function success(summary, data, next = [], coverage) {
+    return coverage === undefined ? { summary, data, next } : { summary, data, coverage, next };
+}

package/vendor/l5x/lib/core/tool.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The tool and service surfaces this package registers against.
+ *
+ * Declared locally, and structurally, so the package compiles without the host
+ * packages at build time while still matching what the Cordis registry and the
+ * filesystem provider expose at runtime.
+ *
+ * @module dsh-engineering-l5x/core/tool
+ */
+import type { Parameters } from './params.ts';
+/** One content block the registry renders for the model. */
+export interface TextBlock {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** The canonical output declaration every tool must carry. */
+export interface ToolOutput {
+    readonly schema: {
+        readonly type: 'object';
+        readonly additionalProperties: boolean;
+    };
+    render(args: unknown, value: unknown): readonly TextBlock[];
+}
+/** The execution context a tool receives from the registry. */
+export interface ToolExec {
+    readonly signal?: AbortSignal;
+    readonly callId?: unknown;
+    readonly sessionId?: string;
+    readonly agent?: {
+        readonly session?: {
+            readonly header?: {
+                readonly cwd?: string;
+            };
+        };
+    };
+}
+/** The context a tool body receives: cancellation, workspace, chat identity and approval fields. */
+export interface ExecContext {
+    readonly signal?: AbortSignal;
+    readonly cwd?: string;
+    /** The calling chat; handles are scoped to it. */
+    readonly chat?: object;
+    /** Registry call id, forwarded to the approval request. */
+    readonly callId?: unknown;
+    /** Owning session id, used by session-owned jobs. */
+    readonly sessionId?: string;
+    /** The calling agent, forwarded to the approval request. */
+    readonly agent?: unknown;
+}
+/** A registered tool. */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Parameters;
+    readonly output: ToolOutput;
+    execute(args: Readonly<Record<string, unknown>>, exec: ToolExec): Promise<unknown>;
+}
+/** The registry service. */
+export interface ToolRegistry {
+    register(definition: ToolDefinition): unknown;
+}
+/** A path resolved by the filesystem provider into its backend identity. */
+export interface FsTarget {
+    /** Opaque key for stale guards and target lookup. */
+    readonly targetKey: unknown;
+    /** Path for model- and UI-facing output. */
+    readonly displayPath: string;
+}
+/** The filesystem service operations this package uses. */
+export interface FsService {
+    resolve(path: string, options?: {
+        readonly signal?: AbortSignal;
+        readonly cwd?: string;
+    }): Promise<FsTarget>;
+    stat(target: FsTarget, signal?: AbortSignal): Promise<{
+        readonly type: string;
+    } | undefined>;
+    readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes?: number): Promise<Uint8Array>;
+    writeText?(target: FsTarget, text: string, options?: {
+        readonly kind?: 'createIfAbsent';
+    }, signal?: AbortSignal): Promise<void>;
+}
+/** The services a composition must provide before this plugin loads. */
+export interface PluginContext {
+    readonly tools: ToolRegistry;
+    readonly fs: FsService;
+    readonly logger?: {
+        warn(message: string): void;
+    };
+    /** Register a service other entries in the same composition can consume. */
+    provide?(name: string, value: unknown): void;
+    /** Read a service another entry in the same composition provided. */
+    get?(name: string): unknown;
+}
+/**
+ * Render one tool answer as pretty JSON.
+ *
+ * @param _args - Accepted arguments; unused by this renderer.
+ * @param value - The validated canonical value.
+ * @returns One text block.
+ */
+export declare function jsonText(_args: unknown, value: unknown): readonly TextBlock[];

package/vendor/l5x/lib/core/tool.js

@@ -0,0 +1,19 @@
+/**
+ * The tool and service surfaces this package registers against.
+ *
+ * Declared locally, and structurally, so the package compiles without the host
+ * packages at build time while still matching what the Cordis registry and the
+ * filesystem provider expose at runtime.
+ *
+ * @module dsh-engineering-l5x/core/tool
+ */
+/**
+ * Render one tool answer as pretty JSON.
+ *
+ * @param _args - Accepted arguments; unused by this renderer.
+ * @param value - The validated canonical value.
+ * @returns One text block.
+ */
+export function jsonText(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value, undefined, 2) }];
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Drafts: one accumulated edit list per project per chat.
+ *
+ * The model adds one operation at a time, sees the count grow, then validates
+ * and applies. Nothing here writes a file; preparation and application belong
+ * to the tools, so an abandoned draft leaves no residue.
+ *
+ * @module dsh-engineering-l5x/drafts
+ */
+import type { ExecContext } from './core/tool.ts';
+/** One version-1 change-set operation, as the engine accepts it. */
+export interface DraftOperation {
+    readonly operation: string;
+    readonly [field: string]: unknown;
+}
+/** One accumulated draft. */
+export interface Draft {
+    /** Stable handle returned to the caller. */
+    readonly id: string;
+    /** Project handle this draft applies to. */
+    readonly projectId: string;
+    /** Operations in the order they were added. */
+    readonly operations: readonly DraftOperation[];
+    /** ISO timestamp of the first operation. */
+    readonly createdAt: string;
+}
+/** Drafts, scoped to the chat that created them. */
+export declare class DraftStore {
+    private readonly chats;
+    private readonly detached;
+    /**
+     * The draft for one project in this chat, created on first use.
+     *
+     * @param exec - Calling context; its chat selects the draft set.
+     * @param projectId - Project handle the draft edits.
+     * @returns The accumulated draft.
+     */
+    forProject(exec: ExecContext | undefined, projectId: string): Draft;
+    /**
+     * Append one operation to a project's draft.
+     *
+     * @param exec - Calling context.
+     * @param projectId - Project handle the draft edits.
+     * @param operation - Operation to append.
+     * @param maxOperations - Inclusive operation cap for one draft.
+     * @returns The updated draft.
+     */
+    append(exec: ExecContext | undefined, projectId: string, operation: DraftOperation, maxOperations: number): Draft;
+    /**
+     * Resolve one draft by handle.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle; empty selects the chat's only draft.
+     * @returns The draft.
+     */
+    get(exec: ExecContext | undefined, id: string | undefined): Draft;
+    /**
+     * Remove one draft after it is applied.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle.
+     */
+    remove(exec: ExecContext | undefined, id: string): void;
+    /** The draft map for one calling chat. */
+    private chatsOf;
+}

package/vendor/l5x/lib/drafts.js

@@ -0,0 +1,98 @@
+/**
+ * Drafts: one accumulated edit list per project per chat.
+ *
+ * The model adds one operation at a time, sees the count grow, then validates
+ * and applies. Nothing here writes a file; preparation and application belong
+ * to the tools, so an abandoned draft leaves no residue.
+ *
+ * @module dsh-engineering-l5x/drafts
+ */
+import { randomUUID } from 'node:crypto';
+import { L5xError } from "./core/errors.js";
+/** Drafts, scoped to the chat that created them. */
+export class DraftStore {
+    chats = new WeakMap();
+    detached = new Map();
+    /**
+     * The draft for one project in this chat, created on first use.
+     *
+     * @param exec - Calling context; its chat selects the draft set.
+     * @param projectId - Project handle the draft edits.
+     * @returns The accumulated draft.
+     */
+    forProject(exec, projectId) {
+        const drafts = this.chatsOf(exec);
+        for (const draft of drafts.values()) {
+            if (draft.projectId === projectId)
+                return draft;
+        }
+        const created = { id: randomUUID(), projectId, operations: [], createdAt: new Date().toISOString() };
+        drafts.set(created.id, created);
+        return created;
+    }
+    /**
+     * Append one operation to a project's draft.
+     *
+     * @param exec - Calling context.
+     * @param projectId - Project handle the draft edits.
+     * @param operation - Operation to append.
+     * @param maxOperations - Inclusive operation cap for one draft.
+     * @returns The updated draft.
+     */
+    append(exec, projectId, operation, maxOperations) {
+        const current = this.forProject(exec, projectId);
+        if (current.operations.length >= maxOperations) {
+            throw new L5xError('DRAFT_TOO_LARGE', `This draft already holds ${current.operations.length} operations, the configured maximum.`, 'Validate and apply this draft, then start another for the remaining edits.');
+        }
+        const updated = { ...current, operations: [...current.operations, operation] };
+        this.chatsOf(exec).set(updated.id, updated);
+        return updated;
+    }
+    /**
+     * Resolve one draft by handle.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle; empty selects the chat's only draft.
+     * @returns The draft.
+     */
+    get(exec, id) {
+        const drafts = this.chatsOf(exec);
+        const ids = [...drafts.keys()];
+        if (id === undefined || id === '') {
+            const only = ids[0];
+            if (only === undefined) {
+                throw new L5xError('NO_DRAFT', 'No draft exists in this chat.', 'Add an operation with a draft_* tool first.');
+            }
+            if (ids.length > 1) {
+                throw new L5xError('AMBIGUOUS_DRAFT', `${ids.length} drafts exist in this chat, so draft_id is required.`, `Pass one of: ${ids.join(', ')}.`, ids);
+            }
+            return drafts.get(only);
+        }
+        const draft = drafts.get(id);
+        if (draft === undefined) {
+            throw new L5xError('UNKNOWN_DRAFT', `No draft exists with draft_id ${JSON.stringify(id)} in this chat.`, ids.length === 0 ? 'Add an operation with a draft_* tool first.' : `Pass one of this chat's draft ids: ${ids.join(', ')}.`, ids);
+        }
+        return draft;
+    }
+    /**
+     * Remove one draft after it is applied.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle.
+     */
+    remove(exec, id) {
+        this.chatsOf(exec).delete(id);
+    }
+    /** The draft map for one calling chat. */
+    chatsOf(exec) {
+        const chat = exec?.chat;
+        if (chat === undefined)
+            return this.detached;
+        const existing = this.chats.get(chat);
+        if (existing !== undefined)
+            return existing;
+        const created = new Map();
+        this.chats.set(chat, created);
+        return created;
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The L5X editing entry: drafts over the read entry's project handles.
+ *
+ * Kept separate so a profile that only reads, checks and compares does not pay
+ * for nine draft schemas. It consumes the `l5xProjects` service the read entry
+ * provides, so a project is opened once and both entries see the same handle.
+ *
+ * @module dsh-engineering-l5x/editing
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "l5x-editing";
+/** The read entry's project service must already be mounted. */
+export declare const inject: readonly ["tools", "l5xProjects"];
+/** Configuration for the editing entry. */
+export interface Config {
+    /** Largest export, in bytes, one preparation may read. Defaults to 64 MiB. */
+    maxFileBytes?: number;
+    /** Most operations one draft may accumulate. Defaults to 200. */
+    maxDraftOperations?: number;
+}
+/**
+ * Register the draft tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export declare function apply(ctx: PluginContext, config?: Config): void;
+export { DraftStore } from './drafts.ts';
+export { draftTools } from './tools/drafts.ts';

package/vendor/l5x/lib/editing.js

@@ -0,0 +1,42 @@
+/**
+ * The L5X editing entry: drafts over the read entry's project handles.
+ *
+ * Kept separate so a profile that only reads, checks and compares does not pay
+ * for nine draft schemas. It consumes the `l5xProjects` service the read entry
+ * provides, so a project is opened once and both entries see the same handle.
+ *
+ * @module dsh-engineering-l5x/editing
+ */
+import { DraftStore } from "./drafts.js";
+import { draftTools } from "./tools/drafts.js";
+import { PROJECTS_SERVICE } from "./index.js";
+/** Plugin name in a composition. */
+export const name = 'l5x-editing';
+/** The read entry's project service must already be mounted. */
+export const inject = ['tools', PROJECTS_SERVICE];
+/**
+ * Register the draft tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export function apply(ctx, config = {}) {
+    const session = ctx.get?.(PROJECTS_SERVICE);
+    if (session === undefined) {
+        throw new Error('l5x-editing: the l5xProjects service is unavailable; mount the L5X read entry before this one');
+    }
+    const maxFileBytes = config.maxFileBytes ?? 64 * 1024 * 1024;
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes <= 0) {
+        throw new Error('l5x-editing: maxFileBytes must be a positive integer');
+    }
+    const maxDraftOperations = config.maxDraftOperations ?? 200;
+    if (!Number.isInteger(maxDraftOperations) || maxDraftOperations <= 0) {
+        throw new Error('l5x-editing: maxDraftOperations must be a positive integer');
+    }
+    const drafts = new DraftStore();
+    for (const definition of draftTools(session, drafts, maxDraftOperations, maxFileBytes)) {
+        ctx.tools.register(definition);
+    }
+}
+export { DraftStore } from "./drafts.js";
+export { draftTools } from "./tools/drafts.js";

package/vendor/l5x/lib/engine/acd-edit.d.ts

@@ -0,0 +1,13 @@
+import { type ProjectSnapshot } from '../session.ts';
+export declare function controllerContent(project: ProjectSnapshot, ignoreModifiedDate?: boolean, ignoreEncodedPayload?: boolean): string;
+/** Validate one edited routine component for review in the user's IDE.
+ * @param baseline - original routine export from Studio.
+ * @param draft - unchanged-on-disk proposal derived from that export.
+ * @param program - intended containing program.
+ * @param routine - intended existing routine.
+ * @returns import target and source identity; no Studio import or controller operation occurs.
+ */
+export declare function studioRoutineImportPlan(baseline: ProjectSnapshot, draft: ProjectSnapshot, program: string, routine: string): object;
+export declare function routineEditPlan(baseline: ProjectSnapshot, draft: ProjectSnapshot, program: string, routine: string): {
+    xpath: string;
+};

package/vendor/l5x/lib/engine/acd-edit.js

@@ -0,0 +1,115 @@
+import { documentRoot, elementChildren, firstChild, parseXml } from "../model/xml.js";
+import { EngineeringError } from "../session.js";
+import { reviewDownloadSource } from "./download-review.js";
+function controller(project) {
+    const node = firstChild(documentRoot(parseXml(project.xml)), 'Controller');
+    if (project.exportKind !== 'controller' || node === undefined)
+        throw new EngineeringError('CONTROLLER_EXPORT_REQUIRED', 'A full controller export is required');
+    return node;
+}
+function named(parent, kind, name) {
+    const matches = parent === undefined ? [] : elementChildren(parent, kind).filter(node => node.attrs.Name === name);
+    if (matches.length !== 1)
+        throw new EngineeringError('AMBIGUOUS_TARGET', `Expected one ${kind} named ${name}`);
+    return matches[0];
+}
+/** Compare every controller XML structure, including fields not modeled by the index. */
+function canonical(node, omit, ignoreModifiedDate = false, ignoreEncodedPayload = false) {
+    if (node === omit)
+        return '#target-routine';
+    if (!('children' in node))
+        return node.name === '#comment' || node.text.trim() === '' ? null : ['text', node.text];
+    const attrs = Object.entries(node.attrs).filter(([key]) => !(ignoreModifiedDate && node.name === 'Controller' && key === 'LastModifiedDate'));
+    const children = node.children.filter(child => !(ignoreEncodedPayload && node.name === 'EncodedData' && !('children' in child)));
+    return [node.name, attrs.sort(([a], [b]) => a.localeCompare(b)), children.map(child => canonical(child, omit, ignoreModifiedDate, ignoreEncodedPayload)).filter(value => value !== null)];
+}
+export function controllerContent(project, ignoreModifiedDate = false, ignoreEncodedPayload = false) {
+    return JSON.stringify(canonical(controller(project), undefined, ignoreModifiedDate, ignoreEncodedPayload));
+}
+/** Validate one edited routine component for review in the user's IDE.
+ * @param baseline - original routine export from Studio.
+ * @param draft - unchanged-on-disk proposal derived from that export.
+ * @param program - intended containing program.
+ * @param routine - intended existing routine.
+ * @returns import target and source identity; no Studio import or controller operation occurs.
+ */
+export function studioRoutineImportPlan(baseline, draft, program, routine) {
+    for (const value of [program, routine])
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value))
+            throw new EngineeringError('INVALID_TARGET', 'Program and routine must be Logix identifiers');
+    const before = documentRoot(parseXml(baseline.xml));
+    const after = documentRoot(parseXml(draft.xml));
+    if (before.attrs.TargetType !== 'Routine' || before.attrs.TargetName !== routine
+        || after.attrs.TargetType !== 'Routine' || after.attrs.TargetName !== routine) {
+        throw new EngineeringError('ROUTINE_COMPONENT_REQUIRED', 'Export the selected routine from the visible IDE first; full controller exports cannot be used as routine import files');
+    }
+    const beforeController = firstChild(before, 'Controller');
+    const afterController = firstChild(after, 'Controller');
+    if (beforeController === undefined || afterController === undefined)
+        throw new EngineeringError('INVALID_COMPONENT', 'Routine export requires controller context');
+    const oldProgram = named(firstChild(beforeController, 'Programs'), 'Program', program);
+    const newProgram = named(firstChild(afterController, 'Programs'), 'Program', program);
+    const oldRoutine = named(firstChild(oldProgram, 'Routines'), 'Routine', routine);
+    const newRoutine = named(firstChild(newProgram, 'Routines'), 'Routine', routine);
+    const protectedNode = (node) => 'children' in node && (node.name === 'EncodedData'
+        || /safety/iu.test(node.attrs.Class ?? '')
+        || Object.entries(node.attrs).some(([key, value]) => /Encrypted|SourceProtected/iu.test(key) && value !== 'false')
+        || node.children.some(protectedNode));
+    if (protectedNode(before) || protectedNode(after) || /safety/iu.test(program))
+        throw new EngineeringError('PROTECTED_TARGET', 'Safety or protected components require the engineer workflow');
+    if (!['RLL', 'ST'].includes(oldRoutine.attrs.Type ?? '') || oldRoutine.attrs.Type !== newRoutine.attrs.Type
+        || oldRoutine.attrs.Use !== 'Target' || newRoutine.attrs.Use !== 'Target')
+        throw new EngineeringError('UNSUPPORTED_TARGET', 'Use an existing unprotected RLL or ST routine exported as Target');
+    if (JSON.stringify(canonical(before, oldRoutine)) !== JSON.stringify(canonical(after, newRoutine)))
+        throw new EngineeringError('UNRELATED_CHANGE', 'Only the selected routine may change; preserve dependency and export context');
+    if (JSON.stringify(canonical(oldRoutine)) === JSON.stringify(canonical(newRoutine)))
+        throw new EngineeringError('NO_CHANGE', 'Routine is unchanged');
+    return {
+        operation: 'studio_ide_routine_import_plan', program, routine, routine_type: newRoutine.attrs.Type,
+        controller_name: beforeController?.attrs.Name ?? null, source_path: baseline.path, source_sha256: baseline.sha256,
+        component_path: draft.path, component_sha256: draft.sha256, software_revision: baseline.softwareRevision,
+        validation: { xml: 'passed', source_and_draft_hashes: 'checked_by_calling_tool', changes_confined_to_routine: true, studio_import: 'not_run', studio_verify: 'not_run', machine_behavior: 'not_verified' },
+        controller_contacted: false, ide_modified: false,
+        steps: ['Observe the same Studio IDE and confirm the saved project, program, routine and offline state.',
+            'Back up the saved project before replacement. Revalidate the proposal immediately before import.',
+            'Navigate to the intended program routine import command using fresh observed UI controls; choose component_path.',
+            'Review the collision preview: replace only this routine, retain existing dependencies, and stop for unexpected changes.',
+            'After import, run Verify in Studio and inspect its diagnostics; unresolved errors block handoff.',
+            'Present the result for engineering review. The engineer performs download; do not accept online edits or change controller mode through UI automation.'],
+    };
+}
+export function routineEditPlan(baseline, draft, program, routine) {
+    for (const value of [program, routine])
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value))
+            throw new EngineeringError('INVALID_TARGET', 'Program and routine must be Logix identifiers');
+    const before = controller(baseline);
+    const after = controller(draft);
+    const oldProgram = named(firstChild(before, 'Programs'), 'Program', program);
+    const newProgram = named(firstChild(after, 'Programs'), 'Program', program);
+    const tasks = firstChild(before, 'Tasks');
+    const safetyScheduled = tasks !== undefined && elementChildren(tasks, 'Task').some(task => /safety/iu.test(task.attrs.Class ?? '')
+        && firstChild(task, 'ScheduledPrograms')?.children.some(child => 'attrs' in child && child.attrs.Name === program));
+    if (/safety/iu.test(oldProgram.attrs.Class ?? '') || /safety/iu.test(program)
+        || safetyScheduled
+        || baseline.document.tasks.some(task => /safety/iu.test(task.name) && task.programs.includes(program)))
+        throw new EngineeringError('PROTECTED_TARGET', 'Safety programs cannot be imported through the ACD edit tool');
+    const oldRoutine = named(firstChild(oldProgram, 'Routines'), 'Routine', routine);
+    const newRoutine = named(firstChild(newProgram, 'Routines'), 'Routine', routine);
+    if (/safety/iu.test(oldRoutine.attrs.Class ?? '') || /safety/iu.test(newRoutine.attrs.Class ?? ''))
+        throw new EngineeringError('PROTECTED_TARGET', 'Safety routines cannot be edited');
+    if (!['RLL', 'ST'].includes(oldRoutine.attrs.Type ?? '') || oldRoutine.attrs.Type !== newRoutine.attrs.Type)
+        throw new EngineeringError('UNSUPPORTED_TARGET', 'Only existing RLL and ST routines of the same type are supported');
+    const protectedRoutine = (node) => node.name === 'EncodedData'
+        || Object.entries(node.attrs).some(([key, value]) => /Encrypted|SourceProtected/iu.test(key) && value !== 'false')
+        || node.children.some(child => 'children' in child && protectedRoutine(child));
+    if (protectedRoutine(oldRoutine) || protectedRoutine(newRoutine))
+        throw new EngineeringError('PROTECTED_TARGET', 'Encoded or protected routines cannot be edited');
+    const review = reviewDownloadSource(baseline, draft);
+    if (!review.eligible)
+        throw new EngineeringError('EDIT_BLOCKED', review.blockers.join('; '));
+    if (JSON.stringify(canonical(before, oldRoutine)) !== JSON.stringify(canonical(after, newRoutine)))
+        throw new EngineeringError('UNRELATED_CHANGE', 'The draft must change only the selected routine; tags, modules, other logic and controller metadata must remain intact');
+    if (JSON.stringify(canonical(oldRoutine)) === JSON.stringify(canonical(newRoutine)))
+        throw new EngineeringError('NO_CHANGE', 'Selected routine is unchanged');
+    return { xpath: `Controller/Programs/Program[@Name='${program}']/Routines/Routine[@Name='${routine}']` };
+}