“`yaml id=”t4z8xp”
PAGE_START
PageID: EDUKATE::MATHOS::ADAPTER_SPEC_01
Slug: /mathos-data-adapter-spec-v0-1/
Title: MathOS Data Adapter Spec v0.1 (Normalize → SensorUpdate Only; No Structure Overwrite)
Version: v0.1 (LOCK)
Parent: /mathos-runtime-control-tower-v0-1/
Intent:

CivOS-parity ingestion layer for MathOS
Define how raw data becomes normalized sensor updates
Hard rule: adapters can update sensors only; never mutate Node/Bind structure
GrammarLock:
Place×Lane×Zoom×Role×Type×ID
Lane: MATH
CivOSOverlaysAllowed:
BOX_SENSOR_ONLY_RULE
SPEC_TABLES
ERROR_HANDLING

============================================================

BLOCK_01_QUICK_ANSWER (AboveTheFold)
Answer:
This spec defines the only allowed way for external data (quiz scores, exam timing, error tags, topic tags) to enter MathOS: convert raw data into normalized sensor updates. Adapters are not allowed to modify curriculum structure, Node IDs, Bind edges, or method corridors. This prevents “data drift” from corrupting the runtime ontology. If the data is noisy or missing, the adapter must degrade gracefully (unknowns) rather than invent structure.

Pointers:

sensors: /mathos-sensors-pack-v0-1/
thresholds: /mathos-fenceos-threshold-table-v0-1/

============================================================

BOX_SENSOR_ONLY_RULE (non-negotiable)
RULE_SENSOR_ONLY:

Adapter MAY:
update sensor values and timestamps
append event logs
compute distributions/aggregates
Adapter MAY NOT:
rename Node IDs
change Bind graph
change definitions
overwrite corridor steps
auto-rewrite thresholds

ViolationPolicy:

If an adapter attempts structure overwrite -> reject update

============================================================

SPEC_TABLES

============================================================

SPEC_00::INPUT SCHEMAS (raw ingestion)

INPUT_SCHEMA_A::RESULT_EVENT
Fields:
student_id
date_time
assessment_id
question_id
topic_tag # e.g., “linear_equation”, “ratio”, “indices”
zoom_tag # Z0..Z6 (if known; else null)
is_correct # bool
time_seconds # numeric (optional)
attempt_count # integer (optional)
used_calculator # bool (optional)
used_solver # bool (optional)
solution_steps_text # optional (for manual/or LLM tagging; can be empty)
teacher_notes # optional

INPUT_SCHEMA_B::ERROR_TAG_EVENT
Fields:
student_id
date_time
question_id
error_type # E1..E6 (Meaning/Parsing/Choice/Execution/Verification/Time)
first_divergence_step_index # optional
sanity_check_done # bool (optional)

INPUT_SCHEMA_C::TRANSFER_PACK_EVENT
Fields:
student_id
date_time
pack_id
structure_family_tag # e.g., “linear_family_ax_plus_b”, “proportion_unit_rate”
skin_ids # list length 3
correct_count # 0..3
notes_optional

INPUT_SCHEMA_D::TIMED_SET_EVENT
Fields:
student_id
date_time
set_id
question_count
correct_count
time_seconds_total
sanity_checks_count
notes_optional

============================================================

SPEC_01::NORMALIZATION (raw -> canonical sensor updates)

CANONICAL_SENSOR_UPDATE_EVENT
Fields:
entity_id # student_id or cohort_id or school_id
entity_zoom # Z0 student, Z1 cohort, Z2 school, …
sensor_id # e.g., SML, TR, LS, CHOICE, ORA, FD, TB, MF, rho
sensor_value # numeric/boolean/categorical
computed_from # list of source event IDs
time_window # e.g., “session”, “week”, “month”
timestamp
confidence # 0..1 (optional)

NORMALIZE_RULES (Z0 student):

Rule_SML_proxy:
input:
ERROR_TAG_EVENT or teacher_notes or rubric
compute:
SML_present_rate = (#questions with meaning line / #questions observed)
output:
sensor_id = SML
sensor_value = SML_present_rate

Rule_TR:
input:
TRANSFER_PACK_EVENT
compute:
TR = correct_count/3
output:
sensor_id = TR
sensor_value = TR

Rule_LS:
input:
compare TIMED_SET_EVENT vs untimed baseline (same structure family if possible)
compute:
LS_ratio = timed_accuracy / untimed_accuracy
output:
sensor_id = LS
sensor_value = LS_ratio
fallback:
if untimed baseline missing -> sensor_value = “unknown”

Rule_CHOICE_proxy:
input:
teacher rubric OR tagged step “structure label before solving”
compute:
CHOICE_accuracy = correct_structure_tags / total_mixed_items
output:
sensor_id = CHOICE
sensor_value = CHOICE_accuracy
fallback:
unknown if tags missing

Rule_ORA:
input:
sanity_check_done + FD accuracy on bug-hunts
compute:
ORA_present_rate = sanity_checks_count / question_count
FD_accuracy = correct_first_divergence / bug_hunt_total
output:
sensor_id = ORA
sensor_value = {ORA_present_rate, FD_accuracy} # allow object payload

Rule_TB:
input:
time_seconds per question vs time budget (requires mark weight or heuristic)
compute:
TB_rate = (#questions exceeding budget w/ no progress) / total
output:
sensor_id = TB
sensor_value = TB_rate

Rule_MF_proxy:
input:
translation rubric on word problems (variable definitions + units)
compute:
MF_score = setup_correct_rate
output:
sensor_id = MF
sensor_value = MF_score

Rule_rho (sandbox track):
input:
corridor logs (attempt counts) + LS changes
compute:
rho = choice_injected / capacity_proxy
output:
sensor_id = rho
sensor_value = rho
fallback:
unknown unless sandbox tracking exists

============================================================

SPEC_02::AGGREGATION (Z1 cohort, Z2 school)

Z1_COHORT_AGGREGATES (weekly):

TR_distribution
LS_distribution
ErrorTypeDistribution (E1..E6)
PromotionRates (P1/P2/P3 counts by family)
InterleaveRatio (if homework tags exist)
Output:
entity_zoom = Z1
sensor_id = TR_dist / LS_dist / ERR_dist / etc.

Z2_SCHOOL_AGGREGATES (monthly):

EDU_PIPE_strength proxies:
FeedbackLoopRate, InterleaveRatio, RemediationLatency
AssessmentMix:
mixed_vs_blocked ratio (if tagged)
Output:
entity_zoom = Z2

Rule:
Aggregates are derived from Z0 and Z1 events; never manual overwritten without audit.

============================================================

SPEC_03::THRESHOLD COUPLING (adapters do not decide actions)

Rule:

Adapter computes sensors only.
Threshold evaluation and actions are executed by FenceOS table:
/mathos-fenceos-threshold-table-v0-1/

Optional_Output:

Adapter may include “suggested triggers” as metadata,
but MUST NOT execute truncation/stitching itself.

============================================================

SPEC_04::DATA QUALITY + ERROR HANDLING

ERROR_HANDLING:
MissingData:
– if required fields missing -> set sensor_value=”unknown” and confidence low
NoisyData:
– use rolling median/mean windows; keep raw logs
ConflictingTags:
– prefer teacher-tagged error_type over auto-tag
Outliers:
– extreme time values flagged; do not discard automatically
Privacy:
– store only necessary identifiers; do not publish personal data in public pages

AUDIT_LOG:

every sensor update stores computed_from + timestamp + confidence
adapter version is recorded (AdapterVersion: v0.1)

============================================================

SPEC_05::EXAMPLE (one student week)
ExampleWeek:
Inputs:
– 2 transfer pack events (TR=0.33, TR=0.67)
– 2 timed sets + untimed baseline -> LS_ratio=0.6
– error tags: E2 dominates
Outputs (Z0):
– TR_week_avg=0.50
– LS_ratio=0.60
– ErrorTypeTop=E2
Downstream (FenceOS):
– triggers: TR < 0.7 and LS low -> TRUNCATE timing + Parsing clinic corridor
Note:
Adapter does not run the corridor; it only updates sensors.

============================================================

RELATED_PAGES
Links:

/mathos-runtime-control-tower-v0-1/
/mathos-sensors-pack-v0-1/
/mathos-fenceos-threshold-table-v0-1/
/mathos-failure-atlas-v0-1/
/mathos-recovery-corridors-p0-to-p3/

NEXT_OUTPUT (if you say “Next”)
PageID: EDUKATE::MATHOS::IN_12_LINES_01
slug: /mathos-in-12-lines/

PAGE_END
“`

SPEC_00::INPUT SCHEMAS (raw ingestion)

SPEC_01::NORMALIZATION (raw -> canonical sensor updates)

SPEC_02::AGGREGATION (Z1 cohort, Z2 school)

SPEC_03::THRESHOLD COUPLING (adapters do not decide actions)

SPEC_04::DATA QUALITY + ERROR HANDLING

Recommended Internal Links (Spine)

Share this: