Skip to content

helico dedicated tables — Phase 1 Implementation Plan

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_id meta equals parent in 100% of rows (17,202/17,202).
  • whereMeta('student_plan_id') on helico_itemmeta: bitmap scan of 16,199 rows by meta_key, 14,585 discarded by the unindexed TEXT meta_value filter, ~229 ms, 4,875 blocks read.
  • Orphans come from enrolment_reset_listener_service::cascade_delete_items(), which deletes sessions/student plans but not their response/classification children.
  • metrics_report.description holds 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:

  1. The repositories stay on $DB plus table_row_hydrator. That is what makes response, 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 dedicated AbstractMapper per table, a larger change than this plan needs.
  2. Reads go through entity() (route C, chosen 2026-10-02). MiddagItemQueryBuilder::make()->entity(response::class)->where('sessionid', …) is bound to the table through the core TableRegistry, and typed_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 the table_row_hydrator mapper registered for the class — the missing link that ItemMapper fills for Item rows through the type column. It also validates what the builder does not (whereMeta/withMetadata, = NULL, unknown columns, raw select()/orderBy(), and a bound class queried without entity()). The repositories (writes and the fixed finders) use the same hydrator, so both paths return identical entities.
  3. 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 reading helico_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.
  4. Projection is a cheaper alternative to a *_data side 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_data is 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 key session_id → column sessionid.
  • Plugin version: current 2026092801 (version.php); this plan ships 2026100201. 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 override create(ItemDtoInterface): ItemInterface, update(ItemDtoInterface): ItemInterface, delete(int): void and find(int): ?ItemInterface (the exact signatures of Middag\Core\Domain\Item\ItemService) and route them to their repository. item_dto exposes public id, 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.xml blocks for them are generated by build:schema:dedicated, never hand-edited. schema_test fails if the two drift.
  • Entities of migrated types are read and written only through their repository. Never MiddagItemQueryBuilder with ->domain()/->entity()/->whereMeta()/->withMetadata() (a builder over a migrated entity is built with ->entity() and run with typed_query::execute()), never item_service->find() for them, never helico_items/helico_itemmeta in raw SQL (the migrator and session_data_copier are the only exceptions). Task 15 Step 6b enforces the first and third.
  • Every repository insert()/update() validates the columns with table_row_validator::assert() (Task 3b) before the $DB write; invalid input is an invalid_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-By trailer in commits (repo CLAUDE.md overrides session attribution). Conventional Commits.
  • Do not run npm run build, do not touch tool-middagctl, use make targets (not raw docker compose).
  • PHPCS Moodle style for plugin code; declare(strict_types=1); file header as in existing files.

