Errors

Import from @workspace/training. Every error a service throws is a subclass of the abstract AppError, a plain Error carrying a stable code and an isExpected flag. Services throw them, tests assert on them, and the consuming app translates them at its boundary. Module-specific subclasses live in the module's domain barrel (@workspace/training/domain/boards, /domain/sessions, /domain/events).

AppError

AppError.captureStackTrace is applied when the runtime offers it, so the stack starts at the throw site rather than inside the constructor.

export function requireOwned(
  collection: DealCollection | null,
  collectionId: string,
  ctx: ServiceContext
): DealCollection {
  if (!collection) {
    throw new NotFoundError(ErrorCode.DEAL_COLLECTION_NOT_FOUND, collectionId);
    // message => "Not found: DEAL_COLLECTION_NOT_FOUND (<id>)", isExpected => true
  }
  if (collection.userId !== ctx.userId) {
    throw new AccessDeniedError(`deal collection ${collectionId}`);
    // message => "Access denied to deal collection <id>", code => "ACCESS_DENIED"
  }
  return collection;
}

Classes

Exposed by the package root

FeatureKey and LimitKey come from @workspace/training/domain/entitlements. SessionTokenVerificationReason is "malformed" | "invalid-signature" | "expired", a category safe to surface on the wire.

Exposed by a module barrel

All five are isExpected: true.

const limit = new LimitReachedError("groups_per_user_max", 5, 5);
limit.code; // => "LIMIT_REACHED"
limit.limitKey; // => "groups_per_user_max"
limit.current; // => 5
limit.max; // => 5

const degraded = new ResourceDegradedError("deal-collection", "c1");
degraded.resource; // => "deal-collection"

const invalid = new ValidationError(ErrorCode.BOARD_GATE_REJECTED, {
  rejections: ["missing declarer"],
});
invalid.context; // => { rejections: ["missing declarer"] }

const missingBoards = new InvalidBoardReferenceError(["b1", "b2"]);
missingBoards.boardIds; // => ["b1", "b2"]
missingBoards.name; // => "InvalidBoardReferenceError"

Narrowing

isAppError separates domain errors from everything else. Narrow further with instanceof when a subclass carries fields, or switch on code when the class is generic (NotFoundError, ValidationError, ConflictError).

export function describe(error: unknown): string {
  if (!isAppError(error)) {
    throw error; // not a domain error: let it surface as a 500
  }
  const app: AppError = error;
  if (!app.isExpected) {
    return `bug: ${app.message}`;
  }
  if (error instanceof LimitReachedError) {
    return `${error.limitKey}: ${error.current}/${error.max}`;
  }
  if (error instanceof NotFoundError) {
    return `${error.code} ${error.resourceId ?? ""}`;
  }
  return app.code; // "ACCESS_DENIED", "GROUP_NOT_FOUND", …
}

ErrorCode

ErrorCode is an as const object; the type of the same name is the union of its values. The codes are semantic: they say what happened, never how to display it. Grouped as in the source:

Several codes are declared for the API or the apps and never thrown by the package (UNAUTHORIZED, FORBIDDEN, the avatar and impersonation groups, API_ERROR). They stay in the registry so one union covers the whole system.

AppEvent

AppEvent is the success counterpart of ErrorCode: an as const object of semantic events the apps map to notifications. The package declares them; it does not emit them.

isKnownErrorCode("GROUP_NOT_FOUND"); // => true
isKnownErrorCode("nope"); // => false
ErrorCode.RESOURCE_DEGRADED; // => "RESOURCE_DEGRADED"
AppEvent.GROUP_ARCHIVED; // => "GROUP_ARCHIVED"

The boundary

Domain errors never reach the wire. In apps/api, apps/api/src/errors/translate-domain-error.ts holds the one translation table:

• A handler wraps its service call in translateDomainErrors(fn), or calls translateDomainError(err) inside a catch. Both rethrow an ApiError built by the apiErrors.* factories of @workspace/api-contract.
• Subclasses with fields get an explicit branch first: InvalidBoardReferenceError, DuplicateBoardInSessionError, BoardNotInTrashError, LimitReachedError, ResourceDegradedError, FeatureDisabledError, SessionTokenVerificationError, WebhookVerificationError, AccessDeniedError.
• NotFoundError, ValidationError, ConflictError and DuplicateError are then looked up by code in three Partial<Record<ErrorCode, …>> tables, so the generic classes translate per code.
• An AppError with no mapping, and anything that is not an AppError, is rethrown unchanged. The error middleware logs it with its stack and answers a 500 UNEXPECTED_ERROR with a scrubbed message. That is the intended signal of a contract violation, not a silent bucket.

The admin calls the services from its server actions, so its boundary is toActionError in apps/admin/src/lib/actions/safe-action.ts: an expected AppError becomes a bad-request carrying the error's message (AccessDeniedError a forbidden), and an unexpected one is logged and masked as internal.

The wire shape and the public codes are on API errors. The teacher app receives those wire errors; it never imports a domain error class to make a UI decision.