@shipfox/api-definitions 12.3.0 → 14.0.0

package/src/db/definitions.ts

@@ -5,7 +5,19 @@ import {
 } from '@shipfox/api-definitions-dto';
 import {writeOutboxEvent} from '@shipfox/node-outbox';
 import type {WorkflowDocument} from '@shipfox/workflow-document';
-import {and, asc, eq, gt, isNull, notInArray, or, type SQL, sql} from 'drizzle-orm';
+import {
+  and,
+  asc,
+  eq,
+  gt,
+  inArray,
+  isNotNull,
+  isNull,
+  notInArray,
+  or,
+  type SQL,
+  sql,
+} from 'drizzle-orm';
 import type {
   WorkflowDefinition,
   WorkflowDefinitionPayload,
@@ -14,8 +26,9 @@ import type {
 import type {WorkflowModel} from '#core/entities/workflow-model.js';
 import {db} from './db.js';
 import {definitionTriggersFor} from './definition-triggers.js';
-import {toDefinition, workflowDefinitions} from './schema/definitions.js';
+import {type DefinitionDb, toDefinition, workflowDefinitions} from './schema/definitions.js';
 import {definitionsOutbox} from './schema/outbox.js';
+import {workflowWorkflows} from './schema/workflows.js';
 
 type Tx = Parameters<Parameters<ReturnType<typeof db>['transaction']>[0]>[0];
 
@@ -33,7 +46,155 @@ export interface UpsertDefinitionParams {
   ref?: string | undefined;
 }
 
-function buildUpsertQuery(tx: Tx, params: UpsertDefinitionParams) {
+/**
+ * Finds or creates the workflow lineage for (projectId, configPath) and returns
+ * its id. Pathless manual definitions share a project-scoped lineage because
+ * their request has no more specific stable key.
+ */
+async function findOrCreateWorkflow(
+  tx: Tx,
+  params: {projectId: string; configPath: string | null},
+): Promise<string> {
+  if (params.configPath === null) {
+    // Serialize the first pathless definition for a project so concurrent saves
+    // cannot create multiple project-scoped lineages.
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${params.projectId}, 0))`);
+    const existing = await tx
+      .select({workflowId: workflowDefinitions.workflowId})
+      .from(workflowDefinitions)
+      .where(
+        and(
+          eq(workflowDefinitions.projectId, params.projectId),
+          isNull(workflowDefinitions.configPath),
+          eq(workflowDefinitions.source, 'manual'),
+          isNotNull(workflowDefinitions.workflowId),
+        ),
+      )
+      .orderBy(asc(workflowDefinitions.createdAt), asc(workflowDefinitions.id))
+      .limit(1);
+    const existingRow = existing[0];
+    if (existingRow?.workflowId) return existingRow.workflowId;
+
+    const inserted = await tx
+      .insert(workflowWorkflows)
+      .values({projectId: params.projectId, configPath: null})
+      .onConflictDoNothing()
+      .returning({id: workflowWorkflows.id});
+    const insertedRow = inserted[0];
+    if (insertedRow) return insertedRow.id;
+
+    const existingLineage = await tx
+      .select({id: workflowWorkflows.id})
+      .from(workflowWorkflows)
+      .where(
+        and(
+          eq(workflowWorkflows.projectId, params.projectId),
+          isNull(workflowWorkflows.configPath),
+        ),
+      )
+      .limit(1);
+    const existingLineageRow = existingLineage[0];
+    if (!existingLineageRow) {
+      throw new Error(`Pathless workflow lineage missing for project ${params.projectId}`);
+    }
+    return existingLineageRow.id;
+  }
+
+  const inserted = await tx
+    .insert(workflowWorkflows)
+    .values({projectId: params.projectId, configPath: params.configPath})
+    .onConflictDoNothing()
+    .returning({id: workflowWorkflows.id});
+  const insertedRow = inserted[0];
+  if (insertedRow) return insertedRow.id;
+
+  const existing = await tx
+    .select({id: workflowWorkflows.id})
+    .from(workflowWorkflows)
+    .where(
+      and(
+        eq(workflowWorkflows.projectId, params.projectId),
+        eq(workflowWorkflows.configPath, params.configPath),
+      ),
+    )
+    .limit(1);
+  const existingRow = existing[0];
+  if (!existingRow) {
+    throw new Error(
+      `Workflow lineage upsert returned no row for project ${params.projectId} and config path ${params.configPath}`,
+    );
+  }
+  return existingRow.id;
+}
+
+async function findOrCreateWorkflows(
+  tx: Tx,
+  params: {projectId: string; configPaths: string[]},
+): Promise<Map<string, string>> {
+  const configPaths = [...new Set(params.configPaths)].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+  if (configPaths.length === 0) return new Map();
+
+  await tx
+    .insert(workflowWorkflows)
+    .values(configPaths.map((configPath) => ({projectId: params.projectId, configPath})))
+    .onConflictDoNothing();
+
+  const rows = await tx
+    .select({id: workflowWorkflows.id, configPath: workflowWorkflows.configPath})
+    .from(workflowWorkflows)
+    .where(
+      and(
+        eq(workflowWorkflows.projectId, params.projectId),
+        inArray(workflowWorkflows.configPath, configPaths),
+      ),
+    );
+  const workflowIds = new Map<string, string>();
+  for (const row of rows) {
+    if (row.configPath !== null) workflowIds.set(row.configPath, row.id);
+  }
+  for (const configPath of configPaths) {
+    if (!workflowIds.has(configPath)) {
+      throw new Error(
+        `Workflow lineage upsert returned no row for project ${params.projectId} and config path ${configPath}`,
+      );
+    }
+  }
+  return workflowIds;
+}
+
+async function ensureWorkflowId(
+  tx: Tx,
+  row: Pick<DefinitionDb, 'id' | 'projectId' | 'configPath' | 'workflowId'>,
+): Promise<string> {
+  if (row.workflowId !== null) return row.workflowId;
+
+  const workflowId = await findOrCreateWorkflow(tx, {
+    projectId: row.projectId,
+    configPath: row.configPath,
+  });
+  const updated = await tx
+    .update(workflowDefinitions)
+    .set({workflowId})
+    .where(and(eq(workflowDefinitions.id, row.id), isNull(workflowDefinitions.workflowId)))
+    .returning({workflowId: workflowDefinitions.workflowId});
+  const updatedRow = updated[0];
+  if (updatedRow?.workflowId) return updatedRow.workflowId;
+
+  const current = await tx
+    .select({workflowId: workflowDefinitions.workflowId})
+    .from(workflowDefinitions)
+    .where(eq(workflowDefinitions.id, row.id))
+    .limit(1);
+  const currentRow = current[0];
+  if (!currentRow?.workflowId) {
+    throw new Error(`Definition ${row.id} still has no workflow lineage after reconciliation`);
+  }
+  return currentRow.workflowId;
+}
+
+function buildUpsertQuery(tx: Tx, params: UpsertDefinitionParams & {workflowId: string}) {
   const source = params.source ?? 'manual';
   if (source === 'vcs' && !params.configPath) {
     throw new Error('configPath is required for VCS definitions');
@@ -54,6 +215,7 @@ function buildUpsertQuery(tx: Tx, params: UpsertDefinitionParams) {
   };
 
   const set = {
+    workflowId: params.workflowId,
     name: params.name,
     source,
     definition,
@@ -65,6 +227,7 @@ function buildUpsertQuery(tx: Tx, params: UpsertDefinitionParams) {
 
   const values = {
     projectId: params.projectId,
+    workflowId: params.workflowId,
     configPath: params.configPath ?? null,
     source,
     sha: params.sha ?? null,
@@ -121,7 +284,11 @@ export async function upsertDefinition(
   params: UpsertDefinitionParams,
 ): Promise<WorkflowDefinition> {
   return await db().transaction(async (tx) => {
-    const rows = await buildUpsertQuery(tx, params);
+    const workflowId = await findOrCreateWorkflow(tx, {
+      projectId: params.projectId,
+      configPath: params.configPath ?? null,
+    });
+    const rows = await buildUpsertQuery(tx, {...params, workflowId});
     const row = rows[0];
     if (!row) throw new Error('Upsert returned no rows');
 
@@ -140,16 +307,68 @@ export async function upsertDefinition(
   });
 }
 
+/**
+ * Finds or creates the workflow lineage for (projectId, configPath) outside a
+ * sync. A dev definition uses the lineage for run numbering without ever
+ * persisting a definition row or publishing a resolution event.
+ */
+export async function findOrCreateWorkflowLineage(params: {
+  projectId: string;
+  configPath: string;
+}): Promise<string> {
+  return await db().transaction(async (tx) => {
+    return await findOrCreateWorkflow(tx, params);
+  });
+}
+
 export async function getDefinitionById(id: string): Promise<WorkflowDefinition | undefined> {
+  return await db().transaction(async (tx) => {
+    const rows = await tx
+      .select()
+      .from(workflowDefinitions)
+      .where(and(eq(workflowDefinitions.id, id), isNull(workflowDefinitions.deletedAt)))
+      .limit(1);
+    const row = rows[0];
+
+    if (row) {
+      const workflowId = await ensureWorkflowId(tx, row);
+      return toDefinition({...row, workflowId});
+    }
+
+    return undefined;
+  });
+}
+
+export async function getWorkflowLineageById(
+  id: string,
+): Promise<{id: string; projectId: string} | undefined> {
+  const rows = await db()
+    .select({id: workflowWorkflows.id, projectId: workflowWorkflows.projectId})
+    .from(workflowWorkflows)
+    .where(eq(workflowWorkflows.id, id))
+    .limit(1);
+
+  return rows[0];
+}
+
+export async function getDefinitionByWorkflowId(params: {
+  workflowId: string;
+  ref: string;
+}): Promise<WorkflowDefinition | undefined> {
   const rows = await db()
     .select()
     .from(workflowDefinitions)
-    .where(and(eq(workflowDefinitions.id, id), isNull(workflowDefinitions.deletedAt)))
+    .where(
+      and(
+        eq(workflowDefinitions.workflowId, params.workflowId),
+        eq(workflowDefinitions.ref, params.ref),
+        isNull(workflowDefinitions.deletedAt),
+      ),
+    )
     .limit(1);
   const row = rows[0];
 
-  if (!row) return undefined;
-  return toDefinition(row);
+  return row ? toDefinition({...row, workflowId: params.workflowId}) : undefined;
 }
 
 export interface DefinitionCursor {
@@ -179,28 +398,35 @@ function cursorWhere(cursor: DefinitionCursor | undefined): SQL | undefined {
 export async function listDefinitions(
   params: ListDefinitionsParams,
 ): Promise<ListDefinitionsResult> {
-  const conditions = [
-    eq(workflowDefinitions.projectId, params.projectId),
-    isNull(workflowDefinitions.deletedAt),
-  ];
-  const cursorCondition = cursorWhere(params.cursor);
-  if (cursorCondition) conditions.push(cursorCondition);
-
-  const rows = await db()
-    .select()
-    .from(workflowDefinitions)
-    .where(and(...conditions))
-    .orderBy(asc(workflowDefinitions.name), asc(workflowDefinitions.id))
-    .limit(params.limit + 1);
-
-  const hasMore = rows.length > params.limit;
-  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
-  const last = pageRows.at(-1);
+  return await db().transaction(async (tx) => {
+    const conditions = [
+      eq(workflowDefinitions.projectId, params.projectId),
+      isNull(workflowDefinitions.deletedAt),
+    ];
+    const cursorCondition = cursorWhere(params.cursor);
+    if (cursorCondition) conditions.push(cursorCondition);
+
+    const rows = await tx
+      .select()
+      .from(workflowDefinitions)
+      .where(and(...conditions))
+      .orderBy(asc(workflowDefinitions.name), asc(workflowDefinitions.id))
+      .limit(params.limit + 1);
+
+    const hasMore = rows.length > params.limit;
+    const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+    const last = pageRows.at(-1);
+    const definitions: WorkflowDefinition[] = [];
+    for (const row of pageRows) {
+      const workflowId = await ensureWorkflowId(tx, row);
+      definitions.push(toDefinition({...row, workflowId}));
+    }
 
-  return {
-    definitions: pageRows.map(toDefinition),
-    nextCursor: hasMore && last ? {value: last.name, id: last.id} : null,
-  };
+    return {
+      definitions,
+      nextCursor: hasMore && last ? {value: last.name, id: last.id} : null,
+    };
+  });
 }
 
 export async function listDefinitionsByProject(projectId: string): Promise<WorkflowDefinition[]> {
@@ -281,11 +507,17 @@ export async function applyVcsDefinitionsBatch(
 ): Promise<ApplyVcsDefinitionsBatchResult> {
   return await db().transaction(async (tx) => {
     let appliedCount = 0;
+    const prepared: Array<{
+      item: (typeof params.upserts)[number];
+      unchanged: boolean;
+      workflowId: string | null | undefined;
+    }> = [];
     for (const item of params.upserts) {
       const existing = await tx
         .select({
           contentHash: workflowDefinitions.contentHash,
           deletedAt: workflowDefinitions.deletedAt,
+          workflowId: workflowDefinitions.workflowId,
         })
         .from(workflowDefinitions)
         .where(
@@ -303,9 +535,31 @@ export async function applyVcsDefinitionsBatch(
         previous.deletedAt === null &&
         previous.contentHash === item.contentHash;
 
+      prepared.push({item, unchanged, workflowId: previous?.workflowId});
+    }
+
+    const workflowIds = await findOrCreateWorkflows(tx, {
+      projectId: params.projectId,
+      configPaths: prepared.filter(({unchanged}) => !unchanged).map(({item}) => item.configPath),
+    });
+
+    for (const {item, unchanged, workflowId: previousWorkflowId} of prepared) {
+      const workflowId = unchanged
+        ? (previousWorkflowId ??
+          (await findOrCreateWorkflow(tx, {
+            projectId: params.projectId,
+            configPath: item.configPath,
+          })))
+        : workflowIds.get(item.configPath);
+      if (!workflowId) {
+        throw new Error(
+          `Workflow lineage missing for project ${params.projectId} and config path ${item.configPath}`,
+        );
+      }
       const rows = await buildUpsertQuery(tx, {
         projectId: params.projectId,
         workspaceId: params.workspaceId,
+        workflowId,
         configPath: item.configPath,
         source: 'vcs',
         ref: params.ref,

package/src/db/index.ts

@@ -12,6 +12,7 @@ export type {
 } from './definitions.js';
 export {
   applyVcsDefinitionsBatch,
+  findOrCreateWorkflowLineage,
   getDefinitionById,
   invalidateCache,
   listDefinitions,
@@ -21,6 +22,7 @@ export {
 } from './definitions.js';
 export {definitionsOutbox} from './schema/outbox.js';
 export {definitionSyncStates} from './schema/sync-states.js';
+export {type WorkflowCreateDb, type WorkflowDb, workflowWorkflows} from './schema/workflows.js';
 export {
   type DefinitionSyncStateKey,
   getLatestDefinitionSyncState,

package/src/db/schema/definitions.test.ts

@@ -16,6 +16,7 @@ describe('toDefinition', () => {
     };
     const row: DefinitionDb = {
       id: '019e98ab-6656-7ca1-b9ad-1ca4442c479d',
+      workflowId: '019e98ab-6656-7ca1-b9ad-1ca4442c479e',
       projectId: '019e98ab-b90f-7265-b13c-8b441c991381',
       configPath: '.shipfox/workflows/manual.yml',
       source: 'manual',

package/src/db/schema/definitions.ts

@@ -6,6 +6,7 @@ import type {
   WorkflowDefinitionPayload,
 } from '#core/entities/workflow-definition.js';
 import {pgTable} from './common.js';
+import {workflowWorkflows} from './workflows.js';
 
 export const definitionSourceEnum = pgEnum('definitions_source', ['manual', 'vcs']);
 
@@ -13,6 +14,8 @@ export const workflowDefinitions = pgTable(
   'workflow_definitions',
   {
     id: uuidv7PrimaryKey(),
+    // Schema-only upgrades leave historical rows null until they are touched.
+    workflowId: uuid('workflow_id').references(() => workflowWorkflows.id),
     projectId: uuid('project_id').notNull(),
     configPath: text('config_path'),
     source: definitionSourceEnum('source').notNull().default('manual'),
@@ -41,6 +44,9 @@ export const workflowDefinitions = pgTable(
     index('definitions_wd_project_name_id_idx')
       .on(table.projectId, table.name, table.id)
       .where(sql`"deleted_at" IS NULL`),
+    index('definitions_wd_workflow_ref_lookup')
+      .on(table.workflowId, table.ref)
+      .where(sql`"ref" IS NOT NULL AND "deleted_at" IS NULL`),
     // Binds source to its git coordinates so the partial indexes above stay
     // unambiguous: vcs rows carry a ref or sha; manual rows carry neither.
     check(
@@ -55,8 +61,13 @@ export type DefinitionCreateDb = typeof workflowDefinitions.$inferInsert;
 export type DefinitionUpdateDb = Partial<DefinitionCreateDb>;
 
 export function toDefinition(row: DefinitionDb): WorkflowDefinition {
+  if (row.workflowId === null) {
+    throw new Error(`Definition ${row.id} has no workflow lineage`);
+  }
+
   return {
     id: row.id,
+    workflowId: row.workflowId,
     projectId: row.projectId,
     configPath: row.configPath,
     source: row.source,

package/src/db/schema/sync-states.ts

@@ -2,13 +2,17 @@ import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
 import {sql} from 'drizzle-orm';
 import {index, jsonb, pgEnum, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
 import type {
+  DefinitionSyncDiagnostic,
   DefinitionSyncErrorCode,
   DefinitionSyncState,
   DefinitionSyncStatus,
-  DefinitionSyncWarning,
 } from '#core/entities/sync-state.js';
 import {pgTable} from './common.js';
 
+type StoredDefinitionSyncDiagnostic = Omit<DefinitionSyncDiagnostic, 'severity'> & {
+  severity?: DefinitionSyncDiagnostic['severity'];
+};
+
 export const definitionSyncStatusEnum = pgEnum('definitions_sync_status', [
   'pending',
   'syncing',
@@ -43,7 +47,7 @@ export const definitionSyncStates = pgTable(
     status: definitionSyncStatusEnum('status').notNull().default('pending'),
     lastErrorCode: definitionSyncErrorCodeEnum('last_error_code'),
     lastErrorMessage: text('last_error_message'),
-    warnings: jsonb('warnings').notNull().default([]).$type<DefinitionSyncWarning[]>(),
+    warnings: jsonb('warnings').notNull().default([]).$type<StoredDefinitionSyncDiagnostic[]>(),
     startedAt: timestamp('started_at', {withTimezone: true}),
     finishedAt: timestamp('finished_at', {withTimezone: true}),
     createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
@@ -64,6 +68,11 @@ export type DefinitionSyncStateDb = typeof definitionSyncStates.$inferSelect;
 export type DefinitionSyncStateCreateDb = typeof definitionSyncStates.$inferInsert;
 
 export function toDefinitionSyncState(row: DefinitionSyncStateDb): DefinitionSyncState {
+  const diagnostics = (row.warnings ?? []).map(({severity, ...diagnostic}) => ({
+    ...diagnostic,
+    severity: severity ?? 'warning',
+  }));
+
   return {
     id: row.id,
     projectId: row.projectId,
@@ -73,7 +82,7 @@ export function toDefinitionSyncState(row: DefinitionSyncStateDb): DefinitionSyn
     status: row.status as DefinitionSyncStatus,
     lastErrorCode: row.lastErrorCode as DefinitionSyncErrorCode | null,
     lastErrorMessage: row.lastErrorMessage,
-    warnings: row.warnings ?? [],
+    diagnostics,
     startedAt: row.startedAt,
     finishedAt: row.finishedAt,
     createdAt: row.createdAt,

package/src/db/schema/workflows.ts

@@ -0,0 +1,23 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {sql} from 'drizzle-orm';
+import {text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {pgTable} from './common.js';
+
+export const workflowWorkflows = pgTable(
+  'workflows',
+  {
+    id: uuidv7PrimaryKey(),
+    projectId: uuid('project_id').notNull(),
+    configPath: text('config_path'),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('definitions_workflows_project_path_unique').on(table.projectId, table.configPath),
+    uniqueIndex('definitions_workflows_project_pathless_unique')
+      .on(table.projectId)
+      .where(sql`"config_path" IS NULL`),
+  ],
+);
+
+export type WorkflowDb = typeof workflowWorkflows.$inferSelect;
+export type WorkflowCreateDb = typeof workflowWorkflows.$inferInsert;

package/src/db/sync-states.test.ts

@@ -1,13 +1,13 @@
 import {
+  DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT,
   DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH,
   DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH,
   DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH,
-  DEFINITION_SYNC_WARNINGS_MAX_COUNT,
 } from '@shipfox/api-definitions-dto';
 import {eq} from 'drizzle-orm';
 import {db} from './db.js';
 import {definitionSyncStates} from './schema/sync-states.js';
-import {markDefinitionSyncState} from './sync-states.js';
+import {getLatestDefinitionSyncState, markDefinitionSyncState} from './sync-states.js';
 
 describe('definition sync state queries', () => {
   let projectId: string;
@@ -65,14 +65,21 @@ describe('definition sync state queries', () => {
     expect(second.startedAt?.getTime()).toBe(first.startedAt?.getTime());
   });
 
-  it('persists warnings and clears them on a subsequent sync', async () => {
-    const warnings = [
+  it('persists diagnostics and clears them on a subsequent sync', async () => {
+    const diagnostics = [
+      {
+        code: 'invalid-trigger-event',
+        message: 'Trigger event is never delivered.',
+        path: 'triggers.on_demand',
+        severity: 'error',
+      },
       {
         code: 're-evaluating-command',
         message: 'Workflow data is re-executed as shell code.',
         path: 'jobs.build.steps.0.run',
+        severity: 'warning',
       },
-    ];
+    ] as const;
 
     const succeeded = await markDefinitionSyncState({
       projectId,
@@ -80,10 +87,10 @@ describe('definition sync state queries', () => {
       sourceExternalRepositoryId: 'gitea-owner/platform',
       ref: 'main',
       status: 'succeeded',
-      warnings,
+      diagnostics,
     });
 
-    expect(succeeded.warnings).toEqual(warnings);
+    expect(succeeded.diagnostics).toEqual(diagnostics);
 
     const syncing = await markDefinitionSyncState({
       projectId,
@@ -93,27 +100,89 @@ describe('definition sync state queries', () => {
       status: 'syncing',
     });
 
-    expect(syncing.warnings).toEqual([]);
+    expect(syncing.diagnostics).toEqual([]);
   });
 
-  it('bounds warning payloads before persisting them', async () => {
+  it('orders errors before warnings and bounds diagnostic payloads before persisting them', async () => {
     const state = await markDefinitionSyncState({
       projectId,
       sourceConnectionId,
       sourceExternalRepositoryId: 'gitea-owner/platform',
       ref: 'main',
       status: 'succeeded',
-      warnings: Array.from({length: DEFINITION_SYNC_WARNINGS_MAX_COUNT + 1}, (_, index) => ({
-        code: `${index}-${'c'.repeat(DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH)}`,
-        message: `${index}-${'m'.repeat(DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH)}`,
-        path: `${index}-${'p'.repeat(DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH)}`,
-      })),
+      diagnostics: [
+        {
+          code: 'warning-last',
+          message: 'warning last',
+          severity: 'warning',
+        },
+        {
+          code: 'error-first',
+          message: 'error first',
+          filePath: '.shipfox/workflows/deploy.yml',
+          severity: 'error',
+        },
+        ...Array.from({length: DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT}, (_, index) => ({
+          code: `${index}-${'c'.repeat(DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH)}`,
+          message: `${index}-${'m'.repeat(DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH)}`,
+          path: `${index}-${'p'.repeat(DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH)}`,
+          severity: 'warning' as const,
+        })),
+      ],
+    });
+
+    expect(state.diagnostics).toHaveLength(DEFINITION_SYNC_DIAGNOSTICS_MAX_COUNT);
+    expect(state.diagnostics[0]).toEqual({
+      code: 'error-first',
+      message: 'error first',
+      filePath: '.shipfox/workflows/deploy.yml',
+      severity: 'error',
+    });
+    expect(state.diagnostics[1]).toEqual({
+      code: 'warning-last',
+      message: 'warning last',
+      severity: 'warning',
+    });
+    expect(state.diagnostics[2]?.code).toHaveLength(DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH);
+    expect(state.diagnostics[2]?.message).toHaveLength(DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH);
+    expect(state.diagnostics[2]?.path).toHaveLength(DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH);
+    // The two sentinel diagnostics survive truncation; overflow warnings drop first.
+    expect(state.diagnostics[0]?.severity).toBe('error');
+    expect(state.diagnostics[1]?.severity).toBe('warning');
+  });
+
+  it('normalizes legacy stored warnings without a severity', async () => {
+    await db()
+      .insert(definitionSyncStates)
+      .values({
+        projectId,
+        sourceConnectionId,
+        sourceExternalRepositoryId: 'gitea-owner/platform',
+        ref: 'main',
+        status: 'succeeded',
+        warnings: [
+          {
+            code: 'legacy-warning',
+            message: 'Written before diagnostics had severity.',
+            path: 'jobs.build.steps.0.run',
+          },
+        ],
+      });
+
+    const state = await getLatestDefinitionSyncState({
+      projectId,
+      sourceConnectionId,
+      sourceExternalRepositoryId: 'gitea-owner/platform',
     });
 
-    expect(state.warnings).toHaveLength(DEFINITION_SYNC_WARNINGS_MAX_COUNT);
-    expect(state.warnings[0]?.code).toHaveLength(DEFINITION_SYNC_WARNING_CODE_MAX_LENGTH);
-    expect(state.warnings[0]?.message).toHaveLength(DEFINITION_SYNC_WARNING_MESSAGE_MAX_LENGTH);
-    expect(state.warnings[0]?.path).toHaveLength(DEFINITION_SYNC_WARNING_PATH_MAX_LENGTH);
+    expect(state?.diagnostics).toEqual([
+      {
+        code: 'legacy-warning',
+        message: 'Written before diagnostics had severity.',
+        path: 'jobs.build.steps.0.run',
+        severity: 'warning',
+      },
+    ]);
   });
 
   it('clears stale finish data when a sync starts again', async () => {