@shipfox/api-definitions 13.1.0 → 14.0.0

package/src/core/workflow-model/normalize-workflow-document.test.ts

@@ -2,7 +2,11 @@ import type {AgentValidationCatalog} from '@shipfox/api-agent-dto/inter-module';
 import type {WorkflowDocument} from '@shipfox/workflow-document';
 import {agentValidationCatalog} from '#test/agent-validation-catalog.js';
 import type {IntegrationValidationContext} from '../entities/integration-context.js';
-import {InvalidWorkflowModelError} from './invalid-workflow-model-error.js';
+import type {WorkflowModel} from '../entities/workflow-model.js';
+import {
+  InvalidWorkflowModelError,
+  type WorkflowModelValidationIssue,
+} from './invalid-workflow-model-error.js';
 import {DEFAULT_JOB_CHECKOUT} from './normalize-job-checkout.js';
 import {normalizeWorkflowDocument as normalizeWorkflowDocumentBase} from './normalize-workflow-document.js';
 
@@ -34,6 +38,16 @@ function expectInvalid(
   }
 }
 
+function normalizeWithDiagnostics(
+  document: WorkflowDocument,
+  options?: Omit<Parameters<typeof normalizeWorkflowDocumentBase>[1], 'agentValidationCatalog'> &
+    Partial<Pick<Parameters<typeof normalizeWorkflowDocumentBase>[1], 'agentValidationCatalog'>>,
+): {model: WorkflowModel; diagnostics: WorkflowModelValidationIssue[]} {
+  const diagnostics: WorkflowModelValidationIssue[] = [];
+  const model = normalizeWorkflowDocument(document, {...options, diagnostics});
+  return {model, diagnostics};
+}
+
 function interpolation(source: string): string {
   return '$'.concat('{{ ', source, ' }}');
 }
@@ -86,6 +100,13 @@ const integrationValidationContext = {
     ['linear-main', {id: 'conn_3', provider: 'linear', capabilities: ['agent_tools']}],
     ['jira-main', {id: 'conn_4', provider: 'jira', capabilities: ['agent_tools']}],
   ]),
+  eventCatalogs: new Map([
+    ['github', new Set(['push', 'pull_request.opened'])],
+    ['sentry', new Set(['issue.created'])],
+    ['linear', new Set(['Issue'])],
+    ['jira', new Set(['jira:issue_created'])],
+  ]),
+  fixedEventProviders: new Set(['webhook']),
   defaultConnectionSlug: 'github-main',
 } satisfies IntegrationValidationContext;
 
