AhaLoop

AhaLoop turns a learner's worked mistake into competing hypotheses, a discriminating probe, a committed prediction, a manipulable counterexample, and two transfer checks. It closes with the deliberately narrow outcome: “Transfer demonstrated in this session.”

Live app · Production health · Submission package · Implementation plan

AhaLoop is a bounded educational prototype, not a photo solver, open-domain tutor, or service validated for real learner data. Use synthetic work for the public demo.

The product loop

Most answer-first tools can hide the rule that produced a mistake. AhaLoop instead makes that rule testable:

1. Review a consented image or start from one of four pre-verified synthetic samples.
2. Correct the line-by-line transcription.
3. Compare two or three evidence-linked, whitelisted possibilities.
4. Answer one deterministic probe and commit to a prediction.
5. Manipulate an area partition or fraction bar that exposes a bounded counterexample.
6. Explain the result, pass a deterministic concept check, then complete near and changed-representation transfer.
7. Receive a text-only session evidence report.

The interface is artifact-first rather than chat-first. Prediction is locked before reveal, every formula has a linear-text alternative, and verified samples stay available when live analysis or rate limiting is unavailable.

Verified versus live

The two entry paths are intentionally visible and never silently substituted.

• Verified sample: choose any of the four sample cards. Each is synthetic, static, independently revalidated at build time, and labeled “Verified sample — pre-checked; live image analysis is not being used.” No model call is made.
• Live analysis: upload a clear JPEG, PNG, or WebP, inspect the local preview and privacy notice, then explicitly confirm transmission. GPT-5.6 transcribes the image and ranks eligible catalog hypotheses. The learner can edit the transcript before continuing. Live calls are billable and rate-limited.

For a reliable first run, use the square verified sample. For the judged live path, use only the code-generated synthetic image in public/images/sample-math.jpg.

Supported mathematics

Input is deliberately bounded to two through eight nonblank lines, at most 80 characters per line, one variable (x), positive base-10 integers, and polynomials of degree at most two. Exact truth decisions use reduced BigInt rationals rather than floating point.

Family	Accepted parameters	Recognized transformation
Square missing cross terms	1 ≤ a ≤ 9	(x+a)^2 → x^2+a^2
Partial distribution	2 ≤ k ≤ 6, 1 ≤ a ≤ 9	k(x+a) → kx+a
Binomial missing products	1 ≤ a,b ≤ 9	(x+a)(x+b) with x² and ab present but one or both cross-products missing
Componentwise fraction addition	proper addends, denominators ≤12, lcm≤24, correct sum ≤1	p/q+r/s → (p+r)/(q+s)

Generated algebra counterexamples use x ∈ {1,…,6} and transfer constants must differ from the submitted instance.

Explicitly unsupported: negative constants, decimals, mixed numbers, improper input fractions, sums over one, inequalities, equation solving, geometry, calculus, multiple variables, arbitrary symbolic algebra, voice, multilingual input, accounts, durable learner history, and open-ended tutoring. The current wording band is 13_15; the public UI does not collect an age or identity.

Architecture and authority boundary

GPT-5.6 owns only language-and-vision work:

• transcribing visible lines and reporting legibility or unrelated content;
• ranking only the eligible catalog IDs supplied by deterministic code;
• linking rankings to exact transcript quotes; and
• short learner-facing wording plus advisory explanation feedback.

Deterministic TypeScript owns tokenization, parsing, first non-equivalent transformation, family eligibility, exact arithmetic, probes and answer keys, MentalModel, counterexample search, SimulationSpec, every generated counterexample/task formula, concept and transfer tasks, grading, retries, state transitions, and evidence outcomes. GPT-transcribed learner lines remain editable evidence, not mathematical authority. Zod validates every boundary. Renderers accept only independently revalidated typed specs and never inspect model output.

The four samples and live analysis enter the same contracts, reducer, family catalog, renderers, transfer graders, and evidence path.

Privacy lifecycle

1. The selected file stays behind a browser object URL until the learner confirms the privacy screen.
2. The browser re-rasterizes it as a bounded JPEG, applying orientation and removing file metadata and the source filename.
3. The server checks magic bytes, MIME agreement, decoded dimensions, a 24-megapixel ceiling, a 2,560-pixel longest edge, and a 3.5 MB limit; it re-encodes in memory with Sharp.
4. Model calls use store: false. AhaLoop holds image buffers only for validation and analysis, then best-effort zeroes them in finally paths.
5. The response contains no image bytes: only transcript/ranking data plus normalized-image acceptance metadata (MIME and dimensions). Browser image references are dropped; sessionStorage receives only validated text/session state and expires after 24 hours of inactivity.
6. API routes, blob URLs, and data URLs are network-only and excluded from the service-worker cache.
7. Upstash receives only a daily HMAC-SHA-256 request fingerprint—not the raw IP from application code. Production fails closed if rate limiting is unavailable, while verified samples remain usable.

AhaLoop does not save the photo, and store: false disables saved-response retrieval. This does not disable provider operational retention: under OpenAI's default API controls, abuse-monitoring logs may retain customer content for up to 30 days, subject to documented exceptions and approved controls. OpenAI's API retention and data controls still apply.

Local setup

Requirements: Node.js >=24 <25 and pnpm 10.32.1.

pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm dev

Open http://localhost:3000. Verified samples need no provider credentials. Installability and offline behavior are production-only; exercise those with pnpm build followed by pnpm start or pnpm test:pwa.

Server-only environment variables

