fix: bootstrap user preferences without invalidating DWH cache

2026-07-16 20:32:20 +02:00
parent ccb3cf4aa9
commit 5cacf70a0d
6 changed files with 242 additions and 3 deletions
@@ -0,0 +1,34 @@
+# User preference bootstrap design
+
+## Problem
+
+The user-owned-session branch reads settings only from the current principal's
+repository preferences. Existing deployments still have their provider, model,
+thinking level, and workspace only in the legacy backend settings JSON file.
+For a principal with no private preference record, a new session is therefore
+created without a provider or model and Pi is rejected before it can spawn.
+
+## Decision
+
+On the first settings read for a principal whose private preference object is
+empty, the backend computes the complete effective legacy settings from
+`SETTINGS_FILE` and the configured environment defaults, writes that complete
+object to the principal's repository preferences, and returns it.
+
+After this one-time bootstrap, the private preference object is the sole
+source for that principal. A non-empty private object is never replaced with
+the legacy values. If either reading or writing the private preferences fails,
+the request remains fail-closed with the existing 503 response.
+
+The addition of optional session storage must not change DWH artifact
+ownership. The DWH binding therefore excludes `session_storage` while retaining
+every schema, retrieval, vector, and execution setting in its fingerprint.
+
+## Scope and verification
+
+The change is confined to the backend settings resolver. Vitest coverage must
+prove that an empty private profile is seeded exactly once with the complete
+legacy settings, and that an existing private profile is neither changed nor
+replaced. Harness coverage must also prove that adding session storage leaves
+the DWH binding unchanged. Existing session-route coverage continues to prove
+that new-session creation consumes the resolved settings.