feat(mgc): rendezvous planner — same-time landing across all modes

Routes every dispatch through a tick-aware planner so all pumps reach
their setpoint at the same wall-clock instant t* = max(eta_i),
regardless of control strategy or per-pump reaction speed.

Architecture (src/movement/):
- machineProfile.js   – pure snapshot of a registered child (state,
                        position, velocityPctPerS, ladder timings,
                        flowAt / positionForFlow). Reads timings from
                        child.state.config.time (the actual storage
                        location — previous fallback paths silently
                        produced 0 s, collapsing every eta to ramp-only).
- moveTrajectory.js   – seconds-to-target per machine; handles
                        idle / starting / warmingup / operational / cooling.
- movementScheduler.js – t* = max eta over ALL non-noop moves. Every
                        command is delayed so its move finishes at t*.
                        Startup execsequence fires at 0; its flowmovement
                        is gated by max(ladderS, t* − rampS) so a fast
                        pump waits before ramping rather than landing
                        early. useRendezvous=false collapses to all
                        fireAtTickN=0 (legacy fire-and-forget).
- movementExecutor.js – wall-clock virtual cursor: each tick fires
                        every command whose fireAtTickN ≤ floor(elapsed/tickS).
                        tick() no longer awaits pending fireCommand
                        promises — the synchronous prologue of
                        handleInput claims the latest-wins gate, which
                        is what race-favouring relies on.

Shared dispatch path (src/specificClass.js):
- _dispatchFlowDistribution(distribution) — extracted from
  _optimalControl. Builds profiles, calls movementScheduler.plan,
  replans the executor, ticks once. Reads
  config.planner.useRendezvous (default true).
- _optimalControl computes its bestCombination and hands off.
- equalFlowControl (priorityControl mode) computes its
  flowDistribution and hands off via ctx.mgc._dispatchFlowDistribution.
  Same-time landing now applies in BOTH modes.

Editor toggle (mgc.html + src/nodeClass.js):
- New "Same-time landing" checkbox under Control Strategy.
- nodeClass.buildDomainConfig bridges uiConfig.useRendezvous →
  config.planner.useRendezvous. Default ON.

Tests:
- New: planner-convergence.integration.test.js (real-time end-to-end
  diagnostic — drives a 3-pump mixed-state dispatch and asserts both
  convergence to the demand setpoint AND same-time landing within
  one tick).
- New: planner-rendezvous.integration.test.js (schedule-shape
  assertions against real pump objects).
- New: movementScheduler.basic.test.js — includes a mixed-speed
  multi-startup case proving the fast pumps wait so all three land
  together (the regression that prompted this work).
- New: movementExecutor.basic.test.js + moveTrajectory.basic.test.js.
- Updated executor contract test: tick() must NOT await pending fires.

Commands + wiki:
- handlers.js: source/mode allow-list gate moved into a shared _gate()
  helper; every command now checks isValidActionForMode +
  isValidSourceForMode before dispatching. Status-level commands
  (set.mode, set.scaling) are allowed in every mode.
- commands.basic.test.js: coverage for the new gate behaviour.
- wiki regen: Home.md visual-first rewrite + Reference-{Architecture,
  Contracts,Examples,Limitations}.md split with _Sidebar.md index.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

test/basic/commands.basic.test.js

@@ -22,17 +22,44 @@ function makeLogger() {
   };
 }
 
