refactor(global): unify OpenAPI types and brand IDs consistently

CONTEXT.md

@@ -0,0 +1,17 @@
+# Jobnik
+
+A job orchestration system: Jobs are composed of Stages, which are composed of Tasks.
+
+## Language
+
+**Branded ID**:
+A nominally-typed wrapper (`JobId`, `StageId`, `TaskId`) around a plain `string` id, generated as part of the OpenAPI types. Its purpose is to catch a job/stage/task id being passed where a different kind of id is expected — a compile-time guard against mixing up ids, not a runtime check that the id exists or is well-formed (that's the OpenAPI request validator's job).
+_Avoid_: validated ID, typed ID
+
+**API model**:
+A type derived directly from the OpenAPI spec (`components['schemas'][...]`), describing the wire contract of a request or response.
+_Avoid_: DTO, schema type
+
+**Persistence model**:
+The Prisma-derived shape of a row as stored in the database. Deliberately not required to mirror the API model — the two are distinct representations of the same entity, and Prisma is expected to be replaced later.
+_Avoid_: DB model, entity (when meaning the Prisma type specifically)

apps/jobnik-manager/eslint.config.mjs

@@ -32,5 +32,5 @@ const customConfig = {
 };
 
 export default defineConfig(vitestConfig, tsBaseConfig, customConfig, {
-  ignores: ['src/db/prisma/generated', 'src/common/generated', 'vitest.config.mts'],
+  ignores: ['src/db/prisma/generated', 'vitest.config.mts'],
 });

apps/jobnik-manager/package.json

@@ -29,8 +29,6 @@
     "assets:copy": "copyfiles -f ./config/* ./dist/config && copyfiles ./package.json dist && copyfiles -u 4 \"./src/db/prisma/migrations/**/*\" ./dist/db/prisma/migrations && copyfiles -f ./src/db/prisma/schema.prisma ./dist/db/prisma",
     "prisma:copy": "node ./scripts/copyDirectories.mjs ./src/db/prisma/generated ./dist/db/prisma/generated",
     "clean": "rimraf dist",
-    "generate:openapi-errors": "node scripts/generateOpenApiErrors.mts",
-    "generate:check": "npm run generate:openapi-errors && git diff --exit-code -- src/common/generated/errors.ts",
     "type-check": "tsc --noEmit",
     "migration:validate": "npx prisma validate --schema ./src/db/prisma/schema.prisma  ",
     "migration:format": "npx prisma format --check --schema ./src/db/prisma/schema.prisma  ",

apps/jobnik-manager/src/api/v1/jobs/controller.ts

@@ -3,9 +3,9 @@ import httpStatus from 'http-status-codes';
 import { injectable, inject } from 'tsyringe';
 import { HttpError } from '@map-colonies/error-express-handler';
 import type { TypedRequestHandlers } from 'jobnik-openapi';
+import { IllegalJobStatusTransitionError, JobNotInFiniteStateError, JobNotFoundError } from 'jobnik-openapi';
 import { SERVICES, successMessages } from '@common/constants';
 import { SamePriorityChangeError } from '@src/jobs/models/errors';
-import { IllegalJobStatusTransitionError, JobNotInFiniteStateError, JobNotFoundError } from '@src/common/generated/errors';
 import { type JobFindCriteriaArg } from '@src/jobs/models/models';
 import { JobManager } from '@src/jobs/models/manager';
 

apps/jobnik-manager/src/api/v1/stages/controller.ts

@@ -3,8 +3,8 @@ import httpStatus from 'http-status-codes';
 import { injectable, inject } from 'tsyringe';
 import { HttpError } from '@map-colonies/error-express-handler';
 import type { TypedRequestHandlers } from 'jobnik-openapi';
+import { IllegalStageStatusTransitionError, JobInFiniteStateError, JobNotFoundError, StageNotFoundError } from 'jobnik-openapi';
 import { SERVICES, successMessages } from '@common/constants';
