From 9c3d9f4623735eb5aea4ac580c71ea3022de5fb6 Mon Sep 17 00:00:00 2001 From: salman Date: Sun, 30 Aug 2026 12:51:27 +0200 Subject: [PATCH] Add a dormant sequential-fit coordinator --- muSRFitlib.js | 209 ++++++++++++++++++++- tests/perl/CGI.pm | 43 +++++ tests/series-fit-runner.test.js | 316 ++++++++++++++++++++++++++++++++ 3 files changed, 559 insertions(+), 9 deletions(-) create mode 100644 tests/perl/CGI.pm create mode 100644 tests/series-fit-runner.test.js diff --git a/muSRFitlib.js b/muSRFitlib.js index b8730e0..06ab573 100644 --- a/muSRFitlib.js +++ b/muSRFitlib.js @@ -1496,6 +1496,18 @@ function seriesTransactionError(error, fallback) { return error && error.message ? error.message : String(error || fallback || "operation-failed"); } +function isValidPreparedSeriesCandidate(candidate) { + return candidate && Number.isInteger(candidate.run) && candidate.run > 0 + && new Set(["fit", "retry", "refit"]).has(candidate.action) + && typeof candidate.targetPath === "string" && candidate.targetPath !== "" + && typeof candidate.text === "string" + && (candidate.action == "fit" + || (typeof candidate.expectedTargetText === "string" + && candidate.expectedTargetText !== "") + || (typeof candidate.expectedTargetHash === "string" + && candidate.expectedTargetHash !== "")); +} + async function discardSeriesTransactionStages(adapter, staged, errors) { for (let index = staged.length - 1; index >= 0; index--) { let item = staged[index]; @@ -1566,18 +1578,10 @@ async function stageAndPromoteSeriesMSRCandidates(prepared, adapter, options = { return result; } - let allowedActions = new Set(["fit", "retry", "refit"]); let targets = new Set(); let items = []; for (let candidate of prepared.candidates) { - if (!candidate || !allowedActions.has(candidate.action) - || typeof candidate.targetPath !== "string" || candidate.targetPath === "" - || typeof candidate.text !== "string" - || (candidate.action != "fit" - && (typeof candidate.expectedTargetText !== "string" - || candidate.expectedTargetText === "") - && (typeof candidate.expectedTargetHash !== "string" - || candidate.expectedTargetHash === ""))) { + if (!isValidPreparedSeriesCandidate(candidate)) { result.reason = "invalid-series-candidate"; return result; } @@ -1879,6 +1883,193 @@ async function finalizeSeriesMSRTransaction(transaction, adapter, decision) { return result; } +function seriesRunResultSucceeded(runResult) { + if (!runResult || typeof runResult !== "object" + || (runResult.ok !== true && runResult.ok !== 1)) { + return false; + } + if (runResult.code !== undefined && runResult.code !== null + && Number(runResult.code) !== 0) { + return false; + } + if (runResult.signal) return false; + return !runResult.outcome || runResult.outcome == "success"; +} + +function seriesSequenceTransactionId(sequenceId, candidate, index) { + let suffix = "-" + (index + 1) + "-" + candidate.run; + return normalizeSeriesTransactionId( + sequenceId.substring(0, Math.max(1, 64 - suffix.length)) + suffix + ); +} + +// Run prepared independent fits in strict sequence. Each candidate gets its +// own transaction so a successfully committed prefix survives a later failure. +// The injected runner is the only operation that may execute musrfit; this +// shared helper itself has no process, CGI, UI, or platform dependency. +// It remains disconnected from startFit() until the platform runner adapters +// and user-facing progress/cancellation behavior are added. +async function runPreparedSeriesFitSequence( + prepared, transactionAdapter, runCandidate, options = {} +) { + let sequenceId = normalizeSeriesTransactionId(options.transactionId); + let result = { + ok: false, + reason: "invalid-prepared-series", + sequenceId: sequenceId, + completed: [], + excluded: prepared && Array.isArray(prepared.excluded) + ? prepared.excluded.slice() : [], + failed: null + }; + if (!prepared || prepared.ok !== true || !Array.isArray(prepared.candidates)) { + return result; + } + if (typeof runCandidate !== "function") { + result.reason = "series-runner-unavailable"; + return result; + } + + // Validate the complete sequence before staging the first run. Per-run + // transactions would otherwise allow malformed later input to be discovered + // only after an earlier fit had already committed. + let targets = new Set(); + for (let candidate of prepared.candidates) { + if (!isValidPreparedSeriesCandidate(candidate) + || targets.has(candidate.targetPath)) { + result.reason = targets.has(candidate && candidate.targetPath) + ? "duplicate-series-target" : "invalid-series-candidate"; + return result; + } + targets.add(candidate.targetPath); + } + + let blocked = result.excluded.filter(function(entry) { + return entry && entry.action == "blocked"; + }); + if (prepared.candidates.length === 0) { + result.ok = blocked.length === 0; + result.reason = blocked.length > 0 + ? "series-no-runnable-candidates" : "series-already-complete"; + return result; + } + + for (let index = 0; index < prepared.candidates.length; index++) { + let candidate = prepared.candidates[index]; + let transaction = await stageAndPromoteSeriesMSRCandidates( + { ok: true, candidates: [candidate] }, + transactionAdapter, + { transactionId: seriesSequenceTransactionId(sequenceId, candidate, index) } + ); + if (!transaction.ok) { + result.reason = "series-candidate-staging-failed"; + result.failed = { + run: candidate.run, + action: candidate.action, + targetPath: candidate.targetPath, + phase: "stage", + transaction: transaction + }; + return result; + } + + let receipt = transaction.receipts[0]; + if (transaction.receipts.length !== 1 || !receipt + || receipt.run !== candidate.run + || receipt.targetPath !== candidate.targetPath) { + result.reason = "series-candidate-stage-uncertain"; + result.failed = { + run: candidate.run, + action: candidate.action, + targetPath: candidate.targetPath, + phase: "stage", + transaction: transaction + }; + return result; + } + let runResult; + try { + runResult = await runCandidate(receipt, candidate, { + index: index, + position: index + 1, + total: prepared.candidates.length, + sequenceId: sequenceId, + transactionId: transaction.transactionId, + referenceRun: prepared.referenceRun || 0 + }); + } catch (error) { + runResult = { + ok: false, + code: null, + error: seriesTransactionError(error, "series-runner-failed") + }; + } + + if (!seriesRunResultSucceeded(runResult)) { + let rollback = await finalizeSeriesMSRTransaction( + transaction, transactionAdapter, "rollback" + ); + result.reason = rollback.ok + ? "series-candidate-run-failed" : "series-candidate-rollback-failed"; + result.failed = { + run: candidate.run, + action: candidate.action, + targetPath: candidate.targetPath, + phase: "run", + transactionId: transaction.transactionId, + runResult: runResult, + rollback: rollback + }; + return result; + } + + let commit = await finalizeSeriesMSRTransaction( + transaction, transactionAdapter, "commit" + ); + if (!commit.ok) { + // A failed preflight is known to be mutation-free and can therefore + // be rolled back automatically. Transport and partial-finalization + // failures are ambiguous; preserve their manifest/backup for explicit + // recovery rather than guessing which side completed. + let rollback = null; + if (commit.reason == "series-finalization-preflight-failed") { + rollback = await finalizeSeriesMSRTransaction( + transaction, transactionAdapter, "rollback" + ); + } + result.reason = rollback + ? (rollback.ok + ? "series-candidate-result-invalid" : "series-candidate-rollback-failed") + : "series-candidate-commit-uncertain"; + result.failed = { + run: candidate.run, + action: candidate.action, + targetPath: candidate.targetPath, + phase: "commit", + transactionId: transaction.transactionId, + runResult: runResult, + commit: commit, + rollback: rollback + }; + return result; + } + + result.completed.push({ + run: candidate.run, + action: candidate.action, + targetPath: candidate.targetPath, + transactionId: transaction.transactionId, + runResult: runResult + }); + } + + result.ok = blocked.length === 0; + result.reason = blocked.length > 0 + ? "series-sequence-completed-with-blocked-runs" + : "series-sequence-completed"; + return result; +} + // Store only presentation-ready fit quality in the job state. Both web and // Electron call this after reading the fitted MSR, keeping parsing independent // of the transport used to run musrfit. diff --git a/tests/perl/CGI.pm b/tests/perl/CGI.pm new file mode 100644 index 0000000..e5706b4 --- /dev/null +++ b/tests/perl/CGI.pm @@ -0,0 +1,43 @@ +# Copyright (C) 2026 Zaher Salman +# SPDX-License-Identifier: GPL-3.0-or-later + +# Minimal application/x-www-form-urlencoded parser used only by the repository +# tests when the host does not provide CGI.pm. Production continues to use the +# system CGI module and never deploys this tests/ directory. +package CGI; + +use strict; +use warnings; + +sub _decode_component { + my ($value) = @_; + $value = "" if !defined($value); + $value =~ tr/+/ /; + $value =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; + return $value; +} + +sub new { + my ($class) = @_; + my $length = $ENV{CONTENT_LENGTH} || 0; + my $body = ""; + read(STDIN, $body, $length) if $length > 0; + my %parameters = (); + foreach my $pair (split(/&/, $body, -1)) { + next if $pair eq ""; + my ($key, $value) = split(/=/, $pair, 2); + $key = _decode_component($key); + $value = _decode_component($value); + push(@{$parameters{$key}}, $value); + } + return bless({ parameters => \%parameters }, $class); +} + +sub param { + my ($self, $name) = @_; + return keys(%{$self->{parameters}}) if !defined($name); + my $values = $self->{parameters}{$name} || []; + return wantarray ? @{$values} : (@{$values} ? $values->[0] : undef); +} + +1; diff --git a/tests/series-fit-runner.test.js b/tests/series-fit-runner.test.js new file mode 100644 index 0000000..afaa5c5 --- /dev/null +++ b/tests/series-fit-runner.test.js @@ -0,0 +1,316 @@ +// Copyright (C) 2026 Zaher Salman +// SPDX-License-Identifier: GPL-3.0-or-later + +const assert = require("assert"); +const fs = require("fs"); +const path = require("path"); +const vm = require("vm"); + +const repoRoot = path.resolve(__dirname, ".."); + +function loadLibrary() { + const sandbox = { console: console, window: { MSREditor: {} } }; + sandbox.global = sandbox; + vm.runInNewContext( + fs.readFileSync(path.join(repoRoot, "muSRFitlib.js"), "utf8"), + sandbox, + { filename: "muSRFitlib.js" } + ); + return sandbox; +} + +function candidate(run, action, oldText) { + const result = { + run: run, + action: action, + targetPath: "/work/" + run + "_asy.msr", + text: "RUN " + run + "\n" + }; + if (action !== "fit") result.expectedTargetText = oldText; + return result; +} + +function prepared(candidates, excluded = []) { + return { + ok: true, + referenceRun: 514, + candidates: candidates, + excluded: excluded + }; +} + +function memoryTransactionAdapter(initialFiles = {}) { + const files = Object.assign({}, initialFiles); + const events = []; + return { + files: files, + events: events, + exists: async function(filePath) { + return Object.prototype.hasOwnProperty.call(files, filePath); + }, + createExclusive: async function(filePath, text) { + if (Object.prototype.hasOwnProperty.call(files, filePath)) { + throw new Error("exclusive-create-collision"); + } + events.push({ operation: "stage", path: filePath }); + files[filePath] = text; + }, + read: async function(filePath) { + return files[filePath]; + }, + promote: async function(item) { + if (item.replace) files[item.backupPath] = files[item.targetPath]; + files[item.targetPath] = files[item.stagePath]; + delete files[item.stagePath]; + events.push({ operation: "promote", run: item.run }); + return { + run: item.run, + action: item.action, + targetPath: item.targetPath, + backupPath: item.backupPath, + replaced: item.replace, + promotedText: item.expectedText, + originalText: item.replace ? files[item.backupPath] : "" + }; + }, + discard: async function(filePath) { + delete files[filePath]; + }, + verifyFinalize: async function(receipt, decision) { + if (!Object.prototype.hasOwnProperty.call(files, receipt.targetPath)) { + throw new Error("target-missing"); + } + if (decision === "commit" && !/\nCONVERGED\n$/.test(files[receipt.targetPath])) { + throw new Error("target-not-converged"); + } + if (receipt.replaced && files[receipt.backupPath] !== receipt.originalText) { + throw new Error("backup-changed"); + } + }, + commit: async function(receipt) { + await this.verifyFinalize(receipt, "commit"); + if (receipt.replaced) delete files[receipt.backupPath]; + events.push({ operation: "commit", run: receipt.run }); + }, + rollback: async function(receipt) { + if (receipt.replaced) { + files[receipt.targetPath] = files[receipt.backupPath]; + delete files[receipt.backupPath]; + } else { + delete files[receipt.targetPath]; + } + events.push({ operation: "rollback", run: receipt.run }); + } + }; +} + +async function testRunsAndCommitsOneAtATime(lib) { + const adapter = memoryTransactionAdapter({ "/work/516_asy.msr": "old-516" }); + const runs = []; + const result = await lib.runPreparedSeriesFitSequence( + prepared([ + candidate(515, "fit"), + candidate(516, "retry", "old-516") + ], [{ run: 514, action: "skip" }]), + adapter, + async function(receipt, item, context) { + runs.push({ run: item.run, position: context.position, total: context.total }); + adapter.events.push({ operation: "run", run: item.run }); + adapter.files[receipt.targetPath] += "\nCONVERGED\n"; + return { ok: true, code: 0 }; + }, + { transactionId: "sequence" } + ); + + assert.strictEqual(result.ok, true); + assert.strictEqual(result.reason, "series-sequence-completed"); + assert.deepStrictEqual(Array.from(result.completed.map(function(item) { + return item.run; + })), [515, 516]); + assert.deepStrictEqual(runs, [ + { run: 515, position: 1, total: 2 }, + { run: 516, position: 2, total: 2 } + ]); + assert.deepStrictEqual(adapter.events.filter(function(event) { + return ["promote", "run", "commit"].includes(event.operation); + }), [ + { operation: "promote", run: 515 }, + { operation: "run", run: 515 }, + { operation: "commit", run: 515 }, + { operation: "promote", run: 516 }, + { operation: "run", run: 516 }, + { operation: "commit", run: 516 } + ]); + assert.match(adapter.files["/work/515_asy.msr"], /CONVERGED/); + assert.match(adapter.files["/work/516_asy.msr"], /CONVERGED/); + assert.strictEqual(Object.keys(adapter.files).some(function(filePath) { + return /musrflow-(?:stage|backup)/.test(filePath); + }), false); +} + +async function testFailureKeepsCommittedPrefix(lib) { + const adapter = memoryTransactionAdapter({ + "/work/516_asy.msr": "old-516", + "/work/517_asy.msr": "old-517" + }); + const attempted = []; + const result = await lib.runPreparedSeriesFitSequence( + prepared([ + candidate(515, "fit"), + candidate(516, "retry", "old-516"), + candidate(517, "refit", "old-517") + ]), + adapter, + async function(receipt, item) { + attempted.push(item.run); + adapter.files[receipt.targetPath] += "\nCONVERGED\n"; + return item.run === 516 ? { ok: false, code: 2 } : { ok: true, code: 0 }; + } + ); + + assert.strictEqual(result.ok, false); + assert.strictEqual(result.reason, "series-candidate-run-failed"); + assert.deepStrictEqual(attempted, [515, 516]); + assert.deepStrictEqual(Array.from(result.completed.map(function(item) { + return item.run; + })), [515]); + assert.strictEqual(result.failed.run, 516); + assert.strictEqual(result.failed.rollback.ok, true); + assert.match(adapter.files["/work/515_asy.msr"], /CONVERGED/); + assert.strictEqual(adapter.files["/work/516_asy.msr"], "old-516"); + assert.strictEqual(adapter.files["/work/517_asy.msr"], "old-517"); +} + +async function testExitCodeAndConvergenceBothMatter(lib) { + let adapter = memoryTransactionAdapter(); + let result = await lib.runPreparedSeriesFitSequence( + prepared([candidate(515, "fit")]), + adapter, + async function(receipt) { + adapter.files[receipt.targetPath] += "\nCONVERGED\n"; + return { ok: true, code: 3 }; + } + ); + assert.strictEqual(result.reason, "series-candidate-run-failed"); + assert.strictEqual(Object.prototype.hasOwnProperty.call( + adapter.files, "/work/515_asy.msr" + ), false); + + adapter = memoryTransactionAdapter(); + result = await lib.runPreparedSeriesFitSequence( + prepared([candidate(515, "fit")]), + adapter, + async function() { + return { ok: true, code: 0 }; + } + ); + assert.strictEqual(result.reason, "series-candidate-result-invalid"); + assert.strictEqual(result.failed.phase, "commit"); + assert.strictEqual(result.failed.rollback.ok, true); + assert.strictEqual(Object.prototype.hasOwnProperty.call( + adapter.files, "/work/515_asy.msr" + ), false); +} + +async function testBlockedRunsAreReportedAfterEligibleRuns(lib) { + const adapter = memoryTransactionAdapter(); + const result = await lib.runPreparedSeriesFitSequence( + prepared( + [candidate(515, "fit")], + [{ run: 514, action: "skip" }, { run: 516, action: "blocked" }] + ), + adapter, + async function(receipt) { + adapter.files[receipt.targetPath] += "\nCONVERGED\n"; + return { ok: true, code: 0 }; + } + ); + assert.strictEqual(result.ok, false); + assert.strictEqual(result.reason, "series-sequence-completed-with-blocked-runs"); + assert.strictEqual(result.completed.length, 1); + assert.strictEqual(result.excluded.length, 2); +} + +async function testWholeSequenceIsValidatedBeforeWriting(lib) { + const adapter = memoryTransactionAdapter(); + const result = await lib.runPreparedSeriesFitSequence( + prepared([ + candidate(515, "fit"), + { run: 516, action: "fit", targetPath: "", text: "bad" } + ]), + adapter, + async function() { + throw new Error("runner must not be called"); + } + ); + assert.strictEqual(result.ok, false); + assert.strictEqual(result.reason, "invalid-series-candidate"); + assert.deepStrictEqual(Object.keys(adapter.files), []); + assert.deepStrictEqual(adapter.events, []); +} + +async function testMalformedRemoteReceiptIsNotRun(lib) { + let runnerCalled = false; + const result = await lib.runPreparedSeriesFitSequence( + prepared([candidate(515, "fit")]), + { + transactBatch: async function() { + return { + ok: true, + reason: "series-candidates-promoted", + receipts: [], + staged: [], + backups: [] + }; + } + }, + async function() { + runnerCalled = true; + return { ok: true, code: 0 }; + } + ); + assert.strictEqual(result.ok, false); + assert.strictEqual(result.reason, "series-candidate-stage-uncertain"); + assert.strictEqual(runnerCalled, false); +} + +async function testAmbiguousCommitPreservesRecoveryFiles(lib) { + const adapter = memoryTransactionAdapter({ "/work/516_asy.msr": "old-516" }); + adapter.commit = async function() { + throw new Error("injected-commit-failure"); + }; + const result = await lib.runPreparedSeriesFitSequence( + prepared([candidate(516, "retry", "old-516")]), + adapter, + async function(receipt) { + adapter.files[receipt.targetPath] += "\nCONVERGED\n"; + return { ok: true, code: 0 }; + } + ); + assert.strictEqual(result.ok, false); + assert.strictEqual(result.reason, "series-candidate-commit-uncertain"); + assert.strictEqual(result.failed.rollback, null); + assert.match(adapter.files["/work/516_asy.msr"], /CONVERGED/); + assert.strictEqual(Object.keys(adapter.files).some(function(filePath) { + return /musrflow-backup/.test(filePath) + && adapter.files[filePath] === "old-516"; + }), true); + assert.strictEqual(adapter.events.some(function(event) { + return event.operation === "rollback"; + }), false); +} + +(async function() { + const lib = loadLibrary(); + await testRunsAndCommitsOneAtATime(lib); + await testFailureKeepsCommittedPrefix(lib); + await testExitCodeAndConvergenceBothMatter(lib); + await testBlockedRunsAreReportedAfterEligibleRuns(lib); + await testWholeSequenceIsValidatedBeforeWriting(lib); + await testMalformedRemoteReceiptIsNotRun(lib); + await testAmbiguousCommitPreservesRecoveryFiles(lib); + console.log("series fit runner tests passed"); +})().catch(function(error) { + console.error(error); + process.exit(1); +});