Parent: #39
Goal
Define the complete contracts of FlashDay vNext before writing product UI or porting old content.
This issue is spec-first. It must be possible to implement and test the learning engine from the spec without referencing the legacy runner.
Deliverables
Domain model
Define schemas and invariants for:
- Capability
- Mission
- LanguageComponent
- RetrievalTask
- AssessmentTask
- EvidenceEvent
- LearnerState
- MemoryState
- TransferState
- SessionPlan
- PlannerDecision
Capability contract
Every capability must specify:
- stable id/version;
- learner performance;
- criteria;
- conditions/support;
- prerequisites;
- required language components;
- skill/modality;
- introduction evidence;
- independent evidence;
- delayed evidence;
- transfer evidence;
- assessment task family;
- external mappings only as metadata.
Evidence contract
Append-only, rebuildable, deterministic.
Must distinguish:
- exposure vs attempt;
- recognition vs recall vs production;
- aided vs unaided;
- teaching retry vs independent assessment;
- immediate vs delayed;
- practiced-context vs transfer-context;
- observed evidence vs self-report;
- speech transcript vs pronunciation/intelligibility evidence.
Planner contract
Pure function:
(state, curriculum, now) -> nextAction
Priority policy:
- safe resume;
- overdue/due retrieval;
- unresolved remediation;
- scheduled transfer/checkpoint;
- current mission continuation;
- next prerequisite-satisfied capability.
Tie-breaking must be deterministic.
Session contract
A session is composed from pedagogical needs, not a fixed screen sequence.
Supported phase semantics:
- input;
- notice;
- retrieval;
- output;
- interaction;
- feedback;
- retry;
- review;
- transfer;
- assessment;
- fluency.
A mission may omit phases that are not justified.
Content authoring format
Course-as-code / course-as-data with validation for:
- unknown-language budget;
- prerequisite closure;
- duplicate ids;
- task/evidence coverage;
- transfer coverage;
- assessment alignment;
- unsupported modality claims.
Memory contract
FSRS remains provisional memory engine.
Specify:
- exact task identity;
- revision policy;
- what produces a scheduling rating;
- how aided teaching attempts differ from retrieval evidence;
- why memory state cannot imply proficiency.
Assessment contract
Separate:
- lesson success;
- independent performance;
- delayed retention;
- changed-context transfer;
- proficiency sampling.
No universal pass percentage without calibration.
Legacy decision
Produce an explicit matrix:
- reuse;
- adapt;
- archive;
- delete later.
Do not preserve legacy APIs solely for compatibility.
Test strategy
Before UI:
- deterministic replay;
- planner determinism;
- evidence honesty;
- modality separation;
- support provenance;
- revision safety;
- prerequisite graph;
- transfer distinction;
- scheduler isolation;
- content validation failures.
Required prototype
Create 10–20 example capabilities and at least 2 missions as fixtures only, enough to prove the model can represent:
- greeting/name exchange;
- one listening-first capability;
- one reading capability;
- one short writing capability;
- one changed-context transfer task.
Do not build learner-facing UI yet.
Definition of done
A developer unfamiliar with legacy FlashDay can implement the headless engine from this spec and tests without asking what a “lesson step” from the old app means.
Parent: #39
Goal
Define the complete contracts of FlashDay vNext before writing product UI or porting old content.
This issue is spec-first. It must be possible to implement and test the learning engine from the spec without referencing the legacy runner.
Deliverables
Domain model
Define schemas and invariants for:
Capability contract
Every capability must specify:
Evidence contract
Append-only, rebuildable, deterministic.
Must distinguish:
Planner contract
Pure function:
Priority policy:
Tie-breaking must be deterministic.
Session contract
A session is composed from pedagogical needs, not a fixed screen sequence.
Supported phase semantics:
A mission may omit phases that are not justified.
Content authoring format
Course-as-code / course-as-data with validation for:
Memory contract
FSRS remains provisional memory engine.
Specify:
Assessment contract
Separate:
No universal pass percentage without calibration.
Legacy decision
Produce an explicit matrix:
Do not preserve legacy APIs solely for compatibility.
Test strategy
Before UI:
Required prototype
Create 10–20 example capabilities and at least 2 missions as fixtures only, enough to prove the model can represent:
Do not build learner-facing UI yet.
Definition of done
A developer unfamiliar with legacy FlashDay can implement the headless engine from this spec and tests without asking what a “lesson step” from the old app means.