DEPLOYMENT_NOTES.md

Deployment notes — SAT & ACT Learning Lab 1.8.18+hfbuild6

Target private Space: DearmonAnalytics/SAT_ACT_Learning_Lab

Turso database: dearmon-sat-act-learning-lab

Schema namespace: sat_act_learning_lab_v1

Encrypted-source secret: SAT_ACT_APP_FERNET_V1_8_18_HFBUILD6_FA5015374498_45CC1E1A0BC7

Runtime contract

• Python 3.12 and Gradio 6.24.0 are pinned.
• The encrypted package is authenticated with Fernet and verified against both ciphertext and decrypted-archive SHA-256 hashes.
• Python source modules load from memory; plaintext source is not extracted to the Space filesystem.
• Turso is required in production. Each process may use its own embedded replica at /tmp/dearmon-sat-act-learning-lab-{pid}.db.
• Authentication-sensitive account reads refresh that replica on a bounded process-local interval and fail closed if a required refresh cannot complete. Live timed-exam state and mutation locks are process-local, so this release must run one application process for authoritative simulation/resume. A multi-process topology requires a distributed exam lease/generation protocol; sticky routing alone does not provide that guarantee.
• Username accounts map to stable opaque learner IDs and store only salted scrypt password records. Five failed sign-ins within 15 minutes lock the account for 15 minutes, and authentication-version checks revoke old sessions after a password change or recovery.
• Legacy learner IDs use the same stable server-side HMAC secret; learner PINs must not be stored or logged. Conversion requires verified name/class/PIN credentials and retains the existing learner ID and mastery history.
• Email password recovery is optional and uses an eight-digit, 15-minute, single-use code with five attempts. Every account also receives a one-time-display offline recovery key that is stored only as a keyed digest and rotates after use or password change.
• One-click demos have a 45-minute ordinary-use window and route all seeded/new progress and simulation state to bounded process memory—not Turso, instructor analytics, exports, deletion, or recovery. A started full simulation may reserve blueprint duration plus a 45-minute grace period, capped at four hours; sign-out or restart still erases it immediately.
• Instructor-wide access requires a strong secret with no fallback.
• Core scored questions and answer keys are deterministic and model-independent.
• Every shipped authored question resolver has a versioned eight-level skill profile with complete ancestor/prerequisite closure and an explicit scoring role. The immutable release gate covers exactly 1,983 profiles and fails closed on an unknown node, missing level, incomplete closure, cycle, or scoring-role conflict.
• Raw objective results remain authoritative. A deterministic estimator reports a separate, explicitly unofficial SAT/ACT practice-score point, plausible interval, evidence sufficiency, and confidence. Optional ACT Science is separate from the English/Math/Reading Composite; ACT Writing remains human reviewed. Pretest/EFT and AI print-only items cannot enter the estimate.
• The Printable Exam Builder requires an active demo or signed-in learner so every generated file is vault-owned, then produces separate matched student/key PDFs from selected or learner-missed topics. Optional AI overflow is explicit, serialized, globally/individually rate-limited, capped at two topic batches and eight items per build, independently reviewed, print-only, and locked until the active learner has completed every built-in question type for that exact topic. It never enters skill evidence, mastery, readiness, routing, diagnostics, or score estimates.
• Break It Apart is a deterministic, provider-independent, post-miss reasoning DAG. It is available after every incorrect practice grade and for every missed objective item reviewed after a completed simulation—never before grading or during an active form. The topic is the top node; sentence, quantity/unit/operation, claim/evidence, or data/variable attributes feed up through the answer dependency path. These attributes are explanatory only and do not create separate mastery or retention records.
• Each graded practice explanation may expose one attempt-bound OpenAI follow-up for the owning signed-in learner. It is unavailable before grading and is retained with that attempt; stale or cross-learner question tokens fail closed.
• The retained Learning Diagnostic uses distinct-topic coverage and remains locked until the same signed-in learner exceeds 50% in both Reading and Math for SAT or ACT. OpenAI receives only allowlisted aggregate counts and foundational-skill evidence—never identity, raw item text, selected responses, or answer keys—and its structured output must match server-known findings and remediation ladders. Guided Examples and Targeted Practice unlock only after a validated report is retained; remediation is deterministic and cannot count toward its own coverage gate.
• The embedded Business Calculus avatar defaults to the male professor and offers Oliver (cedar, speed 1.02). Speech and live Simli video are opt-in; audio retention is disabled by default. Oliver is presented as an AI teaching persona, not as the real person or a source of real-world claims.
• SIMLI_API_KEY and SMTP passwords stay server-side and never enter HTML, browser state, public variables, logs, receipts, or health output.
• /healthz reports the release/source digest and boolean configuration status without returning credentials, learner identifiers, or answers.
• Tracking schema 1.3.0 is additive: versioned hierarchy nodes/edges, question profiles/members, and immutable instance bindings join to existing attempts and learning signals while account, mastery, recovery, diagnostic, and exam rows remain intact. A missing signal remains no evidence. Historical attempts without trusted profiles are not assigned invented fine-grained evidence.

