Boards

A board is a bridge deal owned by a teacher, with teaching metadata: a short code, a name, a level, an auction system, themes, a sharing mode, a localized review and per-move comments. The game field is a Deal from @workspace/bridge whose comments are LocalizedField<RichText>. The teacher app creates, edits, lists and filters boards; the admin audits and bulk-edits them; the API serves them; the public player reads them through Public; import jobs claim anonymous drafts from Editor boards.

Every write of deal content goes through one gate (BoardsWriteService), which converges comment shapes, rotates the deal so the declarer sits South, validates it and computes the derived fields stored for filtering. BoardService.create and update enforce two more invariants before calling it: translations must be complete once a deal carries two languages, and the declarer proven by the auction must be South.

Deals and boards

Board

BoardDeal is Deal<LocalizedField<RichText>, LocalizedField<RichText>, LocalizedField<RichText>>: auction comments, play comments and review are all localized rich text. See Types for the deal shape.

BoardResult is { data: Board; diagnostics: BoardDiagnostic[] }: every read returns the entity with the diagnostics the repository raised while hydrating it (field: "auction" | "play" | "cards" | "analysis", message, path).

BoardMetadata

auctionThemes and playThemes are system themes, userThemes and userInspirations user themes (see Themes). sharing comes from Sharing.

Permissions, votes, ownership

Permissions are computed server-side for the viewer passed as viewerUserId, so the front end never reasons about identity. They are null in public contexts.

Ownership is a discriminated union: { kind: "user"; userId } or { kind: "orphaned"; orphanedAt; reason: OrphanReason }. A board becomes orphaned when its owner hard-deletes it: the row moves under the system account but keeps its id so sessions still resolve it. OrphanReason is "deal_deleted" | (string & {}), open for future triggers. owner is null for orphaned boards: branch on ownership.kind.

makeOwnership({ userId: "u1", orphanedAt: null, orphanReason: null });
// => { kind: "user", userId: "u1" }
makeOwnership({ userId: "u1", orphanedAt: "2026-01-01T00:00:00Z", orphanReason: null });
// => { kind: "orphaned", orphanedAt: "2026-01-01T00:00:00Z", reason: "deal_deleted" }

BoardSummary family

BoardSummary is the minimal representation from the unified deals view, enough to preview and play a deal. TinyBoardSummary is an alias: the base shape, the only thing editor-source rows can offer. RichBoardSummary is the app-only superset with metadata, themes, owner and votes, enough to render a rich preview without a second read. SearchByCodeResult discriminates them: { kind: "tiny"; board: TinyBoardSummary } or { kind: "rich"; board: RichBoardSummary }.

An editor-source review with no recorded language is keyed under the BCP-47 sentinel "und"; consumers must ask for a real language before persisting it.

Collection entries

CollectionBoardEntry replaces parallel boardIds and unavailableBoardIds arrays in collections and sessions: { status: "available"; board: BoardResult } or { status: "unavailable"; id } when the deal was unshared or made private by its owner.

export function entriesInOrder(
  orderedIds: string[],
  readable: BoardResult[]
): string[] {
  const entries = projectBoardEntries(orderedIds, readable);
  // entries[i] => { status: "available", board } or { status: "unavailable", id }
  return getEntryBoardIds(entries); // same order as orderedIds
}

Languages

A board's languages are the union of locale keys holding visible content across the review, every auction comment and every play comment. An empty result means the deal is language-agnostic; the repository treats it as matching every language filter. DealLanguageInput is the minimal structural shape (review?, auction?, play?), satisfied by any BoardDeal or partial snapshot.

export function languagesOf(game: BoardDeal) {
  getDealContentLanguages(game); // => ["en", "fr"] when review or comments hold both
  const report = getDealLanguageGaps(game);
  report.languages; // => ["en", "fr"]
  report.gaps; // => [{ category: "auction", index: 2, missing: ["fr"] }]
  // a slot without any filled locale is never a gap; [] languages = language-agnostic
  return report;
}

Sequence adapters

