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.