Configuration

Core secrets are OPENAI_API_KEY, TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, LEARNER_ID_HMAC_SECRET, INSTRUCTOR_EXPORT_SECRET, and SAT_ACT_APP_FERNET_V1_8_18_HFBUILD6_FA5015374498_45CC1E1A0BC7. Live avatar video additionally uses optional SIMLI_API_KEY.

Email recovery uses AUTH_RECOVERY_EMAIL_ENABLED, AUTH_SMTP_HOST, AUTH_SMTP_PORT, AUTH_SMTP_USERNAME, AUTH_SMTP_PASSWORD, AUTH_SMTP_FROM_EMAIL, AUTH_SMTP_STARTTLS, AUTH_SMTP_SSL, and optional AUTH_SMTP_TIMEOUT_SECONDS. Leave email recovery disabled unless the configuration is complete; offline recovery still works.

Release runtime defaults include ACCOUNT_AUTH_ENABLED=1, AUTH_SESSION_RECHECK_SECONDS=30, AUTH_REPLICA_SYNC_SECONDS=5, SAT_ACT_DEMO_MODE_ENABLED=1, SAT_ACT_DEMO_SESSION_TTL_SECONDS=2700, ASK_PROFESSOR_COMPONENT_DEFAULT=1, ASK_PROFESSOR_TTS_DEFAULT=0, and ASK_PROFESSOR_SIMLI_DEFAULT=0. Printable supplemental generation defaults to OPENAI_OVERFLOW_MODEL=gpt-5-mini and OPENAI_OVERFLOW_REVIEW_MODEL=gpt-5-mini; Learning Diagnostic synthesis defaults to OPENAI_DIAGNOSTIC_MODEL=gpt-5-mini. Face IDs, the same-origin packaged Simli client route, and transport settings are listed in environment.example used to prepare this deployment. Remote avatar-client module overrides are intentionally rejected.

Version 1.8.18+hfbuild6 uses immutable item/timing/scoring snapshots and explicit recovery compatibility contracts. Resume only a saved contract that is explicitly supported; legacy checkpoints follow the tested compatibility allowlist. Incompatible work stays blocked and requires an approved transition or learner choice, never silent regeneration/abandonment. Back up only inside the authorized hosting boundary, preserve identity/source keys, and retain current audit/tombstones/holds/revocations. Rollback requires compatible data and a new reviewed release manifest; it cannot restore expired/revoked access or overwrite legitimate new learner work.

The owner kit ships no decryption key or production data. Its first local build creates the matching source key/payload. Deployment defaults to local dry-run; only explicit --execute plus DEPLOY opens remote changes. Python 3.12.13 is the validated application patch. This Space explicitly selects python_version: "3.12.13"; the builder verifies agreement with runtime.txt and the loader. Health verification records the actual interpreter before deployment succeeds.

Acceptance testing for v1.8.18+hfbuild6 must verify the exact Dearmon Analytics paper, ink, blue, teal, and coral palette; compact 1,240-pixel workspace; bundled same-origin Inter, Source Serif 4, and Geist Mono; and one crisp DA gradient rule across the compact chooser and three shadow-free horizontal Practice rails. Practice variation must be collapsed beneath Test Tools. Selecting a lesson must open Question & Your Work, and the answer row must expose grade, same-lesson, and next-lesson actions. Repeated next-lesson actions must advance from the active item even when browser selector values are stale. Linear- equation solution-count explanations must distribute and cancel the actual terms, explain a true identity, and contrast a false-statement no-solution case. Grading must freeze elapsed and target time, show the exact reduced fraction and pace comparison, and flatten the same fields into learner/account and instructor attempt CSVs while legacy rows stay blank. Inline lesson Math and printable exam/key PDFs must use the shared renderer without visible LaTeX commands or dollar delimiters. The collapsed, question-specific Concept swim lane, full analogous worked example, separate active-item hint, and deterministic confused- word surfaces must remain. Near-white mastered topic tiles intentionally retain dark text for WCAG contrast.

Live-avatar acceptance must verify that /_simli/client.mjs returns JavaScript with X-Content-Type-Options: nosniff, contains no API key, and starts without requesting esm.sh. A forced video-start failure must leave text tutoring and spoken replies usable without displaying a raw module-loader exception. The deployed package must retain THIRD_PARTY_NOTICES.md and its manifest hash.

Skill/scoring acceptance must enumerate exactly 1,983 stable authored profiles: 1,832 ordinary deterministic template profiles (including 1,780 objective and 52 ACT Writing essay families), 145 immutable ACT passage-bank items, and 6 dedicated order-of-operations remediation templates. Every profile must resolve all eight levels and its full closure. The 1,925 potentially objective-score- eligible profiles must be distinguishable from the essay and other unscored roles. Verify that SAT pretest and ACT EFT questions do not affect raw scored counts or estimates; ACT Science does not affect the Composite; ACT Writing is returned for human review; and AI supplemental PDF items cannot enter attempts, hierarchy evidence, or scoring. Score output must keep raw counts separate, set official_score=false, expose interval/evidence/confidence fields, and label partial or insufficient data. A completed session must retain the nested estimated_scores object in result_json while its separate raw_score column continues to mean raw accuracy; scoped exports must preserve the disclosure without creating an official-score column.

Schema acceptance must upgrade an earlier database additively to tracking 1.3.0, preserve legacy rows, write one idempotent profile/skill-evidence set with its owning attempt, reject unknown hierarchy IDs, and omit invented skill evidence for pre-profile historical attempts.

Acceptance must also verify that post-explanation follow-ups are hidden before grading and limited to the owning attempt; both diagnostic coverage bars use distinct topics; the report gate requires strict majority coverage in Reading and Math for one exam; OpenAI report requests contain only aggregate allowlisted signals; invalid/provider-failed reports do not unlock anything; and completed reports can be pulled and used to open graduated Guided Examples and separate Targeted Practice.

Progress & Reports must render three mastery wheels for SAT and ACT, retain every curriculum topic including unassessed topics, and keep attempt depth independent from accuracy color. Verify that one correct attempt has a shallower evidence ring than four correct attempts, untouched topics never show 0%, ACT Reading/Language combines English and Reading, exact-data tables remain usable without color or hover, and signed-out/revoked sessions expose no learner aggregates. Practice, completed-simulation and completed-adaptive evidence may count; diagnostic and review attempts must not inflate the dashboard.

Verify that the third wheel and the Skill Taxonomy Graph below the topic graph use cumulative correct/attempted tagged questions. Per-entry score-loss details must include format-specific blind guessing (25% for four-choice questions, no assumed credit for typed answers), while observed accuracy remains raw. The complete catalog download must retain all taxonomy entries, including unavailable estimates, and state that overlapping losses must not be added.

The release builder continues to generate the versioned Fernet key automatically, store it under release/private/, validate it, and reuse it for safe retries without prompting the deployer operator.

Key lifecycle and rollback

