People & Orgs Alpha Data Dictionary

[
  "Every public Alpha field is a rename, restriction, extension, inherited platform field, or explicit cut against the approved OneRoster or Ed-Fi 1EdTech data dictionaries.",
  "Alpha renamed/cut/restricted objects are public views over the 1EdTech base; only Alpha extension fields get Alpha tables.",
  "No alpha table column may carry a OneRoster or Ed-Fi source. If a field maps to either upstream, it must be documented as a view column.",
  "Relationships are real columns and ids, never tags.",
  "Reporting-blocking enums reality, alpha_level, grade_level, brand, segment, modality, and level are closed value sets published here with write-time alias folds and live production validation evidence.",
  "Every ordinary report read defaults to reality=real for both people and places unless the caller explicitly asks for test or synthetic data.",
  "Point-in-time membership, staff-assignment, program-participation, alpha-level history, and age-grade history reads require asOfDate and use the begin_date/end_date/is_time_locatable rule.",
  "Ed-Fi-backed views select canonical records only, hide is_deleted rows by default, exclude drafts, resolve descriptors through edfi.descriptor_code, and join person/place references through OneRoster sourcedIds.",
  "Secrets never appear in roster fields, tags, logs, public examples, or Problem details.",
  "Role-specific views such as students, guides, and staff are filters over person plus memberships; guardian, staff-assignment, and program-participation facts are Ed-Fi-backed views, not Alpha storage tables.",
  "Mastery, test scores, gradebook rollups, activity events, content effectiveness, and curriculum graph facts are out of module."
]

