# BrainForge 2 — acquisition, repair and retention

BrainForge specializes in initial encoding → recall → weakness detection → moving on → measurable delayed retention. Anki remains the long-term SRS. All 1,864 canonical entries and stable IDs remain intact.

## Run / verify

`npm test` includes curriculum/grading regressions, DOM controls and acquisition/analytics tests. `npm run build` regenerates site assets; generated vocabulary is unchanged by this upgrade. Serve the repository with `python -m http.server 8765` and open `/brainforge/`.

## Learning model

- Acquisition starts with a configurable batch (default five). After three attempts another unseen word can enter even while earlier words are unfinished. Unseen words also fill spacing gaps.
- Three cumulative misses flag difficulty. Five misses or sixteen attempts automatically park a word. These budgets count since the last explicit force-retry. Full historical counts never reset.
- Skip is temporary; park removes the word from the active queue. Force retry explicitly resets its attempt budget. Known is a personal preference, never recall evidence. Post-session unpark opens that item in Repair.
- Recognition and production are explicit direction settings; mixed acquisition checks both. Repair selects only weak items. Diagnostics and delayed checks have one cold attempt per sampled item, no introductions or hints, and no automatic repeat of misses.
- A session ends once all selected items have completed their checks or been parked/marked known. It can also be ended with Finish & assess. “Studied” requires configurable cold accuracy and tested-item coverage (default 80%); clean pass uses 90%. Insufficient cold evidence is labelled Mastery unknown. Otherwise the session needs repair. These are acquisition decisions, not mastery claims.
- Session history offers random samples of up to 12 introduced items at 15 minutes, 2 hours, next day and 3 days. Checkpoints are linked to their original session and actual elapsed time is exported. Direction-matched baseline results identify decay/strengthening; unmatched items explicitly have no baseline. A small sample is not a census of the unit. Other practice between checkpoints is not controlled experimentally.

## Controls / grading

Space continues introductions and feedback. Enter submits answers and still activates focused buttons. Outside editable fields: C correct, H hard, D wrong/don’t know, S override, P park, X skip, U/left previous, K known, I hint, Escape pause. All typing spaces, browser shortcuts and native IME composition stay native.

Previous restores the one-card learning projection while retaining the original raw event. Backtrack, original grade, correction reopening and applied correction are appended with timestamps and reasons. Raw answers remain in submission events unless optional telemetry is disabled. Manual grading never teaches a new dictionary alias.

The deterministic checker handles articles, punctuation, reviewed synonyms, simple equivalent phrasing, and optional brackets. It does not claim arbitrary semantic understanding; unsupported valid synonyms can be overridden. Romaji has a live kana preview and accepts doubled consonants, long vowels, punctuation and native kana/kanji. Kana/romaji distinctions such as missing long vowels remain meaningful.

## Data contract

`acquisition.js` separates raw append-only events, effective recall projections, derived item metrics and session summaries. A session captures app/algorithm/grading/content/config/schema versions and its actual configuration. Existing legacy events are copied without inventing missing timestamps or latency. Existing session content is not refiltered on reload.

Raw events include session/event/item identity, local and UTC timestamps with UTC offset, sequence and item order, prompt/target, introduction, hint, submission, grade overrides, recall, skip/park/unpark/retry/known, corrections, interruption and self-report events. Submission timing captures prompt appearance, first input and submission, thinking delay, typing duration, latency, edits and backspaces. Recall events reference the submission ID and contain stages/failures before and after. Item metadata is embedded, so later content changes do not erase what was tested.

JSON exports include metadata, original raw events, effective recalls, item metadata, derived metrics and retention comparisons. CSV export downloads six tables: events, session, item metrics, item metadata, timeline and retention. CSV cells are quoted and spreadsheet formulas escaped; JSON is the exact raw interchange format. Browsers may ask to allow multiple CSV downloads.

Metrics include cold/practice/directional accuracy, per-item first success, failures, recovery, latency and session-check completion, idle/active time, attempts/item, throughput, failure concentration and recall-time share of the five hardest items. Minute-by-minute accuracy and latency are exported and shown. Difficulty is an observed failure fraction, explicitly a product heuristic. No invented memory-strength or psychological fatigue score is shown. Latency is wall-clock response latency; it can include interruption time. “Active time” excludes whole inactivity gaps of 30 seconds or more; it is a behavioral estimate, not measured cognition. Ratios return null when unmeasured, not zero.

Mental effort, fatigue, boredom, confidence, difficulty and notes are optional end-of-session self-reports. No biometrics are collected. The included Unit 14 baseline test is synthetic arithmetic validation; the actual historical session has not been supplied and is not fabricated.

