Source-bound decision record
20 committed decisions · nweamap/1edtech
#overview
nweamap served audiences
activeOwner: platform3-loopDate: 2026-06-02
Decision
developer building MAP Growth CDF import, sync, read-back, or raw/current-result verification workflows against the public TimeBack NWEAMap 1EdTech surface using NWEA CDF pass-through plus documented platform gap-fill behavior
Alternatives and tradeoffs
- student or parent report reader
- NWEA assessment author
- exact MAP Quadrants report generator
- Alpha report app that expects school-language derived views
Rationale and consequences
the 1EdTech NWEAMap surface is the exact NWEA export and platform behavior contract that downstream Alpha report apps build on
#nitd-000-source-contract
nweamap source contract
activeOwner: platform3-loopDate: 2026-06-02
Decision
NWEA MAP Growth CDF bundle plus MAP_Export_Field_Descriptions.xlsx is the upstream specification; platform docs pass through NWEA field definitions by reference and document only platform-owned sidecar metadata or behavior
Alternatives and tradeoffs
- invent a 1EdTech-like MAP spec
- copy every NWEA field description into platform docs
- derive the contract from sample CSV headers only
Rationale and consequences
NWEA owns field names, field meanings, datatypes, lengths, and repeating blocks; platform decisions should cover only the gaps NWEA leaves open
#nitd-001-mirror-export
nweamap raw export mirror
activeOwner: platform3-loopDate: 2026-06-02
Decision
raw persistence mirrors the five NWEA CDF files 1:1 with NWEA field names and semantics, scoped by tenant, NWEA account, term, import batch, source file, source row number, source row hash, ingest timestamp, and deletion state
Alternatives and tradeoffs
- normalize immediately on ingest
- store only one raw object blob
- collapse the five CDF files into a combined-export table
Rationale and consequences
1:1 mirroring keeps NWEA as source authority and makes re-import, audit, and soft deletion deterministic
#nitd-002-single-result-view
nweamap single result view
activeOwner: platform3-loopDate: 2026-06-02
Decision
real-time MAP result observations and daily CDF backfill update one module-owned current result projection; no separate NWEA helper table and no separate batch table ship
Alternatives and tradeoffs
- separate real-time and batch stores
- raw CDF only with no result projection
- client-side merge of real-time and batch facts
Rationale and consequences
one projection removes the prior helper-table split and gives every consumer a single current MAP result answer
#nitd-003-test-of-record-highest-rit
nweamap test of record highest rit
activeOwner: platform3-loopDate: 2026-06-02
Decision
test of record is the highest valid TestRITScore per tenant, NWEA account, student, subject, and term; valid MAP RIT is 100 through 350, ties choose latest TestStartDate/TestStartTime then larger TestID
Alternatives and tradeoffs
- use GrowthMeasureYN as authoritative during convergence
- use latest sitting
- require external manual official-result choice
Rationale and consequences
highest valid RIT is deterministic, outcome-aligned, and stable while preserving all sittings for audit
#nitd-004-soft-delete
nweamap soft delete retention
activeOwner: platform3-loopDate: 2026-06-02
Decision
when a previously ingested row disappears from the next authoritative export for the same tenant, NWEA account, term, file, and natural identity, mark it soft-deleted with deletion metadata and never hard-delete through the public surface
Alternatives and tradeoffs
- hard-delete missing rows
- tombstone without original row
- ignore missing-row changes
Rationale and consequences
soft deletion preserves retake and invalidation history that customers need to explain report changes
#nitd-005-sitting-scope-parameter
nweamap sitting scope parameter
activeOwner: platform3-loopDate: 2026-06-02
Decision
assessment result reads expose sittingScope with values test_of_record and all; clients choose the documented scope instead of learning internal tables or re-implementing dedupe
Alternatives and tradeoffs
- two hidden tables
- one implicit default only
- client-side dedupe of all sittings
Rationale and consequences
a named parameter keeps sitting selection in the public contract and prevents every consumer from rebuilding test-of-record logic
#nitd-006-axis-write-granularity
nweamap write granularity
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP public bulk-only CDF bundle import through POST /nweamap/v1/imports; DEFER public per-row POST, PUT, PATCH, and DELETE until three integrator decisions in 90 days prove bundle import plus read-back blocks the served job
Alternatives and tradeoffs
- per-resource writes
- both bulk and per-resource writes
- manual row construction
Rationale and consequences
bulk-only matches NWEA's export contract and avoids a duplicate primitive that can drift from CDF source authority
#nitd-007-axis-read-shape
nweamap read shape
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP list endpoints for CDF collections, detail reads for imports and assessment result rows, and narrow current-result projections controlled by sittingScope; DEFER unrestricted nested sub-collections and Alpha report graphs until Alpha approves a report-graph ITD or three integrator decisions in 90 days prove list/detail/projection reads block the served job
Alternatives and tradeoffs
- list-only reads
- detail-only write-and-remember
- arbitrary graph read API
Rationale and consequences
list plus detail plus narrow projections supports import verification and reporting without turning the 1EdTech surface into the Alpha report surface
#nitd-008-axis-query-model
nweamap query model
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP documented filters, stable sort keys, limit-based opaque cursor paging, and modifiedSince for imports, pass-through CDF collection lists, and assessment result projection reads
Alternatives and tradeoffs
- no query model
- filter and sort only
- SQL-over-HTTP style arbitrary query
Rationale and consequences
filter plus cursor paging plus modifiedSince is the smallest query model that supports sync, backfill, and import verification at CDF scale
#nitd-009-axis-concurrency-model
nweamap concurrency model
activeOwner: platform3-loopDate: 2026-06-02
Decision
DEFER If-Match and per-resource ETags because the public NWEAMap surface has no mutable row overwrite route; re-open with any approved public PUT, PATCH, or DELETE route
Alternatives and tradeoffs
- no concurrency statement
- ETag on every raw row
- bulk-only If-Match
Rationale and consequences
concurrency headers protect mutable overwrites, while this release handles import conflicts through idempotency
#nitd-010-axis-idempotency-model
nweamap idempotency model
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP canonical bundle content hash plus optional Idempotency-Key stored in platform.idempotency_key; same bundle repeats return prior/no-op status and key reuse with different content returns 409
Alternatives and tradeoffs
- no idempotency
- required Idempotency-Key only
- database unique constraints only
Rationale and consequences
bundle hashing protects scheduler repeats while Idempotency-Key preserves platform retry semantics
#nitd-011-axis-auth-shape
nweamap auth shape
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP platform HS256 Bearer JWTs with tenantId, role or roles, and scopes nweamap:import, nweamap:read, and nweamap:admin; DEFER school, class, and person scoped claims until repeated decisions prove tenant-level access blocks the served job
Alternatives and tradeoffs
- role-only JWT
- school/class/person scoped claims now
- API keys without tenant claims
Rationale and consequences
role plus NWEAMap scopes separates import from read without inventing visibility semantics the first 1EdTech surface does not need
#nitd-012-axis-eventing-model
nweamap eventing model
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP polling through modifiedSince and cursor-paged lists; DEFER webhooks until three integrator decisions in 90 days show polling blocks MAP sync/report jobs or a platform-wide webhook substrate ships
Alternatives and tradeoffs
- no eventing
- webhooks now
- push stream
Rationale and consequences
polling covers CDF backfill and sync without adding subscription, signature, retry, and replay infrastructure
#nitd-013-axis-error-envelope
nweamap error envelope
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP platform typed RFC 7807 Problems with stable NWEAMap codes, requestId, traceId, fieldErrors, and rowErrors for import failures
Alternatives and tradeoffs
- no error envelope
- plain RFC 7807 only
- free-text import errors
Rationale and consequences
typed Problems with row-level source evidence let agents repair CDF imports without parsing prose
#nitd-014-axis-tenant-routing
nweamap tenant routing
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP platform tenant-in-JWT routing with request tenantId route-token match; nweaAccountId is a required tenant-local partition for imports and a query filter for reads, not a platform tenant
Alternatives and tradeoffs
- tenant in URL only
- NWEA account as platform tenant
- no NWEA account partition
Rationale and consequences
this preserves platform tenant isolation while allowing one tenant to manage multiple NWEA accounts
#nitd-015-axis-conformance-evidence
nweamap conformance evidence
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP local executable evidence: workbook/header parity, CDF import round trip, row counts, idempotent re-import, highest-RIT retake fixture, soft-delete replacement fixture, typed Problem fixtures, live smoke tests, surface QC, integration app, and skill-pack leak check; DEFER official NWEA certification claim
Alternatives and tradeoffs
- no conformance evidence
- claim official NWEA certification without an artifact
- manual screenshots only
Rationale and consequences
local evidence proves the actual NWEA export pass-through and platform gap-fill behavior available to integrators
#nitd-016-axis-privacy-retention
nweamap privacy retention
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP tenant-scoped rows, audit linkage, redaction from logs and Problems except minimal repair evidence, and soft deletion; DEFER age-based retention windows and public erasure APIs until platform privacy policy names the required workflow
Alternatives and tradeoffs
- no privacy behavior
- hard-delete everything on absence
- copy raw student data into logs
Rationale and consequences
NWEA CDF contains learner records, and retake/invalidation history must survive while logs and errors remain safe
#nitd-017-axis-list-endpoints
nweamap list endpoints
activeOwner: platform3-loopDate: 2026-06-02
Decision
SHIP list endpoints for imports, students, assessment results, class assignments, program assignments, and accommodations, all tenant- and NWEA-account scoped with cursor paging and documented filters
Alternatives and tradeoffs
- write-and-remember
- assessment results list only
- direct database access
Rationale and consequences
one list per CDF collection matches the export shape and lets cold integrators discover rows after import
#nitd-018-report-oracle-boundary
nweamap report oracle boundary
activeOwner: platform3-loopDate: 2026-06-03
Decision
DEFER report-oracle, report-contract, golden-cell, and report-verification primitives on the 1EdTech surface; exact MAP Quadrants report cells, norms=2020|2025 verification, Growth X, Alpha report-specific RIT50/RIT90/Effective Grade assembly, and Alpha report graphs belong to the Alpha surface. R6 carves out the module-owned PowerPath RIT-to-grade reference table/lookup as NWEAMAP-owned portable MAP reference data, not a report oracle. Any skill-pack eval asking 1edtech/skill_pack to regenerate Alpha reports must move to alpha/skill_pack
Alternatives and tradeoffs
- ship report contracts on 1EdTech now
- leave the report-oracle boundary implicit
- make the 1EdTech skill pack carry report contracts or golden-cell logic
Rationale and consequences
the 1EdTech surface is the NWEA CDF pass-through and platform gap-fill contract plus the R6 PowerPath RIT-to-grade reference owner, while MAP Quadrants exact report regeneration depends on Alpha-only derived primitives and must not leak into a 1EdTech skill pack or its eval