helico dedicated tables — Phase 1 Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Move response, activity_result, classification, metrics_report the whole written-exam chain (exam_submission, exam_assign_link, exam_correction, criterion_score) the slot trio (slot, slot_scope_ref, lock_dependency), the Caderno Online (notebook_artifact, notebook_annotation, artifact_version) and the two heaviest payloads (session, unit_snapshot) out of the EAV tables (helico_items/helico_itemmeta) into seventeen typed, indexed tables, without changing the public service interfaces or the entity getters their callers use.
Architecture: Each type gets (a) a table in db/install.xml, (b) a small repository over $DB, (c) a hydrator that rebuilds the existing entity class (response, result, classification, report, exam_submission, exam_assign_link, exam_correction, criterion_score, slot, slot_scope_ref, lock_dependency_entity) from a table row so every get_*() caller keeps working, and (d) a one-time, idempotent, batched data migration that copies rows from EAV and skips orphans. Services that extend item_service keep overriding create()/update()/delete()/find() and route them to the repository, so callers that build an item_dto (for example the four AI-correction services that call submission_service->update(new item_dto(...))) keep working unchanged. Raw-SQL listeners that touch these types are rewritten.
Tech Stack: PHP 8.4, Moodle 5.0 XMLDB + $DB, PostgreSQL 17, Middag\Moodle\Support\DbSupport, PHPUnit (advanced_testcase).
Spec: docs/plataforma/adrs/adr-10_persistencia-eav-e-criterios-de-uso.md, docs/plataforma/adrs/ref/ref-10-d_mapa-storage-por-entity.md (note: the REF is stale — it lists 32 types, code has 62). Evidence for the choice of types: dev DB analysis of 2026-10-02 (row/meta counts, orphans, EXPLAIN of whereMeta), summarised in “Evidence” below.
Evidence (dev DB, 2026-10-02, 27 student plans — use proportions, not absolutes)
| Type | items | metas | metas/item | orphans (parent row gone) | parent type |
|---|---|---|---|---|---|
response |
17,202 | 189,222 | 11 | 7,964 (46%) | session |
classification |
3,968 | 43,648 | 11 | 1,338 (34%) | student_plan |
activity_result |
814 | 11,283 | 14 | 217 (27%) | session |
metrics_report |
27 | 133 | 5 | 0 | enrolment |
exam_submission |
8 | 68 | 9 | 0 dangling, 2 with no parent (slot_id ≤ 0) |
slot |
exam_assign_link |
7 | 35 | 5 | 0 | exam_submission |
exam_correction |
3 | 42 | 14 | 0 | exam_submission |
criterion_score |
32 | 312 | 10 | 0 | exam_correction |
slot |
1,765 | 26,656 | 15 | 0 | student_plan (meta student_plan_id = parent in 100%) |
lock_dependency |
2,834 | 8,502 | 3 | 1,237 (44%) — the reset deletes the slot, not its edges | slot |
slot_scope_ref |
0 | 0 | 4 | 0 | slot |
session |
642 | 5,778 | 9 | 0 | slot |
unit_snapshot |
124 | 620 | 5 | 0 | study_plan (product; stays EAV) |
notebook_artifact |
9,371 | 133,299 | 14 | 0 | enrolment (stays EAV) |
artifact_version |
7,133 | 35,665 | 5 | 0 | notebook_artifact |
notebook_annotation |
359 | 1,807 | 5 | 0 | notebook_artifact |
Slot trio: slot is the engine’s hottest lookup (whereMeta('student_plan_id') over 16 k meta rows, 229 ms), carries context up to 157 KB and 15–19 meta rows per slot, and is the parent of session, exam_submission, lock_dependency and slot_scope_ref; 20+ other rows keep its id in a slot_id meta (notebook_artifact 9,371, classification 3,968, activity_result 814, session 642). 102 slots have lock data (lock_reason, lock_unlock_rule, locked).
Heaviest payloads: session.data (moved to its own helico_session_data) is 68 MB (avg 112 KB, max 1.4 MB) with 235 MB of framework revisions (8.4 per session); unit_snapshot.snapshot_data is 15.6 MB (avg 128 KB, max 252 KB), shared per (study plan, unit) and read by 12+ services on polled endpoints.
Caderno Online: the largest per-student set in dev — editor_state_json is 37 MB, rewritten in place on every autosave, and the framework keeps 46,834 revisions (182 MB) of notebook_artifact alone; 579 (enrolment, unit) pairs have more than one artifact (one per topic); description holds the content HTML (5,688 rows, avg 3.7 KB). enrolment (the artifact’s parent) is not migrated: it has 43 rows and no blob.
Written-exam chain: included because it is one dependency chain — criterion_score → exam_correction → exam_submission (→ exam_assign_link), and classification.submission_id points at exam_submission. Dev volume is tiny; the case is structural (1:N criteria per correction, ai_*_json blobs up to 1.7 KB per correction, and a state machine updated by four AI services), not volume.
response.session_idmeta equalsparentin 100% of rows (17,202/17,202).whereMeta('student_plan_id')onhelico_itemmeta: bitmap scan of 16,199 rows bymeta_key, 14,585 discarded by the unindexed TEXTmeta_valuefilter, ~229 ms, 4,875 blocks read.- Orphans come from
enrolment_reset_listener_service::cascade_delete_items(), which deletes sessions/student plans but not theirresponse/classificationchildren. metrics_report.descriptionholds the JSON payload (avg 5 KB, max 15.7 KB);idnumber=report:{enrolment}:{scope}:{target|all}is its idempotency key.
Framework tooling analysis (what middag-php-* already provides)
Checked in /var/www/middag-php-libs (core, framework, moodle, dev-tools) and in how local_middag uses it:
| Need | Existing piece | Used here? |
|---|---|---|
| Declare a table | #[Table], #[Column] (name,type,length,notnull,sequence,default,comment,decimals), #[Key], #[Index] attributes (Middag\Framework\Database\Attribute), read by SchemaBuilder::registerClass()/loadFromClasses() |
Yes — Task 2 declares the 8 tables as descriptor classes |
Generate install.xml |
middag-dev-tools build:schema --format=xmldb --source-dir=... --output=... (SchemaGenerator + SchemaDescriptorValidator; --previous-snapshot blocks destructive changes) |
Yes, to a scratch file, then merged (the tool rewrites the whole file and cannot emit the helico_ prefix for the 4 EAV tables) |
| Create tables / add columns on upgrade | Middag\Framework\Database\Schema\MigrationRunner (install(), upgrade(); concrete MysqlMigrationRunner) + Middag\Moodle\Database\Schema\XmldbSchemaAdapter (maps to xmldb_table/xmldb_field/xmldb_index) + Middag\Moodle\Persistence\VersionTracker |
Yes — Task 2 Step 6 |
| Versioned schema/data migrations | Middag\Core\Persistence\Migration\Contract\MigrationInterface (version(), up($schema, $data)) + MigrationExecutor::apply($migrations, $fromVersion) + Middag\Core\Adapter\Moodle\Persistence\MoodleDataOperations |
Yes — Task 4 wraps the data copy as one MigrationInterface |
| Idempotent upgrade-step gate | Middag\Moodle\Persistence\UpgradeHelper::stepCompleted()/stepComplete() |
Not needed: the migrator is idempotent and upgrade_plugin_savepoint gates by version |
| Core table set with a prefix | PersistenceManifest::withPrefix('helico'), CoreSchema, MigrationOrchestrator |
No — they only cover the fixed core tables (CoreTables); a consumer cannot add its own table ids to a manifest. local_helico already uses it implicitly for helico_items/itemmeta/revisions via PersistenceScope::withPrefix('helico') |
| Table-aware reads | MiddagItemQueryBuilder::from($table, null) (non-EAV) + AbstractItemQueryRepository |
No — a repository over $DB is simpler and keeps item_dto overrides trivial; from() is the fallback if a query ever needs the builder |
Limits that shaped the plan: DataOperationsInterface only exposes execute(string $sql, array $params): void — there is no read or batch API — so the EAV→table copy stays a PHP routine (item_table_migrator), wrapped in a MigrationInterface for versioning. A set-based INSERT … SELECT pivot would be faster but aborts the whole statement on a single bad cast, and the upgrade runs at container boot with set -e. #[Column] has no LENGTH="big" for text (PostgreSQL text is unbounded, matching the core’s own tables). MigrationRunner::upgrade() creates missing tables with their indexes and adds missing columns, but does not add indexes to an existing table.
Registration and query-builder analysis (verified in dev on 2026-10-02)
Question: can the framework’s MiddagItemQueryBuilder handle the new tables now that they have no itemmeta (and no type, parent, …), and where must a table be registered? Checked by reading middag-php-core (buildSql, Executor, the AST classes) and by running ~60 builder calls against temporary PostgreSQL tables in the dev container (they vanish with the connection; the probe scripts are not part of the plan). The probe tables mimicked the real ones, including column names such as level, source, scope, context, result, action, name, label, kind, status, color.
What works on MiddagItemQueryBuilder::make()->from('helico_x') with any real column of the table
| Feature | Result |
|---|---|
where('<column>', Operator::…) — every column name above, including level, scope, context, result, action |
Works. The field must be a bare identifier or alias.column; anything else (id = 1 OR 1, slotid) OR (1=1) is refused with CorePersistenceException |
Eq, Neq, Gt, Gte, Lt, Lte, Like, In, NotIn, Between (whereIn/whereNotIn/whereBetween), Is, IsNot |
Work, including on numeric columns. In [] returns no rows; NotIn [] returns all |
OR/AND groups: whereNode(new Logical(LogicalOperator::Or, [new Comparison('col', ComparisonOperator::Equals, [Parameter::int(12)]), …])), plus In, StartsWith, Contains, IsNull nodes |
Work, ANDed with the plain where() conditions. Values must be Parameter objects and column names lowercase [a-z][a-z0-9_]* (ours are) |
Joins between two dedicated tables: joinNode(new Join(JoinType::Inner|Left, 'helico_pb', 'b', new ColumnComparison(new ColumnRef('slotid'), ComparisonOperator::Equals, new ColumnRef('id', 'b')))), then where('b.col', …) and orderBy('b.col ASC, item.id DESC') |
Work. A node Comparison always targets the main table: filter on the joined table with the dotted where('b.col', …) |
Projection select(['id', 'slotid', …]) |
Works — rows carry only those columns (this is how a list can skip a large column) |
orderBy('col DIR, …'), limit(n), paginate(page, perPage) |
Work. paginate is 0-based. The Result exposes items(), first(), isEmpty(), total(), pages(), page(); total() is a correct COUNT(DISTINCT item.id), also over a join |
asStdClass() |
Rows are stdClass with every column as a string (or NULL) plus an empty metadata array — the same shape $DB returns |
What does not work, or bites
| Feature | Result |
|---|---|
Hydration into the entity: ->domain(response::class) or ->entity(response::class) |
Does not work. The executor always hydrates through ItemMapper::dbToDomain, which only maps item columns, so the result is a generic Middag\Core\Domain\Item\Item (type='generic') with none of the table’s columns, whatever class is passed |
whereMeta(...) |
Silent empty result (0 rows, no exception) — a wrong answer that looks like “no data” |
withMetadata([...]) |
Loud error (no meta_table configured) |
where('type', …) |
Loud error: the table has no type column (the error is about the column, not about the builder; any other real column works) |
where('col', Operator::Eq, null) |
Silent empty result (col = NULL matches nothing); use Operator::Is |
select([...]) and orderBy('…') |
Not validated: select(['id, (SELECT 1) AS x']) and orderBy('id DESC, (SELECT 1)') were accepted verbatim. Safe with constants, an injection vector with user input. (where() fields are validated.) |
| A column that does not exist | A raw dml_read_exception from the database |
Consequences for the plan:
- The repositories stay on
$DBplustable_row_hydrator. That is what makesresponse,slot,session… come back as their real classes; the builder cannot do it, and the core’s own non-EAV base (Adapter\Moodle\Persistence\AbstractTableRepository) needs a dedicatedAbstractMapperper table, a larger change than this plan needs. - Reads go through
entity()(route C, chosen 2026-10-02).MiddagItemQueryBuilder::make()->entity(response::class)->where('sessionid', …)is bound to the table through the coreTableRegistry, andtyped_query::execute()(Task 3 Step 7b) runs it and returns the real entity class: the executor keeps the SQL, scope, paging and total, and only the hydration is replaced by thetable_row_hydratormapper registered for the class — the missing link thatItemMapperfills forItemrows through thetypecolumn. It also validates what the builder does not (whereMeta/withMetadata,= NULL, unknown columns, rawselect()/orderBy(), and a bound class queried withoutentity()). The repositories (writes and the fixed finders) use the same hydrator, so both paths return identical entities. - The danger is not the new tables, it is the old code paths. A leftover
->where('type', Operator::Eq, slot::TYPE)->domain(slot::class)does not fail after the switch: it keeps readinghelico_items, where the pre-migration rows stay until the cleanup release, so it returns stale data. Task 15 Step 6b adds a regression test that fails the build if any class still queries a migrated type through the EAV. - Projection is a cheaper alternative to a
*_dataside table for large columns that lists do not need (unit_snapshot.snapshotdata,notebook_artifact.editorstatejson,exam_submission.ailastresponsejson):typed_query::execute(MiddagItemQueryBuilder::make()->entity(unit_snapshot::class)->select([…every column but snapshotdata…]))lists the rows without reading the blob, and the hydrator leaves the key absent so an entity can load it on demand.session_datais kept as decided; this note is for the next columns.
| Registry | What it does | Decision |
|---|---|---|
ItemTypes::register(type, class) (#[ItemType]) |
maps a type string to the entity class for ItemMapper |
Unchanged. The entity classes keep their registration; item_service->find($id) still resolves them, but from the stale EAV rows, hence the Task 15 audit and guard |
TableRegistry::register(new TableDescriptor(class, table, null)) + ->entity(class) |
binds a query to a table (entity() is a core builder method; unregistered classes silently fall back to helico_items) |
Used. table_bindings::register_all() registers the 16 entities, called from platform_extension::boot() (always enabled, so it always boots); typed_query supplies the hydration. A test asserts every entity is registered and that entity() targets its table |
TypeLoader (core) |
scans the plugin’s Item subclasses at boot into ItemTypes (#[ItemType] or TYPE) |
Unchanged. It has no table attribute, so table registration stays explicit in table_bindings (a future core attribute such as #[ItemTable('helico_response')] would remove the manual list) |
PersistenceScope::withPrefix('helico') (platform_extension.php) |
routes the four EAV tables | Unchanged — dedicated tables are not part of a scope |
AstTableScope / FeatureAstAllowlist |
which tables and columns a stored query document may name | Not needed: only for document-driven features (segments, workflows) whose queries come from JSON; helico builds its queries in code |
db/install.xml + #[Table] descriptors + MysqlMigrationRunner |
creates the tables | Task 2 |
Generated entity regions (BEGIN AUTO-GENERATED in 25 files) |
build:extensions rewrites them |
The only entity edited is session.php, which has no generated region (checked); any future override must go inside a BEGIN MANUAL block |
Moodle privacy provider (classes/privacy/provider.php) |
declares tables holding user data | Gap, outside this plan: local_helico has no privacy provider today (no core_privacy reference in the plugin), including for helico_items.userid. The new tables hold user ids (session.userid, notebook_artifact.userid, notebook_annotation.userid, artifact_version.createdby, classification.userid, exam_submission.userid/correctedby, exam_correction.tutorid/studentuserid, exam_assign_link.studentuserid); a provider that declares and exports/deletes them is a separate task |
What the core item stack did on write, and what replaces it for the dedicated tables
The core cannot manage these tables, and does not need to: ItemService/ItemRepository/ItemQueryRepository are written for items + itemmeta (metadata joins, loadMetadataBulk, meta inserts). The read side already works without them (the probes ran the builder’s SQL on the main table only, with the meta table null). The write side is replaced by the repositories ($DB with column arrays from columns_from_dto). Read in middag-php-core:
What ItemService::create/update/delete did |
Needed for these tables? | Now |
|---|---|---|
Insert/update/delete the row and its itemmeta rows, resolve guid, usermodified, scope columns |
No | Repository insert/update/delete on one table; timecreated/timemodified set by the repository |
ItemValidatorService: type ≤ 100, status ≤ 50, guid ≤ 36, idnumber ≤ 191, version ≤ 50, visible ∈ {0,1}, metadata keys ≤ 191 |
No (those columns do not exist) | The column definitions enforce lengths and a too-long value now fails as a database error instead of a CoreValidationException. Checked on the dev data: none of the 35 char columns overflows (max/limit: content_hash 64/64 and uuid 36/36 fit exactly; the next is slot_type 25/50) |
Existence and type mismatch check on update |
No | Repository update on a missing id is a no-op for the row (callers already fetch first) |
assignVisibleNumber (item numbering) |
No | None of the 16 types is registered for numbering |
Audit (auditService->itemCreated/Updated/Deleted) |
Already off | PersistenceScope::withPrefix('helico')->withoutAudit() — nothing lost |
Revision (item_revision + item_revision_meta) |
Dropped on purpose | 553 MB in dev. The loss is real for history that had value: exam_correction (a re-recorded correction overwrites the previous one), exam_submission state changes and notebook_artifact edits. notebook_artifact_version keeps its own history |
ItemSignal → hooks middag/item/{action} and middag/item/{action}/{type} |
No listener found | No class in local_middag or local_helico subscribes to middag/item/* or aggregate: 'item'. The domain signals the services raise themselves (slot_completed_signal, exam_corrected_signal, activity_completed, snapshot_*) are unchanged. A third-party plugin hooking middag/item/created/slot would stop firing |
CachedItemRepository by id |
No | Not used by the new repositories |
Item base columns the new tables do not keep: guid, usermodified, visible, sortorder, descriptionformat have no consumer on helico classes (getGuid(), getUsermodified(), getVisible(), getSortorder(), getDescriptionformat() appear 0 times). fullname, idnumber, version, shortname and usercreated do have call sites (38, 36, 17, 6 and 1) that cannot be attributed to a type by a grep, so Task 15 Step 6c audits them. core’s own non-EAV base (Adapter\Moodle\Persistence\AbstractTableRepository) writes whole entities through a mapper’s domainToDb, which does not fit the partial item_dto updates the services and the four AI services make; the repositories keep column arrays.
Global Constraints
- Table names: prefix
helico_, max 28 chars (Moodle XMLDB limit). Column names lowercase, no underscores (Moodle convention): meta keysession_id→ columnsessionid. - Plugin version: current
2026092801(version.php); this plan ships2026100201. Schema step =2026100200, data step =2026100201. - Entity classes and their public
get_*()signatures must not change. - Service interfaces (
response_service_interface,result_service_interface,classification_service_interface,report_service_interface,exam_submission_service_interface,exam_assign_link_service_interface,exam_correction_service_interface) must not change. - Services that extend
item_service(result_service,report_service,exam_submission_service,exam_assign_link_service,exam_correction_service,slot_lock_service,slot_scope_service,notebook_artifact_service,notebook_annotation_service,artifact_versioning_service) must overridecreate(ItemDtoInterface): ItemInterface,update(ItemDtoInterface): ItemInterface,delete(int): voidandfind(int): ?ItemInterface(the exact signatures ofMiddag\Core\Domain\Item\ItemService) and route them to their repository.item_dtoexposes publicid, type, userid, parent, description, status, sortorder, metadata. - Table structure is declared only in the
#[Table]descriptor classes (classes/base/persistence/schema/*_table.php);db/install.xmlblocks for them are generated bybuild:schema:dedicated, never hand-edited.schema_testfails if the two drift. - Entities of migrated types are read and written only through their repository. Never
MiddagItemQueryBuilderwith->domain()/->entity()/->whereMeta()/->withMetadata()(a builder over a migrated entity is built with->entity()and run withtyped_query::execute()), neveritem_service->find()for them, neverhelico_items/helico_itemmetain raw SQL (the migrator andsession_data_copierare the only exceptions). Task 15 Step 6b enforces the first and third. - Every repository
insert()/update()validates the columns withtable_row_validator::assert()(Task 3b) before the$DBwrite; invalid input is aninvalid_row_exception, never a database error. Enum-restricted columns are annotated only after Task 16 Step 3b shows the dev values fit. - Column names:
max→maxscore,comment→commenttext(Moodle quotes reserved words in DDL, but raw SQL does not). - Row ids are preserved from
helico_items.id; after import the sequence is reset. - Orphans (parent row missing in
helico_items) are not migrated and are left in the EAV tables (cleanup is a later release). - No
Co-Authored-Bytrailer in commits (repo CLAUDE.md overrides session attribution). Conventional Commits. - Do not run
npm run build, do not touchtool-middagctl, usemaketargets (not rawdocker compose). - PHPCS Moodle style for plugin code;
declare(strict_types=1); file header as in existing files.
Review Focus
- Boot-time upgrade —
docker-entrypoint.shrunsupgrade.phpat every boot withset -e(root CLAUDE.md gotcha 5). A slow or failing migration kills the container. The migrator must be batched, resumable and must never throw on a bad row (count and continue). Pinned in Task 4. - Second run of the migration — running the data step twice (or after partial failure) must not duplicate or error. Pinned in Task 4.
- Sequence after explicit-id import — first insert after migration must get
id > max(imported id). Pinned in Task 4. - NULL vs 0 round trip —
question_id/card_id/scope_target_id/invalidated_atare nullable and callers distinguish null from 0 (report_servicecomment oninvalidated_at). Pinned in Tasks 3, 5, 8. - Reset cascade leaving orphans — after this plan, resetting an enrolment must delete the new-table children too, otherwise the 46% orphan problem moves to the new tables. Pinned in Task 15.
- Re-recording a correction —
exam_correction_service::record()deletes all criteria and re-inserts them; if the insert fails midway the correction is left with no criteria. Must be one DB transaction. Pinned in Task 10. - Partial
item_dtoupdates from the AI services — they callupdate(new item_dto(id: ..., metadata: [...]))with only the fields that changed;item_dto::$statusdefaults to'draft', which must not overwritecorrectionstatus, and omitted metadata keys must not be nulled. Pinned in Tasks 3 and 9. exam_submissionwithout a slot — 2 of 8 dev rows have no parent (slot_id≤ 0,parent = NULL); the migrator must copy them, not treat them as orphans. Pinned in Tasks 4 and 9.- Slot lock keys the old query never loaded —
slot_lock_service::read_lockreadslock_reason/lock_message/lock_unlock_rule/lock_unlock_atwithgetMeta(), butslot::METADATA_FIELDSomits them, sowithMetadata()never loaded them (102 dev slots have values). The new hydrator exposes them.read_lockhas no callers outside its interface today (grep -rn "read_lock(" classes), so nothing changes at runtime, but the first caller will see real values. Pinned in Task 11. - Lock edges and scope refs of a deleted slot — the reset deletes slots but never their
lock_dependencychildren (44% of dev edges are orphans) nor the edges pointing at them.slot_lock_repository::delete_by_slot_idsremoves both directions. Pinned in Tasks 11 and 15. - Silent writes to EAV from
parent::update—notebook_artifact_service::promote_to_notebookandpublish(andslot_lock_service::write_lock,exam_submission_service::mark_*) callparent::update(new item_dto(...))directly. Onceupdate()is overridden,parent::updatewould still write the old EAV tables and the new table would never change. Each such call must become$this->update(...). Pinned in Tasks 9, 11 and 12 (grep -rn "parent::update\|parent::create" classes/extensions/must list no migrated service at the end). unit_snapshot_servicestill needs the EAV item service — besides persisting snapshots it callsitem_service->find($unit_id)for the liveunit(is_consistent,live_audio_relations,persist_snapshot), andunit/unit_contentstay EAV. Only the snapshot persistence is swapped; the constructor keepsItemServiceInterface. Pinned in Task 14.- Session payload split —
helico_sessionhas nodatacolumn;session::getMeta('data')/get_data()load it lazily fromhelico_session_data, so a caller can never get a silentnull. The cost is one extra indexed query per session whose data is read from a list (about 14 call sites readget_data()); a status/time update never rewrites the payload row.session_data_copiermust run after the sessions are migrated. Pinned in Tasks 4 and 13. - The executor cannot hydrate the new tables on its own, and a stale EAV read does not fail — verified in dev:
->domain()/->entity()onfrom(table)return a genericItemwithout the table’s columns;whereMetaandwhere(col, Eq, null)return an empty result instead of an error. A leftover EAV-style query for a migrated type keeps reading the stale pre-migration rows. Pinned bytyped_query(Task 3 Step 7b: refuses a bound class queried withoutentity()) and by the guard test in Task 15 Step 6b. - No privacy provider —
local_helicodeclares no personal-data tables today and the new tables add more user-id columns. Not fixed by this plan; tracked in “Registration and query-builder analysis”. - Invalid column values reach the database — a status outside its enum, an over-long
char, anullin a NOT NULL column. Pinned bytable_row_validator_test(Task 3b), a rejection test insession_repository_test(Task 13) and the guard test in Task 15 Step 6d. select()andorderBy()are not validated by the builder (verified:select(['id, (SELECT 1) AS x'])andorderBy('id DESC, (SELECT 1)')run verbatim);typed_query::execute()is the only supported way to run a query on the new tables because it checks columns, sort and projection against the descriptor. Pinned in Task 3 Step 7b.- History and generic events are not carried over — revisions are dropped on purpose and
ItemSignalis no longer emitted for the 16 types; nothing inlocal_middag/local_helicoconsumes either, butexam_correctionloses its previous versions and a third-partymiddag/item/*hook stops firing. Decide whetherexam_correctionneeds its own history table. Documented in “What the core item stack did on write”. - Item columns the tables do not keep —
getFullname(),getIdnumber(),getVersion(),getShortname(),getUsercreated()have 38, 36, 17, 6 and 1 call sites that cannot be attributed to a type by grep. The hydrator fillsfullnameonly forslot(itslabel). Pinned in Task 15 Step 6c.
File Structure
| File | Responsibility |
|---|---|
classes/base/persistence/schema/*_table.php (create, 17 files) |
#[Table] descriptors — the single source of truth for the 17 tables |
classes/base/persistence/table_bindings.php, classes/base/persistence/typed_query.php (create) |
Entity class → table definition; entity() queries that return the real entity class and are validated |
classes/extensions/platform/platform_extension.php (modify) |
boot() calls table_bindings::register_all() |
classes/base/persistence/dedicated_schema.php (create) |
Lists the descriptor classes; builds the framework SchemaBuilder |
classes/base/persistence/migration/migration_2026100201_eav_to_tables.php (create) |
MigrationInterface wrapper around the data copy |
db/install.xml (modify) |
Receives the 17 generated <TABLE> blocks (merged, not hand-written) |
composer.json (modify) |
Script build:schema:dedicated |
db/upgrade.php (modify) |
Step 2026100200 = framework MysqlMigrationRunner creates tables; step 2026100201 = MigrationExecutor runs the data migration |
version.php (modify) |
Bump to 2026100201 |
classes/base/persistence/table_row_hydrator.php (create) |
Row → existing entity instance |
classes/base/persistence/{table_row_validator,invalid_row_exception}.php, classes/base/persistence/attribute/allowed_values.php (create) |
Descriptor-driven row validation before every write (Task 3b) |
classes/base/persistence/item_table_definition.php (create) |
Immutable description of one type→table mapping |
classes/base/persistence/item_table_migrator.php (create) |
Generic batched, idempotent EAV→table copy |
classes/base/persistence/item_table_definitions.php (create) |
The 4 concrete definitions (single source for migrator and repositories) |
classes/extensions/activity/response/repository/response_repository.php (create) |
Table access for helico_response |
classes/extensions/activity/result/repository/result_repository.php (create) |
Table access for helico_result |
classes/extensions/metrics/classification/repository/classification_repository.php (create) |
Table access for helico_classification |
classes/extensions/metrics/report/repository/report_repository.php (create) |
Table access for helico_metrics_report |
classes/extensions/activity/assessment/exam_submission/repository/exam_submission_repository.php (create) |
Table access for helico_exam_submission |
classes/extensions/activity/assessment/exam_assign_sync/repository/exam_assign_link_repository.php (create) |
Table access for helico_exam_assign_link |
classes/extensions/activity/assessment/exam_correction/repository/exam_correction_repository.php (create) |
Table access for helico_exam_correction |
classes/extensions/activity/assessment/exam_correction/repository/criterion_score_repository.php (create) |
Table access for helico_criterion_score |
classes/extensions/engine/algorithm/repository/{slot,slot_scope_ref,slot_lock}_repository.php (create) |
Table access for helico_slot, helico_slot_scope_ref, helico_slot_lock |
classes/extensions/activity/productive/{notebook_artifact,notebook_annotation,artifact_versioning}/repository/*_repository.php (create, 3 files) |
Table access for the three notebook tables |
classes/extensions/engine/session/repository/{session,session_data}_repository.php, classes/extensions/engine/plan/repository/unit_snapshot_repository.php (create) |
Table access for helico_session, helico_session_data and helico_unit_snapshot |
classes/extensions/engine/session/entity/session.php (modify) |
Lazy getMeta('data')/hasMeta('data') from helico_session_data |
classes/base/persistence/migration/session_data_copier.php (create) |
Set-based copy of the EAV data meta into helico_session_data |
the 4 *_service.php (modify) |
Swap persistence calls to repositories |
classes/extensions/admin/listener/enrolment_reset_listener_service.php (modify) |
Cascade delete includes new tables |
classes/extensions/admin/service/dev_lifecycle_inspector_service.php (modify) |
Reads the 4 types from tables |
cli/migrate_items_to_tables.php (create) |
Manual run + --dry-run of the migrator |
tests/base/persistence/*_test.php, tests/extensions/**/…_test.php (create) |
Tests per task |
docs/plataforma/adrs/adr-10_…md, ref-10-d_…md (modify) |
Record the real state |
Phases (scope check)
This plan = foundation + 17 tables: the 4 activity/metrics tables, the written-exam chain (exam_submission, exam_assign_link, exam_correction, criterion_score), the slot trio (slot, slot_scope_ref, slot_lock) the Caderno Online (notebook_artifact, notebook_annotation, notebook_version) and the two heaviest payloads (session with its payload split into session_data, and unit_snapshot). The remaining tables are independent subsystems and get their own plans, each reusing the Task 3/4 tooling built here:
- Plan 4 (optional):
helico_student_plan,helico_study_flow,helico_study_block,helico_cda_block.
The parents outside this plan (classification.studentplanid and slot.studentplanid → student_plan, unit_snapshot.studyplanid → study_plan, notebook_artifact.enrolmentid → enrolment) stay EAV here. The migrator’s orphan check therefore still looks them up in helico_items (for slot and session rows too: the pre-migration EAV rows remain until the cleanup release); Plan 4 generalises it. The only plan left is Plan 4 (student_plan and its hierarchy, optional); its column specs are in the Appendix.
Task 1: Establish a working Moodle PHPUnit baseline
Files:
- Modify: none (discovery task; record result in
docs/superpowers/plans/2026-10-02-helico-dedicated-tables-phase1.mdunder “Test command” below)
Interfaces:
- Produces: the exact command that runs
tests/**/*_test.phpforlocal_helico, used by every later task as<TEST_CMD>.
Why this is a task: moodle/phpunit.xml and moodle/vendor/bin/phpunit do not exist in the dev checkout today, so the way to run plugin tests is unverified.
- Step 1: Find the project’s test entry points
Run: cd /var/www/docker-moodle-helico && make help | grep -iE "test|phpunit"
Expected: a list of targets. If make test runs only MoodleDocker unit tests (root tests/), it does not cover the plugin.
- Step 2: Check whether Moodle’s PHPUnit is initialised in the container
Run: cd /var/www/docker-moodle-helico && make shell then inside: ls /var/www/html/moodle/vendor/bin/phpunit /var/www/html/moodle/phpunit.xml; grep -n phpunit_ /var/www/html/moodle/config.php
Expected: either the files exist (go to Step 4) or they do not (Step 3).
- Step 3: If missing, add the PHPUnit settings and initialise
Add to config.example.php-derived config.php (gitignored) a separate test prefix and dataroot so tests never touch the dev data:
$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/var/www/html/phpunit_moodledata';Run inside the container: cd /var/www/html/moodle && composer install --dev && php admin/tool/phpunit/cli/init.php
Expected: “Moodle PHPUnit environment is ready”.
- Step 4: Run one existing test to prove the plugin suite works
Run inside the container: cd /var/www/html/moodle && vendor/bin/phpunit --testsuite local_helico_testsuite --filter activity_dto_test
Expected: PASS. Write this command into the “Test command” line at the end of this file as <TEST_CMD> (replace --filter ... per task).
- Step 5: Commit
git add docs/superpowers/plans/2026-10-02-helico-dedicated-tables-phase1.md
git commit -m "docs(plan): record plugin phpunit command"Task 2: Schema — seventeen tables as framework descriptors, generated install.xml, framework runner upgrade
The framework already owns table creation (see “Framework tooling analysis” above), so tables are declared once as #[Table] descriptor classes; install.xml is generated from them and the upgrade step is the framework’s MysqlMigrationRunner with the Moodle XmldbSchemaAdapter. No hand-typed XML.
Files:
- Create:
classes/base/persistence/schema/response_table.php,result_table.php,classification_table.php,metrics_report_table.php,exam_submission_table.php,exam_assign_link_table.php,exam_correction_table.php,criterion_score_table.php,slot_table.php,slot_scope_ref_table.php,slot_lock_table.php,notebook_artifact_table.php,notebook_annotation_table.php,notebook_version_table.php,slot_table.php,slot_scope_ref_table.php,slot_lock_table.php - Create:
classes/base/persistence/dedicated_schema.php - Modify:
db/install.xml(merge the generated<TABLE>blocks),db/upgrade.php,version.php:18,composer.json(scriptbuild:schema:dedicated) - Test:
tests/base/persistence/schema_test.php
Interfaces:
- Produces:
local_helico\base\persistence\dedicated_schema::classes(): list<class-string>(the 8 descriptor classes),::builder(): \Middag\Framework\Database\Schema\SchemaBuilder,::table_names(): list<string>. - Produces: tables
helico_response,helico_result,helico_classification,helico_metrics_report,helico_exam_submission,helico_exam_assign_link,helico_exam_correction,helico_criterion_scoreandhelico_slot,helico_slot_scope_ref,helico_slot_lock, with exactly the columns below. Later tasks read/write these names.
Descriptor limits to respect (verified in middag-php-framework): #[Column] takes name, type, length, notnull, sequence, default, comment, decimals; there is no LENGTH="big" for text (the core’s own tables use plain text; on PostgreSQL, the only engine of this stack, text is unbounded); XmldbSchemaAdapter maps int|char|text|float|number|binary; upgrade() creates missing tables (with indexes) and adds missing columns, but does not add indexes to tables that already exist.
- Step 1: Write the failing schema test (data-driven from the descriptors)
<?php
declare(strict_types=1);
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use Middag\Framework\Database\Schema\MysqlMigrationRunner;
use Middag\Moodle\Database\Schema\XmldbSchemaAdapter;
use Middag\Moodle\Persistence\VersionTracker;
use PHPUnit\Framework\Attributes\Group;
use xmldb_field;
use xmldb_index;
use xmldb_table;
#[Group('local_helico')]
final class schema_test extends advanced_testcase
{
public function test_there_are_seventeen_dedicated_tables(): void
{
$this->assertSame(
['helico_response', 'helico_result', 'helico_classification', 'helico_metrics_report', 'helico_exam_submission', 'helico_exam_assign_link', 'helico_exam_correction', 'helico_criterion_score', 'helico_slot', 'helico_slot_scope_ref', 'helico_slot_lock', 'helico_notebook_artifact', 'helico_notebook_annotation', 'helico_notebook_version', 'helico_session', 'helico_session_data', 'helico_unit_snapshot'],
dedicated_schema::table_names(),
);
}
public static function table_provider(): array
{
$cases = [];
foreach (dedicated_schema::builder()->all() as $name => $descriptor) {
$cases[$name] = [$name];
}
return $cases;
}
/**
* install.xml and the descriptors must not drift: every descriptor column and
* index has to exist in the database that install.xml created.
*
* @dataProvider table_provider
*/
public function test_install_xml_matches_descriptor(string $table): void
{
global $DB;
$dbman = $DB->get_manager();
$descriptor = dedicated_schema::builder()->table($table);
$this->assertTrue($dbman->table_exists($table), "$table missing from install.xml");
foreach ($descriptor['columns'] as $column) {
$this->assertTrue(
$dbman->field_exists(new xmldb_table($table), new xmldb_field($column['name'])),
"$table.{$column['name']} missing",
);
}
foreach ($descriptor['indexes'] ?? [] as $index) {
$this->assertTrue(
$dbman->index_exists(new xmldb_table($table), new xmldb_index('chk', ($index['unique'] ?? false) ? XMLDB_INDEX_UNIQUE : XMLDB_INDEX_NOTUNIQUE, $index['fields'])),
"$table index (" . implode(',', $index['fields']) . ') missing',
);
}
}
public function test_framework_runner_upgrade_is_idempotent_on_installed_tables(): void
{
global $DB;
$runner = new MysqlMigrationRunner(
dedicated_schema::builder(),
new XmldbSchemaAdapter($DB->get_manager()),
new VersionTracker('local_helico', 'schema_dedicated_version'),
);
$runner->upgrade(0);
$runner->upgrade(0);
foreach (dedicated_schema::table_names() as $table) {
$this->assertTrue($DB->get_manager()->table_exists($table));
}
}
}- Step 2: Run it to verify it fails
Run: <TEST_CMD> --filter schema_test
Expected: FAIL (Class ...\dedicated_schema not found).
- Step 3: Create the seventeen descriptor classes
Each file starts with the standard file header, declare(strict_types=1);, namespace local_helico\base\persistence\schema;, defined('MOODLE_INTERNAL') || exit;, and imports Middag\Framework\Database\Attribute\Column, Index, Key, Table. Shown here without the header.
response_table.php:
#[Table('helico_response', comment: 'HELICO - Student answer inside a session (append-only)')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('sessionid', 'int', length: 10, notnull: true, comment: 'helico_items id of the session')]
#[Column('questionid', 'int', length: 10, notnull: false, comment: 'Mutually exclusive with cardid')]
#[Column('cardid', 'int', length: 10, notnull: false)]
#[Column('unitid', 'int', length: 10, notnull: false)]
#[Column('courseid', 'int', length: 10, notnull: false)]
#[Column('answer', 'text', notnull: false)]
#[Column('correct', 'int', length: 1, notnull: true, default: 0)]
#[Column('notsure', 'int', length: 1, notnull: true, default: 0)]
#[Column('timems', 'int', length: 10, notnull: false)]
#[Column('sortorder', 'int', length: 10, notnull: true, default: 0)]
#[Column('category', 'char', length: 100, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('sessionid', ['sessionid'])]
#[Index('unitid', ['unitid'])]
final class response_table {}result_table.php:
#[Table('helico_result', comment: 'HELICO - Computed activity result (one per session)')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('sessionid', 'int', length: 10, notnull: true)]
#[Column('slotid', 'int', length: 10, notnull: false)]
#[Column('studentplanid', 'int', length: 10, notnull: false)]
#[Column('enrolmentid', 'int', length: 10, notnull: false)]
#[Column('unitid', 'int', length: 10, notnull: false)]
#[Column('slottype', 'char', length: 50, notnull: false)]
#[Column('completionstatus', 'char', length: 30, notnull: true, default: 'completed')]
#[Column('completedat', 'int', length: 10, notnull: false)]
#[Column('notareal', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('notabruta', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('notaajustada', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('bonusrelevancia', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('totalquestions', 'int', length: 10, notnull: false)]
#[Column('correctcount', 'int', length: 10, notnull: false)]
#[Column('incorrectcount', 'int', length: 10, notnull: false)]
#[Column('unansweredcount', 'int', length: 10, notnull: false)]
#[Column('timetotalms', 'int', length: 10, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('sessionid', ['sessionid'])]
#[Index('slotid', ['slotid'])]
#[Index('enrolmentid', ['enrolmentid'])]
#[Index('planunit', ['studentplanid', 'unitid'])]
final class result_table {}classification_table.php:
#[Table('helico_classification', comment: 'HELICO - Level classification per student plan and unit (accumulative)')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('studentplanid', 'int', length: 10, notnull: true)]
#[Column('userid', 'int', length: 10, notnull: false)]
#[Column('courseid', 'int', length: 10, notnull: false)]
#[Column('unitid', 'int', length: 10, notnull: false)]
#[Column('level', 'char', length: 30, notnull: true, default: '')]
#[Column('source', 'char', length: 50, notnull: false)]
#[Column('score', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('slotid', 'int', length: 10, notnull: false)]
#[Column('submissionid', 'int', length: 10, notnull: false)]
#[Column('correctcount', 'int', length: 10, notnull: false)]
#[Column('totalcount', 'int', length: 10, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('planunit', ['studentplanid', 'unitid'])]
#[Index('userid', ['userid'])]
#[Index('slotid', ['slotid'])]
#[Index('submissionid', ['submissionid'])]
final class classification_table {}metrics_report_table.php:
#[Table('helico_metrics_report', comment: 'HELICO - Cached performance report per enrolment and scope')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('enrolmentid', 'int', length: 10, notnull: true)]
#[Column('studentplanid', 'int', length: 10, notnull: false)]
#[Column('scope', 'char', length: 30, notnull: true, default: 'overall')]
#[Column('scopetargetid', 'int', length: 10, notnull: false)]
#[Column('status', 'char', length: 20, notnull: true, default: 'fresh')]
#[Column('idnumber', 'char', length: 191, notnull: true, comment: 'report:{enrolment}:{scope}:{target|all}')]
#[Column('dimensiondata', 'text', notnull: false, comment: 'Opaque JSON cache, recomputable')]
#[Column('generatedat', 'int', length: 10, notnull: false)]
#[Column('invalidatedat', 'int', length: 10, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('idnumber', ['idnumber'], unique: true)]
#[Index('enrolmentid', ['enrolmentid'])]
#[Index('studentplanid', ['studentplanid'])]
final class metrics_report_table {}exam_submission_table.php:
#[Table('helico_exam_submission', comment: 'HELICO - Written exam answer submitted by a student for one question')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('slotid', 'int', length: 10, notnull: false, comment: 'helico_items id of the slot; NULL when the legacy row had slot_id <= 0')]
#[Column('questionid', 'int', length: 10, notnull: false)]
#[Column('unitid', 'int', length: 10, notnull: false)]
#[Column('sessionid', 'int', length: 10, notnull: false)]
#[Column('studentplanid', 'int', length: 10, notnull: false)]
#[Column('userid', 'int', length: 10, notnull: false, comment: 'The student')]
#[Column('submittedtext', 'text', notnull: false)]
#[Column('submittedat', 'int', length: 10, notnull: false)]
#[Column('correctionstatus', 'char', length: 30, notnull: true, default: 'pending')]
#[Column('correctedby', 'int', length: 10, notnull: false)]
#[Column('correctedat', 'int', length: 10, notnull: false)]
#[Column('aiattempt', 'int', length: 10, notnull: false)]
#[Column('aiexternalid', 'char', length: 255, notnull: false)]
#[Column('aistatuspath', 'text', notnull: false)]
#[Column('ailastmessage', 'text', notnull: false)]
#[Column('aidispatchedat', 'int', length: 10, notnull: false)]
#[Column('ailastresponsejson', 'text', notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('slotunitquestion', ['slotid', 'unitid', 'questionid'])]
#[Index('sessionid', ['sessionid'])]
#[Index('studentplanid', ['studentplanid'])]
#[Index('correctionstatus', ['correctionstatus'])]
#[Index('userid', ['userid'])]
final class exam_submission_table {}exam_assign_link_table.php:
#[Table('helico_exam_assign_link', comment: 'HELICO - 1:1 link between a mod_assign submission and an exam_submission')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('examsubmissionid', 'int', length: 10, notnull: true)]
#[Column('assignsubmissionid', 'int', length: 10, notnull: true)]
#[Column('cmid', 'int', length: 10, notnull: false)]
#[Column('slotid', 'int', length: 10, notnull: false)]
#[Column('studentuserid', 'int', length: 10, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('examsubmissionid', ['examsubmissionid'])]
#[Index('assignsubmissionid', ['assignsubmissionid'])]
final class exam_assign_link_table {}exam_correction_table.php:
#[Table('helico_exam_correction', comment: 'HELICO - Tutor or AI correction of a written exam submission')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('submissionid', 'int', length: 10, notnull: true)]
#[Column('tutorid', 'int', length: 10, notnull: false, comment: '0 for AI corrections')]
#[Column('studentuserid', 'int', length: 10, notnull: false)]
#[Column('slotid', 'int', length: 10, notnull: false)]
#[Column('totalscore', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('maxscore', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('percentage', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('correctedat', 'int', length: 10, notnull: false)]
#[Column('source', 'char', length: 20, notnull: false)]
#[Column('parentcorrectionid', 'int', length: 10, notnull: false)]
#[Column('aimodel', 'char', length: 100, notnull: false)]
#[Column('finalscore100', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('finalscore10', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('aifeedbackjson', 'text', notnull: false)]
#[Column('aitranscriptionjson', 'text', notnull: false)]
#[Column('warnings', 'text', notnull: false)]
#[Column('cached', 'int', length: 1, notnull: false)]
#[Column('inputmismatch', 'int', length: 1, notnull: false)]
#[Column('feedbackhtml', 'text', notnull: false, comment: 'Tutor feedback HTML (was helico_items.description)')]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('submissionid', ['submissionid'])]
#[Index('slotid', ['slotid'])]
#[Index('studentuserid', ['studentuserid'])]
final class exam_correction_table {}criterion_score_table.php:
#[Table('helico_criterion_score', comment: 'HELICO - One scored criterion of an exam correction')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('correctionid', 'int', length: 10, notnull: true)]
#[Column('criterionname', 'text', notnull: false, comment: 'Can exceed 300 chars (observed)')]
#[Column('score', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('maxscore', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('weight', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('commenttext', 'text', notnull: false)]
#[Column('sortorder', 'int', length: 10, notnull: true, default: 0)]
#[Column('skillid', 'char', length: 100, notnull: false)]
#[Column('skilllabel', 'text', notnull: false)]
#[Column('status', 'char', length: 30, notnull: false)]
#[Column('statuslabel', 'text', notnull: false)]
#[Column('evidence', 'text', notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('correctionid', ['correctionid'])]
final class criterion_score_table {}slot_table.php:
#[Table('helico_slot', comment: 'HELICO - Executable activity slot of a student plan')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('studentplanid', 'int', length: 10, notnull: true, comment: 'helico_items id of the student plan')]
#[Column('courseid', 'int', length: 10, notnull: false)]
#[Column('uuid', 'char', length: 36, notnull: true)]
#[Column('flowref', 'char', length: 100, notnull: false)]
#[Column('blockref', 'char', length: 100, notnull: false)]
#[Column('sortorder', 'int', length: 10, notnull: true, default: 0)]
#[Column('slottype', 'char', length: 50, notnull: false)]
#[Column('slotstatus', 'char', length: 30, notnull: true, default: 'not_started')]
#[Column('label', 'text', notnull: false)]
#[Column('scope', 'text', notnull: false)]
#[Column('context', 'text', notnull: false, comment: 'JSON, up to ~160 KB')]
#[Column('result', 'text', notnull: false)]
#[Column('locked', 'text', notnull: false, comment: 'Legacy JSON blob of the lock')]
#[Column('action', 'text', notnull: false)]
#[Column('lockreason', 'char', length: 100, notnull: false)]
#[Column('lockmessage', 'text', notnull: false)]
#[Column('lockunlockrule', 'char', length: 100, notnull: false)]
#[Column('lockunlockat', 'int', length: 10, notnull: false)]
#[Column('writtencorrectionstate', 'char', length: 30, notnull: false)]
#[Column('writtenoverallscore', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('uuid', ['uuid'])]
#[Index('planblock', ['studentplanid', 'blockref'])]
#[Index('plantype', ['studentplanid', 'slottype'])]
#[Index('slottype', ['slottype'])]
final class slot_table {}uuid is a plain (non-unique) index: a legacy duplicate would make the boot-time copy lose a row instead of just copying it.
slot_scope_ref_table.php:
#[Table('helico_slot_scope_ref', comment: 'HELICO - One scope reference (discipline, unit...) of a slot')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('slotid', 'int', length: 10, notnull: true)]
#[Column('kind', 'char', length: 30, notnull: true, default: '')]
#[Column('refid', 'int', length: 10, notnull: true, default: 0)]
#[Column('name', 'text', notnull: false)]
#[Column('sortorder', 'int', length: 10, notnull: true, default: 0)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('slotid', ['slotid'])]
#[Index('slotkindref', ['slotid', 'kind', 'refid'])]
final class slot_scope_ref_table {}slot_lock_table.php:
#[Table('helico_slot_lock', comment: 'HELICO - Dependency edge: slotid is locked until dependsonslotid satisfies requiredstatus')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('slotid', 'int', length: 10, notnull: true, comment: 'The dependent (locked) slot')]
#[Column('dependsonslotid', 'int', length: 10, notnull: true)]
#[Column('kind', 'char', length: 30, notnull: true, default: 'prerequisite')]
#[Column('requiredstatus', 'char', length: 30, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('slotid', ['slotid'])]
#[Index('dependsonslotid', ['dependsonslotid'])]
final class slot_lock_table {}notebook_artifact_table.php:
#[Table('helico_notebook_artifact', comment: 'HELICO - Caderno Online artifact (one per enrolment, unit and topic)')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('enrolmentid', 'int', length: 10, notnull: true, comment: 'helico_items id of the enrolment (stays EAV)')]
#[Column('userid', 'int', length: 10, notnull: false, comment: 'The student')]
#[Column('studentplanid', 'int', length: 10, notnull: false)]
#[Column('unitid', 'int', length: 10, notnull: false)]
#[Column('disciplineid', 'int', length: 10, notnull: false)]
#[Column('topicid', 'int', length: 10, notnull: false)]
#[Column('slotid', 'int', length: 10, notnull: false)]
#[Column('sessionid', 'int', length: 10, notnull: false)]
#[Column('sourcetype', 'char', length: 30, notnull: false)]
#[Column('sourceorigin', 'char', length: 20, notnull: false)]
#[Column('visibilityscope', 'char', length: 20, notnull: false)]
#[Column('artifactstatus', 'char', length: 20, notnull: true, default: 'draft')]
#[Column('editorstateversion', 'int', length: 10, notnull: true, default: 0)]
#[Column('editorstateformat', 'char', length: 30, notnull: true, default: 'lexical-json')]
#[Column('editorstatejson', 'text', notnull: false, comment: 'Lexical state, rewritten on every autosave')]
#[Column('contenthtml', 'text', notnull: false, comment: 'Rendered content (was helico_items.description)')]
#[Column('lastinteractionat', 'int', length: 10, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('enrolmentunittopic', ['enrolmentid', 'unitid', 'topicid'])]
#[Index('slotscope', ['slotid', 'visibilityscope'])]
#[Index('userid', ['userid'])]
final class notebook_artifact_table {}notebook_annotation_table.php:
#[Table('helico_notebook_annotation', comment: 'HELICO - Highlight/note anchored to a mark of a notebook artifact')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('artifactid', 'int', length: 10, notnull: true)]
#[Column('userid', 'int', length: 10, notnull: false)]
#[Column('topicid', 'int', length: 10, notnull: false)]
#[Column('annotationkey', 'char', length: 191, notnull: true, default: '')]
#[Column('color', 'char', length: 30, notnull: false)]
#[Column('xpct', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('ypct', 'number', length: 10, notnull: false, decimals: 4)]
#[Column('commenttext', 'text', notnull: false, comment: 'Was helico_items.description')]
#[Column('createdat', 'int', length: 10, notnull: false)]
#[Column('updatedat', 'int', length: 10, notnull: false)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('artifactkey', ['artifactid', 'annotationkey'])]
final class notebook_annotation_table {}notebook_version_table.php:
#[Table('helico_notebook_version', comment: 'HELICO - Archived content of a notebook artifact before it was superseded')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('artifactid', 'int', length: 10, notnull: true)]
#[Column('createdby', 'int', length: 10, notnull: false)]
#[Column('versionnumber', 'int', length: 10, notnull: true, default: 1)]
#[Column('changereason', 'char', length: 100, notnull: false)]
#[Column('previousorigin', 'char', length: 30, notnull: false)]
#[Column('contenthtml', 'text', notnull: false, comment: 'Was helico_items.description')]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('artifactversion', ['artifactid', 'versionnumber'])]
final class notebook_version_table {}session_table.php:
#[Table('helico_session', comment: 'HELICO - Execution session of a slot by a student')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('slotid', 'int', length: 10, notnull: true, comment: 'helico_slot id (helico_items id for rows migrated from EAV)')]
#[Column('userid', 'int', length: 10, notnull: false)]
#[Column('courseid', 'int', length: 10, notnull: false)]
#[Column('sessionstatus', 'char', length: 20, notnull: true, default: 'in_progress')]
#[Column('startedat', 'int', length: 10, notnull: false)]
#[Column('pausedat', 'int', length: 10, notnull: false)]
#[Column('lastresumedat', 'int', length: 10, notnull: false)]
#[Column('timespent', 'int', length: 10, notnull: true, default: 0)]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('slotstatus', ['slotid', 'sessionstatus'])]
#[Index('userid', ['userid'])]
final class session_table {}session_data_table.php:
#[Table('helico_session_data', comment: 'HELICO - Per-slot-type JSON payload of a session (1:1, kept out of helico_session)')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('sessionid', 'int', length: 10, notnull: true)]
#[Column('sessiondata', 'text', notnull: false, comment: 'avg 112 KB, up to 1.4 MB')]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('sessionid', ['sessionid'])]
final class session_data_table {}helico_session_data has no definition in item_table_definitions: it is not an item type. It is filled by session_data_copier (Task 4) and written by session_data_repository (Task 13). sessionid is a plain index (not unique) for the same reason as the other keys: a concurrent first save must not throw.
`unit_snapshot_table.php`:
```php
#[Table('helico_unit_snapshot', comment: 'HELICO - Frozen content of a unit for a study plan (shared by its students)')]
#[Column('id', 'int', length: 10, notnull: true, sequence: true)]
#[Column('studyplanid', 'int', length: 10, notnull: true, comment: 'helico_items id of the product study plan (stays EAV)')]
#[Column('unitid', 'int', length: 10, notnull: true, default: 0, comment: 'source unit (helico_items id)')]
#[Column('sourceversion', 'char', length: 50, notnull: false)]
#[Column('contenthash', 'char', length: 64, notnull: false)]
#[Column('snapshotdata', 'text', notnull: false, comment: 'Frozen JSON; avg 128 KB, up to ~250 KB')]
#[Column('flashcard', 'text', notnull: false, comment: 'Mirror of unit_content.flashcard')]
#[Column('timecreated', 'int', length: 10, notnull: true, default: 0)]
#[Column('timemodified', 'int', length: 10, notnull: true, default: 0)]
#[Key('primary', ['id'], name: 'primary')]
#[Index('planunit', ['studyplanid', 'unitid'])]
#[Index('unitid', ['unitid'])]
final class unit_snapshot_table {}(studyplanid, unitid) is a plain index, not unique: the code already guards the lazy creation with a lock and dedups to the first row, and a unique index would make the boot-time copy drop a legacy duplicate. Make it unique in a later release, after SELECT studyplanid, unitid FROM mdl_helico_unit_snapshot GROUP BY 1, 2 HAVING COUNT(*) > 1 returns no rows in production.
- [ ] **Step 4: Create `dedicated_schema`**
`classes/base/persistence/dedicated_schema.php`:
```php
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\schema\classification_table;
use local_helico\base\persistence\schema\criterion_score_table;
use local_helico\base\persistence\schema\exam_assign_link_table;
use local_helico\base\persistence\schema\exam_correction_table;
use local_helico\base\persistence\schema\exam_submission_table;
use local_helico\base\persistence\schema\metrics_report_table;
use local_helico\base\persistence\schema\notebook_annotation_table;
use local_helico\base\persistence\schema\notebook_artifact_table;
use local_helico\base\persistence\schema\notebook_version_table;
use local_helico\base\persistence\schema\response_table;
use local_helico\base\persistence\schema\result_table;
use local_helico\base\persistence\schema\session_data_table;
use local_helico\base\persistence\schema\session_table;
use local_helico\base\persistence\schema\slot_lock_table;
use local_helico\base\persistence\schema\slot_scope_ref_table;
use local_helico\base\persistence\schema\slot_table;
use local_helico\base\persistence\schema\unit_snapshot_table;
use Middag\Framework\Database\Schema\SchemaBuilder;
/**
* The dedicated (non-EAV) tables of local_helico, declared as framework
* `#[Table]` descriptors. Parents come before children.
*/
final class dedicated_schema
{
/**
* @return list<class-string>
*/
public static function classes(): array
{
return [
response_table::class,
result_table::class,
classification_table::class,
metrics_report_table::class,
exam_submission_table::class,
exam_assign_link_table::class,
exam_correction_table::class,
criterion_score_table::class,
slot_table::class,
slot_scope_ref_table::class,
slot_lock_table::class,
notebook_artifact_table::class,
notebook_annotation_table::class,
notebook_version_table::class,
session_table::class,
session_data_table::class,
unit_snapshot_table::class,
];
}
public static function builder(): SchemaBuilder
{
return (new SchemaBuilder())->loadFromClasses(self::classes());
}
/**
* @return list<string>
*/
public static function table_names(): array
{
return array_keys(self::builder()->all());
}
}- Step 5: Generate the XML with the framework tool and merge it into
install.xml
The tool writes a whole file, and db/install.xml also holds the four EAV tables (which the tool cannot regenerate with the helico_ prefix), so generate to a scratch file and merge only the new <TABLE> blocks.
Add to composer.json scripts:
"build:schema:dedicated": "externallib/bin/middag-dev-tools build:schema --format=xmldb --source-dir=classes/base/persistence/schema --output=.cache/dedicated-tables.xml --xmldb-path=local/helico/db --xmldb-version=20261002 --xmldb-comment=\"XMLDB file for Moodle local/helico\"",Run: mkdir -p .cache && composer run-script build:schema:dedicated
Expected: .cache/dedicated-tables.xml exists and grep -c '<TABLE NAME="helico_' .cache/dedicated-tables.xml prints 17.
Merge (inserts the generated blocks before </TABLES>, leaves the EAV tables untouched):
php -r '
$gen = file_get_contents(".cache/dedicated-tables.xml");
preg_match_all("#\s*<TABLE NAME=\"helico_.*?</TABLE>#s", $gen, $m);
$xml = file_get_contents("db/install.xml");
if (str_contains($xml, "helico_response")) { fwrite(STDERR, "already merged\n"); exit(1); }
file_put_contents("db/install.xml", str_replace(" </TABLES>", implode("", $m[0]) . "\n </TABLES>", $xml));
'Run: grep -c '<TABLE NAME=' db/install.xml
Expected: 21 (4 EAV + 17 new). Run xmllint --noout db/install.xml — expected: no output.
- Step 6: Add the framework-runner upgrade step and bump the version
In db/upgrade.php, add the imports after defined('MOODLE_INTERNAL') || exit;:
use local_helico\base\persistence\dedicated_schema;
use Middag\Framework\Database\Schema\MysqlMigrationRunner;
use Middag\Moodle\Database\Schema\XmldbSchemaAdapter;
use Middag\Moodle\Persistence\VersionTracker;and before return true;:
if ($oldversion < 2026100200) {
// Framework runner: creates every missing dedicated table (with its indexes)
// and adds any missing column; a no-op for tables that already match.
(new MysqlMigrationRunner(
dedicated_schema::builder(),
new XmldbSchemaAdapter($dbman),
new VersionTracker('local_helico', 'schema_dedicated_version'),
))->upgrade((int) $oldversion);
upgrade_plugin_savepoint(true, 2026100200, 'local', 'helico');
}In version.php change $plugin->version = 2026092801; to $plugin->version = 2026100201; (the data step in Task 4 uses 2026100201; one version bump per release).
- Step 7: Run the test, then upgrade dev
Run: <TEST_CMD> --filter schema_test
Expected: PASS (1 + 17 + 1 tests).
Run: cd /var/www/docker-moodle-helico && make moodle CMD="upgrade.php --non-interactive"
Expected: upgrade completes; SELECT to_regclass('mdl_helico_response'); returns the table.
- Step 8: Commit
git add classes/base/persistence db/install.xml db/upgrade.php version.php composer.json tests/base/persistence/schema_test.php
git commit -m "feat(db): declare seventeen dedicated tables as framework descriptors"Task 3: Definitions and row→entity hydrator
Files:
- Create:
classes/base/persistence/item_table_definition.php - Create:
classes/base/persistence/item_table_definitions.php - Create:
classes/base/persistence/table_row_hydrator.php - Test:
tests/base/persistence/table_row_hydrator_test.php
Interfaces:
-
Produces:
item_table_definition(final readonly):string $type,string $table,string $parent_column,array<string,string> $meta_columns(meta key → column),array<string,string> $casts(column →'int'|'float'|'string'),?string $description_column,?string $idnumber_column,?string $status_column,string $fixed_status,?string $user_column,?string $sortorder_column,bool $parent_required.item_table_definitions::response(),::result(),::classification(),::report(),::exam_submission(),::exam_assign_link(),::exam_correction(),::criterion_score(),::slot(),::slot_scope_ref(),::slot_lock(),::notebook_artifact(),::notebook_annotation(),::notebook_version(),::session(),::unit_snapshot():item_table_definition;::all():list<item_table_definition>(parents before children).table_row_hydrator::hydrate(item_table_definition $def, string $entity_class, \stdClass $row): \local_middag\base\domain\item\item.table_row_hydrator::row_from_meta(item_table_definition $def, \stdClass $item, array $meta): \stdClass(EAV → table row; used by the migrator).table_row_hydrator::columns_from_meta(item_table_definition $def, array $meta): array(partial meta → columns; keys absent from$metaare absent from the result).table_row_hydrator::columns_from_dto(item_table_definition $def, \Middag\Core\Domain\Item\Contract\ItemDtoInterface $dto): array(what theitem_serviceoverrides in Tasks 5–10 use).
-
Step 1: Write the failing test
<?php
declare(strict_types=1);
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\response\entity\response;
use local_helico\extensions\metrics\report\entity\report;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class table_row_hydrator_test extends advanced_testcase
{
public function test_hydrates_response_and_keeps_getters(): void
{
$row = (object) ['id' => 7, 'sessionid' => 3, 'questionid' => 11, 'cardid' => null, 'unitid' => 5, 'courseid' => 2,
'answer' => 'V', 'correct' => 1, 'notsure' => 0, 'timems' => 1200, 'sortorder' => 4, 'category' => null,
'timecreated' => 100, 'timemodified' => 100];
$entity = table_row_hydrator::hydrate(item_table_definitions::response(), response::class, $row);
$this->assertInstanceOf(response::class, $entity);
$this->assertSame(7, $entity->getId());
$this->assertSame(3, $entity->getParent());
$this->assertSame(3, $entity->get_session_id());
$this->assertSame(11, $entity->get_question_id());
$this->assertNull($entity->get_card_id());
$this->assertSame(4, $entity->get_sort_order());
}
public function test_report_hydration_keeps_null_invalidated_and_payload(): void
{
$row = (object) ['id' => 9, 'enrolmentid' => 21, 'studentplanid' => 4, 'scope' => 'overall', 'scopetargetid' => null,
'status' => 'fresh', 'idnumber' => 'report:21:overall:all', 'dimensiondata' => '{"a":1}',
'generatedat' => 500, 'invalidatedat' => null, 'timecreated' => 500, 'timemodified' => 500];
$entity = table_row_hydrator::hydrate(item_table_definitions::report(), report::class, $row);
$this->assertSame(21, $entity->get_enrolment_id());
$this->assertNull($entity->get_scope_target_id());
$this->assertSame('{"a":1}', $entity->getDescription());
$this->assertSame('report:21:overall:all', $entity->getIdnumber());
$this->assertSame('fresh', $entity->getStatus());
}
public function test_row_from_meta_casts_and_nulls(): void
{
$item = (object) ['id' => 7, 'parent' => 3, 'status' => 'recorded', 'timecreated' => 100, 'timemodified' => 110,
'description' => null, 'idnumber' => null];
$meta = ['session_id' => '3', 'question_id' => '11', 'correct' => '1', 'answer' => 'V', 'timems' => ''];
$row = table_row_hydrator::row_from_meta(item_table_definitions::response(), $item, $meta);
$this->assertSame(7, $row->id);
$this->assertSame(3, $row->sessionid);
$this->assertSame(11, $row->questionid);
$this->assertNull($row->cardid);
$this->assertNull($row->timems);
$this->assertSame(1, $row->correct);
$this->assertSame(110, $row->timemodified);
}
public function test_exam_submission_without_parent_keeps_null_and_student_userid(): void
{
$item = (object) ['id' => 40, 'parent' => null, 'userid' => 12, 'status' => 'pending', 'timecreated' => 1, 'timemodified' => 2,
'description' => 'texto do aluno', 'idnumber' => 'exam_submission:slot:0', 'sortorder' => 0];
$row = table_row_hydrator::row_from_meta(item_table_definitions::exam_submission(), $item, ['correction_status' => 'pending', 'slot_id' => '0']);
$this->assertNull($row->slotid);
$this->assertSame(12, $row->userid);
$this->assertSame('texto do aluno', $row->submittedtext);
$this->assertSame('pending', $row->correctionstatus);
$entity = table_row_hydrator::hydrate(item_table_definitions::exam_submission(), \local_helico\extensions\activity\assessment\exam_submission\entity\exam_submission::class, $row);
$this->assertNull($entity->getParent());
$this->assertSame(12, $entity->getUserid());
$this->assertSame(0, $entity->get_slot_id());
}
public function test_criterion_score_round_trip_keeps_sortorder_and_long_names(): void
{
$name = str_repeat('Conceito de poder constituinte ', 12);
$item = (object) ['id' => 70, 'parent' => 5140, 'userid' => null, 'status' => 'recorded', 'timecreated' => 1, 'timemodified' => 1,
'description' => null, 'idnumber' => 'criterion_score:5140:2', 'sortorder' => 2];
$meta = ['criterion_name' => $name, 'score' => '1.5', 'max' => '2', 'weight' => '1', 'sort_order' => '2', 'comment' => ''];
$row = table_row_hydrator::row_from_meta(item_table_definitions::criterion_score(), $item, $meta);
$entity = table_row_hydrator::hydrate(item_table_definitions::criterion_score(), \local_helico\extensions\activity\assessment\exam_correction\entity\criterion_score::class, $row);
$this->assertSame(5140, $row->correctionid);
$this->assertSame(2, $row->sortorder);
$this->assertSame($name, $entity->get_criterion_name());
$this->assertSame(1.5, $entity->get_score());
$this->assertSame(2.0, $entity->get_max());
$this->assertNull($entity->get_comment());
$this->assertSame(2, $entity->get_criterion_sort_order());
}
public function test_defaults_are_per_definition_a_null_slot_scope_stays_null(): void
{
$item = (object) ['id' => 3254, 'parent' => 3247, 'userid' => null, 'status' => 'completed', 'timecreated' => 1, 'timemodified' => 2,
'description' => null, 'idnumber' => null, 'sortorder' => 0, 'fullname' => 'Diagnóstico Inicial'];
$meta = ['uuid' => 'u-1', 'student_plan_id' => '3247', 'blockref' => 'B1', 'slot_type' => 'diagnostic_initial', 'slot_status' => 'completed', 'label' => 'Diagnóstico Inicial', 'sort_order' => '', 'lock_reason' => ''];
$row = table_row_hydrator::row_from_meta(item_table_definitions::slot(), $item, $meta);
$this->assertNull($row->scope);
$this->assertNull($row->lockreason);
$this->assertSame(0, $row->sortorder);
$this->assertSame('completed', $row->slotstatus);
$this->assertSame(3247, $row->studentplanid);
$report = table_row_hydrator::row_from_meta(item_table_definitions::report(), (object) ['id' => 1, 'parent' => 21, 'status' => 'fresh', 'timecreated' => 1, 'timemodified' => 1, 'description' => '{}', 'idnumber' => 'report:21:overall:all', 'sortorder' => 0], []);
$this->assertSame('overall', $report->scope);
}
public function test_slot_hydration_exposes_label_status_and_lock_keys(): void
{
$row = (object) ['id' => 9, 'studentplanid' => 3, 'courseid' => 2, 'uuid' => 'u-9', 'flowref' => 'F1', 'blockref' => 'B1', 'sortorder' => 4,
'slottype' => 'guided_study', 'slotstatus' => 'in_progress', 'label' => 'Estudo', 'scope' => null, 'context' => '{"a":1}', 'result' => null,
'locked' => '{"reason":"x"}', 'action' => null, 'lockreason' => 'prerequisite', 'lockmessage' => null, 'lockunlockrule' => 'r', 'lockunlockat' => null,
'writtencorrectionstate' => null, 'writtenoverallscore' => null, 'timecreated' => 1, 'timemodified' => 2];
$slot = table_row_hydrator::hydrate(item_table_definitions::slot(), \local_helico\extensions\engine\algorithm\entity\slot::class, $row);
$this->assertSame(3, $slot->getParent());
$this->assertSame('Estudo', $slot->getFullname());
$this->assertSame('in_progress', $slot->getStatus());
$this->assertSame('in_progress', $slot->get_slot_status());
$this->assertSame(3, $slot->get_student_plan_id());
$this->assertSame(4, $slot->get_sort_order());
$this->assertNull($slot->get_scope());
$this->assertSame('{"a":1}', $slot->get_context());
$this->assertSame('prerequisite', $slot->getMeta('lock_reason'));
}
public function test_columns_from_dto_is_partial_and_ignores_default_draft_status(): void
{
$dto = new \local_middag\base\domain\item\item_dto(
id: 9,
type: 'exam_submission',
metadata: ['ai_last_message' => 'unreadable', 'ai_last_response_json' => '{"x":1}'],
);
$columns = table_row_hydrator::columns_from_dto(item_table_definitions::exam_submission(), $dto);
$this->assertSame(['ailastmessage' => 'unreadable', 'ailastresponsejson' => '{"x":1}'], $columns);
}
public function test_columns_from_dto_maps_status_description_and_explicit_null(): void
{
$dto = new \local_middag\base\domain\item\item_dto(
id: 9,
type: 'exam_submission',
status: 'corrected',
description: 'novo texto',
metadata: ['corrected_by' => 4, 'corrected_at' => null],
);
$columns = table_row_hydrator::columns_from_dto(item_table_definitions::exam_submission(), $dto);
$this->assertSame('corrected', $columns['correctionstatus']);
$this->assertSame('novo texto', $columns['submittedtext']);
$this->assertSame(4, $columns['correctedby']);
$this->assertArrayHasKey('correctedat', $columns);
$this->assertNull($columns['correctedat']);
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter table_row_hydrator_test
Expected: FAIL (Class ... item_table_definitions not found).
- Step 3: Implement the definition value object
classes/base/persistence/item_table_definition.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
/**
* Describes how one EAV item type maps onto one dedicated table.
*/
final readonly class item_table_definition
{
/**
* @param array<string, string> $meta_columns EAV meta key => table column
* @param array<string, string> $casts table column => 'int'|'float'|'string'
*/
public function __construct(
public string $type,
public string $table,
public string $parent_column,
public array $meta_columns,
public array $casts,
public ?string $description_column = null,
public ?string $idnumber_column = null,
public ?string $status_column = null,
public string $fixed_status = 'active',
public ?string $user_column = null,
public ?string $sortorder_column = null,
public bool $parent_required = true,
public ?string $fullname_column = null,
public array $defaults = [],
) {}
}New optional fields (all earlier definitions leave them at their defaults):
-
user_column: the column the entity’sgetUserid()reads. If it is not one of themeta_columnsvalues,row_from_metaalso copieshelico_items.useridinto it (this is the case forexam_submission.userid, the student). -
sortorder_column: the column that mirrorshelico_items.sortorderwhen the meta key does not already provide it. -
fullname_column: the column the entity’sgetFullname()reads (the slot’slabel). -
defaults:column => valueapplied byrow_from_metawhen a NOT NULL column would otherwise beNULL, per definition (a global list would turn a nullableslot.scopeinto'overall'). -
parent_required: whenfalse, an item whoseparentisNULLis migrated (parent column staysNULL) instead of being counted as an orphan. -
Step 4: Implement the sixteen definitions
classes/base/persistence/item_table_definitions.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
/**
* Single source of truth for the Phase 1 type -> table mappings, shared by the
* migrator, the hydrator and the repositories.
*/
final class item_table_definitions
{
public static function response(): item_table_definition
{
return new item_table_definition(
type: 'response',
table: 'helico_response',
parent_column: 'sessionid',
meta_columns: [
'question_id' => 'questionid',
'card_id' => 'cardid',
'unit_id' => 'unitid',
'courseid' => 'courseid',
'answer' => 'answer',
'correct' => 'correct',
'notsure' => 'notsure',
'timems' => 'timems',
'sort_order' => 'sortorder',
'category' => 'category',
],
casts: [
'questionid' => 'int', 'cardid' => 'int', 'unitid' => 'int', 'courseid' => 'int',
'correct' => 'int', 'notsure' => 'int', 'timems' => 'int', 'sortorder' => 'int',
'answer' => 'string', 'category' => 'string',
],
fixed_status: 'recorded',
defaults: ['correct' => 0, 'notsure' => 0, 'sortorder' => 0],
);
}
public static function result(): item_table_definition
{
return new item_table_definition(
type: 'activity_result',
table: 'helico_result',
parent_column: 'sessionid',
meta_columns: [
'slot_id' => 'slotid',
'student_plan_id' => 'studentplanid',
'enrolment_id' => 'enrolmentid',
'unit_id' => 'unitid',
'slot_type' => 'slottype',
'completion_status' => 'completionstatus',
'completed_at' => 'completedat',
'nota_real' => 'notareal',
'nota_bruta' => 'notabruta',
'nota_ajustada' => 'notaajustada',
'bonus_relevancia' => 'bonusrelevancia',
'total_questions' => 'totalquestions',
'correct_count' => 'correctcount',
'incorrect_count' => 'incorrectcount',
'unanswered_count' => 'unansweredcount',
'time_total_ms' => 'timetotalms',
],
casts: [
'slotid' => 'int', 'studentplanid' => 'int', 'enrolmentid' => 'int', 'unitid' => 'int',
'completedat' => 'int', 'totalquestions' => 'int', 'correctcount' => 'int',
'incorrectcount' => 'int', 'unansweredcount' => 'int', 'timetotalms' => 'int',
'notareal' => 'float', 'notabruta' => 'float', 'notaajustada' => 'float', 'bonusrelevancia' => 'float',
'slottype' => 'string', 'completionstatus' => 'string',
],
fixed_status: 'completed',
defaults: ['completionstatus' => 'completed'],
);
}
public static function classification(): item_table_definition
{
return new item_table_definition(
type: 'classification',
table: 'helico_classification',
parent_column: 'studentplanid',
meta_columns: [
'user_id' => 'userid',
'courseid' => 'courseid',
'unit_id' => 'unitid',
'level' => 'level',
'source' => 'source',
'score' => 'score',
'slot_id' => 'slotid',
'submission_id' => 'submissionid',
'correct_count' => 'correctcount',
'total_count' => 'totalcount',
],
casts: [
'userid' => 'int', 'courseid' => 'int', 'unitid' => 'int', 'slotid' => 'int',
'submissionid' => 'int', 'correctcount' => 'int', 'totalcount' => 'int',
'score' => 'float', 'level' => 'string', 'source' => 'string',
],
status_column: 'level',
defaults: ['level' => ''],
);
}
public static function report(): item_table_definition
{
return new item_table_definition(
type: 'metrics_report',
table: 'helico_metrics_report',
parent_column: 'enrolmentid',
meta_columns: [
'student_plan_id' => 'studentplanid',
'scope' => 'scope',
'scope_target_id' => 'scopetargetid',
'generated_at' => 'generatedat',
'invalidated_at' => 'invalidatedat',
],
casts: [
'studentplanid' => 'int', 'scopetargetid' => 'int', 'generatedat' => 'int',
'invalidatedat' => 'int', 'scope' => 'string',
],
description_column: 'dimensiondata',
idnumber_column: 'idnumber',
status_column: 'status',
fixed_status: 'fresh',
defaults: ['scope' => 'overall', 'status' => 'fresh'],
);
}
/**
* `parent` is the slot (a table now, but the migrator checks the pre-migration row in `helico_items`); it is NULL for legacy rows with slot_id <= 0.
* `helico_items.userid` is the student, which is not a meta key, hence the real `userid` column.
*/
public static function exam_submission(): item_table_definition
{
return new item_table_definition(
type: 'exam_submission',
table: 'helico_exam_submission',
parent_column: 'slotid',
meta_columns: [
'question_id' => 'questionid',
'unit_id' => 'unitid',
'session_id' => 'sessionid',
'student_plan_id' => 'studentplanid',
'submitted_at' => 'submittedat',
'correction_status' => 'correctionstatus',
'corrected_by' => 'correctedby',
'corrected_at' => 'correctedat',
'ai_attempt' => 'aiattempt',
'ai_external_id' => 'aiexternalid',
'ai_status_path' => 'aistatuspath',
'ai_last_message' => 'ailastmessage',
'ai_dispatched_at' => 'aidispatchedat',
'ai_last_response_json' => 'ailastresponsejson',
],
casts: [
'questionid' => 'int', 'unitid' => 'int', 'sessionid' => 'int', 'studentplanid' => 'int',
'submittedat' => 'int', 'correctedby' => 'int', 'correctedat' => 'int',
'aiattempt' => 'int', 'aidispatchedat' => 'int',
'correctionstatus' => 'string', 'aiexternalid' => 'string', 'aistatuspath' => 'string',
'ailastmessage' => 'string', 'ailastresponsejson' => 'string',
],
description_column: 'submittedtext',
status_column: 'correctionstatus',
fixed_status: 'pending',
user_column: 'userid',
parent_required: false,
defaults: ['correctionstatus' => 'pending'],
);
}
public static function exam_assign_link(): item_table_definition
{
return new item_table_definition(
type: 'exam_assign_link',
table: 'helico_exam_assign_link',
parent_column: 'examsubmissionid',
meta_columns: [
'assign_submission_id' => 'assignsubmissionid',
'cmid' => 'cmid',
'slot_id' => 'slotid',
'student_user_id' => 'studentuserid',
],
casts: ['assignsubmissionid' => 'int', 'cmid' => 'int', 'slotid' => 'int', 'studentuserid' => 'int'],
user_column: 'studentuserid',
);
}
/**
* `helico_items.userid` is the tutor (0 for AI), the same value as the `tutor_id` meta.
* `description` holds the tutor feedback HTML.
*/
public static function exam_correction(): item_table_definition
{
return new item_table_definition(
type: 'exam_correction',
table: 'helico_exam_correction',
parent_column: 'submissionid',
meta_columns: [
'tutor_id' => 'tutorid',
'student_user_id' => 'studentuserid',
'slot_id' => 'slotid',
'total_score' => 'totalscore',
'max_score' => 'maxscore',
'percentage' => 'percentage',
'corrected_at' => 'correctedat',
'source' => 'source',
'parent_correction_id' => 'parentcorrectionid',
'ai_model' => 'aimodel',
'final_score_100' => 'finalscore100',
'final_score_10' => 'finalscore10',
'ai_feedback_json' => 'aifeedbackjson',
'ai_transcription_json' => 'aitranscriptionjson',
'warnings' => 'warnings',
'cached' => 'cached',
'input_mismatch' => 'inputmismatch',
],
casts: [
'tutorid' => 'int', 'studentuserid' => 'int', 'slotid' => 'int', 'correctedat' => 'int',
'parentcorrectionid' => 'int', 'cached' => 'int', 'inputmismatch' => 'int',
'totalscore' => 'float', 'maxscore' => 'float', 'percentage' => 'float',
'finalscore100' => 'float', 'finalscore10' => 'float',
'source' => 'string', 'aimodel' => 'string', 'aifeedbackjson' => 'string',
'aitranscriptionjson' => 'string', 'warnings' => 'string',
],
description_column: 'feedbackhtml',
fixed_status: 'corrected',
user_column: 'tutorid',
);
}
/**
* `helico_items.sortorder` and the `sort_order` meta carry the same value; both land in `sortorder`.
*/
public static function criterion_score(): item_table_definition
{
return new item_table_definition(
type: 'criterion_score',
table: 'helico_criterion_score',
parent_column: 'correctionid',
meta_columns: [
'criterion_name' => 'criterionname',
'score' => 'score',
'max' => 'maxscore',
'weight' => 'weight',
'comment' => 'commenttext',
'sort_order' => 'sortorder',
'skill_id' => 'skillid',
'skill_label' => 'skilllabel',
'status' => 'status',
'status_label' => 'statuslabel',
'evidence' => 'evidence',
],
casts: [
'score' => 'float', 'maxscore' => 'float', 'weight' => 'float', 'sortorder' => 'int',
'criterionname' => 'string', 'commenttext' => 'string', 'skillid' => 'string',
'skilllabel' => 'string', 'status' => 'string', 'statuslabel' => 'string', 'evidence' => 'string',
],
fixed_status: 'recorded',
sortorder_column: 'sortorder',
defaults: ['sortorder' => 0],
);
}
/**
* `parent` is the student plan (still EAV). `helico_items.status` mirrors `slot_status` and
* `helico_items.fullname` is the label. The lock keys (`lock_*`) are columns too.
*/
public static function slot(): item_table_definition
{
return new item_table_definition(
type: 'slot',
table: 'helico_slot',
parent_column: 'studentplanid',
meta_columns: [
'courseid' => 'courseid',
'uuid' => 'uuid',
'flowref' => 'flowref',
'blockref' => 'blockref',
'sort_order' => 'sortorder',
'slot_type' => 'slottype',
'slot_status' => 'slotstatus',
'label' => 'label',
'scope' => 'scope',
'context' => 'context',
'result' => 'result',
'locked' => 'locked',
'action' => 'action',
'lock_reason' => 'lockreason',
'lock_message' => 'lockmessage',
'lock_unlock_rule' => 'lockunlockrule',
'lock_unlock_at' => 'lockunlockat',
'written_correction_state' => 'writtencorrectionstate',
'written_overall_score' => 'writtenoverallscore',
],
casts: [
'courseid' => 'int', 'sortorder' => 'int', 'lockunlockat' => 'int', 'writtenoverallscore' => 'float',
'uuid' => 'string', 'flowref' => 'string', 'blockref' => 'string', 'slottype' => 'string',
'slotstatus' => 'string', 'label' => 'string', 'scope' => 'string', 'context' => 'string',
'result' => 'string', 'locked' => 'string', 'action' => 'string', 'lockreason' => 'string',
'lockmessage' => 'string', 'lockunlockrule' => 'string', 'writtencorrectionstate' => 'string',
],
status_column: 'slotstatus',
fixed_status: 'not_started',
fullname_column: 'label',
defaults: ['sortorder' => 0, 'slotstatus' => 'not_started'],
);
}
/**
* `parent` is the slot. `helico_items.sortorder` carries the same value as the `sort_order` meta.
*/
public static function slot_scope_ref(): item_table_definition
{
return new item_table_definition(
type: 'slot_scope_ref',
table: 'helico_slot_scope_ref',
parent_column: 'slotid',
meta_columns: [
'kind' => 'kind',
'ref_id' => 'refid',
'name' => 'name',
'sort_order' => 'sortorder',
],
casts: ['refid' => 'int', 'sortorder' => 'int', 'kind' => 'string', 'name' => 'string'],
sortorder_column: 'sortorder',
defaults: ['kind' => '', 'refid' => 0, 'sortorder' => 0],
);
}
/**
* `parent` is the dependent slot; `depends_on_slot_id` is the upstream slot.
*/
public static function slot_lock(): item_table_definition
{
return new item_table_definition(
type: 'lock_dependency',
table: 'helico_slot_lock',
parent_column: 'slotid',
meta_columns: [
'depends_on_slot_id' => 'dependsonslotid',
'kind' => 'kind',
'required_status' => 'requiredstatus',
],
casts: ['dependsonslotid' => 'int', 'kind' => 'string', 'requiredstatus' => 'string'],
defaults: ['dependsonslotid' => 0, 'kind' => 'prerequisite'],
);
}
/**
* `parent` is the enrolment, which stays EAV. `helico_items.userid` is the student and
* `helico_items.description` is the rendered content HTML.
*/
public static function notebook_artifact(): item_table_definition
{
return new item_table_definition(
type: 'notebook_artifact',
table: 'helico_notebook_artifact',
parent_column: 'enrolmentid',
meta_columns: [
'student_plan_id' => 'studentplanid',
'unit_id' => 'unitid',
'discipline_id' => 'disciplineid',
'topic_id' => 'topicid',
'slot_id' => 'slotid',
'session_id' => 'sessionid',
'source_type' => 'sourcetype',
'source_origin' => 'sourceorigin',
'visibility_scope' => 'visibilityscope',
'artifact_status' => 'artifactstatus',
'editor_state_version' => 'editorstateversion',
'editor_state_format' => 'editorstateformat',
'editor_state_json' => 'editorstatejson',
'last_interaction_at' => 'lastinteractionat',
],
casts: [
'studentplanid' => 'int', 'unitid' => 'int', 'disciplineid' => 'int', 'topicid' => 'int', 'slotid' => 'int',
'sessionid' => 'int', 'editorstateversion' => 'int', 'lastinteractionat' => 'int',
'sourcetype' => 'string', 'sourceorigin' => 'string', 'visibilityscope' => 'string',
'artifactstatus' => 'string', 'editorstateformat' => 'string', 'editorstatejson' => 'string',
],
description_column: 'contenthtml',
status_column: 'artifactstatus',
fixed_status: 'draft',
user_column: 'userid',
defaults: ['artifactstatus' => 'draft', 'editorstateversion' => 0, 'editorstateformat' => 'lexical-json'],
);
}
/**
* `parent` is the artifact; `description` is the annotation comment.
*/
public static function notebook_annotation(): item_table_definition
{
return new item_table_definition(
type: 'notebook_annotation',
table: 'helico_notebook_annotation',
parent_column: 'artifactid',
meta_columns: [
'topic_id' => 'topicid',
'annotation_key' => 'annotationkey',
'color' => 'color',
'x_pct' => 'xpct',
'y_pct' => 'ypct',
'created_at' => 'createdat',
'updated_at' => 'updatedat',
],
casts: [
'topicid' => 'int', 'createdat' => 'int', 'updatedat' => 'int', 'xpct' => 'float', 'ypct' => 'float',
'annotationkey' => 'string', 'color' => 'string',
],
description_column: 'commenttext',
fixed_status: 'active',
user_column: 'userid',
defaults: ['annotationkey' => ''],
);
}
/**
* `parent` is the artifact; `helico_items.userid` equals the `created_by` meta; `description`
* is the content HTML that was superseded.
*/
public static function notebook_version(): item_table_definition
{
return new item_table_definition(
type: 'artifact_version',
table: 'helico_notebook_version',
parent_column: 'artifactid',
meta_columns: [
'version_number' => 'versionnumber',
'change_reason' => 'changereason',
'previous_origin' => 'previousorigin',
'created_by' => 'createdby',
],
casts: ['versionnumber' => 'int', 'createdby' => 'int', 'changereason' => 'string', 'previousorigin' => 'string'],
description_column: 'contenthtml',
fixed_status: 'archived',
user_column: 'createdby',
defaults: ['versionnumber' => 1],
);
}
/**
* `parent` is the slot; `helico_items.userid` equals the `user_id` meta. `helico_items.status`
* is unreliable for sessions (it holds `draft` for some), so `session_status` is the status. The `data` meta is NOT mapped: it goes to `helico_session_data` (see `session_data_copier`).
*/
public static function session(): item_table_definition
{
return new item_table_definition(
type: 'session',
table: 'helico_session',
parent_column: 'slotid',
meta_columns: [
'courseid' => 'courseid',
'user_id' => 'userid',
'session_status' => 'sessionstatus',
'started_at' => 'startedat',
'paused_at' => 'pausedat',
'last_resumed_at' => 'lastresumedat',
'time_spent' => 'timespent',
],
casts: [
'courseid' => 'int', 'userid' => 'int', 'startedat' => 'int', 'pausedat' => 'int', 'lastresumedat' => 'int',
'timespent' => 'int', 'sessionstatus' => 'string',
],
status_column: 'sessionstatus',
fixed_status: 'in_progress',
user_column: 'userid',
defaults: ['sessionstatus' => 'in_progress', 'timespent' => 0],
);
}
/**
* `parent` is the product study plan (stays EAV); `version` and `source_version` carry the same value.
*/
public static function unit_snapshot(): item_table_definition
{
return new item_table_definition(
type: 'unit_snapshot',
table: 'helico_unit_snapshot',
parent_column: 'studyplanid',
meta_columns: [
'source_unit_id' => 'unitid',
'source_version' => 'sourceversion',
'snapshot_data' => 'snapshotdata',
'content_hash' => 'contenthash',
'flashcard' => 'flashcard',
],
casts: [
'unitid' => 'int', 'sourceversion' => 'string', 'snapshotdata' => 'string',
'contenthash' => 'string', 'flashcard' => 'string',
],
fixed_status: 'active',
defaults: ['unitid' => 0],
);
}
/**
* Parents before children.
*
* @return list<item_table_definition>
*/
public static function all(): array
{
return [
self::response(),
self::result(),
self::classification(),
self::report(),
self::exam_submission(),
self::exam_assign_link(),
self::exam_correction(),
self::criterion_score(),
self::slot(),
self::slot_scope_ref(),
self::slot_lock(),
self::notebook_artifact(),
self::notebook_annotation(),
self::notebook_version(),
self::session(),
self::unit_snapshot(),
];
}
}Note: classification items use status = level (3 distinct values observed: e.g. avancado), so the level column doubles as status; status_column: 'level' makes the hydrator read it back.
- Step 5: Implement the hydrator
classes/base/persistence/table_row_hydrator.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use local_middag\base\domain\item\item;
use stdClass;
/**
* Converts between EAV items/meta and dedicated-table rows, and rebuilds the
* existing entity classes from rows so their get_*() callers keep working.
*/
final class table_row_hydrator
{
/**
* @param class-string<item> $entity_class
*/
public static function hydrate(item_table_definition $def, string $entity_class, stdClass $row): item
{
$metadata = [];
foreach ($def->meta_columns as $meta_key => $column) {
// A projection (`->select([...])` run through `typed_query`) leaves the property out: keep the key absent too,
// so an entity with a lazy payload can load it, instead of reporting a false `null`.
if (property_exists($row, $column)) {
$metadata[$meta_key] = $row->{$column};
}
}
$metadata[self::meta_key_for_parent($def)] = $row->{$def->parent_column} ?? null;
$parent = $row->{$def->parent_column} ?? null;
return new $entity_class(
id: (int) $row->id,
type: $def->type,
userid: $def->user_column !== null && ($row->{$def->user_column} ?? null) !== null ? (int) $row->{$def->user_column} : null,
parent: $parent !== null ? (int) $parent : null,
sortorder: $def->sortorder_column !== null ? (int) ($row->{$def->sortorder_column} ?? 0) : 0,
fullname: $def->fullname_column !== null ? ($row->{$def->fullname_column} ?? null) : null,
idnumber: $def->idnumber_column !== null ? $row->{$def->idnumber_column} : null,
description: $def->description_column !== null ? $row->{$def->description_column} : null,
status: $def->status_column !== null ? (string) $row->{$def->status_column} : $def->fixed_status,
timecreated: (int) ($row->timecreated ?? 0),
timemodified: (int) ($row->timemodified ?? 0),
metadata: $metadata,
);
}
/**
* Builds a table row from an EAV item record plus its metadata map.
*
* @param array<string, mixed> $meta meta_key => raw value
*/
public static function row_from_meta(item_table_definition $def, stdClass $item, array $meta): stdClass
{
$row = (object) [
'id' => (int) $item->id,
$def->parent_column => $item->parent !== null ? (int) $item->parent : null,
'timecreated' => (int) $item->timecreated,
'timemodified' => (int) $item->timemodified,
];
foreach ($def->meta_columns as $meta_key => $column) {
$row->{$column} = self::cast($meta[$meta_key] ?? null, $def->casts[$column] ?? 'string');
}
if ($def->description_column !== null) {
$row->{$def->description_column} = $item->description;
}
if ($def->idnumber_column !== null) {
$row->{$def->idnumber_column} = (string) $item->idnumber;
}
if ($def->status_column !== null && !isset($row->{$def->status_column})) {
$row->{$def->status_column} = (string) $item->status;
}
if ($def->user_column !== null && !in_array($def->user_column, $def->meta_columns, true)) {
$row->{$def->user_column} = $item->userid !== null ? (int) $item->userid : null;
}
if ($def->sortorder_column !== null && !isset($row->{$def->sortorder_column})) {
$row->{$def->sortorder_column} = (int) $item->sortorder;
}
foreach ($def->defaults as $column => $default) {
if (($row->{$column} ?? null) === null) {
$row->{$column} = $default;
}
}
return $row;
}
/**
* Table columns for a *partial* set of EAV meta values (only the keys present
* in $meta are returned, nulls included, so an explicit null clears a column).
*
* @param array<string, mixed> $meta meta_key => value
*
* @return array<string, int|float|string|null>
*/
public static function columns_from_meta(item_table_definition $def, array $meta): array
{
$columns = [];
foreach ($def->meta_columns as $meta_key => $column) {
if (array_key_exists($meta_key, $meta)) {
$columns[$column] = self::cast($meta[$meta_key], $def->casts[$column] ?? 'string');
}
}
return $columns;
}
/**
* Table columns for an `item_dto` handed to an `item_service` override.
* Works for create and for partial update: only what the DTO actually sets is returned.
* `$dto->status` defaults to `'draft'`, which no migrated type uses, so `'draft'` is ignored.
*
* @return array<string, int|float|string|null>
*/
public static function columns_from_dto(item_table_definition $def, \Middag\Core\Domain\Item\Contract\ItemDtoInterface $dto): array
{
$columns = self::columns_from_meta($def, $dto->metadata);
if ($dto->parent !== null) {
$columns[$def->parent_column] = (int) $dto->parent;
}
if ($def->description_column !== null && $dto->description !== null) {
$columns[$def->description_column] = $dto->description;
}
if ($def->user_column !== null && !in_array($def->user_column, $def->meta_columns, true) && $dto->userid !== null) {
$columns[$def->user_column] = (int) $dto->userid;
}
if ($def->sortorder_column !== null && !array_key_exists($def->sortorder_column, $columns) && $dto->sortorder !== null) {
$columns[$def->sortorder_column] = (int) $dto->sortorder;
}
if ($def->status_column !== null && !array_key_exists($def->status_column, $columns) && $dto->status !== null && $dto->status !== 'draft') {
$columns[$def->status_column] = $dto->status;
}
return $columns;
}
private static function cast(mixed $value, string $type): int|float|string|null
{
if ($value === null || $value === '') {
return null;
}
return match ($type) {
'int' => (int) $value,
'float' => (float) $value,
default => (string) $value,
};
}
private static function meta_key_for_parent(item_table_definition $def): string
{
return match ($def->parent_column) {
'sessionid' => 'session_id',
'studentplanid' => 'student_plan_id',
'enrolmentid' => 'enrolment_id',
'slotid' => 'slot_id',
'submissionid' => 'submission_id',
'examsubmissionid' => 'exam_submission_id',
'correctionid' => 'correction_id',
'artifactid' => 'artifact_id',
'studyplanid' => 'study_plan_id',
default => $def->parent_column,
};
}
}Columns that are NOT NULL in the table get their default from the definition’s defaults (see Step 4), applied at the end of row_from_meta above.
- Step 6: Run the tests
Run: <TEST_CMD> --filter table_row_hydrator_test
Expected: PASS (3 tests). If the entity constructor rejects named args, the failure names the missing parameter; adjust the argument list to Middag\Core\Domain\Item\Item::__construct (id, type, userid, scope, parent, fullname, shortname, idnumber, description, descriptionformat, status, visible, guid, sortorder, version, timecreated, timemodified, usermodified, metadata).
- Step 7: Pin definitions to descriptors (drift guard)
Add tests/base/persistence/definitions_match_schema_test.php:
<?php
declare(strict_types=1);
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class definitions_match_schema_test extends advanced_testcase
{
public static function definition_provider(): array
{
$cases = [];
foreach (item_table_definitions::all() as $definition) {
$cases[$definition->table] = [$definition];
}
return $cases;
}
/**
* @dataProvider definition_provider
*/
public function test_every_mapped_column_exists_with_a_compatible_cast(item_table_definition $definition): void
{
$descriptor = dedicated_schema::builder()->table($definition->table);
$this->assertNotNull($descriptor, "{$definition->table} has no descriptor");
$types = [];
foreach ($descriptor['columns'] as $column) {
$types[$column['name']] = $column['type'];
}
$mapped = array_values($definition->meta_columns);
$mapped[] = $definition->parent_column;
foreach (array_filter([$definition->description_column, $definition->idnumber_column, $definition->status_column, $definition->user_column, $definition->sortorder_column, $definition->fullname_column]) as $column) {
$mapped[] = $column;
}
foreach (array_keys($definition->defaults) as $column) {
$mapped[] = $column;
}
foreach (array_unique($mapped) as $column) {
$this->assertArrayHasKey($column, $types, "{$definition->table}.$column is mapped but not in the descriptor");
}
$expected = ['int' => 'int', 'number' => 'float', 'float' => 'float', 'char' => 'string', 'text' => 'string'];
foreach ($definition->casts as $column => $cast) {
$this->assertSame($expected[$types[$column]], $cast, "{$definition->table}.$column cast does not match its column type {$types[$column]}");
}
}
}Run: <TEST_CMD> --filter definitions_match_schema_test
Expected: PASS (16 cases). A failure names the table and column that drifted.
- Step 7b: Typed reads through
entity()—table_bindingsandtyped_query(route C)
Decision (2026-10-02): queries keep using the framework’s query builder, bound to a dedicated table with entity(), and come back as the real entity class, exactly as an Item does. Where the pieces come from:
MiddagItemQueryBuilder::entity(string $class)is a core method (middag-php-core/src/Persistence/QueryEngine/MiddagItemQueryBuilder.php, also exposed by thelocal_middag\base\persistence\query\query_builderfacade). It looks the class up inTableRegistry(Middag\Core\Domain\Item\Type\TableRegistry/TableDescriptor(entityClass, table, metaTable)), binds the query to that table, sets the domain class, and resolves the persistence scope from the first namespace segment of the class (local_helico). If the class has no registered descriptor it silently falls back to the defaulthelico_itemsquery — which is why registration must be complete (tested below).- How an
Itemis typed today:TypeLoaderscans the plugin’sItemsubclasses at boot (#[ItemType]attribute, else theTYPEconstant) intoItemTypes; eachhelico_itemsrow has atypecolumn;ItemMapper::dbToDomainreads it, callsItemTypes::classFor($type)and constructs the entity with the metadata. The executor receives the domain class but ignores it. A dedicated table has notype, so the class must come from the binding instead: that is the missing linktyped_queryadds.
table_bindings is the single list entity class → definition; typed_query binds each in TableRegistry and in its own map, validates the builder, runs it through the existing executor in asStdClass() mode and maps each row with table_row_hydrator (the same hydrator the repositories use, so every path returns identical entities). Registration runs in platform_extension::boot() (this extension reports isEnabled() === true, so it always boots; do not move it to an extension that can be disabled, where boot() silently never runs).
tests/base/persistence/typed_query_test.php:
<?php
declare(strict_types=1);
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use InvalidArgumentException;
use LogicException;
use local_helico\extensions\activity\response\entity\response;
use local_helico\extensions\engine\algorithm\entity\slot;
use local_helico\extensions\engine\plan\entity\student_plan;
use Middag\Core\Domain\Item\Type\TableRegistry;
use Middag\Core\Persistence\Predicate\Comparison;
use Middag\Core\Persistence\Predicate\Enum\ComparisonOperator;
use Middag\Core\Persistence\Predicate\Enum\LogicalOperator;
use Middag\Core\Persistence\Predicate\Logical;
use Middag\Core\Persistence\Predicate\Parameter;
use Middag\Core\Persistence\QueryEngine\MiddagItemQueryBuilder;
use Middag\Framework\Shared\Enum\Operator;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class typed_query_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
table_bindings::register_all();
}
private function response(int $session, int $question, string $answer, int $correct, int $sort, ?string $category = null): int
{
global $DB;
return (int) $DB->insert_record('helico_response', (object) [
'sessionid' => $session, 'questionid' => $question, 'answer' => $answer, 'correct' => $correct,
'sortorder' => $sort, 'category' => $category, 'timecreated' => 1, 'timemodified' => 1,
]);
}
public function test_every_migrated_entity_is_bound_and_entity_targets_its_table(): void
{
foreach (table_bindings::all() as $class => $definition) {
$this->assertTrue(TableRegistry::has($class), "$class is not in TableRegistry");
$builder = MiddagItemQueryBuilder::make()->entity($class);
$this->assertSame($definition->table, $builder->getTable(), "$class: entity() fell back to the EAV table");
$this->assertNull($builder->getMetaTable());
}
$this->assertCount(16, table_bindings::all());
}
public function test_register_all_is_idempotent_and_platform_extension_boot_calls_it(): void
{
table_bindings::register_all();
table_bindings::register_all();
$this->assertTrue(typed_query::is_bound(response::class));
$boot = (string) file_get_contents(__DIR__ . '/../../../classes/extensions/platform/platform_extension.php');
$this->assertStringContainsString('table_bindings::register_all()', $boot, 'platform_extension::boot() must register the bindings');
}
public function test_entity_query_comes_back_as_the_real_typed_entity(): void
{
$this->response(3, 11, 'V', 1, 2);
$second = $this->response(3, 12, 'F', 0, 1);
$this->response(4, 99, 'V', 1, 1);
$result = typed_query::execute(
MiddagItemQueryBuilder::make()->entity(response::class)->where('sessionid', Operator::Eq, 3)->orderBy('sortorder ASC'),
);
$this->assertCount(2, $result->items());
$this->assertContainsOnlyInstancesOf(response::class, $result->items());
$first = $result->items()[0];
$this->assertSame($second, $first->getId());
$this->assertSame(12, $first->get_question_id());
$this->assertSame(3, $first->get_session_id());
$this->assertSame('recorded', $first->getStatus());
$this->assertInstanceOf(\Middag\Core\Domain\Item\Item::class, $first);
}
public function test_the_builder_features_keep_working_and_stay_typed(): void
{
for ($i = 1; $i <= 4; ++$i) {
$this->response($i % 2 === 0 ? 4 : 3, $i, 'V', $i % 2, $i, $i === 1 ? 'direito' : null);
}
$q = fn () => MiddagItemQueryBuilder::make()->entity(response::class);
$this->assertCount(4, typed_query::execute($q()->whereIn('sessionid', [3, 4]))->items());
$this->assertCount(3, typed_query::execute($q()->where('category', Operator::Is, null))->items());
$this->assertCount(2, typed_query::execute($q()->where('answer', Operator::Like, 'V%')->where('correct', Operator::Eq, 1))->items());
$or = typed_query::execute($q()->whereNode(new Logical(LogicalOperator::Or, [
new Comparison('questionid', ComparisonOperator::Equals, [Parameter::int(1)]),
new Comparison('sessionid', ComparisonOperator::Equals, [Parameter::int(4)]),
])));
$this->assertCount(3, $or->items());
$page = typed_query::execute($q()->orderBy('id ASC')->paginate(1, 3));
$this->assertCount(1, $page->items());
$this->assertSame(4, $page->total());
$this->assertContainsOnlyInstancesOf(response::class, $page->items());
}
public function test_columns_named_like_reserved_words_work(): void
{
global $DB;
$DB->insert_record('helico_slot', (object) [
'studentplanid' => 2, 'uuid' => 'u-1', 'blockref' => 'B1', 'slottype' => 'guided_study', 'slotstatus' => 'completed',
'scope' => '{"a":1}', 'context' => '{"b":2}', 'result' => '{"ok":true}', 'action' => 'go', 'label' => 'Estudo', 'timecreated' => 1, 'timemodified' => 1,
]);
$q = fn () => MiddagItemQueryBuilder::make()->entity(slot::class);
$this->assertCount(1, typed_query::execute($q()->where('scope', Operator::Eq, '{"a":1}'))->items());
$this->assertCount(1, typed_query::execute($q()->where('result', Operator::Like, '%ok%'))->items());
$this->assertSame('{"a":1}', typed_query::execute($q()->where('label', Operator::Eq, 'Estudo'))->first()->get_scope());
}
public function test_it_refuses_what_the_builder_would_run_or_silently_ignore(): void
{
$b = fn () => MiddagItemQueryBuilder::make()->entity(response::class);
$bad = [
'whereMeta (no meta table: the builder answers with an empty result)' => $b()->whereMeta('answer', Operator::Eq, 'V'),
'withMetadata' => $b()->withMetadata(['answer']),
'the EAV discriminator column' => $b()->where('type', Operator::Eq, 'response'),
'an unknown column' => $b()->where('nope', Operator::Eq, 1),
'= NULL' => $b()->where('category', Operator::Eq, null),
'<> NULL' => $b()->where('category', Operator::Neq, null),
'a select list with an expression' => $b()->select(['id, (SELECT 1) AS x']),
'an unknown select column' => $b()->select(['id', 'nope']),
'a sort by an expression' => $b()->orderBy('id DESC, (SELECT 1)'),
'a sort by an unknown column' => $b()->orderBy('nope ASC'),
];
foreach ($bad as $label => $builder) {
try {
typed_query::execute($builder);
$this->fail("expected InvalidArgumentException for: $label");
} catch (InvalidArgumentException) {
$this->addToAssertionCount(1);
}
}
}
public function test_an_old_style_query_that_did_not_bind_the_table_is_refused_not_served_stale(): void
{
$this->expectException(LogicException::class);
typed_query::execute(MiddagItemQueryBuilder::make()->domain(response::class)->where('type', Operator::Eq, 'response'));
}
public function test_projection_leaves_the_key_absent(): void
{
$this->response(3, 11, 'resposta longa', 1, 1);
$light = typed_query::execute(MiddagItemQueryBuilder::make()->entity(response::class)->select(['id', 'sessionid']))->first();
$this->assertFalse($light->hasMeta('answer'), 'a skipped column is absent, not a false null');
$this->assertSame(3, $light->get_session_id());
}
public function test_an_eav_entity_still_goes_through_the_unchanged_path(): void
{
$result = typed_query::execute(
MiddagItemQueryBuilder::make()->where('type', Operator::Eq, student_plan::TYPE)->domain(student_plan::class)->where('status', Operator::Eq, 'no-such-status'),
);
$this->assertTrue($result->isEmpty());
}
}Run: <TEST_CMD> --filter typed_query_test
Expected: FAIL (Class ...table_bindings not found).
classes/base/persistence/table_bindings.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use local_helico\extensions\activity\assessment\exam_assign_sync\entity\exam_assign_link;
use local_helico\extensions\activity\assessment\exam_correction\entity\criterion_score;
use local_helico\extensions\activity\assessment\exam_correction\entity\exam_correction;
use local_helico\extensions\activity\assessment\exam_submission\entity\exam_submission;
use local_helico\extensions\activity\productive\artifact_versioning\entity\artifact_version;
use local_helico\extensions\activity\productive\notebook_annotation\entity\notebook_annotation;
use local_helico\extensions\activity\productive\notebook_artifact\entity\notebook_artifact;
use local_helico\extensions\activity\response\entity\response;
use local_helico\extensions\activity\result\entity\result;
use local_helico\extensions\content\base\snapshot\entity\unit_snapshot;
use local_helico\extensions\engine\algorithm\entity\lock_dependency_entity;
use local_helico\extensions\engine\algorithm\entity\slot;
use local_helico\extensions\engine\algorithm\entity\slot_scope_ref_entity;
use local_helico\extensions\engine\session\entity\session;
use local_helico\extensions\metrics\classification\entity\classification;
use local_helico\extensions\metrics\report\entity\report;
/**
* Entity class => table definition, for every type stored in a dedicated table.
*/
final class table_bindings
{
/**
* @return array<class-string, item_table_definition>
*/
public static function all(): array
{
return [
response::class => item_table_definitions::response(),
result::class => item_table_definitions::result(),
classification::class => item_table_definitions::classification(),
report::class => item_table_definitions::report(),
exam_submission::class => item_table_definitions::exam_submission(),
exam_assign_link::class => item_table_definitions::exam_assign_link(),
exam_correction::class => item_table_definitions::exam_correction(),
criterion_score::class => item_table_definitions::criterion_score(),
slot::class => item_table_definitions::slot(),
slot_scope_ref_entity::class => item_table_definitions::slot_scope_ref(),
lock_dependency_entity::class => item_table_definitions::slot_lock(),
notebook_artifact::class => item_table_definitions::notebook_artifact(),
notebook_annotation::class => item_table_definitions::notebook_annotation(),
artifact_version::class => item_table_definitions::notebook_version(),
session::class => item_table_definitions::session(),
unit_snapshot::class => item_table_definitions::unit_snapshot(),
];
}
/**
* Idempotent: registers every binding in the core `TableRegistry` and in {@see typed_query}.
*/
public static function register_all(): void
{
foreach (self::all() as $class => $definition) {
typed_query::bind($class, $definition);
}
}
}classes/base/persistence/typed_query.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use InvalidArgumentException;
use LogicException;
use local_middag\base\facade\query_executor;
use local_middag\base\persistence\query\result;
use Middag\Core\Domain\Item\Type\TableDescriptor;
use Middag\Core\Domain\Item\Type\TableRegistry;
use Middag\Core\Persistence\QueryEngine\MiddagItemQueryBuilder;
use Middag\Core\Persistence\QueryEngine\Result as CoreResult;
use Middag\Framework\Shared\Enum\Operator;
/**
* Runs a `MiddagItemQueryBuilder` bound to a dedicated table with `entity()` and returns the
* **real entity class**, the way an `Item` comes back from `helico_items`.
*
* The executor hydrates through `ItemMapper`, which reads the row's `type` column and ignores the
* domain class; a dedicated table has no `type`. This wrapper keeps the executor for everything else
* (SQL, scope, paging, total) and replaces only the hydration: rows come back as `stdClass` and each is
* mapped by {@see table_row_hydrator} using the binding of the builder's domain class.
*
* It also refuses what the builder would run wrongly: `whereMeta`/`withMetadata` (no meta table),
* `= NULL`, unknown columns, and an unvalidated `select()`/`orderBy()`. A builder whose domain class is bound
* but whose table is not (the old `->domain()` style) is refused instead of silently reading the
* stale `helico_items` rows. Classes that are not bound (EAV types) take the unchanged path.
*/
final class typed_query
{
/** @var array<class-string, item_table_definition> */
private static array $bindings = [];
/**
* @param class-string $entity_class
*/
public static function bind(string $entity_class, item_table_definition $definition): void
{
TableRegistry::register(new TableDescriptor($entity_class, $definition->table, null));
self::$bindings[$entity_class] = $definition;
}
public static function is_bound(string $entity_class): bool
{
return isset(self::$bindings[$entity_class]);
}
/**
* `MiddagItemQueryBuilder::make()->entity($class)` after making sure the bindings exist.
*
* @param class-string $entity_class
*/
public static function for(string $entity_class): MiddagItemQueryBuilder
{
if (!self::is_bound($entity_class)) {
table_bindings::register_all();
}
if (!self::is_bound($entity_class)) {
throw new InvalidArgumentException("{$entity_class} is not stored in a dedicated table.");
}
return MiddagItemQueryBuilder::make()->entity($entity_class);
}
public static function execute(MiddagItemQueryBuilder $builder): result
{
$class = $builder->getDomainClass();
$definition = self::$bindings[$class] ?? null;
if ($definition === null) {
return query_executor::execute($builder);
}
self::validate($builder, $definition, $class);
$raw = query_executor::execute($builder->asStdClass());
$items = array_map(
static fn (object $row) => table_row_hydrator::hydrate($definition, $class, $row),
$raw->items(),
);
return result::wrap(new CoreResult(
items: $items,
total: $raw->total(),
page: $raw->page(),
perPage: $raw->perpage(),
isStdClass: false,
));
}
private static function validate(MiddagItemQueryBuilder $builder, item_table_definition $definition, string $class): void
{
if ($builder->getTable() !== $definition->table) {
throw new LogicException(sprintf(
'%s is stored in %s but the query targets %s: build it with ->entity(%s::class) after table_bindings::register_all().',
$class,
$definition->table,
$builder->getTable(),
$class,
));
}
if ($builder->getMetaWheres() !== [] || $builder->getMetadataKeys() !== []) {
throw new InvalidArgumentException("{$definition->table} has no metadata: whereMeta()/withMetadata() are not available.");
}
$columns = self::columns($definition);
foreach ($builder->getWheres() as $where) {
$field = (string) ($where['field'] ?? '');
if (!str_contains($field, '.') && !isset($columns[$field])) {
throw new InvalidArgumentException("{$field} is not a column of {$definition->table}.");
}
if (($where['value'] ?? null) === null && in_array($where['op'] ?? null, [Operator::Eq, Operator::Neq], true)) {
throw new InvalidArgumentException("Use Operator::Is / IsNot to compare {$field} with NULL: '= NULL' matches nothing.");
}
}
foreach ($builder->getSelect() ?? [] as $column) {
if (!isset($columns[$column])) {
throw new InvalidArgumentException("{$column} is not a column of {$definition->table}.");
}
}
$sort = $builder->getSort();
if ($sort !== null && $sort !== '') {
foreach (explode(',', $sort) as $term) {
if (preg_match('/^\s*(?:([a-z][a-z0-9_]*)\.)?([a-z][a-z0-9_]*)(?:\s+(?:ASC|DESC))?\s*$/i', $term, $m) !== 1) {
throw new InvalidArgumentException("Invalid sort term: {$term}");
}
$own = $m[1] === '' || strtolower($m[1]) === 'item';
if ($own && !isset($columns[$m[2]])) {
throw new InvalidArgumentException("{$m[2]} is not a column of {$definition->table}.");
}
}
}
}
/**
* @return array<string, string> column => descriptor type
*/
private static function columns(item_table_definition $definition): array
{
$descriptor = dedicated_schema::builder()->table($definition->table);
if ($descriptor === null) {
throw new LogicException("No #[Table] descriptor for {$definition->table}");
}
$columns = [];
foreach ($descriptor['columns'] as $column) {
$columns[$column['name']] = $column['type'];
}
return $columns;
}
}In classes/extensions/platform/platform_extension.php add (import local_helico\base\persistence\table_bindings):
#[Override]
public function boot(): void
{
// Entity class => dedicated table, so `->entity(response::class)` resolves to helico_response.
// Before parent::boot(): a failure there must not leave the entities unbound.
table_bindings::register_all();
parent::boot();
}Run: <TEST_CMD> --filter typed_query_test
Expected: PASS (9 tests). Notes verified in the dev probe: paginate is 0-based; Result exposes items(), first(), isEmpty(), total(), pages(), page(), perpage(); Parameter::int()/Parameter::string() exist; unqualified AST Comparison columns resolve to the main table (filter a joined table with the dotted where('b.col', …)).
- Step 8: Commit
git add classes/base/persistence classes/extensions/platform/platform_extension.php tests/base/persistence/table_row_hydrator_test.php tests/base/persistence/definitions_match_schema_test.php tests/base/persistence/typed_query_test.php
git commit -m "feat(persistence): add item->table definitions and row hydrator"Task 3b: Descriptor-driven row validator (#[AllowedValues] + #[Column])
The core ItemValidatorService no longer applies to these tables (they are not written through item_service). The column rules already live in the descriptors (#[Column]: type, length, notnull, default). This task reads them by reflection and adds one small attribute for allowed values, so a bad row fails with a per-column message before the query instead of as a database error (or, worse, a silently wrong value).
Design: the entities stay Item subclasses with meta getters (no properties), and the framework’s #[Column] is TARGET_CLASS only, so the descriptor classes (*_table) remain the single column source. Nothing is duplicated: DDL, drift guard and validation all read the same attributes.
Files:
- Create:
classes/base/persistence/attribute/allowed_values.php - Create:
classes/base/persistence/invalid_row_exception.php - Create:
classes/base/persistence/table_row_validator.php - Modify: the three descriptors
metrics_report_table.php,exam_submission_table.php,session_table.php(Task 2) — add#[AllowedValues] - Test:
tests/base/persistence/table_row_validator_test.php
Interfaces:
- Consumes:
dedicated_schema::classes()(Task 2), the#[Column]attributes of each descriptor. - Produces:
#[AllowedValues(string $column, string $enum)]— class-level, repeatable,$enumis a string-backed enum FQCN.table_row_validator::assert(string $table, array $columns, bool $partial = false): void—$tableis the table name without prefix concerns (helico_session); throwsinvalid_row_exceptionwith->errors(): array<string,string>(column => message).$partial = true(updates) skips the “required column missing” rule and validates only the columns passed.invalid_row_exception extends \InvalidArgumentException.
Rules, per column present in $columns (id, timecreated, timemodified are managed by the repository and accepted as ints):
- unknown column →
unknown column; nullon anotnullcolumn that has no default →required; on insert (not partial) a missingnotnullcolumn without default and withoutsequence→required;intcolumn: value must beintor an integer-like numeric string;number→ numeric;char→ string andstrlen(mb) ≤length;text→ string;#[AllowedValues]column: value must equal a->valueof the enum (nullis left to rule 2).
- Step 1: Write the failing test
tests/base/persistence/table_row_validator_test.php:
<?php
declare(strict_types=1);
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class table_row_validator_test extends advanced_testcase
{
private function errors(array $columns, bool $partial = false): array
{
try {
table_row_validator::assert('helico_session', $columns, $partial);
} catch (invalid_row_exception $e) {
return $e->errors();
}
return [];
}
public function test_valid_row_passes(): void
{
$this->assertSame([], $this->errors(['slotid' => 5, 'userid' => 8, 'sessionstatus' => 'paused', 'timespent' => 10]));
}
public function test_required_column_missing_on_insert(): void
{
$this->assertArrayHasKey('slotid', $this->errors(['userid' => 8]));
}
public function test_partial_update_does_not_require_missing_columns(): void
{
$this->assertSame([], $this->errors(['sessionstatus' => 'completed'], true));
}
public function test_null_on_notnull_column_fails_even_when_partial(): void
{
$this->assertArrayHasKey('slotid', $this->errors(['slotid' => null], true));
}
public function test_value_outside_enum_is_rejected(): void
{
$errors = $this->errors(['slotid' => 5, 'sessionstatus' => 'xyz']);
$this->assertArrayHasKey('sessionstatus', $errors);
$this->assertStringContainsString('xyz', $errors['sessionstatus']);
}
public function test_wrong_type_is_rejected(): void
{
$this->assertArrayHasKey('slotid', $this->errors(['slotid' => 'abc']));
$this->assertSame([], $this->errors(['slotid' => '12']), 'integer-like strings are accepted');
}
public function test_char_longer_than_column_is_rejected(): void
{
$this->assertArrayHasKey('sessionstatus', $this->errors(['slotid' => 5, 'sessionstatus' => str_repeat('a', 21)]));
}
public function test_unknown_column_is_rejected(): void
{
$this->assertSame('unknown column', $this->errors(['slotid' => 5, 'nope' => 1])['nope']);
}
public function test_every_dedicated_table_is_known_to_the_validator(): void
{
foreach (dedicated_schema::table_names() as $table) {
// An empty partial row is valid for every table: proves the descriptor resolves.
table_row_validator::assert($table, [], true);
}
$this->assertTrue(true);
}
public function test_allowed_values_columns_exist_in_their_descriptor(): void
{
foreach (dedicated_schema::classes() as $class) {
$ref = new \ReflectionClass($class);
$columns = array_map(static fn($a) => $a->newInstance()->name, $ref->getAttributes(\Middag\Framework\Database\Attribute\Column::class));
foreach ($ref->getAttributes(attribute\allowed_values::class) as $a) {
$av = $a->newInstance();
$this->assertContains($av->column, $columns, "{$class}: #[AllowedValues] names a column that does not exist");
$this->assertTrue(enum_exists($av->enum) && is_subclass_of($av->enum, \BackedEnum::class), "{$class}: {$av->enum} is not a backed enum");
}
}
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter table_row_validator_test
Expected: FAIL (Class ...table_row_validator not found).
- Step 3: Implement the attribute, the exception and the validator
classes/base/persistence/attribute/allowed_values.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence\attribute;
defined('MOODLE_INTERNAL') || exit;
use Attribute;
/**
* Restricts a column of a dedicated table to the cases of a string-backed enum.
* Placed on the `*_table` descriptor next to the `#[Column]` it constrains.
*/
#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
final class allowed_values
{
/**
* @param class-string<\BackedEnum> $enum
*/
public function __construct(
public readonly string $column,
public readonly string $enum,
) {}
}classes/base/persistence/invalid_row_exception.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
final class invalid_row_exception extends \InvalidArgumentException
{
/**
* @param array<string, string> $errors column => message
*/
public function __construct(private readonly string $table, private readonly array $errors)
{
$parts = [];
foreach ($errors as $column => $message) {
$parts[] = "{$column}: {$message}";
}
parent::__construct("Invalid row for {$table}: " . implode('; ', $parts));
}
/**
* @return array<string, string>
*/
public function errors(): array
{
return $this->errors;
}
public function table(): string
{
return $this->table;
}
}classes/base/persistence/table_row_validator.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\attribute\allowed_values;
use Middag\Framework\Database\Attribute\Column;
use Middag\Framework\Database\Attribute\Table;
use ReflectionClass;
/**
* Validates a row against the `#[Column]` / `#[AllowedValues]` attributes of its table descriptor.
*/
final class table_row_validator
{
/** Managed by the repositories. */
private const MANAGED = ['id', 'timecreated', 'timemodified'];
/** @var array<string, array{columns: array<string, Column>, enums: array<string, class-string<\BackedEnum>>}>|null */
private static ?array $specs = null;
/**
* @param array<string, mixed> $columns
*
* @throws invalid_row_exception
*/
public static function assert(string $table, array $columns, bool $partial = false): void
{
$spec = self::specs()[$table] ?? throw new \InvalidArgumentException("No descriptor for table {$table}");
$errors = [];
foreach ($columns as $name => $value) {
if (in_array($name, self::MANAGED, true)) {
continue;
}
$column = $spec['columns'][$name] ?? null;
if ($column === null) {
$errors[$name] = 'unknown column';
continue;
}
$message = self::check_value($column, $value, $spec['enums'][$name] ?? null);
if ($message !== null) {
$errors[$name] = $message;
}
}
if (!$partial) {
foreach ($spec['columns'] as $name => $column) {
if ($column->notnull && !$column->sequence && $column->default === null && !in_array($name, self::MANAGED, true)
&& !array_key_exists($name, $columns)) {
$errors[$name] = 'required';
}
}
}
if ($errors !== []) {
throw new invalid_row_exception($table, $errors);
}
}
/**
* @param class-string<\BackedEnum>|null $enum
*/
private static function check_value(Column $column, mixed $value, ?string $enum): ?string
{
if ($value === null) {
return $column->notnull && $column->default === null ? 'required' : null;
}
$problem = match ($column->type) {
'int' => (is_int($value) || (is_string($value) && preg_match('/^-?\d+$/', $value) === 1)) ? null : 'must be an integer',
'number' => is_numeric($value) ? null : 'must be numeric',
'char' => !is_string($value) ? 'must be a string'
: (($column->length !== null && mb_strlen($value) > $column->length) ? "longer than {$column->length} characters" : null),
'text' => is_string($value) ? null : 'must be a string',
default => null,
};
if ($problem !== null) {
return $problem;
}
if ($enum !== null) {
$allowed = array_map(static fn(\BackedEnum $c) => (string) $c->value, $enum::cases());
if (!in_array((string) $value, $allowed, true)) {
return 'value "' . (string) $value . '" not in [' . implode(', ', $allowed) . ']';
}
}
return null;
}
/**
* @return array<string, array{columns: array<string, Column>, enums: array<string, class-string<\BackedEnum>>}>
*/
private static function specs(): array
{
if (self::$specs !== null) {
return self::$specs;
}
$specs = [];
foreach (dedicated_schema::classes() as $class) {
$ref = new ReflectionClass($class);
$table = $ref->getAttributes(Table::class)[0]->newInstance()->name;
$columns = [];
foreach ($ref->getAttributes(Column::class) as $a) {
$c = $a->newInstance();
$columns[$c->name] = $c;
}
$enums = [];
foreach ($ref->getAttributes(allowed_values::class) as $a) {
$av = $a->newInstance();
$enums[$av->column] = $av->enum;
}
$specs[$table] = ['columns' => $columns, 'enums' => $enums];
}
return self::$specs = $specs;
}
}- Step 4: Annotate the descriptors
Only columns with a real backed enum whose values the code already writes. Add above the matching #[Column] block (imports: use local_helico\base\persistence\attribute\allowed_values; plus the enum):
// session_table.php
#[allowed_values('sessionstatus', \local_helico\extensions\engine\enum\session_status::class)]
// metrics_report_table.php
#[allowed_values('scope', \local_helico\extensions\metrics\report\enums\report_scope::class)]
// exam_submission_table.php
#[allowed_values('correctionstatus', \local_helico\extensions\activity\assessment\exam_submission\enums\correction_status::class)]Do not annotate slot.slotstatus, slot.slottype, notebook_artifact.artifactstatus/visibilityscope, exam_correction state or the metrics_report.status column until Task 16 Step 3b lists their distinct dev values: an enum narrower than the data the code writes would turn a working save into an exception. Add each one only after that query shows the values are all inside the enum.
- Step 5: Run to verify it passes
Run: <TEST_CMD> --filter table_row_validator_test
Expected: PASS (10 tests).
- Step 6: Commit
git add classes/base/persistence tests/base/persistence/table_row_validator_test.php
git commit -m "feat(persistence): descriptor-driven row validator with allowed-values attribute"Every repository insert()/update() in Tasks 5–14 (already wired in their code blocks below) calls table_row_validator::assert(self::TABLE, $columns[, partial: true]) before the $DB write, and the guard test in Task 15 Step 6d fails the build if a repository writes without it (plus a behavioural rejection test in Task 13). The migrator (Task 4) does not validate: it copies existing rows verbatim.
Task 4: Generic EAV→table migrator (batched, idempotent, skips orphans)
Files:
- Create:
classes/base/persistence/item_table_migrator.php - Create:
classes/base/persistence/migration/migration_2026100201_eav_to_tables.php - Create:
classes/base/persistence/migration/session_data_copier.php - Modify:
db/upgrade.php(data step) - Create:
cli/migrate_items_to_tables.php - Test:
tests/base/persistence/item_table_migrator_test.php
Interfaces:
-
Consumes:
item_table_definition,table_row_hydrator::row_from_meta()(Task 3). -
Produces:
item_table_migrator::migrate(item_table_definition $def, int $batch_size = 500, bool $dry_run = false): array{migrated:int, skipped_orphans:int, already:int}. -
Step 1: Write the failing test
<?php
declare(strict_types=1);
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class item_table_migrator_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
/**
* @param array<string, mixed> $extra extra `helico_items` columns (userid, description, sortorder, idnumber...)
*/
private function make_item(string $type, ?int $parent, array $meta, string $status = 'recorded', array $extra = []): int
{
global $DB;
$id = $DB->insert_record('helico_items', (object) ($extra + [
'type' => $type, 'parent' => $parent, 'status' => $status,
'timecreated' => 100, 'timemodified' => 100, 'sortorder' => 0, 'visible' => 1, 'descriptionformat' => 0,
]));
foreach ($meta as $key => $value) {
$DB->insert_record('helico_itemmeta', (object) ['itemid' => $id, 'meta_key' => $key, 'meta_value' => $value]);
}
return $id;
}
public function test_migrates_children_of_existing_parents_and_skips_orphans(): void
{
global $DB;
$session = $this->make_item('session', null, [], 'active');
$keep = $this->make_item('response', $session, ['session_id' => (string) $session, 'question_id' => '11', 'answer' => 'V', 'correct' => '1']);
$this->make_item('response', 999999, ['session_id' => '999999', 'answer' => 'F']);
$result = item_table_migrator::migrate(item_table_definitions::response());
$this->assertSame(1, $result['migrated']);
$this->assertSame(1, $result['skipped_orphans']);
$row = $DB->get_record('helico_response', ['id' => $keep], '*', MUST_EXIST);
$this->assertSame((int) $session, (int) $row->sessionid);
$this->assertSame(11, (int) $row->questionid);
$this->assertNull($row->cardid);
}
public function test_exam_submission_without_parent_is_migrated_not_skipped(): void
{
global $DB;
$with_slot_parent = $this->make_item('slot', null, [], 'active');
$legacy = $this->make_item('exam_submission', null, ['correction_status' => 'pending'], 'pending', ['userid' => 12, 'description' => 'texto']);
$normal = $this->make_item('exam_submission', $with_slot_parent, ['correction_status' => 'corrected', 'slot_id' => (string) $with_slot_parent], 'corrected', ['userid' => 13]);
$this->make_item('exam_submission', 999999, ['correction_status' => 'pending'], 'pending');
$result = item_table_migrator::migrate(item_table_definitions::exam_submission());
$this->assertSame(2, $result['migrated']);
$this->assertSame(1, $result['skipped_orphans']);
$legacy_row = $DB->get_record('helico_exam_submission', ['id' => $legacy], '*', MUST_EXIST);
$this->assertNull($legacy_row->slotid);
$this->assertSame(12, (int) $legacy_row->userid);
$this->assertSame('texto', $legacy_row->submittedtext);
$this->assertSame((int) $with_slot_parent, (int) $DB->get_field('helico_exam_submission', 'slotid', ['id' => $normal]));
}
public function test_correction_and_criteria_chain_migrates_with_description_and_sortorder(): void
{
global $DB;
$submission = $this->make_item('exam_submission', null, ['correction_status' => 'corrected'], 'corrected', ['userid' => 12]);
$correction = $this->make_item('exam_correction', $submission, ['submission_id' => (string) $submission, 'tutor_id' => '4', 'total_score' => '8.5', 'max_score' => '10', 'cached' => ''], 'corrected', ['userid' => 4, 'description' => '<p>ok</p>']);
$criterion = $this->make_item('criterion_score', $correction, ['criterion_name' => 'Clareza', 'score' => '1', 'max' => '2', 'sort_order' => '1'], 'recorded', ['sortorder' => 1]);
$m1 = item_table_migrator::migrate(item_table_definitions::exam_submission());
$m2 = item_table_migrator::migrate(item_table_definitions::exam_correction());
$m3 = item_table_migrator::migrate(item_table_definitions::criterion_score());
$this->assertSame([1, 1, 1], [$m1['migrated'], $m2['migrated'], $m3['migrated']]);
$c = $DB->get_record('helico_exam_correction', ['id' => $correction], '*', MUST_EXIST);
$this->assertSame('<p>ok</p>', $c->feedbackhtml);
$this->assertSame((int) $submission, (int) $c->submissionid);
$this->assertSame(4, (int) $c->tutorid);
$this->assertNull($c->cached);
$k = $DB->get_record('helico_criterion_score', ['id' => $criterion], '*', MUST_EXIST);
$this->assertSame((int) $correction, (int) $k->correctionid);
$this->assertSame(1, (int) $k->sortorder);
$this->assertSame('Clareza', $k->criterionname);
}
public function test_slot_chain_keeps_status_and_label_and_skips_orphan_lock_edges(): void
{
global $DB;
$plan = $this->make_item('student_plan', null, [], 'active');
$slot = $this->make_item('slot', $plan, ['student_plan_id' => (string) $plan, 'uuid' => 'u-1', 'slot_status' => 'completed', 'slot_type' => 'guided_study', 'label' => 'Estudo', 'sort_order' => '3', 'scope' => '', 'lock_reason' => 'prerequisite'], 'completed', ['fullname' => 'Estudo']);
$upstream = $this->make_item('slot', $plan, ['student_plan_id' => (string) $plan, 'uuid' => 'u-2', 'slot_status' => 'not_started'], 'not_started');
$edge = $this->make_item('lock_dependency', $slot, ['depends_on_slot_id' => (string) $upstream, 'kind' => 'prerequisite', 'required_status' => 'completed'], 'active');
$this->make_item('lock_dependency', 999999, ['depends_on_slot_id' => (string) $upstream], 'active');
$slots = item_table_migrator::migrate(item_table_definitions::slot());
$locks = item_table_migrator::migrate(item_table_definitions::slot_lock());
$this->assertSame(2, $slots['migrated']);
$this->assertSame([1, 1], [$locks['migrated'], $locks['skipped_orphans']]);
$row = $DB->get_record('helico_slot', ['id' => $slot], '*', MUST_EXIST);
$this->assertSame('completed', $row->slotstatus);
$this->assertSame('Estudo', $row->label);
$this->assertSame(3, (int) $row->sortorder);
$this->assertNull($row->scope);
$this->assertSame('prerequisite', $row->lockreason);
$this->assertSame((int) $slot, (int) $DB->get_field('helico_slot_lock', 'slotid', ['id' => $edge]));
$this->assertSame((int) $upstream, (int) $DB->get_field('helico_slot_lock', 'dependsonslotid', ['id' => $edge]));
}
public function test_notebook_chain_moves_content_user_and_keeps_the_eav_enrolment_parent(): void
{
global $DB;
$enrolment = $this->make_item('enrolment', null, ['courseid' => '2'], 'active', ['userid' => 8]);
$artifact = $this->make_item('notebook_artifact', $enrolment, ['enrolment_id' => (string) $enrolment, 'unit_id' => '5', 'topic_id' => '7', 'slot_id' => '40', 'artifact_status' => 'published', 'visibility_scope' => 'notebook', 'editor_state_version' => '3', 'editor_state_json' => '{"root":{}}', 'last_interaction_at' => '100'], 'published', ['userid' => 8, 'description' => '<p>x</p>']);
$version = $this->make_item('artifact_version', $artifact, ['artifact_id' => (string) $artifact, 'version_number' => '1', 'change_reason' => 'submit', 'created_by' => '8'], 'archived', ['userid' => 8]);
$annotation = $this->make_item('notebook_annotation', $artifact, ['artifact_id' => (string) $artifact, 'annotation_key' => 'k1', 'x_pct' => '12.5', 'created_at' => '10'], 'active', ['userid' => 8, 'description' => 'nota']);
$this->make_item('notebook_artifact', 999999, ['unit_id' => '5'], 'draft', ['userid' => 8]);
$a = item_table_migrator::migrate(item_table_definitions::notebook_artifact());
$v = item_table_migrator::migrate(item_table_definitions::notebook_version());
$n = item_table_migrator::migrate(item_table_definitions::notebook_annotation());
$this->assertSame([1, 1], [$a['migrated'], $a['skipped_orphans']]);
$this->assertSame(1, $v['migrated']);
$this->assertSame(1, $n['migrated']);
$row = $DB->get_record('helico_notebook_artifact', ['id' => $artifact], '*', MUST_EXIST);
$this->assertSame((int) $enrolment, (int) $row->enrolmentid);
$this->assertSame(8, (int) $row->userid);
$this->assertSame('<p>x</p>', $row->contenthtml);
$this->assertSame('published', $row->artifactstatus);
$this->assertSame(3, (int) $row->editorstateversion);
$this->assertSame('lexical-json', $row->editorstateformat);
$this->assertSame((int) $artifact, (int) $DB->get_field('helico_notebook_version', 'artifactid', ['id' => $version]));
$this->assertSame(8, (int) $DB->get_field('helico_notebook_version', 'createdby', ['id' => $version]));
$this->assertSame('nota', $DB->get_field('helico_notebook_annotation', 'commenttext', ['id' => $annotation]));
$this->assertSame('12.5000', number_format((float) $DB->get_field('helico_notebook_annotation', 'xpct', ['id' => $annotation]), 4, '.', ''));
}
public function test_session_and_snapshot_move_payloads_status_and_the_session_data_split(): void
{
global $DB;
$slot = $this->make_item('slot', null, [], 'completed');
$plan = $this->make_item('study_plan', null, [], 'active');
$session = $this->make_item('session', $slot, ['slot_id' => (string) $slot, 'user_id' => '8', 'session_status' => 'completed', 'started_at' => '100', 'paused_at' => '', 'time_spent' => '33', 'data' => str_repeat('x', 200000)], 'draft', ['userid' => 8]);
$snapshot = $this->make_item('unit_snapshot', $plan, ['source_unit_id' => '96', 'source_version' => '1', 'snapshot_data' => '{"topics":[]}', 'content_hash' => 'abc', 'flashcard' => '[]'], 'active');
$s = item_table_migrator::migrate(item_table_definitions::session());
$u = item_table_migrator::migrate(item_table_definitions::unit_snapshot());
$this->assertSame([1, 1], [$s['migrated'], $u['migrated']]);
$row = $DB->get_record('helico_session', ['id' => $session], '*', MUST_EXIST);
$this->assertSame('completed', $row->sessionstatus, 'session_status wins over the unreliable items.status');
$this->assertFalse(property_exists($row, 'sessiondata'), 'the payload is not stored in helico_session');
$copied = \local_helico\base\persistence\migration\session_data_copier::copy();
$this->assertSame(1, $copied);
$this->assertSame(200000, strlen((string) $DB->get_field('helico_session_data', 'sessiondata', ['sessionid' => $session])));
$this->assertSame(0, \local_helico\base\persistence\migration\session_data_copier::copy(), 'a second copy is a no-op');
$this->assertSame(1, $DB->count_records('helico_session_data'));
$this->assertNull($row->pausedat);
$this->assertSame(33, (int) $row->timespent);
$this->assertSame(8, (int) $row->userid);
$this->assertSame((int) $slot, (int) $row->slotid);
$snap = $DB->get_record('helico_unit_snapshot', ['id' => $snapshot], '*', MUST_EXIST);
$this->assertSame((int) $plan, (int) $snap->studyplanid);
$this->assertSame(96, (int) $snap->unitid);
$this->assertSame('abc', $snap->contenthash);
}
public function test_second_run_is_a_noop(): void
{
global $DB;
$session = $this->make_item('session', null, [], 'active');
$this->make_item('response', $session, ['session_id' => (string) $session, 'answer' => 'V']);
item_table_migrator::migrate(item_table_definitions::response());
$second = item_table_migrator::migrate(item_table_definitions::response());
$this->assertSame(0, $second['migrated']);
$this->assertSame(1, $second['already']);
$this->assertSame(1, $DB->count_records('helico_response'));
}
public function test_sequence_is_reset_after_explicit_id_import(): void
{
global $DB;
$session = $this->make_item('session', null, [], 'active');
$this->make_item('response', $session, ['session_id' => (string) $session]);
$max_id = (int) $DB->get_field_sql('SELECT MAX(id) FROM {helico_items}');
item_table_migrator::migrate(item_table_definitions::response());
$new_id = $DB->insert_record('helico_response', (object) ['sessionid' => $session, 'timecreated' => 1, 'timemodified' => 1]);
$this->assertGreaterThan($max_id, $new_id);
}
public function test_dry_run_writes_nothing(): void
{
global $DB;
$session = $this->make_item('session', null, [], 'active');
$this->make_item('response', $session, ['session_id' => (string) $session]);
$result = item_table_migrator::migrate(item_table_definitions::response(), 500, true);
$this->assertSame(1, $result['migrated']);
$this->assertSame(0, $DB->count_records('helico_response'));
}
public function test_batches_cover_every_row(): void
{
global $DB;
$session = $this->make_item('session', null, [], 'active');
for ($i = 0; $i < 7; ++$i) {
$this->make_item('response', $session, ['session_id' => (string) $session, 'sort_order' => (string) $i]);
}
$result = item_table_migrator::migrate(item_table_definitions::response(), 3);
$this->assertSame(7, $result['migrated']);
$this->assertSame(7, $DB->count_records('helico_response'));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter item_table_migrator_test
Expected: FAIL (Class ... item_table_migrator not found).
- Step 3: Implement the migrator
classes/base/persistence/item_table_migrator.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence;
defined('MOODLE_INTERNAL') || exit;
use Throwable;
/**
* Copies one EAV item type into its dedicated table.
*
* Idempotent (already-present ids are counted and skipped), batched by item id
* (bounded memory), skips orphans (parent item no longer exists) and never
* throws on a bad row — the upgrade runs at container boot with `set -e`.
*/
final class item_table_migrator
{
/**
* @return array{migrated: int, skipped_orphans: int, already: int}
*/
public static function migrate(item_table_definition $def, int $batch_size = 500, bool $dry_run = false): array
{
global $DB;
$counts = ['migrated' => 0, 'skipped_orphans' => 0, 'already' => 0];
$last_id = 0;
do {
$items = $DB->get_records_sql(
'SELECT i.*
FROM {helico_items} i
WHERE i.type = :type AND i.id > :last
ORDER BY i.id ASC',
['type' => $def->type, 'last' => $last_id],
0,
$batch_size,
);
if ($items === []) {
break;
}
$ids = array_map('intval', array_keys($items));
$last_id = max($ids);
[$insql, $params] = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'id');
$metas = [];
foreach ($DB->get_recordset_select('helico_itemmeta', "itemid {$insql}", $params, 'itemid', 'itemid, meta_key, meta_value') as $m) {
$metas[(int) $m->itemid][(string) $m->meta_key] = $m->meta_value;
}
$existing = $DB->get_fieldset_select($def->table, 'id', "id {$insql}", $params);
$existing = array_flip(array_map('intval', $existing));
[$pinsql, $pparams] = $DB->get_in_or_equal(
array_values(array_unique(array_filter(array_map(static fn ($i) => (int) $i->parent, $items)))) ?: [0],
SQL_PARAMS_NAMED,
'par',
);
$parents = array_flip(array_map('intval', $DB->get_fieldset_select('helico_items', 'id', "id {$pinsql}", $pparams)));
foreach ($items as $item) {
$id = (int) $item->id;
if (isset($existing[$id])) {
++$counts['already'];
continue;
}
$is_orphan = $item->parent !== null
? !isset($parents[(int) $item->parent])
: $def->parent_required;
if ($is_orphan) {
++$counts['skipped_orphans'];
continue;
}
if (!$dry_run) {
try {
$DB->import_record($def->table, table_row_hydrator::row_from_meta($def, $item, $metas[$id] ?? []));
} catch (Throwable $e) {
debugging(sprintf('[migrate %s] id %d failed: %s', $def->type, $id, $e->getMessage()));
continue;
}
}
++$counts['migrated'];
}
} while (count($items) === $batch_size);
if (!$dry_run && $counts['migrated'] > 0) {
$DB->get_manager()->reset_sequence(new \xmldb_table($def->table));
}
return $counts;
}
}- Step 4: Run the tests
Run: <TEST_CMD> --filter item_table_migrator_test
Expected: PASS (5 tests). If test_sequence_is_reset_after_explicit_id_import fails on pgsql, confirm reset_sequence is invoked with an xmldb_table and that import_record is used (not insert_record with an id).
- Step 5: Wrap the copy as a framework migration and run it from
upgrade.php
MigrationExecutor::apply() only runs migrations whose version() is greater than the stored version, which is the framework’s versioning mechanism (the one local_middag uses). DataOperationsInterface has no read API, so up() calls the migrator directly and ignores its $data argument.
classes/base/persistence/migration/migration_2026100201_eav_to_tables.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence\migration;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\item_table_migrator;
use Middag\Core\Persistence\Migration\Contract\DataOperationsInterface;
use Middag\Core\Persistence\Migration\Contract\MigrationInterface;
use Middag\Framework\Database\Contract\SchemaBuilderAdapterInterface;
/**
* Copies the Phase 1 EAV item types into their dedicated tables.
*/
final class migration_2026100201_eav_to_tables implements MigrationInterface
{
public const VERSION = 2026100201;
public function version(): int
{
return self::VERSION;
}
public function up(SchemaBuilderAdapterInterface $schema, DataOperationsInterface $data): void
{
foreach (item_table_definitions::all() as $definition) {
$result = item_table_migrator::migrate($definition);
mtrace(sprintf(
'local_helico: %s -> %s migrated=%d already=%d orphans_skipped=%d',
$definition->type,
$definition->table,
$result['migrated'],
$result['already'],
$result['skipped_orphans'],
));
}
$copied = session_data_copier::copy();
mtrace(sprintf('local_helico: session data -> helico_session_data copied=%d', $copied));
}
}classes/base/persistence/migration/session_data_copier.php — the session payload is copied with one set-based INSERT … SELECT (text to text, no casts, so a bad value cannot abort it), only for sessions that were migrated and only if no payload row exists yet (idempotent):
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\base\persistence\migration;
defined('MOODLE_INTERNAL') || exit;
/**
* Copies the EAV `session.data` meta into `helico_session_data`.
*/
final class session_data_copier
{
/**
* @return int rows copied (rows that would be copied when $dry_run)
*/
public static function copy(bool $dry_run = false): int
{
global $DB;
// A real copy requires the migrated session row; a dry run (nothing migrated yet)
// uses the migrator's own eligibility rule: the session's parent must still exist.
$eligible = $dry_run
? 'i.parent IS NOT NULL AND EXISTS (SELECT 1 FROM {helico_items} p WHERE p.id = i.parent)'
: 'EXISTS (SELECT 1 FROM {helico_session} s WHERE s.id = i.id)';
$from = "FROM {helico_items} i
JOIN {helico_itemmeta} m ON m.itemid = i.id AND m.meta_key = 'data'
WHERE i.type = 'session'
AND m.meta_value IS NOT NULL AND m.meta_value <> ''
AND {$eligible}
AND NOT EXISTS (SELECT 1 FROM {helico_session_data} d WHERE d.sessionid = i.id)";
$pending = (int) $DB->count_records_sql('SELECT COUNT(1) ' . $from);
if ($dry_run || $pending === 0) {
return $pending;
}
$DB->execute(
'INSERT INTO {helico_session_data} (sessionid, sessiondata, timecreated, timemodified)
SELECT i.id, m.meta_value, i.timecreated, i.timemodified ' . $from,
);
return $pending;
}
}In migration_2026100201_eav_to_tables.php add use local_helico\base\persistence\migration\session_data_copier; is not needed (same namespace). In db/upgrade.php add the imports
use local_helico\base\persistence\migration\migration_2026100201_eav_to_tables;
use Middag\Core\Adapter\Moodle\Persistence\MoodleDataOperations;
use Middag\Core\Persistence\Migration\MigrationExecutor;and, after the Task 2 block and before return true;:
if ($oldversion < 2026100201) {
core_php_time_limit::raise();
raise_memory_limit(MEMORY_EXTRA);
(new MigrationExecutor(new XmldbSchemaAdapter($dbman), new MoodleDataOperations($DB)))
->apply([new migration_2026100201_eav_to_tables()], (int) $oldversion);
upgrade_plugin_savepoint(true, 2026100201, 'local', 'helico');
}Add this test to item_table_migrator_test.php to pin the wrapper:
public function test_framework_migration_wrapper_runs_the_copy_once(): void
{
global $DB;
$session = $this->make_item('session', null, [], 'active');
$this->make_item('response', $session, ['session_id' => (string) $session, 'answer' => 'V']);
$executor = new \Middag\Core\Persistence\Migration\MigrationExecutor(
new \Middag\Moodle\Database\Schema\XmldbSchemaAdapter($DB->get_manager()),
new \Middag\Core\Adapter\Moodle\Persistence\MoodleDataOperations($DB),
);
$migration = new \local_helico\base\persistence\migration\migration_2026100201_eav_to_tables();
$this->expectOutputRegex('/response -> helico_response migrated=1/');
$this->assertSame(1, $executor->apply([$migration], 2026100200));
$this->assertSame(0, $executor->apply([$migration], 2026100201));
$this->assertSame(1, $DB->count_records('helico_response'));
}(beStrictAboutOutputDuringTests="true" in phpunit.xml is why the output is asserted with expectOutputRegex.)
- Step 6: Add the manual CLI with
--dry-run
cli/migrate_items_to_tables.php:
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
define('CLI_SCRIPT', true);
require(__DIR__ . '/../../../config.php');
require_once($CFG->libdir . '/clilib.php');
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\item_table_migrator;
[$options] = cli_get_params(['dry-run' => false, 'help' => false], ['h' => 'help']);
if ($options['help']) {
cli_writeln("Copies EAV items into the dedicated helico_* tables.\n --dry-run count only, write nothing");
exit(0);
}
foreach (item_table_definitions::all() as $definition) {
$result = item_table_migrator::migrate($definition, 500, (bool) $options['dry-run']);
cli_writeln(sprintf(
'%s -> %s migrated=%d already=%d orphans_skipped=%d%s',
$definition->type,
$definition->table,
$result['migrated'],
$result['already'],
$result['skipped_orphans'],
$options['dry-run'] ? ' (dry-run)' : '',
));
}
cli_writeln(sprintf(
'session data -> helico_session_data copied=%d%s',
\local_helico\base\persistence\migration\session_data_copier::copy((bool) $options['dry-run']),
$options['dry-run'] ? ' (dry-run)' : '',
));- Step 7: Commit
git add classes/base/persistence/item_table_migrator.php db/upgrade.php cli/migrate_items_to_tables.php tests/base/persistence/item_table_migrator_test.php
git commit -m "feat(persistence): add idempotent batched EAV->table migrator"Task 5: response repository and service switch
Files:
- Create:
classes/extensions/activity/response/repository/response_repository.php - Modify:
classes/extensions/activity/response/service/response_service.php - Test:
tests/extensions/activity/response/response_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::response(),table_row_hydrator::hydrate(). -
Produces
response_repositorywith:find_by_session(int $session_id): list<response>(ordered bysortorder)find_by_session_ids(array $session_ids): list<response>count_by_session(int $session_id, ?bool $correct = null): intinsert(array $data): int(datakeys = column names)insert_many(array $rows): voidfind_question_ids_by_session_ids(array $session_ids): list<int>delete_by_session_ids(array $session_ids): void
-
Step 1: Write the failing test
<?php
declare(strict_types=1);
namespace local_helico\extensions\activity\response;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\response\entity\response;
use local_helico\extensions\activity\response\repository\response_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class response_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_insert_and_find_by_session_orders_by_sortorder(): void
{
$repo = new response_repository();
$repo->insert(['sessionid' => 3, 'questionid' => 12, 'answer' => 'F', 'correct' => 0, 'sortorder' => 2]);
$repo->insert(['sessionid' => 3, 'questionid' => 11, 'answer' => 'V', 'correct' => 1, 'sortorder' => 1]);
$repo->insert(['sessionid' => 4, 'questionid' => 99, 'answer' => 'V', 'correct' => 1, 'sortorder' => 1]);
$found = $repo->find_by_session(3);
$this->assertCount(2, $found);
$this->assertContainsOnlyInstancesOf(response::class, $found);
$this->assertSame(11, $found[0]->get_question_id());
$this->assertSame(12, $found[1]->get_question_id());
}
public function test_count_by_session_filters_correct(): void
{
$repo = new response_repository();
$repo->insert_many([
['sessionid' => 3, 'questionid' => 1, 'correct' => 1],
['sessionid' => 3, 'questionid' => 2, 'correct' => 0],
['sessionid' => 3, 'questionid' => 3, 'correct' => 1],
]);
$this->assertSame(3, $repo->count_by_session(3));
$this->assertSame(2, $repo->count_by_session(3, true));
}
public function test_find_by_session_ids_handles_empty_and_many(): void
{
$repo = new response_repository();
$repo->insert(['sessionid' => 5, 'questionid' => 1]);
$repo->insert(['sessionid' => 6, 'questionid' => 2]);
$this->assertSame([], $repo->find_by_session_ids([]));
$this->assertCount(2, $repo->find_by_session_ids([5, 6]));
}
public function test_null_question_id_survives_round_trip(): void
{
$repo = new response_repository();
$repo->insert(['sessionid' => 7, 'cardid' => 40]);
$found = $repo->find_by_session(7)[0];
$this->assertNull($found->get_question_id());
$this->assertSame(40, $found->get_card_id());
}
public function test_delete_by_session_ids(): void
{
$repo = new response_repository();
$repo->insert(['sessionid' => 8, 'questionid' => 1]);
$repo->insert(['sessionid' => 9, 'questionid' => 1]);
$repo->delete_by_session_ids([8]);
$this->assertSame([], $repo->find_by_session(8));
$this->assertCount(1, $repo->find_by_session(9));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter response_repository_test
Expected: FAIL (Class ... response_repository not found).
- Step 3: Implement the repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\response\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\response\entity\response;
use stdClass;
/**
* Table access for `helico_response` (append-only answers).
*/
final class response_repository
{
private const TABLE = 'helico_response';
/**
* @return list<response>
*/
public function find_by_session(int $session_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['sessionid' => $session_id], 'sortorder ASC, id ASC'));
}
/**
* @param int[] $session_ids
*
* @return list<response>
*/
public function find_by_session_ids(array $session_ids): array
{
global $DB;
$session_ids = array_values(array_filter(array_map('intval', $session_ids), static fn (int $id): bool => $id > 0));
if ($session_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($session_ids, SQL_PARAMS_NAMED, 'sid');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "sessionid {$insql}", $params, 'sessionid ASC, sortorder ASC, id ASC'));
}
public function count_by_session(int $session_id, ?bool $correct = null): int
{
global $DB;
$conditions = ['sessionid' => $session_id];
if ($correct !== null) {
$conditions['correct'] = $correct ? 1 : 0;
}
return $DB->count_records(self::TABLE, $conditions);
}
/**
* @param array<string, mixed> $data column => value
*/
public function insert(array $data): int
{
global $DB;
return (int) $DB->insert_record(self::TABLE, $this->with_times($data));
}
/**
* @param list<array<string, mixed>> $rows
*/
public function insert_many(array $rows): void
{
global $DB;
if ($rows === []) {
return;
}
$DB->insert_records(self::TABLE, array_map(fn (array $r): stdClass => $this->with_times($r), $rows));
}
/**
* @param int[] $session_ids
*
* @return list<int>
*/
public function find_question_ids_by_session_ids(array $session_ids): array
{
global $DB;
$session_ids = array_values(array_filter(array_map('intval', $session_ids), static fn (int $id): bool => $id > 0));
if ($session_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($session_ids, SQL_PARAMS_NAMED, 'sid');
return array_map('intval', $DB->get_fieldset_sql(
"SELECT DISTINCT questionid FROM {" . self::TABLE . "} WHERE questionid IS NOT NULL AND sessionid {$insql}",
$params,
));
}
/**
* @param int[] $session_ids
*/
public function delete_by_session_ids(array $session_ids): void
{
global $DB;
$session_ids = array_values(array_filter(array_map('intval', $session_ids), static fn (int $id): bool => $id > 0));
if ($session_ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($session_ids, SQL_PARAMS_NAMED, 'sid');
$DB->delete_records_select(self::TABLE, "sessionid {$insql}", $params);
}
/**
* @param array<string, mixed> $data
*/
private function with_times(array $data): stdClass
{
$now = time();
$data += ['timecreated' => $now, 'timemodified' => $now];
return (object) $data;
}
/**
* @param array<int, stdClass> $records
*
* @return list<response>
*/
private function hydrate_all(array $records): array
{
$def = item_table_definitions::response();
return array_values(array_map(
static fn (stdClass $row): response => table_row_hydrator::hydrate($def, response::class, $row),
$records,
));
}
}- Step 4: Run the repository tests
Run: <TEST_CMD> --filter response_repository_test
Expected: PASS (5 tests).
- Step 5: Switch
response_serviceto the repository
Read classes/extensions/activity/response/service/response_service.php fully, then replace each persistence block following this mapping (method signatures and return shapes stay as in response_service_interface):
| Interface method | Replace the MiddagItemQueryBuilder / item_service block with |
|---|---|
find_by_session(int $session_id): array |
return $this->repository->find_by_session($session_id); |
find_by_session_ids(array $session_ids): array |
return $this->repository->find_by_session_ids($session_ids); |
count_correct_by_session |
return $this->repository->count_by_session($session_id, true); |
count_total_by_session |
return $this->repository->count_by_session($session_id); |
bulk_create(array $datas): void |
map each $data (existing keys session_id, question_id, card_id, unit_id, answer, correct, notsure, timems, sort_order, category) to a column array with table_row_hydrator::columns_from_meta(item_table_definitions::response(), $data) + ['sessionid' => (int) $data['session_id']], collect them in $rows, then $this->repository->insert_many($rows) |
find_question_ids_by_student_plan, find_question_keys_by_student_plan |
resolve the student plan’s session ids exactly as today (via slot_service/session_service), then call $this->repository->find_question_ids_by_session_ids($session_ids); for the _keys variant keep the existing key-building loop but iterate $this->repository->find_by_session_ids($session_ids) |
Constructor: add private readonly response_repository $repository and remove the ItemServiceInterface $item_service argument only if no remaining code in the class uses it (grep -n item_service response_service.php); if the container autowires by type, no registration change is needed.
Add this test in the same file as Step 1 to pin the service contract:
public function test_service_bulk_create_then_find(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\activity\response\contract\response_service_interface::class);
$service->bulk_create([
['session_id' => 20, 'question_id' => 1, 'answer' => 'V', 'correct' => 1, 'notsure' => 0, 'timems' => 900, 'sort_order' => 1],
['session_id' => 20, 'card_id' => 2, 'answer' => '1', 'correct' => 0, 'notsure' => 0, 'timems' => 400, 'sort_order' => 2],
]);
$found = $service->find_by_session(20);
$this->assertCount(2, $found);
$this->assertSame(1, $service->count_correct_by_session(20));
$this->assertSame(2, $service->count_total_by_session(20));
}(If middag::get is not the resolver in tests, use the same resolver the neighbouring tests use: grep -rn "middag::get" tests/extensions | head -3.)
- Step 6: Run the tests and the existing response consumers’ tests
Run: <TEST_CMD> --filter response
Expected: PASS.
- Step 7: Commit
git add classes/extensions/activity/response tests/extensions/activity/response
git commit -m "feat(activity): persist response in helico_response"Task 6: activity_result repository and service switch
Files:
- Create:
classes/extensions/activity/result/repository/result_repository.php - Modify:
classes/extensions/activity/result/service/result_service.php(extendsitem_service; overrides required, see Step 4) - Test:
tests/extensions/activity/result/result_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::result(),table_row_hydrator. -
Produces
result_repository:find_by_slot(int $slot_id): ?resultfind_by_session(int $session_id): ?resultfind_by_student_plan(int $student_plan_id): list<result>find_by_user_and_unit(int $user_id, int $unit_id): list<result>(join throughhelico_itemsis gone: useslotid→ session→ user; see Step 3 note)save(array $data, ?int $id = null): int(insert or update by id)delete_by_enrolment(int $enrolment_id): voidfind(int $id): ?result,delete(int $id): void(used by theitem_serviceoverrides)
-
Step 1: Write the failing test
<?php
declare(strict_types=1);
namespace local_helico\extensions\activity\result;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\result\entity\result;
use local_helico\extensions\activity\result\repository\result_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class result_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_save_insert_then_update(): void
{
$repo = new result_repository();
$id = $repo->save(['sessionid' => 3, 'slotid' => 10, 'studentplanid' => 2, 'enrolmentid' => 1, 'unitid' => 5,
'slottype' => 'vf', 'completionstatus' => 'completed', 'totalquestions' => 10, 'correctcount' => 7, 'notareal' => 7.0]);
$repo->save(['correctcount' => 8, 'notareal' => 8.0], $id);
$found = $repo->find_by_session(3);
$this->assertInstanceOf(result::class, $found);
$this->assertSame($id, $found->getId());
$this->assertSame($id, $repo->find_by_slot(10)->getId());
$this->assertSame(8, (int) $found->getMeta('correct_count'));
}
public function test_find_by_student_plan_returns_only_that_plan(): void
{
$repo = new result_repository();
$repo->save(['sessionid' => 1, 'studentplanid' => 2]);
$repo->save(['sessionid' => 2, 'studentplanid' => 2]);
$repo->save(['sessionid' => 3, 'studentplanid' => 9]);
$this->assertCount(2, $repo->find_by_student_plan(2));
}
public function test_missing_returns_null(): void
{
$repo = new result_repository();
$this->assertNull($repo->find_by_slot(404));
$this->assertNull($repo->find_by_session(404));
}
public function test_delete_by_enrolment(): void
{
$repo = new result_repository();
$repo->save(['sessionid' => 1, 'enrolmentid' => 7]);
$repo->save(['sessionid' => 2, 'enrolmentid' => 8]);
$repo->delete_by_enrolment(7);
$this->assertNull($repo->find_by_session(1));
$this->assertNotNull($repo->find_by_session(2));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter result_repository_test
Expected: FAIL (Class ... result_repository not found).
- Step 3: Implement the repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\result\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\result\entity\result;
use stdClass;
/**
* Table access for `helico_result`.
*/
final class result_repository
{
private const TABLE = 'helico_result';
public function find_by_slot(int $slot_id): ?result
{
global $DB;
return $this->hydrate_one($DB->get_records(self::TABLE, ['slotid' => $slot_id], 'id DESC', '*', 0, 1));
}
public function find_by_session(int $session_id): ?result
{
global $DB;
return $this->hydrate_one($DB->get_records(self::TABLE, ['sessionid' => $session_id], 'id DESC', '*', 0, 1));
}
/**
* @return list<result>
*/
public function find_by_student_plan(int $student_plan_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['studentplanid' => $student_plan_id], 'id ASC'));
}
/**
* Results of one user for one unit. The user is resolved from the session
* item (`helico_items.userid`), which stays EAV in Phase 1.
*
* @return list<result>
*/
public function find_by_user_and_unit(int $user_id, int $unit_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records_sql(
'SELECT r.*
FROM {' . self::TABLE . '} r
JOIN {helico_items} s ON s.id = r.sessionid
WHERE s.userid = :userid AND r.unitid = :unitid
ORDER BY r.id ASC',
['userid' => $user_id, 'unitid' => $unit_id],
));
}
/**
* Inserts, or updates when $id is given. Returns the row id.
*
* @param array<string, mixed> $data column => value
*/
public function save(array $data, ?int $id = null): int
{
global $DB;
$now = time();
if ($id === null) {
return (int) $DB->insert_record(self::TABLE, (object) ($data + ['timecreated' => $now, 'timemodified' => $now]));
}
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $data, partial: true);
$DB->update_record(self::TABLE, (object) ($data + ['id' => $id, 'timemodified' => $now]));
return $id;
}
public function delete_by_enrolment(int $enrolment_id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['enrolmentid' => $enrolment_id]);
}
/**
* @param array<int, stdClass> $records
*/
private function hydrate_one(array $records): ?result
{
$first = reset($records);
return $first === false ? null : table_row_hydrator::hydrate(item_table_definitions::result(), result::class, $first);
}
/**
* @param array<int, stdClass> $records
*
* @return list<result>
*/
private function hydrate_all(array $records): array
{
$def = item_table_definitions::result();
return array_values(array_map(
static fn (stdClass $row): result => table_row_hydrator::hydrate($def, result::class, $row),
$records,
));
}
}- Step 4: Run the repository tests
Run: <TEST_CMD> --filter result_repository_test
Expected: PASS (4 tests).
- Step 5: Switch
result_service
result_service extends item_service (:39) and overrides create()/update() (:46,:54). Read the whole file, then:
- Add
private readonly result_repository $repository(constructor argument; if the class cannot take a ctor argument because the parent ctor has 5 args — see the comment atnotebook_artifact_service.php:60-66— resolve lazily withprivate ?result_repository $repository = null; private function repository(): result_repository { return $this->repository ??= new result_repository(); }). record(result_dto $dto): result— keep the DTO→values logic; replace the finalcreate()/update()with$id = $this->repository()->save($columns, $existing?->getId());building$columnswithtable_row_hydrator::columns_from_meta(item_table_definitions::result(), $metadata) + ['sessionid' => $dto->session_id](where$metadatais the array the old code passed asitem_dtometadata), and return$this->repository()->find_by_session($dto->session_id).find_by_slot,find_by_session,find_by_student_plan,find_by_user_and_unit: delegate to the repository one-to-one (same names).result_serviceextendsitem_service, so, per the Global Constraints, replace the existingcreate()/update()overrides (:44-56) and adddelete()/find()overrides that route to the repository, exactly as in Task 9 Step 6 withitem_table_definitions::result()and aresult_repository(addfind(int $id): ?resultanddelete(int $id): voidtoresult_repository, each a one-line$DB->get_record/$DB->delete_recordsoverhelico_result). Without this, any caller still usingcreate()/update()/find()silently writes to or reads from the EAV tables.
- Step 6: Run result-related tests
Run: <TEST_CMD> --filter result
Expected: PASS.
- Step 7: Commit
git add classes/extensions/activity/result tests/extensions/activity/result/result_repository_test.php
git commit -m "feat(activity): persist activity_result in helico_result"Task 7: classification repository and service switch
Files:
- Create:
classes/extensions/metrics/classification/repository/classification_repository.php - Modify:
classes/extensions/metrics/classification/service/classification_service.php(blocks at:115,:190,:237-241andcreate()at:151) - Test:
tests/extensions/metrics/classification/classification_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::classification(),table_row_hydrator. -
Produces
classification_repository:find_by_plan_and_unit(int $student_plan_id, int $unit_id, ?int $as_of = null): list<classification>(orderedtimecreated ASC, id ASC)find_by_student_plan(int $student_plan_id, ?int $as_of = null): list<classification>find_by_submission(int $submission_id): ?classificationinsert(array $data): intupdate_score(int $id, float $score, string $level): voidfind(int $id): ?classificationdelete_by_student_plan_ids(array $ids): void
-
Step 1: Write the failing test
<?php
declare(strict_types=1);
namespace local_helico\extensions\metrics\classification;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\metrics\classification\entity\classification;
use local_helico\extensions\metrics\classification\repository\classification_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class classification_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_find_by_plan_and_unit_is_chronological_and_scoped(): void
{
$repo = new classification_repository();
$repo->insert(['studentplanid' => 2, 'unitid' => 5, 'level' => 'basico', 'score' => 40.0, 'timecreated' => 200]);
$repo->insert(['studentplanid' => 2, 'unitid' => 5, 'level' => 'avancado', 'score' => 90.0, 'timecreated' => 300]);
$repo->insert(['studentplanid' => 2, 'unitid' => 6, 'level' => 'basico', 'score' => 10.0, 'timecreated' => 250]);
$repo->insert(['studentplanid' => 3, 'unitid' => 5, 'level' => 'basico', 'score' => 10.0, 'timecreated' => 250]);
$found = $repo->find_by_plan_and_unit(2, 5);
$this->assertCount(2, $found);
$this->assertContainsOnlyInstancesOf(classification::class, $found);
$this->assertSame('basico', $found[0]->getStatus());
$this->assertSame('avancado', $found[1]->getStatus());
}
public function test_as_of_excludes_later_rows(): void
{
$repo = new classification_repository();
$repo->insert(['studentplanid' => 2, 'unitid' => 5, 'level' => 'basico', 'timecreated' => 200]);
$repo->insert(['studentplanid' => 2, 'unitid' => 5, 'level' => 'avancado', 'timecreated' => 300]);
$this->assertCount(1, $repo->find_by_plan_and_unit(2, 5, 250));
$this->assertCount(1, $repo->find_by_student_plan(2, 250));
}
public function test_update_score_changes_score_and_level(): void
{
$repo = new classification_repository();
$id = $repo->insert(['studentplanid' => 2, 'unitid' => 5, 'level' => 'basico', 'score' => 40.0]);
$repo->update_score($id, 85.5, 'intermediario');
$row = $repo->find($id);
$this->assertSame('intermediario', $row->getStatus());
}
public function test_find_by_submission(): void
{
$repo = new classification_repository();
$id = $repo->insert(['studentplanid' => 2, 'unitid' => 5, 'level' => 'basico', 'submissionid' => 77]);
$this->assertSame($id, $repo->find_by_submission(77)->getId());
$this->assertNull($repo->find_by_submission(78));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter classification_repository_test
Expected: FAIL (Class ... classification_repository not found).
- Step 3: Implement the repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\metrics\classification\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\metrics\classification\entity\classification;
use stdClass;
/**
* Table access for `helico_classification` (accumulative, analytical).
*/
final class classification_repository
{
private const TABLE = 'helico_classification';
/**
* @return list<classification>
*/
public function find_by_plan_and_unit(int $student_plan_id, int $unit_id, ?int $as_of = null): array
{
global $DB;
$where = 'studentplanid = :plan AND unitid = :unit';
$params = ['plan' => $student_plan_id, 'unit' => $unit_id];
if ($as_of !== null) {
$where .= ' AND timecreated <= :asof';
$params['asof'] = $as_of;
}
return $this->hydrate_all($DB->get_records_select(self::TABLE, $where, $params, 'timecreated ASC, id ASC'));
}
/**
* @return list<classification>
*/
public function find_by_student_plan(int $student_plan_id, ?int $as_of = null): array
{
global $DB;
$where = 'studentplanid = :plan';
$params = ['plan' => $student_plan_id];
if ($as_of !== null) {
$where .= ' AND timecreated <= :asof';
$params['asof'] = $as_of;
}
return $this->hydrate_all($DB->get_records_select(self::TABLE, $where, $params, 'timecreated ASC, id ASC'));
}
public function find_by_submission(int $submission_id): ?classification
{
global $DB;
$records = $DB->get_records(self::TABLE, ['submissionid' => $submission_id], 'id DESC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
public function find(int $id): ?classification
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
/**
* @param array<string, mixed> $data column => value
*/
public function insert(array $data): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $data);
return (int) $DB->insert_record(self::TABLE, (object) ($data + ['timecreated' => $now, 'timemodified' => $now]));
}
public function update_score(int $id, float $score, string $level): void
{
global $DB;
$DB->update_record(self::TABLE, (object) ['id' => $id, 'score' => $score, 'level' => $level, 'timemodified' => time()]);
}
/**
* @param int[] $ids
*/
public function delete_by_student_plan_ids(array $ids): void
{
global $DB;
$ids = array_values(array_filter(array_map('intval', $ids), static fn (int $id): bool => $id > 0));
if ($ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'pid');
$DB->delete_records_select(self::TABLE, "studentplanid {$insql}", $params);
}
private function hydrate(stdClass $row): classification
{
return table_row_hydrator::hydrate(item_table_definitions::classification(), classification::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<classification>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): classification => $this->hydrate($row), $records));
}
}- Step 4: Run the repository tests
Run: <TEST_CMD> --filter classification_repository_test
Expected: PASS (4 tests).
- Step 5: Switch
classification_service
Read classification_service.php. Replace, keeping the interface:
| Existing block | Replacement |
|---|---|
:115 get_all_by_student_plan query (where type, whereMeta('student_plan_id'), withMetadata, domain) |
return $this->repository->find_by_student_plan($student_plan_id, $as_of); (keep the existing $as_of filtering semantics: compare against the same field the old code compared, timecreated) |
:190 and :237-241 find_by_student_plan_and_unit queries |
$this->repository->find_by_plan_and_unit($student_plan_id, $unit_id, $as_of) |
create(array $data) at :151 (item_dto with parent: $student_plan_id, metadata keys) |
build $columns = table_row_hydrator::columns_from_meta(item_table_definitions::classification(), $data) + ['studentplanid' => $student_plan_id], call $this->repository->insert($columns), return $this->repository->find($id) |
find_by_submission(...) |
$this->repository->find_by_submission($submission_id) |
update_score(int $id, float $score, string $level) |
$this->repository->update_score($id, $score, $level); return $this->repository->find($id); |
level_reclassification_service.php:95 (find_component_classifications) also runs a whereMeta('student_plan_id') query for classification::TYPE: switch it to classification_repository::find_by_plan_and_unit the same way.
- Step 6: Run the metrics tests
Run: <TEST_CMD> --filter classification
Expected: PASS.
- Step 7: Commit
git add classes/extensions/metrics tests/extensions/metrics/classification
git commit -m "feat(metrics): persist classification in helico_classification"Task 8: metrics_report repository and service switch
Files:
- Create:
classes/extensions/metrics/report/repository/report_repository.php - Modify:
classes/extensions/metrics/report/service/report_service.php(extendsitem_service; blocks at:85-150) - Test:
tests/extensions/metrics/report/report_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::report(),table_row_hydrator. -
Produces
report_repository:find_by_idnumber(string $idnumber): ?reportupsert(string $idnumber, array $data): int(insert or update byidnumber; must setinvalidatedattonullwhen givennull)invalidate(int $id, int $at): voidinvalidate_for_enrolment(int $enrolment_id, int $at): intdelete_by_enrolment(int $enrolment_id): voidfind(int $id): ?report,delete(int $id): void(used by theitem_serviceoverrides)
-
Step 1: Write the failing test
<?php
declare(strict_types=1);
namespace local_helico\extensions\metrics\report;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\metrics\report\repository\report_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class report_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_upsert_is_idempotent_on_idnumber(): void
{
$repo = new report_repository();
$a = $repo->upsert('report:21:overall:all', ['enrolmentid' => 21, 'scope' => 'overall', 'dimensiondata' => '{"v":1}', 'generatedat' => 100, 'invalidatedat' => null]);
$b = $repo->upsert('report:21:overall:all', ['enrolmentid' => 21, 'scope' => 'overall', 'dimensiondata' => '{"v":2}', 'generatedat' => 200, 'invalidatedat' => null]);
$this->assertSame($a, $b);
$this->assertSame('{"v":2}', $repo->find_by_idnumber('report:21:overall:all')->getDescription());
}
public function test_invalidate_then_upsert_clears_invalidated_and_restores_fresh(): void
{
$repo = new report_repository();
$id = $repo->upsert('report:21:overall:all', ['enrolmentid' => 21, 'scope' => 'overall', 'generatedat' => 100, 'invalidatedat' => null]);
$repo->invalidate($id, 150);
$stale = $repo->find_by_idnumber('report:21:overall:all');
$this->assertSame('stale', $stale->getStatus());
$repo->upsert('report:21:overall:all', ['enrolmentid' => 21, 'scope' => 'overall', 'generatedat' => 200, 'invalidatedat' => null]);
$fresh = $repo->find_by_idnumber('report:21:overall:all');
$this->assertSame('fresh', $fresh->getStatus());
$this->assertNull($fresh->getMeta('invalidated_at'));
}
public function test_invalidate_for_enrolment_counts_only_fresh_rows(): void
{
$repo = new report_repository();
$repo->upsert('report:21:overall:all', ['enrolmentid' => 21, 'scope' => 'overall']);
$repo->upsert('report:21:discipline:4', ['enrolmentid' => 21, 'scope' => 'discipline', 'scopetargetid' => 4]);
$repo->upsert('report:22:overall:all', ['enrolmentid' => 22, 'scope' => 'overall']);
$this->assertSame(2, $repo->invalidate_for_enrolment(21, 300));
$this->assertSame(0, $repo->invalidate_for_enrolment(21, 301));
}
public function test_delete_by_enrolment(): void
{
$repo = new report_repository();
$repo->upsert('report:21:overall:all', ['enrolmentid' => 21, 'scope' => 'overall']);
$repo->delete_by_enrolment(21);
$this->assertNull($repo->find_by_idnumber('report:21:overall:all'));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter report_repository_test
Expected: FAIL (Class ... report_repository not found).
- Step 3: Implement the repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\metrics\report\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\metrics\report\entity\report;
/**
* Table access for `helico_metrics_report`. `idnumber` is the idempotency key.
*/
final class report_repository
{
private const TABLE = 'helico_metrics_report';
public function find_by_idnumber(string $idnumber): ?report
{
global $DB;
$row = $DB->get_record(self::TABLE, ['idnumber' => $idnumber]);
return $row === false ? null : table_row_hydrator::hydrate(item_table_definitions::report(), report::class, $row);
}
/**
* Inserts or updates the row identified by $idnumber and marks it fresh.
* A `null` for `invalidatedat` is written explicitly (update_record keeps nulls).
*
* @param array<string, mixed> $data column => value
*/
public function upsert(string $idnumber, array $data): int
{
global $DB;
$now = time();
$existing = $DB->get_record(self::TABLE, ['idnumber' => $idnumber], 'id');
$data += ['status' => 'fresh', 'invalidatedat' => null];
if ($existing === false) {
return (int) $DB->insert_record(self::TABLE, (object) ($data + ['idnumber' => $idnumber, 'timecreated' => $now, 'timemodified' => $now]));
}
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $data, partial: true);
$DB->update_record(self::TABLE, (object) ($data + ['id' => $existing->id, 'timemodified' => $now]));
return (int) $existing->id;
}
public function invalidate(int $id, int $at): void
{
global $DB;
$DB->update_record(self::TABLE, (object) ['id' => $id, 'status' => 'stale', 'invalidatedat' => $at, 'timemodified' => time()]);
}
public function invalidate_for_enrolment(int $enrolment_id, int $at): int
{
global $DB;
$ids = $DB->get_fieldset_select(self::TABLE, 'id', 'enrolmentid = :e AND invalidatedat IS NULL', ['e' => $enrolment_id]);
foreach ($ids as $id) {
$this->invalidate((int) $id, $at);
}
return count($ids);
}
public function delete_by_enrolment(int $enrolment_id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['enrolmentid' => $enrolment_id]);
}
}- Step 4: Run the repository tests
Run: <TEST_CMD> --filter report_repository_test
Expected: PASS (4 tests). getMeta('invalidated_at') is null because table_row_hydrator::hydrate copies the nullable column.
- Step 5: Switch
report_service
Read report_service.php. Keep record_snapshot()’s idnumber logic (report:{enrolment}:{scope}:{target|all}) and replace:
| Existing | Replacement |
|---|---|
record_snapshot create()/update() of item_dto |
$id = $this->repository->upsert($idnumber, ['enrolmentid' => $enrolment_id, 'studentplanid' => $student_plan_id, 'scope' => $scope->value, 'scopetargetid' => $scope_target_id, 'dimensiondata' => $dimension_data_json, 'generatedat' => $generated_at, 'invalidatedat' => null]); then return $this->repository->find_by_idnumber($idnumber) |
find_or_invalidated(...) |
return $this->repository->find_by_idnumber($idnumber); with the same idnumber construction |
invalidate(int $report_id, int $at) |
$this->repository->invalidate($report_id, $at); |
invalidate_for_enrolment(...) (the MiddagItemQueryBuilder block at :150) |
return $this->repository->invalidate_for_enrolment($enrolment_id, $at); |
report_service extends item_service: resolve the repository lazily (private ?report_repository $repository = null; plus a repository() accessor, as in Task 9 Step 6) and replace its create()/update() overrides (:44-56) with the four item_service overrides routed to the repository via table_row_hydrator::columns_from_dto(item_table_definitions::report(), $dto). Add find(int $id): ?report and delete(int $id): void to report_repository ($DB->get_record / $DB->delete_records over helico_metrics_report).
- Step 6: Run the metrics tests
Run: <TEST_CMD> --filter report
Expected: PASS.
- Step 7: Commit
git add classes/extensions/metrics/report tests/extensions/metrics/report
git commit -m "feat(metrics): persist metrics_report in helico_metrics_report"Task 9: exam_submission and exam_assign_link repositories and service switch
Files:
- Create:
classes/extensions/activity/assessment/exam_submission/repository/exam_submission_repository.php - Create:
classes/extensions/activity/assessment/exam_assign_sync/repository/exam_assign_link_repository.php - Modify:
classes/extensions/activity/assessment/exam_submission/service/exam_submission_service.php(finders:82-205,mark_in_review/mark_corrected:212-237,find_by_status:239) - Modify:
classes/extensions/activity/assessment/exam_assign_sync/service/exam_assign_link_service.php(record:34, finders:57-90) - Test:
tests/extensions/activity/assessment/exam_submission/exam_submission_repository_test.php,tests/extensions/activity/assessment/exam_assign_sync/exam_assign_link_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::exam_submission(),::exam_assign_link(),table_row_hydrator::hydrate()/columns_from_dto()(Task 3). -
Produces
exam_submission_repository:find(int $id): ?exam_submissionlist_by_slot(int $slot_id): list<exam_submission>andlist_by_slot_ids(array $slot_ids): list<exam_submission>(both orderedid ASC)find_by_slot(int $slot_id): ?exam_submission(lowest id)find_by_slot_and_question(int $slot_id, int $question_id): ?exam_submissionfind_by_slot_unit_and_question(int $slot_id, int $unit_id, int $question_id): ?exam_submissionlist_by_status(string $status, int $limit): list<exam_submission>insert(array $columns): int,update(int $id, array $columns): void,delete(int $id): void
-
Produces
exam_assign_link_repository:find(int $id),find_by_assign_submission_id(int),find_by_exam_submission_id(int),insert(array): int,update(int, array): void,delete(int): void; each find returns?exam_assign_link. -
Step 1: Write the failing tests
exam_submission_repository_test.php:
<?php
declare(strict_types=1);
namespace local_helico\extensions\activity\assessment\exam_submission;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\assessment\exam_submission\entity\exam_submission;
use local_helico\extensions\activity\assessment\exam_submission\repository\exam_submission_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class exam_submission_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_insert_find_and_slot_lookups(): void
{
$repo = new exam_submission_repository();
$a = $repo->insert(['slotid' => 10, 'unitid' => 5, 'questionid' => 1, 'userid' => 12, 'submittedtext' => 'a', 'correctionstatus' => 'pending']);
$b = $repo->insert(['slotid' => 10, 'unitid' => 6, 'questionid' => 1, 'userid' => 12, 'correctionstatus' => 'pending']);
$repo->insert(['slotid' => 11, 'unitid' => 5, 'questionid' => 1, 'userid' => 13, 'correctionstatus' => 'pending']);
$this->assertInstanceOf(exam_submission::class, $repo->find($a));
$this->assertSame($a, $repo->find_by_slot(10)->getId());
$this->assertSame([$a, $b], array_map(static fn ($s) => $s->getId(), $repo->list_by_slot(10)));
$this->assertCount(3, $repo->list_by_slot_ids([10, 11]));
$this->assertSame([], $repo->list_by_slot_ids([]));
$this->assertSame($b, $repo->find_by_slot_unit_and_question(10, 6, 1)->getId());
$this->assertSame($a, $repo->find_by_slot_and_question(10, 1)->getId());
$this->assertNull($repo->find_by_slot_unit_and_question(10, 99, 1));
}
public function test_hydrated_entity_keeps_student_userid_text_and_slot(): void
{
$repo = new exam_submission_repository();
$id = $repo->insert(['slotid' => 10, 'userid' => 12, 'submittedtext' => 'resposta', 'correctionstatus' => 'ai_pending', 'aiattempt' => 2]);
$entity = $repo->find($id);
$this->assertSame(12, $entity->getUserid());
$this->assertSame('resposta', $entity->getDescription());
$this->assertSame(10, $entity->get_slot_id());
$this->assertSame(2, $entity->get_ai_attempt());
$this->assertSame('ai_pending', $entity->getStatus());
}
public function test_submission_without_slot_is_stored_and_found_by_id(): void
{
$repo = new exam_submission_repository();
$id = $repo->insert(['userid' => 12, 'correctionstatus' => 'pending']);
$entity = $repo->find($id);
$this->assertNull($entity->getParent());
$this->assertSame(0, $entity->get_slot_id());
}
public function test_list_by_status_respects_limit_and_update_changes_columns(): void
{
$repo = new exam_submission_repository();
$ids = [];
for ($i = 0; $i < 3; ++$i) {
$ids[] = $repo->insert(['slotid' => 10 + $i, 'correctionstatus' => 'ai_pending']);
}
$this->assertCount(2, $repo->list_by_status('ai_pending', 2));
$repo->update($ids[0], ['correctionstatus' => 'corrected', 'correctedby' => 4, 'correctedat' => 500]);
$this->assertCount(2, $repo->list_by_status('ai_pending', 10));
$this->assertSame(4, $repo->find($ids[0])->get_corrected_by());
}
public function test_delete(): void
{
$repo = new exam_submission_repository();
$id = $repo->insert(['slotid' => 10, 'correctionstatus' => 'pending']);
$repo->delete($id);
$this->assertNull($repo->find($id));
}
}exam_assign_link_repository_test.php:
<?php
declare(strict_types=1);
namespace local_helico\extensions\activity\assessment\exam_assign_sync;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\assessment\exam_assign_sync\repository\exam_assign_link_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class exam_assign_link_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_lookup_both_directions_and_hydration(): void
{
$repo = new exam_assign_link_repository();
$id = $repo->insert(['examsubmissionid' => 50, 'assignsubmissionid' => 900, 'cmid' => 7, 'slotid' => 10, 'studentuserid' => 12]);
$by_assign = $repo->find_by_assign_submission_id(900);
$by_exam = $repo->find_by_exam_submission_id(50);
$this->assertSame($id, $by_assign->getId());
$this->assertSame($id, $by_exam->getId());
$this->assertSame(900, $by_assign->get_assign_submission_id());
$this->assertSame(50, $by_assign->get_exam_submission_id());
$this->assertSame(7, $by_assign->get_cmid());
$this->assertSame(12, $by_assign->get_student_user_id());
$this->assertNull($repo->find_by_assign_submission_id(901));
$this->assertNull($repo->find_by_exam_submission_id(51));
}
public function test_update_and_delete(): void
{
$repo = new exam_assign_link_repository();
$id = $repo->insert(['examsubmissionid' => 50, 'assignsubmissionid' => 900]);
$repo->update($id, ['cmid' => 8]);
$this->assertSame(8, $repo->find($id)->get_cmid());
$repo->delete($id);
$this->assertNull($repo->find($id));
}
}- Step 2: Run to verify they fail
Run: <TEST_CMD> --filter 'exam_submission_repository_test|exam_assign_link_repository_test'
Expected: FAIL (Class ... exam_submission_repository not found).
- Step 3: Implement
exam_submission_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\assessment\exam_submission\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\assessment\exam_submission\entity\exam_submission;
use stdClass;
/**
* Table access for `helico_exam_submission`.
*/
final class exam_submission_repository
{
private const TABLE = 'helico_exam_submission';
public function find(int $id): ?exam_submission
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
/**
* @return list<exam_submission>
*/
public function list_by_slot(int $slot_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['slotid' => $slot_id], 'id ASC'));
}
/**
* @param int[] $slot_ids
*
* @return list<exam_submission>
*/
public function list_by_slot_ids(array $slot_ids): array
{
global $DB;
$slot_ids = array_values(array_filter(array_map('intval', $slot_ids), static fn (int $id): bool => $id > 0));
if ($slot_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'slot');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "slotid {$insql}", $params, 'id ASC'));
}
public function find_by_slot(int $slot_id): ?exam_submission
{
return $this->list_by_slot($slot_id)[0] ?? null;
}
public function find_by_slot_and_question(int $slot_id, int $question_id): ?exam_submission
{
return $this->first(['slotid' => $slot_id, 'questionid' => $question_id]);
}
public function find_by_slot_unit_and_question(int $slot_id, int $unit_id, int $question_id): ?exam_submission
{
return $this->first(['slotid' => $slot_id, 'unitid' => $unit_id, 'questionid' => $question_id]);
}
/**
* @return list<exam_submission>
*/
public function list_by_status(string $status, int $limit): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['correctionstatus' => $status], 'id ASC', '*', 0, $limit));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns only the columns to change
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
public function delete(int $id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['id' => $id]);
}
/**
* @param array<string, int> $conditions
*/
private function first(array $conditions): ?exam_submission
{
global $DB;
$records = $DB->get_records(self::TABLE, $conditions, 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
private function hydrate(stdClass $row): exam_submission
{
return table_row_hydrator::hydrate(item_table_definitions::exam_submission(), exam_submission::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<exam_submission>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): exam_submission => $this->hydrate($row), $records));
}
}- Step 4: Implement
exam_assign_link_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\assessment\exam_assign_sync\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\assessment\exam_assign_sync\entity\exam_assign_link;
use stdClass;
/**
* Table access for `helico_exam_assign_link`.
*/
final class exam_assign_link_repository
{
private const TABLE = 'helico_exam_assign_link';
public function find(int $id): ?exam_assign_link
{
return $this->first(['id' => $id]);
}
public function find_by_assign_submission_id(int $assign_submission_id): ?exam_assign_link
{
return $this->first(['assignsubmissionid' => $assign_submission_id]);
}
public function find_by_exam_submission_id(int $exam_submission_id): ?exam_assign_link
{
return $this->first(['examsubmissionid' => $exam_submission_id]);
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns only the columns to change
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
public function delete(int $id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['id' => $id]);
}
/**
* @param array<string, int> $conditions
*/
private function first(array $conditions): ?exam_assign_link
{
global $DB;
$records = $DB->get_records(self::TABLE, $conditions, 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : table_row_hydrator::hydrate(item_table_definitions::exam_assign_link(), exam_assign_link::class, $first);
}
}- Step 5: Run the repository tests
Run: <TEST_CMD> --filter 'exam_submission_repository_test|exam_assign_link_repository_test'
Expected: PASS (7 tests).
- Step 6: Switch
exam_submission_service
Read the whole file. The class extends item_service with a 5-argument parent constructor (see the comment at notebook_artifact_service.php:60-66), so resolve the repository lazily. Add to the class:
private ?exam_submission_repository $repository = null;
private function repository(): exam_submission_repository
{
return $this->repository ??= new exam_submission_repository();
}
#[Override]
public function create(ItemDtoInterface $dto): ItemInterface
{
$id = $this->repository()->insert(table_row_hydrator::columns_from_dto(item_table_definitions::exam_submission(), $dto));
return $this->repository()->find($id);
}
#[Override]
public function update(ItemDtoInterface $dto): ItemInterface
{
$this->repository()->update((int) $dto->id, table_row_hydrator::columns_from_dto(item_table_definitions::exam_submission(), $dto));
return $this->repository()->find((int) $dto->id);
}
#[Override]
public function delete(int $id): void
{
$this->repository()->delete($id);
}
#[Override]
public function find(int $id): ?ItemInterface
{
return $this->repository()->find($id);
}These replace the existing create()/update() overrides at :44-58 (which only set $dto->type and call parent::). Then replace the finder bodies, keeping every signature and the grouping logic that follows the query:
| Method | New body |
|---|---|
find_by_slot |
return $this->repository()->find_by_slot($slot_id); |
find_all_by_slot |
$items = $this->repository()->list_by_slot($slot_id); then keep the existing $by_question loop (exam_submission::composite_key(...)) and return $by_question;; return [] when $items === [] |
find_all_by_slot_ids |
keep the existing normalisation of $slot_ids, then $items = $this->repository()->list_by_slot_ids($slot_ids); and keep the existing $by_slot loop |
find_by_slot_and_question |
return $this->repository()->find_by_slot_and_question($slot_id, $question_id); |
find_by_slot_unit_and_question |
return $this->repository()->find_by_slot_unit_and_question($slot_id, $unit_id, $question_id); |
find_by_id_safely |
return $this->repository()->find($id); |
find_by_status |
return $this->repository()->list_by_status($status->value, $limit); |
mark_in_review / mark_corrected |
replace parent::update(new item_dto(...)) with $this->update(new item_dto(...)) — parent::update would bypass the override and write to EAV |
record() is unchanged: it calls the finders above and $this->update(...)/$this->create(...). Add the use lines for ItemDtoInterface, ItemInterface, Override, item_table_definitions, table_row_hydrator and exam_submission_repository, and remove MiddagItemQueryBuilder, query_executor and Operator imports if nothing else in the file uses them.
Add this test to exam_submission_repository_test.php to pin the AI services’ partial-update contract through the service:
public function test_service_partial_update_from_ai_dispatch_keeps_status_and_other_columns(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\activity\assessment\exam_submission\contract\exam_submission_service_interface::class);
$repo = new exam_submission_repository();
$id = $repo->insert(['slotid' => 10, 'userid' => 12, 'submittedtext' => 'texto', 'correctionstatus' => 'ai_pending', 'aiattempt' => 1]);
$service->update(new \local_middag\base\domain\item\item_dto(
id: $id,
type: 'exam_submission',
metadata: ['ai_last_message' => 'unreadable', 'ai_last_response_json' => '{"raw":true}'],
));
$after = $repo->find($id);
$this->assertSame('ai_pending', $after->getStatus());
$this->assertSame('texto', $after->getDescription());
$this->assertSame(12, $after->getUserid());
$this->assertSame(1, $after->get_ai_attempt());
$this->assertSame('unreadable', $after->get_ai_last_message());
}(Use the resolver that neighbouring tests use if middag::get is not it: grep -rn "middag::get" tests/extensions | head -3.)
- Step 7: Switch
exam_assign_link_service
Same lazy-repository pattern with exam_assign_link_repository and item_table_definitions::exam_assign_link(); add the four overrides (create, update, delete, find) exactly as in Step 6 with those substitutions. record() already calls $this->update($dto) / $this->create($dto) and needs no change. Replace the two finder bodies:
| Method | New body |
|---|---|
find_by_assign_submission_id |
return $this->repository()->find_by_assign_submission_id($assign_submission_id); |
find_by_exam_submission_id |
return $this->repository()->find_by_exam_submission_id($exam_submission_id); |
- Step 8: Run the exam tests
Run: <TEST_CMD> --filter exam
Expected: PASS.
- Step 9: Commit
git add classes/extensions/activity/assessment tests/extensions/activity/assessment
git commit -m "feat(activity): persist exam_submission and exam_assign_link in dedicated tables"Task 10: exam_correction and criterion_score repositories and service switch
Files:
- Create:
classes/extensions/activity/assessment/exam_correction/repository/exam_correction_repository.php - Create:
classes/extensions/activity/assessment/exam_correction/repository/criterion_score_repository.php - Modify:
classes/extensions/activity/assessment/exam_correction/service/exam_correction_service.php(overrides:44-58,record_*untouched, finders:187-258,replace_criteria/clear_criteria:262-308) - Test:
tests/extensions/activity/assessment/exam_correction/exam_correction_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::exam_correction(),::criterion_score(),table_row_hydrator(Task 3),exam_submissionrows (Task 9, only as ids). -
Produces
exam_correction_repository:find(int $id): ?exam_correction;find_by_submission(int $submission_id): ?exam_correction(highest id);list_by_submission_ids(array $ids): list<exam_correction>(orderedid ASC);insert(array): int;update(int, array): void;delete(int): void. -
Produces
criterion_score_repository:list_by_correction(int $correction_id): list<criterion_score>(orderedsortorder ASC, id ASC);replace_for_correction(int $correction_id, array $rows): void(one transaction);delete_by_correction(int $correction_id): void. -
Step 1: Write the failing tests
<?php
declare(strict_types=1);
namespace local_helico\extensions\activity\assessment\exam_correction;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\assessment\exam_correction\entity\criterion_score;
use local_helico\extensions\activity\assessment\exam_correction\entity\exam_correction;
use local_helico\extensions\activity\assessment\exam_correction\repository\criterion_score_repository;
use local_helico\extensions\activity\assessment\exam_correction\repository\exam_correction_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class exam_correction_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_find_by_submission_returns_latest_and_hydrates_tutor_and_feedback(): void
{
$repo = new exam_correction_repository();
$repo->insert(['submissionid' => 50, 'tutorid' => 4, 'totalscore' => 5.0, 'feedbackhtml' => '<p>v1</p>']);
$latest = $repo->insert(['submissionid' => 50, 'tutorid' => 4, 'totalscore' => 8.5, 'feedbackhtml' => '<p>v2</p>', 'source' => 'tutor']);
$found = $repo->find_by_submission(50);
$this->assertInstanceOf(exam_correction::class, $found);
$this->assertSame($latest, $found->getId());
$this->assertSame(50, $found->get_submission_id());
$this->assertSame(4, $found->getUserid());
$this->assertSame('<p>v2</p>', $found->getDescription());
$this->assertNull($repo->find_by_submission(51));
}
public function test_list_by_submission_ids_handles_empty_and_many(): void
{
$repo = new exam_correction_repository();
$repo->insert(['submissionid' => 50, 'tutorid' => 4]);
$repo->insert(['submissionid' => 51, 'tutorid' => 0, 'source' => 'ai', 'cached' => 1, 'inputmismatch' => 0]);
$this->assertSame([], $repo->list_by_submission_ids([]));
$list = $repo->list_by_submission_ids([50, 51]);
$this->assertCount(2, $list);
}
public function test_update_keeps_untouched_columns_and_can_null_a_column(): void
{
$repo = new exam_correction_repository();
$id = $repo->insert(['submissionid' => 50, 'tutorid' => 4, 'totalscore' => 5.0, 'aimodel' => 'x']);
$repo->update($id, ['totalscore' => 6.5, 'aimodel' => null]);
$row = $repo->find($id);
$this->assertSame(4, $row->getUserid());
$this->assertNull($row->getMeta('ai_model'));
}
public function test_criteria_are_ordered_by_sortorder(): void
{
$criteria = new criterion_score_repository();
$criteria->replace_for_correction(7, [
['criterionname' => 'B', 'score' => 1.0, 'maxscore' => 2.0, 'weight' => 1.0, 'sortorder' => 1],
['criterionname' => 'A', 'score' => 2.0, 'maxscore' => 2.0, 'weight' => 1.0, 'sortorder' => 0],
]);
$list = $criteria->list_by_correction(7);
$this->assertCount(2, $list);
$this->assertContainsOnlyInstancesOf(criterion_score::class, $list);
$this->assertSame('A', $list[0]->get_criterion_name());
$this->assertSame('B', $list[1]->get_criterion_name());
}
public function test_replace_for_correction_replaces_only_that_correction(): void
{
$criteria = new criterion_score_repository();
$criteria->replace_for_correction(7, [['criterionname' => 'old', 'sortorder' => 0]]);
$criteria->replace_for_correction(8, [['criterionname' => 'other', 'sortorder' => 0]]);
$criteria->replace_for_correction(7, [['criterionname' => 'new1', 'sortorder' => 0], ['criterionname' => 'new2', 'sortorder' => 1]]);
$this->assertSame(['new1', 'new2'], array_map(static fn ($c) => $c->get_criterion_name(), $criteria->list_by_correction(7)));
$this->assertSame(['other'], array_map(static fn ($c) => $c->get_criterion_name(), $criteria->list_by_correction(8)));
}
public function test_replace_for_correction_is_atomic_when_an_insert_fails(): void
{
$criteria = new criterion_score_repository();
$criteria->replace_for_correction(7, [['criterionname' => 'keep', 'sortorder' => 0]]);
try {
$criteria->replace_for_correction(7, [
['criterionname' => 'ok', 'sortorder' => 0],
['criterionname' => 'bad', 'sortorder' => 'not-an-int', 'columnthatdoesnotexist' => 1],
]);
$this->fail('expected the insert of the bad row to throw');
} catch (\Throwable) {
// expected
}
$this->assertSame(['keep'], array_map(static fn ($c) => $c->get_criterion_name(), $criteria->list_by_correction(7)));
}
public function test_delete_by_correction(): void
{
$criteria = new criterion_score_repository();
$criteria->replace_for_correction(7, [['criterionname' => 'a', 'sortorder' => 0]]);
$criteria->delete_by_correction(7);
$this->assertSame([], $criteria->list_by_correction(7));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter exam_correction_repository_test
Expected: FAIL (Class ... exam_correction_repository not found).
- Step 3: Implement
exam_correction_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\assessment\exam_correction\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\assessment\exam_correction\entity\exam_correction;
use stdClass;
/**
* Table access for `helico_exam_correction`.
*/
final class exam_correction_repository
{
private const TABLE = 'helico_exam_correction';
public function find(int $id): ?exam_correction
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
public function find_by_submission(int $submission_id): ?exam_correction
{
global $DB;
$records = $DB->get_records(self::TABLE, ['submissionid' => $submission_id], 'id DESC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
/**
* @param int[] $submission_ids
*
* @return list<exam_correction>
*/
public function list_by_submission_ids(array $submission_ids): array
{
global $DB;
$submission_ids = array_values(array_filter(array_map('intval', $submission_ids), static fn (int $id): bool => $id > 0));
if ($submission_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($submission_ids, SQL_PARAMS_NAMED, 'sub');
return array_values(array_map(
fn (stdClass $row): exam_correction => $this->hydrate($row),
$DB->get_records_select(self::TABLE, "submissionid {$insql}", $params, 'id ASC'),
));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns only the columns to change; a `null` value clears the column
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
public function delete(int $id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['id' => $id]);
}
private function hydrate(stdClass $row): exam_correction
{
return table_row_hydrator::hydrate(item_table_definitions::exam_correction(), exam_correction::class, $row);
}
}- Step 4: Implement
criterion_score_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\assessment\exam_correction\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\assessment\exam_correction\entity\criterion_score;
use stdClass;
/**
* Table access for `helico_criterion_score`.
*/
final class criterion_score_repository
{
private const TABLE = 'helico_criterion_score';
/**
* @return list<criterion_score>
*/
public function list_by_correction(int $correction_id): array
{
global $DB;
$def = item_table_definitions::criterion_score();
return array_values(array_map(
static fn (stdClass $row): criterion_score => table_row_hydrator::hydrate($def, criterion_score::class, $row),
$DB->get_records(self::TABLE, ['correctionid' => $correction_id], 'sortorder ASC, id ASC'),
));
}
/**
* Deletes the correction's criteria and inserts $rows in ONE transaction, so a
* failing insert leaves the previous criteria untouched.
*
* @param list<array<string, mixed>> $rows column => value (without `correctionid`)
*/
public function replace_for_correction(int $correction_id, array $rows): void
{
global $DB;
$transaction = $DB->start_delegated_transaction();
try {
$DB->delete_records(self::TABLE, ['correctionid' => $correction_id]);
$now = time();
foreach ($rows as $row) {
$DB->insert_record(self::TABLE, (object) ($row + [
'correctionid' => $correction_id,
'timecreated' => $now,
'timemodified' => $now,
]));
}
$transaction->allow_commit();
} catch (\Throwable $e) {
$transaction->rollback($e);
}
}
public function delete_by_correction(int $correction_id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['correctionid' => $correction_id]);
}
}- Step 5: Run the repository tests
Run: <TEST_CMD> --filter exam_correction_repository_test
Expected: PASS (7 tests). $transaction->rollback($e) rethrows, which is what test_replace_for_correction_is_atomic_when_an_insert_fails expects. PHPUnit’s advanced_testcase wraps tests in a transaction; if the atomicity test cannot observe the rollback because of that outer transaction, mark that single test with #[\PHPUnit\Framework\Attributes\Group('requires_real_transaction')] and verify it manually in Task 12 Step 4 instead.
- Step 6: Switch
exam_correction_service
Read the whole file. Add the lazy repositories and the four overrides (replacing the create/update overrides at :44-58):
private ?exam_correction_repository $corrections = null;
private ?criterion_score_repository $criteria = null;
private function corrections(): exam_correction_repository
{
return $this->corrections ??= new exam_correction_repository();
}
private function criteria(): criterion_score_repository
{
return $this->criteria ??= new criterion_score_repository();
}
#[Override]
public function create(ItemDtoInterface $dto): ItemInterface
{
$id = $this->corrections()->insert(table_row_hydrator::columns_from_dto(item_table_definitions::exam_correction(), $dto));
return $this->corrections()->find($id);
}
#[Override]
public function update(ItemDtoInterface $dto): ItemInterface
{
$this->corrections()->update((int) $dto->id, table_row_hydrator::columns_from_dto(item_table_definitions::exam_correction(), $dto));
return $this->corrections()->find((int) $dto->id);
}
#[Override]
public function delete(int $id): void
{
$this->criteria()->delete_by_correction($id);
$this->corrections()->delete($id);
}
#[Override]
public function find(int $id): ?ItemInterface
{
return $this->corrections()->find($id);
}Then replace the persistence code:
| Method | New body |
|---|---|
find_by_submission |
return $this->corrections()->find_by_submission($submission_id); |
find_by_submission_ids |
keep the existing normalisation of $submission_ids, then foreach ($this->corrections()->list_by_submission_ids($submission_ids) as $item) feeding the existing “keep the highest id per submission” loop; return $by_submission |
find_criteria |
$vos = array_map(static fn (criterion_score_entity $e): criterion_score => $e->to_vo(), $this->criteria()->list_by_correction($exam_correction_id)); then the existing usort on sort_order and return $vos; |
replace_criteria |
build $rows instead of calling parent::create(...) per criterion: for each $vo (same construction as today, sort_order: $sort), $rows[] = table_row_hydrator::columns_from_meta(item_table_definitions::criterion_score(), $vo->to_metadata()); then $this->criteria()->replace_for_correction($correction_id, $rows); (this single call replaces clear_criteria() + the loop, in one transaction) |
clear_criteria |
delete the method (no remaining callers; grep -n clear_criteria must show none) |
record() and record_ai_result() need no change: they call $this->update($dto) / $this->create($dto), which are now the overrides, and replace_criteria(...). Update the imports: add ItemDtoInterface, ItemInterface, Override, item_table_definitions, table_row_hydrator, exam_correction_repository, criterion_score_repository; remove MiddagItemQueryBuilder, query_executor, Operator and item_dto if nothing else in the file uses them.
Add these service-level tests to exam_correction_repository_test.php:
public function test_service_record_then_find_criteria_round_trip(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\activity\assessment\exam_correction\contract\exam_correction_service_interface::class);
$criteria = [
new \local_helico\extensions\activity\assessment\exam_correction\vo\criterion_score(criterion_name: 'Clareza', score: 1.0, max: 2.0, weight: 1.0, comment: null, sort_order: 0, skill_id: null, skill_label: null, status: null, status_label: null, evidence: null),
new \local_helico\extensions\activity\assessment\exam_correction\vo\criterion_score(criterion_name: 'Estrutura', score: 2.0, max: 2.0, weight: 1.0, comment: 'bom', sort_order: 1, skill_id: null, skill_label: null, status: null, status_label: null, evidence: null),
];
$correction = $service->record(50, 4, 12, 10, '<p>feedback</p>', $criteria, 1000);
$again = $service->record(50, 4, 12, 10, '<p>feedback 2</p>', [$criteria[0]], 1100);
$this->assertSame($correction->getId(), $again->getId());
$this->assertSame('<p>feedback 2</p>', $service->find_by_submission(50)->getDescription());
$found = $service->find_criteria((int) $correction->getId());
$this->assertCount(1, $found);
$this->assertSame('Clareza', $found[0]->criterion_name);
}(If the VO constructor’s named parameters differ, copy them from exam_correction/vo/criterion_score.php.)
- Step 7: Run the exam tests
Run: <TEST_CMD> --filter exam
Expected: PASS.
- Step 8: Commit
git add classes/extensions/activity/assessment/exam_correction tests/extensions/activity/assessment/exam_correction
git commit -m "feat(activity): persist exam_correction and criterion_score in dedicated tables"Task 11: slot, slot_scope_ref and lock_dependency repositories and service switch
slot is the hottest query of the engine (whereMeta('student_plan_id'), 229 ms in dev) and the parent of session, exam_submission, lock_dependency and slot_scope_ref; many other rows keep its id in a slot_id meta (notebook_artifact 9,371, classification 3,968, activity_result 814, session 642, exam_*). Ids are preserved, so those references stay valid.
Files:
- Create:
classes/extensions/engine/algorithm/repository/slot_repository.php - Create:
classes/extensions/engine/algorithm/repository/slot_scope_ref_repository.php - Create:
classes/extensions/engine/algorithm/repository/slot_lock_repository.php - Modify:
classes/extensions/engine/algorithm/service/slot_service.php(finders:41-130,create/bulk_create/update_*:136-210) - Modify:
classes/extensions/engine/algorithm/service/slot_lock_service.php(overrides:74-87,write_lock:104-136, finders:138-225) - Modify:
classes/extensions/engine/algorithm/service/slot_scope_service.php(overrides:43-56,:58-135) - Test:
tests/extensions/engine/algorithm/slot_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::slot(),::slot_scope_ref(),::slot_lock(),table_row_hydrator::hydrate()/columns_from_meta()/columns_from_dto()(Task 3). -
Produces
slot_repository:find(int $id): ?slot,find_by_uuid(string $uuid): ?slotlist_by_student_plan(int $student_plan_id, ?string $blockref = null, array $slot_types = []): list<slot>(orderedsortorder ASC, id ASC)list_by_type(string $slot_type): list<slot>ids_by_student_plan(int $student_plan_id): list<int>insert(array $columns): int,insert_many(array $rows): void,update(int $id, array $columns): void,delete_by_ids(array $ids): void
-
Produces
slot_scope_ref_repository:list_by_slot(int $slot_id): list<slot_scope_ref_entity>(orderedsortorder ASC, id ASC);find_pair(int $slot_id, string $kind, int $ref_id): ?slot_scope_ref_entity;replace_for_slot(int $slot_id, array $rows): void(one transaction);delete_by_slot_ids(array $slot_ids): void;find(int $id),insert(array): int,update(int, array): void,delete(int): void. -
Produces
slot_lock_repository:list_by_slot(int $slot_id): list<lock_dependency_entity>;list_by_depends_on(int $upstream_slot_id): list<lock_dependency_entity>;replace_for_slot(int $slot_id, array $rows): void(one transaction);delete_by_slot_ids(array $slot_ids): void(edges of those slots and edges pointing at them);find(int $id),insert(array): int,update(int, array): void,delete(int): void. -
Step 1: Write the failing tests
slot_repository_test.php:
<?php
declare(strict_types=1);
namespace local_helico\extensions\engine\algorithm;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\engine\algorithm\entity\slot;
use local_helico\extensions\engine\algorithm\repository\slot_lock_repository;
use local_helico\extensions\engine\algorithm\repository\slot_repository;
use local_helico\extensions\engine\algorithm\repository\slot_scope_ref_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class slot_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
private function slot(int $plan, string $blockref, string $type, int $sort, string $status = 'not_started'): int
{
static $n = 0;
return (new slot_repository())->insert([
'studentplanid' => $plan, 'uuid' => 'uuid-' . (++$n), 'flowref' => 'F1', 'blockref' => $blockref,
'sortorder' => $sort, 'slottype' => $type, 'slotstatus' => $status, 'label' => 'L' . $n,
]);
}
public function test_list_by_student_plan_filters_orders_and_hydrates(): void
{
$repo = new slot_repository();
$b = $this->slot(2, 'B1', 'guided_study', 2);
$a = $this->slot(2, 'B1', 'flashcard_practice', 1);
$this->slot(2, 'B2', 'guided_study', 1);
$this->slot(3, 'B1', 'guided_study', 1);
$all = $repo->list_by_student_plan(2);
$block = $repo->list_by_student_plan(2, 'B1');
$typed = $repo->list_by_student_plan(2, null, ['guided_study']);
$this->assertCount(3, $all);
$this->assertContainsOnlyInstancesOf(slot::class, $all);
$this->assertSame([$a, $b], array_map(static fn ($s) => $s->getId(), $block));
$this->assertCount(2, $typed);
$this->assertSame(2, $block[0]->get_student_plan_id());
$this->assertSame('B1', $block[0]->get_blockref());
$this->assertSame('flashcard_practice', $block[0]->get_slot_type());
$this->assertSame(1, $block[0]->get_sort_order());
$this->assertCount(3, $repo->list_by_student_plan(2, null, []));
}
public function test_find_find_by_uuid_and_defaults(): void
{
$repo = new slot_repository();
$id = $this->slot(2, 'B1', 'guided_study', 1);
$by_id = $repo->find($id);
$by_uuid = $repo->find_by_uuid($by_id->getUuid());
$this->assertSame($id, $by_uuid->getId());
$this->assertSame('not_started', $by_id->get_slot_status());
$this->assertNull($by_id->get_context());
$this->assertNull($by_id->get_locked());
$this->assertNull($by_id->get_written_overall_score());
$this->assertNull($repo->find(999999));
$this->assertNull($repo->find_by_uuid('nope'));
}
public function test_update_partial_columns_keeps_the_rest(): void
{
$repo = new slot_repository();
$id = $this->slot(2, 'B1', 'guided_study', 1);
$repo->update($id, ['slotstatus' => 'completed']);
$repo->update($id, ['context' => '{"k":1}', 'result' => '{"ok":true}']);
$repo->update($id, ['writtencorrectionstate' => 'corrected', 'writtenoverallscore' => 7.5]);
$s = $repo->find($id);
$this->assertSame('completed', $s->get_slot_status());
$this->assertSame('{"k":1}', $s->get_context());
$this->assertSame('{"ok":true}', $s->get_result());
$this->assertSame('corrected', $s->get_written_correction_state());
$this->assertSame(7.5, $s->get_written_overall_score());
$this->assertSame('guided_study', $s->get_slot_type());
}
public function test_status_is_exposed_as_item_status_and_slot_status(): void
{
$repo = new slot_repository();
$id = $this->slot(2, 'B1', 'guided_study', 1, 'in_progress');
$s = $repo->find($id);
$this->assertSame('in_progress', $s->getStatus());
$this->assertSame('in_progress', $s->get_slot_status());
}
public function test_list_by_type_ids_by_plan_and_delete(): void
{
$repo = new slot_repository();
$a = $this->slot(2, 'B1', 'exam_written', 1);
$b = $this->slot(2, 'B1', 'guided_study', 2);
$this->slot(3, 'B1', 'exam_written', 1);
$this->assertCount(2, $repo->list_by_type('exam_written'));
$this->assertSame([], $repo->list_by_type(''));
$this->assertSame([$a, $b], $repo->ids_by_student_plan(2));
$repo->delete_by_ids([$a]);
$this->assertNull($repo->find($a));
$this->assertSame([$b], $repo->ids_by_student_plan(2));
}
public function test_insert_many(): void
{
$repo = new slot_repository();
$repo->insert_many([
['studentplanid' => 4, 'uuid' => 'u-a', 'blockref' => 'B1', 'slottype' => 'guided_study', 'slotstatus' => 'not_started'],
['studentplanid' => 4, 'uuid' => 'u-b', 'blockref' => 'B1', 'slottype' => 'guided_study', 'slotstatus' => 'not_started'],
]);
$this->assertCount(2, $repo->list_by_student_plan(4));
}
public function test_lock_edges_by_slot_and_by_upstream(): void
{
$locks = new slot_lock_repository();
$locks->replace_for_slot(10, [
['dependsonslotid' => 5, 'kind' => 'prerequisite', 'requiredstatus' => 'completed'],
['dependsonslotid' => 6, 'kind' => 'prerequisite'],
]);
$locks->replace_for_slot(11, [['dependsonslotid' => 5, 'kind' => 'prerequisite']]);
$of_10 = $locks->list_by_slot(10);
$this->assertCount(2, $of_10);
$this->assertSame(10, $of_10[0]->getParent());
$this->assertSame(5, $of_10[0]->get_depends_on_slot_id());
$this->assertSame('completed', $of_10[0]->get_required_status());
$this->assertNull($of_10[1]->get_required_status());
$this->assertSame([10, 11], array_map(static fn ($e) => $e->getParent(), $locks->list_by_depends_on(5)));
}
public function test_lock_replace_is_scoped_and_delete_by_slot_ids_removes_both_directions(): void
{
$locks = new slot_lock_repository();
$locks->replace_for_slot(10, [['dependsonslotid' => 5, 'kind' => 'prerequisite']]);
$locks->replace_for_slot(11, [['dependsonslotid' => 10, 'kind' => 'prerequisite']]);
$locks->replace_for_slot(10, [['dependsonslotid' => 7, 'kind' => 'prerequisite']]);
$this->assertSame([7], array_map(static fn ($e) => $e->get_depends_on_slot_id(), $locks->list_by_slot(10)));
$locks->delete_by_slot_ids([10]);
$this->assertSame([], $locks->list_by_slot(10));
$this->assertSame([], $locks->list_by_slot(11), 'edges pointing at a deleted slot are removed too');
}
public function test_scope_refs_ordered_pair_lookup_and_replace(): void
{
$refs = new slot_scope_ref_repository();
$refs->replace_for_slot(10, [
['kind' => 'unit', 'refid' => 5, 'name' => 'U5', 'sortorder' => 1],
['kind' => 'discipline', 'refid' => 2, 'name' => 'D2', 'sortorder' => 0],
]);
$list = $refs->list_by_slot(10);
$this->assertSame(['D2', 'U5'], array_map(static fn ($r) => $r->get_ref_name(), $list));
$this->assertSame(10, $list[0]->getParent());
$this->assertSame(5, $refs->find_pair(10, 'unit', 5)->get_ref_id());
$this->assertNull($refs->find_pair(10, 'unit', 6));
$refs->replace_for_slot(10, [['kind' => 'unit', 'refid' => 9, 'name' => 'U9', 'sortorder' => 0]]);
$this->assertCount(1, $refs->list_by_slot(10));
$refs->delete_by_slot_ids([10]);
$this->assertSame([], $refs->list_by_slot(10));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter slot_repository_test
Expected: FAIL (Class ... slot_repository not found).
- Step 3: Implement
slot_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\engine\algorithm\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\engine\algorithm\entity\slot;
use stdClass;
/**
* Table access for `helico_slot`.
*/
final class slot_repository
{
private const TABLE = 'helico_slot';
public function find(int $id): ?slot
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
public function find_by_uuid(string $uuid): ?slot
{
global $DB;
$records = $DB->get_records(self::TABLE, ['uuid' => $uuid], 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
/**
* @param string[] $slot_types empty = any type
*
* @return list<slot>
*/
public function list_by_student_plan(int $student_plan_id, ?string $blockref = null, array $slot_types = []): array
{
global $DB;
$where = ['studentplanid = :plan'];
$params = ['plan' => $student_plan_id];
if ($blockref !== null) {
$where[] = 'blockref = :block';
$params['block'] = $blockref;
}
$slot_types = array_values(array_unique(array_filter($slot_types, static fn ($t): bool => is_string($t) && $t !== '')));
if ($slot_types !== []) {
[$insql, $in] = $DB->get_in_or_equal($slot_types, SQL_PARAMS_NAMED, 'type');
$where[] = "slottype {$insql}";
$params += $in;
}
return $this->hydrate_all($DB->get_records_select(self::TABLE, implode(' AND ', $where), $params, 'sortorder ASC, id ASC'));
}
/**
* @return list<slot>
*/
public function list_by_type(string $slot_type): array
{
global $DB;
if ($slot_type === '') {
return [];
}
return $this->hydrate_all($DB->get_records(self::TABLE, ['slottype' => $slot_type], 'sortorder ASC, id ASC'));
}
/**
* @return list<int>
*/
public function ids_by_student_plan(int $student_plan_id): array
{
global $DB;
return array_map('intval', $DB->get_fieldset_select(self::TABLE, 'id', 'studentplanid = :plan ORDER BY id ASC', ['plan' => $student_plan_id]));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param list<array<string, mixed>> $rows
*/
public function insert_many(array $rows): void
{
global $DB;
if ($rows === []) {
return;
}
$now = time();
$DB->insert_records(self::TABLE, array_map(
static fn (array $r): stdClass => (object) ($r + ['timecreated' => $now, 'timemodified' => $now]),
$rows,
));
}
/**
* @param array<string, mixed> $columns only the columns to change; `null` clears a column
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
/**
* @param int[] $ids
*/
public function delete_by_ids(array $ids): void
{
global $DB;
$ids = array_values(array_filter(array_map('intval', $ids), static fn (int $id): bool => $id > 0));
if ($ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'id');
$DB->delete_records_select(self::TABLE, "id {$insql}", $params);
}
private function hydrate(stdClass $row): slot
{
return table_row_hydrator::hydrate(item_table_definitions::slot(), slot::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<slot>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): slot => $this->hydrate($row), $records));
}
}slot::getUuid() is used in the test: it exists (slot.php getUuid() override reads the uuid meta, which the hydrator fills).
- Step 4: Implement
slot_scope_ref_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\engine\algorithm\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\engine\algorithm\entity\slot_scope_ref_entity;
use stdClass;
/**
* Table access for `helico_slot_scope_ref`.
*/
final class slot_scope_ref_repository
{
private const TABLE = 'helico_slot_scope_ref';
public function find(int $id): ?slot_scope_ref_entity
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
/**
* @return list<slot_scope_ref_entity>
*/
public function list_by_slot(int $slot_id): array
{
global $DB;
return array_values(array_map(
fn (stdClass $row): slot_scope_ref_entity => $this->hydrate($row),
$DB->get_records(self::TABLE, ['slotid' => $slot_id], 'sortorder ASC, id ASC'),
));
}
public function find_pair(int $slot_id, string $kind, int $ref_id): ?slot_scope_ref_entity
{
global $DB;
$records = $DB->get_records(self::TABLE, ['slotid' => $slot_id, 'kind' => $kind, 'refid' => $ref_id], 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
/**
* Deletes the slot's refs and inserts $rows in ONE transaction.
*
* @param list<array<string, mixed>> $rows column => value (without `slotid`)
*/
public function replace_for_slot(int $slot_id, array $rows): void
{
global $DB;
$transaction = $DB->start_delegated_transaction();
try {
$DB->delete_records(self::TABLE, ['slotid' => $slot_id]);
$now = time();
foreach ($rows as $row) {
$DB->insert_record(self::TABLE, (object) ($row + ['slotid' => $slot_id, 'timecreated' => $now, 'timemodified' => $now]));
}
$transaction->allow_commit();
} catch (\Throwable $e) {
$transaction->rollback($e);
}
}
/**
* @param int[] $slot_ids
*/
public function delete_by_slot_ids(array $slot_ids): void
{
global $DB;
$slot_ids = array_values(array_filter(array_map('intval', $slot_ids), static fn (int $id): bool => $id > 0));
if ($slot_ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'slot');
$DB->delete_records_select(self::TABLE, "slotid {$insql}", $params);
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
public function delete(int $id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['id' => $id]);
}
private function hydrate(stdClass $row): slot_scope_ref_entity
{
return table_row_hydrator::hydrate(item_table_definitions::slot_scope_ref(), slot_scope_ref_entity::class, $row);
}
}- Step 5: Implement
slot_lock_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\engine\algorithm\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\engine\algorithm\entity\lock_dependency_entity;
use stdClass;
/**
* Table access for `helico_slot_lock` (dependency edges between slots).
*/
final class slot_lock_repository
{
private const TABLE = 'helico_slot_lock';
public function find(int $id): ?lock_dependency_entity
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
/**
* @return list<lock_dependency_entity>
*/
public function list_by_slot(int $slot_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['slotid' => $slot_id], 'id ASC'));
}
/**
* @return list<lock_dependency_entity>
*/
public function list_by_depends_on(int $upstream_slot_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['dependsonslotid' => $upstream_slot_id], 'id ASC'));
}
/**
* Deletes the slot's edges and inserts $rows in ONE transaction.
*
* @param list<array<string, mixed>> $rows column => value (without `slotid`)
*/
public function replace_for_slot(int $slot_id, array $rows): void
{
global $DB;
$transaction = $DB->start_delegated_transaction();
try {
$DB->delete_records(self::TABLE, ['slotid' => $slot_id]);
$now = time();
foreach ($rows as $row) {
$DB->insert_record(self::TABLE, (object) ($row + ['slotid' => $slot_id, 'timecreated' => $now, 'timemodified' => $now]));
}
$transaction->allow_commit();
} catch (\Throwable $e) {
$transaction->rollback($e);
}
}
/**
* Removes the edges OF these slots and the edges pointing AT them.
*
* @param int[] $slot_ids
*/
public function delete_by_slot_ids(array $slot_ids): void
{
global $DB;
$slot_ids = array_values(array_filter(array_map('intval', $slot_ids), static fn (int $id): bool => $id > 0));
if ($slot_ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'slot');
[$dsql, $dparams] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'dep');
$DB->delete_records_select(self::TABLE, "slotid {$insql} OR dependsonslotid {$dsql}", $params + $dparams);
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
public function delete(int $id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['id' => $id]);
}
private function hydrate(stdClass $row): lock_dependency_entity
{
return table_row_hydrator::hydrate(item_table_definitions::slot_lock(), lock_dependency_entity::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<lock_dependency_entity>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): lock_dependency_entity => $this->hydrate($row), $records));
}
}- Step 6: Run the repository tests
Run: <TEST_CMD> --filter slot_repository_test
Expected: PASS (9 tests).
- Step 7: Switch
slot_service
slot_service does not extend item_service; it takes ItemServiceInterface $item_service and SignalDispatcherInterface $dispatcher. Replace the first constructor argument so no DI change is needed (a new initializer is valid in a promoted constructor parameter default on PHP 8.4):
public function __construct(
private readonly SignalDispatcherInterface $dispatcher,
private readonly slot_repository $repository = new slot_repository(),
) {}Check the container registration first: grep -rn "slot_service" classes/extensions/engine/algorithm/*.php classes/extensions/engine/*.php — if the class is built by autowiring, the reordered arguments need no change; if an explicit ->setArguments([...]) exists, update it to [$dispatcher].
Replace the persistence code, keeping every signature in slot_service_interface:
| Method | New body |
|---|---|
find_by_id |
return $this->repository->find($id); |
find_by_uuid |
return $this->repository->find_by_uuid($uuid); |
find_by_student_plan_and_block |
return $this->repository->list_by_student_plan($student_plan_id, $blockref); |
find_by_student_plan |
return $this->repository->list_by_student_plan($student_plan_id); |
find_by_student_plan_and_types |
keep the existing normalisation that returns [] for an empty list, then return $this->repository->list_by_student_plan($student_plan_id, null, $slot_types); |
find_by_type |
keep the '' guard, then return $this->repository->list_by_type($slot_type); |
create(array $data) |
$id = $this->repository->insert(table_row_hydrator::columns_from_dto(item_table_definitions::slot(), $this->build_dto($data))); then $created = $this->repository->find($id); and keep the slot_creation_failed_exception guard |
bulk_create(array $datas) |
$this->repository->insert_many(array_map(fn (array $d): array => table_row_hydrator::columns_from_dto(item_table_definitions::slot(), $this->build_dto($d)), $datas)); |
update_status |
$this->repository->update($id, ['slotstatus' => $slot_status]); then the unchanged COMPLETED dispatch |
update_result |
$this->repository->update($id, ['result' => $result_json]); |
update_context |
$this->repository->update($id, ['context' => $context_json]); |
update_written_correction |
$this->repository->update($id, ['writtencorrectionstate' => $state, 'writtenoverallscore' => $overall]); (a null score is stored as NULL; the old code stored '', which get_written_overall_score() already reads as null) |
sorted_slots |
delete the method (no callers left) |
build_dto() is kept as is: columns_from_dto maps its parent to studentplanid, its status to slotstatus, and its metadata (including uuid, label, scope, context, result, locked, action, courseid) to columns. Remove the ItemServiceInterface, MiddagItemQueryBuilder, query_executor and Operator imports if nothing else uses them; add slot_repository, item_table_definitions and table_row_hydrator.
Add to slot_repository_test.php:
public function test_service_create_update_status_and_dispatch(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\engine\algorithm\contract\slot_service_interface::class);
$created = $service->create([
'student_plan_id' => 2, 'flowref' => 'F1', 'blockref' => 'B1', 'sort_order' => 3,
'slot_type' => 'guided_study', 'label' => 'Estudo guiado', 'courseid' => 77,
]);
$this->assertSame(2, $created->get_student_plan_id());
$this->assertSame('not_started', $created->get_slot_status());
$this->assertSame('Estudo guiado', $created->get_label());
$this->assertNotSame('', $created->getUuid());
$service->update_status((int) $created->getId(), 'in_progress');
$service->update_context((int) $created->getId(), '{"a":1}');
$service->update_written_correction((int) $created->getId(), 'pending', null);
$after = $service->find_by_id((int) $created->getId());
$this->assertSame('in_progress', $after->get_slot_status());
$this->assertSame('{"a":1}', $after->get_context());
$this->assertNull($after->get_written_overall_score());
$this->assertSame($created->getUuid(), $service->find_by_uuid($created->getUuid())->getUuid());
}(Use the resolver neighbouring tests use if middag::get is not it: grep -rn "middag::get" tests/extensions | head -3.)
- Step 8: Switch
slot_lock_service
The class extends item_service with a 6-argument constructor that already calls parent::__construct(...) (the comment at :58-63 explains why: without it the inherited readonly props stay uninitialised). Keep that constructor. Add lazy repositories:
private ?slot_lock_repository $locks = null;
private ?slot_repository $slots = null;
private function locks(): slot_lock_repository
{
return $this->locks ??= new slot_lock_repository();
}
private function slots(): slot_repository
{
return $this->slots ??= new slot_repository();
}Replace the two overrides at :74-87 with the four item_service overrides routed to the lock table:
#[Override]
public function create(ItemDtoInterface $dto): ItemInterface
{
$id = $this->locks()->insert(table_row_hydrator::columns_from_dto(item_table_definitions::slot_lock(), $dto));
return $this->locks()->find($id);
}
#[Override]
public function update(ItemDtoInterface $dto): ItemInterface
{
$this->locks()->update((int) $dto->id, table_row_hydrator::columns_from_dto(item_table_definitions::slot_lock(), $dto));
return $this->locks()->find((int) $dto->id);
}
#[Override]
public function delete(int $id): void
{
$this->locks()->delete($id);
}
#[Override]
public function find(int $id): ?ItemInterface
{
return $this->locks()->find($id);
}Then:
| Method | New body |
|---|---|
read_lock |
unchanged (reads through slot_service->find_by_id) |
write_lock |
build $metadata exactly as today, then replace parent::update($dto) with $this->slots()->update($slot_id, table_row_hydrator::columns_from_meta(item_table_definitions::slot(), $metadata)); — parent::update would write the slot item to EAV and now fails because update() is overridden for locks |
find_dependencies |
array_map(static fn (lock_dependency_entity $e): lock_dependency => $e->to_vo(), $this->locks()->list_by_slot($slot_id)) |
find_dependents |
foreach ($this->locks()->list_by_depends_on($upstream_slot_id) as $entity) { $slot_ids[(int) $entity->getParent()] = true; } then the existing blockref filtering loop |
replace_dependencies |
$this->locks()->replace_for_slot($slot_id, array_map(static fn ($dep): array => table_row_hydrator::columns_from_meta(item_table_definitions::slot_lock(), $dep->to_metadata()), $deps)); (replaces clear() + the create loop, in one transaction) |
clear |
$this->locks()->replace_for_slot($slot_id, []); |
Add the use lines and drop the MiddagItemQueryBuilder, query_executor, Operator imports if unused. Add:
public function test_lock_service_round_trip(): void
{
$slots = new slot_repository();
$slot = $slots->insert(['studentplanid' => 2, 'uuid' => 'u-1', 'blockref' => 'B1', 'slottype' => 'guided_study', 'slotstatus' => 'not_started']);
$upstream = $slots->insert(['studentplanid' => 2, 'uuid' => 'u-2', 'blockref' => 'B1', 'slottype' => 'guided_study', 'slotstatus' => 'not_started']);
$other_block = $slots->insert(['studentplanid' => 2, 'uuid' => 'u-3', 'blockref' => 'B2', 'slottype' => 'guided_study', 'slotstatus' => 'not_started']);
$service = \local_middag\base\middag::get(\local_helico\extensions\engine\algorithm\contract\slot_lock_service_interface::class);
$service->replace_dependencies($slot, [new \local_helico\extensions\engine\algorithm\vo\lock_dependency(depends_on_slot_id: $upstream, kind: 'prerequisite', required_status: 'completed')]);
$service->replace_dependencies($other_block, [new \local_helico\extensions\engine\algorithm\vo\lock_dependency(depends_on_slot_id: $upstream, kind: 'prerequisite', required_status: null)]);
$service->write_lock($slot, new \local_helico\extensions\engine\algorithm\vo\slot_lock(reason: 'prerequisite', message: 'Conclua antes', unlock_rule: 'after_completed', unlock_at: null));
$deps = $service->find_dependencies($slot);
$this->assertCount(1, $deps);
$this->assertSame($upstream, $deps[0]->depends_on_slot_id);
$this->assertEqualsCanonicalizing([$slot, $other_block], $service->find_dependents($upstream));
$this->assertSame([$slot], $service->find_dependents($upstream, 'B1'));
$this->assertTrue($service->read_lock($slot)->is_locked());
$this->assertSame('Conclua antes', $service->read_lock($slot)->message);
$service->clear($slot);
$this->assertSame([], $service->find_dependencies($slot));
}- Step 9: Switch
slot_scope_service
slot_scope_service extends item_service with the default constructor (no parent::__construct args — it only used parent::create/update, which now go away). Add private ?slot_scope_ref_repository $refs = null; with a refs() accessor, and replace the two overrides at :43-56 with the four overrides routed to item_table_definitions::slot_scope_ref() (same code as in Step 8 with refs() instead of locks() and slot_scope_ref() instead of slot_lock()). Then:
| Method | New body |
|---|---|
find_by_slot |
$vos = array_map(static fn (slot_scope_ref_entity $e): slot_scope_ref => $e->to_vo(), $this->refs()->list_by_slot($slot_id)); then the existing usort on sort_order and return $vos; |
replace_for_slot |
$this->refs()->replace_for_slot($slot_id, array_map(static fn (slot_scope_ref $r): array => table_row_hydrator::columns_from_meta(item_table_definitions::slot_scope_ref(), $r->to_metadata()), $refs)); — one transaction; no clear() + loop |
attach |
keep the find_existing_pair guard, then $this->refs()->insert(table_row_hydrator::columns_from_meta(item_table_definitions::slot_scope_ref(), $ref->to_metadata()) + ['slotid' => $slot_id]); |
clear |
$this->refs()->delete_by_slot_ids([$slot_id]); |
find_existing_pair |
return $this->refs()->find_pair($slot_id, $kind, $ref_id); |
Add:
public function test_scope_service_replace_attach_is_idempotent(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\engine\algorithm\contract\slot_scope_service_interface::class);
$ref = new \local_helico\extensions\engine\algorithm\vo\slot_scope_ref(kind: 'unit', ref_id: 5, name: 'U5', sort_order: 1);
$service->replace_for_slot(10, [$ref]);
$service->attach(10, $ref);
$service->attach(10, new \local_helico\extensions\engine\algorithm\vo\slot_scope_ref(kind: 'discipline', ref_id: 2, name: 'D2', sort_order: 0));
$found = $service->find_by_slot(10);
$this->assertCount(2, $found);
$this->assertSame('discipline', $found[0]->kind);
$service->clear(10);
$this->assertSame([], $service->find_by_slot(10));
}- Step 10: Run the engine tests
Run: <TEST_CMD> --filter 'slot|algorithm'
Expected: PASS.
- Step 11: Commit
git add classes/extensions/engine/algorithm tests/extensions/engine/algorithm
git commit -m "feat(engine): persist slot, slot_scope_ref and lock_dependency in dedicated tables"Task 12: notebook_artifact, notebook_annotation and artifact_version repositories and service switch
The Caderno Online is the biggest per-student set in the dev DB: 9,371 artifacts (133 k meta rows), 7,133 versions and 359 annotations, a 37 MB editor_state_json that is rewritten in place on every autosave, and 182 MB of framework revisions. enrolment is the artifact’s parent and stays EAV (43 rows, no payload): the artifact keeps enrolmentid as a plain column, and the migrator checks that parent in helico_items.
Files:
- Create:
classes/extensions/activity/productive/notebook_artifact/repository/notebook_artifact_repository.php - Create:
classes/extensions/activity/productive/notebook_annotation/repository/notebook_annotation_repository.php - Create:
classes/extensions/activity/productive/artifact_versioning/repository/notebook_version_repository.php - Modify:
classes/extensions/activity/productive/notebook_artifact/service/notebook_artifact_service.php(overrides:70-84; finders:106-205,:315-575;promote_to_notebook:168;publish:283-306;refetch_or_throw:~730) - Modify:
classes/extensions/activity/productive/notebook_annotation/service/notebook_annotation_service.php(overrides:37-51, finders:79-120) - Modify:
classes/extensions/activity/productive/artifact_versioning/service/artifact_versioning_service.php(override:38-44,find_history:74-95) - Test:
tests/extensions/activity/productive/notebook_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::notebook_artifact(),::notebook_annotation(),::notebook_version(),table_row_hydrator::hydrate()/columns_from_dto()(Task 3). -
Produces
notebook_artifact_repository:find(int $id): ?notebook_artifactfind_by_enrolment_unit(int $enrolment_id, int $unit_id): ?notebook_artifact,find_by_slot(int $slot_id): ?notebook_artifact,find_by_topic(int $enrolment_id, int $unit_id, int $topic_id): ?notebook_artifact(lowest id, as the olditems()[0])list_by_enrolment(int $enrolment_id): list<notebook_artifact>,list_by_enrolment_units(int $enrolment_id, array $unit_ids): list<…>,list_by_unit_topics(int $enrolment_id, int $unit_id, array $topic_ids): list<…>,list_by_slot_unit(int $slot_id, int $unit_id): list<…>,list_by_slot_ids(array $slot_ids, ?string $visibility_scope = null): list<…>(all orderedid ASC)ids_by_enrolment(int $enrolment_id): list<int>insert(array $columns): int,update(int $id, array $columns): void,delete_by_ids(array $ids): void
-
Produces
notebook_annotation_repository:find(int $id),find_by_key(int $artifact_id, string $key),list_by_artifact(int $artifact_id): list<notebook_annotation>,list_by_artifact_ids(array $ids): list<notebook_annotation>,insert(array): int,update(int, array): void,delete(int): void,delete_by_artifact_ids(array): void. -
Produces
notebook_version_repository:list_by_artifact(int $artifact_id): list<artifact_version>(versionnumber DESC, id DESC),insert(array): int,delete(int $id): void,delete_by_artifact_ids(array): void. -
Step 1: Write the failing tests
<?php
declare(strict_types=1);
namespace local_helico\extensions\activity\productive;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\productive\artifact_versioning\entity\artifact_version;
use local_helico\extensions\activity\productive\artifact_versioning\repository\notebook_version_repository;
use local_helico\extensions\activity\productive\notebook_annotation\entity\notebook_annotation;
use local_helico\extensions\activity\productive\notebook_annotation\repository\notebook_annotation_repository;
use local_helico\extensions\activity\productive\notebook_artifact\entity\notebook_artifact;
use local_helico\extensions\activity\productive\notebook_artifact\repository\notebook_artifact_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class notebook_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
private function artifact(int $enrolment, int $unit, ?int $topic, ?int $slot = null, string $scope = 'notebook', string $status = 'published'): int
{
return (new notebook_artifact_repository())->insert([
'enrolmentid' => $enrolment, 'userid' => 8, 'studentplanid' => 2, 'unitid' => $unit, 'topicid' => $topic, 'slotid' => $slot,
'sourcetype' => 'leitura', 'sourceorigin' => 'student', 'visibilityscope' => $scope, 'artifactstatus' => $status,
'editorstateversion' => 1, 'editorstateformat' => 'lexical-json', 'editorstatejson' => '{"root":{"type":"root","children":[]}}',
'contenthtml' => '<p>x</p>', 'lastinteractionat' => 100,
]);
}
public function test_hydration_keeps_enrolment_parent_user_status_and_content(): void
{
$repo = new notebook_artifact_repository();
$id = $this->artifact(21, 5, 7, 40, 'current_block', 'draft');
$a = $repo->find($id);
$this->assertInstanceOf(notebook_artifact::class, $a);
$this->assertSame(21, $a->getParent());
$this->assertSame(21, $a->get_enrolment_id());
$this->assertSame(8, $a->getUserid());
$this->assertSame('draft', $a->getStatus());
$this->assertSame('<p>x</p>', $a->get_content_html());
$this->assertSame(5, $a->get_unit_id());
$this->assertSame(7, $a->get_topic_id());
$this->assertSame(40, $a->get_slot_id());
$this->assertSame(1, $a->get_editor_state_version());
$this->assertSame('lexical-json', $a->get_editor_state_format());
$this->assertSame(100, $a->get_last_interaction_at());
}
public function test_nullable_ids_round_trip_as_null(): void
{
$repo = new notebook_artifact_repository();
$id = $repo->insert(['enrolmentid' => 21, 'userid' => 8]);
$a = $repo->find($id);
$this->assertNull($a->get_unit_id());
$this->assertNull($a->get_topic_id());
$this->assertNull($a->get_slot_id());
$this->assertNull($a->get_editor_state_json());
$this->assertSame('draft', $a->getStatus());
$this->assertSame(0, $a->get_editor_state_version());
}
public function test_lookups(): void
{
$repo = new notebook_artifact_repository();
$a = $this->artifact(21, 5, 7, 40);
$b = $this->artifact(21, 5, 8, 41);
$this->artifact(22, 5, 7, 42);
$this->assertSame($a, $repo->find_by_enrolment_unit(21, 5)->getId());
$this->assertSame($b, $repo->find_by_topic(21, 5, 8)->getId());
$this->assertSame($a, $repo->find_by_slot(40)->getId());
$this->assertNull($repo->find_by_topic(21, 5, 99));
$this->assertSame([$a, $b], array_map(static fn ($x) => $x->getId(), $repo->list_by_enrolment(21)));
$this->assertCount(2, $repo->list_by_enrolment_units(21, [5, 6]));
$this->assertSame([], $repo->list_by_enrolment_units(21, []));
$this->assertSame([$b], array_map(static fn ($x) => $x->getId(), $repo->list_by_unit_topics(21, 5, [8, 9])));
$this->assertSame([], $repo->list_by_unit_topics(21, 5, []));
$this->assertSame([$a], array_map(static fn ($x) => $x->getId(), $repo->list_by_slot_unit(40, 5)));
$this->assertSame([$a, $b], $repo->ids_by_enrolment(21));
}
public function test_list_by_slot_ids_filters_visibility(): void
{
$repo = new notebook_artifact_repository();
$cur = $this->artifact(21, 5, 7, 40, 'current_block');
$this->artifact(21, 5, 8, 41, 'notebook');
$this->assertCount(2, $repo->list_by_slot_ids([40, 41]));
$this->assertSame([$cur], array_map(static fn ($x) => $x->getId(), $repo->list_by_slot_ids([40, 41], 'current_block')));
$this->assertSame([], $repo->list_by_slot_ids([]));
}
public function test_partial_update_keeps_the_rest_and_delete(): void
{
$repo = new notebook_artifact_repository();
$id = $this->artifact(21, 5, 7, 40, 'current_block');
$repo->update($id, ['visibilityscope' => 'notebook']);
$repo->update($id, ['editorstatejson' => '{"v":2}', 'editorstateversion' => 2, 'lastinteractionat' => 200]);
$a = $repo->find($id);
$this->assertSame('notebook', $a->get_visibility_scope()->value);
$this->assertSame('{"v":2}', $a->get_editor_state_json());
$this->assertSame(2, $a->get_editor_state_version());
$this->assertSame('<p>x</p>', $a->get_content_html());
$this->assertSame(21, $a->get_enrolment_id());
$repo->delete_by_ids([$id]);
$this->assertNull($repo->find($id));
}
public function test_annotations_by_key_artifact_and_ids(): void
{
$repo = new notebook_annotation_repository();
$a1 = $repo->insert(['artifactid' => 50, 'userid' => 8, 'topicid' => 7, 'annotationkey' => 'k1', 'color' => 'yellow', 'xpct' => 12.5, 'ypct' => 3.0, 'commenttext' => 'nota', 'createdat' => 10, 'updatedat' => 11]);
$repo->insert(['artifactid' => 50, 'userid' => 8, 'annotationkey' => 'k2']);
$repo->insert(['artifactid' => 51, 'userid' => 8, 'annotationkey' => 'k1']);
$by_key = $repo->find_by_key(50, 'k1');
$this->assertInstanceOf(notebook_annotation::class, $by_key);
$this->assertSame($a1, $by_key->getId());
$this->assertSame(50, $by_key->get_artifact_id());
$this->assertSame('k1', $by_key->get_annotation_key());
$this->assertSame('yellow', $by_key->get_color());
$this->assertSame(12.5, $by_key->get_x_pct());
$this->assertSame('nota', $by_key->get_comment());
$this->assertSame(10, $by_key->get_created_at());
$this->assertNull($repo->find_by_key(50, 'zz'));
$this->assertCount(2, $repo->list_by_artifact(50));
$this->assertCount(3, $repo->list_by_artifact_ids([50, 51]));
$this->assertSame([], $repo->list_by_artifact_ids([]));
$repo->delete($a1);
$this->assertCount(1, $repo->list_by_artifact(50));
$repo->delete_by_artifact_ids([50, 51]);
$this->assertSame([], $repo->list_by_artifact_ids([50, 51]));
}
public function test_versions_are_listed_newest_first_with_creator_and_content(): void
{
$repo = new notebook_version_repository();
$repo->insert(['artifactid' => 50, 'createdby' => 8, 'versionnumber' => 1, 'changereason' => 'submit', 'previousorigin' => 'student', 'contenthtml' => '<p>v1</p>']);
$repo->insert(['artifactid' => 50, 'createdby' => 9, 'versionnumber' => 2, 'changereason' => 'submit', 'previousorigin' => 'helico', 'contenthtml' => '<p>v2</p>']);
$repo->insert(['artifactid' => 51, 'createdby' => 8, 'versionnumber' => 1]);
$list = $repo->list_by_artifact(50);
$this->assertCount(2, $list);
$this->assertContainsOnlyInstancesOf(artifact_version::class, $list);
$this->assertSame(2, $list[0]->get_version_number());
$this->assertSame(9, $list[0]->get_created_by());
$this->assertSame(9, $list[0]->getUserid());
$this->assertSame('<p>v2</p>', $list[0]->get_content_html());
$this->assertSame('helico', $list[0]->get_previous_origin());
$this->assertSame(50, $list[0]->get_artifact_id());
$repo->delete_by_artifact_ids([50]);
$this->assertSame([], $repo->list_by_artifact(50));
$this->assertCount(1, $repo->list_by_artifact(51));
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter notebook_repository_test
Expected: FAIL (Class ... notebook_artifact_repository not found).
- Step 3: Implement
notebook_artifact_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\activity\productive\notebook_artifact\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\activity\productive\notebook_artifact\entity\notebook_artifact;
use stdClass;
/**
* Table access for `helico_notebook_artifact`.
*/
final class notebook_artifact_repository
{
private const TABLE = 'helico_notebook_artifact';
public function find(int $id): ?notebook_artifact
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
public function find_by_enrolment_unit(int $enrolment_id, int $unit_id): ?notebook_artifact
{
return $this->first(['enrolmentid' => $enrolment_id, 'unitid' => $unit_id]);
}
public function find_by_slot(int $slot_id): ?notebook_artifact
{
return $this->first(['slotid' => $slot_id]);
}
public function find_by_topic(int $enrolment_id, int $unit_id, int $topic_id): ?notebook_artifact
{
return $this->first(['enrolmentid' => $enrolment_id, 'unitid' => $unit_id, 'topicid' => $topic_id]);
}
/**
* @return list<notebook_artifact>
*/
public function list_by_enrolment(int $enrolment_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['enrolmentid' => $enrolment_id], 'id ASC'));
}
/**
* @param int[] $unit_ids
*
* @return list<notebook_artifact>
*/
public function list_by_enrolment_units(int $enrolment_id, array $unit_ids): array
{
global $DB;
$unit_ids = $this->positive($unit_ids);
if ($unit_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($unit_ids, SQL_PARAMS_NAMED, 'unit');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "enrolmentid = :enrolment AND unitid {$insql}", ['enrolment' => $enrolment_id] + $params, 'id ASC'));
}
/**
* @param int[] $topic_ids
*
* @return list<notebook_artifact>
*/
public function list_by_unit_topics(int $enrolment_id, int $unit_id, array $topic_ids): array
{
global $DB;
$topic_ids = $this->positive($topic_ids);
if ($topic_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($topic_ids, SQL_PARAMS_NAMED, 'topic');
return $this->hydrate_all($DB->get_records_select(
self::TABLE,
"enrolmentid = :enrolment AND unitid = :unit AND topicid {$insql}",
['enrolment' => $enrolment_id, 'unit' => $unit_id] + $params,
'id ASC',
));
}
/**
* @return list<notebook_artifact>
*/
public function list_by_slot_unit(int $slot_id, int $unit_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['slotid' => $slot_id, 'unitid' => $unit_id], 'id ASC'));
}
/**
* @param int[] $slot_ids
*
* @return list<notebook_artifact>
*/
public function list_by_slot_ids(array $slot_ids, ?string $visibility_scope = null): array
{
global $DB;
$slot_ids = $this->positive($slot_ids);
if ($slot_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'slot');
$where = "slotid {$insql}";
if ($visibility_scope !== null) {
$where .= ' AND visibilityscope = :scope';
$params['scope'] = $visibility_scope;
}
return $this->hydrate_all($DB->get_records_select(self::TABLE, $where, $params, 'id ASC'));
}
/**
* @return list<int>
*/
public function ids_by_enrolment(int $enrolment_id): array
{
global $DB;
return array_map('intval', $DB->get_fieldset_select(self::TABLE, 'id', 'enrolmentid = :e ORDER BY id ASC', ['e' => $enrolment_id]));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns only the columns to change; `null` clears a column
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
/**
* @param int[] $ids
*/
public function delete_by_ids(array $ids): void
{
global $DB;
$ids = $this->positive($ids);
if ($ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'id');
$DB->delete_records_select(self::TABLE, "id {$insql}", $params);
}
/**
* @param array<string, int> $conditions
*/
private function first(array $conditions): ?notebook_artifact
{
global $DB;
$records = $DB->get_records(self::TABLE, $conditions, 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
/**
* @param int[] $values
*
* @return list<int>
*/
private function positive(array $values): array
{
return array_values(array_unique(array_filter(array_map('intval', $values), static fn (int $v): bool => $v > 0)));
}
private function hydrate(stdClass $row): notebook_artifact
{
return table_row_hydrator::hydrate(item_table_definitions::notebook_artifact(), notebook_artifact::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<notebook_artifact>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): notebook_artifact => $this->hydrate($row), $records));
}
}- Step 4: Implement
notebook_annotation_repositoryandnotebook_version_repository
notebook_annotation_repository.php (namespace local_helico\extensions\activity\productive\notebook_annotation\repository, same file header and imports pattern; entity notebook_annotation, table helico_notebook_annotation, definition item_table_definitions::notebook_annotation()):
final class notebook_annotation_repository
{
private const TABLE = 'helico_notebook_annotation';
public function find(int $id): ?notebook_annotation
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
public function find_by_key(int $artifact_id, string $key): ?notebook_annotation
{
global $DB;
if ($key === '') {
return null;
}
$records = $DB->get_records(self::TABLE, ['artifactid' => $artifact_id, 'annotationkey' => $key], 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
/**
* @return list<notebook_annotation>
*/
public function list_by_artifact(int $artifact_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['artifactid' => $artifact_id], 'id ASC'));
}
/**
* @param int[] $artifact_ids
*
* @return list<notebook_annotation>
*/
public function list_by_artifact_ids(array $artifact_ids): array
{
global $DB;
$artifact_ids = array_values(array_unique(array_filter(array_map('intval', $artifact_ids), static fn (int $id): bool => $id > 0)));
if ($artifact_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($artifact_ids, SQL_PARAMS_NAMED, 'art');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "artifactid {$insql}", $params, 'id ASC'));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
public function delete(int $id): void
{
global $DB;
$DB->delete_records(self::TABLE, ['id' => $id]);
}
/**
* @param int[] $artifact_ids
*/
public function delete_by_artifact_ids(array $artifact_ids): void
{
global $DB;
$artifact_ids = array_values(array_filter(array_map('intval', $artifact_ids), static fn (int $id): bool => $id > 0));
if ($artifact_ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($artifact_ids, SQL_PARAMS_NAMED, 'art');
$DB->delete_records_select(self::TABLE, "artifactid {$insql}", $params);
}
private function hydrate(stdClass $row): notebook_annotation
{
return table_row_hydrator::hydrate(item_table_definitions::notebook_annotation(), notebook_annotation::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<notebook_annotation>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): notebook_annotation => $this->hydrate($row), $records));
}
}notebook_version_repository.php (namespace local_helico\extensions\activity\productive\artifact_versioning\repository; entity artifact_version, table helico_notebook_version, definition item_table_definitions::notebook_version()):
final class notebook_version_repository
{
private const TABLE = 'helico_notebook_version';
/**
* @return list<artifact_version>
*/
public function list_by_artifact(int $artifact_id): array
{
global $DB;
$def = item_table_definitions::notebook_version();
return array_values(array_map(
static fn (stdClass $row): artifact_version => table_row_hydrator::hydrate($def, artifact_version::class, $row),
$DB->get_records(self::TABLE, ['artifactid' => $artifact_id], 'versionnumber DESC, id DESC'),
));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param int[] $artifact_ids
*/
public function delete_by_artifact_ids(array $artifact_ids): void
{
global $DB;
$artifact_ids = array_values(array_filter(array_map('intval', $artifact_ids), static fn (int $id): bool => $id > 0));
if ($artifact_ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($artifact_ids, SQL_PARAMS_NAMED, 'art');
$DB->delete_records_select(self::TABLE, "artifactid {$insql}", $params);
}
}Both files start with the standard header, declare(strict_types=1);, defined('MOODLE_INTERNAL') || exit; and import item_table_definitions, table_row_hydrator, their entity and stdClass.
- Step 5: Run the repository tests
Run: <TEST_CMD> --filter notebook_repository_test
Expected: PASS (8 tests).
- Step 6: Switch
notebook_artifact_service
The class extends item_service with the inherited constructor (it resolves versioning_service and annotation_service lazily through middag::get). Add lazy repositories and replace the overrides at :70-84:
private ?notebook_artifact_repository $artifacts = null;
private ?notebook_annotation_repository $annotation_rows = null;
private ?notebook_version_repository $version_rows = null;
private function artifacts(): notebook_artifact_repository
{
return $this->artifacts ??= new notebook_artifact_repository();
}
private function annotation_rows(): notebook_annotation_repository
{
return $this->annotation_rows ??= new notebook_annotation_repository();
}
private function version_rows(): notebook_version_repository
{
return $this->version_rows ??= new notebook_version_repository();
}
#[Override]
public function create(ItemDtoInterface $dto): ItemInterface
{
$id = $this->artifacts()->insert(table_row_hydrator::columns_from_dto(item_table_definitions::notebook_artifact(), $dto));
return $this->artifacts()->find($id);
}
#[Override]
public function update(ItemDtoInterface $dto): ItemInterface
{
$this->artifacts()->update((int) $dto->id, table_row_hydrator::columns_from_dto(item_table_definitions::notebook_artifact(), $dto));
return $this->artifacts()->find((int) $dto->id);
}
#[Override]
public function delete(int $id): void
{
$this->annotation_rows()->delete_by_artifact_ids([$id]);
$this->version_rows()->delete_by_artifact_ids([$id]);
$this->artifacts()->delete_by_ids([$id]);
}
#[Override]
public function find(int $id): ?ItemInterface
{
return $this->artifacts()->find($id);
}delete() also removes the artifact’s annotations and versions (the generic item delete used to leave them orphaned). Then:
| Method | New body |
|---|---|
find_by_unit |
return $this->artifacts()->find_by_enrolment_unit($enrolment_id, $unit_id); |
find_by_slot |
return $this->artifacts()->find_by_slot($slot_id); |
find_by_enrolment |
$items = $this->artifacts()->list_by_enrolment($enrolment_id); then the existing current_block filter and usort on last_interaction_at; return $items; |
promote_to_notebook |
replace parent::update(new item_dto(...)) with $this->update(new item_dto(...)) — parent::update would write to EAV |
find_by_topic |
return $this->artifacts()->find_by_topic($enrolment_id, $unit_id, $topic_id); |
publish |
replace the parent::update(new item_dto(...)) after the snapshot with $this->update(new item_dto(...)) |
find_by_enrolment_and_units |
keep the $normalized unit-id handling, then $items = $this->artifacts()->list_by_enrolment_units($enrolment_id, array_keys($normalized)); and the existing scope filter and $by_unit grouping |
find_by_unit_topics |
keep $normalized, then $items = $this->artifacts()->list_by_unit_topics($enrolment_id, $unit_id, array_keys($normalized)); and the existing scope filter and latest-per-topic loop |
annotation_counts_for |
keep $normalized, then foreach ($this->annotation_rows()->list_by_artifact_ids(array_keys($normalized)) as $annotation) { $aid = $annotation->get_artifact_id(); $counts[$aid] = ($counts[$aid] ?? 0) + 1; } |
finalize_slot_unit_drafts |
keep the <= 0 guard, then foreach ($this->artifacts()->list_by_slot_unit($slot_id, $unit_id) as $artifact) into the existing loop |
promote_slots_to_notebook |
keep $normalized, then foreach ($this->artifacts()->list_by_slot_ids(array_keys($normalized), visibility_scope::CURRENT_BLOCK->value) as $artifact) into the existing loop |
find_annotations_by_artifacts |
keep $normalized, then foreach ($this->annotation_rows()->list_by_artifact_ids(array_keys($normalized)) as $annotation) { $by_artifact[$annotation->get_artifact_id()][] = $annotation; } |
refetch_or_throw |
$found = $this->artifacts()->find($artifact_id); and keep the existing “throw when null” behaviour |
record(), save_full() and apply_patch() call $this->find_by_*, $this->create() and $this->update(), which now hit the table, and need no change. The autosave path therefore writes editorstatejson to one column of one row (no framework revision). Add the imports (notebook_artifact_repository, notebook_annotation_repository, notebook_version_repository, item_table_definitions, table_row_hydrator, ItemDtoInterface, ItemInterface, Override) and remove MiddagItemQueryBuilder, query_executor, Operator if nothing else uses them.
- Step 7: Switch
notebook_annotation_serviceandartifact_versioning_service
notebook_annotation_service extends item_service: add private ?notebook_annotation_repository $rows = null; with an accessor, replace the two overrides at :37-51 with the four overrides routed to item_table_definitions::notebook_annotation() (same code as in Step 6 with $this->rows() and delete() = $this->rows()->delete($id)), then:
| Method | New body |
|---|---|
find_by_artifact |
return $this->rows()->list_by_artifact($artifact_id); |
find_by_key |
return $this->rows()->find_by_key($artifact_id, $annotation_key); (it already returns null for '') |
upsert, delete_keys_not_in and count_by_artifact keep calling $this->find_by_key(), $this->create(), $this->update(), $this->delete() and need no change.
artifact_versioning_service extends item_service: add private ?notebook_version_repository $rows = null; with an accessor, replace the create() override at :38-44 with the four overrides routed to item_table_definitions::notebook_version() (delete(int $id) calls $this->rows()->delete($id); add delete(int $id): void to notebook_version_repository as a one-line $DB->delete_records(self::TABLE, ['id' => $id])), and replace find_history with return $this->rows()->list_by_artifact($artifact_id);. snapshot() keeps building its item_dto (parent, userid: $created_by, description: $previous_content_html, metadata) and calling $this->create(...); columns_from_dto maps description to contenthtml and created_by to createdby.
Add to notebook_repository_test.php:
public function test_services_publish_snapshot_and_promote(): void
{
$artifacts = \local_middag\base\middag::get(\local_helico\extensions\activity\productive\notebook_artifact\contract\notebook_artifact_service_interface::class);
$versions = \local_middag\base\middag::get(\local_helico\extensions\activity\productive\artifact_versioning\contract\artifact_versioning_service_interface::class);
$id = $this->artifact(21, 5, 7, 40, 'current_block', 'draft');
$published = $artifacts->publish($id, 8);
$promoted = $artifacts->promote_slots_to_notebook([40]);
$this->assertSame('published', $published->getStatus());
$this->assertSame(1, $promoted);
$this->assertSame('notebook', (new notebook_artifact_repository())->find($id)->get_visibility_scope()->value);
$history = $versions->find_history($id);
$this->assertCount(1, $history);
$this->assertSame(1, $history[0]->get_version_number());
$this->assertSame(8, $history[0]->get_created_by());
$this->assertSame('<p>x</p>', $history[0]->get_content_html());
$this->assertSame(2, $versions->next_version_number($id));
$this->assertSame($published->getId(), $artifacts->publish($id, 8)->getId(), 'publishing twice is a no-op');
$this->assertCount(1, $versions->find_history($id));
}
public function test_service_find_by_enrolment_hides_current_block_and_sorts_by_last_interaction(): void
{
$artifacts = \local_middag\base\middag::get(\local_helico\extensions\activity\productive\notebook_artifact\contract\notebook_artifact_service_interface::class);
$repo = new notebook_artifact_repository();
$older = $this->artifact(21, 5, 7);
$newer = $this->artifact(21, 5, 8);
$repo->update($older, ['lastinteractionat' => 100]);
$repo->update($newer, ['lastinteractionat' => 300]);
$this->artifact(21, 6, 9, 41, 'current_block');
$visible = $artifacts->find_by_enrolment(21);
$all = $artifacts->find_by_enrolment(21, true);
$this->assertSame([$newer, $older], array_map(static fn ($a) => $a->getId(), $visible));
$this->assertCount(3, $all);
}
public function test_annotation_service_upsert_is_idempotent_and_counts(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\activity\productive\notebook_annotation\contract\notebook_annotation_service_interface::class);
$dto = static fn (string $comment) => new \local_helico\extensions\activity\productive\notebook_annotation\dto\notebook_annotation_dto(
user_id: 8, artifact_id: 50, topic_id: 7, annotation_key: 'k1', color: 'yellow', comment: $comment, x_pct: 10.0, y_pct: 20.0,
);
$first = $service->upsert($dto('primeira'));
$second = $service->upsert($dto('segunda'));
$this->assertSame($first->getId(), $second->getId());
$this->assertSame('segunda', $service->find_by_key(50, 'k1')->get_comment());
$this->assertSame(1, $service->count_by_artifact(50));
$service->upsert(new \local_helico\extensions\activity\productive\notebook_annotation\dto\notebook_annotation_dto(user_id: 8, artifact_id: 50, topic_id: 7, annotation_key: 'k2', color: null, comment: ''));
$service->delete_keys_not_in(50, ['k2']);
$this->assertNull($service->find_by_key(50, 'k1'));
$this->assertSame(1, $service->count_by_artifact(50));
}(If the notebook_annotation_dto constructor’s named parameters differ, copy them from notebook_annotation/dto/notebook_annotation_dto.php; use the container resolver neighbouring tests use if middag::get is not it.)
- Step 8: Run the notebook tests
Run: <TEST_CMD> --filter 'notebook|artifact'
Expected: PASS.
- Step 9: Commit
git add classes/extensions/activity/productive tests/extensions/activity/productive
git commit -m "feat(activity): persist notebook artifact, annotation and version in dedicated tables"Task 13: session and session_data repositories, lazy payload, service switch
session is the largest payload left in the EAV tables: 642 rows carry 68 MB of data JSON (avg 112 KB, max 1.4 MB), plus 235 MB of framework revisions (8.4 per session) from the many update_* calls. The JSON is therefore not stored in helico_session: it goes to helico_session_data (1:1), so the hot paths that only need status, times or ids (12 handlers call find_active_by_slot; every update_status/update_time_spent/complete rewrites the row) never read or rewrite the blob. The entity loads the payload lazily on the first get_data()/getMeta('data'), so no caller can get a silent null.
The session’s parent is the slot (a table now; the migrator still checks the pre-migration row in helico_items).
Files:
- Create:
classes/extensions/engine/session/repository/session_repository.php - Create:
classes/extensions/engine/session/repository/session_data_repository.php - Modify:
classes/extensions/engine/session/entity/session.php(lazygetMeta) - Modify:
classes/extensions/engine/session/service/session_service.php(constructor:33-35; finders:37-222;create:224-256;update_*andcomplete:258-338) - Test:
tests/extensions/engine/session/session_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::session(),table_row_hydrator::hydrate()/columns_from_dto()(Task 3). -
Produces
session_repository:find(int $id): ?sessionlist_by_slot(int $slot_id): list<session>,list_by_slot_ids(array $slot_ids): list<session>(bothid ASC; without the payload)ids_by_slot_ids(array $slot_ids): list<int>insert(array $columns): int,update(int $id, array $columns): voiddelete_by_ids(array $ids): void(also deletes the sessions’helico_session_datarows)
-
Produces
session_data_repository:find_data(int $session_id): ?stringsave(int $session_id, ?string $json): void(updates the newest row of the session, inserts when none;nullor''deletes it)delete_by_session_ids(array $session_ids): void
-
Produces
session::getMeta('data')/session::get_data()loading the payload fromhelico_session_datawhen the entity was hydrated without it. -
Step 1: Write the failing tests
<?php
declare(strict_types=1);
namespace local_helico\extensions\engine\session;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\engine\session\entity\session;
use local_helico\extensions\engine\session\repository\session_data_repository;
use local_helico\extensions\engine\session\repository\session_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class session_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
private function row(int $slot, string $status = 'in_progress', array $extra = []): int
{
return (new session_repository())->insert($extra + [
'slotid' => $slot, 'userid' => 8, 'courseid' => 2, 'sessionstatus' => $status,
'startedat' => 100, 'lastresumedat' => 100, 'timespent' => 0,
]);
}
public function test_validator_rejects_a_status_outside_the_enum_and_a_missing_slot(): void
{
$repo = new session_repository();
try {
$repo->insert(['slotid' => 40, 'sessionstatus' => 'xyz']);
$this->fail('an invalid status must be rejected');
} catch (\local_helico\base\persistence\invalid_row_exception $e) {
$this->assertArrayHasKey('sessionstatus', $e->errors());
}
try {
$repo->insert(['userid' => 8]);
$this->fail('a missing slotid must be rejected');
} catch (\local_helico\base\persistence\invalid_row_exception $e) {
$this->assertArrayHasKey('slotid', $e->errors());
}
$this->assertSame([], $repo->list_by_slot(40), 'nothing was written');
}
public function test_hydration_exposes_slot_user_status_and_times(): void
{
$repo = new session_repository();
$id = $this->row(40, 'in_progress', ['pausedat' => 150, 'timespent' => 33]);
$s = $repo->find($id);
$this->assertInstanceOf(session::class, $s);
$this->assertSame(40, $s->getParent());
$this->assertSame(40, $s->get_slot_id());
$this->assertSame(8, $s->get_user_id());
$this->assertSame(8, $s->getUserid());
$this->assertSame('in_progress', $s->get_session_status());
$this->assertSame(100, $s->get_started_at());
$this->assertSame(150, $s->get_paused_at());
$this->assertSame(100, $s->get_last_resumed_at());
$this->assertSame(33, $s->get_time_spent());
}
public function test_data_is_loaded_lazily_through_get_data_and_getmeta(): void
{
$repo = new session_repository();
$id = $this->row(40);
(new session_data_repository())->save($id, '{"k":1}');
$s = $repo->find($id);
$this->assertSame('{"k":1}', $s->get_data());
$this->assertSame('{"k":1}', $s->getMeta('data'));
$this->assertSame('{"k":1}', $repo->list_by_slot(40)[0]->get_data(), 'a list hydrates without data and still returns it on demand');
$this->assertSame('{"k":1}', $repo->list_by_slot_ids([40])[0]->getMeta('data'));
}
public function test_session_without_data_row_returns_null_and_does_not_break(): void
{
$repo = new session_repository();
$id = $this->row(40);
$s = $repo->find($id);
$this->assertNull($s->get_data());
$this->assertNull($s->getMeta('data'));
$this->assertSame('fallback', $s->getMeta('data', 'fallback'));
}
public function test_nulls_round_trip(): void
{
$repo = new session_repository();
$id = $repo->insert(['slotid' => 40, 'userid' => 8]);
$s = $repo->find($id);
$this->assertNull($s->get_started_at());
$this->assertNull($s->get_paused_at());
$this->assertSame(0, $s->get_time_spent());
$this->assertSame('in_progress', $s->get_session_status());
}
public function test_lookups_by_slot_and_slot_ids(): void
{
$repo = new session_repository();
$a = $this->row(40);
$b = $this->row(40, 'completed');
$c = $this->row(41);
$this->assertSame([$a, $b], array_map(static fn ($s) => $s->getId(), $repo->list_by_slot(40)));
$this->assertSame([$a, $b, $c], array_map(static fn ($s) => $s->getId(), $repo->list_by_slot_ids([40, 41])));
$this->assertSame([], $repo->list_by_slot_ids([]));
$this->assertEqualsCanonicalizing([$a, $b, $c], $repo->ids_by_slot_ids([41, 40]));
$this->assertNull($repo->find(999999));
}
public function test_status_updates_do_not_touch_the_data_row(): void
{
global $DB;
$repo = new session_repository();
$id = $this->row(40);
(new session_data_repository())->save($id, '{"big":true}');
$data_row = $DB->get_record('helico_session_data', ['sessionid' => $id], '*', MUST_EXIST);
$repo->update($id, ['sessionstatus' => 'paused', 'pausedat' => 200]);
$repo->update($id, ['pausedat' => null, 'timespent' => 9]);
$s = $repo->find($id);
$this->assertSame('paused', $s->get_session_status());
$this->assertNull($s->get_paused_at());
$this->assertSame(9, $s->get_time_spent());
$this->assertSame(8, $s->get_user_id());
$same = $DB->get_record('helico_session_data', ['sessionid' => $id], '*', MUST_EXIST);
$this->assertSame($data_row->timemodified, $same->timemodified, 'the payload row was not rewritten');
$this->assertSame('{"big":true}', $s->get_data());
}
public function test_data_save_updates_in_place_and_empty_deletes(): void
{
global $DB;
$data = new session_data_repository();
$id = $this->row(40);
$data->save($id, '{"v":1}');
$data->save($id, '{"v":2}');
$this->assertSame(1, $DB->count_records('helico_session_data', ['sessionid' => $id]));
$this->assertSame('{"v":2}', $data->find_data($id));
$data->save($id, null);
$this->assertNull($data->find_data($id));
$this->assertSame(0, $DB->count_records('helico_session_data', ['sessionid' => $id]));
$data->save($id, '');
$this->assertSame(0, $DB->count_records('helico_session_data', ['sessionid' => $id]));
}
public function test_delete_by_ids_removes_the_data_rows_too(): void
{
global $DB;
$repo = new session_repository();
$data = new session_data_repository();
$a = $this->row(40);
$b = $this->row(41);
$data->save($a, '{"a":1}');
$data->save($b, '{"b":1}');
$repo->delete_by_ids([$a]);
$this->assertNull($repo->find($a));
$this->assertNull($data->find_data($a));
$this->assertSame('{"b":1}', $data->find_data($b));
$this->assertSame(1, $DB->count_records('helico_session_data'));
}
public function test_service_create_active_latest_and_complete(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\engine\session\contract\session_service_interface::class);
$first = $service->create(['slot_id' => 40, 'user_id' => 8, 'courseid' => 2, 'data' => '{"a":1}']);
$this->assertSame('{"a":1}', $first->get_data());
$service->update_status((int) $first->getId(), 'paused');
$second = $service->create(['slot_id' => 40, 'user_id' => 8, 'courseid' => 2]);
$this->assertSame('in_progress', $second->get_session_status());
$this->assertNull($second->get_data());
$this->assertSame($second->getId(), $service->find_active_by_slot(40)->getId(), 'newest active session wins');
$this->assertSame([40 => $second->getId()], array_map(static fn ($s) => $s->getId(), $service->find_active_by_slot_ids([40, 41])));
$this->assertSame([40 => $second->getId()], array_map(static fn ($s) => $s->getId(), $service->find_latest_by_slot_ids([40])));
$this->assertCount(2, $service->find_by_slot(40));
$this->assertCount(2, $service->find_by_slot_ids([40])[40]);
$service->update_data((int) $second->getId(), '{"b":2}');
$service->update_paused_at((int) $second->getId(), 123);
$service->complete((int) $second->getId(), 77);
$done = $service->find_by_id((int) $second->getId());
$this->assertSame('completed', $done->get_session_status());
$this->assertSame(77, $done->get_time_spent());
$this->assertSame('{"b":2}', $done->get_data());
$this->assertSame(123, $done->get_paused_at());
$this->assertNotNull($service->find_active_by_slot(40), 'the paused first session is still active');
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter session_repository_test
Expected: FAIL (Class ... session_repository not found).
- Step 3: Implement
session_data_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\engine\session\repository;
defined('MOODLE_INTERNAL') || exit;
/**
* Table access for `helico_session_data`: the per-slot-type JSON payload of a session,
* kept out of `helico_session` so status/time updates and lookups never touch it.
*
* `sessionid` has a plain index, so a concurrent first save could insert twice; reads
* take the newest row and `save()` updates the newest row.
*/
final class session_data_repository
{
private const TABLE = 'helico_session_data';
public function find_data(int $session_id): ?string
{
global $DB;
$records = $DB->get_records(self::TABLE, ['sessionid' => $session_id], 'id DESC', 'id, sessiondata', 0, 1);
$first = reset($records);
return $first === false || $first->sessiondata === null || $first->sessiondata === '' ? null : (string) $first->sessiondata;
}
/**
* Stores the payload; `null` or `''` removes it.
*/
public function save(int $session_id, ?string $json): void
{
global $DB;
if ($json === null || $json === '') {
$DB->delete_records(self::TABLE, ['sessionid' => $session_id]);
return;
}
$now = time();
$records = $DB->get_records(self::TABLE, ['sessionid' => $session_id], 'id DESC', 'id', 0, 1);
$existing = reset($records);
if ($existing === false) {
$DB->insert_record(self::TABLE, (object) ['sessionid' => $session_id, 'sessiondata' => $json, 'timecreated' => $now, 'timemodified' => $now]);
return;
}
$DB->update_record(self::TABLE, (object) ['id' => $existing->id, 'sessiondata' => $json, 'timemodified' => $now]);
}
/**
* @param int[] $session_ids
*/
public function delete_by_session_ids(array $session_ids): void
{
global $DB;
$session_ids = array_values(array_filter(array_map('intval', $session_ids), static fn (int $id): bool => $id > 0));
if ($session_ids === []) {
return;
}
[$insql, $params] = $DB->get_in_or_equal($session_ids, SQL_PARAMS_NAMED, 'sess');
$DB->delete_records_select(self::TABLE, "sessionid {$insql}", $params);
}
}- Step 4: Implement
session_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\engine\session\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\engine\session\entity\session;
use stdClass;
/**
* Table access for `helico_session` (without the payload, see {@see session_data_repository}).
*/
final class session_repository
{
private const TABLE = 'helico_session';
public function find(int $id): ?session
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
/**
* @return list<session>
*/
public function list_by_slot(int $slot_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['slotid' => $slot_id], 'id ASC'));
}
/**
* @param int[] $slot_ids
*
* @return list<session>
*/
public function list_by_slot_ids(array $slot_ids): array
{
global $DB;
$slot_ids = $this->positive($slot_ids);
if ($slot_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'slot');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "slotid {$insql}", $params, 'id ASC'));
}
/**
* @param int[] $slot_ids
*
* @return list<int>
*/
public function ids_by_slot_ids(array $slot_ids): array
{
global $DB;
$slot_ids = $this->positive($slot_ids);
if ($slot_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($slot_ids, SQL_PARAMS_NAMED, 'slot');
return array_map('intval', $DB->get_fieldset_select(self::TABLE, 'id', "slotid {$insql} ORDER BY id ASC", $params));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns only the columns to change; `null` clears a column
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
/**
* Deletes the sessions and their payload rows.
*
* @param int[] $ids
*/
public function delete_by_ids(array $ids): void
{
global $DB;
$ids = $this->positive($ids);
if ($ids === []) {
return;
}
(new session_data_repository())->delete_by_session_ids($ids);
[$insql, $params] = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED, 'id');
$DB->delete_records_select(self::TABLE, "id {$insql}", $params);
}
/**
* @param int[] $values
*
* @return list<int>
*/
private function positive(array $values): array
{
return array_values(array_unique(array_filter(array_map('intval', $values), static fn (int $v): bool => $v > 0)));
}
private function hydrate(stdClass $row): session
{
return table_row_hydrator::hydrate(item_table_definitions::session(), session::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<session>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): session => $this->hydrate($row), $records));
}
}- Step 5: Make the entity load the payload lazily
The hydrator fills helico_session columns only, so data is absent from the entity’s metadata. In classes/extensions/engine/session/entity/session.php add (imports: Override, session_data_repository):
/**
* `data` lives in `helico_session_data` and is loaded on first access, so a list of
* sessions never reads the (up to 1.4 MB) payload unless a caller asks for it.
* Every access path — `get_data()`, `getMeta('data')`, `hasMeta('data')` — goes through here.
*/
#[Override]
public function getMeta(string $key, mixed $default = null): mixed
{
if ($key === 'data' && !array_key_exists('data', $this->metadata)) {
$this->metadata['data'] = $this->getId() !== null
? (new session_data_repository())->find_data((int) $this->getId())
: null;
}
return parent::getMeta($key, $default);
}
#[Override]
public function hasMeta(string $key): bool
{
if ($key === 'data') {
return $this->getMeta('data') !== null;
}
return parent::hasMeta($key);
}get_data() (:91) already reads $this->getMeta('data') and needs no change; dev_lifecycle_inspector_service.php:928 ($session->getMeta('data')) is covered by the override.
- Step 6: Run the repository tests
Run: <TEST_CMD> --filter 'session_repository_test::test_(hydration|data|session_without|nulls|lookups|status|delete)'
Expected: PASS (8 tests). The service test needs Step 7.
- Step 7: Switch
session_service
session_service does not extend item_service; it takes ItemServiceInterface $item_service. Replace the constructor so no DI change is needed (a new initializer is valid as a promoted-parameter default on PHP 8.4):
public function __construct(
private readonly session_repository $repository = new session_repository(),
private readonly session_data_repository $data = new session_data_repository(),
) {}Check the container registration: grep -rn "session_service" classes/extensions/engine/*.php classes/extensions/engine/session/*.php — if an explicit ->setArguments([...]) exists, change it to []. Then replace the persistence code, keeping every signature in session_service_interface and the PHP-side filtering exactly as it is:
| Method | New body |
|---|---|
find_by_id |
return $this->repository->find($id); |
find_active_by_slot |
$items = $this->repository->list_by_slot($slot_id); if ($items === []) { return null; } then the existing active-status filter and “newest id” usort, over $items instead of $result->items() |
find_active_by_slot_ids |
keep the slot-id normalisation, then foreach ($this->repository->list_by_slot_ids($slot_ids) as $item) into the existing active-status / newest-per-slot loop |
find_latest_by_slot_ids |
same, into the existing newest-per-slot loop |
find_by_slot_ids |
same, into the existing group-by-slot and sort loops |
find_by_slot |
return $this->repository->list_by_slot($slot_id); |
create(array $data) |
build the same item_dto as today, then $id = $this->repository->insert(table_row_hydrator::columns_from_dto(item_table_definitions::session(), $dto)); (data is not a mapped column, so it is ignored there), then $this->data->save($id, isset($data['data']) ? (string) $data['data'] : null); and $created = $this->repository->find($id); keeping the session_creation_failed guard |
update_status |
$this->repository->update($id, ['sessionstatus' => $session_status]); |
update_data |
$this->data->save($id, $data_json); — the session row is not rewritten |
update_time_spent |
$this->repository->update($id, ['timespent' => $time_spent]); |
update_paused_at |
$this->repository->update($id, ['pausedat' => $paused_at]); (null clears it) |
update_started_at |
$this->repository->update($id, ['startedat' => $started_at]); |
update_last_resumed_at |
$this->repository->update($id, ['lastresumedat' => $last_resumed_at]); |
complete |
$this->repository->update($id, ['sessionstatus' => session_status::COMPLETED->value, 'timespent' => $time_spent]); |
Remove the ItemServiceInterface, MiddagItemQueryBuilder, query_executor and Operator imports if nothing else uses them; add session_repository, session_data_repository, item_table_definitions and table_row_hydrator.
- Step 8: Run the session tests and the questionnaire tests
Run: <TEST_CMD> --filter 'session'
Expected: PASS (9 session tests; session_questionnaire_service only uses session_service).
- Step 9: Commit
git add classes/extensions/engine/session tests/extensions/engine/session
git commit -m "feat(engine): persist session in helico_session with the payload in helico_session_data"Task 14: unit_snapshot repository and service switch
unit_snapshot holds the second-largest payload: 124 rows with 15.6 MB (snapshot_data avg 128 KB, up to 252 KB), read by 12+ services on polled endpoints. It is created lazily per (study plan, unit) and shared across students; its parent is the product study plan (EAV, stays).
Files:
- Create:
classes/extensions/engine/plan/repository/unit_snapshot_repository.php - Modify:
classes/extensions/engine/plan/service/unit_snapshot_service.php(constructor:41-46; finders:81-200;apply_audio_refresh:416;persist_snapshot:~272-336) - Test:
tests/extensions/engine/plan/unit_snapshot_repository_test.php
Interfaces:
-
Consumes:
item_table_definitions::unit_snapshot(),table_row_hydrator::hydrate()(Task 3). -
Produces
unit_snapshot_repository:find(int $id): ?unit_snapshotfind_by_plan_and_unit(int $study_plan_id, int $unit_id): ?unit_snapshot(lowest id, as the olditems()[0])list_by_study_plan(int $study_plan_id): list<unit_snapshot>,list_by_plan_and_units(int $study_plan_id, array $unit_ids): list<…>,list_by_units(array $unit_ids): list<…>(allid ASC)insert(array $columns): int,update(int $id, array $columns): void
-
Step 1: Write the failing tests
<?php
declare(strict_types=1);
namespace local_helico\extensions\engine\plan;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\content\base\snapshot\entity\unit_snapshot;
use local_helico\extensions\engine\plan\repository\unit_snapshot_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class unit_snapshot_repository_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
private function snap(int $plan, int $unit, string $data = '{"topics":[]}'): int
{
return (new unit_snapshot_repository())->insert([
'studyplanid' => $plan, 'unitid' => $unit, 'sourceversion' => '1',
'snapshotdata' => $data, 'contenthash' => hash('sha256', $data), 'flashcard' => '[]',
]);
}
public function test_hydration_keeps_parent_unit_version_data_hash_and_flashcard(): void
{
$repo = new unit_snapshot_repository();
$id = $this->snap(218, 96, '{"topics":[{"id":1}]}');
$s = $repo->find($id);
$this->assertInstanceOf(unit_snapshot::class, $s);
$this->assertSame(218, $s->getParent());
$this->assertSame(96, $s->get_source_unit_id());
$this->assertSame('1', $s->get_source_version());
$this->assertSame('{"topics":[{"id":1}]}', $s->get_snapshot_data());
$this->assertSame(hash('sha256', '{"topics":[{"id":1}]}'), $s->get_content_hash());
$this->assertSame('[]', $s->getMeta('flashcard'));
$this->assertNull($repo->find(999999));
}
public function test_lookups(): void
{
$repo = new unit_snapshot_repository();
$a = $this->snap(218, 96);
$b = $this->snap(218, 98);
$c = $this->snap(219, 96);
$dup = $this->snap(218, 96, '{"dup":true}');
$this->assertSame($a, $repo->find_by_plan_and_unit(218, 96)->getId(), 'a duplicate resolves to the first, as before');
$this->assertNull($repo->find_by_plan_and_unit(218, 99));
$this->assertSame([$a, $b, $dup], array_map(static fn ($s) => $s->getId(), $repo->list_by_study_plan(218)));
$this->assertSame([$b], array_map(static fn ($s) => $s->getId(), $repo->list_by_plan_and_units(218, [98, 99])));
$this->assertSame([], $repo->list_by_plan_and_units(218, []));
$this->assertSame([$a, $c, $dup], array_map(static fn ($s) => $s->getId(), $repo->list_by_units([96])));
$this->assertSame([], $repo->list_by_units([]));
}
public function test_update_snapshot_data_keeps_the_hash_and_other_columns(): void
{
$repo = new unit_snapshot_repository();
$id = $this->snap(218, 96, '{"v":1}');
$hash = $repo->find($id)->get_content_hash();
$repo->update($id, ['snapshotdata' => '{"v":2,"audios":[1]}']);
$s = $repo->find($id);
$this->assertSame('{"v":2,"audios":[1]}', $s->get_snapshot_data());
$this->assertSame($hash, $s->get_content_hash(), 'audio refresh must not change the frozen content hash');
$this->assertSame(96, $s->get_source_unit_id());
}
}- Step 2: Run to verify it fails
Run: <TEST_CMD> --filter unit_snapshot_repository_test
Expected: FAIL (Class ... unit_snapshot_repository not found).
- Step 3: Implement
unit_snapshot_repository
<?php
declare(strict_types=1);
/**
* HÉLICO Local
*
* @package local_helico
*
* @author Michael Meneses <michael@middag.com.br>
* @author Gabriel Sousa <gabriel.sousa@middag.com.br>
* @copyright 2026 MIDDAG (https://www.middag.com.br)
* @license commercial
*/
namespace local_helico\extensions\engine\plan\repository;
defined('MOODLE_INTERNAL') || exit;
use local_helico\base\persistence\item_table_definitions;
use local_helico\base\persistence\table_row_hydrator;
use local_helico\extensions\content\base\snapshot\entity\unit_snapshot;
use stdClass;
/**
* Table access for `helico_unit_snapshot`.
*/
final class unit_snapshot_repository
{
private const TABLE = 'helico_unit_snapshot';
public function find(int $id): ?unit_snapshot
{
global $DB;
$row = $DB->get_record(self::TABLE, ['id' => $id]);
return $row === false ? null : $this->hydrate($row);
}
public function find_by_plan_and_unit(int $study_plan_id, int $unit_id): ?unit_snapshot
{
global $DB;
$records = $DB->get_records(self::TABLE, ['studyplanid' => $study_plan_id, 'unitid' => $unit_id], 'id ASC', '*', 0, 1);
$first = reset($records);
return $first === false ? null : $this->hydrate($first);
}
/**
* @return list<unit_snapshot>
*/
public function list_by_study_plan(int $study_plan_id): array
{
global $DB;
return $this->hydrate_all($DB->get_records(self::TABLE, ['studyplanid' => $study_plan_id], 'id ASC'));
}
/**
* @param int[] $unit_ids
*
* @return list<unit_snapshot>
*/
public function list_by_plan_and_units(int $study_plan_id, array $unit_ids): array
{
global $DB;
$unit_ids = $this->positive($unit_ids);
if ($unit_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($unit_ids, SQL_PARAMS_NAMED, 'unit');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "studyplanid = :plan AND unitid {$insql}", ['plan' => $study_plan_id] + $params, 'id ASC'));
}
/**
* @param int[] $unit_ids
*
* @return list<unit_snapshot>
*/
public function list_by_units(array $unit_ids): array
{
global $DB;
$unit_ids = $this->positive($unit_ids);
if ($unit_ids === []) {
return [];
}
[$insql, $params] = $DB->get_in_or_equal($unit_ids, SQL_PARAMS_NAMED, 'unit');
return $this->hydrate_all($DB->get_records_select(self::TABLE, "unitid {$insql}", $params, 'id ASC'));
}
/**
* @param array<string, mixed> $columns
*/
public function insert(array $columns): int
{
global $DB;
$now = time();
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns);
return (int) $DB->insert_record(self::TABLE, (object) ($columns + ['timecreated' => $now, 'timemodified' => $now]));
}
/**
* @param array<string, mixed> $columns only the columns to change
*/
public function update(int $id, array $columns): void
{
global $DB;
\local_helico\base\persistence\table_row_validator::assert(self::TABLE, $columns, partial: true);
$DB->update_record(self::TABLE, (object) ($columns + ['id' => $id, 'timemodified' => time()]));
}
/**
* @param int[] $values
*
* @return list<int>
*/
private function positive(array $values): array
{
return array_values(array_unique(array_filter(array_map('intval', $values), static fn (int $v): bool => $v > 0)));
}
private function hydrate(stdClass $row): unit_snapshot
{
return table_row_hydrator::hydrate(item_table_definitions::unit_snapshot(), unit_snapshot::class, $row);
}
/**
* @param array<int, stdClass> $records
*
* @return list<unit_snapshot>
*/
private function hydrate_all(array $records): array
{
return array_values(array_map(fn (stdClass $row): unit_snapshot => $this->hydrate($row), $records));
}
}- Step 4: Run the repository tests
Run: <TEST_CMD> --filter unit_snapshot_repository_test
Expected: PASS (3 tests).
- Step 5: Switch
unit_snapshot_service
unit_snapshot_service does not extend item_service. It keeps its ItemServiceInterface $item_service argument: the service also uses it to look up the live unit (find($unit_id) in is_consistent, live_audio_relations, persist_snapshot), and unit stays EAV. Add the repository as a trailing argument with a default so the container needs no change:
public function __construct(
private readonly ItemServiceInterface $item_service,
private readonly unit_content_service_interface $unit_content_service,
private readonly SignalDispatcherInterface $dispatcher,
private readonly discipline_service_interface $discipline_service,
private readonly unit_snapshot_repository $repository = new unit_snapshot_repository(),
) {}Replace only the snapshot persistence, keeping every signature, the lock in get_or_create, and the dedup loops:
| Method | New body |
|---|---|
find_by_study_plan_and_unit |
return $this->repository->find_by_plan_and_unit($study_plan_id, $unit_id); |
find_all_by_study_plan |
$items = $this->repository->list_by_study_plan($study_plan_id); if ($items === []) { return []; } then the existing “one snapshot per source unit” dedup loop over $items |
find_by_study_plan_and_units |
keep the unit-id normalisation, then foreach ($this->repository->list_by_plan_and_units($study_plan_id, array_keys($normalized)) as $item) into the existing $by_unit loop |
find_all_by_units |
keep the normalisation, then return $this->repository->list_by_units(array_keys($normalized)); |
apply_audio_refresh |
replace $this->item_service->update(new item_dto(...)) with $this->repository->update((int) $snapshot->getId(), ['snapshotdata' => json_encode($data, self::JSON_FLAGS)]); |
persist_snapshot |
replace $item = $this->item_service->create(new item_dto(...)) and $snapshot_id = (int) $item->getId(); with $snapshot_id = $this->repository->insert(['studyplanid' => $study_plan_id, 'unitid' => $unit_id, 'sourceversion' => $source_version, 'snapshotdata' => json_encode($snapshot_data, self::JSON_FLAGS), 'contenthash' => $content_hash, 'flashcard' => $flashcard_meta]);; the signals and the final find_by_study_plan_and_unit re-fetch stay |
Do not touch the $this->item_service->find($unit_id) calls. Add the unit_snapshot_repository import and remove MiddagItemQueryBuilder, query_executor, Operator and item_dto if nothing else in the file uses them.
Add to unit_snapshot_repository_test.php:
public function test_service_find_all_dedups_a_duplicate_to_the_first_snapshot(): void
{
$service = \local_middag\base\middag::get(\local_helico\extensions\engine\plan\contract\unit_snapshot_service_interface::class);
$first = $this->snap(218, 96, '{"v":"first"}');
$this->snap(218, 96, '{"v":"dup"}');
$other = $this->snap(218, 98);
$all = $service->find_all_by_study_plan(218);
$this->assertSame([$first, $other], array_map(static fn ($s) => $s->getId(), $all));
$this->assertSame($first, $service->find_by_study_plan_and_unit(218, 96)->getId());
$this->assertSame([98], array_keys($service->find_by_study_plan_and_units(218, [98, 99])));
$this->assertCount(3, $service->find_all_by_units([96, 98]));
}(Use the container resolver neighbouring tests use if middag::get is not it.)
- Step 6: Run the engine/plan tests
Run: <TEST_CMD> --filter 'snapshot|plan'
Expected: PASS.
- Step 7: Commit
git add classes/extensions/engine/plan tests/extensions/engine/plan
git commit -m "feat(engine): persist unit_snapshot in helico_unit_snapshot"Task 15: Raw-SQL sites, orphan-free reset, generic-id audit
Files:
- Modify:
classes/extensions/admin/listener/enrolment_reset_listener_service.php:91,131,300(results, reports, cascade) - Modify:
classes/extensions/admin/service/dev_lifecycle_inspector_service.php:704,750,944,970 - Modify:
classes/extensions/admin/listener/cda_force_complete_listener_service.php:616,full_plan_complete_listener_service.php:444,module_skip_to_review_listener_service.php:185(only if the JOIN targets a Phase 1 type — Step 1 decides) - Test:
tests/extensions/admin/enrolment_reset_cascade_test.php
Interfaces:
-
Consumes:
result_repository::delete_by_enrolment,report_repository::delete_by_enrolment,response_repository::delete_by_session_ids,classification_repository::delete_by_student_plan_ids(Tasks 5–8). -
Step 1: Classify every raw
helico_itemmetaJOIN
Run: cd /var/www/middag-work/moodle-local_helico && grep -rn "helico_itemmeta" --include='*.php' classes | grep -v "^classes/extensions/admin/service/dev_lifecycle"
For each hit, read ±15 lines and record which type the query filters. Only hits whose type is one of the sixteen migrated types need a change; hits on student_plan, enrolment, study_*, cda_block, unit, unit_content stay (EAV). Checked on 2026-10-02: the three JOINs at cda_force_complete_listener_service.php:616, full_plan_complete_listener_service.php:444 and module_skip_to_review_listener_service.php:185 are all resolve_student_plan() lookups of student_plan by enrolment_id, so they need no change; the only raw-SQL consumers of migrated types are enrolment_reset_listener_service and dev_lifecycle_inspector_service.
- Step 2: Write the failing cascade test
<?php
declare(strict_types=1);
namespace local_helico\extensions\admin;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use local_helico\extensions\activity\response\repository\response_repository;
use local_helico\extensions\activity\result\repository\result_repository;
use local_helico\extensions\metrics\classification\repository\classification_repository;
use local_helico\extensions\metrics\report\repository\report_repository;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class enrolment_reset_cascade_test extends advanced_testcase
{
protected function setUp(): void
{
parent::setUp();
$this->resetAfterTest(true);
}
public function test_reset_removes_responses_results_classifications_and_reports(): void
{
$responses = new response_repository();
$results = new result_repository();
$classifications = new classification_repository();
$reports = new report_repository();
$responses->insert(['sessionid' => 50, 'questionid' => 1]);
$results->save(['sessionid' => 50, 'enrolmentid' => 7]);
$classifications->insert(['studentplanid' => 60, 'unitid' => 1, 'level' => 'basico']);
$reports->upsert('report:7:overall:all', ['enrolmentid' => 7, 'scope' => 'overall']);
$listener = \local_middag\base\middag::get(\local_helico\extensions\admin\listener\enrolment_reset_listener_service::class);
$listener->cascade_phase1_tables(7, [50], 60);
$this->assertSame([], $responses->find_by_session(50));
$this->assertNull($results->find_by_session(50));
$this->assertSame([], $classifications->find_by_student_plan(60));
$this->assertNull($reports->find_by_idnumber('report:7:overall:all'));
}
}- Step 3: Run to verify it fails
Run: <TEST_CMD> --filter enrolment_reset_cascade_test
Expected: FAIL (Call to undefined method ... cascade_phase1_tables).
- Step 4: Implement the cascade in
enrolment_reset_listener_service
Add a public method (testable seam) and call it from the existing reset flow:
/**
* Deletes the Phase 1 dedicated-table rows tied to an enrolment: results and
* reports by enrolment, responses by session, classifications by student plan.
* Responses and classifications used to be left orphaned by this reset.
*
* @param int[] $session_ids
*/
public function cascade_phase1_tables(int $enrolment_id, array $session_ids, ?int $student_plan_id): void
{
(new result_repository())->delete_by_enrolment($enrolment_id);
(new report_repository())->delete_by_enrolment($enrolment_id);
(new response_repository())->delete_by_session_ids($session_ids);
if ($student_plan_id !== null) {
(new classification_repository())->delete_by_student_plan_ids([$student_plan_id]);
}
}In the existing flow:
-
Replace step 1 (
:90-92,activity_resultviafind_items_ids_by_type_and_meta+cascade_delete_items) and step 9 (:127-132,metrics_report) by a single call tocascade_phase1_tables($enrolment_id, $session_ids, $student_plan_id).$session_idsis computed at:95-97before the session delete, so move the call to just beforecascade_delete_items($session_ids)and keep$session_ids = []when$student_plan_id === null. -
Add the matching
usestatements for the four repositories. -
Step 4b: Slot tables in the reset (and the orphan-edge fix)
Add to tests/extensions/admin/enrolment_reset_cascade_test.php:
public function test_reset_removes_slots_with_their_lock_edges_and_scope_refs(): void
{
$slots = new \local_helico\extensions\engine\algorithm\repository\slot_repository();
$locks = new \local_helico\extensions\engine\algorithm\repository\slot_lock_repository();
$refs = new \local_helico\extensions\engine\algorithm\repository\slot_scope_ref_repository();
$mine = $slots->insert(['studentplanid' => 60, 'uuid' => 'a', 'slotstatus' => 'not_started']);
$upstream = $slots->insert(['studentplanid' => 60, 'uuid' => 'b', 'slotstatus' => 'not_started']);
$other_plan = $slots->insert(['studentplanid' => 61, 'uuid' => 'c', 'slotstatus' => 'not_started']);
$locks->replace_for_slot($mine, [['dependsonslotid' => $upstream]]);
$locks->replace_for_slot($other_plan, [['dependsonslotid' => $mine]]);
$refs->replace_for_slot($mine, [['kind' => 'unit', 'refid' => 5, 'name' => 'U5', 'sortorder' => 0]]);
$listener = \local_middag\base\middag::get(\local_helico\extensions\admin\listener\enrolment_reset_listener_service::class);
$deleted = $listener->cascade_slot_tables(60);
$this->assertEqualsCanonicalizing([$mine, $upstream], $deleted);
$this->assertSame([], $slots->ids_by_student_plan(60));
$this->assertSame([], $locks->list_by_slot($mine));
$this->assertSame([], $locks->list_by_slot($other_plan), 'an edge pointing at a deleted slot is removed');
$this->assertSame([], $refs->list_by_slot($mine));
$this->assertSame([$other_plan], $slots->ids_by_student_plan(61));
}In enrolment_reset_listener_service add the seam and use it (imports for slot_repository, slot_lock_repository, slot_scope_ref_repository):
/**
* Deletes the student plan's slots plus their lock edges (both directions) and scope refs.
*
* @return list<int> the deleted slot ids, so the caller can still find the sessions that point at them
*/
public function cascade_slot_tables(int $student_plan_id): array
{
$slots = new slot_repository();
$slot_ids = $slots->ids_by_student_plan($student_plan_id);
(new slot_lock_repository())->delete_by_slot_ids($slot_ids);
(new slot_scope_ref_repository())->delete_by_slot_ids($slot_ids);
$slots->delete_by_ids($slot_ids);
return $slot_ids;
}In the reset flow (:95-103) replace the $slot_ids = $this->find_items_ids_by_type_and_meta(slot::TYPE, 'student_plan_id', $student_plan_id); line with $slot_ids = (new slot_repository())->ids_by_student_plan($student_plan_id); (sessions are still EAV and are found by slot_id), and replace step 3 ($this->cascade_delete_items($slot_ids);) with $this->cascade_slot_tables($student_plan_id);. Also replace the session lookup ($session_ids = $slot_ids !== [] ? $this->find_items_ids_by_type_and_meta_in(engine_session::TYPE, 'slot_id', $slot_ids) : [];) with $session_ids = (new session_repository())->ids_by_slot_ids($slot_ids); and the session deletion ($this->cascade_delete_items($session_ids);) with (new session_repository())->delete_by_ids($session_ids); (import session_repository). Keep the session deletion before the slot deletion, as it is today, and keep cascade_phase1_tables(...) (which removes the responses of those sessions) before the session deletion.
Run: <TEST_CMD> --filter enrolment_reset_cascade_test
Expected: PASS (2 tests).
- Step 4c: Notebook tables in the reset
Add to tests/extensions/admin/enrolment_reset_cascade_test.php:
public function test_reset_removes_notebook_artifacts_with_annotations_and_versions(): void
{
$artifacts = new \local_helico\extensions\activity\productive\notebook_artifact\repository\notebook_artifact_repository();
$annotations = new \local_helico\extensions\activity\productive\notebook_annotation\repository\notebook_annotation_repository();
$versions = new \local_helico\extensions\activity\productive\artifact_versioning\repository\notebook_version_repository();
$mine = $artifacts->insert(['enrolmentid' => 7, 'userid' => 8]);
$other = $artifacts->insert(['enrolmentid' => 9, 'userid' => 8]);
$annotations->insert(['artifactid' => $mine, 'annotationkey' => 'k1']);
$annotations->insert(['artifactid' => $other, 'annotationkey' => 'k1']);
$versions->insert(['artifactid' => $mine, 'versionnumber' => 1]);
$listener = \local_middag\base\middag::get(\local_helico\extensions\admin\listener\enrolment_reset_listener_service::class);
$deleted = $listener->cascade_notebook_tables(7);
$this->assertSame([$mine], $deleted);
$this->assertNull($artifacts->find($mine));
$this->assertSame([], $annotations->list_by_artifact($mine));
$this->assertSame([], $versions->list_by_artifact($mine));
$this->assertNotNull($artifacts->find($other));
$this->assertCount(1, $annotations->list_by_artifact($other));
}In enrolment_reset_listener_service add (imports for the three repositories):
/**
* Deletes the enrolment's notebook artifacts plus their annotations and versions.
*
* @return list<int> the deleted artifact ids
*/
public function cascade_notebook_tables(int $enrolment_id): array
{
$artifacts = new notebook_artifact_repository();
$artifact_ids = $artifacts->ids_by_enrolment($enrolment_id);
(new notebook_annotation_repository())->delete_by_artifact_ids($artifact_ids);
(new notebook_version_repository())->delete_by_artifact_ids($artifact_ids);
$artifacts->delete_by_ids($artifact_ids);
return $artifact_ids;
}In the reset flow replace the whole step 10 block (:134-143: find_items_ids_by_type_and_meta(notebook_artifact::TYPE, ...), the annotation/version lookups by parent and the three cascade_delete_items calls) with $this->cascade_notebook_tables($enrolment_id);. Step 11 (clear_meta_value($enrolment_id, ...)) stays: enrolment is still EAV.
Run: <TEST_CMD> --filter enrolment_reset_cascade_test
Expected: PASS (3 tests).
- Step 5: Update
dev_lifecycle_inspector_service
At :668 (type: slot::TYPE), :704 (classification query), :726/:777 (lock_dependency_entity), :750, :944 (type: response::TYPE) and :970 (type: activity_result::TYPE): replace the helico_items reads with the corresponding repository (find_by_student_plan, find_by_session, find_by_session_ids, find_by_student_plan), keeping the payload shape each node already returns. dump_raw_metadata() (:1204) dumps helico_itemmeta by item id; for the sixteen migrated types the EAV rows left behind are stale, so for those types build raw_metadata from the table row instead ($DB->get_record($definition->table, ['id' => $id]) cast to column => value) and keep the generic dump, with its 500-row cap, for the remaining EAV types.
- Step 6: Audit generic id lookups
Run: grep -rnE "item_service->find\(" --include='*.php' classes | grep -iE "response|result|classification|report|slot|session|snapshot|notebook|artifact|annotation|submission|correction|criterion|assign_link|lock"
For each hit that resolves an id of a migrated type through the generic item service, switch it to the type’s repository find(); record the list in the commit body. If none, state “none found”. The guard test in Step 6b catches the query-builder and raw-SQL cases; this grep is for the generic find(int $id) that no static rule can attribute to a type.
- Step 6b: Guard test — migrated types are never read from the EAV
After the switch a leftover EAV-style query does not fail: it reads the stale pre-migration rows. This test fails the build instead. It scans classes/ for the patterns that would read a migrated type from helico_items (->entity() is the allowed way, so it is not flagged), resolving each file’s use aliases (the code imports entities under aliases such as criterion_score_entity and engine_session).
tests/regression/migrated_types_not_read_from_eav_test.php:
<?php
declare(strict_types=1);
namespace local_helico\regression;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use FilesystemIterator;
use PHPUnit\Framework\Attributes\Group;
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;
#[Group('local_helico')]
final class migrated_types_not_read_from_eav_test extends advanced_testcase
{
/** Types now stored in dedicated tables. */
private const MIGRATED_TYPES = [
'response', 'activity_result', 'classification', 'metrics_report', 'exam_submission', 'exam_assign_link',
'exam_correction', 'criterion_score', 'slot', 'slot_scope_ref', 'lock_dependency', 'notebook_artifact',
'notebook_annotation', 'artifact_version', 'session', 'unit_snapshot',
];
/** Files that read the EAV rows on purpose. */
private const ALLOWED = [
'base/persistence/item_table_migrator.php',
'base/persistence/migration/session_data_copier.php',
'base/persistence/migration/migration_2026100201_eav_to_tables.php',
'base/persistence/item_table_definitions.php',
];
/**
* @return array<string, string> FQCN => type for every entity whose TYPE constant is a migrated type
*/
private function migrated_entities(string $root): array
{
$entities = [];
foreach ($this->php_files($root) as $file) {
$src = (string) file_get_contents($file);
if (!preg_match("/const\\s+TYPE\\s*=\\s*'([a-z_]+)'/", $src, $t) || !in_array($t[1], self::MIGRATED_TYPES, true)) {
continue;
}
if (preg_match('/^namespace\\s+([\\w\\\\]+);/m', $src, $ns) && preg_match('/^(?:final\\s+|abstract\\s+)?class\\s+(\\w+)/m', $src, $c)) {
$entities[$ns[1] . '\\' . $c[1]] = $t[1];
}
}
return $entities;
}
/**
* @return list<string>
*/
private function php_files(string $root): array
{
$files = [];
$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($root, FilesystemIterator::SKIP_DOTS));
foreach ($it as $f) {
if ($f->isFile() && $f->getExtension() === 'php') {
$files[] = $f->getPathname();
}
}
sort($files);
return $files;
}
public function test_no_class_reads_a_migrated_type_through_the_eav(): void
{
global $CFG;
$root = $CFG->dirroot . '/local/helico/classes';
$entities = $this->migrated_entities($root);
$this->assertGreaterThanOrEqual(15, count($entities), 'the scan must find the migrated entity classes');
$violations = [];
foreach ($this->php_files($root) as $file) {
$relative = substr($file, strlen($root) + 1);
if (in_array($relative, self::ALLOWED, true)) {
continue;
}
$src = (string) file_get_contents($file);
// Aliases under which this file imports a migrated entity.
$aliases = [];
if (preg_match_all('/^use\\s+([\\w\\\\]+)(?:\\s+as\\s+(\\w+))?;/m', $src, $uses, PREG_SET_ORDER)) {
foreach ($uses as $u) {
if (isset($entities[$u[1]])) {
$aliases[] = $u[2] ?? substr($u[1], (int) strrpos($u[1], '\\') + 1);
}
}
}
foreach ($aliases as $alias) {
$q = preg_quote($alias, '/');
if (preg_match("/->where\\(\\s*'type'\\s*,\\s*Operator::Eq\\s*,\\s*{$q}::TYPE\\s*\\)/", $src)) {
$violations[] = "$relative: where('type', …, {$alias}::TYPE) reads helico_items";
}
if (preg_match("/->domain\\(\\s*{$q}::class\\s*\\)/", $src)) {
$violations[] = "$relative: ->domain({$alias}::class) targets helico_items; use ->entity() with typed_query::execute()";
}
if (preg_match('/helico_item(?:s|meta)/', $src) && preg_match("/{$q}::TYPE/", $src)) {
$violations[] = "$relative: raw helico_items SQL in a file that names {$alias}::TYPE";
}
}
// A literal type in raw SQL against the EAV tables.
foreach (self::MIGRATED_TYPES as $type) {
if (preg_match("/helico_items[^;]{0,400}'type'\\s*=>\\s*'{$type}'/s", $src)) {
$violations[] = "$relative: raw SQL over helico_items with type '$type'";
}
}
}
$this->assertSame([], $violations, "Migrated types must be read through their repository:\n" . implode("\n", $violations));
}
}Run: <TEST_CMD> --filter migrated_types_not_read_from_eav_test
Expected: PASS once Tasks 5–14 and Steps 4–5 above are done. Until then it fails and lists every file still reading the EAV, which is the to-do list. A file that only builds a label from X::TYPE (for example the inspector’s lifecycle_node_dto(type: slot::TYPE, …)) contains none of these patterns and is not flagged; do not add a file to ALLOWED unless the message names a real read.
- Step 6c: Audit the item getters the tables no longer fill
Run: grep -rnE "->(getFullname|getIdnumber|getVersion|getShortname|getUsercreated)\(\)" --include='*.php' classes
For every hit, find the type of the receiver. If it is one of the 16 migrated entities, either (a) the value is available from a column (slot::getFullname() is the label), (b) the call only builds a label and can use the entity’s own getters (for example Plano do Aluno #<id>), or (c) it needs a column that the table lacks — then add the column to the descriptor and the definition. Receivers that are unit, unit_content, trail, study_plan*, enrolment, student_plan, study_*, discipline, file_word stay EAV and need nothing. Record the reviewed list in the commit body (“none affected” is a valid result).
- Step 6d: Guard test — every repository validates before writing
tests/regression/repositories_validate_rows_test.php:
<?php
declare(strict_types=1);
namespace local_helico\regression;
defined('MOODLE_INTERNAL') || exit;
use advanced_testcase;
use PHPUnit\Framework\Attributes\Group;
#[Group('local_helico')]
final class repositories_validate_rows_test extends advanced_testcase
{
public function test_every_repository_that_writes_a_dedicated_table_validates_first(): void
{
global $CFG;
$root = $CFG->dirroot . '/local/helico/classes';
$checked = 0;
$missing = [];
foreach (new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($root, \FilesystemIterator::SKIP_DOTS)) as $f) {
if (!$f->isFile() || !str_ends_with($f->getFilename(), '_repository.php')) {
continue;
}
$src = (string) file_get_contents($f->getPathname());
// Repositories that write through self::TABLE (helico_session_data and the bulk copiers are plain payload writes).
if (!preg_match('/->(?:insert|update)_record\(self::TABLE/', $src) || str_contains($src, "TABLE = 'helico_session_data'")) {
continue;
}
$checked++;
if (!str_contains($src, 'table_row_validator::assert(self::TABLE')) {
$missing[] = $f->getFilename();
}
}
$this->assertGreaterThanOrEqual(10, $checked, 'the scan must find the repositories');
$this->assertSame([], $missing, 'Repositories writing without table_row_validator::assert(): ' . implode(', ', $missing));
}
}Run: <TEST_CMD> --filter repositories_validate_rows_test
Expected: PASS once Tasks 5–14 are done.
- Step 7: Run tests and commit
Run: <TEST_CMD> --filter enrolment_reset_cascade_test then <TEST_CMD> (whole suite).
Expected: PASS.
git add classes/extensions/admin tests/extensions/admin/enrolment_reset_cascade_test.php
git commit -m "fix(admin): reset also removes response, classification, result, slot, lock and notebook rows"Task 16: Run on dev, verify, and record the real state in the docs
Files:
-
Modify:
docs/plataforma/adrs/adr-10_persistencia-eav-e-criterios-de-uso.md -
Modify:
docs/plataforma/adrs/ref/ref-10-d_mapa-storage-por-entity.md -
Step 1: Dry-run on dev
Run (inside the container via make shell): php local/helico/cli/migrate_items_to_tables.php --dry-run
Expected (dev as of 2026-10-02): response migrated=9238 orphans_skipped=7964, activity_result migrated=597 orphans_skipped=217, classification migrated=2630 orphans_skipped=1338, metrics_report migrated=27 orphans_skipped=0, exam_submission migrated=8 orphans_skipped=0 (the 2 rows with no slot are copied), exam_assign_link migrated=7 orphans_skipped=0, exam_correction migrated=3 orphans_skipped=0, criterion_score migrated=32 orphans_skipped=0, slot migrated=1765 orphans_skipped=0, lock_dependency migrated=1597 orphans_skipped=1237, slot_scope_ref migrated=0 orphans_skipped=0, notebook_artifact migrated=9371 orphans_skipped=0, artifact_version migrated=7133 orphans_skipped=0, notebook_annotation migrated=359 orphans_skipped=0, session migrated=642 orphans_skipped=0, session data copied=642, unit_snapshot migrated=124 orphans_skipped=0. If numbers differ, the dev data changed — compare with the live SELECT counts before continuing.
- Step 2: Run the real upgrade
Run: cd /var/www/docker-moodle-helico && make moodle CMD="upgrade.php --non-interactive"
Expected: seventeen local_helico: <type> -> <table> migrated=… lines, exit 0.
- Step 3: Verify counts and integrity with read-only SQL
SELECT 'response' t, COUNT(*) FROM mdl_helico_response
UNION ALL SELECT 'result', COUNT(*) FROM mdl_helico_result
UNION ALL SELECT 'classification', COUNT(*) FROM mdl_helico_classification
UNION ALL SELECT 'report', COUNT(*) FROM mdl_helico_metrics_report
UNION ALL SELECT 'exam_submission', COUNT(*) FROM mdl_helico_exam_submission
UNION ALL SELECT 'exam_assign_link', COUNT(*) FROM mdl_helico_exam_assign_link
UNION ALL SELECT 'exam_correction', COUNT(*) FROM mdl_helico_exam_correction
UNION ALL SELECT 'criterion_score', COUNT(*) FROM mdl_helico_criterion_score
UNION ALL SELECT 'slot', COUNT(*) FROM mdl_helico_slot
UNION ALL SELECT 'slot_lock', COUNT(*) FROM mdl_helico_slot_lock
UNION ALL SELECT 'slot_scope_ref', COUNT(*) FROM mdl_helico_slot_scope_ref
UNION ALL SELECT 'notebook_artifact', COUNT(*) FROM mdl_helico_notebook_artifact
UNION ALL SELECT 'notebook_version', COUNT(*) FROM mdl_helico_notebook_version
UNION ALL SELECT 'notebook_annotation', COUNT(*) FROM mdl_helico_notebook_annotation
UNION ALL SELECT 'session', COUNT(*) FROM mdl_helico_session
UNION ALL SELECT 'session_data', COUNT(*) FROM mdl_helico_session_data
UNION ALL SELECT 'unit_snapshot', COUNT(*) FROM mdl_helico_unit_snapshot;
-- sessions point at an existing slot, snapshots at an existing study plan; payload moved intact
SELECT (SELECT COUNT(*) FROM mdl_helico_session s WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_items i WHERE i.id = s.slotid)) AS orphan_sessions,
(SELECT COUNT(*) FROM mdl_helico_unit_snapshot u WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_items i WHERE i.id = u.studyplanid)) AS orphan_snapshots,
(SELECT COUNT(*) FROM mdl_helico_session_data d WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_session s WHERE s.id = d.sessionid)) AS orphan_session_data,
(SELECT ROUND(SUM(LENGTH(sessiondata))/1048576.0, 1) FROM mdl_helico_session_data) AS session_data_mb,
(SELECT ROUND(SUM(LENGTH(snapshotdata))/1048576.0, 1) FROM mdl_helico_unit_snapshot) AS snapshot_data_mb,
(SELECT COUNT(*) FROM (SELECT studyplanid, unitid FROM mdl_helico_unit_snapshot GROUP BY 1, 2 HAVING COUNT(*) > 1) d) AS duplicate_snapshots;
-- every artifact still points at an existing enrolment (EAV); versions and annotations at an existing artifact
SELECT (SELECT COUNT(*) FROM mdl_helico_notebook_artifact a WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_items e WHERE e.id = a.enrolmentid)) AS orphan_artifacts,
(SELECT COUNT(*) FROM mdl_helico_notebook_version v WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_notebook_artifact a WHERE a.id = v.artifactid)) AS orphan_versions,
(SELECT COUNT(*) FROM mdl_helico_notebook_annotation n WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_notebook_artifact a WHERE a.id = n.artifactid)) AS orphan_annotations,
(SELECT ROUND(SUM(LENGTH(editorstatejson))/1048576.0, 1) FROM mdl_helico_notebook_artifact) AS editor_state_mb;
-- slots point at an existing student plan; every edge points at existing slots
SELECT (SELECT COUNT(*) FROM mdl_helico_slot s WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_items p WHERE p.id = s.studentplanid)) AS orphan_slots,
(SELECT COUNT(*) FROM mdl_helico_slot_lock l WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_slot s WHERE s.id = l.slotid)) AS orphan_edges,
(SELECT COUNT(*) FROM mdl_helico_slot_lock l WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_slot s WHERE s.id = l.dependsonslotid)) AS dangling_upstream;
-- the lookup that cost 229 ms in EAV
EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT id FROM mdl_helico_slot WHERE studentplanid = (SELECT studentplanid FROM mdl_helico_slot LIMIT 1);
-- every migrated criterion points at an existing correction, every correction at a submission
SELECT (SELECT COUNT(*) FROM mdl_helico_criterion_score c WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_exam_correction x WHERE x.id = c.correctionid)) AS orphan_criteria,
(SELECT COUNT(*) FROM mdl_helico_exam_correction x WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_exam_submission s WHERE s.id = x.submissionid)) AS orphan_corrections;
-- every migrated response still points at an existing session
SELECT COUNT(*) AS orphan_responses FROM mdl_helico_response r
WHERE NOT EXISTS (SELECT 1 FROM mdl_helico_items s WHERE s.id = r.sessionid);
-- sequence is ahead of the data
SELECT (SELECT MAX(id) FROM mdl_helico_response) < (SELECT last_value FROM mdl_helico_response_id_seq) AS seq_ok;
-- the query that cost 229 ms in EAV
EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT id FROM mdl_helico_classification WHERE studentplanid = (SELECT studentplanid FROM mdl_helico_classification LIMIT 1);Expected: counts equal the dry-run migrated values, orphan_responses = 0, orphan_criteria = 0, orphan_corrections = 0, orphan_slots = 0, orphan_edges = 0, orphan_artifacts = 0, orphan_versions = 0, orphan_annotations = 0, editor_state_mb ≈ 37, orphan_sessions = 0, orphan_session_data = 0, orphan_snapshots = 0, session_data_mb ≈ 68, snapshot_data_mb ≈ 15, duplicate_snapshots = 0, seq_ok = t, and both plans use Index Scan/Bitmap Index Scan (planunit, planblock/plantype). dangling_upstream may be non-zero in dev: edges whose upstream slot was already deleted by a past reset — record the number, do not fail on it.
- Step 3b: Check enum coverage before annotating more columns (read-only)
For each candidate column, list the distinct values on dev and compare with the enum cases; annotate the descriptor with #[allowed_values] only if every value is inside the enum:
SELECT 'session.sessionstatus' AS col, sessionstatus AS value, COUNT(*) FROM mdl_helico_session GROUP BY 2
UNION ALL SELECT 'metrics_report.scope', scope, COUNT(*) FROM mdl_helico_metrics_report GROUP BY 2
UNION ALL SELECT 'exam_submission.correctionstatus', correctionstatus, COUNT(*) FROM mdl_helico_exam_submission GROUP BY 2
UNION ALL SELECT 'slot.slotstatus', slotstatus, COUNT(*) FROM mdl_helico_slot GROUP BY 2
UNION ALL SELECT 'slot.slottype', slottype, COUNT(*) FROM mdl_helico_slot GROUP BY 2
UNION ALL SELECT 'notebook_artifact.artifactstatus', artifactstatus, COUNT(*) FROM mdl_helico_notebook_artifact GROUP BY 2
ORDER BY 1, 2;Run it with the same read-only helper as Step 3.
Expected: the three already-annotated columns show only enum values (otherwise remove the annotation and record why). For slot.slotstatus/slot.slottype/notebook_artifact.artifactstatus, add #[allowed_values] only when the list fits slot_status/slot_type/artifact_status; leave the rest unannotated and note it in the ADR.
- Step 4: Smoke test in the app
Log in as tecnico@helico.dev (see memory local-dev-login-and-runtime-build-order), open a student plan, complete a flashcard or V/F slot, and confirm a new row in mdl_helico_response and mdl_helico_result, and that the Desempenho (metrics) screen renders. For the exam chain: submit a written answer, open the tutor correction screen, save a correction with 2 criteria and re-save it with 1 (the criteria must be replaced, not appended), and confirm the AI flow still moves correctionstatus. For slots: generate a plan for a new enrolment and check that its slots appear in mdl_helico_slot (and none in helico_items), complete one and confirm slotstatus = 'completed', and that the block-advance unlock still fires. For the notebook: write in a guided-study slot (autosave) and confirm editorstateversion increments on the same mdl_helico_notebook_artifact row with no new mdl_helico_item_revision rows; submit the slot and confirm one mdl_helico_notebook_version row appears and artifactstatus becomes published; then reset the enrolment and confirm the artifact, its annotations and its versions are gone. For sessions and snapshots: open a guided-study slot (a row appears in mdl_helico_session and its payload in mdl_helico_session_data; answering rewrites only the mdl_helico_session_data row, pausing or completing rewrites only the mdl_helico_session row, and mdl_helico_session_data.timemodified does not change on pause) and open a unit of a plan whose snapshot does not exist yet (one row appears in mdl_helico_unit_snapshot, and opening it again does not add another) (mdl_helico_slot_lock edges for the next slots) (ai_pending → ai_corrected). The atomicity test from Task 10 Step 5 can only be proven here if PHPUnit’s outer transaction hid it: force a failing criterion insert (for example by temporarily renaming a column in a scratch DB) and confirm the old criteria survive. Then reset that enrolment from the admin lifecycle tool and confirm the new rows are gone (SELECT COUNT(*) FROM mdl_helico_response WHERE sessionid = <session> = 0).
- Step 5: Update the docs
In adr-10_…md section 3 (“Mapa definitivo de tabelas”) replace the 4 planned dedicated tables with the real Phase 1 set (helico_response, helico_result, helico_classification, helico_metrics_report — helico_metrics is split in two because the columns differ — plus helico_exam_submission, helico_exam_assign_link, helico_exam_correction, helico_criterion_score, helico_slot, helico_slot_scope_ref, helico_slot_lock, helico_notebook_artifact, helico_notebook_annotation, helico_notebook_version, helico_session, helico_session_data, helico_unit_snapshot) and add the history row 2026-10-02 — Fase 1 executada (17 tabelas), ver plano 2026-10-02-helico-dedicated-tables-phase1.md; also record that tables are declared as #[Table] descriptors and installed through the framework runner. In ref-10-d_…md move those sixteen types from the EAV section to “Tabelas dedicadas” and add the note that the REF listed 32 types while the code has 62.
- Step 6: Commit
git add docs/plataforma/adrs
git commit -m "docs(adr-10): record phase 1 dedicated tables"Decisions and open items (recorded 2026-10-02)
- No history table for
exam_correction. Dev has 3 corrections and 3 revisions of that type, a re-save replaces thecriterion_scorerows (Task 10), and the table keeps the last author and date. Revisit only if the business needs every grade edit traced (contestation, academic audit). - No privacy provider in this plan, and no follow-up plan opened.
local_helicohas none today, including forhelico_items.userid; the new tables add user-id columns (session,notebook_artifact,notebook_annotation,classification,exam_submission,exam_correction,exam_assign_link). A correct provider must also cover the EAV tables, which is outside this migration.
Rollback and cleanup
- Rollback of code (before any new write): revert the service commits; the EAV rows were never modified, so the old code reads the original data. Rows written to the new tables after the switch are not copied back — rolling back after real traffic loses those rows. Take a DB backup (
make backup) before the production upgrade. - Cleanup release (separate, later): delete the migrated and orphaned
response/activity_result/classification/metrics_report/exam_submission/exam_assign_link/exam_correction/criterion_score/slot/slot_scope_ref/lock_dependency/notebook_artifact/notebook_annotation/artifact_version/session/unit_snapshotrows fromhelico_items,helico_itemmeta,helico_item_revision,helico_item_revision_meta. Not part of this plan.
Before production (not part of dev)
The data step runs inside upgrade.php at container boot with set -e. Before shipping, measure production row counts of the sixteen types (read-only SELECT, via the SSM tunnel) and run --dry-run on a restored copy to estimate the duration. If it exceeds the boot/health-check budget, run cli/migrate_items_to_tables.php ahead of the deploy and let the upgrade step find everything already migrated.
Test command
<TEST_CMD> = cd /private/var/www/docker-moodle-helico && docker compose exec -T moodle bash -c 'cd /var/www/html/moodle && vendor/bin/phpunit --testsuite local_helico_testsuite' (append --filter <name> per task).
Baseline (2026-10-02): --filter activity_dto_test → OK (19 tests, 64 assertions). PHPUnit runs against a separate database helico_phpunit (prefix phpu_, set by MoodleDocker\ConfigExtras::applyPhpunit; the same-DB setup failed with relation "idx_oidc_unique" already exists because PostgreSQL index names are schema-global). Initialise with php admin/tool/phpunit/cli/init.php inside the container.
Appendix — column specs for Plan 4 (not implemented here)
| Table | Parent / FK columns | Key columns | Blob columns | Indexes | Notes |
|---|---|---|---|---|---|
helico_student_plan (Plan 4) |
enrolmentid, studyplanid, studentid |
studyplanversion, studentplanstatus, currentflowref, currentblockref, firstaccessat, weeklyhours, completedat |
sequence, settings |
(enrolmentid) |
root of the hierarchy |
helico_study_flow / helico_study_block / helico_cda_block (Plan 4) |
studentplanid / studyflowid / studyflowid, studyblockid |
flow: flowref, sourcemoduleid, flowtype, sortorder, flowstatus, stagenumber, modulenumber, rgnumber; block: blockref, blocktype, sortorder, blockstatus, unitids; cda: sortorder, blockstatus, cdastatus |
— | by parent id | small in dev (77/220/66 rows) — optional |
enrolment stays EAV by decision (43 rows in dev, no payload): notebook_artifact and metrics_report keep enrolmentid as a plain column and the migrator checks that parent in helico_items.
Plan 4 declares its tables the same way (#[Table] descriptors added to dedicated_schema::classes(), generated XML merged into install.xml, a new MigrationInterface for the data copy).
When a Phase 1 parent type moves to a table (student_plan in Plan 4), item_table_migrator’s orphan check (EXISTS in helico_items) must be generalised to check the parent’s table. Plan 4 owns that change.