Skip to content

TimbreCore: the Library, strength, the daily pick, Spell it's check (ADR-0013, ADR-0014) - #66

Open
ChaliceForAuri wants to merge 1 commit into
companion-recordsfrom
timbrecore
Open

ChaliceForAuri wants to merge 1 commit into
companion-recordsfrom
timbrecore

Conversation

@ChaliceForAuri

@ChaliceForAuri ChaliceForAuri commented Oct 19, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #64 (the records). Phase 1–2's engine: the platform-neutral package GDR-0023 decision 4 asked for, born with the Library so nothing moves twice.

What's in TimbreCore

  • The Library (Library, LibraryEntry, LibraryEvent, LibraryMerge, LibrarySync, Profile): one store, five kinds; meaning, example, provenance, tags, and the events strength is derived from. One versioned JSON document in Application Support, written atomically. Merge is a union of events by composed id; forgot is a tombstone. The three UserDefaults lists import once, in order, and stay put for a downgrade.
  • Strength (ADR-0014): retrievability from events with FSRS-4.5's published defaults, never stored. Pass and met are good, fail is again, due is below 0.9, replay is order-independent.
  • The daily pick (GDR-0027): the weakest entry due at the start of the day, else a bundled word from the profile's lists (then the general ones). Deterministic: the same word from midnight to midnight on every device.
  • MetDetector: today's word in the polished text, whole word, case-insensitive, after corrections. Only the fact is recorded.
  • SpellCheck: Spell it's deterministic check, tolerant of letter names, doubles, "capital", hyphens, glued tokens and acronyms. Its one blind spot is documented.
  • Corpora: Fixtures/spell.json (16 cases) and Fixtures/picks.json (8 cases), run by the tests and by timbre-eval --spell / --picks.
  • Moved from TimbreKit with their tests: Correction, Acronym, CorrectionTable, SentenceCapitalizer, Todo/TodoParser/TodoPhrasing.

TimbreKit

Depends on TimbreCore and re-exports it, so the app shell still imports one module and the Xcode project is untouched. VocabularyStore is replaced by the Library behind the same DictationController API (Settings keeps working unchanged), the controller exposes library, and marks today's word met after every dictation and spoken to-do. The harness gains --spell and --picks.

Records and docs

  • ADR-0013 — TimbreCore: the package, and the rule for what goes where.
  • ADR-0014 — Strength is retrievability, derived from events with FSRS-4.5.
  • CLAUDE.md: layout, commands, the Library in the architecture, three conventions. The architecture model makes TimbreCore real. Backstage's JSON regenerated. CI runs the new package's tests.

Verified

  • swift test TimbreCore: 68 tests, TimbreKit: 204 tests (28 moved over). swift-format lint --strict clean.
  • timbre-eval --spell 16/16, --picks 8/8.
  • xcodebuild of the Mac app: BUILD SUCCEEDED, with TimbreCore resolved transitively.
  • gen:architecture validates the model; sync:docs regenerated.

One corpus case changed my mind rather than the code: I had expected a failed drill to bring a word back the next morning. FSRS says a fail is a fresh exposure, so it returns in a few days, sooner than a plain fade. Case 03 records that this is intended, and ADR-0014 says so.

🤖 Generated with Claude Code

@vercel

vercel Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
timbre Ignored Ignored Preview Oct 21, 2026 8:59pm UTC

Request Review

…ADR-0013, ADR-0014)

The platform-neutral package GDR-0023 (decision 4) asked for, created with
the Library so nothing moves twice. Foundation and Observation only, so the
iPhone and the Watch import it too.

- The Library: one store, five kinds (word, acronym, phrase, spelling,
  correction), each entry with meaning, example, provenance, tags and the
  events strength is derived from. One versioned JSON document in
  Application Support, written atomically; LibrarySync is the door sync
  comes through; merge is a union of events with tombstones. The three
  UserDefaults lists are imported once, in order, and left in place.
- Strength is retrievability from events, FSRS-4.5 with its published
  defaults, never stored (ADR-0014). Pass and met are "good", fail is
  "again"; due is below 0.9; replay is order-independent.
- The daily pick (GDR-0027): the weakest entry due at the start of the day,
  else a bundled word for the profile's lists; deterministic and the same
  all day. The met detector marks today's word from polished text.
- Spell it's check: letters heard against the word, tolerant of letter
  names, doubles, "capital", hyphens, glued tokens and acronyms.
- Corpora: Fixtures/spell.json (16 cases) and Fixtures/picks.json
  (8 cases), run by TimbreCoreTests and by timbre-eval --spell / --picks.

TimbreKit depends on TimbreCore and re-exports it; Correction, Acronym,
CorrectionTable, SentenceCapitalizer and the to-do parser moved over with
their tests. VocabularyStore is replaced by the Library behind the same
DictationController API, which also exposes the Library and marks today's
word met after every dictation and spoken to-do.

CI runs the new package's tests; CLAUDE.md and the architecture model
describe the split; Backstage's JSON is regenerated.

Core: 68 tests. Kit: 204 tests. Lint clean. The Mac app builds.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant