Preserve cohort homework, answer, submission, scoring, and statistics behavior

Parent epic: #5. Downstream aggregate consumer: #57. Final management parity: #59. Protected rehearsal: #60.

PM disposition

GROOMED / P0 / DEPENDENCY-BLOCKED. Do not dispatch engineering.

This issue preserves the adopted cohort-owned homework/question/answer/submission/scoring/statistics behavior behind shared courses services and supplies one exact, PII-free homework component result to #57. It does not redesign grading, own Enrollment preferences, send email, inspect protected data, or execute a production migration.

Normative authority

• _docs/PROCESS.md
• 04 — Preserved learner behavior, Studio coverage, migration checks
• 06 — Studio/admin API registry, authorization, revisions, operations, and audit
• 07 — learner privacy, grading repair, retention, and redaction
• 09 — course migration and score reconciliation
• 10 — Course/Cohort verification
• accepted copied-source characterization/provenance baseline #30 and shared operation/job primitives #31

Exact owned model and mutation boundary

Homework, Question, Submission, Answer, and HomeworkStatistics remain owned by one exact Cohort. A Submission belongs to one Homework and one Enrollment in that Homework's Cohort; its retained learner compatibility reference must resolve to the same durable learner as the Enrollment. An Answer belongs to that Submission and to a Question in the same Homework. Unknown, missing, duplicate, cross-Homework, cross-Enrollment, cross-Cohort, or mismatched learner state fails before mutation and is never repaired by family, slug/year, email, newest Cohort, or arbitrary primary-key inference.

Preserve all adopted question types, answer types, choice ordering, optional/required fields, draft/open/closed/scored behavior, due-date boundaries, create-versus-update behavior, answer checking/reveal, contribution fields, timestamps, and public/learner compatibility schemas. Scope is resolved before object lookup. Reads never create an Enrollment or Submission. A safe archive/delete protects every Question, Homework, Submission, Answer, component result, and statistics row with dependent history.

Learner submit/update is one atomic service mutation. Invalid or stale input re-renders the same canonical Cohort form with bounded field errors and leaves the prior Submission, Answers, scores, result identity, timestamps, and contribution fields unchanged. It performs no synchronous arbitrary-host fetch. HTTP/HTTPS and approved FAQ-link syntax/private-literal checks are local; any future remote verification is a bounded, SSRF-safe durable operation and is not score authority.

Exact adopted homework scoring rule

For one accepted Submission:

• questions_score is the sum of each accepted Question's configured scores_for_correct_answer when the preserved answer checker marks that Submission's one logical Answer correct; missing/blank/incorrect answers contribute zero. Question type, normalization, tolerance, multiple-choice and checkbox behavior remain source-characterized rather than reimplemented.
• faq_score is 1 only when the enabled FAQ field contains an accepted DataTalksClub FAQ issue/pull-request URL under the preserved validator; otherwise it is 0.
• learning_in_public_score is 0 when the owning Enrollment has disable_learning_in_public=true; otherwise it is the count of the Submission's accepted, normalized, de-duplicated HTTP/HTTPS learning-in-public links after the Homework cap and cohort-wide duplicate rules are applied.
• total_score = questions_score + faq_score + learning_in_public_score.

There is no second score formula in Studio, API, statistics, migration, #57, or a compatibility adapter. A scoring run uses one frozen Homework definition/settings revision and one frozen Submission/Answer input revision. It scores every in-scope Submission, stages Answer correctness, component values, result rows, Homework state, statistics, and downstream invalidation intent, then activates them atomically. Exact command replay returns the original operation/result; changed replay conflicts. Concurrent answer, definition, cap, Enrollment-preference, or Cohort change makes the candidate stale and leaves the prior complete revision active. Long/full-homework scoring and repair run as bounded durable operations with progress, safe per-row failures, cancellation before activation, lease/fence crash recovery, and no request-thread bulk loop.