Converters between the flat sequence stored in the database (Sequence<TComment> = { value: string; comment?: TComment }[]) and the bridge Auction / Play. Generic over the comment type, no casts needed.

export function roundTrip(game: BoardDeal) {
  const flat = dealAuctionToSequence(game.auction); // [{ value: "1S", comment: undefined }, …]
  const back = sequenceToDealAuction(flat, game.auction.first);
  return back; // { first: "S", moves: [{ bid: "1S" }, …] }
}

PBN export

boardsToPBN(opts: BoardsToPbnOptions): string serialises boards into one multi-deal PBN file. Boards are numbered from startBoardNumber and repeated seriesCount times; each deal is rotated so its dealer matches the standard dealer of its box number, using the injected rotater (apps hand in their localized one from @workspace/bridge/rotation). Comments are flattened to plain text in language.

export function exportCollection(
  boards: Board[],
  rotater: Rotater, // the app's localized rotater
  language: string
): string {
  return boardsToPBN({
    boards,
    startBoardNumber: 1,
    seriesCount: 2, // boards repeated twice, board numbers continue
    language,
    rotater,
    event: "Tuesday class",
    site: "https://example.test",
    now: new Date(),
  });
}

AuctionSystem and Bookmark

Codes and enums

Deal codes

A deal code is the 8-character public identity of a board, used in player URLs and sharing. Generation delegates to the short-code utility of @workspace/shared (56-character alphabet without ambiguous glyphs). Uniqueness is enforced by the repository.

const code = generateDealCode(); // 8 chars from the short-code alphabet
isValidDealCode(code); // => true
isValidDealCode("abcdefgh"); // => false when a char is outside the alphabet
isLegacyCompatibleDealCode("abcdefgh"); // => true: length and alphanumeric shape only
isLegacyCompatibleDealCode("abc"); // => false

Levels, scoring, vulnerability, contract level, counter status

ContractLevel and CounterStatus are re-exported from @workspace/bridge/types.

parseLevel(3); // => 3
parseLevel(7); // => "UNSET"
isUnsetLevel(parseLevel(null)); // => true
parseScoring("IMP"); // => "IMP"
parseScoring("bogus"); // => "UNSET"
parseVulnerability("NS"); // => "NS"
parseVulnerability(undefined); // => "UNSET"
parseCounterStatus("XX"); // => "XX"
parseCounterStatus(42); // => "none"

Votes

computeVoteDeltas(null, "up"); // => { score: 1, upvotes: 1, downvotes: 0 }
computeVoteDeltas("up", "up"); // => { score: -1, upvotes: -1, downvotes: 0 } (toggle off)
computeVoteDeltas("down", "up"); // => { score: 2, upvotes: 1, downvotes: -1 } (switch)

Writing boards

BoardService

createBoardService(deps: BoardServiceDeps): BoardService, where the deps are { boards: BoardRepository; boardsRead: BoardReadRepository; themesRead: ThemeReadRepository; boardsWrite: BoardsWriteService; boardThemes: BoardThemesRepository; uow: BoardWriteUnitOfWork }.

create and update write through uow.run: the new themes and inspirations, the board and its theme links commit or roll back together. BoardWriteTx is { boards; boardsWrite; themes; boardThemes }, bound to the transaction. Everything the write needs is read before the transaction opens, so a request never holds two connections. The database package's createDrizzleBoardWriteUnitOfWork(db: OwnerConnection) implements it.

Every method takes ctx: ServiceContext last (see Service Context). The service holds the access rules, whatever connection the repositories run on:

• Reads are scoped with visibleTo(ctx.userId): the caller's own boards, public ones, shared ones whose owner has the caller in a sharing group, and orphans still linked from one of the caller's sessions or collections. A board carries system themes and the caller's own themes, never another account's. Its score counts every account's vote. There is no admin view: an administrator reads like any other account.
• Mutations (update, softDelete, restore, hardDelete, linkThemes) first look the boards up among the caller's own: any id not found there, missing or another account's, throws AccessDeniedError before any write, so the answer does not reveal whether the board exists.
• Theme ids given to create, update or linkThemes must be system themes or the caller's own; any other id, a missing one included, throws AccessDeniedError.