The current loader reads only SAT_ACT_APP_FERNET_V1_8_18_HFBUILD6_FA5015374498_45CC1E1A0BC7. A later release must generate a new versioned, fingerprinted secret name. The deployer adds that secret before the repository commit and retains earlier keys. Roll back by reverting the Space repository to the prior commit recorded in deployment_receipt.json. Do not delete an earlier Fernet key until its rollback revision is retired.

Legal notice

This independent practice lab is not affiliated with or endorsed by College Board or ACT, Inc. SAT and ACT are their respective owners' trademarks. The lab contains original practice material only; raw diagnostics and separate practice-score estimates are not official scores.

Adaptive Test and Normal Test

Adaptive Test generates a 10-, 20-, or 30-question SAT/ACT assessment with question-by-question selection and difficulty updates. Evidence-adjusted content weakness is combined with the largest single applicable modeled score opportunity; generic process nodes and overlapping gain sums are excluded. Calibration probes cover selected sections when history is sparse. The full answer review and study priorities appear at completion.

Normal Test · Exam Simulation preserves the standard blueprint, timing, optional ACT sections and SAT module routing. Saved weakness priorities do not alter its assembly. Adaptive samples have a distinct tracking mode and cannot supply a normal scaled score. Completed adaptive attempts do count toward raw cumulative mastery charts and subsequent adaptive selection.

Acceptance must verify ownership/revocation, stale double-submit rejection, no feedback before completion, completion-only attempt/mastery persistence with separate encrypted unfinished-test checkpoints, retry without duplicate attempts, unchanged normal-test assembly, and explicit exclusion of adaptive rows from ordinary scale-score estimates. Authenticated unfinished adaptive state now has encrypted same-version recovery checkpoints. Verify the saved checkpoint boundary, stale revision rejection and remote durability; unsaved browser input is not recovered. The normal-exam recovery path retains its existing version/owner checks.

Diagnostic prerequisite and database upgrade

The diagnostic must be fully completed and saved before adaptive testing unlocks for the same learner and exam. Partial responses, older practice or demo sample history cannot unlock it. Normal testing remains available independently. The latest completed diagnostic seeds adaptive priorities alongside eligible practice history, with its actual item-level guessing adjustment preserved.

Tracking schema 1.5.0 retains additive checkpoint storage and completed learner history. Run repeat-safe migrations and an authorized host-side backup before deployment. Current immutable recovery contracts preserve compatible work across releases; unsupported historical contracts remain blocked for an explicit transition. Keep security decision stores and reviewer revocations independent of database rollback.

Institutional controls and OMES readiness

The institutional profile blocks unapproved student processing and external AI/Simli services. It disables public signup, demos and legacy PIN entry and implements OIDC code/PKCE, explicit MFA assertion checks, provisioned issuer/subject identity, individual staff roles/class scopes and server-side ownership guards. Recovery email requires verified TLS. Accessible chart tables, keyboard improvements and owned diagnostic exports are included; framework analytics remains disabled.

Read the source package's docs/OMES_PLATFORM_READINESS.md, docs/INSTITUTIONAL_IDENTITY.md, docs/SECURITY_IMPLEMENTATION.md and docs/ASSESSMENT_RECOVERY.md. Use deployment/institutional/README.md for a new approved container deployment. The institutional HF updater only updates a preprovisioned approved target with protected roster and persistent storage. Code/configuration does not establish State-approved MFA, completed human accessibility/ACR acceptance, educator signoff on standards alignment, actual U.S. hosting/encryption/backup evidence, signed IT terms or supplier/AI authorization. Run the redacted preflight and obtain the actual applicable external records before covered performance.

Tracking schema is 1.5.0. Authenticated diagnostic/adaptive checkpoints now survive supported same-version restarts; recovery validates the learner, exact release/source compatibility and checkpoint revision. Unsaved browser input is outside that boundary. Production acceptance must separately prove remote durability, restored keys/database and provider backups. Consumer accounts remain available in consumer mode; institutional use requires its own approved OIDC roster and dedicated deployment/database.