Disabling learning in public through #244's accepted Enrollment-preference service immediately produces new #55 component results with that component zero and recomputed totals; it neither deletes the submitted links nor changes question/FAQ points. Re-enabling does not silently recreate points: an explicit authorized recomputation under the current input/settings revision is required. #244 owns the preference mutation and UI; #55 owns only the homework recomputation primitive and result.

HomeworkStatistics is derived only from the activated in-scope #55 results and preserves the characterized count/min/max/average/median/quartile/time behavior, null/empty distinctions, and calculation timestamp metadata. Statistics never become a scoring input.

Exact handoff to #57

The shared courses query/service exposes one immutable, PII-free HomeworkSubmissionScoreResult for each activated Submission revision with exactly:

• schema version and deterministic result_key;
• Course UUID, Cohort UUID, Enrollment UUID and retained Enrollment ordering identity;
• retained Homework and Submission identities;
• activated Homework score revision;
• questions_score, faq_score, learning_in_public_score, and total_score;
• ordered answer-outcome/input fingerprint, scoring-definition/settings fingerprint, and Enrollment learning-in-public preference revision; and
• reconciliation disposition and calculated timestamp as metadata, neither of which changes logical identity.

result_key is deterministic over the schema version, exact identities, accepted ordered input/result fingerprint, and score/settings/preference revision. It contains no learner name/email, answer text, free text, URL, profile value, or reversible learner identifier. Exact replay produces the same key and values; a changed answer, contribution, definition, point value, cap, preference, scope, or schema produces a new key and score revision. A stale, unactivated, duplicated, quarantined, or foreign result cannot be consumed.

The compatibility Submission.questions_score, faq_score, learning_in_public_score, and total_score fields are an atomic projection of the activated result, not a second authority. #57 computes homework_total by summing exactly one current accepted #55 total_score per logical Submission for the exact Cohort/Enrollment and includes the ordered #55 result identities in its own fingerprint. Missing legitimate rows contribute no points; unknown, duplicate, stale, quarantined, or cross-Cohort rows block activation rather than being guessed or moved.

Shared management and notification boundary

Register at least these exact capability keys through accepted #52 policy:

• courses.homework.view and courses.homework.manage;
• courses.homework_submission.view and courses.homework_submission.repair;
• courses.homework.score;
• courses.homework_statistics.view; and
• courses.homework_notification.initiate.

Studio and /api/v1/admin/ use the same courses query/command services for definition/question ordering, correct-answer workflow, submissions, deadline extension, score/rescore, statistics, repair, and notification-intent initiation. Mutations use UUID resources where supplied by the accepted foundations, revision/If-Match, Idempotency-Key, allowlisted bodies, generic scope-first errors, bounded bulk operations, and the accepted #28/#52 high-risk preview/confirmation/reauthentication/audit controls. No adapter, compatibility view, task, signal, or Django-admin action writes homework score/result/statistics state directly.

#55 owns only a versioned domain event/trigger and immutable scalar context after commit. It creates no renderer, sender, provider call, Datamailer write/requeue, Relay call, delivery status, or recipient export. #49 supplies the ordinary delivery-intent interface to the separately groomed #50 adapter; #50 consumes accepted #55 triggers later and is not a prerequisite for this non-sending component result.

Migration, reconciliation, and evidence identity

Repository verification uses deterministic synthetic fixtures only. #60 owns any separately authorized production-like rehearsal and cutover.

The engineer handoff freezes and records:

• full base/head SHAs and change-selective graph/plan/report digests;
• adopted source pin 98a235283904b4ef9ad29e196298540756cf1bcc, #30 copied-file manifest digest, and current integration-patch-ledger digest;
• exact prerequisite merge SHAs, migration leaves, and schema/migration-plan fingerprint;
• #51 Course/Cohort/retargeted-relation/mapping fingerprint;
• #52 capability/policy/registry/OpenAPI fingerprint;
• #53 lifecycle/route/alias/archive fingerprint;
• #244 Enrollment identity/preference/progress-route fingerprint;
• #55 question/answer/scoring/result/statistics/operation/domain-event schema versions plus the complete characterized-fixture checksum; and
• #57 homework-component consumer-schema fingerprint current at dispatch.