export function createBoard(
  deps: BoardServiceDeps,
  input: CreateBoardInput,
  ctx: ServiceContext
): Promise<BoardResult> {
  const boards = createBoardService(deps);
  // Throws ValidationError(BOARD_TRANSLATION_INCOMPLETE | BOARD_DECLARER_NOT_SOUTH | BOARD_GATE_REJECTED)
  return boards.create(input, ctx);
}

export function newBoardInput(game: BoardDeal): CreateBoardInput {
  return {
    game, // declarer South, translations complete
    metadata: {
      name: "Stayman after 1NT",
      auctionSystem: "sef",
      sharing: "private",
      level: LEVEL.INTERMEDIATE,
    },
    newThemes: [{ title: "Stayman" }], // created before the board, then linked
  };
}

export async function trashThenPurge(
  deps: BoardServiceDeps,
  boardId: string,
  ctx: ServiceContext
): Promise<void> {
  const boards = createBoardService(deps);
  await boards.softDelete(boardId, ctx); // idempotent; AccessDeniedError unless ctx.userId owns it, missing included
  await boards.restore(boardId, ctx); // back in the explorer
  await boards.softDelete(boardId, ctx);
  await boards.hardDelete(boardId, ctx); // BoardNotInTrashError without the softDelete above
}

DTOs

CreateBoardInput is Omit<CreateBoardDTO, "code" | ComputedFields>: the caller never supplies the code nor the derived fields (partnership, contractLevel, counterStatus, opener, flattenedAuction, cardCounts, supportedLanguages). UpdateBoardInput is Omit<UpdateBoardDTO, ComputedFields>.

NewThemeDTO is { title: string }: a user theme or inspiration created inline, stored under the "default" label key.

BoardsWriteService

The write gate. createBoardsWriteService(deps: { boards: BoardRepository; boardsRead: BoardReadRepository; clock?: () => Date }). Every method takes opts: WriteOpts = { commentLocale: string | null }: the BCP-47 locale that plain-string and non-localized RichText comments are wrapped at. With null, any such comment rejects the write.

The gate accepts a RawBoardData (an EditorBoardData whose move comments may be string, RichText or LocalizedField<RichText>) and, in order:

1. Rejects a code that is not a valid deal code, unless it equals the grandfatheredCode byte for byte (invalid_code). Overwrites pass the stored code as grandfathered, so a legacy code stays writable as long as it is kept unchanged; a changed code is code_mismatch.
2. Canonicalises the deal shape for the teaching mode's auction input, resolves the declarer (a complete auction overrides the declared one and report.declarerCorrected records it), and derives the rotation count to South.
3. Rejects when unlocalized comments are present and commentLocale is null (comments_present_without_locale).
4. Converts comments: strings are rotated (player names) and parsed from PBN text, RichText is wrapped at the locale, localized fields pass through. report.commentsConverted counts them.
5. Rotates the deal structurally so the declarer sits South. When no final comment was supplied, the rotated review becomes the final comment at the locale.
6. Validates: missing_declarer, missing_player, cards_incomplete (malformed_hands or invalid_total_<n>: 52 cards, or an equal multiple of 4 per seat), auction_first_invalid, and play_order_invalid from the engine's chronological trick replay (card_not_owned, revoke, invalid_play). No repair.
7. Computes ValidatedDerivedFields (denomination, contractLevel, opener, partnership, counterStatus, flattenedAuction, cardCounts, supportedLanguages) and stamps the persistable write with gatedAt (from clock) and gatedVersion.

GateRejection is { reason: GateRejectionReason; detail?: string } with GateRejectionReason one of missing_declarer, missing_player, cards_incomplete, play_order_invalid, comments_present_without_locale, auction_first_invalid, invalid_code, code_mismatch. RawBoardData, RawAuctionMove, RawPlayMove and ValidatedDerivedFields are exported as types; the gate function itself is internal to the package.

