Formation DELF

122    await client.query("begin");123    for (const f of FIXES) {124      const row = qs.rows.find((r) => r.id === f.qid)!;125      const res = await client.query(126        `update questions set correct_answer_index = $1, correct_answer = $2, updated_at = now()127          where id = $3 and correct_answer_index = $4`,128        [f.to, row.options[f.to], f.qid, f.from],129      );130      if (res.rowCount !== 1) throw new Error(`update guard failed for question ${f.qid}`);131    }

The WHERE clause carries the expected old key: if the row changed since the audit, nothing is written.

62/**63 * The official PE anomalies, and the word-floor fraction under which a response64 * is treated as "manque de matière" (< 50 % of the expected words → 0 on every65 * criterion) per the grille.66 */67export const MANQUE_MATIERE_FRACTION = 0.5;68 69/**70 * Resolve the effective PE anomaly. The two *length-based* anomalies are decided71 * here from the word count — never trusted from the model (same rigor as72 * `total25`): a blank copy is `copie_blanche`, and a copy under half the word73 * floor is `manque_matiere`. A length anomaly the model emitted but the count74 * doesn't support is discarded (so a hallucinated `copie_blanche` can't wrongly75 * zero a full-length copy); content-based anomalies (`hors_sujet_*`) are kept as76 * the model reported them.77 */78export function resolveEcriteAnomalie(79  modelAnomalie: string | null | undefined,80  wordCount: number,81  wordMin: number,82): string | null {83  if (wordCount === 0) return "copie_blanche";84  if (wordMin > 0 && wordCount < wordMin * MANQUE_MATIERE_FRACTION) return "manque_matiere";85  if (modelAnomalie === "copie_blanche" || modelAnomalie === "manque_matiere") return null;86  return modelAnomalie ?? null;87}

Length is counted by code. Under half the required words, every criterion is capped to 0 after the model returns.