{
  "rule": "Alpha is views over the OneRoster and Ed-Fi 1EdTech bases for rename/cut/restrict changes; only extend changes add Alpha-owned tables containing new Alpha fields plus foreign keys to base rows.",
  "itd": {
    "id": "paitd-011-storage-model",
    "title": "Alpha Storage Is Views Over OneRoster Plus Extension Tables",
    "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-011-storage-model"
  },
  "forbiddenAlphaTables": [
    "alpha.person",
    "alpha.place",
    "alpha.place_membership",
    "alpha.class_membership",
    "alpha.school_period",
    "alpha.person_sensitive_profile",
    "alpha.guardian_view",
    "alpha.guardian_relationship_view",
    "alpha.staff_assignment_view",
    "alpha.program_participation_view"
  ],
  "forbiddenTables": [
    "alpha.person",
    "alpha.place",
    "alpha.place_membership",
    "alpha.class_membership",
    "alpha.school_period",
    "alpha.person_sensitive_profile",
    "alpha.guardian_view",
    "alpha.guardian_relationship_view",
    "alpha.staff_assignment_view",
    "alpha.program_participation_view"
  ],
  "allowedExtensionTables": [
    "alpha.person_ext",
    "alpha.place_ext",
    "alpha.app_credential",
    "alpha.tag_definition",
    "alpha.object_tag",
    "alpha.alpha_level_history",
    "alpha.age_grade_history"
  ],
  "storageContract": [
    {
      "alphaObject": "person",
      "publicSurface": "alpha.person",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.users",
      "baseView": "alpha.person_base",
      "extensionTables": [
        "alpha.person_ext"
      ],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech users surface.",
      "extensionWriteRoute": "Write admission_date, exit_date, age_grade, and reality to alpha.person_ext after the base person exists.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns. Wave 2 adds reality as an Alpha extension field, not a copied OneRoster column."
    },
    {
      "alphaObject": "place",
      "publicSurface": "alpha.place",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.orgs",
      "baseView": "alpha.place_base",
      "extensionTables": [
        "alpha.place_ext",
        "alpha.object_tag"
      ],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech orgs surface.",
      "extensionWriteRoute": "Write nwea_district_id and reality to alpha.place_ext, and report-slice tags to alpha.object_tag, after the base place exists.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns. Wave 2 adds reality as an Alpha extension field, not a copied OneRoster column."
    },
    {
      "alphaObject": "place_membership",
      "publicSurface": "alpha.place_membership",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.roles",
      "baseView": "alpha.place_membership_base",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech roles surface.",
      "extensionWriteRoute": "None. is_time_locatable is a view expression, not stored Alpha state.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "class_membership",
      "publicSurface": "alpha.class_membership",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.enrollments",
      "baseView": "alpha.class_membership_base",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech enrollments surface.",
      "extensionWriteRoute": "None. is_time_locatable is a view expression, not stored Alpha state.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "school_period",
      "publicSurface": "alpha.school_period",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.academic_sessions",
      "baseView": "alpha.school_period_base",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech academic_sessions surface.",
      "extensionWriteRoute": "None.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "person_sensitive_profile",
      "publicSurface": "alpha.person_sensitive_profile",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.demographics",
      "baseView": "alpha.person_sensitive_profile_base",
      "extensionTables": [],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech demographics surface.",
      "extensionWriteRoute": "None. Authorization and redaction are API/view restrictions, not copied storage.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "guardian",
      "publicSurface": "alpha.guardian_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name=Contact)",
      "baseView": "alpha.guardian_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech Contact collection; Alpha exposes only canonical, non-deleted Contact records.",
      "extensionWriteRoute": "None. Guardian facts that originate in Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "guardian_relationship",
      "publicSurface": "alpha.guardian_relationship_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name=StudentContactAssociation)",
      "baseView": "alpha.guardian_relationship_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech StudentContactAssociation collection; Alpha joins to OneRoster users only by platform3 sourcedId references.",
      "extensionWriteRoute": "None. Relationship descriptors and flags remain Ed-Fi canonical data.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "staff_assignment",
      "publicSurface": "alpha.staff_assignment_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name=StaffEducationOrganizationAssignmentAssociation)",
      "baseView": "alpha.staff_assignment_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech StaffEducationOrganizationAssignmentAssociation collection; OneRoster users and orgs remain the roster identity boundary.",
      "extensionWriteRoute": "None. Staff assignment facts from Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "program_participation",
      "publicSurface": "alpha.program_participation_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name in GeneralStudentProgramAssociation, StudentProgramAssociation, and specializations)",
      "baseView": "alpha.program_participation_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech Program and StudentProgramAssociation-family collections; Alpha joins student and place ids through OneRoster sourcedIds.",
      "extensionWriteRoute": "None. Program participation facts from Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "app_credential",
      "publicSurface": "alpha.app_credential",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.app_credential"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.app_credential rows with a student_sourced_id foreign key to oneroster.users.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "tag_definition",
      "publicSurface": "alpha.tag_definition",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.tag_definition"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.tag_definition rows only; no 1EdTech columns are copied.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "object_tag",
      "publicSurface": "alpha.object_tag",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.object_tag"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.object_tag rows only; object_id is a relationship reference to a live public object, not a copied 1EdTech field.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "alpha_level_history",
      "publicSurface": "alpha.alpha_level_history",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.alpha_level_history"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write effective-dated alpha.alpha_level_history rows with a person_id foreign key to the base person, after the base person exists. No OneRoster or Ed-Fi column is copied.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "age_grade_history",
      "publicSurface": "alpha.age_grade_history",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.age_grade_history"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write effective-dated alpha.age_grade_history rows with a person_id foreign key to the base person, after the base person exists. No OneRoster or Ed-Fi column is copied.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    }
  ]
}

[
  {
    "source": "oneroster.users.password",
    "alphaDisposition": "cut",
    "reason": "Secrets are never roster fields or tags. Alpha uses alpha.app_credential.secret_ref instead.",
    "itd": {
      "id": "paitd-008-app-credentials",
      "title": "App Credentials Use Vault References, Never Roster Password Fields",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-008-app-credentials"
    },
    "invalidIf": "Any Alpha person response, tag, log, example, or Problem contains a password or plaintext secret."
  },
  {
    "source": "oneroster.user_profiles.password",
    "alphaDisposition": "cut",
    "reason": "User profile credentials are operational secrets, not roster facts.",
    "itd": {
      "id": "paitd-008-app-credentials",
      "title": "App Credentials Use Vault References, Never Roster Password Fields",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-008-app-credentials"
    },
    "invalidIf": "The value appears outside the managed vault or is exposed through an Alpha API."
  },
  {
    "source": "oneroster.user_profiles.*",
    "alphaDisposition": "restrict",
    "reason": "Profile context can exist in OneRoster provenance, but ordinary Alpha roster reads expose only non-secret profile references and app credential status.",
    "itd": {
      "id": "paitd-009-sensitive-profile-privacy",
      "title": "Sensitive Profiles Are Restricted, Not Default Roster Fields",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-009-sensitive-profile-privacy"
    },
    "invalidIf": "Vendor username, credential type, or profile description leaks into ordinary person or membership list responses."
  },
  {
    "source": "oneroster.demographics.*",
    "alphaDisposition": "restrict",
    "reason": "Sensitive demographic fields move behind alpha.person_sensitive_profile with explicit scopes and audit.",
    "itd": {
      "id": "paitd-009-sensitive-profile-privacy",
      "title": "Sensitive Profiles Are Restricted, Not Default Roster Fields",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-009-sensitive-profile-privacy"
    },
    "invalidIf": "Birth date, sex, race/ethnicity, birth location, or residence status appears in ordinary people lists."
  },
  {
    "source": "oneroster.users.user_ids / identifier / user_master_identifier",
    "alphaDisposition": "cut from ordinary person",
    "reason": "Alpha identity is the plain TimeBack person_id plus authorized contact fields. Extra external identifiers stay in the 1EdTech surface unless a future Alpha ITD ships them.",
    "itd": {
      "id": "paitd-002-person-vocabulary",
      "title": "Person Is The Plain Alias For OneRoster User",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-002-person-vocabulary"
    },
    "invalidIf": "A consumer has to choose between competing person identifiers for ordinary Alpha joins."
  },
  {
    "source": "oneroster.users.preferred_middle_name / pronouns",
    "alphaDisposition": "not public in this attempt",
    "reason": "The approved alias map does not publish these as public Alpha fields. They remain available in the 1EdTech surface until a future People & Orgs architecture ITD adds a privacy-scoped Alpha alias.",
    "itd": {
      "id": "paitd-010-alias-map-contract",
      "title": "Alias Map Is A Generated Architecture Artifact",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-010-alias-map-contract"
    },
    "invalidIf": "A downstream artifact exposes an unmapped public Alpha field."
  },
  {
    "source": "oneroster.users.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech OneRoster ingest rows. Alpha exposes person source_updated_at and platform collection sync controls; consumers must not join roster answers by import batch.",
    "itd": {
      "id": "paitd-010-alias-map-contract",
      "title": "Alias Map Is A Generated Architecture Artifact",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-010-alias-map-contract"
    },
    "invalidIf": "A raw Alpha person query requires import_batch_id or treats one import batch as the roster truth for an as-of-date answer."
  },
  {
    "source": "oneroster.orgs.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech OneRoster ingest rows. Alpha exposes place source_updated_at and platform collection sync controls; consumers must not group schools or districts by ingest batch.",
    "itd": {
      "id": "paitd-010-alias-map-contract",
      "title": "Alias Map Is A Generated Architecture Artifact",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-010-alias-map-contract"
    },
    "invalidIf": "A raw Alpha place query requires import_batch_id or uses it as a tenant, district, brand, modality, or school-period boundary."
  },
  {
    "source": "oneroster.roles.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech role ingest rows. Alpha place_membership answers use person_id, place_id, role_kind, begin_date, end_date, and is_time_locatable instead.",
    "itd": {
      "id": "paitd-004-point-in-time-memberships",
      "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
    },
    "invalidIf": "A raw Alpha place-membership query filters by import_batch_id instead of the documented point-in-time membership rule."
  },
  {
    "source": "oneroster.enrollments.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech enrollment ingest rows. Alpha class_membership answers use person_id, school_id, learning_group_id, role_kind, begin_date, end_date, and is_time_locatable instead.",
    "itd": {
      "id": "paitd-004-point-in-time-memberships",
      "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
    },
    "invalidIf": "A raw Alpha class-membership query filters by import_batch_id instead of tenant, school, learning_group, role, and as-of-date."
  },
  {
    "source": "oneroster.academic_sessions.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech academic-session ingest rows. Alpha school_period exposes typed period fields and source_updated_at for sync.",
    "itd": {
      "id": "paitd-005-school-periods",
      "title": "School Period Is The Plain Alias For Academic Session",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-005-school-periods"
    },
    "invalidIf": "A raw Alpha school-period query uses import_batch_id to infer school-year or term membership."
  },
  {
    "source": "oneroster.demographics.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech demographics ingest rows. Alpha sensitive-profile access is scope-gated and must not expose ingest-batch identifiers.",
    "itd": {
      "id": "paitd-009-sensitive-profile-privacy",
      "title": "Sensitive Profiles Are Restricted, Not Default Roster Fields",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-009-sensitive-profile-privacy"
    },
    "invalidIf": "An Alpha sensitive-profile read or migration exposes import_batch_id outside an authorized 1EdTech audit path."
  },
  {
    "source": "oneroster.user_profiles.import_batch_id",
    "alphaDisposition": "cut from Alpha public view",
    "reason": "Import batch provenance stays on the 1EdTech user-profile ingest rows. Alpha cuts profile secrets and exposes only app_credential secret references.",
    "itd": {
      "id": "paitd-008-app-credentials",
      "title": "App Credentials Use Vault References, Never Roster Password Fields",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-008-app-credentials"
    },
    "invalidIf": "An Alpha app credential or profile query requires OneRoster user_profile import_batch_id."
  },
  {
    "source": "oneroster.roles.status",
    "alphaDisposition": "cut",
    "reason": "The approved alias map does not publish role-row lifecycle status on alpha.place_membership. Alpha answers active membership from begin_date, end_date, and is_time_locatable; OneRoster delta lifecycle remains on the 1EdTech roles surface for audit.",
    "itd": {
      "id": "paitd-004-point-in-time-memberships",
      "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
    },
    "invalidIf": "A raw Alpha roster query treats role status as the active-as-of rule or a downstream artifact exposes an unmapped place_membership source_status field."
  },
  {
    "source": "oneroster.roles.date_last_modified",
    "alphaDisposition": "cut",
    "reason": "The approved alias map does not publish a roles modified timestamp on alpha.place_membership. Consumers use documented membership date windows for as-of answers and platform/API collection clocks for sync.",
    "itd": {
      "id": "paitd-103-query-model",
      "title": "API Axis: Query Model",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
    },
    "invalidIf": "A downstream artifact requires alpha.place_membership.source_updated_at without a new architecture alias-map decision."
  },
  {
    "source": "oneroster.enrollments.status",
    "alphaDisposition": "cut",
    "reason": "The approved alias map does not publish enrollment-row lifecycle status on alpha.class_membership. Alpha answers active class membership from begin_date, end_date, and is_time_locatable; OneRoster delta lifecycle remains on the 1EdTech enrollments surface for audit.",
    "itd": {
      "id": "paitd-004-point-in-time-memberships",
      "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
    },
    "invalidIf": "A raw Alpha class roster query treats enrollment status as the active-as-of rule or a downstream artifact exposes an unmapped class_membership source_status field."
  },
  {
    "source": "oneroster.enrollments.date_last_modified",
    "alphaDisposition": "cut",
    "reason": "The approved alias map does not publish an enrollments modified timestamp on alpha.class_membership. Consumers use documented membership date windows for as-of answers and platform/API collection clocks for sync.",
    "itd": {
      "id": "paitd-103-query-model",
      "title": "API Axis: Query Model",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
    },
    "invalidIf": "A downstream artifact requires alpha.class_membership.source_updated_at without a new architecture alias-map decision."
  },
  {
    "source": "OneRoster classes, courses, resources, lineItems, results, categories, scoreScales",
    "alphaDisposition": "cut by module boundary",
    "reason": "People & Orgs owns who, where, and as-of-date belonging. Content, Results, Curriculum, and Events own the adjacent facts.",
    "itd": {
      "id": "paitd-001-module-boundary",
      "title": "People & Orgs Owns Who, Where, And As-Of-Date Belonging",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-001-module-boundary"
    },
    "invalidIf": "This module stores mastery, test scores, activity events, content effectiveness, curriculum graph, or gradebook rollups."
  },
  {
    "source": "Ed-Fi attendance, discipline, transcripts, health, finance, credentials, evaluation, and full HR/employment records",
    "alphaDisposition": "cut by module boundary",
    "reason": "Only Ed-Fi records that say who someone is or where they belong are exposed here: guardian, guardian_relationship, staff_assignment, and program_participation. Other Ed-Fi domains remain on Ed-Fi, Results, Policy, or other owning surfaces.",
    "itd": {
      "id": "paitd-012-edfi-second-upstream",
      "title": "Ed-Fi Administrative Records Are A Second View-Only Upstream",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-012-edfi-second-upstream"
    },
    "invalidIf": "A People & Orgs row stores attendance, discipline, transcript, staff evaluation, finance, service effectiveness, eligibility, or outcome facts."
  },
  {
    "source": "edfi.draft_record and edfi.canonical_record.is_deleted=true",
    "alphaDisposition": "restrict from ordinary Alpha reads",
    "reason": "Drafts are UI-recovery state and deleted canonical records are audit/retention history. Ordinary Alpha views expose only canonical, non-deleted Ed-Fi facts.",
    "itd": {
      "id": "paitd-012-edfi-second-upstream",
      "title": "Ed-Fi Administrative Records Are A Second View-Only Upstream",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-012-edfi-second-upstream"
    },
    "invalidIf": "A normal guardian, staff_assignment, or program_participation query returns draft records or is_deleted=true rows without an authorized audit/admin path."
  },
  {
    "source": "Ed-Fi descriptor tables for Relation, StaffClassification, ProgramType, and ProgramParticipationStatus",
    "alphaDisposition": "restrict to resolved descriptor values",
    "reason": "The surface resolves descriptors through edfi.descriptor_code so consumers never ship descriptor maps, parse titles, or use free-form tags.",
    "itd": {
      "id": "paitd-012-edfi-second-upstream",
      "title": "Ed-Fi Administrative Records Are A Second View-Only Upstream",
      "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-012-edfi-second-upstream"
    },
    "invalidIf": "A skill pack or raw-query recipe carries its own descriptor table or parses descriptor names in client code."
  }
]

{
  "queryParameters": [
    {
      "name": "asOfDate",
      "type": "ISO 8601 date",
      "required": "Required for active-as-of membership views; optional on raw historical scans.",
      "meaning": "The date the caller wants the roster answer for.",
      "constraints": "Membership rows are active when begin_date is not null, asOfDate >= begin_date, and end_date is null or asOfDate < end_date.",
      "invalidWhen": "Missing from active membership views, malformed, or replaced by currentOnly.",
      "itds": [
        {
          "id": "paitd-004-point-in-time-memberships",
          "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "modifiedSince",
      "type": "ISO 8601 datetime",
      "required": "Optional",
      "meaning": "Requests rows changed after the supplied instant for polling-based sync.",
      "constraints": "Uses the collection's documented source_updated_at, edfi.canonical_record.updated_at, or platform updated_at clock. Unsupported clocks return a typed 400 Problem.",
      "invalidWhen": "Malformed or combined with a cursor in a way the endpoint does not document.",
      "itds": [
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        },
        {
          "id": "paitd-107-eventing-model",
          "title": "API Axis: Eventing Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-107-eventing-model"
        }
      ]
    },
    {
      "name": "includeDeleted",
      "type": "boolean",
      "required": "No; ordinary callers cannot set it.",
      "meaning": "Requests Ed-Fi soft-deleted canonical records for an authorized audit/admin path.",
      "constraints": "Only valid for privileged Ed-Fi-backed guardian, guardian_relationship, staff_assignment, and program_participation audit reads. Ordinary Alpha reads behave as includeDeleted=false.",
      "invalidWhen": "Used without audit/admin scope, used on OneRoster-backed collections, or used to bypass privacy retention rules.",
      "itds": [
        {
          "id": "paitd-012-edfi-second-upstream",
          "title": "Ed-Fi Administrative Records Are A Second View-Only Upstream",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-012-edfi-second-upstream"
        },
        {
          "id": "paitd-111-privacy-retention",
          "title": "API Axis: Privacy / Retention",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
        }
      ]
    },
    {
      "name": "filter",
      "type": "string",
      "required": "Optional",
      "meaning": "Narrows a list to the documented filters named on each table.",
      "constraints": "Unsupported fields or operators return people_orgs:unsupported_query_parameter.",
      "invalidWhen": "The parameter silently does nothing or accepts undocumented field names.",
      "itds": [
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        },
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "name": "reality",
      "type": "real | test | synthetic",
      "required": "Optional; defaults to real on ordinary report reads.",
      "meaning": "Explicitly selects which reality classification to include. Omit it for default customer reports, which include real rows only.",
      "constraints": "Supported on people, places, active-student, history, enrollment-anchor, and guide-inverse reads. Including test or synthetic rows requires an authorized report/debug scope.",
      "invalidWhen": "Missing from a raw SQL report filter, set to an unsupported value, or implemented as name/campus string matching.",
      "itds": [
        {
          "id": "paitd-017-reality-flag",
          "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        },
        {
          "id": "paitd-111-privacy-retention",
          "title": "API Axis: Privacy / Retention",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
        }
      ]
    },
    {
      "name": "sort",
      "type": "string",
      "required": "Optional",
      "meaning": "Orders list results by the documented sort keys named on each table.",
      "constraints": "Unsupported sort keys return a typed 400 Problem.",
      "invalidWhen": "Sorts by a field not documented as sortable.",
      "itds": [
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "cursor",
      "type": "opaque string",
      "required": "Optional",
      "meaning": "Continues a paged list from a server-provided token.",
      "constraints": "Opaque, tenant-scoped, and not client-generated.",
      "invalidWhen": "Parsed by the client or reused across tenants.",
      "itds": [
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "limit",
      "type": "integer",
      "required": "Optional",
      "meaning": "Caps returned rows.",
      "constraints": "Positive integer within the endpoint maximum.",
      "invalidWhen": "Zero, negative, non-integer, or above maximum.",
      "itds": [
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    }
  ],
  "headers": [
    {
      "name": "Authorization",
      "type": "Bearer JWT",
      "required": "Required except demo token mint.",
      "meaning": "Authenticates the caller and supplies tenant and relationship-scoped claims.",
      "constraints": "JWT must include tenant_id or tenantId, role/scopes, and relationship claims where needed.",
      "invalidWhen": "Missing, expired, wrong tenant, or too broad for sensitive profile/credential reads.",
      "itds": [
        {
          "id": "paitd-106-auth-shape",
          "title": "API Axis: Auth Shape",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
        },
        {
          "id": "paitd-109-tenant-routing",
          "title": "API Axis: Tenant Routing",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-109-tenant-routing"
        }
      ]
    },
    {
      "name": "Idempotency-Key",
      "type": "ASCII string",
      "required": "Required on retryable writes.",
      "meaning": "Scopes replay protection for create, update, delete, and rotation commands.",
      "constraints": "Same key and same canonical request hash replays; same key and different request hash returns 409.",
      "invalidWhen": "Missing on retryable writes or reused for a different request body.",
      "itds": [
        {
          "id": "paitd-105-idempotency-model",
          "title": "API Axis: Idempotency Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-105-idempotency-model"
        }
      ]
    },
    {
      "name": "ETag",
      "type": "HTTP entity tag",
      "required": "Returned on mutable resource reads.",
      "meaning": "Validator the client stores before update or delete.",
      "constraints": "Changes when the customer-visible representation changes.",
      "invalidWhen": "Missing from mutable reads.",
      "itds": [
        {
          "id": "paitd-104-concurrency-model",
          "title": "API Axis: Concurrency Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-104-concurrency-model"
        }
      ]
    },
    {
      "name": "If-Match",
      "type": "HTTP entity tag",
      "required": "Required on PUT, PATCH, and DELETE that can overwrite state.",
      "meaning": "Prevents lost updates.",
      "constraints": "Missing precondition returns 428; stale validators return 412 or a documented conflict Problem.",
      "invalidWhen": "Mutation proceeds without a required matching validator.",
      "itds": [
        {
          "id": "paitd-104-concurrency-model",
          "title": "API Axis: Concurrency Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-104-concurrency-model"
        }
      ]
    }
  ],
  "namedQueries": [
    {
      "name": "alphaLevel(student, date)",
      "endpoint": "/people/{personId}/alpha_level?asOfDate=YYYY-MM-DD",
      "resultShape": "{ person_id, alpha_level, begin_date, end_date, is_time_locatable }",
      "rawDbRule": "Read alpha.alpha_level_history for the person with is_time_locatable=true, begin_date <= :as_of_date, and (end_date is null or :as_of_date < end_date), then join alpha.person and require p.reality='real' for ordinary reports.",
      "invalidWhen": "Answered from one mutable current alpha_level field, parsed from place/class names, or returned without the begin/end null rule.",
      "itds": [
        {
          "id": "paitd-018-over-time-history",
          "title": "Alpha Level And Age Grade Keep Effective-Dated History, Read By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-018-over-time-history"
        },
        {
          "id": "paitd-017-reality-flag",
          "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
        },
        {
          "id": "paitd-004-point-in-time-memberships",
          "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
        },
        {
          "id": "paitd-007-tenure-and-grade-context",
          "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "ageGrade(student, date)",
      "endpoint": "/people/{personId}/age_grade?asOfDate=YYYY-MM-DD",
      "resultShape": "{ person_id, age_grade, begin_date, end_date, is_time_locatable }",
      "rawDbRule": "Read alpha.age_grade_history for the person with is_time_locatable=true, begin_date <= :as_of_date, and (end_date is null or :as_of_date < end_date), then join alpha.person and require p.reality='real' for ordinary reports.",
      "invalidWhen": "Answered only from alpha.person.age_grade when the caller asked for a historical date, parsed from class/test labels, or mixed with Results working grade.",
      "itds": [
        {
          "id": "paitd-018-over-time-history",
          "title": "Alpha Level And Age Grade Keep Effective-Dated History, Read By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-018-over-time-history"
        },
        {
          "id": "paitd-017-reality-flag",
          "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
        },
        {
          "id": "paitd-004-point-in-time-memberships",
          "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
        },
        {
          "id": "paitd-007-tenure-and-grade-context",
          "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "firstEnrolledCourseGrade(student, subject)",
      "endpoint": "/people/{personId}/enrollment_anchors/first_enrolled_course_grade?subject=math",
      "resultShape": "{ person_id, subject, grade_level, first_enrolled_course_grade_level, grade_levels, course_grade_mode, first_enrolled_course_begin_date, evidence_membership_id }",
      "rawDbRule": "Public People & Orgs subject query values are the canonical lowercase Alpha subject ids: math, reading, language, science, vocabulary, writing. Display/source aliases such as Math or Mathematics are folded only at import/write boundaries and are validation errors on public reads. Use the surface-owned query/read function so the subject, course_grade_mode, and course_grade_levels come from Curriculum's typed learning-group/course context and the enrollment date comes from alpha.class_membership. The raw path must not parse subject or grade from class names.",
      "invalidWhen": "Computed by parsing course titles, using the single-grade-only anchor as the general first-course answer, treating multi-grade courses as single-grade, using display/source aliases such as subject=Math on public reads, ignoring begin_date null rows, or selecting a test/synthetic person/place by default.",
      "itds": [
        {
          "id": "paitd-004-point-in-time-memberships",
          "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
        },
        {
          "id": "paitd-007-tenure-and-grade-context",
          "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "firstSingleGradeEnrollmentDate(student, subject)",
      "endpoint": "/people/{personId}/enrollment_anchors/first_single_grade?subject=math",
      "resultShape": "{ person_id, subject, grade_level, first_single_grade_enrollment_date, evidence_membership_id }",
      "rawDbRule": "Public People & Orgs subject query values are the canonical lowercase Alpha subject ids: math, reading, language, science, vocabulary, writing. Display/source aliases such as Math or Mathematics are folded only at import/write boundaries and are validation errors on public reads. Use the surface-owned query/read function so the subject and single-grade classification come from Curriculum's typed learning-group/course context and the enrollment dates come from alpha.class_membership. The raw path must not parse subject or grade from class names.",
      "invalidWhen": "Computed by parsing course titles, treating multi-grade courses as single-grade, using display/source aliases such as subject=Math on public reads, ignoring begin_date null rows, or selecting a test/synthetic person/place by default.",
      "itds": [
        {
          "id": "paitd-004-point-in-time-memberships",
          "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
        },
        {
          "id": "paitd-007-tenure-and-grade-context",
          "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        }
      ]
    },
    {
      "name": "studentsForGuide(guide, date)",
      "endpoint": "/guides/{guidePersonId}/students?asOfDate=YYYY-MM-DD",
      "resultShape": "{ guide_person_id, student_person_id, learning_group_id, school_id, begin_date, end_date }[]",
      "rawDbRule": "Join active guide class_membership rows to active student class_membership rows on tenant_id, school_id, and learning_group_id for the same asOfDate; join alpha.person for both sides and alpha.place for the school; require all joined person/place reality values to be real unless explicitly including test/synthetic rows.",
      "invalidWhen": "Implemented as an undocumented two-hop in the client, inferred from staff titles, missing asOfDate, or returning test/synthetic students in ordinary reports.",
      "itds": [
        {
          "id": "paitd-004-point-in-time-memberships",
          "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
        },
        {
          "id": "paitd-102-read-shape",
          "title": "API Axis: Read Shape",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-102-read-shape"
        },
        {
          "id": "paitd-103-query-model",
          "title": "API Axis: Query Model",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
        },
        {
          "id": "paitd-106-auth-shape",
          "title": "API Axis: Auth Shape",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
        }
      ]
    }
  ],
  "problemCategories": [
    {
      "code": "people_orgs:unsupported_query_parameter",
      "status": 400,
      "callerFix": "Remove or replace the query parameter with a documented filter, sort, cursor, limit, modifiedSince, or asOfDate parameter.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "code": "people_orgs:validation_failed",
      "status": 400,
      "callerFix": "Fix field type, range, requiredness, enum, or relationship errors named in fieldErrors.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "code": "people_orgs:tenant_forbidden",
      "status": 403,
      "callerFix": "Use a token scoped to the tenant and relationship being read.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "code": "people_orgs:sensitive_scope_required",
      "status": 403,
      "callerFix": "Request a token with sensitive-profile or credential-status scope and the required relationship claim.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "code": "people_orgs:not_found",
      "status": 404,
      "callerFix": "Check tenant scope and id. The response does not reveal cross-tenant existence.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "code": "people_orgs:idempotency_conflict",
      "status": 409,
      "callerFix": "Replay the exact original request with the same key or use a new key for a different write.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    },
    {
      "code": "people_orgs:precondition_required",
      "status": 428,
      "callerFix": "Refetch the resource, keep its ETag, and send If-Match.",
      "itds": [
        {
          "id": "paitd-108-error-envelope",
          "title": "API Axis: Error Envelope",
          "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-108-error-envelope"
        }
      ]
    }
  ]
}

[
  {
    "name": "personLifecycleDates(person)",
    "endpoint": "/people and /people/{personId}",
    "resultShape": "{ person_id, admission_date, exit_date }",
    "rawDbRule": "alpha.person.admission_date and alpha.person.exit_date come only from alpha.person_ext. admission_date is the person-level lifecycle open date; exit_date is the exclusive person-level lifecycle close date; null exit_date means still active/open after admission_date. Membership begin_date/end_date and school_period start_date/end_date are separate interval facts.",
    "invalidWhen": "A consumer or doer treats membership end_date as person exit_date, uses school_period start_date as admission_date, or advertises a generic start_date for person lifecycle.",
    "itds": [
      {
        "id": "paitd-002-person-vocabulary",
        "title": "Person Vocabulary",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture/#paitd-002-person-vocabulary"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture/#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-011-storage-model",
        "title": "Storage Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture/#paitd-011-storage-model"
      }
    ]
  },
  {
    "name": "alphaLevel(student, date)",
    "endpoint": "/people/{personId}/alpha_level?asOfDate=YYYY-MM-DD",
    "resultShape": "{ person_id, alpha_level, begin_date, end_date, is_time_locatable }",
    "rawDbRule": "Read alpha.alpha_level_history for the person with is_time_locatable=true, begin_date <= :as_of_date, and (end_date is null or :as_of_date < end_date), then join alpha.person and require p.reality='real' for ordinary reports.",
    "invalidWhen": "Answered from one mutable current alpha_level field, parsed from place/class names, or returned without the begin/end null rule.",
    "itds": [
      {
        "id": "paitd-018-over-time-history",
        "title": "Alpha Level And Age Grade Keep Effective-Dated History, Read By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-018-over-time-history"
      },
      {
        "id": "paitd-017-reality-flag",
        "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
      },
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "ageGrade(student, date)",
    "endpoint": "/people/{personId}/age_grade?asOfDate=YYYY-MM-DD",
    "resultShape": "{ person_id, age_grade, begin_date, end_date, is_time_locatable }",
    "rawDbRule": "Read alpha.age_grade_history for the person with is_time_locatable=true, begin_date <= :as_of_date, and (end_date is null or :as_of_date < end_date), then join alpha.person and require p.reality='real' for ordinary reports.",
    "invalidWhen": "Answered only from alpha.person.age_grade when the caller asked for a historical date, parsed from class/test labels, or mixed with Results working grade.",
    "itds": [
      {
        "id": "paitd-018-over-time-history",
        "title": "Alpha Level And Age Grade Keep Effective-Dated History, Read By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-018-over-time-history"
      },
      {
        "id": "paitd-017-reality-flag",
        "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
      },
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "activePersonalizedCourseBindings(student, date)",
    "endpoint": "/people/{personId}/active_course_bindings?asOfDate=YYYY-MM-DD&reality=real",
    "resultShape": "{ person_id, asOfDate, reality, data[{ course_id, source_course_ref, subject_id, course_grade_mode, course_grade_levels[], student_id, next_lesson_path, evidence_memberships[] }], count, links }",
    "rawDbRule": "Start from active alpha.class_membership rows for the exact real student and date using begin_date <= :as_of_date and (:as_of_date < end_date or end_date is null). Join the exact OneRoster class course_sourced_id to alpha.curriculum_courses.source_refs. Return only non-retired published personalized static course roots whose stored alpha.student_id exactly equals the requested person. subject_id is the eight-value authoring registry id owned by loop/context/authoring-subject-registry.json; explicit machine subject codes outrank display labels and unsupported machine codes fail closed. A source_course_ref resolving to multiple active roots is a typed conflict across all active learning groups. The separate enrolled_grade and enrollment-anchor reads remain exact-six reporting contracts.",
    "invalidWhen": "A client composes subject-specific reads, parses course or class labels, infers student ownership from a name, omits asOfDate, admits shared/draft/dynamic/wrong-owner roots, treats malformed or timed-out dependency data as absence, or expands the exact-six reporting registry.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      }
    ]
  },
  {
    "name": "enrolledGradeInSubject(student, subject, date)",
    "endpoint": "/people/{personId}/enrolled_grade?subject=math&asOfDate=YYYY-MM-DD",
    "resultShape": "{ person_id, subject, asOfDate, grade_level, grade_levels, enrolled_grade_mode, curriculum_course_bindings[], evidence_memberships[] }",
    "rawDbRule": "Public People & Orgs subject query values are the canonical lowercase Alpha subject ids: math, reading, language, science, vocabulary, writing. Display/source aliases such as Math or Mathematics are folded only at import/write boundaries and are validation errors on public reads. Use the surface-owned query/read function so the subject and grade context come from imported typed OneRoster class/course context for the active learning_group_id, and the date window comes from active alpha.class_membership rows with is_time_locatable=true, begin_date <= :as_of_date, and (end_date is null or :as_of_date < end_date). OneRoster subjects is multi-valued: every canonical subject declared by the exact class/course row materializes independently without duplicating the class or membership. curriculum_course_bindings[].course_id is resolved only by exact source_course_ref/source_refs over alpha.curriculum_courses; that same exact course binds each of its declared canonical source subjects even when Curriculum records one primary subject_id. The returned id is for Curriculum GET /alpha/curriculum/v1/courses/{courseId}/next-lesson. Untyped or unsupported source subjects such as FastMath remain absence; non-404 upstream/storage errors are not absence. Join alpha.person and alpha.place and require real student/school rows for ordinary reports.",
    "invalidWhen": "Computed by parsing course titles, answered from age_grade or Results working grade, using display/source aliases such as subject=Math on public reads, ignoring begin_date null rows, missing asOfDate, or selecting a test/synthetic person/place by default.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "firstEnrolledCourseGrade(student, subject)",
    "endpoint": "/people/{personId}/enrollment_anchors/first_enrolled_course_grade?subject=math",
    "resultShape": "{ person_id, subject, grade_level, first_enrolled_course_grade_level, grade_levels, course_grade_mode, first_enrolled_course_begin_date, evidence_membership_id }",
    "rawDbRule": "Public People & Orgs subject query values are the canonical lowercase Alpha subject ids: math, reading, language, science, vocabulary, writing. Display/source aliases such as Math or Mathematics are folded only at import/write boundaries and are validation errors on public reads. Use the surface-owned query/read function so the subject, course_grade_mode, and course_grade_levels come from Curriculum's typed learning-group/course context and the enrollment date comes from alpha.class_membership. The raw path must not parse subject or grade from class names.",
    "invalidWhen": "Computed by parsing course titles, using the single-grade-only anchor as the general first-course answer, treating multi-grade courses as single-grade, using display/source aliases such as subject=Math on public reads, ignoring begin_date null rows, or selecting a test/synthetic person/place by default.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "firstSingleGradeEnrollmentDate(student, subject)",
    "endpoint": "/people/{personId}/enrollment_anchors/first_single_grade?subject=math",
    "resultShape": "{ person_id, subject, grade_level, first_single_grade_enrollment_date, evidence_membership_id }",
    "rawDbRule": "Public People & Orgs subject query values are the canonical lowercase Alpha subject ids: math, reading, language, science, vocabulary, writing. Display/source aliases such as Math or Mathematics are folded only at import/write boundaries and are validation errors on public reads. Use the surface-owned query/read function so the subject and single-grade classification come from Curriculum's typed learning-group/course context and the enrollment dates come from alpha.class_membership. The raw path must not parse subject or grade from class names.",
    "invalidWhen": "Computed by parsing course titles, treating multi-grade courses as single-grade, using display/source aliases such as subject=Math on public reads, ignoring begin_date null rows, or selecting a test/synthetic person/place by default.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "studentsForGuide(guide, date)",
    "endpoint": "/guides/{guidePersonId}/students?asOfDate=YYYY-MM-DD",
    "resultShape": "{ guide_person_id, student_person_id, learning_group_id, school_id, begin_date, end_date }[]",
    "rawDbRule": "Join active guide class_membership rows to active student class_membership rows on tenant_id, school_id, and learning_group_id for the same asOfDate; join alpha.person for both sides and alpha.place for the school; require all joined person/place reality values to be real unless explicitly including test/synthetic rows.",
    "invalidWhen": "Implemented as an undocumented two-hop in the client, inferred from staff titles, missing asOfDate, or returning test/synthetic students in ordinary reports.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-102-read-shape",
        "title": "API Axis: Read Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-102-read-shape"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      }
    ]
  }
]

[
  {
    "key": "alpha.policy.reality_source_mapping",
    "type": "write-boundary source mapping",
    "owner": "People & Orgs surface config",
    "meaning": "Maps authoritative SIS and TimeBack source classifications to the closed reality enum without parsing names or campus labels.",
    "requiredBy": "person.reality, place.reality, default real-only report reads, migration backfill, and deployed smoke tests that exclude test data.",
    "invalidWhen": "A report ships an exclude-list, regexes campus/person names, or treats missing reality as real.",
    "example": {
      "authoritative_real": "real",
      "qa_or_agent_test": "test",
      "generated_fixture": "synthetic"
    },
    "itds": [
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "key": "alpha.policy.tenure_buckets",
    "type": "ordered bucket config",
    "owner": "People & Orgs surface config",
    "meaning": "Defines tenure bands computed from person.admission_date and asOfDate.",
    "requiredBy": "Tenure reports and cohort filters.",
    "invalidWhen": "A dashboard or skill pack hardcodes bucket edges instead of calling the surface.",
    "example": [
      {
        "label": "0-0.5 year",
        "min_days": 0,
        "max_days": 182
      },
      {
        "label": "0.5-1 year",
        "min_days": 183,
        "max_days": 365
      },
      {
        "label": "1-2 years",
        "min_days": 366,
        "max_days": 730
      },
      {
        "label": "2-3 years",
        "min_days": 731,
        "max_days": 1095
      },
      {
        "label": "3+ years",
        "min_days": 1096,
        "max_days": null
      }
    ],
    "itds": [
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      }
    ]
  },
  {
    "key": "alpha.policy.grade_alias_folds",
    "type": "alias-fold config",
    "owner": "People & Orgs surface config",
    "meaning": "Maps source grade aliases to the closed grade_level enum at write time.",
    "requiredBy": "person.grade_levels and person.age_grade.",
    "invalidWhen": "A consumer parses grade strings from users.grades, class names, or test names at read time.",
    "example": {
      "0": 0,
      "7": 7,
      "13": "reject_or_reconcile",
      "PK": -1,
      "-1": -1,
      "K": 0,
      "4TH_GRADE": 4,
      "Grade_4": 4
    },
    "itds": [
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      }
    ]
  },
  {
    "key": "alpha.policy.alpha_level_alias_folds",
    "type": "alias-fold config",
    "owner": "People & Orgs surface config",
    "meaning": "Maps live source alpha-level labels to the closed alpha_level enum at write time.",
    "requiredBy": "alpha_level reporting and point-in-time cohort slices.",
    "invalidWhen": "A consumer parses level labels from users_visibility.user_alpha_level or place names at read time.",
    "example": {
      "PKBY": "WL",
      "WL": "WL",
      "Linc": "LL",
      "LL": "LL",
      "L3": "MS",
      "Middle School": "MS",
      "L4.1": "HS",
      "L4.2": "HS",
      "L4.3": "HS",
      "High School": "HS"
    },
    "itds": [
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-006-tag-registry",
        "title": "Governed Tags Are Report Slices Only",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-006-tag-registry"
      }
    ]
  },
  {
    "key": "alpha.policy.brand_alias_folds",
    "type": "alias-fold config",
    "owner": "People & Orgs setup import",
    "meaning": "Maps live org labels and campus-taxonomy aliases to the closed brand enum at write time.",
    "requiredBy": "place.brand and NWEA Brand x Modality account grouping.",
    "invalidWhen": "A report groups by parsed school names or maintains its own campus taxonomy.",
    "example": {
      "Alpha School": "alpha",
      "Alpha Anywhere": "alpha",
      "GT School": "gt",
      "GT Anywhere": "gt",
      "TSA Online": "texas_sports_academy",
      "Texas Sports Academy": "texas_sports_academy"
    },
    "itds": [
      {
        "id": "paitd-003-place-nwea-boundary",
        "title": "Place Is The Plain Alias For OneRoster Org And District Is The NWEA Account",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-003-place-nwea-boundary"
      },
      {
        "id": "paitd-006-tag-registry",
        "title": "Governed Tags Are Report Slices Only",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-006-tag-registry"
      }
    ]
  },
  {
    "key": "alpha.policy.segment_alias_folds",
    "type": "alias-fold config",
    "owner": "People & Orgs setup import",
    "meaning": "Maps live org labels and campus-taxonomy aliases to the closed segment enum at write time.",
    "requiredBy": "place.segment and reporting slices.",
    "invalidWhen": "A dashboard parses segment from place.name, campusId, or a stale local list.",
    "example": {
      "Private": "private",
      "Virtual": "virtual",
      "SW Sales": "sw_sales",
      "Charter": "charter",
      "multi-segment district": "mixed"
    },
    "itds": [
      {
        "id": "paitd-003-place-nwea-boundary",
        "title": "Place Is The Plain Alias For OneRoster Org And District Is The NWEA Account",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-003-place-nwea-boundary"
      },
      {
        "id": "paitd-006-tag-registry",
        "title": "Governed Tags Are Report Slices Only",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-006-tag-registry"
      }
    ]
  },
  {
    "key": "alpha.policy.school_year_boundaries",
    "type": "date-boundary config",
    "owner": "Surface config shared with school_period reads",
    "meaning": "Defines the school-year boundary used by policy computations that need a year start/end.",
    "requiredBy": "asOfDate reports that align roster context to school-year windows.",
    "invalidWhen": "A report hardcodes start/end dates or parses them from school_period.title.",
    "example": {
      "start_month": 8,
      "start_day": 1,
      "end_month": 7,
      "end_day": 31
    },
    "itds": [
      {
        "id": "paitd-005-school-periods",
        "title": "School Period Is The Plain Alias For Academic Session",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-005-school-periods"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      }
    ]
  },
  {
    "key": "alpha.policy.school_day",
    "type": "enumerable school-day calendar",
    "owner": "People & Orgs calendar reads over Ed-Fi CalendarDate",
    "meaning": "Defines school-day answers from alpha.school_calendar, a view over Ed-Fi CalendarDate records keyed by school. Consumers call the surface for is-school-day, school-days-in-range, school-days-between, school-days-remaining, and next-school-year-start instead of counting weekdays or carrying holiday tables.",
    "requiredBy": "GOALS date-to-effort arithmetic, within-grade pacing, minutes-per-school-day denominators, and school-day reports.",
    "invalidWhen": "A client counts weekdays, skips summer gaps locally, stores local holidays, or parses school_period start/end dates as a school-day list.",
    "example": {
      "source_view": "alpha.school_calendar",
      "source_truth": "ed_fi.CalendarDate",
      "reason_values": [
        "instructional",
        "weekend",
        "teacher_workshop",
        "holiday_break",
        "nwea_map_testing",
        "other"
      ],
      "range_inclusive": true,
      "regression": {
        "school_id": "place_north_valley_school",
        "start_date": "2025-08-13",
        "end_date": "2026-07-24",
        "school_days_between": 204
      }
    },
    "itds": [
      {
        "id": "paitd-005-school-periods",
        "title": "School Period Is The Plain Alias For Academic Session",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-005-school-periods"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "key": "alpha.policy.expected_xp_minute_convention",
    "type": "effort unit convention",
    "owner": "Cross-module policy surfaced here for roster-calendar consumers",
    "meaning": "1 expected XP is approximately 1 expected minute. Convert expected_xp to planned hours with expected_xp / 60 before applying school-day pacing.",
    "requiredBy": "GOALS effort-per-school-day calculations and any report that turns expected XP into time.",
    "invalidWhen": "A consumer learns the XP-minute relationship from production defaults such as default_xp_goal == default_minutes_goal or applies awarded XP history as expected effort.",
    "example": {
      "expected_xp": 360,
      "expected_minutes": 360,
      "planned_hours_before_calendar_pacing": 6
    },
    "itds": [
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      }
    ]
  }
]

[
  {
    "name": "students",
    "definition": "Filter alpha.person to people with an active place_membership or class_membership where role_kind=student at asOfDate.",
    "notStorage": "Not a new table; person plus memberships remain the storage contract.",
    "invalidWhen": "A student row stores mastery, working grade, MAP result, or advancement. Those facts live in Results."
  },
  {
    "name": "parents_and_guardians",
    "definition": "Use alpha.guardian_view plus alpha.guardian_relationship_view for Ed-Fi guardian/contact facts, and alpha.person family_or_agent_person_ids only for thin OneRoster agent links.",
    "notStorage": "Guardian/contact facts are Ed-Fi-backed views, not Alpha tables; OneRoster family links remain real ids, never tags.",
    "invalidWhen": "A parent/guardian relationship is stored as a free-form tag or copied into an Alpha own-table."
  },
  {
    "name": "guides",
    "definition": "Filter alpha.person to people with role_kind=guide or class_membership.role_kind=guide at asOfDate. The inverse studentsForGuide(guide, date) joins active guide and student class_membership rows on learning_group_id and school_id.",
    "notStorage": "Not a new table; guide assignment is a dated membership and the inverse is a first-class query over those memberships.",
    "invalidWhen": "A guide is inferred by parsing a class title or email domain, or studentsForGuide is rebuilt as an undocumented client-side two-hop."
  },
  {
    "name": "staff_and_administrators",
    "definition": "Filter alpha.person to people with active staff/admin memberships for simple roster roles; use alpha.staff_assignment_view for Ed-Fi assignment-specific facts such as staff classification, title, assignment order, and full-time equivalency.",
    "notStorage": "Not a new table; staff/admin roles are dated memberships and assignment detail is an Ed-Fi-backed view.",
    "invalidWhen": "An admin list bypasses asOfDate, ignores relationship-scoped auth, or parses titles instead of using staff_classification."
  },
  {
    "name": "program_participants",
    "definition": "Use alpha.program_participation_view to answer which administrative programs a student belongs to at a place as of a date.",
    "notStorage": "Not a tag and not a Results object; it is an Ed-Fi-backed relationship view.",
    "invalidWhen": "Program participation is stored as a tag, mixed with outcomes/eligibility formulas, or queried without the begin/end date rule."
  }
]

[
  {
    "title": "Query: active students in one school on one date",
    "job": "Use this when a teacher, parent report, or app-builder LLM asks for the roster of real students for a school as of a date.",
    "setup": "export PEOPLE_ORGS_BASE_URL=\"$BASE_URL\"\nexport PEOPLE_ORGS_JWT=\"$JWT\"\nexport AS_OF_DATE=\"2026-09-15\"\nexport SCHOOL_ID=\"place_north_valley_school\"\nexport TENANT_ID=\"0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3\"",
    "api": "curl -sS \"$PEOPLE_ORGS_BASE_URL/people?asOfDate=$AS_OF_DATE&reality=real&filter=roleKind:eq:student,schoolId:eq:$SCHOOL_ID&sort=last_name,first_name\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\"",
    "sql": "WITH active_students AS (\n  -- Row grain: one active class-membership row per student per learning group.\n  -- DISTINCT below intentionally folds this to one person row for the people list;\n  -- it is not a substitute for tenant_id, school_id, role_kind, or asOfDate joins.\n  SELECT DISTINCT cm.tenant_id, cm.person_id\n  FROM alpha.class_membership cm\n  WHERE cm.tenant_id = :'tenant_id'\n    AND cm.school_id = :'school_id'\n    AND cm.role_kind = 'student'\n    AND cm.is_time_locatable IS TRUE\n    AND cm.begin_date <= :'as_of_date'::date\n    AND (cm.end_date IS NULL OR :'as_of_date'::date < cm.end_date)\n)\nSELECT p.person_id, p.first_name, p.last_name, p.email, p.age_grade\nFROM alpha.person p\nJOIN active_students s\n  ON s.tenant_id = p.tenant_id\n AND s.person_id = p.person_id\nJOIN alpha.place school\n  ON school.tenant_id = s.tenant_id\n AND school.place_id = :'school_id'\nWHERE p.tenant_id = :'tenant_id'\n  AND p.reality = 'real'\n  AND school.reality = 'real'\n  AND COALESCE(p.source_status, 'active') <> 'tobedeleted'\n  AND COALESCE(school.source_status, 'active') <> 'tobedeleted'\nORDER BY p.last_name, p.first_name, p.person_id;",
    "sameAnswerRule": "The API and raw SQL must return the same person ids in the same order. If they diverge, check tenant scope, person/place reality=real, source_status tombstones, role_kind=student, school_id, the asOfDate membership rule, and the stated row grain before changing consumer code.",
    "itds": [
      {
        "id": "paitd-017-reality-flag",
        "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
      },
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      },
      {
        "id": "paitd-109-tenant-routing",
        "title": "API Axis: Tenant Routing",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-109-tenant-routing"
      },
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "title": "Query: alpha level and age grade for a student on one date",
    "job": "Use this when a progress report asks what Alpha level or age grade was true on a historical date.",
    "setup": "export PEOPLE_ORGS_BASE_URL=\"$BASE_URL\"\nexport PEOPLE_ORGS_JWT=\"$JWT\"\nexport AS_OF_DATE=\"2026-09-15\"\nexport STUDENT_PERSON_ID=\"person_ada_lovelace\"\nexport TENANT_ID=\"0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3\"",
    "api": "curl -sS \"$PEOPLE_ORGS_BASE_URL/people/$STUDENT_PERSON_ID/alpha_level?asOfDate=$AS_OF_DATE&reality=real\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\"\n\ncurl -sS \"$PEOPLE_ORGS_BASE_URL/people/$STUDENT_PERSON_ID/age_grade?asOfDate=$AS_OF_DATE&reality=real\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\"",
    "sql": "SELECT\n  p.person_id,\n  al.alpha_level,\n  ag.age_grade\nFROM alpha.person p\nLEFT JOIN alpha.alpha_level_history al\n  ON al.tenant_id = p.tenant_id\n AND al.person_id = p.person_id\n AND al.is_time_locatable IS TRUE\n AND al.begin_date <= :'as_of_date'::date\n AND (al.end_date IS NULL OR :'as_of_date'::date < al.end_date)\nLEFT JOIN alpha.age_grade_history ag\n  ON ag.tenant_id = p.tenant_id\n AND ag.person_id = p.person_id\n AND ag.is_time_locatable IS TRUE\n AND ag.begin_date <= :'as_of_date'::date\n AND (ag.end_date IS NULL OR :'as_of_date'::date < ag.end_date)\nWHERE p.tenant_id = :'tenant_id'\n  AND p.person_id = :'student_person_id'\n  AND p.reality = 'real'\n  AND COALESCE(p.source_status, 'active') <> 'tobedeleted';",
    "sameAnswerRule": "The API and raw SQL must return the same alpha_level and age_grade for the same asOfDate. If they diverge, check reality=real, duplicate overlapping history rows, and the begin_date/end_date/is_time_locatable null rule before changing consumer code.",
    "itds": [
      {
        "id": "paitd-018-over-time-history",
        "title": "Alpha Level And Age Grade Keep Effective-Dated History, Read By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-018-over-time-history"
      },
      {
        "id": "paitd-017-reality-flag",
        "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
      },
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "title": "Query: students for one guide on one date",
    "job": "Use this when a guide dashboard asks which real students a guide serves as of a date.",
    "setup": "export PEOPLE_ORGS_BASE_URL=\"$BASE_URL\"\nexport PEOPLE_ORGS_JWT=\"$JWT\"\nexport AS_OF_DATE=\"2026-09-15\"\nexport GUIDE_PERSON_ID=\"person_katherine_johnson\"\nexport TENANT_ID=\"0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3\"",
    "api": "curl -sS \"$PEOPLE_ORGS_BASE_URL/guides/$GUIDE_PERSON_ID/students?asOfDate=$AS_OF_DATE&reality=real\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\"",
    "sql": "WITH active_guide_groups AS (\n  SELECT tenant_id, school_id, learning_group_id, begin_date, end_date\n  FROM alpha.class_membership\n  WHERE tenant_id = :'tenant_id'\n    AND person_id = :'guide_person_id'\n    AND role_kind = 'guide'\n    AND is_time_locatable IS TRUE\n    AND begin_date <= :'as_of_date'::date\n    AND (end_date IS NULL OR :'as_of_date'::date < end_date)\n),\nactive_student_groups AS (\n  SELECT cm.tenant_id, cm.person_id, cm.school_id, cm.learning_group_id, cm.begin_date, cm.end_date\n  FROM alpha.class_membership cm\n  JOIN active_guide_groups gg\n    ON gg.tenant_id = cm.tenant_id\n   AND gg.school_id = cm.school_id\n   AND gg.learning_group_id = cm.learning_group_id\n  WHERE cm.role_kind = 'student'\n    AND cm.is_time_locatable IS TRUE\n    AND cm.begin_date <= :'as_of_date'::date\n    AND (cm.end_date IS NULL OR :'as_of_date'::date < cm.end_date)\n)\nSELECT DISTINCT\n  -- Row grain: one row per guide/student/school/learning_group after the active\n  -- membership join. DISTINCT only removes duplicate overlapping evidence for\n  -- the same returned person row; it must never hide a missing join predicate.\n  :'guide_person_id' AS guide_person_id,\n  student.person_id AS student_person_id,\n  student.first_name,\n  student.last_name,\n  sg.school_id,\n  sg.learning_group_id\nFROM active_student_groups sg\nJOIN alpha.person student\n  ON student.tenant_id = sg.tenant_id\n AND student.person_id = sg.person_id\nJOIN alpha.person guide\n  ON guide.tenant_id = sg.tenant_id\n AND guide.person_id = :'guide_person_id'\nJOIN alpha.place school\n  ON school.tenant_id = sg.tenant_id\n AND school.place_id = sg.school_id\nWHERE student.reality = 'real'\n  AND guide.reality = 'real'\n  AND school.reality = 'real'\nORDER BY student.last_name, student.first_name, student.person_id;",
    "sameAnswerRule": "The API and raw SQL must return the same student ids for the guide/date. If they diverge, check the guide role, shared tenant_id/school_id/learning_group_id, asOfDate windows, tenant scope, row grain, and real-only filters before rebuilding a two-hop client query.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-102-read-shape",
        "title": "API Axis: Read Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-102-read-shape"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      }
    ]
  },
  {
    "title": "Query: first single-grade enrollment date in a subject",
    "job": "Use this when a school-year-start anchor or growth report needs the first date a real student entered a single-grade learning group for a subject.",
    "setup": "export PEOPLE_ORGS_BASE_URL=\"$BASE_URL\"\nexport PEOPLE_ORGS_JWT=\"$JWT\"\nexport STUDENT_PERSON_ID=\"person_ada_lovelace\"\nexport SUBJECT=\"Math\"\nexport TENANT_ID=\"0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3\"",
    "api": "curl -sS \"$PEOPLE_ORGS_BASE_URL/people/$STUDENT_PERSON_ID/enrollment_anchors/first_single_grade?subject=$SUBJECT&reality=real\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\"",
    "sql": "SELECT *\nFROM alpha.first_single_grade_enrollment_date(\n  tenant_id => :'tenant_id'::uuid,\n  student_person_id => :'student_person_id',\n  subject => :'subject',\n  reality => 'real'\n);",
    "sameAnswerRule": "The API and raw SQL function must return the same first_single_grade_enrollment_date and evidence_membership_id. The function owns the Curriculum subject/single-grade join and the People & Orgs begin/end null rule so consumers do not parse class names or keep subject maps.",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "title": "Query: legal guardians and primary contacts for one student",
    "job": "Use this when a parent portal, guide dashboard, or app-builder LLM asks who may act for or contact a student.",
    "setup": "export PEOPLE_ORGS_BASE_URL=\"$BASE_URL\"\nexport PEOPLE_ORGS_JWT=\"$JWT\"\nexport STUDENT_PERSON_ID=\"person_ada_lovelace\"\nexport TENANT_ID=\"0d4ce2f4-1c42-4f3c-9f0d-03fb7f5271d3\"",
    "api": "curl -sS \"$PEOPLE_ORGS_BASE_URL/guardian_relationships?filter=studentPersonId:eq:$STUDENT_PERSON_ID&sort=contact_priority,guardian_id\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\"",
    "sql": "SELECT\n  gr.guardian_relationship_id,\n  gr.student_person_id,\n  gr.guardian_id,\n  g.full_name,\n  gr.relationship_kind,\n  gr.is_legal_guardian,\n  gr.is_primary_contact,\n  gr.is_emergency_contact,\n  gr.contact_priority\nFROM alpha.guardian_relationship_view gr\nJOIN alpha.guardian_view g\n  ON g.tenant_id = gr.tenant_id\n AND g.guardian_id = gr.guardian_id\nWHERE gr.tenant_id = :'tenant_id'\n  AND gr.student_person_id = :'student_person_id'\n  AND COALESCE(g.is_deleted, false) IS FALSE\nORDER BY gr.contact_priority NULLS LAST, gr.guardian_id;",
    "sameAnswerRule": "The API and raw SQL must return the same guardian_relationship ids. If they diverge, check tenant scope, Ed-Fi canonical-only state, is_deleted=false, descriptor_code resolution, and OneRoster sourcedId joins before changing consumer code.",
    "itds": [
      {
        "id": "paitd-012-edfi-second-upstream",
        "title": "Ed-Fi Administrative Records Are A Second View-Only Upstream",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-012-edfi-second-upstream"
      },
      {
        "id": "paitd-013-guardian-views",
        "title": "Guardians Come From Ed-Fi Contact And StudentContactAssociation Views",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-013-guardian-views"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      },
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "title": "Migration: backfill person_ext and place_ext without copying base rows",
    "job": "Use this when a migration needs to add Alpha-owned tenure, age-grade, or NWEA-account context after OneRoster people and places already exist.",
    "setup": "-- psql variables expected:\n--   :tenant_id\n-- This migration writes only allowed Alpha extension tables.\n-- It validates every row against alpha.person_base or alpha.place_base first.",
    "api": "# API-equivalent per-resource writes route sourced fields to OneRoster\n# and extension fields to the owning Alpha extension table.\ncurl -sS -X PATCH \"$PEOPLE_ORGS_BASE_URL/people/person_ada_lovelace\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"admissionDate\":\"2025-08-18\",\"exitDate\":null,\"ageGrade\":7,\"reality\":\"real\"}'\n\ncurl -sS -X PATCH \"$PEOPLE_ORGS_BASE_URL/places/place_timeback_physical_district\" \\\n  -H \"Authorization: Bearer $PEOPLE_ORGS_JWT\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"nweaDistrictId\":\"nwea-district-physical-001\",\"reality\":\"real\"}'",
    "sql": "BEGIN;\n\nWITH incoming_person_ext(tenant_id, person_id, admission_date, exit_date, age_grade, reality) AS (\n  VALUES\n    (:'tenant_id'::uuid, 'person_ada_lovelace', DATE '2025-08-18', NULL::date, 7, 'real')\n),\nvalidated_person_ext AS (\n  SELECT i.*\n  FROM incoming_person_ext i\n  JOIN alpha.person_base pb\n    ON pb.tenant_id = i.tenant_id\n   AND pb.person_id = i.person_id\n)\nINSERT INTO alpha.person_ext (\n  tenant_id, person_id, admission_date, exit_date, age_grade, reality\n)\nSELECT tenant_id, person_id, admission_date, exit_date, age_grade, reality\nFROM validated_person_ext\nON CONFLICT (tenant_id, person_id) DO UPDATE\nSET admission_date = EXCLUDED.admission_date,\n    exit_date = EXCLUDED.exit_date,\n    age_grade = EXCLUDED.age_grade,\n    reality = EXCLUDED.reality;\n\nWITH incoming_place_ext(tenant_id, place_id, nwea_district_id, reality) AS (\n  VALUES\n    (:'tenant_id'::uuid, 'place_timeback_physical_district', 'nwea-district-physical-001', 'real')\n),\nvalidated_place_ext AS (\n  SELECT i.*\n  FROM incoming_place_ext i\n  JOIN alpha.place_base pb\n    ON pb.tenant_id = i.tenant_id\n   AND pb.place_id = i.place_id\n  WHERE pb.place_kind = 'district'\n)\nINSERT INTO alpha.place_ext (\n  tenant_id, place_id, nwea_district_id, reality\n)\nSELECT tenant_id, place_id, nwea_district_id, reality\nFROM validated_place_ext\nON CONFLICT (tenant_id, place_id) DO UPDATE\nSET nwea_district_id = EXCLUDED.nwea_district_id,\n    reality = EXCLUDED.reality;\n\nCOMMIT;",
    "sameAnswerRule": "This is valid because alpha.person_ext and alpha.place_ext are allowed extension tables, and every row is validated against the base view before insert. The migration must classify reality from authoritative source data; it must not create or populate alpha.person, alpha.place, alpha.place_membership, alpha.class_membership, or alpha.school_period as tables.",
    "itds": [
      {
        "id": "paitd-003-place-nwea-boundary",
        "title": "Place Is The Plain Alias For OneRoster Org And District Is The NWEA Account",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-003-place-nwea-boundary"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      },
      {
        "id": "paitd-011-storage-model",
        "title": "Alpha Storage Is Views Over OneRoster Plus Extension Tables",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-011-storage-model"
      },
      {
        "id": "paitd-101-write-granularity",
        "title": "API Axis: Write Granularity",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-101-write-granularity"
      }
    ]
  },
  {
    "title": "Migration: add a governed reporting tag without copying roster fields",
    "job": "Use this as the storage-gate pattern for a migration that adds a report slice over a real Alpha extension table.",
    "setup": "-- psql variables expected:\n--   :tenant_id\n-- This migration touches only allowed Alpha extension tables.\n-- It does not CREATE TABLE alpha.person or copy from oneroster.users.",
    "api": "# There is no client-side computation here. After this migration,\n# callers filter /places by level through the Alpha surface.",
    "sql": "BEGIN;\n\nINSERT INTO alpha.tag_definition (\n  tenant_id, tag_key, anchor, allowed_values, value_type, is_locked\n) VALUES (\n  :'tenant_id',\n  'level',\n  'school',\n  '[\"WL\",\"LL\",\"L1\",\"L2\",\"MS\",\"HS\"]'::jsonb,\n  'string',\n  true\n) ON CONFLICT (tenant_id, tag_key, anchor) DO UPDATE\nSET allowed_values = EXCLUDED.allowed_values,\n    value_type = EXCLUDED.value_type,\n    is_locked = EXCLUDED.is_locked;\n\nCREATE INDEX IF NOT EXISTS object_tag_tenant_key_value_idx\n  ON alpha.object_tag (tenant_id, tag_key, tag_value);\n\nCOMMIT;",
    "sameAnswerRule": "This is valid because alpha.tag_definition and alpha.object_tag are allowed extension tables, and level is a locked school-level tag using the same WL/LL/L1/L2/MS/HS glossary as alpha_level. A migration that creates alpha.person, alpha.place, or any other renamed object as a table fails PAITD-011.",
    "itds": [
      {
        "id": "paitd-006-tag-registry",
        "title": "Governed Tags Are Report Slices Only",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-006-tag-registry"
      },
      {
        "id": "paitd-011-storage-model",
        "title": "Alpha Storage Is Views Over OneRoster Plus Extension Tables",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-011-storage-model"
      }
    ]
  }
]

[
  {
    "name": "Tenant scope",
    "apiRule": "The API reads tenant_id or tenantId only from the verified bearer token.",
    "rawDbRule": "Every raw query includes tenant_id = :tenant_id on the public Alpha view and on every joined extension table. Do not read tenant ids from request headers, body fields, or display names.",
    "wrongPlausibleAnswer": "Rows from another school network appear valid because ids are only unique inside a tenant.",
    "exampleWhere": "p.tenant_id = :'tenant_id' AND cm.tenant_id = p.tenant_id",
    "itds": [
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      },
      {
        "id": "paitd-109-tenant-routing",
        "title": "API Axis: Tenant Routing",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-109-tenant-routing"
      }
    ]
  },
  {
    "name": "Join grain before de-duplication",
    "apiRule": "List endpoints choose the response grain before joining: people lists return one row per person, membership lists return one row per membership, and guide/student inverse reads return one row per guide-student-learning_group-school relationship.",
    "rawDbRule": "Every raw query states its row grain before it joins. Join membership rows on tenant_id plus the documented relationship keys: place membership uses person_id/place_id/role_kind/date window, class membership uses person_id/school_id/learning_group_id/role_kind/date window, guide inverse joins guide and student rows on tenant_id, school_id, and learning_group_id, and place account joins use parent_place_id. Use DISTINCT only after projecting the documented response grain, never to hide a missing join key or date predicate.",
    "wrongPlausibleAnswer": "A query returns duplicate students, loses a valid multi-school membership, or silently hides a cross-school join mistake because DISTINCT cleaned up rows after the wrong join.",
    "exampleWhere": "student_cm.tenant_id = guide_cm.tenant_id AND student_cm.school_id = guide_cm.school_id AND student_cm.learning_group_id = guide_cm.learning_group_id -- then SELECT DISTINCT only at the documented response grain",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-102-read-shape",
        "title": "API Axis: Read Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-102-read-shape"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "Real student, not every person",
    "apiRule": "Student list endpoints use dated role membership plus reality=real by default, not a person table shortcut.",
    "rawDbRule": "A real student answer joins alpha.person to alpha.place_membership or alpha.class_membership with p.reality='real', role_kind='student', is_time_locatable=true, begin_date <= :asOfDate, and end_date null or after :asOfDate. If a school/place is in the query, the joined place must also have reality='real'.",
    "wrongPlausibleAnswer": "Parents, guides, inactive students, test users, synthetic rows, or undated rows enter a student report because the query filtered person.grade_levels or a name string instead of membership and reality.",
    "exampleWhere": "p.reality = 'real' AND school.reality = 'real' AND cm.role_kind = 'student' AND cm.is_time_locatable IS TRUE AND cm.begin_date <= :'as_of_date'::date AND (cm.end_date IS NULL OR :'as_of_date'::date < cm.end_date)",
    "itds": [
      {
        "id": "paitd-017-reality-flag",
        "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
      },
      {
        "id": "paitd-002-person-vocabulary",
        "title": "Person Is The Plain Alias For OneRoster User",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-002-person-vocabulary"
      },
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "name": "Reality filter",
    "apiRule": "Ordinary report endpoints default to reality=real for both person and place. Including test or synthetic data is explicit and scope-gated.",
    "rawDbRule": "Every ordinary raw report query over alpha.person or alpha.place includes reality = 'real' on each joined person/place role. Do not infer reality from names, campus labels, email domains, tenant names, or local exclude-lists.",
    "wrongPlausibleAnswer": "A test campus or AI-agent test user has valid memberships and therefore appears in production reports.",
    "exampleWhere": "p.reality = 'real' AND school.reality = 'real'",
    "itds": [
      {
        "id": "paitd-017-reality-flag",
        "title": "Reality Is A Typed Closed Flag On Person And Place, Set At Write Time",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-017-reality-flag"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      },
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "name": "Point-in-time belonging rows",
    "apiRule": "Active membership, staff-assignment, program-participation, alpha-level, and age-grade routes require asOfDate and never offer a currentOnly shortcut.",
    "rawDbRule": "For alpha.place_membership, alpha.class_membership, alpha.staff_assignment_view, alpha.program_participation_view, alpha.alpha_level_history, and alpha.age_grade_history: begin_date null means excluded from every point-in-time computation. end_date null means still active for asOfDate on or after begin_date. Both null means excluded.",
    "wrongPlausibleAnswer": "A membership, staff assignment, program participation, alpha-level row, or age-grade row with no begin date looks active forever, or an ended row remains active after its end date.",
    "exampleWhere": "m.is_time_locatable IS TRUE AND m.begin_date <= :'as_of_date'::date AND (m.end_date IS NULL OR :'as_of_date'::date < m.end_date)",
    "itds": [
      {
        "id": "paitd-018-over-time-history",
        "title": "Alpha Level And Age Grade Keep Effective-Dated History, Read By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-018-over-time-history"
      },
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-014-staff-assignment-views",
        "title": "Staff Assignments Come From Ed-Fi Assignment Views Beyond OneRoster Roles",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-014-staff-assignment-views"
      },
      {
        "id": "paitd-015-program-participation-views",
        "title": "Program Participation Is A People & Orgs Belonging View, Not Results Or Policy",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-015-program-participation-views"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "Enrollment anchor and guide inverse",
    "apiRule": "firstEnrolledCourseGrade(student, subject), firstSingleGradeEnrollmentDate(student, subject), and studentsForGuide(guide, date) are first-class reads so consumers do not reconstruct them in app code.",
    "rawDbRule": "The enrollment-anchor raw paths use the surface-owned function/query for Curriculum subject, course_grade_mode, course_grade_levels, and single-grade context plus alpha.class_membership begin/end windows. The guide inverse raw path joins guide and student class_membership rows on tenant_id, school_id, and learning_group_id with the same asOfDate and reality=real filters.",
    "wrongPlausibleAnswer": "A report chooses the wrong school-year start date by parsing class names, treating multi-grade groups as single-grade, or doing an undocumented two-hop for guide rosters.",
    "exampleWhere": "guide_cm.role_kind = 'guide' AND student_cm.role_kind = 'student' AND guide_cm.learning_group_id = student_cm.learning_group_id AND student.reality = 'real'",
    "itds": [
      {
        "id": "paitd-004-point-in-time-memberships",
        "title": "Memberships Are Effective-Dated And Answered By AsOfDate",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-004-point-in-time-memberships"
      },
      {
        "id": "paitd-102-read-shape",
        "title": "API Axis: Read Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-102-read-shape"
      },
      {
        "id": "paitd-103-query-model",
        "title": "API Axis: Query Model",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-103-query-model"
      }
    ]
  },
  {
    "name": "Soft-delete, logical-delete, and tombstone hygiene",
    "apiRule": "Ordinary roster reads hide source_status = 'tobedeleted' and Ed-Fi is_deleted=true rows unless the caller requests an authorized audit or retention workflow.",
    "rawDbRule": "Ordinary raw roster queries add COALESCE(source_status, 'active') <> 'tobedeleted' for OneRoster-backed views and is_deleted=false for Ed-Fi-backed views. Historical audit queries may include tombstones or soft-deleted rows only when the job explicitly asks for retained delete history.",
    "wrongPlausibleAnswer": "A soft-deleted contact, deleted person, or retired place remains in a live roster because the raw query ignored the source lifecycle marker instead of matching the API hygiene filter.",
    "exampleWhere": "COALESCE(p.source_status, 'active') <> 'tobedeleted'",
    "itds": [
      {
        "id": "paitd-111-privacy-retention",
        "title": "API Axis: Privacy / Retention",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-111-privacy-retention"
      }
    ]
  },
  {
    "name": "Sensitive profile scope",
    "apiRule": "Ordinary person and place lists do not include birth date, race or ethnicity, birth location, residence status, vendor profile usernames, or credential details.",
    "rawDbRule": "Do not join alpha.person_sensitive_profile or alpha.app_credential in ordinary roster queries. Query those objects only for a job that has explicit sensitive-profile or credential-status scope and relationship evidence.",
    "wrongPlausibleAnswer": "A raw query returns sensitive PII that the public API would correctly redact.",
    "exampleWhere": "Use alpha.person_sensitive_profile only in a privileged query path; ordinary alpha.person queries must not join it.",
    "itds": [
      {
        "id": "paitd-008-app-credentials",
        "title": "App Credentials Use Vault References, Never Roster Password Fields",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-008-app-credentials"
      },
      {
        "id": "paitd-009-sensitive-profile-privacy",
        "title": "Sensitive Profiles Are Restricted, Not Default Roster Fields",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-009-sensitive-profile-privacy"
      },
      {
        "id": "paitd-106-auth-shape",
        "title": "API Axis: Auth Shape",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-106-auth-shape"
      }
    ]
  },
  {
    "name": "NWEA account grain",
    "apiRule": "For MAP reporting, a district place row is exactly one Brand x Modality NWEA account; a school reads its account through parent_place_id.",
    "rawDbRule": "Find a school's NWEA account by joining the school place to its parent district place, then read the parent's nwea_district_id plus locked brand and modality tags. Segment is a closed report slice on the place, with mixed reserved for multi-segment district rows. Never store or query a second school-level nwea_district_id.",
    "wrongPlausibleAnswer": "Physical and virtual schools combine in one NWEA account report because the raw query grouped by school name or a school-level tag.",
    "exampleWhere": "school.parent_place_id = district.place_id AND district.place_kind = 'district' AND district.nwea_district_id IS NOT NULL",
    "itds": [
      {
        "id": "paitd-003-place-nwea-boundary",
        "title": "Place Is The Plain Alias For OneRoster Org And District Is The NWEA Account",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-003-place-nwea-boundary"
      },
      {
        "id": "paitd-006-tag-registry",
        "title": "Governed Tags Are Report Slices Only",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-006-tag-registry"
      }
    ]
  },
  {
    "name": "Closed reporting enums",
    "apiRule": "Writes canonicalize alpha_level, grade_level, brand, segment, modality, and level aliases at the boundary and reject unreconciled live values instead of passing free text through.",
    "rawDbRule": "Raw migrations seed alpha.tag_definition and extension fields with only the closed values published in the enum catalog. The school level tag is locked to WL, LL, L1, L2, MS, and HS. Alias folds such as PK->-1, K->0, L3->MS, L4.*->HS, Physical->physical, and GT School->gt are write-time normalization rules, not read-time parsing recipes.",
    "wrongPlausibleAnswer": "A report silently splits Alpha School/alpha, GT School/gt, PK/-1, or L4.1/HS into separate cohorts because the consumer grouped on raw source labels.",
    "exampleWhere": "brand IN ('100for100','alpha','gt','limitless_education','montessorium','nextgen','nova_academy','novatio','sw_sales','texas_sports_academy','towermath','unbound','waypoint') AND modality IN ('physical','virtual') AND level IN ('WL','LL','L1','L2','MS','HS')",
    "itds": [
      {
        "id": "paitd-003-place-nwea-boundary",
        "title": "Place Is The Plain Alias For OneRoster Org And District Is The NWEA Account",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-003-place-nwea-boundary"
      },
      {
        "id": "paitd-006-tag-registry",
        "title": "Governed Tags Are Report Slices Only",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-006-tag-registry"
      },
      {
        "id": "paitd-007-tenure-and-grade-context",
        "title": "Tenure And Grade Context Are Typed Inputs, Not Dashboard Math",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-007-tenure-and-grade-context"
      }
    ]
  },
  {
    "name": "Ed-Fi canonical view guardrail",
    "apiRule": "Guardian, guardian_relationship, staff_assignment, and program_participation endpoints read only canonical Ed-Fi records for the documented resource family, hide is_deleted=true rows by default, exclude drafts, resolve descriptors through edfi.descriptor_code, and join person/place ids through OneRoster sourcedId boundaries.",
    "rawDbRule": "Raw queries must use the documented alpha.*_view objects, or if auditing the underlying Ed-Fi tables directly, filter tenant_id, resource_name/collection_route, canonical state, is_deleted=false for ordinary reads, join descriptor fields through edfi.descriptor_code, and join student/staff/place references to OneRoster sourcedIds.",
    "wrongPlausibleAnswer": "A raw report includes deleted contacts, draft program rows, unresolved descriptor ids, or cross-system student ids that the API would correctly hide or resolve.",
    "exampleWhere": "FROM alpha.guardian_relationship_view gr JOIN alpha.guardian_view g ON g.tenant_id = gr.tenant_id AND g.guardian_id = gr.guardian_id WHERE gr.tenant_id = :'tenant_id' AND COALESCE(g.is_deleted, false) IS FALSE",
    "itds": [
      {
        "id": "paitd-012-edfi-second-upstream",
        "title": "Ed-Fi Administrative Records Are A Second View-Only Upstream",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-012-edfi-second-upstream"
      },
      {
        "id": "paitd-013-guardian-views",
        "title": "Guardians Come From Ed-Fi Contact And StudentContactAssociation Views",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-013-guardian-views"
      },
      {
        "id": "paitd-014-staff-assignment-views",
        "title": "Staff Assignments Come From Ed-Fi Assignment Views Beyond OneRoster Roles",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-014-staff-assignment-views"
      },
      {
        "id": "paitd-015-program-participation-views",
        "title": "Program Participation Is A People & Orgs Belonging View, Not Results Or Policy",
        "href": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#paitd-015-program-participation-views"
      }
    ]
  }
]

[
  {
    "term": "Alpha",
    "expansion": "The plain-language TimeBack surface for students, parents, teachers, and app-builder LLMs.",
    "use": "Use Alpha names such as person, place, and school_period instead of OneRoster jargon in this data dictionary."
  },
  {
    "term": "API",
    "expansion": "Application programming interface.",
    "use": "The HTTP surface that validates auth, filters, pagination, and writes."
  },
  {
    "term": "DB",
    "expansion": "Database.",
    "use": "The raw SQL path over documented Alpha views and extension tables."
  },
  {
    "term": "Ed-Fi",
    "expansion": "A standards-backed administrative student information model.",
    "use": "People & Orgs uses Ed-Fi only for guardian, staff-assignment, and program-participation who/where facts."
  },
  {
    "term": "ETag",
    "expansion": "HTTP entity tag.",
    "use": "The version validator returned on mutable reads and supplied through If-Match on updates."
  },
  {
    "term": "GDPR",
    "expansion": "General Data Protection Regulation style privacy and erasure handling.",
    "use": "The privacy model for redaction, audit, tombstones, and erasure."
  },
  {
    "term": "ITD",
    "expansion": "Important Technical Decision.",
    "use": "A pinned architecture decision that every dictionary field and rule traces to."
  },
  {
    "term": "JWT",
    "expansion": "JSON Web Token.",
    "use": "The signed bearer token that supplies tenant and relationship-scoped claims."
  },
  {
    "term": "LLM",
    "expansion": "Large language model.",
    "use": "An AI agent building apps or reports from these docs."
  },
  {
    "term": "MAP",
    "expansion": "Measures of Academic Progress.",
    "use": "NWEA MAP Growth test results live in Results/NWEAMap; People & Orgs supplies the student and place context."
  },
  {
    "term": "NWEA",
    "expansion": "Northwest Evaluation Association.",
    "use": "The organization behind MAP Growth; in this roster surface it appears only as the district account boundary."
  },
  {
    "term": "PII",
    "expansion": "Personally identifiable information.",
    "use": "Data that can identify or contact a person and must follow privacy scopes."
  },
  {
    "term": "SQL",
    "expansion": "Structured Query Language.",
    "use": "The raw database query language used by the first-class raw-DB path."
  },
  {
    "term": "UUID",
    "expansion": "Universally unique identifier.",
    "use": "The tenant key format inherited from platform.tenant."
  }
]

[
  {
    "table": "alpha.canonical_enums",
    "field": "reality",
    "anchor": "enum-alpha-canonical-enums-reality",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "real",
        "meaning": "A production student, person, school, district, or roster place that belongs in ordinary customer reports.",
        "useWhen": "Use for real TimeBack people and places after the write boundary has verified the source classification.",
        "invalidWhen": "Invalid for QA accounts, AI-agent test rows, generated fixtures, or demo-only entities."
      },
      {
        "value": "test",
        "meaning": "A QA, staff-test, integration-test, or AI-agent test entity that must be excluded from ordinary reports.",
        "useWhen": "Use for entities intentionally created to test the surface or another app.",
        "invalidWhen": "Invalid for production students or schools even if their display name looks unusual."
      },
      {
        "value": "synthetic",
        "meaning": "Generated, seeded, anonymized, or fixture data that is useful for demos or development but not a real customer row.",
        "useWhen": "Use for generated seed rows, local fixtures, and anonymized examples.",
        "invalidWhen": "Invalid for a row imported from the authoritative SIS or TimeBack production source as a real entity."
      }
    ],
    "sourceEvidence": {
      "sourceTables": [
        "SIS school/person classification",
        "TimeBack production test/demo markers"
      ],
      "note": "Wave 2 decision: reality is set at the write boundary from authoritative source classification. Consumers never infer it from person names, campus names, email domains, or hand-maintained exclusion lists.",
      "values": [
        "real",
        "test",
        "synthetic"
      ]
    }
  },
  {
    "table": "alpha.canonical_enums",
    "field": "alpha_level",
    "anchor": "enum-alpha-canonical-enums-alpha-level",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "WL",
        "meaning": "WonderLab, the pre-K Alpha level. Live source alias validated 2026-06-09: PKBY folds here.",
        "useWhen": "Use for the pre-K Alpha level, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for kindergarten, LearningLab, or any grade-level placement."
      },
      {
        "value": "LL",
        "meaning": "LearningLab, the K-1 Alpha level. Live source alias validated 2026-06-09: Linc folds here.",
        "useWhen": "Use for K-1 Alpha-level grouping, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for WonderLab or numbered upper levels."
      },
      {
        "value": "L1",
        "meaning": "Level 1, the grade 2-3 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 2 through grade 3.",
        "invalidWhen": "Invalid for grade 4+ cohorts or for MAP working-grade state."
      },
      {
        "value": "L2",
        "meaning": "Level 2, the grade 4-5 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 4 through grade 5.",
        "invalidWhen": "Invalid for grade 2-3, middle school, high school, or Results working-grade state."
      },
      {
        "value": "MS",
        "meaning": "Middle School, the grade 6-8 Alpha level. Live source aliases validated 2026-06-09: Middle School and L3 fold here.",
        "useWhen": "Use for middle-school Alpha-level grouping.",
        "invalidWhen": "Invalid for high school or elementary level rows."
      },
      {
        "value": "HS",
        "meaning": "High School, the grade 9-12 Alpha level. Live source aliases validated 2026-06-09: High School, L4.1, L4.2, and L4.3 fold here.",
        "useWhen": "Use for high-school Alpha-level grouping.",
        "invalidWhen": "Invalid for middle-school or elementary level rows."
      }
    ],
    "sourceEvidence": {
      "sourceTable": "public.users_visibility.user_alpha_level",
      "observedAliases": {
        "WL": [
          "WL",
          "PKBY"
        ],
        "LL": [
          "LL",
          "Linc"
        ],
        "L1": [
          "L1"
        ],
        "L2": [
          "L2"
        ],
        "MS": [
          "MS",
          "Middle School",
          "L3"
        ],
        "HS": [
          "HS",
          "High School",
          "L4.1",
          "L4.2",
          "L4.3"
        ]
      },
      "nullCount": 24577,
      "uncoveredValues": []
    }
  },
  {
    "table": "alpha.canonical_enums",
    "field": "grade_level",
    "anchor": "enum-alpha-canonical-enums-grade-level",
    "type": "INTEGER closed enum",
    "values": [
      {
        "value": "-1",
        "meaning": "PreK. Live source aliases validated 2026-06-09: -1 and PK fold here.",
        "useWhen": "Use for pre-kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for kindergarten or any student grade 1 through 12."
      },
      {
        "value": "0",
        "meaning": "Kindergarten. Live source aliases validated 2026-06-09: 0 and K fold here.",
        "useWhen": "Use for kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for PreK or any numbered grade."
      },
      {
        "value": "1",
        "meaning": "Grade 1.",
        "useWhen": "Use for grade 1 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "2",
        "meaning": "Grade 2.",
        "useWhen": "Use for grade 2 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "3",
        "meaning": "Grade 3.",
        "useWhen": "Use for grade 3 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "4",
        "meaning": "Grade 4. Live source aliases validated 2026-06-09: 4, 4TH_GRADE, and Grade_4 fold here.",
        "useWhen": "Use for grade 4 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "5",
        "meaning": "Grade 5.",
        "useWhen": "Use for grade 5 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "6",
        "meaning": "Grade 6.",
        "useWhen": "Use for grade 6 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "7",
        "meaning": "Grade 7.",
        "useWhen": "Use for grade 7 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "8",
        "meaning": "Grade 8.",
        "useWhen": "Use for grade 8 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "9",
        "meaning": "Grade 9.",
        "useWhen": "Use for grade 9 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "10",
        "meaning": "Grade 10.",
        "useWhen": "Use for grade 10 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "11",
        "meaning": "Grade 11.",
        "useWhen": "Use for grade 11 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "12",
        "meaning": "Grade 12.",
        "useWhen": "Use for grade 12 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      }
    ],
    "sourceEvidence": {
      "sourceTable": "public.users.grades",
      "observedAliases": {
        "0": [
          "0",
          "K"
        ],
        "4": [
          "4",
          "4TH_GRADE",
          "Grade_4"
        ],
        "-1": [
          "-1",
          "PK"
        ]
      },
      "uncoveredValues": [
        {
          "value": "13",
          "count": 112,
          "action": "Reject or reconcile at the write boundary; do not publish as canonical K-12 grade_level."
        }
      ]
    }
  },
  {
    "table": "alpha.canonical_enums",
    "field": "brand",
    "anchor": "enum-alpha-canonical-enums-brand",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "100for100",
        "meaning": "100for100 brand. Live active org validation found this brand in the campus taxonomy intersected with production org rows.",
        "useWhen": "Use for NWEA-account district and school rows whose typed brand is 100for100.",
        "invalidWhen": "Invalid as a fallback for Alpha, GT, Texas Sports Academy, or partner brands."
      },
      {
        "value": "alpha",
        "meaning": "Alpha School brand. Live source aliases include Alpha, Alpha School, Alpha Anywhere, Alpha School campus names, and 2 Hour Learning legacy names.",
        "useWhen": "Use for Alpha School physical and virtual NWEA-account rows.",
        "invalidWhen": "Invalid for GT School, Texas Sports Academy, or non-Alpha partner schools."
      },
      {
        "value": "gt",
        "meaning": "GT School brand. Live aliases include GT School and GT Anywhere.",
        "useWhen": "Use for GT physical or virtual NWEA-account rows.",
        "invalidWhen": "Invalid for Alpha or partner school rows."
      },
      {
        "value": "limitless_education",
        "meaning": "Limitless Education brand observed in live active org rows.",
        "useWhen": "Use for schools whose typed brand is Limitless Education.",
        "invalidWhen": "Invalid for generic partner rows without that brand assignment."
      },
      {
        "value": "montessorium",
        "meaning": "Montessorium brand observed in live active org rows.",
        "useWhen": "Use for Montessorium school rows.",
        "invalidWhen": "Invalid for Alpha, GT, or Texas Sports Academy rows."
      },
      {
        "value": "nextgen",
        "meaning": "NextGen brand observed in live active org rows.",
        "useWhen": "Use for NextGen Academy or NextGen tutoring rows.",
        "invalidWhen": "Invalid for unrelated partner schools."
      },
      {
        "value": "nova_academy",
        "meaning": "Nova Academy brand observed in live active org rows.",
        "useWhen": "Use for Nova Academy campuses.",
        "invalidWhen": "Invalid for Novatio; that is a separate brand value."
      },
      {
        "value": "novatio",
        "meaning": "Novatio brand observed in live active org rows.",
        "useWhen": "Use for Novatio rows.",
        "invalidWhen": "Invalid for Nova Academy rows."
      },
      {
        "value": "sw_sales",
        "meaning": "SW Sales segment/brand value observed across Allendale and similar live active org rows.",
        "useWhen": "Use when the production taxonomy classifies the school as SW Sales.",
        "invalidWhen": "Invalid for Alpha-owned campuses or Texas Sports Academy rows."
      },
      {
        "value": "texas_sports_academy",
        "meaning": "Texas Sports Academy brand. Live aliases include Texas Sports Academy, TSA, TSA Online, and TSA sport/prep campus names.",
        "useWhen": "Use for Texas Sports Academy physical and virtual accounts.",
        "invalidWhen": "Invalid for Alpha, GT, or non-TSA partner rows."
      },
      {
        "value": "towermath",
        "meaning": "TowerMath brand observed in live active org rows.",
        "useWhen": "Use for TowerMath rows.",
        "invalidWhen": "Invalid for Alpha math products unless the typed brand is TowerMath."
      },
      {
        "value": "unbound",
        "meaning": "Unbound brand observed in live active org rows.",
        "useWhen": "Use for Unbound Academy rows.",
        "invalidWhen": "Invalid for other partner schools."
      },
      {
        "value": "waypoint",
        "meaning": "Waypoint brand observed in live active org rows.",
        "useWhen": "Use for Waypoint Academy rows.",
        "invalidWhen": "Invalid for other partner schools."
      }
    ],
    "sourceEvidence": {
      "sourceTable": "public.orgs",
      "activeOrgRows": 162,
      "taxonomyMatchedRows": 118,
      "taxonomyUnmatchedRows": 44,
      "brandValues": [
        "100for100",
        "alpha",
        "gt",
        "limitless_education",
        "montessorium",
        "nextgen",
        "nova_academy",
        "novatio",
        "sw_sales",
        "texas_sports_academy",
        "towermath",
        "unbound",
        "waypoint"
      ],
      "segmentValues": [
        "charter",
        "private",
        "sw_sales",
        "virtual",
        "mixed"
      ],
      "modalityValues": [
        "physical",
        "virtual"
      ],
      "note": "Production orgs do not yet store typed brand/segment columns. The closed lists were validated by intersecting live active org rows with the existing TimeBack campus taxonomy, then freezing write-boundary canonical values. Unmatched active orgs require reconciliation; they do not create an unknown enum value."
    }
  },
  {
    "table": "alpha.canonical_enums",
    "field": "segment",
    "anchor": "enum-alpha-canonical-enums-segment",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "charter",
        "meaning": "Charter-school segment observed in live active org rows.",
        "useWhen": "Use for schools whose typed segment is charter.",
        "invalidWhen": "Invalid for private, virtual, or SW Sales rows."
      },
      {
        "value": "private",
        "meaning": "Private-school segment observed in live active org rows.",
        "useWhen": "Use for private school campuses and district accounts.",
        "invalidWhen": "Invalid for virtual-only, charter, or SW Sales rows."
      },
      {
        "value": "sw_sales",
        "meaning": "SW Sales segment observed in live active org rows.",
        "useWhen": "Use for schools typed into the SW Sales segment.",
        "invalidWhen": "Invalid for Alpha private/virtual rows unless the write boundary explicitly assigns SW Sales."
      },
      {
        "value": "virtual",
        "meaning": "Virtual segment observed in live active org rows.",
        "useWhen": "Use for schools or accounts whose segment is virtual.",
        "invalidWhen": "Invalid for physical private or charter segment rows; modality still remains physical or virtual separately."
      },
      {
        "value": "mixed",
        "meaning": "District/account rollup reserved for a district spanning multiple segments.",
        "useWhen": "Use only on a district/account row that intentionally spans more than one segment.",
        "invalidWhen": "Invalid on an ordinary school row or as a substitute for unknown."
      }
    ],
    "sourceEvidence": {
      "sourceTable": "public.orgs",
      "activeOrgRows": 162,
      "taxonomyMatchedRows": 118,
      "taxonomyUnmatchedRows": 44,
      "brandValues": [
        "100for100",
        "alpha",
        "gt",
        "limitless_education",
        "montessorium",
        "nextgen",
        "nova_academy",
        "novatio",
        "sw_sales",
        "texas_sports_academy",
        "towermath",
        "unbound",
        "waypoint"
      ],
      "segmentValues": [
        "charter",
        "private",
        "sw_sales",
        "virtual",
        "mixed"
      ],
      "modalityValues": [
        "physical",
        "virtual"
      ],
      "note": "Production orgs do not yet store typed brand/segment columns. The closed lists were validated by intersecting live active org rows with the existing TimeBack campus taxonomy, then freezing write-boundary canonical values. Unmatched active orgs require reconciliation; they do not create an unknown enum value."
    }
  },
  {
    "table": "alpha.canonical_enums",
    "field": "modality",
    "anchor": "enum-alpha-canonical-enums-modality",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "physical",
        "meaning": "The NWEA account is for the physical-school modality of a brand. Live source aliases validated 2026-06-09: Physical folds here.",
        "useWhen": "Use for the district or school place row representing the physical NWEA account or child school.",
        "invalidWhen": "Invalid for virtual accounts or for a mixed/hybrid account."
      },
      {
        "value": "virtual",
        "meaning": "The NWEA account is for the virtual-school modality of a brand. Live source aliases validated 2026-06-09: Virtual folds here.",
        "useWhen": "Use for the district or school place row representing the virtual NWEA account or child school.",
        "invalidWhen": "Invalid for physical accounts or for a mixed/hybrid account."
      }
    ],
    "sourceEvidence": {
      "sourceTable": "public.orgs",
      "activeOrgRows": 162,
      "taxonomyMatchedRows": 118,
      "taxonomyUnmatchedRows": 44,
      "brandValues": [
        "100for100",
        "alpha",
        "gt",
        "limitless_education",
        "montessorium",
        "nextgen",
        "nova_academy",
        "novatio",
        "sw_sales",
        "texas_sports_academy",
        "towermath",
        "unbound",
        "waypoint"
      ],
      "segmentValues": [
        "charter",
        "private",
        "sw_sales",
        "virtual",
        "mixed"
      ],
      "modalityValues": [
        "physical",
        "virtual"
      ],
      "note": "Production orgs do not yet store typed brand/segment columns. The closed lists were validated by intersecting live active org rows with the existing TimeBack campus taxonomy, then freezing write-boundary canonical values. Unmatched active orgs require reconciliation; they do not create an unknown enum value."
    }
  },
  {
    "table": "alpha.canonical_enums",
    "field": "level",
    "anchor": "enum-alpha-canonical-enums-level",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "WL",
        "meaning": "WonderLab, the pre-K Alpha level. Live source alias validated 2026-06-09: PKBY folds here.",
        "useWhen": "Use for the pre-K Alpha level, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for kindergarten, LearningLab, or any grade-level placement."
      },
      {
        "value": "LL",
        "meaning": "LearningLab, the K-1 Alpha level. Live source alias validated 2026-06-09: Linc folds here.",
        "useWhen": "Use for K-1 Alpha-level grouping, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for WonderLab or numbered upper levels."
      },
      {
        "value": "L1",
        "meaning": "Level 1, the grade 2-3 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 2 through grade 3.",
        "invalidWhen": "Invalid for grade 4+ cohorts or for MAP working-grade state."
      },
      {
        "value": "L2",
        "meaning": "Level 2, the grade 4-5 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 4 through grade 5.",
        "invalidWhen": "Invalid for grade 2-3, middle school, high school, or Results working-grade state."
      },
      {
        "value": "MS",
        "meaning": "Middle School, the grade 6-8 Alpha level. Live source aliases validated 2026-06-09: Middle School and L3 fold here.",
        "useWhen": "Use for middle-school Alpha-level grouping.",
        "invalidWhen": "Invalid for high school or elementary level rows."
      },
      {
        "value": "HS",
        "meaning": "High School, the grade 9-12 Alpha level. Live source aliases validated 2026-06-09: High School, L4.1, L4.2, and L4.3 fold here.",
        "useWhen": "Use for high-school Alpha-level grouping.",
        "invalidWhen": "Invalid for middle-school or elementary level rows."
      }
    ],
    "sourceEvidence": {
      "sourceTable": "public.users_visibility.user_alpha_level",
      "observedAliases": {
        "WL": [
          "WL",
          "PKBY"
        ],
        "LL": [
          "LL",
          "Linc"
        ],
        "L1": [
          "L1"
        ],
        "L2": [
          "L2"
        ],
        "MS": [
          "MS",
          "Middle School",
          "L3"
        ],
        "HS": [
          "HS",
          "High School",
          "L4.1",
          "L4.2",
          "L4.3"
        ]
      },
      "nullCount": 24577,
      "uncoveredValues": []
    }
  },
  {
    "table": "alpha.person",
    "field": "source_status",
    "anchor": "field-alpha-person-source-status",
    "type": "TEXT enum",
    "values": [
      {
        "value": "active",
        "meaning": "The delta row is current and should be inserted or updated.",
        "useWhen": "Use only in delta row status fields. Alpha keeps this only as source provenance; ordinary active-as-of queries still use dated memberships.",
        "invalidWhen": "Invalid in bulk rows or when the row should be deleted."
      },
      {
        "value": "tobedeleted",
        "meaning": "The delta row indicates the source wants this object deleted or retired.",
        "useWhen": "Use only in delta row status fields. Alpha keeps this only as source provenance; ordinary active-as-of queries still use dated memberships.",
        "invalidWhen": "Invalid in bulk rows or when the source object remains active."
      }
    ]
  },
  {
    "table": "alpha.person",
    "field": "reality",
    "anchor": "field-alpha-person-reality",
    "type": "TEXT enum",
    "values": [
      {
        "value": "real",
        "meaning": "A production student, person, school, district, or roster place that belongs in ordinary customer reports.",
        "useWhen": "Use for real TimeBack people and places after the write boundary has verified the source classification.",
        "invalidWhen": "Invalid for QA accounts, AI-agent test rows, generated fixtures, or demo-only entities."
      },
      {
        "value": "test",
        "meaning": "A QA, staff-test, integration-test, or AI-agent test entity that must be excluded from ordinary reports.",
        "useWhen": "Use for entities intentionally created to test the surface or another app.",
        "invalidWhen": "Invalid for production students or schools even if their display name looks unusual."
      },
      {
        "value": "synthetic",
        "meaning": "Generated, seeded, anonymized, or fixture data that is useful for demos or development but not a real customer row.",
        "useWhen": "Use for generated seed rows, local fixtures, and anonymized examples.",
        "invalidWhen": "Invalid for a row imported from the authoritative SIS or TimeBack production source as a real entity."
      }
    ]
  },
  {
    "table": "alpha.person",
    "field": "is_enabled",
    "anchor": "field-alpha-person-is-enabled",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.person",
    "field": "grade_levels",
    "anchor": "field-alpha-person-grade-levels",
    "type": "INTEGER[] closed enum",
    "values": [
      {
        "value": "-1",
        "meaning": "PreK. Live source aliases validated 2026-06-09: -1 and PK fold here.",
        "useWhen": "Use for pre-kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for kindergarten or any student grade 1 through 12."
      },
      {
        "value": "0",
        "meaning": "Kindergarten. Live source aliases validated 2026-06-09: 0 and K fold here.",
        "useWhen": "Use for kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for PreK or any numbered grade."
      },
      {
        "value": "1",
        "meaning": "Grade 1.",
        "useWhen": "Use for grade 1 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "2",
        "meaning": "Grade 2.",
        "useWhen": "Use for grade 2 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "3",
        "meaning": "Grade 3.",
        "useWhen": "Use for grade 3 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "4",
        "meaning": "Grade 4. Live source aliases validated 2026-06-09: 4, 4TH_GRADE, and Grade_4 fold here.",
        "useWhen": "Use for grade 4 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "5",
        "meaning": "Grade 5.",
        "useWhen": "Use for grade 5 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "6",
        "meaning": "Grade 6.",
        "useWhen": "Use for grade 6 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "7",
        "meaning": "Grade 7.",
        "useWhen": "Use for grade 7 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "8",
        "meaning": "Grade 8.",
        "useWhen": "Use for grade 8 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "9",
        "meaning": "Grade 9.",
        "useWhen": "Use for grade 9 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "10",
        "meaning": "Grade 10.",
        "useWhen": "Use for grade 10 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "11",
        "meaning": "Grade 11.",
        "useWhen": "Use for grade 11 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "12",
        "meaning": "Grade 12.",
        "useWhen": "Use for grade 12 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      }
    ]
  },
  {
    "table": "alpha.person",
    "field": "age_grade",
    "anchor": "field-alpha-person-age-grade",
    "type": "INTEGER closed enum",
    "values": [
      {
        "value": "-1",
        "meaning": "PreK. Live source aliases validated 2026-06-09: -1 and PK fold here.",
        "useWhen": "Use for pre-kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for kindergarten or any student grade 1 through 12."
      },
      {
        "value": "0",
        "meaning": "Kindergarten. Live source aliases validated 2026-06-09: 0 and K fold here.",
        "useWhen": "Use for kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for PreK or any numbered grade."
      },
      {
        "value": "1",
        "meaning": "Grade 1.",
        "useWhen": "Use for grade 1 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "2",
        "meaning": "Grade 2.",
        "useWhen": "Use for grade 2 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "3",
        "meaning": "Grade 3.",
        "useWhen": "Use for grade 3 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "4",
        "meaning": "Grade 4. Live source aliases validated 2026-06-09: 4, 4TH_GRADE, and Grade_4 fold here.",
        "useWhen": "Use for grade 4 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "5",
        "meaning": "Grade 5.",
        "useWhen": "Use for grade 5 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "6",
        "meaning": "Grade 6.",
        "useWhen": "Use for grade 6 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "7",
        "meaning": "Grade 7.",
        "useWhen": "Use for grade 7 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "8",
        "meaning": "Grade 8.",
        "useWhen": "Use for grade 8 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "9",
        "meaning": "Grade 9.",
        "useWhen": "Use for grade 9 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "10",
        "meaning": "Grade 10.",
        "useWhen": "Use for grade 10 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "11",
        "meaning": "Grade 11.",
        "useWhen": "Use for grade 11 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "12",
        "meaning": "Grade 12.",
        "useWhen": "Use for grade 12 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "source_status",
    "anchor": "field-alpha-place-source-status",
    "type": "TEXT enum",
    "values": [
      {
        "value": "active",
        "meaning": "The delta row is current and should be inserted or updated.",
        "useWhen": "Use only in delta row status fields. Alpha keeps this only as source provenance; ordinary active-as-of queries still use dated memberships.",
        "invalidWhen": "Invalid in bulk rows or when the row should be deleted."
      },
      {
        "value": "tobedeleted",
        "meaning": "The delta row indicates the source wants this object deleted or retired.",
        "useWhen": "Use only in delta row status fields. Alpha keeps this only as source provenance; ordinary active-as-of queries still use dated memberships.",
        "invalidWhen": "Invalid in bulk rows or when the source object remains active."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "reality",
    "anchor": "field-alpha-place-reality",
    "type": "TEXT enum",
    "values": [
      {
        "value": "real",
        "meaning": "A production student, person, school, district, or roster place that belongs in ordinary customer reports.",
        "useWhen": "Use for real TimeBack people and places after the write boundary has verified the source classification.",
        "invalidWhen": "Invalid for QA accounts, AI-agent test rows, generated fixtures, or demo-only entities."
      },
      {
        "value": "test",
        "meaning": "A QA, staff-test, integration-test, or AI-agent test entity that must be excluded from ordinary reports.",
        "useWhen": "Use for entities intentionally created to test the surface or another app.",
        "invalidWhen": "Invalid for production students or schools even if their display name looks unusual."
      },
      {
        "value": "synthetic",
        "meaning": "Generated, seeded, anonymized, or fixture data that is useful for demos or development but not a real customer row.",
        "useWhen": "Use for generated seed rows, local fixtures, and anonymized examples.",
        "invalidWhen": "Invalid for a row imported from the authoritative SIS or TimeBack production source as a real entity."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "place_kind",
    "anchor": "field-alpha-place-place-kind",
    "type": "TEXT enum",
    "values": [
      {
        "value": "department",
        "meaning": "Department-level organization, usually below a school or district.",
        "useWhen": "Use for academic/administrative departments that can own courses or roles but should not satisfy school_sourced_id references.",
        "invalidWhen": "Invalid as the target of classes.school_sourced_id or enrollments.school_sourced_id."
      },
      {
        "value": "school",
        "meaning": "School/building organization and the required org type for school-scoped class, enrollment, and line-item references.",
        "useWhen": "Use when a row can be referenced by classes.school_sourced_id, enrollments.school_sourced_id, or line_items.school_sourced_id.",
        "invalidWhen": "Invalid for district or department rows that should only be hierarchy parents."
      },
      {
        "value": "district",
        "meaning": "District organization that commonly parents school rows.",
        "useWhen": "Use as parent_sourced_id for schools or for district-level roles/courses where the source sends them.",
        "invalidWhen": "Invalid as a class/enrollment school_sourced_id target."
      },
      {
        "value": "local",
        "meaning": "Local education authority or local-level organization.",
        "useWhen": "Use when the source models an LEA/local authority distinct from a district.",
        "invalidWhen": "Invalid as a school_sourced_id target unless the source profile explicitly says local rows are schools."
      },
      {
        "value": "state",
        "meaning": "State-level education agency or authority.",
        "useWhen": "Use as a hierarchy ancestor or role scope when supplied by the source.",
        "invalidWhen": "Invalid as a class/enrollment school_sourced_id target."
      },
      {
        "value": "national",
        "meaning": "National-level education agency or authority.",
        "useWhen": "Use only for national hierarchy/role contexts supplied by the source.",
        "invalidWhen": "Invalid as a school_sourced_id target or ordinary school parent when a district/local row exists."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "brand",
    "anchor": "field-alpha-place-brand",
    "type": "TEXT enum",
    "values": [
      {
        "value": "100for100",
        "meaning": "100for100 brand. Live active org validation found this brand in the campus taxonomy intersected with production org rows.",
        "useWhen": "Use for NWEA-account district and school rows whose typed brand is 100for100.",
        "invalidWhen": "Invalid as a fallback for Alpha, GT, Texas Sports Academy, or partner brands."
      },
      {
        "value": "alpha",
        "meaning": "Alpha School brand. Live source aliases include Alpha, Alpha School, Alpha Anywhere, Alpha School campus names, and 2 Hour Learning legacy names.",
        "useWhen": "Use for Alpha School physical and virtual NWEA-account rows.",
        "invalidWhen": "Invalid for GT School, Texas Sports Academy, or non-Alpha partner schools."
      },
      {
        "value": "gt",
        "meaning": "GT School brand. Live aliases include GT School and GT Anywhere.",
        "useWhen": "Use for GT physical or virtual NWEA-account rows.",
        "invalidWhen": "Invalid for Alpha or partner school rows."
      },
      {
        "value": "limitless_education",
        "meaning": "Limitless Education brand observed in live active org rows.",
        "useWhen": "Use for schools whose typed brand is Limitless Education.",
        "invalidWhen": "Invalid for generic partner rows without that brand assignment."
      },
      {
        "value": "montessorium",
        "meaning": "Montessorium brand observed in live active org rows.",
        "useWhen": "Use for Montessorium school rows.",
        "invalidWhen": "Invalid for Alpha, GT, or Texas Sports Academy rows."
      },
      {
        "value": "nextgen",
        "meaning": "NextGen brand observed in live active org rows.",
        "useWhen": "Use for NextGen Academy or NextGen tutoring rows.",
        "invalidWhen": "Invalid for unrelated partner schools."
      },
      {
        "value": "nova_academy",
        "meaning": "Nova Academy brand observed in live active org rows.",
        "useWhen": "Use for Nova Academy campuses.",
        "invalidWhen": "Invalid for Novatio; that is a separate brand value."
      },
      {
        "value": "novatio",
        "meaning": "Novatio brand observed in live active org rows.",
        "useWhen": "Use for Novatio rows.",
        "invalidWhen": "Invalid for Nova Academy rows."
      },
      {
        "value": "sw_sales",
        "meaning": "SW Sales segment/brand value observed across Allendale and similar live active org rows.",
        "useWhen": "Use when the production taxonomy classifies the school as SW Sales.",
        "invalidWhen": "Invalid for Alpha-owned campuses or Texas Sports Academy rows."
      },
      {
        "value": "texas_sports_academy",
        "meaning": "Texas Sports Academy brand. Live aliases include Texas Sports Academy, TSA, TSA Online, and TSA sport/prep campus names.",
        "useWhen": "Use for Texas Sports Academy physical and virtual accounts.",
        "invalidWhen": "Invalid for Alpha, GT, or non-TSA partner rows."
      },
      {
        "value": "towermath",
        "meaning": "TowerMath brand observed in live active org rows.",
        "useWhen": "Use for TowerMath rows.",
        "invalidWhen": "Invalid for Alpha math products unless the typed brand is TowerMath."
      },
      {
        "value": "unbound",
        "meaning": "Unbound brand observed in live active org rows.",
        "useWhen": "Use for Unbound Academy rows.",
        "invalidWhen": "Invalid for other partner schools."
      },
      {
        "value": "waypoint",
        "meaning": "Waypoint brand observed in live active org rows.",
        "useWhen": "Use for Waypoint Academy rows.",
        "invalidWhen": "Invalid for other partner schools."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "modality",
    "anchor": "field-alpha-place-modality",
    "type": "TEXT enum",
    "values": [
      {
        "value": "physical",
        "meaning": "The NWEA account is for the physical-school modality of a brand. Live source aliases validated 2026-06-09: Physical folds here.",
        "useWhen": "Use for the district or school place row representing the physical NWEA account or child school.",
        "invalidWhen": "Invalid for virtual accounts or for a mixed/hybrid account."
      },
      {
        "value": "virtual",
        "meaning": "The NWEA account is for the virtual-school modality of a brand. Live source aliases validated 2026-06-09: Virtual folds here.",
        "useWhen": "Use for the district or school place row representing the virtual NWEA account or child school.",
        "invalidWhen": "Invalid for physical accounts or for a mixed/hybrid account."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "segment",
    "anchor": "field-alpha-place-segment",
    "type": "TEXT enum",
    "values": [
      {
        "value": "charter",
        "meaning": "Charter-school segment observed in live active org rows.",
        "useWhen": "Use for schools whose typed segment is charter.",
        "invalidWhen": "Invalid for private, virtual, or SW Sales rows."
      },
      {
        "value": "private",
        "meaning": "Private-school segment observed in live active org rows.",
        "useWhen": "Use for private school campuses and district accounts.",
        "invalidWhen": "Invalid for virtual-only, charter, or SW Sales rows."
      },
      {
        "value": "sw_sales",
        "meaning": "SW Sales segment observed in live active org rows.",
        "useWhen": "Use for schools typed into the SW Sales segment.",
        "invalidWhen": "Invalid for Alpha private/virtual rows unless the write boundary explicitly assigns SW Sales."
      },
      {
        "value": "virtual",
        "meaning": "Virtual segment observed in live active org rows.",
        "useWhen": "Use for schools or accounts whose segment is virtual.",
        "invalidWhen": "Invalid for physical private or charter segment rows; modality still remains physical or virtual separately."
      },
      {
        "value": "mixed",
        "meaning": "District/account rollup reserved for a district spanning multiple segments.",
        "useWhen": "Use only on a district/account row that intentionally spans more than one segment.",
        "invalidWhen": "Invalid on an ordinary school row or as a substitute for unknown."
      }
    ]
  },
  {
    "table": "alpha.place",
    "field": "level",
    "anchor": "field-alpha-place-level",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "WL",
        "meaning": "WonderLab, the pre-K Alpha level. Live source alias validated 2026-06-09: PKBY folds here.",
        "useWhen": "Use for the pre-K Alpha level, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for kindergarten, LearningLab, or any grade-level placement."
      },
      {
        "value": "LL",
        "meaning": "LearningLab, the K-1 Alpha level. Live source alias validated 2026-06-09: Linc folds here.",
        "useWhen": "Use for K-1 Alpha-level grouping, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for WonderLab or numbered upper levels."
      },
      {
        "value": "L1",
        "meaning": "Level 1, the grade 2-3 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 2 through grade 3.",
        "invalidWhen": "Invalid for grade 4+ cohorts or for MAP working-grade state."
      },
      {
        "value": "L2",
        "meaning": "Level 2, the grade 4-5 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 4 through grade 5.",
        "invalidWhen": "Invalid for grade 2-3, middle school, high school, or Results working-grade state."
      },
      {
        "value": "MS",
        "meaning": "Middle School, the grade 6-8 Alpha level. Live source aliases validated 2026-06-09: Middle School and L3 fold here.",
        "useWhen": "Use for middle-school Alpha-level grouping.",
        "invalidWhen": "Invalid for high school or elementary level rows."
      },
      {
        "value": "HS",
        "meaning": "High School, the grade 9-12 Alpha level. Live source aliases validated 2026-06-09: High School, L4.1, L4.2, and L4.3 fold here.",
        "useWhen": "Use for high-school Alpha-level grouping.",
        "invalidWhen": "Invalid for middle-school or elementary level rows."
      }
    ]
  },
  {
    "table": "alpha.person_ext",
    "field": "age_grade",
    "anchor": "field-alpha-person-ext-age-grade",
    "type": "INTEGER closed enum",
    "values": [
      {
        "value": "-1",
        "meaning": "PreK. Live source aliases validated 2026-06-09: -1 and PK fold here.",
        "useWhen": "Use for pre-kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for kindergarten or any student grade 1 through 12."
      },
      {
        "value": "0",
        "meaning": "Kindergarten. Live source aliases validated 2026-06-09: 0 and K fold here.",
        "useWhen": "Use for kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for PreK or any numbered grade."
      },
      {
        "value": "1",
        "meaning": "Grade 1.",
        "useWhen": "Use for grade 1 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "2",
        "meaning": "Grade 2.",
        "useWhen": "Use for grade 2 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "3",
        "meaning": "Grade 3.",
        "useWhen": "Use for grade 3 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "4",
        "meaning": "Grade 4. Live source aliases validated 2026-06-09: 4, 4TH_GRADE, and Grade_4 fold here.",
        "useWhen": "Use for grade 4 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "5",
        "meaning": "Grade 5.",
        "useWhen": "Use for grade 5 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "6",
        "meaning": "Grade 6.",
        "useWhen": "Use for grade 6 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "7",
        "meaning": "Grade 7.",
        "useWhen": "Use for grade 7 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "8",
        "meaning": "Grade 8.",
        "useWhen": "Use for grade 8 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "9",
        "meaning": "Grade 9.",
        "useWhen": "Use for grade 9 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "10",
        "meaning": "Grade 10.",
        "useWhen": "Use for grade 10 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "11",
        "meaning": "Grade 11.",
        "useWhen": "Use for grade 11 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "12",
        "meaning": "Grade 12.",
        "useWhen": "Use for grade 12 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      }
    ]
  },
  {
    "table": "alpha.person_ext",
    "field": "reality",
    "anchor": "field-alpha-person-ext-reality",
    "type": "TEXT enum",
    "values": [
      {
        "value": "real",
        "meaning": "A production student, person, school, district, or roster place that belongs in ordinary customer reports.",
        "useWhen": "Use for real TimeBack people and places after the write boundary has verified the source classification.",
        "invalidWhen": "Invalid for QA accounts, AI-agent test rows, generated fixtures, or demo-only entities."
      },
      {
        "value": "test",
        "meaning": "A QA, staff-test, integration-test, or AI-agent test entity that must be excluded from ordinary reports.",
        "useWhen": "Use for entities intentionally created to test the surface or another app.",
        "invalidWhen": "Invalid for production students or schools even if their display name looks unusual."
      },
      {
        "value": "synthetic",
        "meaning": "Generated, seeded, anonymized, or fixture data that is useful for demos or development but not a real customer row.",
        "useWhen": "Use for generated seed rows, local fixtures, and anonymized examples.",
        "invalidWhen": "Invalid for a row imported from the authoritative SIS or TimeBack production source as a real entity."
      }
    ]
  },
  {
    "table": "alpha.place_ext",
    "field": "reality",
    "anchor": "field-alpha-place-ext-reality",
    "type": "TEXT enum",
    "values": [
      {
        "value": "real",
        "meaning": "A production student, person, school, district, or roster place that belongs in ordinary customer reports.",
        "useWhen": "Use for real TimeBack people and places after the write boundary has verified the source classification.",
        "invalidWhen": "Invalid for QA accounts, AI-agent test rows, generated fixtures, or demo-only entities."
      },
      {
        "value": "test",
        "meaning": "A QA, staff-test, integration-test, or AI-agent test entity that must be excluded from ordinary reports.",
        "useWhen": "Use for entities intentionally created to test the surface or another app.",
        "invalidWhen": "Invalid for production students or schools even if their display name looks unusual."
      },
      {
        "value": "synthetic",
        "meaning": "Generated, seeded, anonymized, or fixture data that is useful for demos or development but not a real customer row.",
        "useWhen": "Use for generated seed rows, local fixtures, and anonymized examples.",
        "invalidWhen": "Invalid for a row imported from the authoritative SIS or TimeBack production source as a real entity."
      }
    ]
  },
  {
    "table": "alpha.alpha_level_history",
    "field": "alpha_level",
    "anchor": "field-alpha-alpha-level-history-alpha-level",
    "type": "TEXT closed enum",
    "values": [
      {
        "value": "WL",
        "meaning": "WonderLab, the pre-K Alpha level. Live source alias validated 2026-06-09: PKBY folds here.",
        "useWhen": "Use for the pre-K Alpha level, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for kindergarten, LearningLab, or any grade-level placement."
      },
      {
        "value": "LL",
        "meaning": "LearningLab, the K-1 Alpha level. Live source alias validated 2026-06-09: Linc folds here.",
        "useWhen": "Use for K-1 Alpha-level grouping, point-in-time as of the roster date.",
        "invalidWhen": "Invalid for WonderLab or numbered upper levels."
      },
      {
        "value": "L1",
        "meaning": "Level 1, the grade 2-3 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 2 through grade 3.",
        "invalidWhen": "Invalid for grade 4+ cohorts or for MAP working-grade state."
      },
      {
        "value": "L2",
        "meaning": "Level 2, the grade 4-5 Alpha level after live cohort confirmation.",
        "useWhen": "Use for the Alpha level spanning grade 4 through grade 5.",
        "invalidWhen": "Invalid for grade 2-3, middle school, high school, or Results working-grade state."
      },
      {
        "value": "MS",
        "meaning": "Middle School, the grade 6-8 Alpha level. Live source aliases validated 2026-06-09: Middle School and L3 fold here.",
        "useWhen": "Use for middle-school Alpha-level grouping.",
        "invalidWhen": "Invalid for high school or elementary level rows."
      },
      {
        "value": "HS",
        "meaning": "High School, the grade 9-12 Alpha level. Live source aliases validated 2026-06-09: High School, L4.1, L4.2, and L4.3 fold here.",
        "useWhen": "Use for high-school Alpha-level grouping.",
        "invalidWhen": "Invalid for middle-school or elementary level rows."
      }
    ]
  },
  {
    "table": "alpha.alpha_level_history",
    "field": "is_time_locatable",
    "anchor": "field-alpha-alpha-level-history-is-time-locatable",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.age_grade_history",
    "field": "age_grade",
    "anchor": "field-alpha-age-grade-history-age-grade",
    "type": "INTEGER closed enum",
    "values": [
      {
        "value": "-1",
        "meaning": "PreK. Live source aliases validated 2026-06-09: -1 and PK fold here.",
        "useWhen": "Use for pre-kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for kindergarten or any student grade 1 through 12."
      },
      {
        "value": "0",
        "meaning": "Kindergarten. Live source aliases validated 2026-06-09: 0 and K fold here.",
        "useWhen": "Use for kindergarten age-grade or enrolled-grade context.",
        "invalidWhen": "Invalid for PreK or any numbered grade."
      },
      {
        "value": "1",
        "meaning": "Grade 1.",
        "useWhen": "Use for grade 1 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "2",
        "meaning": "Grade 2.",
        "useWhen": "Use for grade 2 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "3",
        "meaning": "Grade 3.",
        "useWhen": "Use for grade 3 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "4",
        "meaning": "Grade 4. Live source aliases validated 2026-06-09: 4, 4TH_GRADE, and Grade_4 fold here.",
        "useWhen": "Use for grade 4 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "5",
        "meaning": "Grade 5.",
        "useWhen": "Use for grade 5 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "6",
        "meaning": "Grade 6.",
        "useWhen": "Use for grade 6 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "7",
        "meaning": "Grade 7.",
        "useWhen": "Use for grade 7 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "8",
        "meaning": "Grade 8.",
        "useWhen": "Use for grade 8 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "9",
        "meaning": "Grade 9.",
        "useWhen": "Use for grade 9 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "10",
        "meaning": "Grade 10.",
        "useWhen": "Use for grade 10 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "11",
        "meaning": "Grade 11.",
        "useWhen": "Use for grade 11 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      },
      {
        "value": "12",
        "meaning": "Grade 12.",
        "useWhen": "Use for grade 12 age-grade, enrolled-grade, or course grade-level context.",
        "invalidWhen": "Invalid when parsed from names, class titles, test labels, or free text at read time."
      }
    ]
  },
  {
    "table": "alpha.age_grade_history",
    "field": "is_time_locatable",
    "anchor": "field-alpha-age-grade-history-is-time-locatable",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.place_membership",
    "field": "role_kind",
    "anchor": "field-alpha-place-membership-role-kind",
    "type": "TEXT enum",
    "values": [
      {
        "value": "student",
        "meaning": "A learner whose roster context may feed Results and Events, but whose mastery and scores never live in People & Orgs.",
        "useWhen": "Use for source roles/enrollments that say student.",
        "invalidWhen": "Invalid for parents, guardians, staff, guides, or administrators."
      },
      {
        "value": "parent",
        "meaning": "A parent relationship for a student or school context.",
        "useWhen": "Use for the OneRoster parent role or a maintained source alias that folds to parent.",
        "invalidWhen": "Invalid for guardian when the source distinguishes guardian from parent."
      },
      {
        "value": "guardian",
        "meaning": "A guardian relationship for a student or school context.",
        "useWhen": "Use for the OneRoster guardian role or a maintained source alias that folds to guardian.",
        "invalidWhen": "Invalid for parent when the source distinguishes parent from guardian."
      },
      {
        "value": "relative",
        "meaning": "A family relationship that is not parent or guardian.",
        "useWhen": "Use for the OneRoster relative role.",
        "invalidWhen": "Invalid as a generic fallback for unknown family data."
      },
      {
        "value": "guide",
        "meaning": "A teacher or guide who works directly with students.",
        "useWhen": "Use for teacher source roles and approved aliases that TimeBack treats as instructional guides.",
        "invalidWhen": "Invalid for administrative-only or family relationship roles."
      },
      {
        "value": "staff",
        "meaning": "School staff who are not the student's primary instructional guide in this row.",
        "useWhen": "Use for aide, counselor, proctor, or similar staff roles when the source does not make them the guide.",
        "invalidWhen": "Invalid when the source role is teacher and the row should be guide."
      },
      {
        "value": "administrator",
        "meaning": "A district, site, system, or school administrator.",
        "useWhen": "Use for districtAdministrator, siteAdministrator, systemAdministrator, principal, or administrator source roles.",
        "invalidWhen": "Invalid for teachers, students, parents, or guardians."
      }
    ]
  },
  {
    "table": "alpha.place_membership",
    "field": "role_priority",
    "anchor": "field-alpha-place-membership-role-priority",
    "type": "TEXT enum",
    "values": [
      {
        "value": "primary",
        "meaning": "This is the user's primary role in the organization/date window.",
        "useWhen": "Use when one role should be treated as the main role for org-scoped lookups.",
        "invalidWhen": "Invalid if another role is already primary for the same user/org/window under the local profile."
      },
      {
        "value": "secondary",
        "meaning": "This is an additional non-primary role in the organization/date window.",
        "useWhen": "Use when the user has more than one org role.",
        "invalidWhen": "Invalid if the source intends the role to be primary."
      }
    ]
  },
  {
    "table": "alpha.place_membership",
    "field": "is_time_locatable",
    "anchor": "field-alpha-place-membership-is-time-locatable",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.class_membership",
    "field": "role_kind",
    "anchor": "field-alpha-class-membership-role-kind",
    "type": "TEXT enum",
    "values": [
      {
        "value": "student",
        "meaning": "The person participates in the learning group as a learner.",
        "useWhen": "Use for source enrollments.role=student.",
        "invalidWhen": "Invalid for guide, proctor, or administrator rows."
      },
      {
        "value": "guide",
        "meaning": "The person teaches or guides the learning group.",
        "useWhen": "Use for source enrollments.role=teacher.",
        "invalidWhen": "Invalid for learners or non-instructional administrative access."
      },
      {
        "value": "proctor",
        "meaning": "The person supervises an assessment or activity context without being the guide.",
        "useWhen": "Use for source enrollments.role=proctor.",
        "invalidWhen": "Invalid as a substitute for guide when the source says teacher."
      },
      {
        "value": "administrator",
        "meaning": "The person has administrative participation in the learning group.",
        "useWhen": "Use for source enrollments.role=administrator.",
        "invalidWhen": "Invalid for students or guides."
      }
    ]
  },
  {
    "table": "alpha.class_membership",
    "field": "is_primary_guide",
    "anchor": "field-alpha-class-membership-is-primary-guide",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.class_membership",
    "field": "is_time_locatable",
    "anchor": "field-alpha-class-membership-is-time-locatable",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.school_period",
    "field": "source_status",
    "anchor": "field-alpha-school-period-source-status",
    "type": "TEXT enum",
    "values": [
      {
        "value": "active",
        "meaning": "The delta row is current and should be inserted or updated.",
        "useWhen": "Use only in delta row status fields. Alpha keeps this only as source provenance; ordinary active-as-of queries still use dated memberships.",
        "invalidWhen": "Invalid in bulk rows or when the row should be deleted."
      },
      {
        "value": "tobedeleted",
        "meaning": "The delta row indicates the source wants this object deleted or retired.",
        "useWhen": "Use only in delta row status fields. Alpha keeps this only as source provenance; ordinary active-as-of queries still use dated memberships.",
        "invalidWhen": "Invalid in bulk rows or when the source object remains active."
      }
    ]
  },
  {
    "table": "alpha.school_period",
    "field": "period_kind",
    "anchor": "field-alpha-school-period-period-kind",
    "type": "TEXT enum",
    "values": [
      {
        "value": "school_year",
        "meaning": "Whole school-year calendar window. Source alias: OneRoster schoolYear.",
        "useWhen": "Use when the period spans the school year and school_year is the ending year.",
        "invalidWhen": "Invalid for semester, term, or grading-period windows."
      },
      {
        "value": "semester",
        "meaning": "A semester within a school year. Source alias: OneRoster semester.",
        "useWhen": "Use when the school calendar is semester-based.",
        "invalidWhen": "Invalid for shorter terms or grading periods."
      },
      {
        "value": "term",
        "meaning": "A term that is not a semester. Source alias: OneRoster term.",
        "useWhen": "Use for quarter, trimester, or local term windows represented by OneRoster term.",
        "invalidWhen": "Invalid for a whole school year."
      },
      {
        "value": "grading_period",
        "meaning": "A reporting period used for gradebook context. Source alias: OneRoster gradingPeriod.",
        "useWhen": "Use when a downstream gradebook or Results rollup needs the grading-period context.",
        "invalidWhen": "Invalid when the period is only a semester or whole school year."
      }
    ]
  },
  {
    "table": "alpha.person_sensitive_profile",
    "field": "sex",
    "anchor": "field-alpha-person-sensitive-profile-sex",
    "type": "TEXT enum",
    "values": [
      {
        "value": "male",
        "meaning": "Demographic sex value supplied by the source system.",
        "useWhen": "Use only when the source system lawfully provides this value.",
        "invalidWhen": "Invalid if copied to logs or used outside OneRoster demographic exchange."
      },
      {
        "value": "female",
        "meaning": "Demographic sex value supplied by the source system.",
        "useWhen": "Use only when the source system lawfully provides this value.",
        "invalidWhen": "Invalid if copied to logs or used outside OneRoster demographic exchange."
      },
      {
        "value": "unspecified",
        "meaning": "The source system did not specify a male/female/other value.",
        "useWhen": "Use when the demographic value is intentionally unspecified.",
        "invalidWhen": "Invalid if used to guess or erase a known source value."
      },
      {
        "value": "other",
        "meaning": "The source system supplied a demographic sex value outside male/female/unspecified.",
        "useWhen": "Use only when that is the source-system value.",
        "invalidWhen": "Invalid if used as a catch-all for missing data."
      }
    ]
  },
  {
    "table": "alpha.person_sensitive_profile",
    "field": "race_ethnicity_flags",
    "anchor": "field-alpha-person-sensitive-profile-race-ethnicity-flags",
    "type": "JSONB object",
    "values": [
      {
        "value": "american_indian_or_alaska_native",
        "meaning": "Source-supplied race flag. It may be true at the same time as another race flag.",
        "useWhen": "Use only when the source demographics row supplies the value.",
        "invalidWhen": "Invalid if inferred from name, language, place, or another demographic field."
      },
      {
        "value": "asian",
        "meaning": "Source-supplied race flag. It may be true at the same time as another race flag.",
        "useWhen": "Use only when the source demographics row supplies the value.",
        "invalidWhen": "Invalid if inferred from name, language, place, or another demographic field."
      },
      {
        "value": "black_or_african_american",
        "meaning": "Source-supplied race flag. It may be true at the same time as another race flag.",
        "useWhen": "Use only when the source demographics row supplies the value.",
        "invalidWhen": "Invalid if inferred from name, language, place, or another demographic field."
      },
      {
        "value": "native_hawaiian_or_other_pacific_islander",
        "meaning": "Source-supplied race flag. It may be true at the same time as another race flag.",
        "useWhen": "Use only when the source demographics row supplies the value.",
        "invalidWhen": "Invalid if inferred from name, language, place, or another demographic field."
      },
      {
        "value": "white",
        "meaning": "Source-supplied race flag. It may be true at the same time as another race flag.",
        "useWhen": "Use only when the source demographics row supplies the value.",
        "invalidWhen": "Invalid if inferred from name, language, place, or another demographic field."
      },
      {
        "value": "two_or_more_races",
        "meaning": "Source-supplied indicator that the source reports two or more races.",
        "useWhen": "Use only when the source sends demographic_race_two_or_more_races.",
        "invalidWhen": "Invalid if computed by counting other flags at read time."
      },
      {
        "value": "hispanic_or_latino_ethnicity",
        "meaning": "Source-supplied ethnicity flag. It is independent of race flags.",
        "useWhen": "Use only when the source demographics row supplies the value.",
        "invalidWhen": "Invalid if inferred from name, language, place, or another demographic field."
      }
    ]
  },
  {
    "table": "alpha.person_sensitive_profile",
    "field": "birth_place_fields",
    "anchor": "field-alpha-person-sensitive-profile-birth-place-fields",
    "type": "JSONB object",
    "values": [
      {
        "value": "country_of_birth_code",
        "meaning": "Country of birth code from OneRoster demographics.",
        "useWhen": "Use only when lawfully supplied by the source.",
        "invalidWhen": "Invalid if guessed from current address, language, or school."
      },
      {
        "value": "state_of_birth_abbreviation",
        "meaning": "State or province of birth abbreviation from OneRoster demographics.",
        "useWhen": "Use only when lawfully supplied by the source.",
        "invalidWhen": "Invalid if guessed or normalized without a source value."
      },
      {
        "value": "city_of_birth",
        "meaning": "City of birth text from OneRoster demographics.",
        "useWhen": "Use only when lawfully supplied by the source.",
        "invalidWhen": "Invalid if logged, exposed publicly, or inferred."
      }
    ]
  },
  {
    "table": "alpha.guardian_view",
    "field": "is_deleted",
    "anchor": "field-alpha-guardian-view-is-deleted",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.guardian_relationship_view",
    "field": "is_primary_contact",
    "anchor": "field-alpha-guardian-relationship-view-is-primary-contact",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.guardian_relationship_view",
    "field": "is_legal_guardian",
    "anchor": "field-alpha-guardian-relationship-view-is-legal-guardian",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.guardian_relationship_view",
    "field": "lives_with_student",
    "anchor": "field-alpha-guardian-relationship-view-lives-with-student",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.guardian_relationship_view",
    "field": "is_emergency_contact",
    "anchor": "field-alpha-guardian-relationship-view-is-emergency-contact",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.staff_assignment_view",
    "field": "is_time_locatable",
    "anchor": "field-alpha-staff-assignment-view-is-time-locatable",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.program_participation_view",
    "field": "is_time_locatable",
    "anchor": "field-alpha-program-participation-view-is-time-locatable",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.program_participation_view",
    "field": "source_program_resource",
    "anchor": "field-alpha-program-participation-view-source-program-resource",
    "type": "TEXT enum",
    "values": [
      {
        "value": "GeneralStudentProgramAssociation",
        "meaning": "Generic Ed-Fi student-program association.",
        "useWhen": "Use when the canonical record comes from GeneralStudentProgramAssociation.",
        "invalidWhen": "Invalid for specialized associations that the Ed-Fi surface names more specifically."
      },
      {
        "value": "StudentProgramAssociation",
        "meaning": "Ed-Fi student-program association family record.",
        "useWhen": "Use when the canonical record comes from StudentProgramAssociation or a direct equivalent.",
        "invalidWhen": "Invalid for unrelated attendance, discipline, transcript, or intervention-outcome records."
      },
      {
        "value": "SpecialEducationProgramAssociation",
        "meaning": "Special Education participation specialization when the Ed-Fi surface exposes it as a canonical program association.",
        "useWhen": "Use only for the Special Education program association.",
        "invalidWhen": "Invalid for outcomes, services effectiveness, or eligibility formulas."
      },
      {
        "value": "TitleIPartAProgramAssociation",
        "meaning": "Title I participation specialization when present in the Ed-Fi source.",
        "useWhen": "Use only for the Title I program association.",
        "invalidWhen": "Invalid for general program rows or outcome records."
      },
      {
        "value": "EnglishLearnerProgramAssociation",
        "meaning": "English Learner participation specialization when present in the Ed-Fi source.",
        "useWhen": "Use only for the English Learner program association.",
        "invalidWhen": "Invalid for language preference fields or test results."
      },
      {
        "value": "Section504ProgramAssociation",
        "meaning": "Section 504 participation specialization when present in the Ed-Fi source.",
        "useWhen": "Use only for the Section 504 program association.",
        "invalidWhen": "Invalid for service details or policy thresholds."
      },
      {
        "value": "FoodServiceProgramAssociation",
        "meaning": "Food service participation specialization when present in the Ed-Fi source.",
        "useWhen": "Use only for the Food Service program association.",
        "invalidWhen": "Invalid for finance records or eligibility calculations."
      }
    ]
  },
  {
    "table": "alpha.tag_definition",
    "field": "anchor",
    "anchor": "field-alpha-tag-definition-anchor",
    "type": "TEXT enum",
    "values": [
      {
        "value": "nwea_account",
        "meaning": "The tag applies to a place whose place_kind is district and which carries nwea_district_id.",
        "useWhen": "Use for locked brand and modality tags.",
        "invalidWhen": "Invalid on school rows or non-NWEA-account places."
      },
      {
        "value": "school",
        "meaning": "The tag applies to a place whose place_kind is school.",
        "useWhen": "Use for school-level report slicing dimensions such as level.",
        "invalidWhen": "Invalid for a relationship, foreign key, secret, or computed input."
      },
      {
        "value": "person",
        "meaning": "The tag applies to a person for reporting only.",
        "useWhen": "Use only for low-cardinality slices that are not relationships or sensitive secrets.",
        "invalidWhen": "Invalid for parent/guardian links, credentials, mastery, or policy formulas."
      }
    ]
  },
  {
    "table": "alpha.tag_definition",
    "field": "value_type",
    "anchor": "field-alpha-tag-definition-value-type",
    "type": "TEXT enum",
    "values": [
      {
        "value": "string",
        "meaning": "Allowed values are strings.",
        "useWhen": "Use for brand, modality, level, and similar labels.",
        "invalidWhen": "Invalid for dates or numeric bands."
      },
      {
        "value": "integer",
        "meaning": "Allowed values are integers.",
        "useWhen": "Use for a governed numeric slice.",
        "invalidWhen": "Invalid when values need decimal precision or units."
      },
      {
        "value": "boolean",
        "meaning": "Allowed values are true/false.",
        "useWhen": "Use for a governed reporting switch.",
        "invalidWhen": "Invalid when missing and false have different meanings."
      },
      {
        "value": "date",
        "meaning": "Allowed values are ISO dates.",
        "useWhen": "Use only for a report slice, not for point-in-time membership computations.",
        "invalidWhen": "Invalid when the date must be a real computed input column."
      }
    ]
  },
  {
    "table": "alpha.tag_definition",
    "field": "is_locked",
    "anchor": "field-alpha-tag-definition-is-locked",
    "type": "BOOLEAN",
    "values": [
      {
        "value": "true",
        "meaning": "The fact is asserted by the source or by the Alpha surface.",
        "useWhen": "Use only when the field's own constraints say the fact is true.",
        "invalidWhen": "Invalid when guessed from names, labels, dates, tags, or another field."
      },
      {
        "value": "false",
        "meaning": "The fact is explicitly not asserted.",
        "useWhen": "Use only when the source or surface stores an explicit false value.",
        "invalidWhen": "Invalid when a missing value should remain unknown."
      }
    ]
  },
  {
    "table": "alpha.object_tag",
    "field": "object_kind",
    "anchor": "field-alpha-object-tag-object-kind",
    "type": "TEXT enum",
    "values": [
      {
        "value": "person",
        "meaning": "The tag attaches to alpha.person.",
        "useWhen": "Use only when tag_definition.anchor allows person.",
        "invalidWhen": "Invalid when the tag describes a place or membership relationship."
      },
      {
        "value": "place",
        "meaning": "The tag attaches to alpha.place.",
        "useWhen": "Use for school, district, NWEA-account, brand, modality, or level slices when registered.",
        "invalidWhen": "Invalid when the tag value should be a real parent_place_id or nwea_district_id column."
      },
      {
        "value": "school_period",
        "meaning": "The tag attaches to alpha.school_period.",
        "useWhen": "Use for reporting slices only, not term math.",
        "invalidWhen": "Invalid when the period value is a computed input."
      },
      {
        "value": "place_membership",
        "meaning": "The tag attaches to alpha.place_membership.",
        "useWhen": "Use only for low-cardinality reporting dimensions registered for memberships.",
        "invalidWhen": "Invalid for person_id, place_id, begin_date, end_date, or role_kind."
      },
      {
        "value": "class_membership",
        "meaning": "The tag attaches to alpha.class_membership.",
        "useWhen": "Use only for low-cardinality reporting dimensions registered for class memberships.",
        "invalidWhen": "Invalid for class, school, person, date, or role relationships."
      }
    ]
  }
]

{
  "queriedAt": "2026-06-09T20:28:00Z",
  "queryTool": "node loop/nweamap/vendor/skill-pack-baseline/nwea-map-analysis/scripts/timeback-query.mjs --token-file ~/Documents/timeback-danny-mcp-creds",
  "productionDatabase": "app",
  "orgEvidence": {
    "sourceTable": "public.orgs",
    "activeOrgRows": 162,
    "taxonomyMatchedRows": 118,
    "taxonomyUnmatchedRows": 44,
    "brandValues": [
      "100for100",
      "alpha",
      "gt",
      "limitless_education",
      "montessorium",
      "nextgen",
      "nova_academy",
      "novatio",
      "sw_sales",
      "texas_sports_academy",
      "towermath",
      "unbound",
      "waypoint"
    ],
    "segmentValues": [
      "charter",
      "private",
      "sw_sales",
      "virtual",
      "mixed"
    ],
    "modalityValues": [
      "physical",
      "virtual"
    ],
    "note": "Production orgs do not yet store typed brand/segment columns. The closed lists were validated by intersecting live active org rows with the existing TimeBack campus taxonomy, then freezing write-boundary canonical values. Unmatched active orgs require reconciliation; they do not create an unknown enum value."
  },
  "alphaLevelEvidence": {
    "sourceTable": "public.users_visibility.user_alpha_level",
    "observedAliases": {
      "WL": [
        "WL",
        "PKBY"
      ],
      "LL": [
        "LL",
        "Linc"
      ],
      "L1": [
        "L1"
      ],
      "L2": [
        "L2"
      ],
      "MS": [
        "MS",
        "Middle School",
        "L3"
      ],
      "HS": [
        "HS",
        "High School",
        "L4.1",
        "L4.2",
        "L4.3"
      ]
    },
    "nullCount": 24577,
    "uncoveredValues": []
  },
  "gradeLevelEvidence": {
    "sourceTable": "public.users.grades",
    "observedAliases": {
      "0": [
        "0",
        "K"
      ],
      "4": [
        "4",
        "4TH_GRADE",
        "Grade_4"
      ],
      "-1": [
        "-1",
        "PK"
      ]
    },
    "uncoveredValues": [
      {
        "value": "13",
        "count": 112,
        "action": "Reject or reconcile at the write boundary; do not publish as canonical K-12 grade_level."
      }
    ]
  },
  "realityEvidence": {
    "sourceTables": [
      "SIS school/person classification",
      "TimeBack production test/demo markers"
    ],
    "note": "Wave 2 decision: reality is set at the write boundary from authoritative source classification. Consumers never infer it from person names, campus names, email domains, or hand-maintained exclusion lists.",
    "values": [
      "real",
      "test",
      "synthetic"
    ]
  }
}

{
  "generatedAt": "2026-06-11T00:00:00Z",
  "canonicalUrl": "https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture/",
  "upstream": {
    "rules": {
      "upstream_module": "oneroster+ed_fi"
    },
    "upstreamDictionaryUrl": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/",
    "edFiDictionaryUrl": "https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/data_dictionary/"
  },
  "aliasMap": [
    {
      "alphaObject": "person",
      "changeType": "rename+extend",
      "sourceType": "1edtech_alias_view_with_extension_join",
      "oneEdTechSource": "oneroster.users",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/#table-oneroster-users",
      "baseView": "alpha.person_base",
      "surfaceView": "alpha.person",
      "extensionTables": [
        "alpha.person_ext"
      ],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech users surface.",
      "extensionWriteRoute": "Write only admission_date, exit_date, age_grade, and reality to alpha.person_ext after the base person exists.",
      "meaning": "One human in the roster: student, parent or guardian, guide, staff member, or administrator. A person's roles are separate memberships, not hidden inside the person row.",
      "fields": [
        {
          "alphaField": "person_id",
          "sourceField": "sourced_id",
          "meaning": "Tenant-scoped person id.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "source_status",
          "sourceField": "status",
          "meaning": "OneRoster lifecycle state, preserved for provenance.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "source_updated_at",
          "sourceField": "date_last_modified",
          "meaning": "Source-system modified timestamp for delta rows.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "is_enabled",
          "sourceField": "enabled_user",
          "meaning": "Whether the source system says the account is enabled.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "username",
          "sourceField": "username",
          "meaning": "Roster username, never a password.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "first_name",
          "sourceField": "given_name",
          "meaning": "Legal or source first name.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "last_name",
          "sourceField": "family_name",
          "meaning": "Legal or source family name.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "middle_name",
          "sourceField": "middle_name",
          "meaning": "Legal or source middle name.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "preferred_first_name",
          "sourceField": "preferred_given_name",
          "meaning": "Preferred first name.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "preferred_last_name",
          "sourceField": "preferred_family_name",
          "meaning": "Preferred last name.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "email",
          "sourceField": "email",
          "meaning": "Contact email, subject to role-scoped privacy rules.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "sms",
          "sourceField": "sms",
          "meaning": "SMS contact address.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "phone",
          "sourceField": "phone",
          "meaning": "Phone contact.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "family_or_agent_person_ids",
          "sourceField": "agent_sourced_ids",
          "meaning": "Explicit OneRoster agent relationships such as parent or guardian links.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "grade_levels",
          "sourceField": "grades",
          "meaning": "Source grade values folded to the Alpha canonical grade vocabulary at write time.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "primary_place_id",
          "sourceField": "primary_org_sourced_id",
          "meaning": "Source primary organization for the person.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "admission_date",
          "sourceField": "alpha.person_ext.admission_date",
          "meaning": "Admission date used with asOfDate to compute tenure buckets.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "age_grade",
          "sourceField": "alpha.person_ext.age_grade",
          "meaning": "Canonical age-grade value set by the Alpha boundary; not parsed from names or test titles. Current convenience value; dated history lives in alpha.age_grade_history (PAITD-018).",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "reality",
          "sourceField": "alpha.person_ext.reality",
          "meaning": "Typed closed reality flag: real, test, or synthetic. Set at write time from authoritative source classification; ordinary reports default to real (PAITD-017).",
          "storageKind": "alpha_extend_table"
        }
      ]
    },
    {
      "alphaObject": "place",
      "changeType": "rename+restrict+extend",
      "sourceType": "1edtech_alias_view_with_extension_join",
      "oneEdTechSource": "oneroster.orgs",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/#table-oneroster-orgs",
      "baseView": "alpha.place_base",
      "surfaceView": "alpha.place",
      "extensionTables": [
        "alpha.place_ext",
        "alpha.object_tag"
      ],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech orgs surface.",
      "extensionWriteRoute": "Write nwea_district_id and reality to alpha.place_ext and report-slice tags to alpha.object_tag only.",
      "meaning": "A district, school, level, department, or other roster place. For NWEA, district means exactly one Brand x Modality NWEA account.",
      "fields": [
        {
          "alphaField": "place_id",
          "sourceField": "sourced_id",
          "meaning": "Tenant-scoped place id.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "source_status",
          "sourceField": "status",
          "meaning": "OneRoster lifecycle state.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "source_updated_at",
          "sourceField": "date_last_modified",
          "meaning": "Source-system modified timestamp for delta rows.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "name",
          "sourceField": "name",
          "meaning": "Place name.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "place_kind",
          "sourceField": "type",
          "meaning": "Canonical place type. District and school are structural; tags may refine but never override type.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "public_identifier",
          "sourceField": "identifier",
          "meaning": "Human-readable public identifier such as NCES id.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "parent_place_id",
          "sourceField": "parent_sourced_id",
          "meaning": "Parent place in the stock OneRoster tree.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "nwea_district_id",
          "sourceField": "alpha.place_ext.nwea_district_id",
          "meaning": "Required only when place_kind=district and the row is a Brand x Modality NWEA account.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "brand",
          "sourceField": "alpha.object_tag(tag_key=brand)",
          "meaning": "Locked registry tag anchored at nwea_account.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "modality",
          "sourceField": "alpha.object_tag(tag_key=modality)",
          "meaning": "Locked registry tag anchored at nwea_account; allowed values physical or virtual.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "level",
          "sourceField": "alpha.object_tag(tag_key=level)",
          "meaning": "Low-cardinality reporting dimension for school or program level.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "segment",
          "sourceField": "alpha.object_tag(tag_key=segment)",
          "meaning": "Closed governed reporting tag for the operating segment of a school or district; allowed values are seeded at setup and a place spanning more than one segment carries segment=mixed.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "reality",
          "sourceField": "alpha.place_ext.reality",
          "meaning": "Typed closed reality flag: real, test, or synthetic. Set at write time from authoritative source classification; ordinary reports default to real (PAITD-017).",
          "storageKind": "alpha_extend_table"
        }
      ]
    },
    {
      "alphaObject": "place_membership",
      "changeType": "rename+restrict",
      "sourceType": "1edtech_alias_view",
      "oneEdTechSource": "oneroster.roles",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/#table-oneroster-roles",
      "baseView": "alpha.place_membership_base",
      "surfaceView": "alpha.place_membership",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech roles surface.",
      "extensionWriteRoute": "None. is_time_locatable is a view expression, not stored Alpha state.",
      "meaning": "A dated relationship saying what one person is in one place, such as parent, guardian, guide, student, administrator, or staff.",
      "fields": [
        {
          "alphaField": "membership_id",
          "sourceField": "sourced_id",
          "meaning": "Tenant-scoped membership id.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "person_id",
          "sourceField": "user_sourced_id",
          "meaning": "Person who holds the role.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "place_id",
          "sourceField": "org_sourced_id",
          "meaning": "Place where the role applies.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "role_kind",
          "sourceField": "role",
          "meaning": "Canonical role enum with a maintained alias fold; never parsed from names or titles.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "role_priority",
          "sourceField": "role_type",
          "meaning": "Primary or secondary role marker.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "begin_date",
          "sourceField": "begin_date",
          "meaning": "Inclusive date when the membership becomes locatable.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "end_date",
          "sourceField": "end_date",
          "meaning": "Exclusive date when the membership stops being active; null means still active after begin_date.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "is_time_locatable",
          "sourceField": "view expression: begin_date is not null",
          "meaning": "True only when begin_date is non-null; consumers filter on this field instead of guessing at nulls.",
          "storageKind": "view_derived"
        },
        {
          "alphaField": "profile_id",
          "sourceField": "user_profile_sourced_id",
          "meaning": "Optional non-secret profile reference.",
          "storageKind": "oneedtech_view_column"
        }
      ]
    },
    {
      "alphaObject": "class_membership",
      "changeType": "rename+restrict",
      "sourceType": "1edtech_alias_view",
      "oneEdTechSource": "oneroster.enrollments",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/#table-oneroster-enrollments",
      "baseView": "alpha.class_membership_base",
      "surfaceView": "alpha.class_membership",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech enrollments surface.",
      "extensionWriteRoute": "None. is_time_locatable is a view expression, not stored Alpha state.",
      "meaning": "A dated relationship saying that one person belongs to one learning group at one school. The detailed class/course object is not re-owned by this module.",
      "fields": [
        {
          "alphaField": "membership_id",
          "sourceField": "sourced_id",
          "meaning": "Tenant-scoped class membership id.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "person_id",
          "sourceField": "user_sourced_id",
          "meaning": "Person in the learning group.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "school_id",
          "sourceField": "school_sourced_id",
          "meaning": "School place for the membership.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "learning_group_id",
          "sourceField": "class_sourced_id",
          "meaning": "OneRoster class id retained as a real relationship column.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "role_kind",
          "sourceField": "role",
          "meaning": "Canonical enrollment role: student, teacher, proctor, or administrator.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "is_primary_guide",
          "sourceField": "primary",
          "meaning": "Primary-teacher marker, valid only for guide/teacher rows.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "begin_date",
          "sourceField": "begin_date",
          "meaning": "Inclusive date when the membership becomes locatable.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "end_date",
          "sourceField": "end_date",
          "meaning": "Exclusive date when the membership stops being active; null means still active after begin_date.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "is_time_locatable",
          "sourceField": "view expression: begin_date is not null",
          "meaning": "True only when begin_date is non-null.",
          "storageKind": "view_derived"
        }
      ]
    },
    {
      "alphaObject": "school_period",
      "changeType": "rename+restrict",
      "sourceType": "1edtech_alias_view",
      "oneEdTechSource": "oneroster.academic_sessions",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/#table-oneroster-academic-sessions",
      "baseView": "alpha.school_period_base",
      "surfaceView": "alpha.school_period",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech academic_sessions surface.",
      "extensionWriteRoute": "None.",
      "meaning": "A school year, term, semester, or grading period used to answer roster questions as of a date.",
      "fields": [
        {
          "alphaField": "period_id",
          "sourceField": "sourced_id",
          "meaning": "Tenant-scoped school period id.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "source_status",
          "sourceField": "status",
          "meaning": "OneRoster lifecycle state.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "source_updated_at",
          "sourceField": "date_last_modified",
          "meaning": "Source-system modified timestamp for delta rows.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "title",
          "sourceField": "title",
          "meaning": "Human title for the period.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "period_kind",
          "sourceField": "type",
          "meaning": "Canonical period type; consumers never parse the title.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "start_date",
          "sourceField": "start_date",
          "meaning": "Inclusive period start date.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "end_date",
          "sourceField": "end_date",
          "meaning": "Exclusive period end date.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "parent_period_id",
          "sourceField": "parent_sourced_id",
          "meaning": "Parent period relationship.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "school_year",
          "sourceField": "school_year",
          "meaning": "Typed school-year value, not a string parsed from title.",
          "storageKind": "oneedtech_view_column"
        }
      ]
    },
    {
      "alphaObject": "person_sensitive_profile",
      "changeType": "restrict",
      "sourceType": "1edtech_restricted_view",
      "oneEdTechSource": "oneroster.demographics",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/oneroster/1edtech/data_dictionary/#table-oneroster-demographics",
      "baseView": "alpha.person_sensitive_profile_base",
      "surfaceView": "alpha.person_sensitive_profile",
      "extensionTables": [],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech demographics surface.",
      "extensionWriteRoute": "None. Authorization and redaction are API/view restrictions, not copied storage.",
      "meaning": "Sensitive demographic facts kept out of ordinary roster lists and returned only through authorized self, guardian, or administrative views.",
      "fields": [
        {
          "alphaField": "person_id",
          "sourceField": "sourced_id",
          "meaning": "Person whose sensitive profile is described.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "birth_date",
          "sourceField": "birth_date",
          "meaning": "Date of birth when lawfully supplied.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "sex",
          "sourceField": "sex",
          "meaning": "Source demographic sex value.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "race_ethnicity_flags",
          "sourceField": "race/ethnicity fields",
          "meaning": "Independent source flags; never inferred from names or places.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "birth_place_fields",
          "sourceField": "country/state/city of birth",
          "meaning": "Optional source-supplied birth location details.",
          "storageKind": "oneedtech_view_column"
        },
        {
          "alphaField": "residence_status",
          "sourceField": "public_school_residence_status",
          "meaning": "Source legal-residence status.",
          "storageKind": "oneedtech_view_column"
        }
      ]
    },
    {
      "alphaObject": "guardian",
      "changeType": "rename+restrict",
      "sourceType": "edfi_alias_view",
      "upstreamModule": "ed_fi/1edtech",
      "oneEdTechSource": "edfi.canonical_record(resource_name=Contact)",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/data_dictionary/#entry-contact-4d61009a458d",
      "baseView": "alpha.guardian_base_view",
      "surfaceView": "alpha.guardian_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech Contact collection; Alpha exposes only canonical, non-deleted Contact records.",
      "extensionWriteRoute": "None. Guardian facts that originate in Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "meaning": "A parent, guardian, emergency contact, or family contact for a student. The person exists because Ed-Fi administrative records know the contact even when OneRoster only has a thin agent reference.",
      "fields": [
        {
          "alphaField": "guardian_id",
          "sourceField": "edfi.canonical_record.edfi_local_id",
          "meaning": "Tenant-scoped Ed-Fi local id for the canonical Contact record.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "contact_unique_id",
          "sourceField": "edfi.canonical_record.payload_json.ContactUniqueId",
          "meaning": "Ed-Fi contact unique id.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "full_name",
          "sourceField": "edfi.canonical_record.payload_json.Name",
          "meaning": "Full legal name supplied by Ed-Fi Contact.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "email",
          "sourceField": "edfi.canonical_record.payload_json.ElectronicMail",
          "meaning": "Contact email, redacted by relationship-scoped authorization when required.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "phone",
          "sourceField": "edfi.canonical_record.payload_json.Telephone",
          "meaning": "Contact phone, redacted by relationship-scoped authorization when required.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "language_codes",
          "sourceField": "edfi.canonical_record.payload_json.Language",
          "meaning": "Communication languages from the Ed-Fi Contact payload.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "source_updated_at",
          "sourceField": "edfi.canonical_record.updated_at",
          "meaning": "Canonical Ed-Fi record updated timestamp.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "is_deleted",
          "sourceField": "edfi.canonical_record.is_deleted",
          "meaning": "Always false in ordinary Alpha views; deleted contacts are visible only to authorized audit paths.",
          "storageKind": "edfi_canonical_record_view_column"
        }
      ]
    },
    {
      "alphaObject": "guardian_relationship",
      "changeType": "rename+restrict",
      "sourceType": "edfi_alias_view",
      "upstreamModule": "ed_fi/1edtech",
      "oneEdTechSource": "edfi.canonical_record(resource_name=StudentContactAssociation)",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/data_dictionary/#entry-studentcontactassociation-32667f508a41",
      "baseView": "alpha.guardian_relationship_base_view",
      "surfaceView": "alpha.guardian_relationship_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech StudentContactAssociation collection; Alpha joins to OneRoster users only by platform3 sourcedId references.",
      "extensionWriteRoute": "None. Relationship descriptors and flags remain Ed-Fi canonical data.",
      "meaning": "The dated or active relationship between one student and one guardian/contact, including relation, priority, legal-guardian, lives-with, and emergency-contact facts.",
      "fields": [
        {
          "alphaField": "guardian_relationship_id",
          "sourceField": "edfi.canonical_record.edfi_local_id",
          "meaning": "Tenant-scoped Ed-Fi local id for the StudentContactAssociation record.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "student_person_id",
          "sourceField": "join oneroster.users.sourced_id via edfi.canonical_record.student_sourced_id",
          "meaning": "Student person id resolved through the platform3 sourcedId boundary.",
          "storageKind": "roster_fk_view_column"
        },
        {
          "alphaField": "guardian_id",
          "sourceField": "edfi.canonical_record.payload_json.Contact.ContactUniqueId",
          "meaning": "Contact id from the StudentContactAssociation payload, resolved to alpha.guardian_view when present.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "relationship_kind",
          "sourceField": "edfi.descriptor_code(Relation)",
          "meaning": "Governed Ed-Fi relation descriptor resolved to a stable plain value.",
          "storageKind": "edfi_descriptor_resolved_view"
        },
        {
          "alphaField": "is_primary_contact",
          "sourceField": "edfi.canonical_record.payload_json.PrimaryContactStatus",
          "meaning": "Whether Ed-Fi marks this contact as primary.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "is_legal_guardian",
          "sourceField": "edfi.canonical_record.payload_json.LegalGuardian",
          "meaning": "Whether Ed-Fi marks this contact as a legal guardian.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "lives_with_student",
          "sourceField": "edfi.canonical_record.payload_json.LivesWith",
          "meaning": "Whether the student lives with the contact.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "is_emergency_contact",
          "sourceField": "edfi.canonical_record.payload_json.EmergencyContactStatus",
          "meaning": "Whether the contact is an emergency contact.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "contact_priority",
          "sourceField": "edfi.canonical_record.payload_json.ContactPriority",
          "meaning": "Preferred contact order.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "contact_restrictions",
          "sourceField": "edfi.canonical_record.payload_json.ContactRestrictions",
          "meaning": "Contact restrictions; restricted/redacted by privacy rules.",
          "storageKind": "edfi_canonical_record_view_column"
        }
      ]
    },
    {
      "alphaObject": "staff_assignment",
      "changeType": "rename+restrict",
      "sourceType": "edfi_alias_view",
      "upstreamModule": "ed_fi/1edtech",
      "oneEdTechSource": "edfi.canonical_record(resource_name=StaffEducationOrganizationAssignmentAssociation)",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/data_dictionary/#entry-staffeducationorganizationassignmentassociation-e92aa18ecc7f",
      "baseView": "alpha.staff_assignment_base_view",
      "surfaceView": "alpha.staff_assignment_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech StaffEducationOrganizationAssignmentAssociation collection; OneRoster users and orgs remain the roster identity boundary.",
      "extensionWriteRoute": "None. Staff assignment facts from Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "meaning": "A staff member's assignment to a school, district, department, or other education organization beyond the role rows OneRoster already carries.",
      "fields": [
        {
          "alphaField": "staff_assignment_id",
          "sourceField": "edfi.canonical_record.edfi_local_id",
          "meaning": "Tenant-scoped Ed-Fi local id for the staff assignment.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "staff_person_id",
          "sourceField": "join oneroster.users.sourced_id via edfi.canonical_record.staff_sourced_id",
          "meaning": "Staff person id resolved through the platform3 sourcedId boundary.",
          "storageKind": "roster_fk_view_column"
        },
        {
          "alphaField": "place_id",
          "sourceField": "join oneroster.orgs.sourced_id via edfi.canonical_record.school_sourced_id",
          "meaning": "School or education organization place id resolved through OneRoster.",
          "storageKind": "roster_fk_view_column"
        },
        {
          "alphaField": "staff_classification",
          "sourceField": "edfi.descriptor_code(StaffClassification)",
          "meaning": "Governed staff-classification descriptor.",
          "storageKind": "edfi_descriptor_resolved_view"
        },
        {
          "alphaField": "position_title",
          "sourceField": "edfi.canonical_record.payload_json.PositionTitle",
          "meaning": "Human staff position title.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "begin_date",
          "sourceField": "edfi.canonical_record.payload_json.BeginDate",
          "meaning": "Inclusive date the assignment becomes locatable.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "end_date",
          "sourceField": "edfi.canonical_record.payload_json.EndDate",
          "meaning": "Date the assignment ends; null means active after begin_date.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "is_time_locatable",
          "sourceField": "view expression: payload_json.BeginDate is not null",
          "meaning": "True only when begin_date is present; consumers do not infer from nulls.",
          "storageKind": "view_derived"
        },
        {
          "alphaField": "assignment_order",
          "sourceField": "edfi.canonical_record.payload_json.OrderOfAssignment",
          "meaning": "Primary/secondary assignment order when supplied.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "full_time_equivalency",
          "sourceField": "edfi.canonical_record.payload_json.FullTimeEquivalency",
          "meaning": "Ratio of expected work time for the assignment.",
          "storageKind": "edfi_canonical_record_view_column"
        }
      ]
    },
    {
      "alphaObject": "program_participation",
      "changeType": "rename+restrict",
      "sourceType": "edfi_alias_view",
      "upstreamModule": "ed_fi/1edtech",
      "oneEdTechSource": "edfi.canonical_record(resource_name in GeneralStudentProgramAssociation, StudentProgramAssociation, and specializations)",
      "sourceAnchor": "https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/data_dictionary/#entry-generalstudentprogramassociation-b50a12920f64",
      "baseView": "alpha.program_participation_base_view",
      "surfaceView": "alpha.program_participation_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech Program and StudentProgramAssociation-family collections; Alpha joins student and place ids through OneRoster sourcedIds.",
      "extensionWriteRoute": "None. Program participation facts from Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "meaning": "A student's participation in an administrative program such as Special Education, Title I, English Learner, Section 504, food service, or another Ed-Fi program association. This records membership in the program, not outcomes or services effectiveness.",
      "fields": [
        {
          "alphaField": "program_participation_id",
          "sourceField": "edfi.canonical_record.edfi_local_id",
          "meaning": "Tenant-scoped Ed-Fi local id for the program association.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "student_person_id",
          "sourceField": "join oneroster.users.sourced_id via edfi.canonical_record.student_sourced_id",
          "meaning": "Student person id resolved through the platform3 sourcedId boundary.",
          "storageKind": "roster_fk_view_column"
        },
        {
          "alphaField": "place_id",
          "sourceField": "join oneroster.orgs.sourced_id via edfi.canonical_record.school_sourced_id",
          "meaning": "School or education organization place id resolved through OneRoster.",
          "storageKind": "roster_fk_view_column"
        },
        {
          "alphaField": "program_id",
          "sourceField": "edfi.canonical_record.payload_json.Program.ProgramId",
          "meaning": "Program identifier from the linked Ed-Fi Program payload when present.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "program_name",
          "sourceField": "edfi.canonical_record.payload_json.Program.ProgramName",
          "meaning": "Plain program name.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "program_type",
          "sourceField": "edfi.descriptor_code(ProgramType)",
          "meaning": "Governed Ed-Fi program-type descriptor.",
          "storageKind": "edfi_descriptor_resolved_view"
        },
        {
          "alphaField": "participation_status",
          "sourceField": "edfi.descriptor_code(ProgramParticipationStatus)",
          "meaning": "Governed participation-status descriptor.",
          "storageKind": "edfi_descriptor_resolved_view"
        },
        {
          "alphaField": "begin_date",
          "sourceField": "edfi.canonical_record.payload_json.BeginDate",
          "meaning": "Inclusive date the student becomes involved with the program.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "end_date",
          "sourceField": "edfi.canonical_record.payload_json.EndDate",
          "meaning": "Date the student exits the program; null means active after begin_date.",
          "storageKind": "edfi_canonical_record_view_column"
        },
        {
          "alphaField": "is_time_locatable",
          "sourceField": "view expression: payload_json.BeginDate is not null",
          "meaning": "True only when begin_date is present.",
          "storageKind": "view_derived"
        },
        {
          "alphaField": "source_program_resource",
          "sourceField": "edfi.canonical_record.resource_name",
          "meaning": "Exact Ed-Fi association/specialization that produced the row.",
          "storageKind": "edfi_canonical_record_view_column"
        }
      ]
    },
    {
      "alphaObject": "app_credential",
      "changeType": "extend",
      "sourceType": "alpha_extend",
      "oneEdTechSource": null,
      "sourceAnchor": "#paitd-008-app-credentials",
      "baseView": null,
      "surfaceView": "alpha.app_credential",
      "extensionTables": [
        "alpha.app_credential"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.app_credential rows with a student_sourced_id foreign key to oneroster.users.",
      "meaning": "A first-class operational secret reference for a student's login to a third-party learning app. The secret value is never stored in a roster field, tag, log, or API response.",
      "fields": [
        {
          "alphaField": "student_sourced_id",
          "sourceField": "alpha.app_credential.student_sourced_id",
          "meaning": "Student person id foreign key that owns the credential; named to match the required app_credential contract.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "app_id",
          "sourceField": "alpha.app_credential.app_id",
          "meaning": "Learning app identifier.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "secret_ref",
          "sourceField": "alpha.app_credential.secret_ref",
          "meaning": "Reference to a managed secrets vault, never plaintext.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "created_at",
          "sourceField": "alpha.app_credential.created_at",
          "meaning": "Credential reference creation time.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "last_rotated_at",
          "sourceField": "alpha.app_credential.last_rotated_at",
          "meaning": "Last rotation time surfaced for audit and operations.",
          "storageKind": "alpha_extend_table"
        }
      ]
    },
    {
      "alphaObject": "tag_definition",
      "changeType": "extend",
      "sourceType": "alpha_extend",
      "oneEdTechSource": null,
      "sourceAnchor": "#paitd-006-tag-registry",
      "baseView": null,
      "surfaceView": "alpha.tag_definition",
      "extensionTables": [
        "alpha.tag_definition"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.tag_definition rows only; no 1EdTech columns are copied.",
      "meaning": "Governed tag registry for low-cardinality roster reporting dimensions that do not belong as enforced relationship columns.",
      "fields": [
        {
          "alphaField": "tag_key",
          "sourceField": "alpha.tag_definition.tag_key",
          "meaning": "Stable tag key.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "anchor",
          "sourceField": "alpha.tag_definition.anchor",
          "meaning": "The grain the tag is allowed to attach to, such as nwea_account or school.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "allowed_values",
          "sourceField": "alpha.tag_definition.allowed_values",
          "meaning": "Governed allowed value list.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "value_type",
          "sourceField": "alpha.tag_definition.value_type",
          "meaning": "Typed value class.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "is_locked",
          "sourceField": "alpha.tag_definition.is_locked",
          "meaning": "True when setup seeds and locks the tag, as with brand and modality.",
          "storageKind": "alpha_extend_table"
        }
      ]
    },
    {
      "alphaObject": "object_tag",
      "changeType": "extend",
      "sourceType": "alpha_extend",
      "oneEdTechSource": null,
      "sourceAnchor": "#paitd-006-tag-registry",
      "baseView": null,
      "surfaceView": "alpha.object_tag",
      "extensionTables": [
        "alpha.object_tag"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.object_tag rows only; object_id is a relationship reference to a live public object, not a copied 1EdTech field.",
      "meaning": "A governed tag assignment for report slicing only. It is never used for relationships, joins to live rows, or secrets.",
      "fields": [
        {
          "alphaField": "object_kind",
          "sourceField": "alpha.object_tag.object_kind",
          "meaning": "Tagged Alpha object kind.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "object_id",
          "sourceField": "alpha.object_tag.object_id",
          "meaning": "Tagged object id.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "tag_key",
          "sourceField": "alpha.object_tag.tag_key",
          "meaning": "Registered tag key.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "tag_value",
          "sourceField": "alpha.object_tag.tag_value",
          "meaning": "Allowed value from tag_definition.",
          "storageKind": "alpha_extend_table"
        }
      ]
    },
    {
      "alphaObject": "alpha_level_history",
      "changeType": "extend",
      "sourceType": "alpha_extend",
      "oneEdTechSource": null,
      "sourceAnchor": "#paitd-018-over-time-history",
      "baseView": null,
      "surfaceView": "alpha.alpha_level_history",
      "extensionTables": [
        "alpha.alpha_level_history"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write effective-dated alpha.alpha_level_history rows with a person_id foreign key to the base person, after the base person exists. No OneRoster or Ed-Fi column is copied.",
      "meaning": "Effective-dated history of a student's Alpha level. Answers alphaLevel(person, asOfDate) for current and past dates; the dated table is the system of record so no level change overwrites history.",
      "fields": [
        {
          "alphaField": "history_id",
          "sourceField": "alpha.alpha_level_history.history_id",
          "meaning": "Tenant-scoped Alpha-owned history row id; not a OneRoster sourcedId.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "person_id",
          "sourceField": "alpha.alpha_level_history.person_id",
          "meaning": "Foreign key to the base person row; the only reference this extension table holds.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "alpha_level",
          "sourceField": "alpha.alpha_level_history.alpha_level",
          "meaning": "Canonical Alpha level for this interval; source labels are folded through alpha.policy.alpha_level_alias_folds at write time.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "begin_date",
          "sourceField": "alpha.alpha_level_history.begin_date",
          "meaning": "Inclusive date the level becomes effective; null excludes the row from point-in-time reads.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "end_date",
          "sourceField": "alpha.alpha_level_history.end_date",
          "meaning": "Exclusive date the level ends; null means still active for dates on or after begin_date.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "is_time_locatable",
          "sourceField": "view expression: begin_date is not null",
          "meaning": "True only when begin_date is non-null; consumers filter on this field instead of guessing at nulls.",
          "storageKind": "view_derived"
        }
      ]
    },
    {
      "alphaObject": "age_grade_history",
      "changeType": "extend",
      "sourceType": "alpha_extend",
      "oneEdTechSource": null,
      "sourceAnchor": "#paitd-018-over-time-history",
      "baseView": null,
      "surfaceView": "alpha.age_grade_history",
      "extensionTables": [
        "alpha.age_grade_history"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write effective-dated alpha.age_grade_history rows with a person_id foreign key to the base person, after the base person exists. No OneRoster or Ed-Fi column is copied.",
      "meaning": "Effective-dated history of a student's canonical age grade. Answers ageGrade(person, asOfDate) for current and past dates; the dated table is the system of record so no grade change overwrites history.",
      "fields": [
        {
          "alphaField": "history_id",
          "sourceField": "alpha.age_grade_history.history_id",
          "meaning": "Tenant-scoped Alpha-owned history row id; not a OneRoster sourcedId.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "person_id",
          "sourceField": "alpha.age_grade_history.person_id",
          "meaning": "Foreign key to the base person row; the only reference this extension table holds.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "age_grade",
          "sourceField": "alpha.age_grade_history.age_grade",
          "meaning": "Canonical age grade for this interval; source labels are folded through alpha.policy.grade_alias_folds at write time and never parsed from names.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "begin_date",
          "sourceField": "alpha.age_grade_history.begin_date",
          "meaning": "Inclusive date the age grade becomes effective; null excludes the row from point-in-time reads.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "end_date",
          "sourceField": "alpha.age_grade_history.end_date",
          "meaning": "Exclusive date the age grade ends; null means still active for dates on or after begin_date.",
          "storageKind": "alpha_extend_table"
        },
        {
          "alphaField": "is_time_locatable",
          "sourceField": "view expression: begin_date is not null",
          "meaning": "True only when begin_date is non-null; consumers filter on this field instead of guessing at nulls.",
          "storageKind": "view_derived"
        }
      ]
    }
  ],
  "storageContract": [
    {
      "alphaObject": "person",
      "publicSurface": "alpha.person",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.users",
      "baseView": "alpha.person_base",
      "extensionTables": [
        "alpha.person_ext"
      ],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech users surface.",
      "extensionWriteRoute": "Write only admission_date, exit_date, age_grade, and reality to alpha.person_ext after the base person exists.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "place",
      "publicSurface": "alpha.place",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.orgs",
      "baseView": "alpha.place_base",
      "extensionTables": [
        "alpha.place_ext",
        "alpha.object_tag"
      ],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech orgs surface.",
      "extensionWriteRoute": "Write nwea_district_id and reality to alpha.place_ext and report-slice tags to alpha.object_tag only.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "place_membership",
      "publicSurface": "alpha.place_membership",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.roles",
      "baseView": "alpha.place_membership_base",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech roles surface.",
      "extensionWriteRoute": "None. is_time_locatable is a view expression, not stored Alpha state.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "class_membership",
      "publicSurface": "alpha.class_membership",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.enrollments",
      "baseView": "alpha.class_membership_base",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech enrollments surface.",
      "extensionWriteRoute": "None. is_time_locatable is a view expression, not stored Alpha state.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "school_period",
      "publicSurface": "alpha.school_period",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.academic_sessions",
      "baseView": "alpha.school_period_base",
      "extensionTables": [],
      "coreWriteRoute": "Route all writes to the OneRoster 1EdTech academic_sessions surface.",
      "extensionWriteRoute": "None.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "person_sensitive_profile",
      "publicSurface": "alpha.person_sensitive_profile",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": "oneroster.demographics",
      "baseView": "alpha.person_sensitive_profile_base",
      "extensionTables": [],
      "coreWriteRoute": "Route sourced-field writes to the OneRoster 1EdTech demographics surface.",
      "extensionWriteRoute": "None. Authorization and redaction are API/view restrictions, not copied storage.",
      "requiredShape": "CREATE VIEW over the OneRoster 1EdTech base; no Alpha table may store sourced OneRoster columns."
    },
    {
      "alphaObject": "guardian",
      "publicSurface": "alpha.guardian_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name=Contact)",
      "baseView": "alpha.guardian_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech Contact collection; Alpha exposes only canonical, non-deleted Contact records.",
      "extensionWriteRoute": "None. Guardian facts that originate in Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "guardian_relationship",
      "publicSurface": "alpha.guardian_relationship_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name=StudentContactAssociation)",
      "baseView": "alpha.guardian_relationship_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech StudentContactAssociation collection; Alpha joins to OneRoster users only by platform3 sourcedId references.",
      "extensionWriteRoute": "None. Relationship descriptors and flags remain Ed-Fi canonical data.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "staff_assignment",
      "publicSurface": "alpha.staff_assignment_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name=StaffEducationOrganizationAssignmentAssociation)",
      "baseView": "alpha.staff_assignment_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech StaffEducationOrganizationAssignmentAssociation collection; OneRoster users and orgs remain the roster identity boundary.",
      "extensionWriteRoute": "None. Staff assignment facts from Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "program_participation",
      "publicSurface": "alpha.program_participation_view",
      "upstreamModule": "ed_fi/1edtech",
      "baseSource": "edfi.canonical_record(resource_name in GeneralStudentProgramAssociation, StudentProgramAssociation, and specializations)",
      "baseView": "alpha.program_participation_base_view",
      "extensionTables": [],
      "coreWriteRoute": "Route all sourced-field writes to the Ed-Fi 1EdTech Program and StudentProgramAssociation-family collections; Alpha joins student and place ids through OneRoster sourcedIds.",
      "extensionWriteRoute": "None. Program participation facts from Ed-Fi stay in edfi.canonical_record and descriptor_code-backed views.",
      "requiredShape": "CREATE VIEW over edfi.canonical_record; filter resource_name/collection_route, tenant_id, is_deleted=false, canonical state, descriptor_code resolution, and OneRoster sourcedId joins. No Alpha table may store sourced Ed-Fi columns."
    },
    {
      "alphaObject": "app_credential",
      "publicSurface": "alpha.app_credential",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.app_credential"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.app_credential rows with a student_sourced_id foreign key to oneroster.users.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "tag_definition",
      "publicSurface": "alpha.tag_definition",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.tag_definition"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.tag_definition rows only; no 1EdTech columns are copied.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "object_tag",
      "publicSurface": "alpha.object_tag",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.object_tag"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write alpha.object_tag rows only; object_id is a relationship reference to a live public object, not a copied 1EdTech field.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "alpha_level_history",
      "publicSurface": "alpha.alpha_level_history",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.alpha_level_history"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write effective-dated alpha.alpha_level_history rows with a person_id foreign key to the base person, after the base person exists. No OneRoster or Ed-Fi column is copied.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    },
    {
      "alphaObject": "age_grade_history",
      "publicSurface": "alpha.age_grade_history",
      "upstreamModule": "oneroster/1edtech",
      "baseSource": null,
      "baseView": null,
      "extensionTables": [
        "alpha.age_grade_history"
      ],
      "coreWriteRoute": "None.",
      "extensionWriteRoute": "Write effective-dated alpha.age_grade_history rows with a person_id foreign key to the base person, after the base person exists. No OneRoster or Ed-Fi column is copied.",
      "requiredShape": "CREATE TABLE is allowed because this is a pure Alpha extension."
    }
  ],
  "forbiddenAlphaTables": [
    "alpha.person",
    "alpha.place",
    "alpha.place_membership",
    "alpha.class_membership",
    "alpha.school_period",
    "alpha.person_sensitive_profile",
    "alpha.guardian_view",
    "alpha.guardian_relationship_view",
    "alpha.staff_assignment_view",
    "alpha.program_participation_view"
  ],
  "allowedExtensionTables": [
    "alpha.person_ext",
    "alpha.place_ext",
    "alpha.app_credential",
    "alpha.tag_definition",
    "alpha.object_tag",
    "alpha.alpha_level_history",
    "alpha.age_grade_history"
  ]
}

[
  {
    "fact": "person identity and contact",
    "home": "People & Orgs",
    "reason": "It says who someone is."
  },
  {
    "fact": "guardian and student-guardian relationship",
    "home": "People & Orgs",
    "reason": "It says who may act for or contact a student, with the relationship tied to one student."
  },
  {
    "fact": "place, school, district, NWEA account boundary",
    "home": "People & Orgs",
    "reason": "It says where people belong and how places nest."
  },
  {
    "fact": "roles and enrollments with dates",
    "home": "People & Orgs",
    "reason": "They link a person to a place or learning group over time."
  },
  {
    "fact": "staff assignment to an education organization",
    "home": "People & Orgs",
    "reason": "It says where a staff person serves and in what capacity as of a date."
  },
  {
    "fact": "student program participation",
    "home": "People & Orgs",
    "reason": "It says a student belongs to an administrative program at a place for a date range."
  },
  {
    "fact": "Alpha level over time and age grade over time",
    "home": "People & Orgs",
    "reason": "They say what level or grade a student is as of a date - who someone is over time - kept as dated history, not student outcomes."
  },
  {
    "fact": "real / test / synthetic classification of a person or place",
    "home": "People & Orgs",
    "reason": "It says what kind of roster entity this is so reports include only real people and places; it is identity context, not an outcome."
  },
  {
    "fact": "highest mastered grade as of a date",
    "home": "Results",
    "reason": "It reads the mastery ledger as of a date; the dated knowledge state is a durable statement about how a student is doing, not roster belonging."
  },
  {
    "fact": "student mastery, decay, working grade, MAP result, report-card outcome",
    "home": "Results",
    "reason": "It is a durable statement about how a specific student is doing."
  },
  {
    "fact": "program outcomes, intervention effect, eligibility formulas, thresholds",
    "home": "Results / Policy",
    "reason": "They are settled outcomes or policy decisions, not roster belonging facts."
  },
  {
    "fact": "curriculum graph and knowledge components",
    "home": "Curriculum",
    "reason": "It is the shared map of what there is to learn."
  },
  {
    "fact": "questions, lessons, videos, articles, tests",
    "home": "Content",
    "reason": "They are things students touch."
  },
  {
    "fact": "views, submissions, hint requests, video scrubs",
    "home": "Events",
    "reason": "They are records that something happened."
  }
]

[
  {
    "rule": "Tag registry vs. real column",
    "handling": "Relationships, computed inputs, constraints, sort keys, and durable structural fields are real columns. On Alpha, sourced columns are view expressions over OneRoster or Ed-Fi canonical records; only new Alpha-owned facts live in extension tables. Brand, modality, segment, and level are governed registry tags only when used as report slices, with brand/modality locked at the NWEA-account grain and segment a closed list (a place spanning more than one segment is tagged segment=mixed). Ed-Fi descriptors resolve through edfi.descriptor_code, not free tags."
  },
  {
    "rule": "Point-in-time is default",
    "handling": "Roles, enrollments, school assignments, guide assignments, guardian relationships, staff assignments, program participation, Alpha level, age grade, and campus facts answer by entity plus asOfDate. begin_date null means excluded; end_date null means active after begin_date; both null means excluded. is_time_locatable is exposed. Alpha level and age grade keep dated history (alpha.alpha_level_history, alpha.age_grade_history) instead of a single overwritten current column."
  },
  {
    "rule": "Typed, never parsed",
    "handling": "role_kind, place_kind, period_kind, age_grade, school_year, season, brand, modality, segment, level, relationship_kind, staff_classification, program_type, and participation_status are typed at write time or descriptor-resolution time with maintained alias folds. Consumers never parse names, titles, URLs, or free strings."
  },
  {
    "rule": "Policy in alpha.policy.*",
    "handling": "Tenure buckets and school-year boundaries are named policy config; no dashboard or skill pack hardcodes them."
  },
  {
    "rule": "Event/result/gradebook split",
    "handling": "This module owns roster facts only. Interaction events live in Events; scored outcomes and gradebook rollups live in Results."
  },
  {
    "rule": "Two graphs, two homes",
    "handling": "The shared curriculum graph lives in Curriculum, and per-student mastery state lives in Results. Mastery is never a field on person."
  },
  {
    "rule": "NWEA account is district",
    "handling": "Each Brand x Modality NWEA account is exactly one place with place_kind=district, required nwea_district_id, locked brand/modality tags, and school children linked by parent_place_id."
  },
  {
    "rule": "Secrets are not roster fields",
    "handling": "OneRoster password fields and user_profile passwords are cut from Alpha. Student app credentials use app_credential.secret_ref to a vault and never return secret values."
  },
  {
    "rule": "Tenure bands are config",
    "handling": "Tenure derives from person.admission_date and alpha.policy.tenure_buckets at asOfDate."
  },
  {
    "rule": "Ed-Fi view guardrails are raw-DB rules",
    "handling": "Guardian, guardian_relationship, staff_assignment, and program_participation views select only edfi.canonical_record rows for the named resource, scoped by tenant_id, ordinary reads filter is_deleted=false, drafts in edfi.draft_record never appear as canonical facts, descriptor fields join edfi.descriptor_code, and student/staff/place references join OneRoster via platform3 sourcedId columns."
  },
  {
    "rule": "Content effectiveness belongs to Content",
    "handling": "No person or place counter stores validated_by_count, failed_by_count, or effectiveness rate."
  },
  {
    "rule": "Real-only is the reporting default",
    "handling": "Person and place carry a typed closed reality enum (real, test, synthetic) set at the write boundary from authoritative source classification. Ordinary reports default to reality=real; including test or synthetic is an explicit documented parameter. No consumer hand-maintains a name/email/campus exclusion list, and reality is never inferred from display strings."
  },
  {
    "rule": "External results use ingest adapters",
    "handling": "People & Orgs supplies canonical student ids and place context only; MAP, AP, and other results normalize in Results/NWEAMap adapters."
  },
  {
    "rule": "Test type is on Content",
    "handling": "No People & Orgs field classifies tests or gates by parsing names."
  },
  {
    "rule": "K-8 advancement is surface-owned",
    "handling": "People & Orgs supplies identity, school, grade, and tenure inputs; advancement is computed by the Results surface metric."
  }
]