Synthetic preflight/dry-run/apply/exact replay/reverse/forward reports Homework/Question/Submission/Answer/result/statistics counts, retained key and Cohort/Enrollment mapping cardinalities, question-type and optional-field matrices, score-component/totals matrices, preference states, transformed/rejected/quarantined rows, and safe non-PII checksums. It preserves null/blank distinctions, timestamps, answer outcomes, scores, statistics, and sibling-Cohort isolation. Unknown mapping, duplicate logical Answer/Submission/result, student/Enrollment mismatch, cross-Cohort relation, unsupported question/answer type, invalid cap/score setting, or unexplained score/statistics drift fails closed and leaves the prior revision active. Evidence contains no answer/free text, submitted URL, learner identity, profile/certificate value, or production data.

Dependencies and readiness

Accepted baseline inputs are #30 and #31.

Engineering hard-depends on accepted and integrated:

1. #51 — final Course/Cohort identity, mechanically retargeted homework relations, and migration/rollback contract;
2. #52 — exact Course/Cohort capability, object/field policy, management registry, and audit boundary;
3. #53 — final Cohort lifecycle, canonical/legacy route identity, archive protection, and definition-only duplication behavior; and
4. #244 — final cohort-isolated Enrollment identity, learning-in-public preference semantics, learner progress/dashboard routes, and preservation/migration mapping.

#224 is transitive through #51; #32/#33/#40/#288 are transitive through #52/#244. Broad parent #54 is coordination only. #49/#50 are downstream notification integration. #57 consumes the accepted component result; #59 consumes management coverage; #60 consumes migration/reconciliation evidence. None is a prerequisite.

Readiness remains GROOMED / DEPENDENCY-BLOCKED. After all four hard inputs are accepted and integrated on one green current-main base, PM must revalidate the frozen identities and #57 consumer schema before an isolated engineer lane starts. A local candidate, current source model, copied characterization test, or partial migration does not imply acceptance. Any prerequisite, schema, migration, capability, route, preference, source-pin, or consumer drift returns #55 to PM.

Acceptance criteria

• Every Homework/Question/Submission/Answer/statistics relation and mutation is scoped to one exact Cohort/Enrollment, with all named mismatch/duplicate/cross-scope states rejected before mutation.
• Learner create/update/check/reveal and all question/answer/optional/deadline/state behaviors remain source-characterized; invalid input is atomic and performs no synchronous arbitrary-host fetch.
• The exact question, FAQ, learning-in-public, and total formulas above are the sole authority and preserve cap, duplicate, preference, re-enable, and boundary behavior.
• HomeworkSubmissionScoreResult has the exact PII-free schema and deterministic identity; exact replay is stable, changed/stale/foreign/quarantined input fails safely, compatibility fields are an atomic projection, and #57 can consume it without recalculating answers.
• Scoring/rescoring/repair and statistics are revisioned, idempotent, concurrency-safe, durable when long, atomically activated, crash/resume safe, and leave the prior complete revision visible on failure.
• Safe archive/delete protects dependent history; Cohort duplication copies definitions/order/configuration only and never learner Answers, Submissions, result identities, statistics, or history.
• Studio/admin API/compatibility adapters have service, capability, scope, revision, idempotency, operation, result/error, audit, and OpenAPI parity; no adapter writes domain state directly.
• Notification work stops at an after-commit versioned domain trigger/scalar context; no sender/provider/Datamailer/Relay or recipient-export behavior is introduced.
• Synthetic migration/reconciliation preserves mappings, values, timestamps, scores, statistics, and sibling isolation; every named corruption/drift case fails closed while protected rehearsal remains #60.
• Focused model/service/migration/API/security/concurrency/adoption tests plus graph-selected full verification pass on one frozen candidate; the independent tester inspects every required desktop/mobile screenshot before PM acceptance.