3import { createHash } from "node:crypto";4 5/**6 * A short fingerprint of an écrite evaluation prompt template, stored on every7 * prompt version and every harness run. The exact mirror of the orale-eval hash.8 *9 * Scores drifting between two runs is only actionable if you can tell *why*.10 * Persisting the hash alongside the model id turns "lexique dropped a band" into11 * "lexique dropped a band and the prompt changed" — or, more usefully, "lexique12 * dropped a band and the prompt did NOT change", which points at the model.13 *14 * It is also how the page knows a stored result is stale: a run whose hash no15 * longer matches the current draft was produced by a prompt that no longer16 * exists, so its scores describe the past, not the present.17 *18 * Hashes the template itself, not a rendered prompt — the template *is* the19 * thing being versioned, and rendering would fold in an arbitrary fixture.20 */21export function hashPromptTemplate(template: string): string {22  return createHash("sha256").update(template).digest("hex").slice(0, 12);

Twelve hex characters identify a prompt version on every evaluation run, so stale results are flagged.

374/**375 * The first names candidates know the live examiners by, keyed by the real376 * choice. The ONE place a persona is named: the candidate dropdown prints the377 * name alone, the admin dropdown and ledger print it after the engine378 * ("Gemini Live (Caroline)"), so when a candidate writes in about "Caroline"379 * the admin can tell which model they are talking about without a lookup.380 *381 * Insertion order is the candidate dropdown's display order, and the first382 * entry is the candidate's default.383 */384export const PO_EXAMINER_PERSONAS = {385  "grok-voice-2.0": "Sara",386  [GEMINI_LIVE_EXAMINER_CHOICE]: "Caroline",387} as const satisfies Partial<Record<PoExaminerChoice, string>>;388 389/** The persona's first name for a choice, or null when the choice has no candidate-facing persona. */390export function examinerPersonaName(choice: PoExaminerChoice): string | null {391  return choice in PO_EXAMINER_PERSONAS392    ? PO_EXAMINER_PERSONAS[choice as keyof typeof PO_EXAMINER_PERSONAS]393    : null;394}

The examiner contract keeps the catalogue of engines evaluated; production sittings run on Gemini Live.

47export const PHONOLOGIE_AUDIO_MODEL =48  process.env.PO_PHONOLOGIE_AUDIO_MODEL || "google/gemini-2.5-pro";49 50const schema = z.object({51  band: grilleBandSchema,52  justification: z.string().min(1),53  traits: z.array(z.string()).max(12),54  confidence: z.enum(["haute", "moyenne", "basse"]),55});

Only used when live phonology scoring fails: Gemini 2.5 Pro listens to a trimmed sample of the recordings.

172  // Global countdown. Recomputes elapsed time from a Date.now() baseline on173  // each tick and on tab re-focus, so a throttled background tab can't drift174  // the clock — and so a tab that was frozen PAST zero still finishes the175  // moment it comes back. Hitting zero force-finishes the session: the exam is176  // over, the results screen is where the candidate belongs.177  useEffect(() => {178    if (finished || !hasStarted) return;179 180    if (!quizStartTimeRef.current) {181      // A resumed attempt adopts its ORIGINAL start stamp, so the countdown182      // continues where it left off; only a fresh attempt stamps now. Seeding183      // here rather than in a separate effect is deliberate — a separate effect184      // would run after this one, which would already have stamped `Date.now()`185      // and silently handed the candidate a new hour.186      quizStartTimeRef.current = resumeAt ?? Date.now();187    }188 189    const timer = setInterval(() => {190      const remaining = calculateTimeRemaining();191      setTimeRemaining(remaining);192      if (remaining <= 0) {193        clearInterval(timer);194        setIsFinished(true);195      }196    }, 1000);

Remaining time comes from a wall-clock baseline, re-checked when the tab comes back into view.

4 * Official DELF model (see docs/DELF_EXAM_REFERENCE.md section 2):5 *   - Each of the 4 competencies is marked out of 25 → total out of 100.6 *   - Pass = total ≥ 50/100 AND ≥ 5/25 in every competency (a score < 5 is7 *     éliminatoire and cannot be rescued by a strong score elsewhere).8 *   - The level (A1/A2/B1/B2) is the exam sat, not a derived band.9 */10 11export type DelfLevel = "A1" | "A2" | "B1" | "B2";12 13export const DELF_LEVELS: readonly DelfLevel[] = ["A1", "A2", "B1", "B2"] as const;14 15export const COMPETENCY_MAX = 25;16export const TOTAL_MAX = 100;17export const PASS_TOTAL = 50;18export const COMPETENCY_FLOOR = 5;

One rule file feeds the dashboard, the examen blanc and every result screen.

52export function decideCheckoutDedupe(input: {53  sessions: readonly CheckoutSessionSummary[];54  planKey: string;55  isDelfPlanKey: (key: string) => boolean;56  /** Unix seconds. */57  now: number;58}): CheckoutDedupeDecision {59  const { sessions, planKey, isDelfPlanKey, now } = input;60  const delf = sessions.filter((session) => {61    const key = session.metadata?.planKey;62    return typeof key === "string" && isDelfPlanKey(key);63  });64 65  const recentPurchase = delf.find(66    (session) =>67      session.status === "complete" &&68      session.metadata?.planKey === planKey &&69      now - session.created <= RECENT_PURCHASE_WINDOW_S,70  );71 72  return {73    recentPurchaseSessionId: recentPurchase?.id ?? null,74    sessionIdsToExpire: delf75      .filter((session) => session.status === "open")76      .map((session) => session.id),77  };78}

A pure function decides; the Stripe calls around it stay thin and easy to test.

458    const values = {459      clerkUserId: input.clerkUserId,460      planKey: plan.planKey,461      kind: plan.kind,462      source: input.source,463      stripeCheckoutSessionId: input.stripeCheckoutSessionId ?? null,464      stripePaymentIntentId: input.stripePaymentIntentId ?? null,465      amountPaidCents: input.amountPaidCents ?? null,466      currency: input.currency?.toLowerCase() ?? null,467      startsAt,468      expiresAt: expiresAtForPlan(plan, startsAt),469      ecriteTriesTotal: plan.ecriteTries,470      oraleTriesTotal: plan.oraleTries,471      grantedBy: input.grantedBy ?? null,472    };473 474    if (values.stripeCheckoutSessionId) {475      const inserted = await tx476        .insert(userPlans)477        .values(values)478        .onConflictDoNothing({ target: userPlans.stripeCheckoutSessionId })479        .returning();480      return { created: inserted.length > 0, plan: inserted[0] ?? null };481    }482 483    const [created] = await tx.insert(userPlans).values(values).returning();484    return { created: true, plan: created ?? null };485  });

Stripe retries are harmless: the unique checkout session id makes the second insert a no-op.

28/**29 * A compréhension série is locked for the current user when they lack premium30 * access AND an admin has not unlocked it (`series.is_free`), the one rule31 * shared with the séries listing and the examen blanc pool (lib/free-series.ts).32 */33async function isSeriesLockedForUser(category: string, seriesId: number, hasFullAccess: boolean) {34  if (hasFullAccess) return false;35  if (!isComprehensionCategory(category)) return true;36  const freeIds = await getFreeSeriesIds(category);37  return !freeIds.has(seriesId);38}

The lock is decided on the server before the player renders, never in the browser.

566  if (isFullRefund(charge)) {567    if (stripeSubscriptionId) {568      await cancelSubscriptionIfActive(stripeSubscriptionId);569    }570    if (paymentIntentId) {571      await revokeUserPlansByPaymentIntent(paymentIntentId);572      // A promo code used for this purchase can be used again.573      await releaseCouponForRefundedPayment(paymentIntentId);574    }

A full refund takes the same webhook path as the purchase, in reverse.