Sessions

The sessions module models what a group does on a given day: a named session carrying an ordered list of boards. A session can be created (persisted, with a permanent public code) or expected (virtual, derived from the group's weekly recurrence and not yet persisted). The teacher app's calendar, the session detail page, the public session page served by the player and the PDF export all read from here.

Import from @workspace/training/domain/sessions and @workspace/training/application/sessions.

Domain

Session types

GroupSession = CreatedGroupSession | ExpectedGroupSession, discriminated on status. Session is an alias of CreatedGroupSession.

boards is the deduped union of the boards reached through linkedCollections (in collection position order, then the collection's own order) and the ad-hoc boards. A board present in a linked collection and ad-hoc appears once, at its collection's position. Each entry is a CollectionBoardEntry from Boards: available with the full board, or an unavailable tombstone with the id only when the owner unshared it.

Occurrence key

OccurrenceKey is a string {groupId}:{YYYY-MM-DD} identifying one weekly slot of a group. A created session and the expected occurrence it fulfils share the same key; this is how the two lists are merged.

Visibility and public link

Every created session has a permanent code, assigned at creation and never updated. Only sessions whose visibility is enabled, and whose availability window includes now, are served at the public URL.

PublicContent is an alias of RichText from @workspace/rich-text: the teacher composes the public page in one editor, with magic-variable slots resolved at render time. PublicContentPatch is PublicContent | null, the value both public-link ports write, where null clears the content.

PUBLIC_CONTENT_SLOT_NAMES.boardsList; // => "boards_list"

textToParagraphs("Hello\nthere\n\nSee you"); // => two paragraphs, a line-break inside the first

// Legacy `{ intro, closing }` rows are migrated on read; invalid content gives null with a reason.
export function readPublicContent(raw: string | null, sessionId: string) {
  return parseStoredPublicContent(raw, {
    onLegacyMigration: () => {
      console.info("legacy public content migrated", sessionId);
    },
    onInvalid: (reason) => {
      console.warn("invalid public content", sessionId, reason);
    },
  });
}

Session code

generateSessionCode(); // => "K7MDP2XQ" (8 characters, unambiguous alphabet)
SESSION_CODE_LENGTH; // => 8

Board id helpers

export function splitBoards(session: CreatedGroupSession) {
  const fromCollections = getCollectionBoardIds(session); // deduped, collection position order
  const adHoc = getAdHocBoardIds(session); // session.boards minus the collection ones
  return { fromCollections, adHoc };
}

Recurring sessions

Pure date arithmetic on local dates (YYYY-MM-DD), no clock.

The merge of created and expected occurrences is internal to the domain; call GroupSessionsService.getOccurrences from application code.

export function expectedThisAutumn(groups: Group[]) {
  // Only weekly, non-archived groups produce occurrences; the window is also
  // clamped by each group's startDate / endDate.
  return computeExpectedOccurrences({
    groups,
    from: "2026-09-01",
    to: "2026-12-31",
  }); // => ExpectedGroupSession[] sorted by date
}

buildOccurrenceKey("group-1", "2026-09-21"); // => "group-1:2026-09-21"

Completeness

The calendar colours a session by how its board count compares with the previous session of the same group.

export function completenessByKey(
  sessions: CreatedGroupSession[],
  merged: GroupSession[]
): Map<string, string> {
  const previous = buildPreviousBoardCountMap(sessions);
  const result = new Map<string, string>();
  for (const session of merged) {
    result.set(
      session.occurrenceKey,
      getSessionCompleteness(session, previous.get(session.occurrenceKey))
    );
  }
  return result; // "expected" | "empty" | "incomplete" | "complete"
}

Projections

Domain errors

DuplicateBoardInSessionError extends AppError with code DUPLICATE_BOARD_IN_SESSION, isExpected: true and a boardIds: string[] field listing the offenders. The duplicate guard that throws it is internal: it rejects a payload that repeats an id, then a payload that contains an id already on the session. The same guard protects collections.

Application

GroupSessionsService

createGroupSessionsService(deps: GroupSessionsServiceDeps): GroupSessionsService, where the deps are { sessions: GroupSessionsRepository; sessionsRead: GroupSessionsReadRepository; sessionBoards: GroupSessionBoardsRepository; sessionCollections: GroupSessionCollectionsRepository; collectionsRead: DealCollectionsReadRepository; groupsRead: GroupsReadRepository; boardsRead: BoardReadRepository; entitlements: EntitlementsGate; uow: GroupSessionsUnitOfWork }.

create and update write through uow.run: the session row and its board and collection links commit or roll back together. GroupSessionsTx is { sessions; sessionBoards; sessionCollections }, bound to the transaction; createDrizzleGroupSessionsUnitOfWork(db: OwnerConnection) implements it.

Every method composes the canonical ports: a GroupSessionQuery or a GroupSessionCriteria, a projection or an aggregation, and the two junction repositories for the links. The service hydrates the detail() projection (board ids) into CreatedGroupSession entities (board entries) with one board read per session, scoped to the boards ctx.userId may read (visibleTo): ids the caller cannot read become unavailable tombstones, inside linked collections too. The ServiceContext comes last everywhere.

Access. A session belongs to the owner of its group, and only that account reads or changes it. The service decides, on the owner's predicate (ownerId), before reading the session itself:

• a session id: the caller's own session goes through; any other id, another account's or a missing one, throws AccessDeniedError, so the answer does not reveal whether the session exists;
• a group id (create, listByGroup, listScheduledDates): the same rule, on the caller's groups;
• a collection id (create, update, linkCollection): the same rule, on the caller's collections;
• a board id (create, addBoards, and the ids update and updateBoardOrder add): it must be a board the caller may read, else InvalidBoardReferenceError. Boards already on the session stay, readable or not.

Each refusal comes before any write.

export function buildGroupSessions(repositories: {
  sessions: GroupSessionsRepository;
  sessionsRead: GroupSessionsReadRepository;
  sessionBoards: GroupSessionBoardsRepository;
  sessionCollections: GroupSessionCollectionsRepository;
  collectionsRead: DealCollectionsReadRepository;
  groupsRead: GroupsReadRepository;
  boardsRead: BoardReadRepository;
  uow: GroupSessionsUnitOfWork; // a session and its links commit together
}): GroupSessionsService {
  return createGroupSessionsService({
    ...repositories,
    entitlements: allowAllEntitlements,
  });
}

export function calendar(
  service: GroupSessionsService,
  ctx: ServiceContext
): Promise<GroupSession[]> {
  // `to` defaults to from + 365 days; created sessions win over expected ones
  // sharing the same occurrenceKey.
  return service.getOccurrences(
    { from: "2026-09-01", to: "2026-12-31", expectedFrom: "2026-10-08" },
    ctx
  );
}

export async function scheduleSession(
  service: GroupSessionsService,
  groupId: string,
  boardIds: string[],
  ctx: ServiceContext
): Promise<CreatedGroupSession> {
  const session = await service.create(
    groupId,
    { name: "Week 3: overcalls", date: "2026-09-21", boardIds },
    ctx
  );
  await service.setPublicVisibility(
    session.id,
    { enabled: true, availableTo: "2026-09-28T00:00:00Z" },
    ctx
  );
  return session;
}

export async function addBoards(
  service: GroupSessionsService,
  sessionId: string,
  boardIds: string[],
  ctx: ServiceContext
): Promise<number> {
  try {
    return await service.addBoards(sessionId, boardIds, ctx);
  } catch (error) {
    if (isAppError(error)) {
      error.code; // "SESSION_NOT_FOUND" | "DUPLICATE_BOARD_IN_SESSION" | "INVALID_BOARD_REFERENCE"
    }
    throw error;
  }
}

export async function attachCollection(
  service: GroupSessionsService,
  sessionId: string,
  collectionId: string,
  ctx: ServiceContext
): Promise<void> {
  await service.linkCollection(sessionId, collectionId, ctx); // ConflictError(COLLECTION_ALREADY_LINKED) when already linked
  await service.unlinkCollection(sessionId, collectionId, ctx); // idempotent
  await service.unlinkCollection(sessionId, collectionId, ctx); // resolves too
}

DTOs

collectionIds on update has replace semantics: ids removed are unlinked, ids added are linked at their index. Omit it to leave the links untouched. The code is never updatable.

Query objects

The generics are described on Queries. The session family binds them as follows.

GroupSessionQuery (read side), over QueryParams<GroupSessionWhere, GroupSessionSort>.

GroupSessionCriteria (write side and aggregates): byId, byIds, byGroup, where and .and(where). Refuses an empty where.

GroupSessionWhere: id, groupId, ownerId and code, each an Equality<string>; dateRange, a GroupSessionDateRange { from, to } of inclusive days; publiclyVisible, a boolean naming the visibility predicate. ownerId maps to the owner of the session's group, so it scopes writes too.

GroupSessionProjections

Board counts and the detail() board ids are the deduped union of the linked collections' boards and the ad-hoc ones, as CreatedGroupSession.boards describes.

RawCreatedGroupSession is Omit<CreatedGroupSession, "boards" | "linkedCollections"> & { boardIds: string[]; linkedCollections: RawLinkedCollection[] }.

GroupSessionAggregations: count(criteria), the number of matching sessions; calendarDays(criteria), the distinct UTC days (YYYY-MM-DD) the matching sessions fall on, ascending. GroupSessionSort: { column: "date" \| "name"; desc: boolean }, whitelisted by GROUP_SESSION_SORT_COLUMNS. GroupSessionPatch: name, date, the three visibility columns and publicContent; only the provided fields change, and an empty patch writes nothing.

export function sessionsOfMonth(
  sessionsRead: GroupSessionsReadRepository,
  ownerId: string
) {
  // Both days inclusive; the detail keeps boards by id for the service to hydrate.
  return sessionsRead.findMany(
    GroupSessionQuery.empty().byOwner(ownerId).between("2026-09-01", "2026-09-30"),
    GroupSessionProjections.detail()
  ); // => RawCreatedGroupSession[], by date
}

Ports

GroupSessionsReadRepository is ReadRepository<GroupSessionQuery>: getById(id, projection), findMany(query, projection), findManyPaginated(query, projection), aggregate(aggregation), plus the public-link read getPublicLink(sessionId) => Promise<PublicLink | null>, null only when the session does not exist. getById throws NotFoundError(SESSION_NOT_FOUND) when no row matches.

GroupSessionsRepository is WriteRepository<GroupSessionCriteria, GroupSessionPatch, PersistableGroupSessionWrite> plus writeOne(input) => Promise<{ sessionId: string }> and the public-link write updatePublicContent(sessionId, content: PublicContentPatch) => Promise<void>, which replaces the public content alone and bumps updatedAt. update, updateMany and delete report the affected ids; a delete cascades to both link tables.

getPublicLink and updatePublicContent are the public-link pair the deal collections ports carry too, implemented once in the database package.

The session links junctions

A session's ad-hoc boards and its linked collections are two ordered links, each its own repository, as Junction tables prescribes. Each link carries a 0-based position; reads come back by session, then by position. Writes lock the session row and run in one transaction inside the repository.

GroupSessionBoardsRepository

GroupSessionCollectionsRepository has the same four methods over GroupSessionCollectionsQuery, GroupSessionCollectionsCriteria and GroupSessionCollectionLink rows { sessionId, collectionId, position }, with replaceAll(sessionId, orderedCollectionIds). Its writeMany turns the unique index into ConflictError(COLLECTION_ALREADY_LINKED), so a link that races past the service's check still answers the typed conflict. A link that survives a replaceAll keeps its added_at.

Both queries take .bySession(id), .bySessions(ids) and the child's .byBoard(id) / .byBoards(ids) or .byCollection(id) / .byCollections(ids); both criteria have bySession, the child's byBoard or byCollection, where and .and(where). GroupSessionBoardWrite is { sessionId: string; boardId: string }, GroupSessionCollectionWrite { sessionId: string; collectionId: string }.

SessionDealsReader

Read-side port used by telemetry and usage analytics: the deals of one session, in session order, each once. Its 1-based position is the "deal N" shown next to a session-scoped metric. Bespoke by design: two parallel statements over the session, its group's owner, both junctions, the linked collections' boards and the board codes, where the canonical ports would chain four round trips.

ScopedDeal is { code: string; position: number } from @workspace/training/application/shared.

Errors

Test data: makeCreatedGroupSession, makeRawCreatedGroupSession, makeRawLinkedCollection, makeGroupSessionSummary, makeGroupSessionPreview, makePublicSessionData, makeExpectedGroupSession, makePublicLink, makePublicContent and makeSessionVisibility in Factories. In-memory fakes in Testing: createFakeGroupSessionsRepositories, createFakeGroupSessionBoardsRepository and createFakeGroupSessionCollectionsRepository.

export function sessionFixture(faker: Faker): CreatedGroupSession {
  return makeCreatedGroupSession(faker, { boardCount: 4 });
}