@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/mwi/lib/session/service.js

@@ -0,0 +1,566 @@
+/**
+ * One workspace's MotionWorks runtime: bridge, code engine, stage and the rows
+ * that need them.
+ *
+ * Runtimes are cached per workspace so one chat reuses the bridge it started and
+ * one workspace's mailbox never answers another's request.
+ *
+ * @module dsh-engineering-mwi/session/service
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Bridge } from "../core/bridge.js";
+import { CodeEngine } from "../core/code-engine.js";
+import { MwiError } from "../core/errors.js";
+import { PowerShellBridgeTransport } from "../core/ps-bridge.js";
+import { StageService } from "./stage.js";
+import { compareVariables } from "../edit/compare.js";
+import { ReadService } from "../read/service.js";
+import { stageRootOf, workspaceOf, isInside } from "./workspace.js";
+/** The bridge directory shipped with this package. */
+export const BRIDGE_DIR = fileURLToPath(new URL('../../bridge/', import.meta.url));
+/** The code engine directory shipped with this package. */
+export const CODE_DIR = fileURLToPath(new URL('../../code/', import.meta.url));
+/** Vendored proven mutation helpers. */
+export const LEGACY_DIR = fileURLToPath(new URL('../../legacy/', import.meta.url));
+/** Hash every file in a native package, refusing links and oversized trees. */
+function nativePackageManifest(directory, workspace) {
+    const files = [];
+    let bytes = 0;
+    const visit = (folder) => {
+        if (!isInside(workspace, folder))
+            throw new MwiError('REFUSED', 'The package directory escapes the workspace.', 'Export into the workspace stage.');
+        for (const entry of readdirSync(folder, { withFileTypes: true })) {
+            const path = join(folder, entry.name);
+            if (entry.isSymbolicLink() || !isInside(workspace, path))
+                throw new MwiError('REFUSED', 'The package contains a link.', 'Re-export the package; links are refused.');
+            if (entry.isDirectory()) {
+                visit(path);
+                continue;
+            }
+            if (!entry.isFile())
+                throw new MwiError('REFUSED', 'The package contains an unsupported item.', 'Re-export the package.');
+            const content = readFileSync(path);
+            bytes += content.length;
+            if (files.length >= 100 || bytes > 64 * 1024 * 1024)
+                throw new MwiError('REFUSED', 'The package exceeds the supported size.', 'Export a smaller POU.');
+            files.push({ path: path.slice(directory.length + 1).replaceAll('\\', '/'), bytes: content.length, sha256: createHash('sha256').update(content).digest('hex') });
+        }
+    };
+    visit(directory);
+    return files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+/** A workspace runtime over the real bridge and engine. */
+export class PowerShellSessionRuntime {
+    workspace;
+    bridge;
+    engine;
+    stages;
+    /** Saved-project reads. */
+    reads;
+    /** Live POU-package receipts, bound to this runtime. */
+    packages = new Map();
+    /**
+     * @param workspace - Absolute workspace root.
+     */
+    constructor(workspace) {
+        this.workspace = workspace;
+        this.bridge = new Bridge(new PowerShellBridgeTransport({
+            bridgeDir: BRIDGE_DIR,
+            workspace,
+            stageRoot: stageRootOf(workspace),
+        }));
+        this.engine = new CodeEngine({ workspace, stageRoot: stageRootOf(workspace), codeDir: CODE_DIR });
+        this.stages = new StageService(this.engine, workspace);
+        this.reads = new ReadService(this.engine);
+    }
+    /** @returns The bridge's status document. */
+    async status() {
+        return await this.bridge.run('status');
+    }
+    /** @returns The bridge's live state document. */
+    async ideState() {
+        return await this.bridge.run('ide_state', { include_window_state: true });
+    }
+    /** @returns The written stage record. */
+    async stage(source, options = {}) {
+        return await this.stages.stage(source, {
+            ...options,
+            assertClosed: async () => {
+                let status;
+                try {
+                    status = await this.status();
+                }
+                catch (error) {
+                    if (error instanceof MwiError && error.code === 'IDE_NOT_RUNNING')
+                        return;
+                    throw error;
+                }
+                const active = typeof status.active_project === 'string' ? status.active_project : undefined;
+                if (active === undefined)
+                    return;
+                const requested = resolve(this.workspace, source);
+                const name = requested.replace(/\\/gu, '/').split('/').pop()?.replace(/\.mwt$/iu, '') ?? '';
+                if (name !== '')
+                    StageService.assertClosed(join(stageRootOf(this.workspace), name), { is_project_open: true, active_project: active });
+            },
+        });
+    }
+    /** @returns The bridge's open result. */
+    async open(path, options) {
+        const resolved = resolve(path);
+        if (!isInside(stageRootOf(this.workspace), resolved) || !existsSync(resolved)) {
+            throw new MwiError('NOT_STAGED', `${resolved} is not a staged project.`, 'Stage the workspace project with mw_project_stage, then open the staged .mwt.');
+        }
+        const name = resolved.replace(/\\/gu, '/').split('/').pop()?.replace(/\.mwt$/iu, '') ?? '';
+        if (this.stages.identityOf(name) === undefined) {
+            throw new MwiError('STAGE_IDENTITY_MISSING', `The stage ${name} has no identity record.`, 'Stage the project again; an unproven stage is never opened.');
+        }
+        const binding = await this.engine.run('check_mwt', { project: resolved });
+        return await this.bridge.run('open', {
+            path: resolved,
+            wrapper_sha256: binding.wrapper_sha256,
+            user_approved: options.userApproved === true,
+            ...(options.expectedProject === undefined ? {} : { expected_project: options.expectedProject }),
+        });
+    }
+    /** @returns The bridge's start result. */
+    async start(project) {
+        const staged = project === undefined ? this.singleStage() : this.stageMwt(project);
+        const binding = await this.engine.run('check_mwt', { project: staged });
+        return await this.bridge.run('start_ide', {
+            include_trial_method: true,
+            path: staged,
+            wrapper_sha256: binding.wrapper_sha256,
+        });
+    }
+    /** @returns The bridge's worksheet result. */
+    async worksheet(request) {
+        const status = await this.status();
+        if (status.is_project_open !== true || typeof status.active_project !== 'string') {
+            throw new MwiError('NO_PROJECT', 'No project is open in the IDE.', 'Open a staged project first with mw_project_open.');
+        }
+        const record = this.stages.stagedAt(status.active_project);
+        if (record === undefined) {
+            throw new MwiError('NOT_STAGED', `The open project is not a proven stage: ${status.active_project}.`, 'Open a staged project before navigating worksheets.');
+        }
+        const target = await this.engine.run('worksheet_target', {
+            project: record.staged_directory,
+            kind: request.kind,
+            ...(request.pou === undefined ? {} : { pou: request.pou }),
+        });
+        return await this.bridge.run('open_worksheet', {
+            project: record.staged_directory,
+            ...target,
+            inspect_only: request.inspectOnly === true,
+        });
+    }
+    /** @returns The bridge's close result. */
+    async close(options) {
+        if (options.userApproved !== true) {
+            throw new MwiError('APPROVAL_REQUIRED', 'Closing the IDE requires explicit user approval.', 'Ask the user, then pass user_approved: true and the exact open project path.');
+        }
+        return await this.bridge.run('close_ide', {
+            user_approved: true,
+            ...(options.expectedProject === undefined ? {} : { expected_project: options.expectedProject }),
+        });
+    }
+    /** @returns The stage record for a path. */
+    stagedAt(path) {
+        return this.stages.stagedAt(path);
+    }
+    /** @returns The bridge's compile result. */
+    async compile(mode) {
+        await this.openStagedRecord();
+        if (mode === 'state')
+            return await this.bridge.run('compile_state', {});
+        try {
+            return await this.bridge.run(mode, {}, 400_000);
+        }
+        catch (error) {
+            if (error instanceof MwiError && error.code === 'BRIDGE_FAILED') {
+                throw new MwiError('COMPILE_FAILED', error.message, 'Read mw_diagnostics for the exact message, fix the reported task or source, then compile again.');
+            }
+            throw error;
+        }
+    }
+    /** @returns The output pane and the compile verdict when readable. */
+    async diagnostics(pane, limit) {
+        const read = await this.bridge.run('read_output', { pane, limit }, 60_000);
+        const state = await this.bridge.run('compile_state', {}, 30_000).catch(() => null);
+        return { ...read, compile_state: state };
+    }
+    /** @returns A baseline receipt or a comparison against one. */
+    async verify(mode, baselineId) {
+        const record = await this.openStagedRecord();
+        const manifest = await this.engine.run('source_manifest', { project: record.staged_directory });
+        const state = await this.bridge.run('compile_state', {}, 30_000).catch(() => null);
+        const directory = join(this.workspace, '.motionworks', 'verification');
+        if (mode === 'baseline') {
+            const id = randomUUID();
+            mkdirSync(directory, { recursive: true });
+            const baseline = {
+                id,
+                project: record.staged_directory,
+                source_digest: manifest.source_digest,
+                files: manifest.files,
+                compile_state: state,
+                captured_at: new Date().toISOString(),
+            };
+            writeFileSync(join(directory, `${id}.json`), JSON.stringify(baseline, null, 2));
+            return { baseline_id: id, project: record.staged_directory, source_digest: manifest.source_digest, compile_state: state, baseline_path: join(directory, `${id}.json`) };
+        }
+        if (baselineId === undefined || baselineId === '') {
+            throw new MwiError('BASELINE_REQUIRED', 'Comparing needs the baseline_id returned by a baseline capture.', 'Call mw_verify mode baseline, then compare with that id.');
+        }
+        let baseline;
+        try {
+            baseline = JSON.parse(readFileSync(join(directory, `${baselineId}.json`), 'utf8'));
+        }
+        catch {
+            throw new MwiError('BASELINE_NOT_FOUND', `No baseline ${baselineId} exists in this workspace.`, 'Capture a new baseline and compare against that id.');
+        }
+        if (baseline.project === undefined || resolve(baseline.project) !== resolve(record.staged_directory)) {
+            throw new MwiError('BASELINE_PROJECT_MISMATCH', 'The baseline belongs to another project.', 'Capture a baseline for the open project and compare that id.');
+        }
+        const before = baseline.files ?? {};
+        const after = manifest.files ?? {};
+        const added = Object.keys(after).filter(file => before[file] === undefined);
+        const removed = Object.keys(before).filter(file => after[file] === undefined);
+        const changed = Object.keys(after).filter(file => before[file] !== undefined && before[file] !== after[file]);
+        return {
+            baseline_id: baselineId,
+            project: record.staged_directory,
+            matched: baseline.source_digest === manifest.source_digest,
+            source_digest: manifest.source_digest,
+            baseline_source_digest: baseline.source_digest,
+            added,
+            removed,
+            changed,
+            compile_state: state,
+            baseline_compile_state: baseline.compile_state,
+        };
+    }
+    /** Export one POU to a workspace package, or import it into this project. */
+    async transferPou(input) {
+        const record = await this.openStagedRecord();
+        const helpers = await import(__rewriteRelativeImportExtension(pathToFileURL(join(LEGACY_DIR, 'pou-package.js')).href));
+        const workspace = this.workspace;
+        const project = record.staged_directory;
+        const evidenceDirectory = join(workspace, '.motionworks', 'verification');
+        mkdirSync(evidenceDirectory, { recursive: true });
+        const evidence = join(evidenceDirectory, `pou-package-${randomUUID()}.json`);
+        if (input.operation === 'export') {
+            const directory = join(workspace, '.motionworks', `pk-${randomUUID().slice(0, 8)}`);
+            mkdirSync(directory);
+            const deps = {
+                status: async () => await this.bridge.run('compile_state'),
+                saved: async () => await this.engine.run('structure_snapshot', { project }),
+                snapshot: async () => await this.bridge.run('pou_package_snapshot', {}, 120_000),
+                manifest: async () => nativePackageManifest(directory, workspace),
+                consume: async () => undefined,
+                mutate: async (request) => await this.bridge.run('pou_package_mutate', { ...request, project, package_directory: directory }, 120_000),
+            };
+            try {
+                const exported = await helpers.exportPouPackage({ project, pou: input.pou, baseline_saved: true }, deps);
+                const token = randomUUID();
+                const receipt = {
+                    ...exported, directory, project, workspace, evidence_path: evidence, used: false,
+                };
+                this.packages.set(token, receipt);
+                writeFileSync(evidence, JSON.stringify({ operation: 'export', token, receipt }, null, 2), 'utf8');
+                return {
+                    accepted: true,
+                    operation: 'export',
+                    package_token: token,
+                    package_directory: directory,
+                    file_count: exported.manifest.length,
+                    evidence_path: evidence,
+                };
+            }
+            catch (error) {
+                throw new MwiError('EDIT_REFUSED', `${error.message}; evidence at ${evidence}`, 'Inspect the partial package before another attempt.');
+            }
+        }
+        const token = typeof input.package_token === 'string' ? input.package_token : '';
+        const receipt = this.packages.get(token);
+        if (receipt === undefined || receipt.workspace !== workspace || receipt.project !== project) {
+            throw new MwiError('PACKAGE_TOKEN_UNKNOWN', 'No live export receipt matches this token, workspace and project.', 'Export the POU again; tokens do not survive a plugin reload.');
+        }
+        if (input.dependencies_reviewed !== true) {
+            throw new MwiError('APPROVAL_REQUIRED', 'Importing needs dependencies_reviewed:true.', 'Review the package externals, then retry with the flag.');
+        }
+        const deps = {
+            status: async () => await this.bridge.run('compile_state'),
+            saved: async () => await this.engine.run('structure_snapshot', { project }),
+            snapshot: async () => await this.bridge.run('pou_package_snapshot', {}, 120_000),
+            manifest: async () => nativePackageManifest(receipt.directory, workspace),
+            consume: async () => {
+                receipt.used = true;
+                writeFileSync(evidence, JSON.stringify({ operation: 'import', token, phase: 'token_consumed', receipt }, null, 2), 'utf8');
+            },
+            mutate: async (request) => await this.bridge.run('pou_package_mutate', { ...request, project, package_directory: receipt.directory }, 120_000),
+        };
+        try {
+            const imported = await helpers.importPouPackage({ project, baseline_saved: true, dependencies_reviewed: true }, receipt, deps);
+            writeFileSync(evidence, JSON.stringify({ operation: 'import', token, ...imported }, null, 2), 'utf8');
+            return { ...imported, evidence_path: evidence };
+        }
+        catch (error) {
+            throw new MwiError('EDIT_REFUSED', `${error.message}; evidence at ${evidence}`, 'Inspect the retained receipt and current project; do not retry a consumed token.');
+        }
+    }
+    /** Insert one FB instance and its ST call into a POU. */
+    async insertBlock(input) {
+        const record = await this.openStagedRecord();
+        const helpers = await import(__rewriteRelativeImportExtension(pathToFileURL(join(LEGACY_DIR, 'fb-insertion.js')).href));
+        const project = record.staged_directory;
+        const state = await this.bridge.run('compile_state');
+        if (state.is_modified !== false) {
+            throw new MwiError('EDIT_REFUSED', 'The native project has unsaved changes.', 'Save or reconcile the IDE, then retry.');
+        }
+        const libraries = await this.bridge.run('library_snapshot');
+        const block = await this.engine.run('block_interface', {
+            project,
+            native_libraries: libraries.libraries ?? [],
+            name: input.block,
+            ...(typeof input.library === 'string' ? { library: input.library } : {}),
+        }, 120_000);
+        const read = await this.engine.run('read_st', { project, pou: input.pou }, 60_000);
+        const plan = helpers.fbInsertionPlan({ ...input, project, baseline_saved: true }, block, read);
+        const variable = await this.editVariable({
+            pou: input.pou,
+            operation: 'add',
+            declaration: plan.declaration,
+            ...(typeof input.group === 'string' ? {} : { group: 'Default' }),
+        });
+        if (variable.verification?.accepted !== true) {
+            throw new MwiError('EDIT_REFUSED', `The instance declaration did not verify: ${variable.verification?.errors?.join('; ') ?? 'unknown'}.`, 'Inspect the declaration evidence before another attempt.');
+        }
+        const code = await this.editCode({
+            pou: String(input.pou),
+            expectedBody: typeof read.body === 'string' ? read.body : '',
+            body: plan.code,
+        });
+        const accepted = code.verification?.accepted === true;
+        return {
+            verification: { accepted, errors: code.verification?.errors ?? [], warnings: plan.warnings },
+            instance: input.instance,
+            call: plan.call,
+            completed_phases: accepted ? ['instance_declared', 'call_inserted'] : ['instance_declared'],
+            body: code.body,
+            evidence: { variable, block },
+        };
+    }
+    /** Add, edit or delete one native declaration. */
+    async editVariable(input) {
+        const record = await this.openStagedRecord();
+        const helpers = await import(__rewriteRelativeImportExtension(pathToFileURL(join(LEGACY_DIR, 'native-variables.js')).href));
+        const project = record.staged_directory;
+        const pou = typeof input.pou === 'string' ? input.pou : undefined;
+        const evidenceDirectory = join(this.workspace, '.motionworks', 'verification');
+        mkdirSync(evidenceDirectory, { recursive: true });
+        const evidence = join(evidenceDirectory, `native-variable-${randomUUID()}.json`);
+        const args = { ...input, project, baseline_saved: true };
+        try {
+            const result = await helpers.nativeVariableChange(args, {
+                status: async () => await this.bridge.run('compile_state'),
+                saved: async () => await this.engine.run(pou === undefined ? 'globals' : 'read_st', { project, ...(pou === undefined ? {} : { pou }) }),
+                snapshotSaved: async () => await this.bridge.run('variable_snapshot', { ...(pou === undefined ? {} : { pou }), require_saved: true }),
+                mutate: async (request) => await this.bridge.run('variable_mutate', { ...request, project }, 60_000),
+                compare: compareVariables,
+                globals: async () => await this.engine.run('globals', { project }),
+            });
+            writeFileSync(evidence, JSON.stringify({ args, ...result }, null, 2), { encoding: 'utf8', flag: 'wx' });
+            return { ...result, evidence_path: evidence };
+        }
+        catch (error) {
+            throw new MwiError('EDIT_REFUSED', `${error.message}; evidence at ${evidence}`, 'Read the refusal, correct the request, and retry. Do not repeat an unverified edit.');
+        }
+    }
+    /** Create, copy, rename, delete or assign one POU or task. */
+    async editStructure(input) {
+        const record = await this.openStagedRecord();
+        const helpers = await import(__rewriteRelativeImportExtension(pathToFileURL(join(LEGACY_DIR, 'native-structure.js')).href));
+        const project = record.staged_directory;
+        const scope = input.scope === 'task' ? 'task' : 'pou';
+        const args = { ...input, project, baseline_saved: true };
+        delete args.scope;
+        const evidenceDirectory = join(this.workspace, '.motionworks', 'verification');
+        const inputDirectory = join(this.workspace, '.motionworks', 'native-input');
+        mkdirSync(evidenceDirectory, { recursive: true });
+        const evidence = join(evidenceDirectory, `native-structure-${randomUUID()}.json`);
+        try {
+            const result = await helpers.nativeStructureChange(scope, args, {
+                status: async () => await this.bridge.run('compile_state'),
+                saved: async () => await this.engine.run('structure_snapshot', { project }),
+                snapshot: async () => await this.bridge.run('structure_snapshot'),
+                mutate: async (request) => await this.bridge.run('structure_mutate', { ...request, project }, 60_000),
+                retainPlan: async (plan) => {
+                    writeFileSync(evidence, JSON.stringify({ phase: 'plan_retained', ...plan }, null, 2), { encoding: 'utf8', flag: 'wx' });
+                },
+                prepareSettings: async (settingsText) => {
+                    mkdirSync(inputDirectory, { recursive: true });
+                    const path = join(inputDirectory, `${randomUUID()}.SET`);
+                    writeFileSync(path, settingsText, { encoding: 'ascii', flag: 'wx' });
+                    return { settings_import_path: path };
+                },
+            });
+            writeFileSync(evidence, JSON.stringify({ phase: 'result', ...result }, null, 2), 'utf8');
+            return { ...result, evidence_path: evidence };
+        }
+        catch (error) {
+            throw new MwiError('EDIT_REFUSED', `${error.message}; evidence at ${evidence}`, 'Read the refusal, correct the request, and retry. Do not repeat an unverified edit.');
+        }
+    }
+    /** Validate the current saved project. */
+    async validate(options) {
+        const record = await this.openStagedRecord();
+        const workflow = await this.engine.run('workflow_check', { project: record.staged_directory }, 120_000);
+        const validate = await this.engine.run('validate', { project: record.staged_directory }, 120_000);
+        const review = options.pou === undefined && options.body === undefined
+            ? undefined
+            : await this.engine.run('check_program', {
+                project: record.staged_directory,
+                ...(options.pou === undefined ? {} : { pou: options.pou }),
+                ...(options.body === undefined ? {} : { body: options.body }),
+            }, 180_000);
+        const state = await this.bridge.run('compile_state', {}, 30_000).catch(() => null);
+        const blockers = workflow.blockers ?? [];
+        const validation = validate.result;
+        return {
+            project: record.staged_directory,
+            blockers,
+            validation_errors: validation?.errors ?? [],
+            workflow,
+            validate,
+            ...(review === undefined ? {} : { review }),
+            compile_state: state,
+            ready: blockers.length === 0 && (validation?.errors?.length ?? 0) === 0,
+        };
+    }
+    /** Save the open staged project through the IDE. */
+    async apply() {
+        const record = await this.openStagedRecord();
+        const saved = await this.bridge.run('save', {}, 60_000);
+        const state = await this.bridge.run('compile_state', {}, 30_000).catch(() => null);
+        return { project: record.staged_directory, saved, compile_state: state };
+    }
+    /** Replace one ST/IL body through the proven native ChangeCodeWS path. */
+    async editCode(input) {
+        const record = await this.openStagedRecord();
+        const helpers = await import(__rewriteRelativeImportExtension(pathToFileURL(join(LEGACY_DIR, 'native-code.js')).href));
+        const project = record.staged_directory;
+        const evidenceDirectory = join(this.workspace, '.motionworks', 'verification');
+        const inputDirectory = join(this.workspace, '.motionworks', 'native-input');
+        mkdirSync(evidenceDirectory, { recursive: true });
+        const evidence = join(evidenceDirectory, `native-code-${randomUUID()}.json`);
+        const args = { project, pou: input.pou, baseline_saved: true };
+        if (input.changes !== undefined) {
+            args.changes = input.changes;
+            if (input.expectedHash !== undefined)
+                args.expected_body_sha256 = input.expectedHash;
+        }
+        else {
+            args.code = input.body;
+            args.expected_body = input.expectedBody;
+        }
+        try {
+            const result = await helpers.nativeCodeChange(args, {
+                status: async () => await this.bridge.run('compile_state'),
+                saved: async () => await this.engine.run('structure_snapshot', { project }),
+                snapshot: async () => await this.bridge.run('structure_snapshot'),
+                read: async () => await this.engine.run('read_text', { project, pou: input.pou }),
+                document: async () => {
+                    const code = await this.engine.run('worksheet_target', { project, pou: input.pou, kind: 'code' });
+                    const variables = await this.engine.run('worksheet_target', { project, pou: input.pou, kind: 'variables' });
+                    const urn = String(variables.urn ?? '');
+                    return { ...code, variable_worksheet: urn.split('.').at(-1) };
+                },
+                declarations: async () => await this.bridge.run('variable_snapshot', { pou: input.pou }),
+                prepare: async (text, language) => {
+                    mkdirSync(inputDirectory, { recursive: true });
+                    const path = join(inputDirectory, `${randomUUID()}.${language}`);
+                    writeFileSync(path, text, { encoding: 'ascii', flag: 'wx' });
+                    return { code_import_path: path };
+                },
+                retain: async (plan) => {
+                    writeFileSync(evidence, JSON.stringify({ phase: 'plan_retained', ...plan }, null, 2), { encoding: 'utf8', flag: 'wx' });
+                },
+                mutate: async (request) => await this.bridge.run('code_mutate', { ...request, project }, 60_000),
+            });
+            writeFileSync(evidence, JSON.stringify({ phase: 'result', ...result }, null, 2), 'utf8');
+            return result;
+        }
+        catch (error) {
+            throw new MwiError('EDIT_REFUSED', `${error.message}; evidence at ${evidence}`, 'Read the refusal, correct the request, and retry. Do not repeat an unverified edit.');
+        }
+    }
+    /** The open project must be a proven stage; every compile and verify depends on it. */
+    async openStagedRecord() {
+        const status = await this.status();
+        if (status.is_project_open !== true || typeof status.active_project !== 'string') {
+            throw new MwiError('NO_PROJECT', 'No project is open in the IDE.', 'Open a staged project with mw_project_open before compiling.');
+        }
+        const record = this.stages.stagedAt(status.active_project);
+        if (record === undefined) {
+            throw new MwiError('NOT_STAGED', `The open project is not a proven stage: ${status.active_project}.`, 'Open a staged project; the verify row never compiles a workspace original.');
+        }
+        return record;
+    }
+    /** The only staged project, or a refusal that explains the choice. */
+    singleStage() {
+        let names = [];
+        try {
+            names = readdirSync(stageRootOf(this.workspace)).filter(name => name.toLowerCase().endsWith('.mwt'));
+        }
+        catch {
+            names = [];
+        }
+        if (names.length === 0)
+            throw new MwiError('NO_STAGE', 'No project is staged in this workspace.', 'Call mw_project_find, then mw_project_stage.');
+        if (names.length > 1) {
+            throw new MwiError('AMBIGUOUS_STAGE', `${names.length} projects are staged.`, 'Pass project: the staged .mwt to start.', names);
+        }
+        return join(stageRootOf(this.workspace), names[0]);
+    }
+    /** Resolve a requested staged project. */
+    stageMwt(project) {
+        const resolved = resolve(this.workspace, project);
+        const mwt = resolved.toLowerCase().endsWith('.mwt') ? resolved : `${resolved}.mwt`;
+        if (!isInside(stageRootOf(this.workspace), mwt) || !existsSync(mwt)) {
+            throw new MwiError('NOT_STAGED', `${mwt} is not a staged project.`, 'Stage the workspace project first, then pass the staged .mwt.');
+        }
+        return mwt;
+    }
+}
+const runtimes = new Map();
+/**
+ * Resolve the runtime for one workspace.
+ *
+ * @param workspace - Absolute workspace root.
+ * @returns The cached runtime.
+ */
+export function runtimeFor(workspace) {
+    const key = workspace.toLowerCase();
+    const existing = runtimes.get(key);
+    if (existing !== undefined)
+        return existing;
+    const created = new PowerShellSessionRuntime(workspace);
+    runtimes.set(key, created);
+    return created;
+}
+/** Resolve a tool call's workspace. */
+export function workspaceFrom(exec) {
+    return workspaceOf(exec.cwd);
+}

package/vendor/mwi/lib/session/stage.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Staging: copy one workspace project into `.motionworks/stage` and bind its wrapper.
+ *
+ * The source is never modified. A stage is refused when it already exists unless
+ * the caller explicitly replaces it after review; the previous stage is moved to
+ * `backups/stage-<id>` rather than discarded.
+ *
+ * @module dsh-engineering-mwi/session/stage
+ */
+import type { CodeEngine } from '../core/code-engine.ts';
+/** Identity suffix, matching the legacy stage record. */
+export declare const IDENTITY_SUFFIX = ".identity.json";
+/** One staged project. */
+export interface StageRecord {
+    /** Project name (the `.mwt` basename). */
+    readonly name: string;
+    /** Original workspace `.mwt`. */
+    readonly source: string;
+    /** Original expanded project directory. */
+    readonly source_directory: string;
+    /** Workspace that owns the stage. */
+    readonly workspace: string;
+    /** Staged `.mwt`. */
+    readonly staged_mwt: string;
+    /** Staged expanded directory. */
+    readonly staged_directory: string;
+    /** Directory the wrapper was bound to. */
+    readonly bound_to: string;
+    /** The wrapper's previous embedded directory, when it named one. */
+    readonly previous_embedded_path: string | null;
+    /** When the stage was written. */
+    readonly staged_at: string;
+}
+/** Options for one staging request. */
+export interface StageOptions {
+    /** Replace an existing stage after review; the previous stage is retained. */
+    readonly replace?: boolean;
+    /** Refuse when the current IDE project is inside the target stage. */
+    readonly assertClosed?: () => Promise<void>;
+}
+/** The service that stages projects for one workspace. */
+export declare class StageService {
+    private readonly engine;
+    private readonly workspace;
+    /**
+     * @param engine - Code engine that binds the wrapper.
+     * @param workspace - Absolute workspace root.
+     */
+    constructor(engine: CodeEngine, workspace: string);
+    /** The stage root of this workspace. */
+    get stageRoot(): string;
+    /**
+     * Stage one project.
+     *
+     * @param sourceArg - `.mwt` or project directory inside the workspace.
+     * @param options - Replacement and closed-project checks.
+     * @returns The written stage record.
+     */
+    stage(sourceArg: string, options?: StageOptions): Promise<StageRecord>;
+    /**
+     * Read one identity record.
+     *
+     * @param name - Project name.
+     * @returns The record, or undefined when the name was not staged.
+     */
+    identityOf(name: string): StageRecord | undefined;
+    /**
+     * The staged project whose `.mwt` or directory is `path`.
+     *
+     * @param path - Active or requested project path.
+     * @returns Its identity record, or undefined.
+     */
+    stagedAt(path: string): StageRecord | undefined;
+    /**
+     * Refuse when the active IDE project is this stage.
+     *
+     * @param targetDir - Stage directory about to be replaced.
+     * @param status - Bridge status document.
+     */
+    static assertClosed(targetDir: string, status: {
+        is_project_open?: boolean;
+        active_project?: string;
+    }): void;
+}