From dadf778f710d40dbbbaaecaa00ac9a6a66ec1a57 Mon Sep 17 00:00:00 2001 From: Alex Southwell Date: Sun, 20 Sep 2026 12:50:29 +1000 Subject: [PATCH 1/2] docs: require acknowledged settings completion --- .../consistency-settings-completion.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/internals/consistency-settings-completion.md diff --git a/docs/internals/consistency-settings-completion.md b/docs/internals/consistency-settings-completion.md new file mode 100644 index 0000000000000..0dee3d173da4c --- /dev/null +++ b/docs/internals/consistency-settings-completion.md @@ -0,0 +1,34 @@ +# Settings completion follows persistence + +Proposed contract, not a ratified maintainer decision: a settings form that says +“Added” or “Saved”, or closes to signal a successful save, must first receive +confirmation from the store that owns the setting. Accepting input or scheduling +an update is not that confirmation. + +[Apple's Feedback guidance](https://developer.apple.com/design/human-interface-guidelines/feedback) +and [Loading guidance](https://developer.apple.com/design/human-interface-guidelines/loading) +support keeping people informed while work proceeds. Here, that means a pending +save prevents duplicate submission; a failed or interrupted save keeps the draft +and provides a retry path. Only confirmed success may clear the form or announce +completion. + +This boundary spans the form, client command, and authoritative persistence. +Awaiting a convenience updater that returns `void` does not cross it. Server-owned +settings require the command's successful receipt for the environment selected at +submission. Closing, reopening, or changing environments must detach the old +completion from the new form; it does not cancel or undo a server write. + +The rule applies to explicit settings completion claims in web, Electron, and +React Native where those forms exist. The additional-provider form and custom-model editors are shared by +web and Electron. Custom-model add and edit retain their drafts until the +environment confirms persistence; removal cleans up local preferences only +after that confirmation. Quiet optimistic preference controls may remain optimistic +when failures are surfaced and effective state reconciles. This contract does +not require modal saves for toggles, change shared-setting synchronization, or +extend to clipboard acknowledgements. + +Observable acceptance cases are delayed success with pending feedback and one +submission; rejection or interruption with retained input and an actionable +error; successful retry; and an old receipt arriving after a form or environment +change without dismissing the current form or announcing its success. A server +receipt confirms persistence, not provider authentication or readiness. From fe7c3755b00d93f2332f2b3e4afc4303a0be5f1e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 27 Sep 2026 09:08:34 +1000 Subject: [PATCH 2/2] docs: define settings persistence acknowledgement --- docs/internals/consistency-settings-completion.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/internals/consistency-settings-completion.md b/docs/internals/consistency-settings-completion.md index 0dee3d173da4c..42da9b8bfb3cd 100644 --- a/docs/internals/consistency-settings-completion.md +++ b/docs/internals/consistency-settings-completion.md @@ -13,7 +13,9 @@ and provides a retry path. Only confirmed success may clear the form or announce completion. This boundary spans the form, client command, and authoritative persistence. -Awaiting a convenience updater that returns `void` does not cross it. Server-owned +A promise, including `Promise`, confirms persistence only if it resolves +after the write succeeds and rejects on failure. Scheduling a write or swallowing +its error does not provide confirmation. Server-owned settings require the command's successful receipt for the environment selected at submission. Closing, reopening, or changing environments must detach the old completion from the new form; it does not cancel or undo a server write. @@ -22,8 +24,10 @@ The rule applies to explicit settings completion claims in web, Electron, and React Native where those forms exist. The additional-provider form and custom-model editors are shared by web and Electron. Custom-model add and edit retain their drafts until the environment confirms persistence; removal cleans up local preferences only -after that confirmation. Quiet optimistic preference controls may remain optimistic -when failures are surfaced and effective state reconciles. This contract does +after that confirmation. Quiet preference controls may update optimistically only +if their callers observe write failures, show an error and reconcile the displayed +value with persisted state. Otherwise they must await persistence. A helper that +logs a failed write and resolves does not qualify for this exception. This contract does not require modal saves for toggles, change shared-setting synchronization, or extend to clipboard acknowledgements.