## Persistence / privacy

`tabicuts.brainforge.v1` remains backward compatible. Sessions are archived instead of discarded. Export/import includes archives; validation checks their event history. Revision guards stop stale tabs from overwriting a newer save. Corrupt saves and quota errors remain visible and exportable. Raw history is never truncated to save space. LocalStorage is finite: export regularly; large histories may reach browser quota and the UI then warns instead of claiming a successful save.

Optional telemetry applies to newly created sessions. When disabled, raw answers, normalized answers, accepted-synonym text, input timings/edits and device metadata are omitted from event exports; learning grades and timestamps remain. Current drafts/feedback still exist as necessary resume state until committed. Existing rich sessions are retained until explicitly deleted. Reset downloads a backup before clearing local data. No third-party analytics scripts are used.

## Optional accounts — deployment setup required

`sync.js` implements Supabase email-link authentication, refresh, progress download, automatic saves after a device connects, sign-out, and deletion of cloud learning data. A database compare-and-swap revision rejects stale-device writes. It deliberately does not silently merge divergent progress. On conflict, both copies remain available; export the local copy before downloading cloud progress. Signing in does not automatically upload a device’s existing study history: Sync now connects it explicitly. Reconnect with Sync now after reload.

To activate:

1. Create a Supabase project and run `account-schema.sql`. RLS permits authenticated users to read/delete only their own row; writes use the authenticated revision-checked function.
2. Enable email-link auth and allow `https://tabicuts.com/brainforge/` as the redirect URL.
3. Put the HTTPS project URL and **public anonymous key only** in `account-config.json`. Never include a service-role key.
4. Verify sign-in, refresh, two-device conflict handling, export and cloud-data deletion against that real project before announcing account availability.

The supplied config is intentionally blank: no project or credentials were supplied. Accounts/cloud sync therefore remain inactive. The identity account itself is managed by the identity provider; the app’s delete button deletes learning data, not the identity account.

Official references: [email-link authentication](https://supabase.com/docs/guides/auth/auth-email-passwordless), [row-level security](https://supabase.com/docs/guides/database/postgres/row-level-security).

## Limits

The current storage is browser JSON plus the optional account snapshot adapter, not a warehouse. It preserves raw history but is not designed for unlimited years of events without moving storage to IndexedDB/server event tables. Per-item interference candidates are a schema field; automatically inferring confused word pairs is not implemented. No automatic experiments, Parquet export, statistically validated stability model or automated optimal-schedule recommendation is claimed. Configuration is stored to support later analysis in Python/Jupyter.


## Session difficult words (v1)

Choose Free Practice, select Units 16, 17 and 18 (or any units), and practice.
Use **Hard** for effortful recall and **Don't know** for failures. Finish the round
whenever you want. **Difficult words from this session** lists every word that
struggled, ranked with persistent difficulties first. Export its JSON or CSV for
mnemonics and memory-palace work; full session JSON includes `weakWords` too.
A later correct answer does not erase an earlier struggle. Unanswered words are
not failures. Typing time alone does not make a word weak.

Persistent means at least two unaided failures, three struggling attempts,
parking, or an explicit difficulty reason. A single failure/Hard/hinted recall is
kept as `watch`. The export includes stable card and session IDs, unit, reading,
meaning, counts, affected facets, reasons and whether the word recovered in the
session. These are session observations, not a mastery claim.

Free Practice now uploads immutable evidence as `manual_practice` in a `manual`
session. It creates no first-check actions and never advances FSRS. It retains
the one-answer undo boundary. Saved rounds and upload IDs retry after reload or
**Sync now**; pending/rejected evidence is not described as synced. Cloud storage
still requires the existing learning-data consent. Offline exports work locally.
The cloud ZIP additionally includes `session-weak-words.json`.

Mari-san can read `public.session_weak_words` directly through Supabase, filtering
by account, session and/or unit. This invoker-security view uses the existing RLS,
excludes superseded grading events, and derives rows from review/action evidence.
`session_status`, `expected_events` and `received_events` show completeness.
Query the latest matching session first rather than mixing every historical round:

```sql
select w.* from public.session_weak_words w
where w.user_id = :user_id and w.session_id = :session_id
  and w.unit in (16,17,18)
order by w.severity, w.struggles desc, w.failures desc, w.card_id;
```

Security advisors checked after the migration: the new view has no advisor
finding. Existing notices concern server-only private tables with no policies,
the intentional private-alpha allowlist helper, and disabled leaked-password
protection. No unrelated access policies or authentication settings were changed.