fix(service-settings): refuse a settings write issued before the engine is bound

.changeset/settings-write-before-engine-bind.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/service-settings": patch
+"@objectstack/spec": patch
+---
+
+**Behaviour change (tightening, boot-time only):** a settings write issued before `SettingsService`'s data engine is bound is now **refused loudly** instead of resolving successfully while nothing reaches `sys_setting` (#10159).
+
+`upsertRow` picks its store on `if (this.engine)`, and the engine is bound in exactly one place — `SettingsServicePlugin` registers a `kernel:ready` hook from its `start()` and calls `bindEngine` inside it. `kernel:ready` handlers run in registration order and every plugin's `init()` runs before any plugin's `start()`, so **every `kernel:ready` hook registered from an `init()` fires inside that window**. A `set()` from there landed in the in-process memory fallback, re-resolved off that same array, and handed the caller a fully resolved value; `sys_setting` received nothing, and neither audit ledger recorded anything (both sinks bind on the same `bindEngine` call). Nothing was logged at any level, because the write did not fail — it succeeded against the wrong store.
+
+**What an operator will now observe.** A write in that window throws `SettingsEngineNotBoundError` — code `SETTINGS_ENGINE_NOT_BOUND`, status **503** — whose message names the window, the reason, and the fix: move the write to `kernel:bootstrapped` (or later), which fires strictly after every `kernel:ready` handler has settled. Previously that same call returned a resolved value and the setting was silently absent after restart.
+
+**Nothing outside the window changes.** The refusal is armed only by the new opt-in `SettingsServiceOptions.engineBindPending`, which `SettingsServicePlugin` sets in `init()` and clears on both branches of its `kernel:ready` hook — by `bindEngine` when `objectql` is present, or by the new `SettingsService.settleWithoutEngine()` when it is not. So:
+
+- a `SettingsService` constructed directly (unit tests, bootstrap, control-plane mock) keeps the in-memory fallback exactly as before — it declares no pending bind, and the guard never arms;
+- a lean kernel with no `objectql` keeps the plugin's deliberate degradation: once its `kernel:ready` hook has established that no engine is coming, writes resolve into the memory fallback again (now with a `warn` saying those values are lost on restart);
+- reads are untouched in every state, so an ordinary boot-time read of a setting still resolves.
+
+No shipped caller wrote settings inside the window, so no existing startup sequence becomes an error.
+
+`SETTINGS_ENGINE_NOT_BOUND` is registered in `ERROR_CODE_LEDGER` per ADR-0112. The status is declared on the error class rather than at an HTTP door because no door can reach it: the window closes at `kernel:ready`, and HTTP servers open their socket at `kernel:listening`, strictly after.

content/docs/references/api/contract.mdx

@@ -27,7 +27,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +283 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +284 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112, #9106) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim (#9934). Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution (#3821) for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -290,6 +290,7 @@ const result = ApiErrorSchema.parse(data);
 * `SCHEDULE_DELETE_FAILED`
 * `SETTINGS_ACTION_FAILED`
 * `SETTINGS_CRYPTO_UNAVAILABLE`
+* `SETTINGS_ENGINE_NOT_BOUND`
 * `SETTINGS_FORBIDDEN`
 * `SETTINGS_LOCKED`
 * `SETTINGS_UNKNOWN_KEY`

content/docs/references/api/error-code-ledger.mdx

@@ -394,6 +394,7 @@ const result = ErrorCode.parse(data);
 * `SCHEDULE_DELETE_FAILED`
 * `SETTINGS_ACTION_FAILED`
 * `SETTINGS_CRYPTO_UNAVAILABLE`
+* `SETTINGS_ENGINE_NOT_BOUND`
 * `SETTINGS_FORBIDDEN`
 * `SETTINGS_LOCKED`
 * `SETTINGS_UNKNOWN_KEY`

packages/services/service-settings/src/index.ts

@@ -41,6 +41,11 @@ export {
  // it. Exported so an in-process caller can branch on the refusal (there is no
  // dedicated wire code for it yet; see the class doc).
  SettingsCryptoUnavailableError,
+ // The pre-bind write refusal. Exported for the same reason: an in-process
+ // caller that runs during boot branches on `code` to tell "too early"
+ // apart from "locked" / "invalid", and the class carries the 503 itself
+ // because no HTTP door can reach it (see the class doc).
+ SettingsEngineNotBoundError,
  SettingsLockedError,
  SettingsValidationError,
  UnknownKeyError,