export async function importOne(
  boards: BoardRepository,
  boardsRead: BoardReadRepository,
  input: BoardsWriteInput // raw deal + overrides, code generated by the caller
) {
  const writer = createBoardsWriteService({ boards, boardsRead });

  const check = writer.checkMany([input], { commentLocale: "fr" });
  if (!check[0]?.ok) {
    return check[0]?.rejections; // [{ reason: "cards_incomplete", detail: "invalid_total_48" }]
  }

  const outcome = await writer.writeOne(input, { commentLocale: "fr" });
  switch (outcome.status) {
    case "persisted":
      return outcome.report; // { rotated, rotationCount, commentsConverted, declarerCorrected? }
    case "gate_rejected":
      return outcome.rejections;
    case "already_exists":
    case "persistence_failed":
      return outcome.status;
  }
}

Derived fields

computeClaimDerivedFields(source: ClaimDerivableSource): ClaimDerivedFields computes cardCounts, partnership, opener, contractLevel, counterStatus and flattenedAuction from cards, contract, player and auction. It throws ValidationError with VALIDATION_ERROR when player is missing. The gate computes its own derived fields; this helper serves callers that need them without a write.

Claiming

Claiming turns an anonymous editor board into an owned board. The editor record's data is the gate's raw input, the editor code is grandfathered, and commentLocale gives the editor's plain comments their language.

BoardClaimService

createBoardClaimService(deps: BoardClaimServiceDeps) with { editorBoardsRead, boardsRead, boardsWrite }.

export async function claimEditorBoard(
  deps: BoardClaimServiceDeps,
  code: string,
  userId: string
) {
  const claim = createBoardClaimService(deps);
  const plan = await claim.plan({ code, userId });
  if (plan.status === "already_exists") {
    return plan.boardId;
  }
  const result = await claim.apply({
    code,
    userId,
    overrides: claim.parseOverrides('{"name":"Lesson 3","sharing":"shared"}'),
    commentLocale: "fr", // locale the editor's plain comments are wrapped at
  });
  return result.status === "created" ? result.boardId : null;
}

BoardBulkClaimService

createBoardBulkClaimService(deps: BoardBulkClaimServiceDeps). It takes editorBoardsRead, boardsRead and boardsWrite like the claim, boardThemes (writeMany, for the theme links), accounts (AccountsService.resolveIdsByEmails, to resolve owner and share emails), themes and themesRead (user themes by slug), sharingGroups (the SharingGroupsService, for ensureWithMembers) and getThemeLocale(). Two callers: the admin xlsx and csv claim, and pnpm cli --actor <accountId> import-xlsx-metadata, whose dry run is plan and whose --apply is apply, both under the operator's context.

Row helpers are exported for the import tooling.

export async function bulkClaim(
  deps: BoardBulkClaimServiceDeps,
  rows: BulkClaimRow[],
  ctx: ServiceContext // the acting admin
) {
  const bulk = createBoardBulkClaimService(deps);
  const plan = await bulk.plan(rows, { commentLocale: "fr" }, ctx);
  plan.rows.map((r) => r.status); // "will_insert" | "will_update" | "skip_already_claimed" | …
  plan.stats.gateRejections; // [{ code, reasons }]
  const stats = await bulk.apply(
    plan,
    {
      commentLocale: "fr",
      batchSize: 100,
      onProgress: (n) => console.log(`${n} rows processed`),
    },
    ctx
  );
  return stats.inserted;
}

PbnImportService

createPbnImportService(deps: PbnImportServiceDeps) turns spreadsheet rows and already-parsed PBN files into owned boards. It composes services only: accounts (resolveIdsByEmails), themes (checkSystemThemeIds, ensureOwnerThemes), sharingGroups (ensureWithMembers), dealCollections (listByOwner, ensureForOwner) and boardsWrite (writeMany), plus the boardThemes junction (writeMany): the importer links boards it writes for many owners to their own themes, which the caller-scoped BoardService.linkThemes would refuse. PBN parsing and the deal-to-source mapping stay with the caller: each PbnImportFile carries a parsed first deal, an empty file or a parse error.

normalizePbnRef(ref) is the file key both sides use: trimmed, lower-cased, .pbn appended when missing.