-import { IllegalStageStatusTransitionError, JobInFiniteStateError, JobNotFoundError, StageNotFoundError } from '@src/common/generated/errors';
 import { StageManager } from '@src/stages/models/manager';
 import type { StageFindCriteriaArg } from '@src/stages/models/models';
 

apps/jobnik-manager/src/api/v1/tasks/controller.ts

@@ -3,7 +3,6 @@ import httpStatus from 'http-status-codes';
 import { injectable, inject } from 'tsyringe';
 import { HttpError } from '@map-colonies/error-express-handler';
 import type { TypedRequestHandlers } from 'jobnik-openapi';
-import { SERVICES, successMessages } from '@common/constants';
 import {
   IllegalJobStatusTransitionError,
   IllegalStageStatusTransitionError,
@@ -14,7 +13,8 @@ import {
   StageNotFoundError,
   TaskStatusUpdateFailedError,
   TaskNotFoundError,
-} from '@src/common/generated/errors';
+} from 'jobnik-openapi';
+import { SERVICES, successMessages } from '@common/constants';
 import { TaskManager } from '@src/tasks/models/manager';
 import { type TasksFindCriteriaArg } from '@src/tasks/models/models';
 

apps/jobnik-manager/src/jobs/models/manager.ts

@@ -5,14 +5,15 @@ import type { Tracer } from '@opentelemetry/api';
 import { trace } from '@opentelemetry/api';
 import { withSpanAsyncV4 } from '@map-colonies/tracing-utils';
 import { INFRA_CONVENTIONS } from '@map-colonies/semantic-conventions';
+import type { JobId } from 'jobnik-openapi';
+import { IllegalJobStatusTransitionError, JobNotInFiniteStateError, JobNotFoundError } from 'jobnik-openapi';
 import type { PrismaClient, Priority } from '@prismaClient';
 import { Prisma, JobOperationStatus } from '@prismaClient';
 import { SERVICES } from '@common/constants';
 import { convertArrayPrismaStageToStageResponse } from '@src/stages/models/helper';
 import { illegalStatusTransitionErrorMessage, prismaKnownErrors } from '@common/errors';
 import { type PrismaTransaction } from '@src/db/types';
 import { resolveTraceContext } from '@src/common/utils/tracingHelpers';
-import { IllegalJobStatusTransitionError, JobNotInFiniteStateError, JobNotFoundError } from '@src/common/generated/errors';
 import { ATTR_MESSAGING_MESSAGE_CONVERSATION_ID } from '@src/common/semconv';
 import { paginate } from '@src/common/utils/pagination';
 import { errorMessages as jobsErrorMessages, SamePriorityChangeError } from './errors';
@@ -88,7 +89,7 @@ export class JobManager {
   }
 
   @withSpanAsyncV4