Required verification scenarios

1. Every copied question/answer type and optional field; blank/missing/Unicode/boundary values; draft/open/closed/scored, due-date/DST/leap-day boundaries, create/update/double-submit, reveal, and exact replay.
2. Correct/incorrect/missing/duplicate/cross-Homework Answers; same learner in sibling Cohorts; mismatched student/Enrollment; direct foreign identifiers; transaction failure before/after Answer staging.
3. Zero/one/many question points, FAQ accepted/rejected, learning links zero/at/beyond cap and duplicated within/across homework/project, preference enabled/disabled/re-enabled, and exact component/total/result-key matrices.
4. Concurrent score/rescore/input edit/settings edit/preference edit; stale revision, changed idempotency replay, crash/resume/cancel, partial-row failure, prior-revision visibility, statistics refresh, and cache/result invalidation.
5. Archive/delete with and without dependent responses/results; duplicate Cohort definitions then prove no learner/history copy and independent edit.
6. Studio/admin API allowed/denied actors, stale If-Match, exact/changed replay, bulk bound/partial result, progress/cancel/result, high-risk proof, audit/log redaction, CSRF/Bearer separation, OpenAPI/registry coverage, and compatibility parity.
7. Synthetic migration dry-run/apply twice/reverse/forward with missing/duplicate/cross-Cohort relations, unsupported type/settings, mapping/checksum drift, and all Datamailer/Relay/SES/provider paths patched to fail if called.
8. #57 contract test accepts only the current exact component result set, rejects stale/foreign/quarantined/duplicate/schema-drifted results, and reproduces the exact homework subtotal without answer-table recalculation.

Independent browser evidence

Using synthetic .invalid fixtures at approximately 1440×900 and 390×844, the separate tester captures and reads:

1. canonical learner Homework empty/open/closed/scored states, representative question types, invalid and successful create/update, answer result/reveal, and score breakdown;
2. learning-in-public and FAQ validation at enabled/disabled preference states plus a sibling-Cohort safe denial;
3. public statistics/submission states to the exact characterized visibility, including empty and populated cases; and
4. authorized/denied Studio definition/correct-answer/submission/extension/score-rescore/repair/statistics operation states including preview, progress, stale/conflict, failure, and success.

Include keyboard-only operation, visible focus/status/error announcement, 44 CSS px targets, 200% zoom and 320 CSS px reflow, reduced motion, and supported JavaScript-disabled form/confirmation/error paths. Screenshots contain no real or unnecessary synthetic learner identity, answer/free text, submitted URL, profile/certificate value, credential, provider, or production data.

Explicit non-goals

• No grading formula redesign, new question type, reusable/versioned curriculum, Course/Cohort/Enrollment identity, registration conversion, profile schema, leaderboard/completion/certificate algorithm, or intentional visibility change.
• No synchronous arbitrary URL fetch, destructive deletion of answered history, request-thread full-cohort work, score/statistics trust without reconciliation, or direct adapter/model mutation.
• No delivery-intent/recipient selection implementation, template, sender, Relay/Datamailer/provider action, email transport/status, production/protected data, live migration/import, deployment, workflow dispatch, commit, merge, or push during PM/engineering/tester gates.

Lifecycle

After prerequisites integrate, one engineer leaves an uncommitted frozen candidate and complete versioned verification report. A separate tester recomputes the plan, verifies every criterion, and captures/inspects required screenshots. PM then performs product acceptance. Only after both gates pass may the engineer create a focused Closes #55 commit; the orchestrator locally merges with --no-ff, pushes, and on-call alone observes terminal CI.

Read _docs/PROCESS.md and specs 04, 06, 07, 09, and 10 first, then review accepted baselines #30 and #31 and the hard dependencies #51, #52, #53, and #244. This issue is explicitly dependency-blocked and says not to dispatch engineering. Done requires the four prerequisites to be integrated before implementing the shared courses services, scoring/result behavior, verification evidence, and #57 handoff.