Review Focus

  1. Boot-time upgrade — docker-entrypoint.sh runs upgrade.php at every boot with set -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.
  2. Second run of the migration — running the data step twice (or after partial failure) must not duplicate or error. Pinned in Task 4.
  3. Sequence after explicit-id import — first insert after migration must get id > max(imported id). Pinned in Task 4.
  4. NULL vs 0 round trip — question_id/card_id/scope_target_id/invalidated_at are nullable and callers distinguish null from 0 (report_service comment on invalidated_at). Pinned in Tasks 3, 5, 8.
  5. 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.
  6. 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.
  7. Partial item_dto updates from the AI services — they call update(new item_dto(id: ..., metadata: [...])) with only the fields that changed; item_dto::$status defaults to 'draft', which must not overwrite correctionstatus, and omitted metadata keys must not be nulled. Pinned in Tasks 3 and 9.
  8. exam_submission without 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.
  9. Slot lock keys the old query never loaded — slot_lock_service::read_lock reads lock_reason/lock_message/lock_unlock_rule/lock_unlock_at with getMeta(), but slot::METADATA_FIELDS omits them, so withMetadata() never loaded them (102 dev slots have values). The new hydrator exposes them. read_lock has 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.
  10. Lock edges and scope refs of a deleted slot — the reset deletes slots but never their lock_dependency children (44% of dev edges are orphans) nor the edges pointing at them. slot_lock_repository::delete_by_slot_ids removes both directions. Pinned in Tasks 11 and 15.
  11. Silent writes to EAV from parent::update — notebook_artifact_service::promote_to_notebook and publish (and slot_lock_service::write_lock, exam_submission_service::mark_*) call parent::update(new item_dto(...)) directly. Once update() is overridden, parent::update would 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).
  12. unit_snapshot_service still needs the EAV item service — besides persisting snapshots it calls item_service->find($unit_id) for the live unit (is_consistent, live_audio_relations, persist_snapshot), and unit/unit_content stay EAV. Only the snapshot persistence is swapped; the constructor keeps ItemServiceInterface. Pinned in Task 14.
  13. Session payload split — helico_session has no data column; session::getMeta('data')/get_data() load it lazily from helico_session_data, so a caller can never get a silent null. The cost is one extra indexed query per session whose data is read from a list (about 14 call sites read get_data()); a status/time update never rewrites the payload row. session_data_copier must run after the sessions are migrated. Pinned in Tasks 4 and 13.
  14. The executor cannot hydrate the new tables on its own, and a stale EAV read does not fail — verified in dev: ->domain()/->entity() on from(table) return a generic Item without the table’s columns; whereMeta and where(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 by typed_query (Task 3 Step 7b: refuses a bound class queried without entity()) and by the guard test in Task 15 Step 6b.
  15. No privacy provider — local_helico declares 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”.
  16. Invalid column values reach the database — a status outside its enum, an over-long char, a null in a NOT NULL column. Pinned by table_row_validator_test (Task 3b), a rejection test in session_repository_test (Task 13) and the guard test in Task 15 Step 6d.
  17. select() and orderBy() are not validated by the builder (verified: select(['id, (SELECT 1) AS x']) and orderBy('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.
  18. History and generic events are not carried over — revisions are dropped on purpose and ItemSignal is no longer emitted for the 16 types; nothing in local_middag/local_helico consumes either, but exam_correction loses its previous versions and a third-party middag/item/* hook stops firing. Decide whether exam_correction needs its own history table. Documented in “What the core item stack did on write”.
  19. 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 fills fullname only for slot (its label). 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.md under “Test command” below)

Interfaces:

  • Produces: the exact command that runs tests/**/*_test.php for local_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 (script build: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_score and helico_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 $meta are absent from the result).
    • table_row_hydrator::columns_from_dto(item_table_definition $def, \Middag\Core\Domain\Item\Contract\ItemDtoInterface $dto): array (what the item_service overrides 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’s getUserid() reads. If it is not one of the meta_columns values, row_from_meta also copies helico_items.userid into it (this is the case for exam_submission.userid, the student).

  • sortorder_column: the column that mirrors helico_items.sortorder when the meta key does not already provide it.

  • fullname_column: the column the entity’s getFullname() reads (the slot’s label).

  • defaults: column => value applied by row_from_meta when a NOT NULL column would otherwise be NULL, per definition (a global list would turn a nullable slot.scope into 'overall').

  • parent_required: when false, an item whose parent is NULL is migrated (parent column stays NULL) 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_bindings and typed_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 the local_middag\base\persistence\query\query_builder facade). It looks the class up in TableRegistry (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 default helico_items query — which is why registration must be complete (tested below).
  • How an Item is typed today: TypeLoader scans the plugin’s Item subclasses at boot (#[ItemType] attribute, else the TYPE constant) into ItemTypes; each helico_items row has a type column; ItemMapper::dbToDomain reads it, calls ItemTypes::classFor($type) and constructs the entity with the metadata. The executor receives the domain class but ignores it. A dedicated table has no type, so the class must come from the binding instead: that is the missing link typed_query adds.

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, $enum is a string-backed enum FQCN.
    • table_row_validator::assert(string $table, array $columns, bool $partial = false): void — $table is the table name without prefix concerns (helico_session); throws invalid_row_exception with ->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):

  1. unknown column → unknown column;
  2. null on a notnull column that has no default → required; on insert (not partial) a missing notnull column without default and without sequence → required;
  3. int column: value must be int or an integer-like numeric string; number → numeric; char → string and strlen (mb) ≤ length; text → string;
  4. #[AllowedValues] column: value must equal a ->value of the enum (null is 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_repository with:

    • find_by_session(int $session_id): list<response> (ordered by sortorder)
    • find_by_session_ids(array $session_ids): list<response>
    • count_by_session(int $session_id, ?bool $correct = null): int
    • insert(array $data): int (data keys = column names)
    • insert_many(array $rows): void
    • find_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_service to 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 (extends item_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): ?result
    • find_by_session(int $session_id): ?result
    • find_by_student_plan(int $student_plan_id): list<result>
    • find_by_user_and_unit(int $user_id, int $unit_id): list<result> (join through helico_items is gone: use slotid→ session→ user; see Step 3 note)
    • save(array $data, ?int $id = null): int (insert or update by id)
    • delete_by_enrolment(int $enrolment_id): void
    • find(int $id): ?result, delete(int $id): void (used by the item_service overrides)
  • 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:

  1. 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 at notebook_artifact_service.php:60-66 — resolve lazily with private ?result_repository $repository = null; private function repository(): result_repository { return $this->repository ??= new result_repository(); }).
  2. record(result_dto $dto): result — keep the DTO→values logic; replace the final create()/update() with $id = $this->repository()->save($columns, $existing?->getId()); building $columns with table_row_hydrator::columns_from_meta(item_table_definitions::result(), $metadata) + ['sessionid' => $dto->session_id] (where $metadata is the array the old code passed as item_dto metadata), and return $this->repository()->find_by_session($dto->session_id).
  3. find_by_slot, find_by_session, find_by_student_plan, find_by_user_and_unit: delegate to the repository one-to-one (same names).
  4. result_service extends item_service, so, per the Global Constraints, replace the existing create()/update() overrides (:44-56) and add delete()/find() overrides that route to the repository, exactly as in Task 9 Step 6 with item_table_definitions::result() and a result_repository (add find(int $id): ?result and delete(int $id): void to result_repository, each a one-line $DB->get_record / $DB->delete_records over helico_result). Without this, any caller still using create()/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-241 and create() 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> (ordered timecreated ASC, id ASC)
    • find_by_student_plan(int $student_plan_id, ?int $as_of = null): list<classification>
    • find_by_submission(int $submission_id): ?classification
    • insert(array $data): int
    • update_score(int $id, float $score, string $level): void
    • find(int $id): ?classification
    • delete_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 (extends item_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): ?report
    • upsert(string $idnumber, array $data): int (insert or update by idnumber; must set invalidatedat to null when given null)
    • invalidate(int $id, int $at): void
    • invalidate_for_enrolment(int $enrolment_id, int $at): int
    • delete_by_enrolment(int $enrolment_id): void
    • find(int $id): ?report, delete(int $id): void (used by the item_service overrides)
  • 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"

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_submission
    • list_by_slot(int $slot_id): list<exam_submission> and list_by_slot_ids(array $slot_ids): list<exam_submission> (both ordered id ASC)
    • find_by_slot(int $slot_id): ?exam_submission (lowest id)
    • find_by_slot_and_question(int $slot_id, int $question_id): ?exam_submission
    • find_by_slot_unit_and_question(int $slot_id, int $unit_id, int $question_id): ?exam_submission
    • list_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_submission rows (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> (ordered id ASC); insert(array): int; update(int, array): void; delete(int): void.

  • Produces criterion_score_repository: list_by_correction(int $correction_id): list<criterion_score> (ordered sortorder 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): ?slot
    • list_by_student_plan(int $student_plan_id, ?string $blockref = null, array $slot_types = []): list<slot> (ordered sortorder 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> (ordered sortorder 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_artifact
    • find_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 old items()[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 ordered id 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_repository and notebook_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_service and artifact_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 (lazy getMeta)
  • Modify: classes/extensions/engine/session/service/session_service.php (constructor :33-35; finders :37-222; create :224-256; update_* and complete :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): ?session
    • list_by_slot(int $slot_id): list<session>, list_by_slot_ids(array $slot_ids): list<session> (both id ASC; without the payload)
    • ids_by_slot_ids(array $slot_ids): list<int>
    • insert(array $columns): int, update(int $id, array $columns): void
    • delete_by_ids(array $ids): void (also deletes the sessions’ helico_session_data rows)
  • Produces session_data_repository:

    • find_data(int $session_id): ?string
    • save(int $session_id, ?string $json): void (updates the newest row of the session, inserts when none; null or '' deletes it)
    • delete_by_session_ids(array $session_ids): void
  • Produces session::getMeta('data') / session::get_data() loading the payload from helico_session_data when 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_snapshot
    • find_by_plan_and_unit(int $study_plan_id, int $unit_id): ?unit_snapshot (lowest id, as the old items()[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<…> (all id 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_itemmeta JOIN

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_result via find_items_ids_by_type_and_meta + cascade_delete_items) and step 9 (:127-132, metrics_report) by a single call to cascade_phase1_tables($enrolment_id, $session_ids, $student_plan_id). $session_ids is computed at :95-97 before the session delete, so move the call to just before cascade_delete_items($session_ids) and keep $session_ids = [] when $student_plan_id === null.

  • Add the matching use statements 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 the criterion_score rows (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_helico has none today, including for helico_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_snapshot rows from helico_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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close