Variable	Required	Purpose
OPENAI_API_KEY	Live routes	OpenAI Responses API credential
OPENAI_MODEL	Optional	Server-only override; defaults to gpt-5.6-sol
UPSTASH_REDIS_REST_URL	Production live routes	Redis REST endpoint
UPSTASH_REDIS_REST_TOKEN	Production live routes	Redis REST credential
RATE_LIMIT_HMAC_SECRET	Production live routes	Derives opaque daily fingerprints

Never create NEXT_PUBLIC_ variants of these values. Local development can run verified flows without them; deployed model routes fail closed unless the limiter is fully configured.

Quality and release commands

Command	What it checks
pnpm check	ESLint, Prettier, strict TypeScript, Vitest/property tests, Next.js and Serwist production build
pnpm test:e2e	Desktop Chromium, mobile Chromium, and mobile WebKit product flows
pnpm test:e2e:verified	All four verified loops, three repeats, across all three browser projects
pnpm test:a11y	Axe, touch-target, reduced-motion, 200%-zoom, and layout checks
pnpm test:pwa	Production installability, offline fallback, and cache/storage privacy
pnpm test:bundle	Builds the app, then checks the product-route JavaScript gzip budget
pnpm test:gpt-evals	Opt-in, billable 48-fixture synthetic GPT release gate; use a non-production key
pnpm verify:production	Non-billable live health, exact build identity, readiness, no-store, and security headers
pnpm assets:submission:images	Rebuilds the hero composite, architecture PNG, and synthetic live-demo image
pnpm assets:submission:screenshots	Captures the five synthetic/verified submission screenshots

The production verifier requires the expected deployment identity:

PRODUCTION_URL="https://aha-loop.vercel.app" \
EXPECTED_BUILD_SHA="<full-deployed-sha>" \
pnpm verify:production

The complete release gate also includes the explicit E2E, accessibility, PWA, bundle, live-evaluation, production reliability, Lighthouse, and representative-device checks; pnpm check alone is not the full release suite.

Retained verification evidence

• 33 Vitest files, 201 passing tests, and one intentionally skipped opt-in live-evaluation test in the P14 release-candidate preflight.
• Four verified loops passed three times across three Playwright projects (36 repeated flows).
• The safe 48-fixture GPT evaluation summary records 1.0 for normalized target, top-two family, top-one family, unsupported precision, and unsupported recall.
• Production analysis reliability passed 20/20 calls within the 30-second timeout.
• The latest retained Lighthouse mobile report records LCP 1.880 s and CLS 0; an earlier retained first run remains documented as a failure.
• Three physical-device runs record worst INP 120.827 ms, worst simulation input feedback 96.195 ms, and minimum 58 FPS.

Raw and summarized production evidence lives under artifacts/production-performance. These measurements validate the bounded release candidate, not learning effectiveness.

Deployment

Import the repository root into Vercel with the Next.js preset, Node 24, main as the production branch, the frozen pnpm lockfile, and pnpm build. Configure the five server-only variables for Production, establish OpenAI and Upstash spend limits/alerts, then deploy one fixed commit.

Before promotion, run the full local gate, require a green GitHub Actions run, complete all verified flows on the preview, and check /api/health. After promotion, run pnpm verify:production with the exact full deployed SHA and inspect error logs. See the Vercel production deployment runbook for preview, rollback, limiter-aware smoke, and evidence procedures.

The checked-in Vercel configuration uses region iad1, a 35-second function limit, and an application-level 30-second model timeout.

How Codex and GPT-5.6 were used

GPT-5.6 is a narrow runtime component: multimodal transcription, evidence-linked ranking among allowed candidates, and advisory wording. It is never the mathematical authority.

Codex was the build collaborator across the phased implementation: reconciling contracts, implementing the deterministic math/catalog/state boundaries, building tests and browser flows, auditing privacy and accessibility, diagnosing CI and production evidence, and preparing the release and submission package. The entrant retained the product/scope decisions, evaluated tradeoffs, supplied account and billing authorization, performed device measurements, and owns the final license, deployment, recording, /feedback, and submission decisions.

Limitations and claims

• AhaLoop supports exactly four misconception families and two renderer primitives.
• Handwriting outside the bounded grammar may be rejected even when a person could infer it.
• Model ranking can be wrong; the probe and deterministic validators reduce that risk but do not turn one trace into a diagnosis.
• Session transfer is not evidence of durable learning, remediation, or general effectiveness.
• The app is English-only and anonymous, with intentionally no accounts, learner/session database, teacher dashboard, analytics profile, or saved learner history. Upstash is used only for opaque rate-limit counters.
• Offline mode supports verified samples, not live analysis.
• The repository is publicly viewable, but reuse rights remain reserved until the entrant selects and adds a license.

Attribution and research

• Product UI, AhaLoop icon, verified-sample SVGs, synthetic math image, architecture diagram, and screenshots: project-authored.
• Hero background: generated for this submission with OpenAI's built-in image-generation tool on July 19, 2026; exact prompt and provenance are recorded in the submission asset notes.
• Interface icons: Phosphor Icons 2.1.10, MIT license.
• Runtime and tooling include Next.js, React, Tailwind CSS, Zod, KaTeX, Serwist, Sharp, Upstash, and the OpenAI JavaScript SDK.
• Technical references: GPT-5.6, Structured Outputs, and image input.
• Research context: student–AI answer-extraction behavior, LLM-based misconception diagnosis, and digitally enhanced experimentation and conceptual change in mathematics.

The prototype makes no claim that these research sources validate AhaLoop's learning effectiveness.