@voltro/plugin-flags 0.85.0 → 0.87.0

package/README.md

@@ -24,3 +24,109 @@ deliberately short so there is nothing here to drift out of date.
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+
+## Typed Remote Config
+
+`defineConfig` is an optional `flagsPlugin` extension. Its declared bounds are
+budgets. Config editing, automatic Room delivery and a full LiveOps lifecycle
+remain open.
+
+```ts
+// lib/public-game-config.ts — browser-safe public declarations only
+import { Schema } from 'effect'
+import { defineConfig } from '@voltro/plugin-flags/config'
+
+export const publicConfigSpec = {
+  'xp.multiplier': { schema: Schema.Number, default: 1, min: 0.5, max: 5, public: true },
+  'shop.featured': { schema: Schema.Array(Schema.String), default: [], public: true, restartRequired: 'live' },
+} as const
+export const publicGameConfig = defineConfig(publicConfigSpec)
+```
+
+```ts
+// app.config.ts — server only
+import { Schema } from 'effect'
+import { flagsPlugin } from '@voltro/plugin-flags'
+import { defineConfig } from '@voltro/plugin-flags/config'
+import { publicConfigSpec } from './lib/public-game-config'
+
+export const gameConfig = defineConfig({
+  ...publicConfigSpec,
+  'arena.maxPlayers': { schema: Schema.Int, default: 32, min: 1, max: 256, restartRequired: 'room' },
+})
+export const plugins = [flagsPlugin({ config: gameConfig, store: 'postgres' })]
+```
+
+`store:'postgres'` names the existing durable Flag tier; it borrows the app
+DataStore and its SQL dialect. No separate pool or Config table is created.
+Validated rows in `_voltro_feature_flags` replace the code definition whole.
+Invalid values, targeting, schedules or bounds refuse the entire override and
+retain the code definition. Error and inspect responses omit rejected values.
+SQL is the override truth and rebuild source; no direct backend or tick read is
+introduced.
+
+Each key declares an Effect Schema and a typed default. Numeric `min`/`max`
+refine that schema. `variants`, `targeting`, `rollout`, `rolloutBy` and `schedule`
+reuse Flag targeting and deterministic bucketing. A disabled, excluded or
+out-of-window Config resolves to its declared default. Keys are private by
+default; only `public:true` keys reach the caller-bound `config.mine` query.
+Existing Flag evaluation, variant queries, lifecycle rows and boolean toggles
+omit Config keys. A Config key cannot be edited through the boolean toggle.
+
+```ts
+// server handler — read before Room creation, never from its tick
+import { Effect } from 'effect'
+import { ConfigPort, configValue } from '@voltro/plugin-flags/config-port'
+import { gameConfig } from './app.config'
+
+export const readRoomConfig = (subject: { id: string; tenantId?: string; type?: string }) =>
+  Effect.gen(function* () {
+    const config = yield* ConfigPort
+    const multiplier = yield* configValue(gameConfig, config, 'xp.multiplier', subject)
+    const snapshot = yield* config.snapshot(subject, 'room')
+    return { multiplier, snapshot }
+  })
+```
+
+The complete read port is `get(key,subject)`, `mine(subject)` and
+`snapshot(subject,'room'|'live')`. `room` is the default application scope;
+`live` is explicit. A snapshot uses one time and one merged definition set.
+The app passes it during creation or through an explicit message outside the
+tick. Declaring a scope does not install Room delivery. Escaped effects from a
+released activation refuse reads; another Flag instance does not replace this
+instance's Config snapshot.
+
+```tsx
+import { useConfig } from '@voltro/plugin-flags/web'
+import { publicGameConfig } from '../lib/public-game-config'
+
+export function FeaturedItems() {
+  const items = useConfig(publicGameConfig, 'shop.featured')
+  return <ul>{items.map(item => <li key={item}>{item}</li>)}</ul>
+}
+```
+
+The web hook accepts only explicitly public keys and uses the validated default
+while no valid response exists. Import a browser-safe catalog that contains no
+private values; server-only declarations must stay outside web imports.
+
+`configResolver` overrides the pure resolution slot and requires a named
+`configVersion` other than `default.v1`. `configService` replaces all three port
+methods, preserves class receivers and requires the same version plus explicit
+`configQuerySources` (an empty list means an app-owned static view). Resolver and
+complete port replacement cannot be combined. Replacement owns its storage,
+privacy and invalidation sources; it borrows no default persistence behavior.
+Returned keys and values still obey the declared public/snapshot schema.
+
+The value and override capture budget is 16,384 encoded JSON bytes, 4,096 nodes,
+16 nesting levels, 1,024 array entries and 256 object properties; keys are bounded
+to 120 characters and catalogs to 128 keys. Override metadata counts toward the
+byte budget too. Non-finite numbers, cycles, accessors, non-JSON objects and
+unbounded input refuse. These are configured limits, not measured capacities.
+Config contributes no new subject table. App-owned replacement privacy remains
+its owner's responsibility; existing Flag audit/usage retention is independent.
+
+Local and Cloud Flags panels show key/type/public/scope/bounds/version/ownership
+through the same canonical inspect schema. They never show resolved values,
+subjects or rejected payloads, and distinguish the remaining editor/delivery
+work.