Mission

Key Rules

1. Rich domain — mutations live on the Entity

The entity owns its invariants. Use cases only orchestrate.

// ❌ WRONG — anemic, usecase bypassing entity rules
mission._name = input.name;
await repo.update(mission);

// ✅ CORRECT
const mission = await this.findByIdUseCase.execute({ id, organizationId });
mission.updateMission({ name: input.name, description: input.description });
await this.missionRepository.update(mission);

Entity methods: Mission.create() (static factory), updateMission(props), publish(hash), changeName/Description/Status. Every mutator validates the relevant group and throws EntityValidationError on failure.

2. Events: addEvent() in entity, pullEvents() in usecase after persistence

// entity
this.addEvent(new MissionPublishedEvent(id, hash, orgId));

// usecase — AFTER persistence commits
await this.missionRepository.update(mission);
if (this.eventDispatcher) {
  for (const event of mission.pullEvents()) {
    await this.eventDispatcher.dispatch(event);
  }
}

Never dispatch from inside the entity. If the DB write fails, events must not fire (dual-write bug).

3. FindByIdUseCase is the single point of "not found"

Gateway returns Mission | null. The FindByIdUseCase throws new NotFoundError(id, Mission). Every other usecase that needs a mission injects FindByIdUseCaseInterface — never calls the gateway directly for lookup+throw.

4. Multi-tenant isolation is non-negotiable

• Gateway methods all receive organizationId.
• update() uses updateMany({ where: { id, organizationId } }).
• MissionVersion queries filter through the relation: { missionId, mission: { organizationId } }.
• saveVersion() pre-checks that the mission belongs to the org before inserting.

5. Workspace-scoped

• The entity carries workspaceId (required, validated as UUID on create).
• The repository persists workspaceId on create and reads it back in toDomainEntity.
• The controller route is workspaces/:workspaceId/missions — the param is injected into the create payload.
• workspaceId is immutable on the entity (no setter, set only at creation).

6. DAG validation cannot infinite-loop

DAGValidatorService.validate(graph, startNodeId?) uses:

• Tricolor DFS (WHITE/GRAY/BLACK) with explicit stack → detects cycles without stack-overflow, terminates even on adversarial inputs.
• Dangling-edge check → edges referencing missing nodes.
• Dead-end check → leaves that aren't terminal node types (Reward.Give, Flag.Set, Cinematic.Play).
• BFS reachability → unreachable nodes from the provided startNodeId.

Returns { isValid, errors: DAGValidationError[] } where each error has { nodeId, errorType, message }.

7. DAG validation is server-side, not client-provided

SaveVersionUseCase injects DAGValidatorService and computes isValid and validationErrors from graphData before computing the hash. The frontend cannot override validation results — the usecase always validates server-side. This prevents invalid contracts from being published to the runtime.

// Inside SaveVersionUseCase
const validation = this.dagValidatorService.validate(input.graphData, startNodeId);
const contract = new MissionContract(input.missionData, input.graphData);
const hash = this.hashService.compute(contract);
await this.missionVersionRepository.create({
  missionId, hash, isValid: validation.isValid, validationErrors: validation.errors
});

8. Hash = identity of a version

MissionHashService.compute(contract) returns SHA-256 hex of JSON.stringify(contract). Same content → same hash → runtime cache hit. Injected into SaveVersionUseCase.

9. Facade DTOs are pure interfaces

mission.facade.dto.ts never imports class-validator. Class-validator decorators only live in usecase/**/*.usecase.dto.ts (because controllers use those classes). Facade consumers get clean interfaces.

10. active field aligned with BaseEntity

The entity persists active on create and update. toDomainEntity reads active from the DB row. Soft-delete sets deletedAt + deactivates (active = false).

Use cases

Errors thrown

Infra wiring

• src/infra/http/mission/mission.module.ts — MissionModule exports MissionService and provides MissionFacade via factory.
• src/infra/http/mission/mission.controller.ts — REST surface at workspaces/:workspaceId/missions. Guarded by AuthGuard + RolesGuard.
  • POST / (create) — requires DESIGNER, extracts workspaceId from route param.
  • POST /:id/versions (saveVersion) — requires DESIGNER.
  • PUT /:id/publish — requires DESIGNER.
  • GET /:id/versions (listVersions) — requires VIEWER.
  • GET /:id/active (getActive) — requires VIEWER.
• src/infra/http/mission/mission.service.ts — thin adapter delegating to MissionFacade.

Testing conventions

• __tests__/ mirrors the module structure.
• Domain entity + validator + services tested without mocks (pure domain).
• Use cases mocked at Gateway boundary via jest.fn() using the makeSut() pattern.
• Facade mocked at each UseCase boundary.
• DAG validator specs include: simple cycle, self-loop, deep cycle, dangling edge, dead-end, terminal-node allowed, unreachable node.
• EventDispatcher mocked in Create/Publish specs to assert events fire only after repository.create/update resolves.
• All test factories include workspaceId as a required UUID field.
• Current coverage: 32 suites, 141 tests, all green.

Open items (not yet in the module)

• No DeleteUseCase yet (soft delete via mission.delete() is on the entity).
• No integration tests under test/integration/mission/.

Update this skill when you change the module

Per CLAUDE.md's MANDATORY rule, update this file whenever you:

• add/rename a use case or route
• change DTO shape or validators
• add/remove domain services or events
• touch multi-tenant filtering in the repository
• change facade method signatures