@@ -779,6 +800,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Provider "github-copilot" is not supported.',
         path: ['jobs', 'fix', 'steps', 0, 'provider'],
         details: {provider: 'github-copilot'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -829,6 +852,8 @@ describe('normalizeWorkflowDocument', () => {
           'Agent model "not-a-model" is not available for harness "pi" and provider "anthropic".',
         path: ['jobs', 'fix', 'steps', 0, 'model'],
         details: {harness: 'pi', provider: 'anthropic', model: 'not-a-model'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -902,6 +927,8 @@ describe('normalizeWorkflowDocument', () => {
           'Harness "claude" does not support provider: openai. Supported providers: anthropic.',
         path: ['jobs', 'fix', 'steps', 0, 'provider'],
         details: {harness: 'claude', provider: 'openai', supportedProviders: ['anthropic']},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -940,6 +967,8 @@ describe('normalizeWorkflowDocument', () => {
             'get_search_content',
           ],
         },
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -982,6 +1011,8 @@ describe('normalizeWorkflowDocument', () => {
           'Agent step tools require an explicit harness because tool names are harness-specific.',
         path: ['jobs', 'fix', 'steps', 0, 'tools'],
         details: {tools: ['Read']},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -1069,6 +1100,8 @@ describe('normalizeWorkflowDocument', () => {
         thinking: 'off',
         supportedLevels: ['low', 'medium', 'high', 'xhigh', 'max'],
       },
+      severity: 'error',
+      scope: 'definition',
     });
   });
 
@@ -1434,6 +1467,78 @@ describe('normalizeWorkflowDocument', () => {
     ]);
   });
 
+  it('reports missing resolution sources when every until matcher is inert', () => {
+    const document: WorkflowDocument = {
+      name: 'listen forever',
+      jobs: {
+        review: {
+          listening: {
+            on: [{source: 'github', event: 'pull_request_review'}],
+            until: [{source: 'github', event: 'pull_request', filter: 'event.action'}],
+          },
+          steps: [{run: 'echo ok'}],
+        },
+      },
+    };
+
+    const diagnostics: WorkflowModelValidationIssue[] = [];
+    let error: InvalidWorkflowModelError | undefined;
+    try {
+      normalizeWorkflowDocument(document, {diagnostics});
+      expect.fail('Expected InvalidWorkflowModelError');
+    } catch (caught) {
+      expect(caught).toBeInstanceOf(InvalidWorkflowModelError);
+      error = caught as InvalidWorkflowModelError;
+    }
+
+    expect(error?.issues).toEqual([
+      expect.objectContaining({
+        code: 'listening-job-missing-resolution-source',
+        path: ['jobs', 'review', 'listening'],
+      }),
+    ]);
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        code: 'invalid-listener-filter',
+        path: ['jobs', 'review', 'listening', 'until', 0, 'filter'],
+        severity: 'error',
+        scope: 'trigger',
+      }),
+    ]);
+  });
+
+  it('drops inert until matchers from the model when a timeout resolves the job', () => {
+    const document: WorkflowDocument = {
+      name: 'listen with timeout',
+      jobs: {
+        review: {
+          listening: {
+            on: [{source: 'github', event: 'pull_request_review'}],
+            until: [{source: 'github', event: 'pull_request', filter: 'event.action'}],
+            timeout: '1h',
+          },
+          steps: [{run: 'echo ok'}],
+        },
+      },
+    };
+
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
+
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        code: 'invalid-listener-filter',
+        path: ['jobs', 'review', 'listening', 'until', 0, 'filter'],
+        severity: 'error',
+        scope: 'trigger',
+      }),
+    ]);
+    expect(model.jobs[0]?.listening).toMatchObject({
+      on: [{source: 'github', event: 'pull_request_review'}],
+      timeoutMs: 60 * 60 * 1000,
+    });
+    expect(model.jobs[0]?.listening).not.toHaveProperty('until');
+  });
+
   it('reports listening timeouts above the run timeout', () => {
     const document: WorkflowDocument = {
       name: 'too long',
@@ -1503,7 +1608,6 @@ describe('normalizeWorkflowDocument', () => {
     ['executions root', 'executions.size() > 0', 'context-unavailable-at-predicate-site'],
     ['matrix root', 'matrix.os == "linux"', 'context-unavailable-at-predicate-site'],
     ['runner root', 'runner.os == "linux"', 'runner-context-in-server-predicate'],
-    ['non-boolean source', 'event.action', 'invalid-listener-filter'],
   ] as const)('reports invalid listener on filters for %s', (_label, filter, code) => {
     const document: WorkflowDocument = {
       name: 'invalid listener filter',
@@ -1532,6 +1636,70 @@ describe('normalizeWorkflowDocument', () => {
     ]);
   });
 
+  it('rejects a listening job whose only on matcher is inert', () => {
+    const document: WorkflowDocument = {
+      name: 'invalid listener filter',
+      jobs: {
+        review: {
+          listening: {
+            on: [{source: 'github', event: 'pull_request_review', filter: 'event.action'}],
+            max_executions: 1,
+          },
+          steps: [{run: 'echo ok'}],
+        },
+      },
+    };
+
+    const error = expectInvalid(document);
+
+    expect(error.issues).toEqual([
+      expect.objectContaining({
+        code: 'listening-job-no-active-matcher',
+        path: ['jobs', 'review', 'listening', 'on'],
+      }),
+    ]);
+  });
+
+  it('makes an invalid listener on matcher inert and keeps the others active', () => {
+    const document: WorkflowDocument = {
+      name: 'invalid listener filter',
+      jobs: {
+        review: {
+          listening: {
+            on: [
+              {source: 'github', event: 'pull_request_review', filter: 'event.action'},
+              {
+                source: 'github',
+                event: 'pull_request_review',
+                filter: 'event.action == "submitted"',
+              },
+            ],
+            max_executions: 1,
+          },
+          steps: [{run: 'echo ok'}],
+        },
+      },
+    };
+
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
+
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        code: 'invalid-listener-filter',
+        path: ['jobs', 'review', 'listening', 'on', 0, 'filter'],
+        details: expect.objectContaining({
+          field: 'listener.on',
+          source: 'event.action',
+        }),
+        severity: 'error',
+        scope: 'trigger',
+      }),
+    ]);
+    expect(model.jobs[0]?.listening?.on).toEqual([
+      {source: 'github', event: 'pull_request_review', filter: 'event.action == "submitted"'},
+    ]);
+  });
+
   it('rejects listener filters that reference jobs without a direct needs edge', () => {
     const document: WorkflowDocument = {
       name: 'listener missing needs',
@@ -3175,6 +3343,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Duration must be an integer followed by ms, s, m, h, or d.',
         path: ['jobs', 'build', 'execution_timeout'],
         details: {source: 'ten minutes'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3198,6 +3368,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Duration must be between 1s and 24h.',
         path: ['jobs', 'build', 'execution_timeout'],
         details: {source: '999ms', min_ms: 1000, max_ms: 24 * 60 * 60 * 1000},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3221,6 +3393,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Duration must be between 1s and 24h.',
         path: ['jobs', 'build', 'execution_timeout'],
         details: {source: '25h', min_ms: 1000, max_ms: 24 * 60 * 60 * 1000},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3244,6 +3418,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Duration must be between 1s and 24h.',
         path: ['jobs', 'build', 'execution_timeout'],
         details: {source: '30d', min_ms: 1000, max_ms: 24 * 60 * 60 * 1000},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3336,6 +3512,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Step "build-review" must restart from an earlier keyed step; found "producer".',
         path: ['jobs', 'build', 'steps', 0, 'gate', 'on_failure'],
         details: {stepId: 'build-review', restartFrom: 'producer'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3364,6 +3542,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Step "build-review" must restart from an earlier keyed step; found "review".',
         path: ['jobs', 'build', 'steps', 0, 'gate', 'on_failure'],
         details: {stepId: 'build-review', restartFrom: 'review'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3393,6 +3573,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Step "build-review" must restart from an earlier keyed step; found "producer".',
         path: ['jobs', 'build', 'steps', 0, 'gate', 'on_failure'],
         details: {stepId: 'build-review', restartFrom: 'producer'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3416,6 +3598,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Job "test" depends on unknown job "build".',
         path: ['jobs', 'test', 'needs'],
         details: {job: 'test', dependency: 'build'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3439,6 +3623,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Job "test" depends on itself.',
         path: ['jobs', 'test', 'needs'],
         details: {job: 'test'},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3466,6 +3652,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Circular dependency detected among jobs: build, test.',
         path: ['jobs'],
         details: {cycleSourceNames: ['build', 'test'], cycleJobIds: ['build', 'test']},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3497,6 +3685,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Circular dependency detected among jobs: build, test.',
         path: ['jobs'],
         details: {cycleSourceNames: ['build', 'test'], cycleJobIds: ['build', 'test']},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3522,6 +3712,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Job keys "build app" and "build-app" resolve to the same stable id "build-app".',
         path: ['jobs', 'build-app'],
         details: {id: 'build-app', sourceKeys: ['build app', 'build-app']},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3547,7 +3739,7 @@ describe('normalizeWorkflowDocument', () => {
     ]);
   });
 
-  it('reports stable trigger id collisions', () => {
+  it('reports stable trigger id collisions with the later trigger inert', () => {
     const document: WorkflowDocument = {
       name: 'trigger collision',
       triggers: {
@@ -3561,17 +3753,20 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'duplicate-trigger-id',
         message:
           'Trigger keys "main_push" and "main push" resolve to the same stable id "main-push".',
         path: ['triggers', 'main push'],
         details: {id: 'main-push', sourceKeys: ['main_push', 'main push']},
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers.map((trigger) => trigger.key)).toEqual(['main_push']);
   });
 
   it('reports stable step id collisions inside a job', () => {
@@ -3592,6 +3787,8 @@ describe('normalizeWorkflowDocument', () => {
         message: 'Steps 0 and 1 in job "build" resolve to the same stable id "build-step-1".',
         path: ['jobs', 'build', 'steps', 1],
         details: {id: 'build-step-1', indexes: [0, 1]},
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
@@ -3675,17 +3872,6 @@ describe('normalizeWorkflowDocument', () => {
         site: 'ingest',
       },
     ],
-    [
-      'non-boolean shape',
-      'event.ref',
-      'invalid-trigger-filter',
-      {
-        field: 'trigger.filter',
-        source: 'event.ref',
-        contextRoots: ['event'],
-        reason: 'Predicate source must be boolean-shaped.',
-      },
-    ],
   ] as const)('rejects trigger filters with %s', (_label, filter, code, details) => {
     const document: WorkflowDocument = {
       name: 'invalid trigger filter',
@@ -3711,11 +3897,50 @@ describe('normalizeWorkflowDocument', () => {
         message: expect.any(String),
         path: ['triggers', 'main', 'filter'],
         details,
+        severity: 'error',
+        scope: 'definition',
       },
     ]);
   });
 
-  it.each(['manual', 'cron'] as const)('rejects filters on %s triggers', (source) => {
+  it('makes a trigger with a non-boolean filter inert', () => {
+    const document: WorkflowDocument = {
+      name: 'invalid trigger filter',
+      triggers: {
+        main: {
+          source: 'github',
+          event: 'push',
+          filter: 'event.ref',
+        },
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'npm run build'}],
+        },
+      },
+    };
+
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
+
+    expect(diagnostics).toEqual([
+      {
+        code: 'invalid-trigger-filter',
+        message: expect.any(String),
+        path: ['triggers', 'main', 'filter'],
+        details: {
+          field: 'trigger.filter',
+          source: 'event.ref',
+          contextRoots: ['event'],
+          reason: 'Predicate source must be boolean-shaped.',
+        },
+        severity: 'error',
+        scope: 'trigger',
+      },
+    ]);
+    expect(model.triggers).toEqual([]);
+  });
+
+  it.each(['manual', 'cron'] as const)('makes a %s trigger with a filter inert', (source) => {
     const document: WorkflowDocument = {
       name: 'unsupported trigger filter',
       triggers: {
@@ -3733,16 +3958,19 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'invalid-trigger-filter',
         message: `A ${source} trigger cannot define a filter because it does not receive an event payload.`,
         path: ['triggers', 'main', 'filter'],
         details: {source: 'event.ref == "refs/heads/main"', triggerSource: source},
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers).toEqual([]);
   });
 
   it('maps trigger with values to model inputs', () => {
@@ -3844,7 +4072,64 @@ describe('normalizeWorkflowDocument', () => {
     ]);
   });
 
-  it('reports a cron trigger with a non-tick event', () => {
+  it('materializes fire for a manual trigger with the event omitted', () => {
+    const document: WorkflowDocument = {
+      name: 'manual trigger',
+      triggers: {
+        manual: {source: 'manual'},
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'npm run build'}],
+        },
+      },
+    };
+
+    const model = normalizeWorkflowDocument(document);
+
+    expect(model.triggers).toEqual([
+      {
+        id: 'manual',
+        key: 'manual',
+        source: 'manual',
+        event: 'fire',
+      },
+    ]);
+  });
+
+  it('materializes tick for a cron trigger with the event omitted', () => {
+    const document: WorkflowDocument = {
+      name: 'nightly trigger',
+      triggers: {
+        nightly: {
+          source: 'cron',
+          config: {schedule: '0 2 * * *'},
+        },
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'npm run build'}],
+        },
+      },
+    };
+
+    const model = normalizeWorkflowDocument(document);
+
+    expect(model.triggers).toEqual([
+      {
+        id: 'nightly',
+        key: 'nightly',
+        source: 'cron',
+        event: 'tick',
+        config: {
+          schedule: '0 2 * * *',
+          timezone: 'UTC',
+        },
+      },
+    ]);
+  });
+
+  it('makes a cron trigger with a non-tick event inert', () => {
     const document: WorkflowDocument = {
       name: 'nightly trigger',
       triggers: {
@@ -3861,19 +4146,58 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'invalid-cron-event',
         message: 'A cron trigger must use event "tick"; found "push".',
         path: ['triggers', 'nightly', 'event'],
         details: {event: 'push'},
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers).toEqual([]);
   });
 
-  it('reports a cron trigger without a schedule', () => {
+  it('keeps the event absent for integration triggers with the event omitted', () => {
+    const document: WorkflowDocument = {
+      name: 'source subscriptions',
+      triggers: {
+        on_any_deploy: {
+          source: 'deploy_hook',
+        },
+        on_any_github_event: {
+          source: 'github_acme',
+        },
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'npm run build'}],
+        },
+      },
+    };
+
+    const model = normalizeWorkflowDocument(document);
+
+    expect(model.triggers).toEqual([
+      {
+        id: 'on-any-deploy',
+        key: 'on_any_deploy',
+        source: 'deploy_hook',
+      },
+      {
+        id: 'on-any-github-event',
+        key: 'on_any_github_event',
+        source: 'github_acme',
+      },
+    ]);
+    expect(model.triggers[0]).not.toHaveProperty('event');
+    expect(model.triggers[1]).not.toHaveProperty('event');
+  });
+
+  it('makes a cron trigger without a schedule inert', () => {
     const document: WorkflowDocument = {
       name: 'nightly trigger',
       triggers: {
@@ -3889,22 +4213,25 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'missing-cron-schedule',
         message: 'A cron trigger requires a schedule.',
         path: ['triggers', 'nightly', 'config', 'schedule'],
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers).toEqual([]);
   });
 
   it.each([
     ['malformed', 'not a cron'],
     ['6-field', '0 0 2 * * *'],
     ['preset', '@daily'],
-  ])('reports an invalid %s cron schedule', (_label, schedule) => {
+  ])('makes a cron trigger with an invalid %s schedule inert', (_label, schedule) => {
     const document: WorkflowDocument = {
       name: 'nightly trigger',
       triggers: {
@@ -3921,19 +4248,22 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'invalid-cron-schedule',
         message: 'Cron trigger schedule must be a valid 5-field cron expression.',
         path: ['triggers', 'nightly', 'config', 'schedule'],
         details: {schedule},
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers).toEqual([]);
   });
 
-  it('reports an invalid cron timezone', () => {
+  it('makes a cron trigger with an invalid timezone inert', () => {
     const document: WorkflowDocument = {
       name: 'nightly trigger',
       triggers: {
@@ -3953,16 +4283,19 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'invalid-cron-timezone',
         message: 'Cron trigger timezone must be a valid IANA time zone.',
         path: ['triggers', 'nightly', 'config', 'timezone'],
         details: {timezone: 'Not/A/Zone'},
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers).toEqual([]);
   });
 
   it('allows multiple cron triggers', () => {
@@ -4010,7 +4343,47 @@ describe('normalizeWorkflowDocument', () => {
     expect(model.triggers).toMatchObject([{id: 'manual', source: 'manual', event: 'fire'}]);
   });
 
-  it('reports multiple manual triggers as a semantic rule', () => {
+  it('keeps other triggers active when a cron trigger is inert', () => {
+    const document: WorkflowDocument = {
+      name: 'partially broken triggers',
+      triggers: {
+        nightly: {
+          source: 'cron',
+          event: 'tick',
+          config: {schedule: 'not a cron'},
+        },
+        on_demand: {source: 'manual', event: 'fire'},
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'npm run build'}],
+        },
+      },
+    };
+
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
+
+    expect(diagnostics).toEqual([
+      {
+        code: 'invalid-cron-schedule',
+        message: 'Cron trigger schedule must be a valid 5-field cron expression.',
+        path: ['triggers', 'nightly', 'config', 'schedule'],
+        details: {schedule: 'not a cron'},
+        severity: 'error',
+        scope: 'trigger',
+      },
+    ]);
+    expect(model.triggers).toEqual([
+      {
+        id: 'on-demand',
+        key: 'on_demand',
+        source: 'manual',
+        event: 'fire',
+      },
+    ]);
+  });
+
+  it('keeps the first manual trigger active and makes later ones inert', () => {
     const document: WorkflowDocument = {
       name: 'manual triggers',
       triggers: {
@@ -4024,16 +4397,51 @@ describe('normalizeWorkflowDocument', () => {
       },
     };
 
-    const error = expectInvalid(document);
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
 
-    expect(error.issues).toEqual([
+    expect(diagnostics).toEqual([
       {
         code: 'multiple-manual-triggers',
-        message: 'A workflow may declare at most one manual trigger; found 2: one, two.',
-        path: ['triggers'],
+        message:
+          'A workflow may declare at most one manual trigger; found 2: one, two. This trigger is inert because it is not the first manual trigger in document order.',
+        path: ['triggers', 'two'],
         details: {manualTriggerKeys: ['one', 'two']},
+        severity: 'error',
+        scope: 'trigger',
       },
     ]);
+    expect(model.triggers.map((trigger) => trigger.key)).toEqual(['one']);
+  });
+
+  it('promotes the first valid manual trigger when an earlier one is inert', () => {
+    const document: WorkflowDocument = {
+      name: 'manual triggers with an inert first trigger',
+      triggers: {
+        broken: {
+          source: 'manual',
+          event: 'fire',
+          filter: 'event.ref == "refs/heads/main"',
+        },
+        working: {source: 'manual', event: 'fire'},
+      },
+      jobs: {
+        build: {
+          steps: [{run: 'npm run build'}],
+        },
+      },
+    };
+
+    const {model, diagnostics} = normalizeWithDiagnostics(document);
+
+    expect(diagnostics).toEqual([
+      expect.objectContaining({
+        code: 'invalid-trigger-filter',
+        path: ['triggers', 'broken', 'filter'],
+        severity: 'error',
+        scope: 'trigger',
+      }),
+    ]);
+    expect(model.triggers.map((trigger) => trigger.key)).toEqual(['working']);
   });
 
   it('accumulates independent semantic issues in one pass', () => {