Interface TicketService

All Superinterfaces:

BaseImmutableService<Ticket>, BaseReadOnlyService<Ticket>, BaseService<Ticket>

All Known Implementing Classes:

TicketServiceImpl

public interface TicketService
extends BaseService<Ticket>

Service-layer API for the Phase B-1 Ticket layer (AUDIT_AS_WORKFLOW_RECCE.md). Mutating methods append a corresponding TicketEvent to the ticket's event log; persistence is via JPA cascade.

Author:

paul

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	TicketService.TargetAddition	What addTarget(Ticket, TicketTargetType, Long, Contact) did: the saved ticket, and whether the target was new to it.

Method Summary

Modifier and Type	Method	Description
Ticket	addComment(Ticket ticket, Contact actor, String payload)	Append a comment event (free-form payload).
TicketService.TargetAddition	addTarget(Ticket ticket, TicketTargetType targetType, Long targetId, Contact actor)	Add a target to a ticket that was already opened.
Ticket	assign(Ticket ticket, Contact actor, Contact assignee)	Assign (or re-assign) the ticket.
long	countOpen()
Map<TicketType, Long>	countOpenByType()
long	countTickets(boolean openOnly, Long assigneeId, TicketPriority priority)
long	countTickets(boolean openOnly, Long assigneeId, TicketPriority priority, TicketType type, TicketState state, TicketTargetType targetType, Date updatedSince)
List<Ticket>	findAssignedTo(Contact assignee)
CursorPage<TicketEvent>	findEventsByCursor(Ticket ticket, Cursor cursor, int limit)
Date	findOldestOpenCreatedAt()
List<Ticket>	findOpenForTarget(TicketTargetType targetType, Long targetId)
CursorPage<Ticket>	findOpenForTargetByCursor(TicketTargetType targetType, Long targetId, Cursor cursor, int limit)
Map<Long, List<TicketSummaryForTargetValueObject>>	findOpenSummariesForTargets(TicketTargetType targetType, Collection<Long> targetIds)
List<Ticket>	findTickets(boolean openOnly, Long assigneeId, TicketPriority priority, int offset, int limit)
List<Ticket>	findTickets(boolean openOnly, Long assigneeId, TicketPriority priority, TicketType type, TicketState state, TicketTargetType targetType, Date updatedSince, int offset, int limit)
CursorPage<Ticket>	findTicketsByCursor(boolean openOnly, Long assigneeId, TicketPriority priority, TicketType type, TicketState state, TicketTargetType targetType, Date updatedSince, Cursor cursor, int limit)
CursorPage<Ticket>	findTicketsByCursor(boolean openOnly, Long assigneeId, TicketPriority priority, Cursor cursor, int limit)
Ticket	getOrCreateScratchpad(Contact curator)	Return the curator's scratchpad, provisioning it on first call.
TicketValueObject	loadValueObject(Long id, boolean includeEvents)	Load a ticket and project it to a TicketValueObject inside the same transaction, force-initializing the reporter + assignee + targets (and events + each event's actor when includeEvents=true) so the projection doesn't raise LazyInitializationException once the transaction ends and the JAX-RS handler reads the returned VO.
Ticket	openTicket(Contact reporter, TicketType type, String title, Collection<TicketTarget> targets)	Create a new ticket and seed its event log with a single TicketEventType.OPENED event.
TicketTargetStatus	removeTarget(Ticket ticket, TicketTargetType targetType, Long targetId, Contact actor)	Remove a target from a ticket.
List<TicketSearchHitValueObject>	searchTickets(String query, boolean openOnly, Long callerContactId, int limit)	Find tickets a curator could be meaning when they type into a ticket picker — backs GET /tickets/search.
Ticket	transition(Ticket ticket, TicketState newState, Contact actor, String reason)	Transition the ticket to a new state.
Ticket	updateMetadata(Ticket ticket, String changedFields)	Persist metadata-only edits (priority, dueDate, title, body, mode, etc.) to a ticket.
Ticket	updateTargetScreeningResult(Ticket ticket, Long targetId, ScreeningResult screeningResult, String reason, boolean reasonProvided, Contact actor)	Record a ScreeningResult on one target (by its row id).
Ticket	updateTargetStatus(Ticket ticket, Long targetId, TicketTargetStatus newStatus, Contact actor)

Methods inherited from interface BaseImmutableService

create, create, findOrCreate, remove, remove

Methods inherited from interface BaseReadOnlyService

countAll, find, findOrFail, getElementClass, load, load, loadAll, loadOrFail, loadOrFail, loadOrFail, loadOrFail, loadOrFail, loadOrFail, streamAll, streamAll

Methods inherited from interface BaseService

save, save, update, update

Method Details

openTicket

Ticket openTicket(Contact reporter,
 TicketType type,
 String title,
 Collection<TicketTarget> targets)

Create a new ticket and seed its event log with a single TicketEventType.OPENED event.

Parameters:

reporter - who is creating the ticket (must be non-null)

type - domain category

title - short human title; mandatory

targets - one or more targets; must contain at least one entry

getOrCreateScratchpad

Ticket getOrCreateScratchpad(Contact curator)

Return the curator's scratchpad, provisioning it on first call.

A scratchpad is a TicketType.SCRATCHPAD ticket kept open indefinitely, holding whatever the curator is currently looking at; finishing with a dataset means REMOVING it from the scratchpad, not resolving the ticket (Paul, 2026-08-31). It is created with acceptsTargets = true, because a scratchpad nothing can be added to is inert, and with no targets, which is why this does not delegate to openTicket(Contact, TicketType, String, Collection) (that method requires at least one).

Identified by type == SCRATCHPAD and reporter == curator, with no state clause: a cancelled scratchpad is still the curator's, and comes back as-is for them to reopen through the normal state transition rather than being superseded by a fresh one.

🛑 Duplicate prevention is query-then-create inside one transaction, which is not a guarantee. Nothing in the schema forbids a second row, so two first-calls that both run the SELECT before either commits will both insert. What IS guaranteed is that the identity never splits afterwards: TicketDao.findScratchpad(Contact) orders by id ascending and takes one row, so every later call — this one included — returns the same ticket forever. A stray duplicate is an orphan row visible in GET /tickets?type=SCRATCHPAD and reachable by id, not a scratchpad that flips between two identities. Closing the window properly needs a unique index, which needs a migration.

The returned ticket has its lazy fields initialized for TicketValueObject.from(Ticket, boolean), events included, so the REST layer can project it after the transaction ends.

Parameters:

curator - the scratchpad's owner; recorded as the ticket's reporter

assign

Ticket assign(Ticket ticket,
 Contact actor,
 @Nullable
 Contact assignee)

Assign (or re-assign) the ticket. Appends an TicketEventType.ASSIGNED event. Pass assignee == null to clear an assignment (still appends an ASSIGNED event with a null target).

addComment

Ticket addComment(Ticket ticket,
 Contact actor,
 @Nullable
 String payload)

Append a comment event (free-form payload). Doesn't change ticket state; doesn't change the updatedAt field beyond bumping the audit timestamp.

transition

Ticket transition(Ticket ticket,
 TicketState newState,
 Contact actor,
 @Nullable
 String reason)

Transition the ticket to a new state. Appends a TicketEventType.STATE_CHANGED event (or one of the terminal-state aliases — RESOLVED / CANCELLED / REOPENED — when the new state matches the corresponding terminal). Bumps updatedAt.

updateMetadata

Ticket updateMetadata(Ticket ticket,
 String changedFields)

Persist metadata-only edits (priority, dueDate, title, body, mode, etc.) to a ticket. The caller mutates the Ticket arg in place, then passes a comma-separated list of changed field names so the audit trail row's NOTE column documents what changed.

Unlike transition(Ticket, TicketState, Contact, String), assign(Ticket, Contact, Contact), addComment(Ticket, Contact, String) — which append rows to BOTH log streams — metadata edits write to the governance AuditTrail stream ONLY (Decision 4 of AUDIT_AS_WORKFLOW_RECCE.md: "no TicketEvent log spam for fact-of-update edits"). Bumps updatedAt.

addTarget

TicketService.TargetAddition addTarget(Ticket ticket,
 TicketTargetType targetType,
 Long targetId,
 Contact actor)

Add a target to a ticket that was already opened.

Until this existed a ticket's targets were fixed at openTicket(Contact, TicketType, String, Collection): the other target methods only modify rows that are already there. The motivating case is a curator scratchpad — a ticket someone keeps adding experiments to as they meet them.

Two conditions, both refused with IllegalStateException:

• the ticket's acceptsTargets flag must be set. It is false by default and false on every ticket predating the flag, so an agent-created ticket keeps the fixed batch it was opened for unless someone deliberately opens it up.
• the ticket must not be TicketState.RESOLVED, whatever the flag says, so a finished ticket cannot quietly grow new work. The flag is not rewritten — reopening the ticket makes it effective again.

Adding a target already on the ticket is idempotent: the ticket comes back unchanged and TicketService.TargetAddition.isAdded() is false.

Returns:

the saved ticket, and whether this call is what put the target on it

removeTarget

@Nullable
TicketTargetStatus removeTarget(Ticket ticket,
 TicketTargetType targetType,
 Long targetId,
 Contact actor)

Remove a target from a ticket.

On a curator scratchpad this is what finishing with a dataset looks like — the ticket stays open and the dataset leaves it — so this is the counterpart of addTarget(Ticket, TicketTargetType, Long, Contact) rather than an afterthought.

Idempotent: removing a target the ticket does not have returns null rather than throwing, since the caller has already reached the state it asked for. A terminal ticket (RESOLVED / CANCELLED) refuses the change.

Removing a target whose status is past NOT_DONE is permitted — a scratchpad's rows are all NOT_DONE and refusing would make the common case pay for the rare one — so the removed status is returned and the caller decides what to say about it.

Returns:

the status the removed target had, or null if it was not on the ticket

updateTargetStatus

Ticket updateTargetStatus(Ticket ticket,
 Long targetId,
 TicketTargetStatus newStatus,
 Contact actor)

updateTargetScreeningResult

Ticket updateTargetScreeningResult(Ticket ticket,
 Long targetId,
 @Nullable
 ScreeningResult screeningResult,
 @Nullable
 String reason,
 boolean reasonProvided,
 Contact actor)

Record a ScreeningResult on one target (by its row id). Uncoupled from updateTargetStatus(Ticket, Long, TicketTargetStatus, Contact): the two are set independently. No-op when unchanged; writes a SCREENING_RESULT_CHANGED ticket event when it changes.

loadValueObject

@Nullable
TicketValueObject loadValueObject(Long id,
 boolean includeEvents)

Load a ticket and project it to a TicketValueObject inside the same transaction, force-initializing the reporter + assignee + targets (and events + each event's actor when includeEvents=true) so the projection doesn't raise LazyInitializationException once the transaction ends and the JAX-RS handler reads the returned VO.

Returns null when no ticket with that id exists; the REST surface turns that into a 404.

findOpenForTarget

List<Ticket> findOpenForTarget(TicketTargetType targetType,
 Long targetId)

See Also:

• TicketDao.findOpenForTarget(TicketTargetType, Long)

findOpenSummariesForTargets

Map<Long, List<TicketSummaryForTargetValueObject>> findOpenSummariesForTargets(TicketTargetType targetType,
 Collection<Long> targetIds)

See Also:

• TicketDao.findOpenSummariesForTargets(TicketTargetType, Collection)

findAssignedTo

List<Ticket> findAssignedTo(Contact assignee)

See Also:

• TicketDao.findAssignedTo(Contact)

findTickets

List<Ticket> findTickets(boolean openOnly,
 @Nullable
 Long assigneeId,
 @Nullable
 TicketPriority priority,
 int offset,
 int limit)

See Also:

• TicketDao.findTickets(boolean, Long, TicketPriority, int, int)

findTickets

List<Ticket> findTickets(boolean openOnly,
 @Nullable
 Long assigneeId,
 @Nullable
 TicketPriority priority,
 @Nullable
 TicketType type,
 @Nullable
 TicketState state,
 @Nullable
 TicketTargetType targetType,
 @Nullable
 Date updatedSince,
 int offset,
 int limit)

See Also:

• TicketDao.findTickets(boolean, Long, TicketPriority, TicketType, TicketState, TicketTargetType, Date, int, int)

countTickets

long countTickets(boolean openOnly,
 @Nullable
 Long assigneeId,
 @Nullable
 TicketPriority priority)

See Also:

• TicketDao.countTickets(boolean, Long, TicketPriority)

countTickets

long countTickets(boolean openOnly,
 @Nullable
 Long assigneeId,
 @Nullable
 TicketPriority priority,
 @Nullable
 TicketType type,
 @Nullable
 TicketState state,
 @Nullable
 TicketTargetType targetType,
 @Nullable
 Date updatedSince)

See Also:

• TicketDao.countTickets(boolean, Long, TicketPriority, TicketType, TicketState, TicketTargetType, Date)

findTicketsByCursor

CursorPage<Ticket> findTicketsByCursor(boolean openOnly,
 @Nullable
 Long assigneeId,
 @Nullable
 TicketPriority priority,
 @Nullable
 Cursor cursor,
 int limit)

See Also:

• TicketDao.findTicketsByCursor(boolean, Long, TicketPriority, Cursor, int)

findTicketsByCursor

CursorPage<Ticket> findTicketsByCursor(boolean openOnly,
 @Nullable
 Long assigneeId,
 @Nullable
 TicketPriority priority,
 @Nullable
 TicketType type,
 @Nullable
 TicketState state,
 @Nullable
 TicketTargetType targetType,
 @Nullable
 Date updatedSince,
 @Nullable
 Cursor cursor,
 int limit)

See Also:

• TicketDao.findTicketsByCursor(boolean, Long, TicketPriority, TicketType, TicketState, TicketTargetType, Date, Cursor, int)

findOpenForTargetByCursor

CursorPage<Ticket> findOpenForTargetByCursor(TicketTargetType targetType,
 Long targetId,
 @Nullable
 Cursor cursor,
 int limit)

See Also:

• TicketDao.findOpenForTargetByCursor(TicketTargetType, Long, Cursor, int)

findEventsByCursor

CursorPage<TicketEvent> findEventsByCursor(Ticket ticket,
 @Nullable
 Cursor cursor,
 int limit)

See Also:

• TicketDao.findEventsByCursor(Ticket, Cursor, int)

countOpenByType

Map<TicketType, Long> countOpenByType()

See Also:

• TicketDao.countOpenByType()

countOpen

long countOpen()

See Also:

• TicketDao.countOpen()

findOldestOpenCreatedAt

@Nullable
Date findOldestOpenCreatedAt()

See Also:

• TicketDao.findOldestOpenCreatedAt()

searchTickets

List<TicketSearchHitValueObject> searchTickets(String query,
 boolean openOnly,
 @Nullable
 Long callerContactId,
 int limit)

Find tickets a curator could be meaning when they type into a ticket picker — backs GET /tickets/search. Exists because a flat dropdown of every open ticket stops being usable well before the corpus does.

query matches EITHER a ticket id typed verbatim (digits and nothing else: "6" is ticket 6, "6 samples" is title text) OR a case-insensitive substring of the title — a curator has whichever of the two is to hand. An id that parses but names no ticket simply contributes no hit; it is not an error, and the caller should not turn it into a 404.

Hits come back exact-id-first, then by updatedAt descending, truncated to limit. Each is a TicketSearchHitValueObject, whose targetCount is counted in SQL — no TicketTarget row is loaded.

Parameters:

query - id or title fragment; blank yields no hits

openOnly - restrict to OPEN/IN_PROGRESS. The REST default is true: work is rarely added to a closed ticket

callerContactId - the calling curator's contact id, or null when anonymous. Their own TicketType.SCRATCHPAD tickets are offered; nobody else's are

limit - maximum hits; must be greater than zero