Intervention Bundles

When a student has an active educational profile, the modules/bundle module takes a single step: it looks the profile up in a 21-row deterministic map and returns exactly one named intervention bundle. The teacher then decides whether to activate it. Nothing reaches a student until the teacher acts (V-12).

The catalog

The bundle catalog contains 20 defined bundle definitions. Bundles are closed catalog items identified by a string bundleId. They are not generated, not freeform, and not per-student. What changes per student is the scaffold tier assigned to each skill within that bundle.

The catalog is versioned and publish-then-freeze: once a catalog version is published it is never mutated. A V-6 dry-run replay endpoint lets you preview how a catalog change would affect existing recommendations before publishing.

From profile to bundle: the map

The 21-row profile_bundle_map is keyed on (primary_profile_code, access_driver | comprehension_subprofile | modifier_driver). The extra driver column narrows which bundle is selected for profiles that have multiple instructionally distinct sub-types.

Row MAP-000 / NO_BUNDLE_SYSTEM_GUARD is the halt case: when the student has no active profile, a DATA_INCOMPLETE guard state, or a do_not_decide_yet anchor skill, the map returns blocked_insufficient_evidence plus a nextRecommendedDataAction that names the specific data action needed. No bundle is recommended and there is no override path around this.

The Threaded Path Model

Every recommended bundle has three parts:

The anchor weight being strictly the largest is enforced in two places: the engine (threaded-path.ts) and a DB CHECK constraint on the assignment table. Trying to store a split where a supporting thread outweighs the anchor will be rejected.

The dosageSplit field on every ActivateBundleResponse and BundleCatalogRowDTO carries the actual percentages.

Scaffold tier

The scaffold tier is assigned per (student × skill × bundle × task_type), not per student and not per bundle. A student may have Level_1_Foundation on one skill within a bundle and Level_2_Targeted on another.

The scaffold tier is never shown to the student. It drives which level of scaffolded task the task-delivery layer selects. Teacher and admin routes can see tier distribution (the cluster preview and the scaffold adjustment endpoint expose it), but no student-facing route does.

Scaffold tier adjustments use override rule OVR_SCAFFOLD with a reasonCode from the 9-code catalog. RTI tier is in every override’s forbidden_fields and is never written through any bundle endpoint.

Bundle assignment lifecycle

Once a teacher activates a bundle, the assignment follows a 17-value lifecycle reflecting the monitoring loop:

recommended → in_review → activated → monitoring
                                      ├─ paused
                                      ├─ reviewed → continued | adjusted | modified
                                      ├─ escalated → immediate_review
                                      ├─ data_completion_required
                                      ├─ met_criteria → exited
                                      ├─ teacher_modified
                                      ├─ regression_review
                                      └─ rescinded

The BundleAssignmentStatus enum is the authoritative list returned in ActivateBundleResponse and exposed on the class profile distribution endpoint.

Teacher adjustments (override codes)

Teachers adjust bundle parameters (delivery mode, schedule, context flags) through controlled override operations. Every adjustment picks a reasonCode from the 9-code OverrideCodeCatalog:

No free-text reason fields exist anywhere in the bundle module. All adjustment endpoints accept only a reasonCode FK into this catalog. This is enforced at the CI lint level (pnpm lint:bundle).

Context flags (e.g. CTX_SESSION_INTERRUPTED) may optionally accompany an adjustment. The 7 allowed ContextFlagId values are the only representable flags; the 3 blocked ones are not constructible through the API.

Key endpoints

Smart Cluster + bulk-activation endpoints are in Smart Clustering.

Connections

• Upstream: Student Profiles: the active profile is the input to the profile-to-bundle map.
• Downstream: Smart Clustering: cluster logic groups students who share bundle, anchor, tier, and delivery mode.
• Monitoring: Progress Monitoring: the 5 GSR safety rules and 19 per-bundle success criteria that govern when a bundle transitions.
• Workflow: Teacher Activation Workflow: the 17-step UI workflow that drives teacher confirmation, adjustment, and review.
• Task delivery: Task Delivery: once a bundle is active, task delivery selects and serves stored items using the scaffold tier.