refactor(workspace): remove KV migration machinery

[braden-w]

Simplifies the workspace KV system end-to-end: polishes the schema layer, adds required defaults so get() always returns a typed value, then removes the migration machinery that defaults made unnecessary.

This is Wave 1 of the Whispering workspace polish spec plus two follow-on specs that it unlocked. The three phases built on each other—schema polish exposed that KV defaults were missing, defaults made migration structurally unnecessary, and removing migration was the payoff.

Wave 1 — Schema polish
  │  Break config blobs → individual KVs, flat camelCase schemas,
  │  discriminated unions for run tables, JSDoc on all entries
  │
  ▼
defineKv defaults
  │  Add required defaultValue param, simplify get() → always returns T,
  │  add observeAll(), update all call sites in Whispering
  │
  ▼
Remove KV migration
     Drop variadic overload + migrate field entirely.
     define-kv.ts: 163 → 47 lines.

KV defaults

defineKv(schema) had no concept of a default value. get() returned a discriminated union ({ status: 'valid', value } | { status: 'not_found' } | { status: 'invalid' }) that forced every consumer to handle three cases. For the upcoming settings separation (Wave 2), we need get() to always return a valid T.

// BEFORE: no default, consumers handle three cases
const result = kv.get('sound.manualStart');
if (result.status === 'valid') { /* use result.value */ }

// AFTER: required default, get() always returns T
const value = kv.get('sound.manualStart');
// value: boolean — stored value if valid, default otherwise

The default is never written to Yjs—it would pollute CRDT history and cause initialization races on multi-device sync. Added observeAll() for reactive observation of all KV entries. Updated all 44 defineKv call sites in Whispering to include defaults.

This phase also exposed a real bug: the isSecondArgSchema heuristic used typeof args[1] === 'object' to distinguish schemas from default values, but arktype schemas are functions. The check silently misidentified the second schema as a default value in multi-version definitions.

Remove KV migration machinery

Removes the variadic defineKv(v1, v2, ...).migrate(fn, default) pattern and all migration infrastructure from KV stores. defineKv now has exactly one signature: defineKv(schema, defaultValue).

The variadic pattern had zero production usage across 44 defineKv call sites in Whispering—every single one already used the shorthand. The multi-version overload existed only for test coverage, and the isSecondArgSchema detection heuristic it relied on caused a real bug: arktype schemas are functions, not objects, so typeof args[1] === 'object' silently misidentified the second schema as a default value. More fundamentally, KV stores hold scalar preferences, not accumulated rows. Schema changes either don't break validation (widening an enum) or the default fallback is acceptable (resetting a toggle). Migration is structurally unnecessary for this data lifecycle.

// BEFORE — two overloads, migration identity function on every read
defineKv(schema, defaultValue)          // → { schema, migrate: (v) => v, defaultValue }
defineKv(v1, v2).migrate(fn, default)   // → { schema: union, migrate: fn, defaultValue }

// get() called definition.migrate(result.value) on every read

// AFTER — one function, validate-or-default
defineKv(schema, defaultValue)          // → { schema, defaultValue }

// get() returns result.value directly

BEFORE                                    AFTER
──────                                    ─────

defineKv(schema, default)                 defineKv(schema, default)
  → { schema, migrate: identity, default }  → { schema, default }

defineKv(v1, v2).migrate(fn, default)     (removed)
  → { schema: union, migrate: fn, default }

get(key):                                 get(key):
  raw = ykv.get(key)                        raw = ykv.get(key)
  if missing → default                     if missing → default
  validate(raw)                             validate(raw)
  if invalid → default                     if invalid → default
  migrate(validated) → return               return validated

The type system reflects the simplification. KvDefinition dropped its TVersions tuple generic for a single TSchema, and the migrate field is gone:

// BEFORE
type KvDefinition<TVersions extends readonly CombinedStandardSchema[]> = {
  schema: CombinedStandardSchema<unknown, StandardSchemaV1.InferOutput<TVersions[number]>>;
  migrate: (value: ...) => StandardSchemaV1.InferOutput<LastSchema<TVersions>>;
  defaultValue: StandardSchemaV1.InferOutput<LastSchema<TVersions>>;
};

// AFTER
type KvDefinition<TSchema extends CombinedStandardSchema> = {
  schema: TSchema;
  defaultValue: StandardSchemaV1.InferOutput<TSchema>;
};

InferKvValue simplified from LastSchema indirection to direct extraction. InferKvVersionUnion was removed entirely. LastSchema and createUnionSchema remain untouched—tables still use them.

In create-kv.ts, the parseValue helper (which existed solely to call definition.migrate) was removed. get(), observe(), and observeAll() now return result.value directly after validation. The file went from importing CombinedStandardSchema and KvGetResult (for the helper's type signature) to importing only what it needs.

define-kv.ts went from 163 lines (two overloads, implementation with isSecondArgSchema branching, createUnionSchema import) to 47 lines (one function that returns { schema, defaultValue }).

Six documentation files were updated to replace variadic KV examples with the shorthand pattern. The workspace-api skill file now documents a scalar-per-key convention: use dot-namespaced keys ('theme.mode', 'theme.fontSize') instead of structured objects, which makes migration structurally unnecessary. A seventh doc (inline-single-use-definitions-in-tests.md) was caught in a straggler sweep—its defineKv examples were missing the now-required default value.

All 347 tests pass. Zero production code changes—every Whispering defineKv call was already using the shorthand.

Schema polish

The Whispering workspace definition had structural issues from rapid prototyping: a transcription.config blob KV that should have been individual keys, transformationSteps using a nested discriminated union that could be a flat camelCase schema, and no JSDoc on any table or KV group.

// BEFORE: one blob with mixed concerns
'transcription.config': defineKv(TranscriptionConfig)
// get() returns the whole object; changing one field requires read-modify-write

// AFTER: individual keys with scalar-per-key convention
'transcription.outputLanguage': defineKv(type("string"), 'en')
'transcription.prompt': defineKv(type("string"), '')
'transcription.temperature': defineKv(type("number"), 0)

Also added completion.openrouter.model KV entry and used discriminated unions for transformation run schemas (spec Decision 4).

Why remove instead of deprecate?

Zero production callers. The variadic pattern had test-only usage and had already caused one bug. Deprecation warnings serve callers who need time to migrate; there were none.

Why not add an optional migrate callback?

No production KV entry needs one today. If a genuine case appears, the escape hatch is straightforward: add a new KV key with the new schema and write app-level migration code. Or add { migrate? } as an optional third parameter at that time.

Tables are deliberately different

Tables accumulate rows that must survive schema changes—migration is mandatory. KV stores hold single preferences where resetting to default is acceptable. This PR makes the asymmetry explicit rather than having KV borrow table machinery it doesn't need.