config: degrade an unknown enum token per field #316

Merged

natsukium merged 3 commits from config-enum-fallback into main 2026-09-21 15:53:15 +09:00

Conversation 0 Commits 3 Files changed 8 +411 -16

natsukium commented 2026-09-21 13:03:21 +09:00

Owner

Copy link

A closed config enum had no forward-compatible growth rule: one token an older build did not recognize failed the whole merged document and replaced every setting with the built-in defaults, so a file a newer felis wrote lost its font, theme, keymap, and window settings over one presentation option.

An unknown string token now degrades only its own field to that field's documented default and emits a value warning carrying the full key path, client.felis. prefix included when the overlay wrote it. Shape is still checked, so a number or a table where a token belongs stays a structural error, as do syntax errors and structurally unreadable TOML. shader.post degrades at the smallest typed boundary: an unrecognized builtin name or an unknown outer selector leaves the rest of [shader] alone and reports shader.post.builtin or shader.post.

Because the failure became a warning, felis config check reports it at exit 0, startup loads the document instead of falling to defaults, and live reload applies the degraded value rather than keeping the previous state. The generated JSON schema is unchanged apart from a $comment sentence: it keeps enumerating only the tokens this build understands, since editor validation describes the vocabulary in hand while the runtime rule is what carries a file between versions.

Docs: docs/reference/config.md (the additive-schema sentence and two rows in the malformed-value table), a new decision bullet in docs/explanation/architecture/control-surfaces.md "Configuration architecture" recording whole-document rejection as the rejected alternative, and a CHANGELOG entry.

Closes #314

A closed config enum had no forward-compatible growth rule: one token an older build did not recognize failed the whole merged document and replaced every setting with the built-in defaults, so a file a newer felis wrote lost its font, theme, keymap, and window settings over one presentation option. An unknown string token now degrades only its own field to that field's documented default and emits a `value` warning carrying the full key path, `client.felis.` prefix included when the overlay wrote it. Shape is still checked, so a number or a table where a token belongs stays a structural error, as do syntax errors and structurally unreadable TOML. `shader.post` degrades at the smallest typed boundary: an unrecognized `builtin` name or an unknown outer selector leaves the rest of `[shader]` alone and reports `shader.post.builtin` or `shader.post`. Because the failure became a warning, `felis config check` reports it at exit 0, startup loads the document instead of falling to defaults, and live reload applies the degraded value rather than keeping the previous state. The generated JSON schema is unchanged apart from a `$comment` sentence: it keeps enumerating only the tokens this build understands, since editor validation describes the vocabulary in hand while the runtime rule is what carries a file between versions. Docs: `docs/reference/config.md` (the additive-schema sentence and two rows in the malformed-value table), a new decision bullet in `docs/explanation/architecture/control-surfaces.md` "Configuration architecture" recording whole-document rejection as the rejected alternative, and a CHANGELOG entry. Closes #314

natsukium added 1 commit 2026-09-21 13:03:22 +09:00

config: degrade an unknown enum token per field ... f6bf7f32a0

The config reference calls the schema additive and promises a file stays
readable across versions, but a closed enum had no such property: one
unrecognized token failed the whole merged document and replaced every
setting with the built-in defaults. An older build reading a file a newer
felis wrote lost its font, theme, keymap, and window settings over one
presentation option it has no code for, which would make every added
variant a config break needing a flag day.

An unknown string token now degrades only its own field to that field's
documented default and warns with the full key path, overlay spelling
included. Shape is still checked: a number or a table where a token
belongs remains a structural error, as does a syntax error, because no
version of felis accepted those. `shader.post` degrades at the smallest
typed boundary, so an unrecognized `builtin` name leaves the rest of
`[shader]` alone.

Because the failure is now a warning, `felis config check` reports it
without the exit-1 error, startup loads the document instead of falling
to defaults, and live reload applies the degraded value rather than
keeping the previous state. The generated schema keeps enumerating only
the tokens this build understands: editor validation describes the
vocabulary in hand, while the runtime rule is what carries a file
between versions.

Assisted-by: Claude Code

natsukium added 1 commit 2026-09-21 13:16:36 +09:00

config: state field-local enum fallback as a requirement ... c68c746939

The rule that an unknown enum token degrades one field rather than the
document is a compatibility promise a reader needs to find in the
numbered set, not only in the config reference prose, so REQ-1103 names
it and cites the page that commits to it.

The helper's doc comment argued the case over seven lines, past the
five-line ceiling the comment gate enforces: the argument and its
rejected alternative belong in the control-surfaces decision bullet,
leaving the invariant at the site.

Assisted-by: Claude Code

natsukium added 1 commit 2026-09-21 13:26:49 +09:00

docs: bound the enum-fallback rule to fields with a default ... a54f204b0e

"An enum-valued config key" read as every enum in the document, keymap
binding kinds and arguments included, which follow the opposite rule:
a binding has no default to fall back to, so an unrecognized one drops
that entry and the remaining keybindings apply. Naming the six
closed-enum fields that do carry a default keeps the two blast radii
distinguishable, and REQ-1103 now says which rule a keymap binding
takes and cites the page that owns it.

Assisted-by: Claude Code

natsukium merged commit 18234a1f6f into main 2026-09-21 15:53:15 +09:00

natsukium deleted branch config-enum-fallback 2026-09-21 15:53:15 +09:00

natsukium referenced this pull request from a commit 2026-09-21 15:53:17 +09:00

config: degrade an unknown enum token per field (#316)

natsukium referenced this pull request from a commit 2026-09-21 16:13:33 +09:00

Merge origin/main into attach-by-prefix

natsukium referenced this pull request 2026-09-21 21:35:04 +09:00

[v0.1/Tracker] Close release blockers before v0.1.0 #12

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!316

No description provided.