export async function importPbn(
  deps: PbnImportServiceDeps,
  rows: PbnImportRow[],
  files: PbnImportFile[],
  ctx: ServiceContext
) {
  const importer = createPbnImportService(deps);
  const plan = await importer.plan({ rows, files, language: "fr" }, ctx);
  plan.stats.willCreate;
  plan.collections; // [{ name, ownerEmail, status: "create" | "add_to_existing", … }]
  if (plan.invalidThemeTitles.length > 0) {
    return null; // apply would throw InvalidThemeTitlesError
  }
  if (plan.invalidSystemThemeIds.length > 0) {
    return null; // apply would throw UnknownSystemThemesError
  }
  const report = await importer.apply({ rows, files, language: "fr" }, ctx);
  return report.inserted;
}

Queries and filters

The generics (QueryObject, Criteria, Projection, Aggregation, ReadRepository, WriteRepository, pagination) are described on Queries. This section lists the board bindings.

BoardQuery

Immutable query object for reads. BoardQueryParams extends QueryParams<BoardWhere, BoardSort> with two decorations: viewerUserId (permissions and avatars, never a filter) and lifecycleMode. Visibility is a filter of its own, where.visibleTo.

export function recentSharedBoards(
  boardsRead: BoardReadRepository,
  viewerUserId: string
): Promise<BoardResult[]> {
  const query = BoardQuery.empty()
    .notOwnedBy(viewerUserId)
    .withSharing("public")
    .withLevels([1, 2])
    .withLanguages(["fr"]) // language-agnostic boards match too
    .withTrumpSuit({ suits: ["H", "S"], includeNT: false })
    .withSorting({ column: "createdAt", desc: true })
    .withPagination({ page: 1, pageSize: 20 })
    .asViewer(viewerUserId); // permissions and avatars, never a filter
  return boardsRead.findMany(query, BoardProjections.entity());
}

export async function codesOf(
  boardsRead: BoardReadRepository,
  ids: string[]
): Promise<string[]> {
  const refs = await boardsRead.findMany(
    BoardQuery.empty().withIds(ids).withLifecycle("all"),
    BoardProjections.ids()
  );
  return refs.map((r) => r.code);
}

BoardWhere

The leaf filter shape returned by toParams().where and consumed by the repository. Fields are AND-combined; names mirror domain concepts, not columns. mergeWhere(a, b) shallow-merges two fragments.

BoardCriteria

Filter-only query object for update, delete and scoped aggregations. Inherits the empty-where refusal from Criteria.

BoardUpdatePatch

The payload of BoardRepository.update. index patches the index columns, payload the JSONB payload columns, themeIds replaces the theme junction ([] clears it, undefined leaves it), recomputeAuctionSearch asks the repository to recompute the auction search tokens from { auction, dealer }.

export async function renameBoards(
  boards: BoardRepository,
  ids: string[],
  name: string
): Promise<number> {
  const { updatedIds } = await boards.update(
    BoardCriteria.byIds(ids).notInTrash(),
    { index: { name } }
  );
  return updatedIds.length;
}

export function clearThemes(boards: BoardRepository, boardId: string) {
  return boards.update(BoardCriteria.byId(boardId), { themeIds: [] });
}

BoardSort

{ column: BoardSortColumn; desc: boolean } with BOARD_SORT_COLUMNS = ["level", "name", "boardNumber", "createdAt", "updatedAt", "deletedAt", "publishedAt"] as the trust boundary for sort input. publishedAt is the first time the board became public (boards_index.published_at, written by the repository on every path that sets sharing, never cleared); its nulls sort last in both directions. votes is absent on purpose: vote counts live in another table.

BoardProjections

BoardAggregations

Each factory returns an Aggregation<T>; criteria scopes the rows, default scope excludes trashed and orphan rows.

Legacy filters

BoardFilters and BoardFiltersQuery are the filter value objects of the advanced search: a query is a list of groups combined with OR, each group AND-combining its fields. BiddingSequenceFilter is Bid[][], one array of alternatives per position. BoardListFilters / BoardListInput are the wire shape of the deals page, translated into a BoardQuery by the service. BoardSearchByCodeInput is { code }; FilteredBoardsWithPagination is the list response.

