Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 | 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 7x 7x 7x 7x 7x 7x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 3x 3x 3x 3x 1x 1x 1x 1x 1x 1x 1x 23x 23x 23x 23x 23x 23x 23x 23x 23x 23x 23x 23x 23x 1x 1x 1x 1x 1x 1x 1x 30x 30x 30x 30x 30x 30x 30x 2x 1x 1x 2x 2x 2x 2x 2x 2x 2x 2x 2x 2x 30x 30x 9x 9x 9x 9x 9x 9x 9x 9x 4x 4x 4x 4x 4x 4x 9x 6x 6x 6x 9x 1x 1x 8x 8x 8x 8x 30x 30x 5x 5x 5x 5x 5x 5x 5x 5x 3x 3x 3x 3x 3x 5x 1x 1x 1x 5x 1x 1x 4x 4x 4x 4x 30x 30x 8x 8x 3x 3x 3x 3x 3x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 5x 30x 30x 2x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 30x 30x 3x 3x 3x 3x 3x 30x 30x 1x 1x 1x 1x 1x 30x 30x 30x 30x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x | /**
* Adult review & repair domain logic (#158).
*
* Single home for the per-attempt review mutations invoked by the results
* PATCH route and the timing-review UI, plus session-level soft delete /
* restore. Kept out of the route so the mutation logic is unit-testable and
* shared with any other caller (never forked).
*
* Design (per the shared #156/#157/#158 contract):
* - `responseTimeMs` and `responseTimeMsRaw` are NEVER mutated by review.
* Manual replacements live in `timingReview.adjustedResponseTimeMs`; the
* original measurement is always preserved.
* - Scopes are independent: mastery exclusion = `source: 'teacher-excluded'`
* (+ `originalSource` for restore); timing omission = `omitFromTiming`.
* - `timingReview` doubles as the review-audit stamp: every action records the
* acting adult (`reviewedBy`) and time (`reviewedAt`), even a mastery-only
* change, since `SlotResult` has no other per-attempt reviewer field.
*/
import { eq } from 'drizzle-orm'
import { db, schema } from '@/db'
import type {
SessionPlan,
SessionStatus,
SlotResult,
SlotResultSource,
SlotTimingReview,
} from '@/db/schema/session-plans'
import { getSessionPlan, updateSessionPlanResults } from './session-planner'
/**
* Bounds for a manually-entered response time (`set_time`): 1 second to 24
* hours. The upper bound is deliberately generous (not a 30-minute cap) so an
* adult can "count the full recorded time" — restore a Tier-1 raw value that
* legitimately exceeds the auto-pause clamp; that adjusted value re-enters the
* estimate and is never re-classified.
*/
export const SET_TIME_MIN_MS = 1_000
export const SET_TIME_MAX_MS = 24 * 60 * 60 * 1000 // 86_400_000
/** Statuses a session may be soft-deleted from (only finished sessions). */
const SOFT_DELETABLE_STATUSES: readonly SessionStatus[] = ['completed', 'abandoned']
/**
* Error carrying the HTTP status a route should surface. The route catches
* this and maps it directly to a `NextResponse`, so the domain layer owns the
* validation semantics while staying framework-free.
*/
export class SessionReviewError extends Error {
constructor(
message: string,
public readonly status: number
) {
super(message)
this.name = 'SessionReviewError'
}
}
/** Which axis (or both) a scoped exclude/include acts on. */
export type SlotReviewScope = 'timing' | 'mastery' | 'both'
/**
* A single per-attempt review action.
*
* `exclude`/`include` default to `scope: 'mastery'` for backward compatibility
* with the pre-#158 route (`{ action: 'exclude' }` sets `teacher-excluded`).
*/
export type SlotResultReviewAction =
| { action: 'mark_correct' }
| { action: 'exclude'; scope?: SlotReviewScope }
| { action: 'include'; scope?: SlotReviewScope }
| { action: 'set_time'; adjustedResponseTimeMs: number }
| { action: 'clear_time' }
| { action: 'confirm_timing' }
| { action: 'unconfirm_timing' }
export type SlotResultReviewActionName = SlotResultReviewAction['action']
/** Legacy shape: the pre-#158 route stored the pre-exclusion source here. */
type LegacyOriginalSource = SlotResult & { _originalSource?: SlotResultSource }
/**
* Resolve the source an excluded attempt should restore to, tolerating the
* legacy untyped `_originalSource` key written by the pre-#158 route.
*/
function readOriginalSource(result: SlotResult): SlotResultSource | undefined {
if (result.originalSource != null) return result.originalSource
return (result as LegacyOriginalSource)._originalSource ?? undefined
}
/**
* Merge a patch into the attempt's `timingReview`, always (re)stamping the
* acting adult and timestamp. Clearing a field is expressed by passing it as
* `undefined` in the patch (JSON serialization drops it, and every reader uses
* `!= null`).
*/
function stampTimingReview(
result: SlotResult,
patch: Partial<Omit<SlotTimingReview, 'reviewedBy' | 'reviewedAt'>>,
reviewerUserId: string,
now: Date
): SlotTimingReview {
return {
...result.timingReview,
...patch,
reviewedBy: reviewerUserId,
reviewedAt: now.toISOString(),
}
}
/**
* Pure transformation: apply a review action to one attempt and return the new
* result. Throws {@link SessionReviewError} on invalid/no-op requests. Never
* mutates the input or the stored `responseTimeMs`/`responseTimeMsRaw`.
*/
export function computeReviewedResult(
result: SlotResult,
action: SlotResultReviewAction,
reviewerUserId: string,
now: Date = new Date()
): SlotResult {
switch (action.action) {
case 'mark_correct': {
if (result.isCorrect) {
throw new SessionReviewError('Result is already correct', 400)
}
const epochNumber = result.epochNumber ?? 0
const masteryWeight = 1.0 / 2 ** epochNumber
return {
...result,
isCorrect: true,
masteryWeight,
source: 'teacher-corrected',
timingReview: stampTimingReview(result, {}, reviewerUserId, now),
}
}
case 'exclude': {
const scope = action.scope ?? 'mastery'
const wantMastery = scope === 'mastery' || scope === 'both'
const wantTiming = scope === 'timing' || scope === 'both'
const next: SlotResult = { ...result }
const timingPatch: Partial<Omit<SlotTimingReview, 'reviewedBy' | 'reviewedAt'>> = {}
let changed = false
if (wantMastery && next.source !== 'teacher-excluded') {
// Preserve the pre-exclusion source (may be undefined = 'practice') so
// include() can restore it exactly.
next.originalSource = next.source
next.source = 'teacher-excluded'
changed = true
}
if (wantTiming && !next.timingReview?.omitFromTiming) {
timingPatch.omitFromTiming = true
changed = true
}
if (!changed) {
throw new SessionReviewError('Result is already excluded for the requested scope', 400)
}
next.timingReview = stampTimingReview(result, timingPatch, reviewerUserId, now)
return next
}
case 'include': {
const scope = action.scope ?? 'mastery'
const wantMastery = scope === 'mastery' || scope === 'both'
const wantTiming = scope === 'timing' || scope === 'both'
const next: SlotResult = { ...result }
const timingPatch: Partial<Omit<SlotTimingReview, 'reviewedBy' | 'reviewedAt'>> = {}
let changed = false
if (wantMastery && next.source === 'teacher-excluded') {
next.source = readOriginalSource(result) ?? 'practice'
delete next.originalSource
delete (next as LegacyOriginalSource)._originalSource
changed = true
}
if (wantTiming && next.timingReview?.omitFromTiming) {
timingPatch.omitFromTiming = false
changed = true
}
if (!changed) {
throw new SessionReviewError('Result is not excluded for the requested scope', 400)
}
next.timingReview = stampTimingReview(next, timingPatch, reviewerUserId, now)
return next
}
case 'set_time': {
const value = action.adjustedResponseTimeMs
if (!Number.isInteger(value) || value < SET_TIME_MIN_MS || value > SET_TIME_MAX_MS) {
throw new SessionReviewError(
`adjustedResponseTimeMs must be an integer between ${SET_TIME_MIN_MS} and ${SET_TIME_MAX_MS} ms`,
400
)
}
return {
...result,
// responseTimeMs is preserved untouched; the replacement lives here.
// Also clear any prior `omitFromTiming`: in the resolution order omit
// wins over an adjusted value, so leaving both set would make the manual
// value dead. Entering an explicit time means "count THIS value", so
// setting a time from an omitted state re-includes the sample.
timingReview: stampTimingReview(
result,
{ adjustedResponseTimeMs: value, omitFromTiming: false },
reviewerUserId,
now
),
}
}
case 'clear_time': {
if (result.timingReview?.adjustedResponseTimeMs == null) {
throw new SessionReviewError('Result has no adjusted time to clear', 400)
}
return {
...result,
timingReview: stampTimingReview(
result,
{ adjustedResponseTimeMs: undefined },
reviewerUserId,
now
),
}
}
case 'confirm_timing': {
return {
...result,
timingReview: stampTimingReview(result, { timingConfirmed: true }, reviewerUserId, now),
}
}
case 'unconfirm_timing': {
return {
...result,
timingReview: stampTimingReview(result, { timingConfirmed: false }, reviewerUserId, now),
}
}
default: {
const _exhaustive: never = action
throw new SessionReviewError(
`Unknown review action: ${String((_exhaustive as { action?: string }).action)}`,
400
)
}
}
}
export interface ApplySlotResultReviewParams {
planId: string
/** Expected owner; enforced against the loaded plan (returns 404 on mismatch). */
playerId: string
resultIndex: number
/** User ID of the acting adult (stamped into the audit fields). */
reviewerUserId: string
action: SlotResultReviewAction
now?: Date
}
/**
* Load the plan, verify ownership + index, apply the review action, and persist
* via `updateSessionPlanResults`. Restricted to finished sessions is enforced
* by the caller (the results route only exposes this for review); the plan
* itself may be in any status here since the review UI targets history.
*/
export async function applySlotResultReview(
params: ApplySlotResultReviewParams
): Promise<SessionPlan> {
const { planId, playerId, resultIndex, reviewerUserId, action, now = new Date() } = params
const plan = await getSessionPlan(planId)
if (!plan || plan.playerId !== playerId) {
// Don't distinguish "missing" from "not yours".
throw new SessionReviewError('Plan not found', 404)
}
if (!Number.isInteger(resultIndex) || resultIndex < 0 || resultIndex >= plan.results.length) {
throw new SessionReviewError('Result index out of bounds', 400)
}
const updatedResults = [...plan.results]
updatedResults[resultIndex] = computeReviewedResult(
updatedResults[resultIndex],
action,
reviewerUserId,
now
)
return updateSessionPlanResults(planId, updatedResults)
}
/**
* Soft-delete a finished session (status → 'deleted'), preserving the prior
* status for exact restore. Raw results are kept (they feed BKT history) and
* the row stays loadable by ID so the session page can show a restore banner.
*
* NOTE (v1 scope): the denormalized `player_skill_mastery` counters and
* `lastPracticedAt` written at record time are NOT unwound here. BKT pKnown
* recomputes live from status-filtered history so it self-corrects on the next
* plan; the counters are a documented follow-up.
*/
export async function softDeleteSessionPlan(params: {
planId: string
playerId: string
deletedByUserId: string
now?: Date
}): Promise<SessionPlan> {
const { planId, playerId, deletedByUserId, now = new Date() } = params
const plan = await getSessionPlan(planId)
if (!plan || plan.playerId !== playerId) {
throw new SessionReviewError('Plan not found', 404)
}
if (plan.status === 'deleted') {
throw new SessionReviewError('Session is already deleted', 400)
}
if (!SOFT_DELETABLE_STATUSES.includes(plan.status)) {
throw new SessionReviewError(
`Only completed or abandoned sessions can be deleted (status: ${plan.status})`,
409
)
}
const [updated] = await db
.update(schema.sessionPlans)
.set({
status: 'deleted',
statusBeforeDeletion: plan.status,
deletedAt: now,
deletedBy: deletedByUserId,
})
.where(eq(schema.sessionPlans.id, planId))
.returning()
if (!updated) {
throw new SessionReviewError('Plan not found', 404)
}
return updated
}
/**
* Restore a soft-deleted session to its prior status (recorded at delete time).
*/
export async function restoreSessionPlan(params: {
planId: string
playerId: string
}): Promise<SessionPlan> {
const { planId, playerId } = params
const plan = await getSessionPlan(planId)
if (!plan || plan.playerId !== playerId) {
throw new SessionReviewError('Plan not found', 404)
}
if (plan.status !== 'deleted') {
throw new SessionReviewError('Session is not deleted', 400)
}
// Fall back to 'completed' for legacy rows deleted before this column existed.
const restoredStatus: SessionStatus = plan.statusBeforeDeletion ?? 'completed'
const [updated] = await db
.update(schema.sessionPlans)
.set({
status: restoredStatus,
statusBeforeDeletion: null,
deletedAt: null,
deletedBy: null,
})
.where(eq(schema.sessionPlans.id, planId))
.returning()
if (!updated) {
throw new SessionReviewError('Plan not found', 404)
}
return updated
}
|