feat(events): conditions, phase advancement and the diagnosis panel (Phase 5)

A phase used to advance on one fact - every step terminal. It can now also carry
an advance CONDITION: `{ after: '30m' }` or `{ on: '<triggerId>', where:
<conditions>, count: n }`, reusing `engagement/conditions.js` unchanged. The
phase's real deliverable is the diagnosis panel: "why didn't phase 3 start?"
answered in the condition builder's own words, with the tally, the elapsed time
and the last related firing whether or not it counted.

`POST /admin/events/runs/:runId/advance` arrives beside it. It has been absent
since Phase 3 for want of a meaning; a phase with a gate can wait on a boss that
will never spawn, and that is the one state "force it anyway" names.

One new table, `event_run_phase_gates`. The emit path writes the tally at the
moment a firing happens - a gate waiting on three spawns counts things that
occur between two ticks, and a tally held in a process's memory is one a restart
silently zeroes - and the runner's tick reads it.

A gate that never opens is HELD, with no automatic advance and no authored
timeout (org lead, 2026-09-02). What the engine owes instead is visibility:
`EVENT_PHASE_STALL_MS` takes the run's health to `stalled`, and `setHealth` is
now escalation-only so a later retry cannot demote it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T6t8mrAWhZU5vnyYgZTMtL

server/test/eventSpec.test.js

@@ -13,8 +13,11 @@
 //   • a dormant step blocks a PUBLISH and never a SAVE
 //   • two phases may not share a key, because `UNIQUE (run_id, phase, seq)`
 //     would silently collapse them into one at materialisation
-//   • a key a later phase owns (`advance`, `announcements`) is REFUSED rather
-//     than preserved, so no corpus of unvalidated specs accumulates
+//   • a key a later phase owns (`announcements`) is REFUSED rather than
+//     preserved, so no corpus of unvalidated specs accumulates
+//   • a phase's `advance` gate (Phase 5) is checked at SAVE against the
+//     trigger's declaration with the offending variable named, and a gate on an
+//     unregistered trigger is dormant on exactly the rule a step's action is
 process.env.DB_HOST = '127.0.0.1'
 process.env.DB_PORT = '59999'
 
