import { loadTextFile, saveTextFile } from "./file-service.js"; import { gcodeProgramPath, machineIniPath, normalizeOpfsPath, parameterFilePath, sessionSnapshotPath, toolTablePath, } from "./path-model.js"; import { VIRTUAL_HAL_SIM_CONFIG_EVIDENCE_EXPANSION_CANDIDATES, VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_FIXTURES, VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES, VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS, cloneVirtualHalState, createVirtualHalCommandScriptFixtureReport, createVirtualHalMotionControllerMatrixReport, createVirtualHalSimConfigEvidenceExpansionReport, createVirtualHalSimConfigMacroLoadFixtureReport, createVirtualHalSimConfigPromotionCandidateReport, createVirtualHalSimConfigSourceCoverageReport, createVirtualHalSimulationReplacementReport, createVirtualHalSourceComplianceReport, createVirtualHalState, } from "../sdk/src/linuxcnc-hal.js"; export const SESSION_SNAPSHOT_FORMAT = "linuxcnc-wasm-session-snapshot"; export const SESSION_SNAPSHOT_VERSION = 1; function assertPlainObject(value, label) { if (value === null || typeof value !== "object" || Array.isArray(value)) { throw new Error(`${label} must be a plain object.`); } } function optionalOpfsPath(value, label) { if (value === undefined) { return undefined; } if (typeof value !== "string") { throw new Error(`${label} must be a string.`); } return normalizeOpfsPath(value); } function requiredSnapshotFilePath(files, key, label) { const value = files[key]; if (typeof value !== "string") { throw new Error(`${label} must be a string.`); } return normalizeOpfsPath(value); } function validateMachineSessionSnapshotPayload(payload, machineId) { assertPlainObject(payload, "machine session snapshot payload"); if (payload.machineId !== machineId) { throw new Error(`Machine session snapshot id mismatch: ${payload.machineId}`); } assertPlainObject(payload.files, "machine session snapshot files"); requiredSnapshotFilePath(payload.files, "ini", "machine session INI OPFS path"); requiredSnapshotFilePath(payload.files, "parameters", "machine session parameter OPFS path"); requiredSnapshotFilePath(payload.files, "toolTable", "machine session tool table OPFS path"); optionalOpfsPath(payload.files.gcode, "machine session G-code OPFS path"); if (payload.virtualHal !== undefined) { validateVirtualHalSessionPayload(payload.virtualHal); } return payload; } function validateVirtualHalSessionPayload(virtualHal) { assertPlainObject(virtualHal, "virtual HAL session payload"); assertPlainObject(virtualHal.state, "virtual HAL session state"); assertPlainObject(virtualHal.diagnostics, "virtual HAL session diagnostics"); assertPlainObject(virtualHal.sourceCompliance, "virtual HAL session source compliance"); assertPlainObject(virtualHal.simConfigSourceCoverage, "virtual HAL session sim-config source coverage"); assertPlainObject(virtualHal.simConfigPromotionCandidates, "virtual HAL session sim-config promotion candidates"); assertPlainObject(virtualHal.simConfigMacroLoadFixtures, "virtual HAL session sim-config macro/load fixtures"); assertPlainObject(virtualHal.commandScriptFixtures, "virtual HAL session command script fixtures"); assertPlainObject(virtualHal.motionControllerMatrix, "virtual HAL session motion controller matrix"); if (virtualHal.state.source !== "browser-virtual-hal") { throw new Error(`Unsupported virtual HAL state source: ${virtualHal.state.source}`); } if (virtualHal.sourceCompliance.complete !== true) { throw new Error("virtual HAL source compliance is incomplete."); } if (virtualHal.simConfigSourceCoverage.complete !== true) { throw new Error("virtual HAL sim-config source coverage is incomplete."); } if (virtualHal.simConfigPromotionCandidates.complete !== true) { throw new Error("virtual HAL sim-config promotion candidates are incomplete."); } if (virtualHal.simConfigEvidenceExpansion.complete !== true) { throw new Error("virtual HAL sim-config evidence expansion candidates are incomplete."); } if (virtualHal.simConfigMacroLoadFixtures.complete !== true) { throw new Error("virtual HAL sim-config macro/load fixtures are incomplete."); } if (virtualHal.commandScriptFixtures.complete !== true) { throw new Error("virtual HAL command script fixtures are incomplete."); } if (virtualHal.motionControllerMatrix.complete !== true) { throw new Error("virtual HAL motion controller matrix is incomplete."); } return virtualHal; } export function createVirtualHalSessionPayload(halState = createVirtualHalState(), options = {}) { const state = cloneVirtualHalState(halState); const reportOptions = { ...options, ...( options.manifestText === undefined && options.manifestEntries === undefined ? { manifestEntries: [ ...VIRTUAL_HAL_SIM_CONFIG_SOURCE_TARGETS.flatMap((target) => target.sourceFiles ?? []), ...VIRTUAL_HAL_SIM_CONFIG_PROMOTION_CANDIDATES.flatMap((candidate) => candidate.sourceFiles ?? []), ...VIRTUAL_HAL_SIM_CONFIG_EVIDENCE_EXPANSION_CANDIDATES.flatMap((candidate) => candidate.sourceFiles ?? []), ...VIRTUAL_HAL_SIM_CONFIG_MACRO_LOAD_FIXTURES.flatMap((fixture) => fixture.sourceFiles ?? []), ], } : {} ), }; const simConfigSourceCoverage = options.simConfigSourceCoverage ?? createVirtualHalSimConfigSourceCoverageReport(reportOptions); const simConfigMacroLoadFixtures = options.simConfigMacroLoadFixtures ?? createVirtualHalSimConfigMacroLoadFixtureReport(reportOptions); const commandScriptFixtures = options.commandScriptFixtures ?? createVirtualHalCommandScriptFixtureReport({ ...reportOptions, halState: state }); const motionControllerMatrix = options.motionControllerMatrix ?? createVirtualHalMotionControllerMatrixReport(reportOptions); const simConfigPromotionCandidates = options.simConfigPromotionCandidates ?? createVirtualHalSimConfigPromotionCandidateReport({ ...reportOptions, simConfigSourceCoverage, commandScriptFixtures, motionControllerMatrix, }); const simConfigEvidenceExpansion = options.simConfigEvidenceExpansion ?? createVirtualHalSimConfigEvidenceExpansionReport({ ...reportOptions, simConfigSourceCoverage, commandScriptFixtures, motionControllerMatrix, }); const sourceCompliance = options.sourceCompliance ?? createVirtualHalSourceComplianceReport({ ...reportOptions, halState: state, simConfigSourceCoverage, commandScriptFixtures, motionControllerMatrix, }); const diagnostics = options.diagnostics ?? createVirtualHalSimulationReplacementReport(state, { ...reportOptions, sourceCompliance, simConfigSourceCoverage, commandScriptFixtures, motionControllerMatrix, }); return validateVirtualHalSessionPayload({ apiName: "linuxcnc-wasm-virtual-hal-session-payload", payloadVersion: 1, source: "browser-virtual-hal", state, diagnostics, sourceCompliance, simConfigSourceCoverage, simConfigPromotionCandidates, simConfigEvidenceExpansion, simConfigMacroLoadFixtures, commandScriptFixtures, motionControllerMatrix, }); } export function restoreVirtualHalStateFromSessionSnapshot(snapshot) { assertPlainObject(snapshot, "session snapshot"); const virtualHal = validateVirtualHalSessionPayload(snapshot.payload?.virtualHal); return cloneVirtualHalState(virtualHal.state); } export function createMachineSessionSnapshotPayload(machineId, options = {}) { assertPlainObject(options, "machine session snapshot options"); const ini = optionalOpfsPath(options.iniOpfsPath, "INI OPFS path") ?? machineIniPath(machineId, options.iniFilename); const parameters = optionalOpfsPath(options.parameterOpfsPath, "parameter OPFS path") ?? parameterFilePath(machineId, options.parameterFilename); const toolTable = optionalOpfsPath(options.toolTableOpfsPath, "tool table OPFS path") ?? toolTablePath(machineId, options.toolTableFilename); const gcode = optionalOpfsPath(options.gcodeOpfsPath, "G-code OPFS path") ?? (options.gcodeFilename === undefined ? undefined : gcodeProgramPath(options.gcodeFilename)); const virtualHal = options.virtualHalState === undefined && options.virtualHal === undefined ? undefined : (options.virtualHal ?? createVirtualHalSessionPayload(options.virtualHalState, options.virtualHalOptions ?? {})); return { machineId, files: { ini, parameters, toolTable, ...(gcode === undefined ? {} : { gcode }), }, ...(virtualHal === undefined ? {} : { virtualHal }), }; } export function createSessionSnapshot(sessionId, payload, options = {}) { sessionSnapshotPath(sessionId, options.filename); assertPlainObject(payload, "snapshot payload"); if (options.metadata !== undefined) { assertPlainObject(options.metadata, "snapshot metadata"); } return { format: SESSION_SNAPSHOT_FORMAT, version: SESSION_SNAPSHOT_VERSION, sessionId, createdAt: options.createdAt ?? new Date().toISOString(), metadata: options.metadata ?? {}, payload, }; } export function validateSessionSnapshot(snapshot, sessionId) { assertPlainObject(snapshot, "session snapshot"); if (snapshot.format !== SESSION_SNAPSHOT_FORMAT) { throw new Error(`Unsupported session snapshot format: ${snapshot.format}`); } if (snapshot.version !== SESSION_SNAPSHOT_VERSION) { throw new Error(`Unsupported session snapshot version: ${snapshot.version}`); } if (snapshot.sessionId !== sessionId) { throw new Error(`Session snapshot id mismatch: ${snapshot.sessionId}`); } assertPlainObject(snapshot.metadata, "snapshot metadata"); assertPlainObject(snapshot.payload, "snapshot payload"); return snapshot; } export async function saveSessionSnapshot(sessionId, payload, options = {}) { const snapshot = createSessionSnapshot(sessionId, payload, options); const path = sessionSnapshotPath(sessionId, options.filename); await saveTextFile(path, `${JSON.stringify(snapshot, null, 2)}\n`, options.storage); return snapshot; } export async function saveMachineSessionSnapshot(sessionId, machineId, options = {}) { assertPlainObject(options, "machine session snapshot save options"); const payload = createMachineSessionSnapshotPayload(machineId, options); return saveSessionSnapshot(sessionId, payload, options); } export async function loadMachineSessionSnapshot(sessionId, machineId, options = {}) { const snapshot = await loadSessionSnapshot(sessionId, options); validateMachineSessionSnapshotPayload(snapshot.payload, machineId); return snapshot; } export async function loadSessionSnapshot(sessionId, options = {}) { const path = sessionSnapshotPath(sessionId, options.filename); const text = await loadTextFile(path, options.storage); let snapshot; try { snapshot = JSON.parse(text); } catch (error) { throw new Error(`Invalid session snapshot JSON: ${error.message}`); } return validateSessionSnapshot(snapshot, sessionId); }