-  public async getJobById(jobId: string, includeStages?: boolean): Promise<JobModel> {
+  public async getJobById(jobId: JobId, includeStages?: boolean): Promise<JobModel> {
     trace.getActiveSpan()?.setAttributes({
       [ATTR_MESSAGING_MESSAGE_CONVERSATION_ID]: jobId,
     });
@@ -103,7 +104,7 @@ export class JobManager {
   }
 
   @withSpanAsyncV4
-  public async updateUserMetadata(jobId: string, userMetadata: Record<string, unknown>): Promise<void> {
+  public async updateUserMetadata(jobId: JobId, userMetadata: Record<string, unknown>): Promise<void> {
     trace.getActiveSpan()?.setAttributes({
       [ATTR_MESSAGING_MESSAGE_CONVERSATION_ID]: jobId,
     });
@@ -128,7 +129,7 @@ export class JobManager {
   }
 
   @withSpanAsyncV4
-  public async updatePriority(jobId: string, priority: Priority): Promise<void> {
+  public async updatePriority(jobId: JobId, priority: Priority): Promise<void> {
     trace.getActiveSpan()?.setAttributes({
       [ATTR_MESSAGING_MESSAGE_CONVERSATION_ID]: jobId,
       [INFRA_CONVENTIONS.infra.jobnik.job.priority]: priority,
@@ -157,7 +158,7 @@ export class JobManager {
   }
 
   @withSpanAsyncV4
-  public async updateStatus(jobId: string, status: JobOperationStatus, tx?: PrismaTransaction): Promise<void> {
+  public async updateStatus(jobId: JobId, status: JobOperationStatus, tx?: PrismaTransaction): Promise<void> {
     trace.getActiveSpan()?.setAttributes({
       [ATTR_MESSAGING_MESSAGE_CONVERSATION_ID]: jobId,
       [INFRA_CONVENTIONS.infra.jobnik.job.status]: status,
@@ -173,7 +174,7 @@ export class JobManager {
   }
 
   @withSpanAsyncV4
-  public async deleteJob(jobId: string): Promise<void> {
+  public async deleteJob(jobId: JobId): Promise<void> {
     trace.getActiveSpan()?.setAttributes({
       [ATTR_MESSAGING_MESSAGE_CONVERSATION_ID]: jobId,
     });
@@ -207,7 +208,7 @@ export class JobManager {
    */
   @withSpanAsyncV4
   public async getJobEntityById<IncludeStages extends boolean = false>(
-    jobId: string,
+    jobId: JobId,
     options: { includeStages?: IncludeStages; tx?: PrismaTransaction } = {}
   ): Promise<JobPrismaObject<IncludeStages> | null> {
     const spanActive = trace.getActiveSpan();
@@ -229,7 +230,7 @@ export class JobManager {
   }
 
   @withSpanAsyncV4
-  private async executeUpdateStatus(jobId: string, status: JobOperationStatus, tx: PrismaTransaction): Promise<void> {
+  private async executeUpdateStatus(jobId: JobId, status: JobOperationStatus, tx: PrismaTransaction): Promise<void> {
     const job = await this.getJobEntityById(jobId, { tx });
 
     if (!job) {
@@ -279,6 +280,6 @@ export class JobManager {
       stages: Array.isArray(stage) ? convertArrayPrismaStageToStageResponse(stage) : undefined,
     };
 
-    return Object.assign(rest, transformedFields);
+    return Object.assign(rest, transformedFields) as unknown as JobModel;
   }
 }

apps/jobnik-manager/src/stages/DAL/stageRepository.ts

@@ -1,5 +1,6 @@
 import { inject, Lifecycle, scoped } from 'tsyringe';
 import { type Logger } from '@map-colonies/js-logger';
+import type { StageId } from 'jobnik-openapi';
 import { Prisma, PrismaClient } from '@prismaClient';
 import { SERVICES } from '@src/common/constants';
 import { PrismaTransaction } from '@src/db/types';
@@ -13,7 +14,7 @@ export class StageRepository {
     @inject(SERVICES.PRISMA) private readonly prisma: PrismaClient
   ) {}
 
-  public async updateStageSummary(stageId: string, summaryPayload: UpdateSummaryCount, tx: PrismaTransaction): Promise<StageSummary> {
+  public async updateStageSummary(stageId: StageId, summaryPayload: UpdateSummaryCount, tx: PrismaTransaction): Promise<StageSummary> {
     const addStatus = summaryCountsMapper[summaryPayload.add.status];
     const addCount = summaryPayload.add.count;
 

apps/jobnik-manager/src/stages/models/helper.ts

@@ -39,7 +39,7 @@ function convertPrismaToStageResponse(prismaObjects: StagePrismaObject): StageMo
     tasks: Array.isArray(task) ? convertArrayPrismaTaskToTaskResponse(task) : undefined,
     tracestate: tracestate ?? undefined,
   };
-  return Object.assign(rest, transformedFields);
+  return Object.assign(rest, transformedFields) as StageModel;
 }
 
 /**