Limits protect query plans and keep the UI readable. BOARD_FILTERS_LIMITS aggregates them and BoardFiltersLimits is its type.

const query: BoardFiltersQuery = [
  { levels: [1, 2], biddingSequence: [["1NT"], ["Pass"], ["2C"]] },
  {}, // empty group, dropped
];
cleanFiltersQuery(query);
// => 4 groups: the sequence is expanded with 0 to 3 leading Pass bids

generatePaddedSequences([["Pass"], ["1S"]]); // => [[["Pass"], ["1S"]]]: already starts with Pass

assertBoardsAccessible

assertBoardsAccessible(boardReadRepository: BoardReadRepository | undefined, boardIds: string[], accountId: string): Promise<void> checks that every id resolves to a board the account may read (visibleTo(accountId), lifecycle all, ids() projection) before a session or collection mutation and throws InvalidBoardReferenceError with the missing ids. It is skipped when no repository is injected or the list is empty.

Comments

BoardsCommentsService

Admin bulk surface for the final per-locale board comment. createBoardsCommentsService(deps: { boards: BoardRepository; boardsRead: BoardReadRepository }).

Comment rewrite rules

domain/boards holds the pure rules of the bulk search and replace over that comment. A CommentRule is { find, locale, action, replace? }:

• find is the literal * (every comment), a regex when it holds a regex metacharacter (isRegexFind), else a literal matched anywhere in the plain text.
• locale is * (every locale of the comment) or a supported locale code.
• action is one of COMMENT_RULE_ACTION_VALUES: search only reports the match, replace substitutes replace for every occurrence, delete_block removes every occurrence, append adds replace (markdown, with \n and \t escapes) as new blocks, delete_comment drops the locale.

Rules run in order on each text leaf of the matched locale. A locale is will_update when its plain text changes or it is dropped, no_change when the rewrite keeps the text, matched for search-only rules; a row takes the strongest status of its locales. A literal rule narrows the repository scan with an escaped ilike pattern and its locale; any regex, wildcard find or wildcard locale lifts that part of the prefilter.

CommentsRewriteService

The plan/apply use case over BoardsCommentsService. createCommentsRewriteService(deps: { boardsComments: BoardsCommentsService; accounts: Pick<AccountsService, "resolveIdsByEmails"> }).

export async function replaceInComments(
  boards: BoardRepository,
  boardsRead: BoardReadRepository,
  accounts: AccountsService,
  ctx: ServiceContext
) {
  const rewrite = createCommentsRewriteService({
    boardsComments: createBoardsCommentsService({ boards, boardsRead }),
    accounts,
  });
  const plan = await rewrite.plan(
    {
      ownerEmail: "teacher@example.com",
      rules: [
        { find: "Stayman", locale: "fr", action: "replace", replace: "2♣" },
      ],
    },
    ctx
  );
  // plan.rows => [{ boardId, rowStatus, locales }], plan.stats => { scanned, matched, willUpdate, … }
  return rewrite.apply(plan, ctx); // => { ...stats, updated }
}

Analytics

BoardsAnalyticsService

The admin audit surface, composed over BoardReadRepository.aggregate and BoardAggregations. createBoardsAnalyticsService(deps: { boardsRead: BoardReadRepository }).

export async function auditSnapshot(boardsRead: BoardReadRepository) {
  const analytics = createBoardsAnalyticsService({ boardsRead });
  const byLevel = await analytics.groupByEnum("level"); // [{ value, count }]
  const names = await analytics.topValues("name", 10); // { items, totalDistinct, otherCount }
  const months = await analytics.dateHistogram("createdAt", "month");
  const comments = await analytics.commentsStats();
  return { byLevel, names, months, comments };
}

Bookmarks and votes

BookmarksService and VotingService

createBookmarksService(deps: { bookmarks: BookmarksRepository; boardsRead: BoardReadRepository }) and createVotingService(deps: { votes: VotingRepository; boardsRead: BoardReadRepository }). Both take a ServiceContext last on every method and scope the repository call to ctx.userId. Adding a bookmark or setting a vote first checks the board is one the caller may read (BoardQuery.visibleTo), and refuses a missing or another account's private board with the same AccessDeniedError; removing one's own row needs no check.