@@ -184,12 +187,166 @@ test('a key a later phase owns is refused, not silently preserved', () => {
   assert.equal(top.ok, false)
   assert.match(top.errors.join('\n'), /unknown key "announcements"/)
 
+  // `advance` was one of these until Phase 5 gave it a meaning; the refusal
+  // moved down a level rather than going away, and a key inside a gate that no
+  // shape declares is refused on the same argument.
   const phase = spec.validate({
     schedule: { kind: 'manual' },
-    phases: [{ key: 'main', label: 'Main', steps: [], advance: { after: '30m' } }],
+    phases: [{ key: 'main', label: 'Main', steps: [], advance: { after: '30m', timeout: '2h' } }],
   })
   assert.equal(phase.ok, false)
-  assert.match(phase.errors.join('\n'), /unknown key\(s\) advance .*Phase 5/)
+  assert.match(phase.errors.join('\n'), /unknown key\(s\) timeout for an "after" gate/)
+})
+
+// -- The advance gate (Phase 5) --------------------------------------------
+//
+// The phase's stated trap: a condition is checked at SAVE against the trigger's
+// declaration, with the offending variable NAMED. A predicate that silently
+// reads `undefined` is a phase that silently never advances, and the night you
+// find out is the night of the event.
+
+test('an `after` gate normalises its duration the way `days` is normalised', () => {
+  const ok = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [{ key: 'main', label: 'Main', steps: [], advance: { after: '120m' } }],
+  })
+  assert.equal(ok.ok, true)
+  assert.deepEqual(ok.spec.phases[0].advance, { after: '2h' }, 'two spellings of one delay are one spec')
+  assert.equal(spec.parseAfter('2h'), 7200)
+  assert.equal(spec.formatAfter(5400), '90m', 'and a duration with no whole larger unit keeps the smaller one')
+
+  for (const bad of ['0s', '30', '1h30m', 'soon', '0.5h', `${31 * 86_400}s`]) {
+    const result = spec.validate({
+      schedule: { kind: 'manual' },
+      phases: [{ key: 'main', label: 'Main', steps: [], advance: { after: bad } }],
+    })
+    assert.equal(result.ok, false, `"${bad}" should not validate`)
+    assert.match(result.errors.join('\n'), /expected a duration like "30m"/)
+  }
+})
+
+test('an `on` gate is validated against the trigger declaration, and names the variable', () => {
+  const bad = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      {
+        key: 'main',
+        label: 'Main',
+        steps: [],
+        advance: { on: 'news.post', where: { variable: 'reigon', cmp: 'eq', value: 'Yew' } },
+      },
+    ],
+  })
+  assert.equal(bad.ok, false)
+  assert.match(bad.errors.join('\n'), /"reigon" is not a variable of "news.post"/)
+  assert.match(bad.errors.join('\n'), /spec\.phases\[0\]\.advance\.where/, 'and it says which phase')
+
+  // The type check is the grammar's, unchanged: `gt` on a string is refused at
+  // save rather than quietly answering false for ever.
+  const typed = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      { key: 'main', label: 'Main', steps: [], advance: { on: 'news.post', where: { variable: 'title', cmp: 'gt', value: 'x' } } },
+    ],
+  })
+  assert.equal(typed.ok, false)
+  assert.match(typed.errors.join('\n'), /"gt" cannot be applied to a string/)
+
+  const ok = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      {
+        key: 'main',
+        label: 'Main',
+        steps: [],
+        advance: { on: 'news.post', where: { variable: 'category', cmp: 'eq', value: 'Five on Friday' }, count: 3 },
+      },
+    ],
+  })
+  assert.equal(ok.ok, true)
+  assert.deepEqual(ok.spec.phases[0].advance, {
+    on: 'news.post',
+    where: { variable: 'category', cmp: 'eq', value: 'Five on Friday' },
+    count: 3,
+    dormant: false,
+  })
+})
+
+test('a gate on an unregistered trigger is dormant: it saves, and it will not publish', () => {
+  const result = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      { key: 'main', label: 'Main', steps: [], advance: { on: 'gone.trigger', where: { variable: 'x', cmp: 'eq', value: 1 } } },
+    ],
+  })
+  assert.equal(result.ok, true, 'uninstalling a module must not be destructive to an author’s work')
+  assert.equal(result.spec.phases[0].advance.dormant, true)
+  assert.deepEqual(
+    result.spec.phases[0].advance.where,
+    { variable: 'x', cmp: 'eq', value: 1 },
+    'and the predicate is kept, not deleted for want of a declaration to check it against',
+  )
+
+  const pub = spec.publishable(result.spec)
+  assert.equal(pub.ok, false)
+  assert.deepEqual(pub.dormant, ['gone.trigger'], 'the same list a dormant ACTION lands in, and the same message')
+})
+
+test('a gate names exactly one shape, and its count is bounded', () => {
+  const both = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [{ key: 'main', label: 'Main', steps: [], advance: { after: '1h', on: 'news.post' } }],
+  })
+  assert.equal(both.ok, false)
+  assert.match(both.errors.join('\n'), /exactly one of "after" or "on"/)
+
+  const neither = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [{ key: 'main', label: 'Main', steps: [], advance: {} }],
+  })
+  assert.equal(neither.ok, false)
+
+  for (const count of [0, -1, 1.5, spec.MAX_ADVANCE_COUNT + 1]) {
+    const result = spec.validate({
+      schedule: { kind: 'manual' },
+      phases: [{ key: 'main', label: 'Main', steps: [], advance: { on: 'news.post', count } }],
+    })
+    assert.equal(result.ok, false, `count ${count} should not validate`)
+  }
+})
+
+test('validate accepts its own output — the walk found this one', () => {
+  // A saved spec is re-validated on every later save and AGAIN AT PUBLISH.
+  // `validate` normalises a gate with `dormant`, and the first draft refused
+  // that key on the way back in: the definition saved, and then publishing it
+  // answered 400 over a field the validator itself had written. The rule was
+  // already on the page for a step's `actionVersion` and `dormant`; the gate
+  // just had to follow it. `validate(validate(x)) === validate(x)`.
+  const once = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      { key: 'a', label: 'A', steps: [], advance: { on: 'news.post', where: { variable: 'title', cmp: 'present' }, count: 2 } },
+      { key: 'b', label: 'B', steps: [], advance: { after: '15m' } },
+    ],
+  })
+  assert.equal(once.ok, true)
+  const twice = spec.validate(once.spec)
+  assert.equal(twice.ok, true, twice.errors?.join('; '))
+  assert.deepEqual(twice.spec, once.spec)
+
+  // And `dormant` is RECOMPUTED, never trusted: a spec claiming a dead trigger
+  // is fine must not publish just because it says so.
+  const lying = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [{ key: 'a', label: 'A', steps: [], advance: { on: 'gone.trigger', count: 1, dormant: false } }],
+  })
+  assert.equal(lying.spec.phases[0].advance.dormant, true)
+})
+
+test('a phase with no gate carries no `advance` key at all', () => {
+  const result = spec.validate({ schedule: { kind: 'manual' }, phases: [{ key: 'main', label: 'Main', steps: [] }] })
+  assert.equal(result.ok, true)
+  assert.equal('advance' in result.spec.phases[0], false, 'so one phase gaining a gate is not a diff on every phase')
 })
 
 // ── The schedule shapes (Phase 4) ────────────────────────────────────