feat(spec,service-settings): ADR-0128 anchors, the stage-1 changeset, and the versioned-handle label on the contract

The contract's third provider obligation is labelled for what it is: the
versioned handle ADR-0128 section 4 calls for, with D3 (no fallback, the fix
at the producer of the AAD) named on the no-second-try sentence.

ADR-0128 anchors for the contract and for LocalCryptoProvider, so the scoped,
length-prefixed, versioned derivation cannot be "simplified" back into a join
without the gate naming the record.

One changeset: spec and service-settings minor with the BREAKING banner (the
keyedDigest precedent's level and header), objectql and service-datasource
patch (each passes its own scope; no public surface moves).

Claude-Session: https://claude.ai/code/session_01YDt3PzwfrkuFzUBF89WPmM
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/21326-crypto-context-scope-discriminant.md

@@ -0,0 +1,54 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-settings': minor
+'@objectstack/objectql': patch
+'@objectstack/service-datasource': patch
+---
+
+feat(spec): `CryptoContext` gains a required `scope` discriminant, and `LocalCryptoProvider` binds it into a delimiter-safe, versioned AAD (ADR-0128 D1–D3, #21326 stage 1)
+
+Clause-②: yes
+
+**BREAKING** for `ICryptoProvider` implementers and for every direct caller of
+`encrypt`, `decrypt` or `rotateKey`: `CryptoContext.scope` is required, so a
+context literal without it stops compiling (`TS2741`), and the compiler names the
+missing member. `LocalCryptoProvider` also refuses such a context at runtime with
+`CryptoContextScopeError`, for a caller the compiler never saw. Code that only
+injects a provider is unaffected.
+
+`scope` is a member of the new closed set `CRYPTO_CONTEXT_SCOPES` (type
+`CryptoContextScope`), one member per producer of `CryptoContext`:
+`settings` (`SettingsService`), `object_secret_field` (the ObjectQL engine's
+secret-field path) and `datasource_credential` (the datasource secret binder).
+Each producer in this release passes its own member on every call. A new producer
+adds its own member; it never borrows an existing one.
+
+What the contract now requires of every provider that binds AAD:
+
+- **Producer-discriminated (D1).** The AAD binds `(scope, namespace, key)`, so a
+  ciphertext sealed by one producer does not authenticate under another
+  producer's context, whatever the two `(namespace, key)` pairs are.
+- **Delimiter-safe (D2).** Distinct triples produce distinct AAD bytes. An
+  unescaped join is not permitted.
+- **Versioned.** A ciphertext records which AAD derivation sealed it, and is
+  opened only with that derivation. An unknown derivation fails closed. No second
+  derivation or scope is ever tried after a failure (D3).
+
+`LocalCryptoProvider` seals every new value under derivation version 2: a lead
+byte that never occurs in UTF-8, a versioned label, then the scope, namespace and
+key, each prefixed with its 4-byte length. The ciphertext carries a `v2:` marker.
+A ciphertext with no marker is version 1, the bare base64 every earlier release
+sealed, and it still opens with the older `(namespace, key)` binding. Existing
+secrets therefore keep working with no action, and carry the older binding until
+they are re-wrapped. Re-wrapping existing ciphertext at rest is stage 2 of
+#21326. `rotateKey` already re-seals a version-1 handle under version 2. Any other
+marker is refused with `UnknownCiphertextVersionError`.
+
+Operational note: a secret set or rotated by this release carries the `v2:`
+marker, and an earlier release cannot open it. A rollback past this release needs
+those values to be set again.
+
+`@objectstack/objectql` and `@objectstack/service-datasource` pass their own
+scope on every seal and open. Their public surface is unchanged.
+
+<!-- adr-0087: not-required (no-migration-prescription) `CryptoContext` and `ICryptoProvider` are TypeScript contracts with no metadata surface: no Zod schema, no authorable key, no export renamed or removed, and no stored row changes shape (`sys_secret.ciphertext` is provider-defined, and every existing ciphertext still opens), so `objectstack migrate meta` has nothing to rewrite. The affected party is a provider implementer or a direct caller, and the compiler names the missing member at their call site. -->

packages/spec/src/contracts/crypto-provider.ts

@@ -143,12 +143,14 @@ export type CryptoContextScope = (typeof CRYPTO_CONTEXT_SCOPES)[number];
  *     or a canonical structured encoding. ⛔ Never an unescaped join:
  *     neither a settings specifier key nor a caller-supplied datasource
  *     namespace is barred from containing any separator.
- *  3. **Record its derivation in what it seals** (D3). A provider whose AAD
- *     derivation changes records, in the ciphertext it returns, which
- *     derivation sealed it. `decrypt` and `rotateKey` open a ciphertext with
- *     the derivation it records, and refuse — fail closed — one whose
- *     derivation they do not know. ⛔ Never try a second derivation, or a
- *     second scope, after one fails: the record decides, nothing is guessed.
+ *  3. **Record its derivation in what it seals** (§4's versioned handle). A
+ *     provider whose AAD derivation changes records, in the ciphertext it
+ *     returns, which derivation sealed it. `decrypt` and `rotateKey` open a
+ *     ciphertext with the derivation it records, and refuse — fail closed —
+ *     one whose derivation they do not know. ⛔ Never try a second
+ *     derivation, or a second scope, after one fails (D3: the fix lives at
+ *     the producer of the AAD, never in a fallback): the record decides,
+ *     nothing is guessed.
  *
  * ⚠️ **What it does not cover yet.** A ciphertext sealed before its
  * provider adopted the scope (for `LocalCryptoProvider`: every handle whose

scripts/adr-anchors/packages__services__service-settings__src__local-crypto-provider.ts.json

@@ -0,0 +1,7 @@
+{
+  "file": "packages/services/service-settings/src/local-crypto-provider.ts",
+  "adrs": [
+    "ADR-0128"
+  ],
+  "invariant": "Every seal is AAD derivation version 2: a 0xFF lead byte, a versioned label, then scope, namespace and key each length-prefixed, marked `v2:` on the ciphertext. A ciphertext with no marker is version 1 (the bare base64 every earlier release sealed), opened read-only with the old namespace-and-key derivation; any other marker is refused, fail closed. `decrypt` dispatches on the recorded marker and never tries a second derivation; a context without a member of the closed scope set is refused, never defaulted (ADR-0128 D1-D3)."
+}

scripts/adr-anchors/packages__spec__src__contracts__crypto-provider.ts.json

@@ -0,0 +1,7 @@
+{
+  "file": "packages/spec/src/contracts/crypto-provider.ts",
+  "adrs": [
+    "ADR-0128"
+  ],
+  "invariant": "`CryptoContext.scope` is REQUIRED and drawn from the closed `CRYPTO_CONTEXT_SCOPES` set, one member per producer of `CryptoContext`; a new producer adds its own member and never borrows one. Every provider that binds AAD folds the scope in, encodes the triple delimiter-safely (never an unescaped join), records in what it seals which derivation sealed it, and opens only with the recorded derivation — an unknown one fails closed, and no second derivation or scope is ever tried (ADR-0128 D1-D3)."
+}