export function toggleBookmark(
  bookmarks: BookmarksRepository,
  boardsRead: BoardReadRepository,
  boardId: string,
  ctx: ServiceContext
): Promise<boolean> {
  return createBookmarksService({ bookmarks, boardsRead }).toggle(boardId, ctx); // true when added
}

SetVoteDTO = { boardId; voteType } is the vote input, and computeVoteDeltas drives the optimistic update on the client. The in-memory fakes createFakeBookmarksRepository() and createFakeVotingRepository() from @workspace/training/testing back the services' tests with the tables' semantics: one bookmark and one vote per (user, board).

Auction systems

AuctionSystemsService

createAuctionSystemsService(deps: { auctionSystems: AuctionSystemsRepository }): AuctionSystemsService. The catalogue is global reference data, read the same by every caller, so no method takes a ServiceContext. The API exposes it as auctionSystemsService in the authenticated context.

Ports

BoardRepository

Command side. WriteRepository<BoardCriteria, BoardUpdatePatch, PersistableBoardWrite, BoardDeleteOptions, BoardUpdateResult, BoardDeleteResult> plus the inserts. Theme links live on BoardThemesRepository.

BoardData is the owned-deal payload shape: an EditorBoardData whose auction and play comments are LocalizedField<RichText>. SupportedLanguage and BoardResult are re-exported from this port for convenience.

BoardThemesRepository

The board_themes junction, named after both sides. Reads take a BoardThemesQuery (empty().byBoard(id), .byBoards(ids), .byTheme(id), .byThemes(ids)) and the BoardThemesProjections.links() projection, which returns BoardThemeLink = { boardId; themeId } rows.

BoardReadRepository

ReadRepository<BoardQuery, BoardGetByIdOptions>: getById(id, projection, opts?), findMany(query, projection), findManyPaginated(query, projection), aggregate(aggregation). getById throws NotFoundError when no row matches. BoardGetByIdOptions is { viewerUserId?; visibleTo? }: the viewer drives permissions and avatars, visibleTo applies the rule of BoardWhere.visibleTo, so an invisible board is not found.

BookmarksRepository and VotingRepository

The board_bookmarks and board_votes user ↔ board links. Reads take a BookmarkQuery or a VoteQuery (empty().byUser(id), .byBoard(id)) and the BookmarkProjections.links() or VoteProjections.votes() projection, which return BookmarkLink = { userId; boardId } and BoardVote = { userId; boardId; voteType } rows. Deletes take BookmarkCriteria or VoteCriteria (byUserAndBoard(userId, boardId), where(...)), which refuse an empty where.

AuctionSystemsRepository

Pick<ReadRepository<AuctionSystemQuery>, "findMany">: the catalogue has no write path in the product. AuctionSystemQuery.empty() reads the whole catalogue, withFilters narrows it by id or identifier; AuctionSystemProjections.entity() returns AuctionSystem rows ordered by sortOrder.

createFakeAuctionSystemsRepository(seed?) from @workspace/training/testing is its in-memory fake.

Testing

makeBoard(faker, options), makeBoardDeal(faker, overrides), makeBoardSummary, makeBookmark, makeAuctionSystem, makeDealCode and makePersistableBoardWrite come from @workspace/training/factories. makeBoard takes compact hands, auction and dealer strings plus partial metadata and board overrides.

export function fixture(faker: Faker): Board {
  return makeBoard(faker, {
    hands: "AKQ2.KQ3.A54.K32 / JT98.JT9.KQJ.JT9",
    auction: "1NT pass 3NT AP",
    metadata: { sharing: "public", level: 2 },
  });
}

Errors

Claim and write services return rejections as data (BoardsWriteOutcome, ClaimPlan, BulkClaimStats) rather than throwing; BoardClaimService.apply and BoardService.create escalate a gate rejection to a plain Error or a ValidationError respectively. See Errors for the base classes.