-function makeSource({ name = 'mgc-1', handleInputResult = undefined, dt = { flow: { min: 0, max: 100 } } } = {}) {
+function makeSource({
+  name = 'mgc-1',
+  handleInputResult = undefined,
+  dt = { flow: { min: 0, max: 100 } },
+  // Initial mode for the fake. Defaults to optimalControl so gates pass for
+  // the historical tests; per-test override via the returned `source.mode = …`.
+  mode = 'optimalControl',
+  // Override the gate decisions. Default-true matches the no-gating world
+  // tests assumed before this change; negative-path tests pass functions that
+  // return false for specific actions / sources.
+  isValidActionForMode = () => true,
+  isValidSourceForMode = () => true,
+} = {}) {
   const calls = {
     setMode: [],
     handleInput: [],
     registerChild: [],
     turnOffAllMachines: 0,
+    gateAction: [],
+    gateSource: [],
   };
   const source = {
     logger: makeLogger(),
     config: { general: { name } },
-    setMode: (m) => calls.setMode.push(m),
+    mode,
+    setMode: (m) => { calls.setMode.push(m); /* keep fake.mode unchanged unless test does it */ },
+    isValidActionForMode: (action, m) => {
+      const ok = isValidActionForMode(action, m);
+      calls.gateAction.push({ action, mode: m, ok });
+      if (!ok) source.logger.warn(`action '${action}' not allowed in mode '${m}'`);
+      return ok;
+    },
+    isValidSourceForMode: (src, m) => {
+      const ok = isValidSourceForMode(src, m);
+      calls.gateSource.push({ src, mode: m, ok });
+      if (!ok) source.logger.warn(`source '${src}' not allowed in mode '${m}'`);
+      return ok;
+    },
     handleInput: async (src, demand) => {
       calls.handleInput.push({ src, demand });
       if (handleInputResult instanceof Error) throw handleInputResult;
@@ -192,3 +219,124 @@ test('child.register with unknown child id logs warn and does not throw', async
     `expected warn about missing child, got: ${JSON.stringify(ctxLogger.calls.warn)}`
   );
 });
+
+// --- mode gate tests -------------------------------------------------------
+
+test('gate: set.demand in maintenance mode is dropped (action not allowed)', async () => {
+  // Mirror schema: maintenance allows only statusCheck. The dispatch action
+  // for a positive demand under optimalControl/priorityControl is
+  // execOptimalCombination / execSequentialControl — neither in maintenance.
+  const { source, calls } = makeSource({
+    mode: 'maintenance',
+    isValidActionForMode: (action) => action === 'statusCheck',
+  });
+  const reg = makeRegistry(makeLogger());
+
+  await reg.dispatch({ topic: 'set.demand', payload: 50 }, source, makeCtx());
+  assert.equal(calls.handleInput.length, 0, 'handleInput must not be invoked');
+  assert.equal(calls.turnOffAllMachines, 0, 'turnOffAllMachines must not be invoked');
+  assert.ok(
+    source.logger.calls.warn.some((m) => m.includes('not allowed')),
+    `expected warn about action not allowed in maintenance, got: ${JSON.stringify(source.logger.calls.warn)}`
+  );
+});
+
+test("gate: set.demand from msg.source 'physical' in maintenance is dropped (source not allowed)", async () => {
+  // Maintenance accepts sources ['parent','GUI'] per schema. Physical/HMI is
+  // rejected by the source gate even before we ask which action to perform.
+  const { source, calls } = makeSource({
+    mode: 'maintenance',
+    isValidActionForMode: () => true, // pretend action is allowed; source gate must still reject
+    isValidSourceForMode: (src) => src === 'parent' || src === 'GUI',
+  });
+  const reg = makeRegistry(makeLogger());
+
+  await reg.dispatch({ topic: 'set.demand', payload: 50, source: 'physical' }, source, makeCtx());
+  assert.equal(calls.handleInput.length, 0);
+  assert.equal(calls.turnOffAllMachines, 0);
+  assert.ok(
+    source.logger.calls.warn.some((m) => m.includes("'physical'") && m.includes('not allowed')),
+    `expected warn about physical source not allowed, got: ${JSON.stringify(source.logger.calls.warn)}`
+  );
+});
+
+test('gate: set.demand from msg.source GUI in optimalControl reaches handleInput', async () => {
+  const { source, calls } = makeSource({
+    mode: 'optimalControl',
+    isValidActionForMode: (action) =>
+      ['statusCheck', 'execOptimalCombination', 'balanceLoad', 'emergencyStop'].includes(action),
+    isValidSourceForMode: (src) => ['parent', 'GUI', 'physical', 'API'].includes(src),
+  });
+  const reg = makeRegistry(makeLogger());
+
+  await reg.dispatch({ topic: 'set.demand', payload: 25, source: 'GUI' }, source, makeCtx());
+  assert.equal(calls.handleInput.length, 1);
+  assert.deepEqual(calls.handleInput[0], { src: 'parent', demand: 25 });
+  // Sanity check on the gate plumbing: both gates were consulted with the
+  // expected (action, source, mode) tuple.
+  assert.ok(calls.gateAction.some((g) => g.action === 'execOptimalCombination' && g.mode === 'optimalControl' && g.ok));
+  assert.ok(calls.gateSource.some((g) => g.src === 'GUI' && g.mode === 'optimalControl' && g.ok));
+});
+
+test('gate: emergencyStop (negative demand) gated by mode → maintenance blocks the stop-all', async () => {
+  // A negative demand is the operator stop-all signal. The schema declares
+  // emergencyStop in optimalControl/priorityControl but NOT in maintenance,
+  // so this should be rejected too — maintenance is "monitor only", which
+  // includes "no dispatch decisions, even shutdowns".
+  const { source, calls } = makeSource({
+    mode: 'maintenance',
+    isValidActionForMode: (action) => action === 'statusCheck',
+  });
+  const reg = makeRegistry(makeLogger());
+
+  await reg.dispatch({ topic: 'set.demand', payload: -1 }, source, makeCtx());
+  assert.equal(calls.turnOffAllMachines, 0, 'turnOff must be gated');
+  assert.ok(
+    source.logger.calls.warn.some((m) => m.includes('emergencyStop') && m.includes('not allowed')),
+    `expected warn about emergencyStop not allowed, got: ${JSON.stringify(source.logger.calls.warn)}`
+  );
+});
+
+// --- mode-string normalisation (specificClass internals) --------------------
+
+const { _normaliseMode, ALLOWED_MODES } = require('../../src/specificClass');
+
+test('mode normalisation: camelCase pass-through, lowercase accepted, garbage rejected', () => {
+  assert.equal(_normaliseMode('optimalControl'), 'optimalControl');
+  assert.equal(_normaliseMode('optimalcontrol'), 'optimalControl');
+  assert.equal(_normaliseMode('OPTIMALCONTROL'), 'optimalControl');
+  assert.equal(_normaliseMode('priorityControl'), 'priorityControl');
+  assert.equal(_normaliseMode('prioritycontrol'), 'priorityControl');
+  assert.equal(_normaliseMode('maintenance'), 'maintenance');
+  assert.equal(_normaliseMode('MAINTENANCE'), 'maintenance');
+  assert.equal(_normaliseMode('wat'), null);
+  assert.equal(_normaliseMode(''), null);
+  assert.equal(_normaliseMode(null), null);
+  assert.equal(_normaliseMode(undefined), null);
+  assert.deepEqual(ALLOWED_MODES, ['optimalControl', 'priorityControl', 'maintenance']);
+});
+
+// --- schema-shape regression -----------------------------------------------
+
+test('schema regression: allowedSources keys are camelCase for all three modes', () => {
+  // Read the JSON directly — generalFunctions' package.json `exports` map
+  // doesn't expose the configs subpath, and we don't want to add it just for
+  // a test. Path is repo-relative from this test file.
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const schemaPath = path.resolve(__dirname, '../../../generalFunctions/src/configs/machineGroupControl.json');
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  const allowedSourcesSchema = schema.mode.allowedSources.rules.schema;
+  assert.ok(allowedSourcesSchema.optimalControl, 'optimalControl key must exist on allowedSources');
+  assert.ok(allowedSourcesSchema.priorityControl, 'priorityControl key must exist on allowedSources');
+  assert.ok(allowedSourcesSchema.maintenance, 'maintenance key must exist on allowedSources');
+  // Maintenance is monitor-only: parent + GUI permitted, physical/API rejected.
+  const mDefaults = allowedSourcesSchema.maintenance.default;
+  assert.ok(mDefaults.includes('parent'), `maintenance default should permit parent, got ${mDefaults}`);
+  assert.ok(mDefaults.includes('GUI'), `maintenance default should permit GUI, got ${mDefaults}`);
+  assert.ok(!mDefaults.includes('physical'), 'maintenance must NOT permit physical writes');
+  assert.ok(!mDefaults.includes('API'), 'maintenance must NOT permit API writes');
+  // Catch a regression to lowercase keys.
+  assert.equal(allowedSourcesSchema.optimalcontrol, undefined, 'lowercase optimalcontrol key must NOT exist');
+  assert.equal(allowedSourcesSchema.prioritycontrol, undefined, 'lowercase prioritycontrol key must NOT exist');
+});