@voltro/plugin-flags 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,10 +1,118 @@
 import { ColumnBuilder } from '@voltro/database';
+import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
 import { FieldDefinitions } from '@voltro/database';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+/** `TypedFlag` with the value type erased — what the plugin and the registry
+ *  hold. Sound because `TypedFlag` is covariant in `A` (see the annotation). */
+export declare type AnyTypedFlag = TypedFlag<unknown>;
+
+/**
+ * The boot-time form: throw with every problem at once.
+ *
+ * Loud and at CONSTRUCTION rather than a warning at first evaluation, because
+ * the failure this prevents produces a number an operator will act on. An
+ * experiment reporting the wrong split is worse than one reporting nothing.
+ */
+export declare const assertFlagExperimentLinks: (flags: ReadonlyArray<AnyTypedFlag>, experiments: ReadonlyArray<LinkedExperimentLike>) => void;
+
+declare interface BufferEntry {
+    readonly flag: string;
+    readonly source: FlagUsageSource;
+    lastAt: number;
+}
+
+/**
+ * Check every typed flag that names an experiment against the experiments the
+ * app declared. Pure — returns the problems rather than throwing, so the same
+ * rules are unit-testable and the caller decides the cost.
+ */
+export declare const checkFlagExperimentLinks: (flags: ReadonlyArray<AnyTypedFlag>, experiments: ReadonlyArray<LinkedExperimentLike>) => ReadonlyArray<FlagExperimentLinkProblem>;
+
+/**
+ * Classify a flag from its definition alone. Pure, total, and independent of
+ * every observation — this is the half that is a proof.
+ */
+export declare const classifyShape: (value: FlagValue, now: number) => {
+    readonly shape: FlagShape;
+    readonly reason: string;
+};
+
+/** Adapt the framework `DataStore` to a {@link FlagUsageStore}. */
+export declare const dataStoreFlagUsageStore: (store: DataStore) => FlagUsageStore;
+
+/** Default flush interval. Five minutes rather than one: the report's
+ *  resolution is a DAY, so a tighter interval buys nothing and costs one write
+ *  per active flag per replica. */
+export declare const DEFAULT_FLAG_USAGE_FLUSH_MS = 300000;
+
+/**
+ * Declare a flag with a value type.
+ *
+ * ```ts
+ * // apps/api/lib/flags.ts — browser-safe, imported by app.config.ts AND by the UI
+ * import { Schema } from 'effect'
+ * import { defineFlag } from '@voltro/plugin-flags'
+ *
+ * export const checkoutButton = defineFlag({
+ *   key: 'checkout.button',
+ *   value: Schema.Literal('blue', 'green'),
+ *   default: 'blue',
+ *   variants: [{ name: 'control', value: 'blue' }, { name: 'green', value: 'green' }],
+ *   experiment: 'checkout-button-color',
+ * })
+ *
+ * export const pageSize = defineFlag({
+ *   key: 'search.pageSize',
+ *   value: Schema.Number,
+ *   default: 20,
+ * // default: 'twenty',   ← Type 'string' is not assignable to type 'number'
+ * })
+ * ```
+ *
+ * Validation that CANNOT wait for a type error runs here, at declaration, so a
+ * malformed flag fails at import rather than at the first evaluation:
+ * a duplicate variant name, an `offVariant` naming no variant, a non-positive
+ * weight, a rollout outside 0..100.
+ */
+export declare const defineFlag: <S extends Schema.Schema.AnyNoContext>(spec: DefineFlagSpec<S>) => TypedFlag<Schema.Schema.Type<S>>;
+
+export declare interface DefineFlagSpec<S extends Schema.Schema.AnyNoContext> {
+    /** The flag key — `dotted.camelCase`, matching the `flags: { … }` record. */
+    readonly key: string;
+    /** The value Schema. Everything else in this spec is checked against it. */
+    readonly value: S;
+    /**
+     * The value served when the flag does not resolve to a variant.
+     *
+     * A wrong value here is a COMPILE ERROR. `NoInfer` is one of three reasons
+     * why and, measured, the redundant one — see the header for the other two and
+     * for why it is kept anyway.
+     */
+    readonly default: NoInfer<Schema.Schema.Type<S>>;
+    /** The value arms, each checked against the Schema. */
+    readonly variants?: ReadonlyArray<TypedFlagVariant<NoInfer<Schema.Schema.Type<S>>>>;
+    /** Variant name treated as the "off" state for boolean resolution. */
+    readonly offVariant?: string;
+    /** Master switch. `false` ⇒ off for everyone. Default true. */
+    readonly enabled?: boolean;
+    /** Percentage rollout 0..100. Omit ⇒ 100. */
+    readonly rollout?: number;
+    /** OR-of-rules targeting. */
+    readonly targeting?: ReadonlyArray<FlagTargetingRule>;
+    /** Bucket on the tenant id instead of the subject id. */
+    readonly rolloutBy?: 'subject' | 'tenant';
+    /** Time-boxed / ramping schedule. */
+    readonly schedule?: FlagSchedule;
+    /** Surfaced in the dashboard. */
+    readonly description?: string;
+    /** IN-11 — the `defineExperiment` name this flag's arms report uplift for. */
+    readonly experiment?: string;
+}
+
 /** Convert a resolved flag to a dashboard/inspect row. Surfaces the variant
  *  names + a `scheduled` flag so the panel can badge multivariate / time-boxed
  *  flags without re-deriving the definition. */
@@ -73,6 +181,12 @@ export declare const featureFlagsTable: Table<"_voltro_feature_flags", FieldDefi
     readonly updatedAt: ColumnBuilder<Date, "timestamp", true>;
 }>, true, never>;
 
+/** What the report structurally cannot see. Shipped in the payload. */
+export declare const FLAG_LIFECYCLE_LIMITS: ReadonlyArray<string>;
+
+/** The observation table name. */
+export declare const FLAG_USAGE_TABLE = "_voltro_feature_flag_usage";
+
 /** One kill-switch audit row (who flipped what, when, old→new). */
 export declare interface FlagAuditRow {
     readonly flag: string;
@@ -97,6 +211,17 @@ export declare const flagAuditTable: Table<"_voltro_feature_flag_audit", FieldDe
     readonly at: ColumnBuilder<Date, "timestamp", true>;
 }>, true, "byFlagAuditFlag" | "byFlagAuditAt">;
 
+/** The result of decoding an UNTRUSTED value (a DB override, a dashboard edit)
+ *  against a flag's Schema. Deliberately not an exception: the caller's correct
+ *  response is to keep the code-declared value and say so, not to unwind. */
+export declare type FlagDecodeResult<A> = {
+    readonly ok: true;
+    readonly value: A;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
 export declare interface FlagDefinition {
     /** Master switch. `false` → off for everyone regardless of rollout/targeting. Default true. */
     readonly enabled?: boolean;
@@ -135,6 +260,70 @@ declare const FlagDisabled_base: Schema.TaggedErrorClass<FlagDisabled, "FlagDisa
     flag: typeof Schema.String;
 }>;
 
+export declare interface FlagExperimentLinkProblem {
+    readonly flag: string;
+    readonly experiment: string;
+    readonly problem: string;
+}
+
+export declare interface FlagLifecycleFinding {
+    readonly key: string;
+    readonly shape: FlagShape;
+    /** Plain-language reason for `shape`, quoting the fields that decided it. */
+    readonly shapeReason: string;
+    readonly usage: FlagUsageVerdict;
+    /** ISO instant of the newest TARGETED evaluation in the window, or null. */
+    readonly lastTargetedAt: string | null;
+    /** ISO instant of the newest BULK delivery in the window, or null. A flag
+     *  that only ever appears here is one a client was HANDED, not one a client
+     *  was measured reading. */
+    readonly lastBulkAt: string | null;
+    /** Targeted evaluations seen by THIS process since it started. Not persisted
+     *  and not summed across replicas — a live pulse, not a total. */
+    readonly liveTargetedEvaluations: number;
+    /**
+     * True only when something here is PROVEN: a constant/expired shape, or a
+     * `stale` usage verdict over a sufficient window. `neverObserved` never sets
+     * it, because a flag declared yesterday looks exactly the same.
+     */
+    readonly removalCandidate: boolean;
+    /** The evidence, in the order it was applied. */
+    readonly why: ReadonlyArray<string>;
+}
+
+export declare interface FlagLifecycleInput {
+    /** The live flag set — the same record the registry holds. */
+    readonly flags: Record<string, FlagValue>;
+    /** Persisted observations. Empty is meaningful (nothing observed yet), which
+     *  is why `tracking` is a separate input rather than inferred from length. */
+    readonly usage: ReadonlyArray<FlagUsageRow>;
+    /** Is recording on? `false` ⇒ every verdict is `untracked`. */
+    readonly tracking: boolean;
+    /** Targeted evaluations seen by this process, per flag. */
+    readonly liveCounts?: ReadonlyMap<string, number>;
+    /** A flag with no targeted evaluation in this many days is `stale`. */
+    readonly staleAfterDays: number;
+    /** The observation retention TTL, in days. The window ceiling. */
+    readonly retentionDays: number;
+    readonly now?: number;
+}
+
+export declare interface FlagLifecycleReport {
+    readonly coverage: FlagUsageCoverage;
+    readonly findings: ReadonlyArray<FlagLifecycleFinding>;
+    /** What this report structurally cannot see. Shipped WITH the data, not in a
+     *  docs page nobody reads next to the number they are about to act on. */
+    readonly limits: ReadonlyArray<string>;
+}
+
+/**
+ * Build the lifecycle report.
+ *
+ * Pure: definitions + rows + a clock in, a report out. Nothing here reads a
+ * store, so every rule above is unit-testable at a chosen instant.
+ */
+export declare const flagLifecycleReport: (input: FlagLifecycleInput) => FlagLifecycleReport;
+
 /** A persisted override row (`_voltro_feature_flags`). `targeting` is JSON. */
 declare interface FlagOverrideRow {
     readonly key: string;
@@ -181,18 +370,67 @@ export declare interface FlagSchedule {
     };
 }
 
+/** What the DEFINITION alone proves about a flag. */
+export declare type FlagShape = 
+/** Serves the same answer to everyone, forever: `rollout` ≥ 100, no
+*  targeting, no variants, no live schedule. The flag is a constant `true`. */
+'constantOn'
+/** `enabled: false`, or a rollout of 0 — a constant `false`. The guarded path
+*  is unreachable THROUGH THIS FLAG (which is not the same as unreachable). */
+| 'constantOff'
+/** A schedule whose `deactivateAt` has passed. It can never be on again. */
+| 'expired'
+/** A schedule whose `activateAt` is still in the future. Not dead — pending. */
+| 'notYetActive'
+/** Genuinely does work: a partial rollout, targeting, variants, or a ramp. */
+| 'conditional';
+
 export declare const flagsPlugin: (options?: FlagsPluginOptions) => VoltroPlugin;
 
 export declare interface FlagsPluginOptions {
     /** Flags as code. The baseline; a postgres store overlays runtime toggles. */
     readonly flags?: Record<string, FlagValue>;
+    /**
+     * Flags declared with `defineFlag()` — a per-flag VALUE Schema, so a wrong
+     * default is a compile error and a runtime override that does not match is
+     * refused instead of served. Their keys join the same namespace as `flags`;
+     * a key in both is refused at construction.
+     */
+    readonly typedFlags?: ReadonlyArray<AnyTypedFlag>;
+    /**
+     * The `defineExperiment()` definitions any typed flag links to via
+     * `experiment:`. Required when at least one does — the linkage is validated
+     * at construction (see `experimentLink.ts` for why a name alone is not
+     * enough), and an unvalidated link reports uplift for a split nobody served.
+     */
+    readonly experiments?: ReadonlyArray<LinkedExperimentLike>;
+    /** Evaluation observation + dead-flag reporting. */
+    readonly usage?: FlagUsageOptions;
     /** `'memory'` (config-as-code, default) | `'postgres'` (runtime-toggleable
      *  via `_voltro_feature_flags`, overlaid on the config baseline). */
     readonly store?: 'memory' | 'postgres';
     /** Declarative gate: map an rpc tag (or regex) → flag key. A call to a gated
      *  tag fails `FlagDisabled` BEFORE the handler runs when the flag is off. */
     readonly gatedBy?: Record<string, string>;
-    /** Disambiguates multiple instances. */
+    /**
+     * Namespace for this plugin's rpc tags + inspect endpoints. Default `flags`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     *
+     * The cost, stated because nothing else states it: the local and cloud
+     * dashboards fetch this plugin's panel at the DEFAULT slug, so an aliased
+     * install keeps working while its dashboard panel 404s. Alias to escape a
+     * collision, not for taste.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-flags#analytics`). Not a rename — for that use
+     * `alias`.
+     */
     readonly name?: string;
 }
 
@@ -239,9 +477,154 @@ export declare interface FlagTargetingRule {
     readonly metadata?: Record<string, string>;
 }
 
+/**
+ * Process-wide evaluation buffer.
+ *
+ * A module-level singleton for the same reason `registry` is one: the guards
+ * (`isFlagEnabled`, `requireFlag`) are free functions a handler calls without
+ * reaching the plugin instance, so the recorder has to be reachable the same
+ * way. Recording is OFF until the plugin turns it on — an app on the memory
+ * tier, or one that opted out, pays nothing but a boolean check.
+ */
+declare class FlagUsageBuffer {
+    private on;
+    private readonly pending;
+    /** Since-process-start counters, surfaced live in the inspect payload. Never
+     *  persisted — see the header on why a persisted count would be a lie. */
+    private readonly liveCounts;
+    enable(): void;
+    disable(): void;
+    get enabled(): boolean;
+    record(flag: string, source: FlagUsageSource, at?: number): void;
+    /** Take + clear the pending set. The caller owns writing it. */
+    drain(): ReadonlyArray<BufferEntry>;
+    /** Put drained entries back after a failed flush — a store hiccup must not
+     *  silently erase the observation that keeps a flag classified `active`. */
+    restore(entries: ReadonlyArray<BufferEntry>): void;
+    /** Targeted evaluations this PROCESS has seen, per flag. */
+    liveTargetedCounts(): ReadonlyMap<string, number>;
+    /** Test seam — resets everything, including the live counters. */
+    reset(): void;
+}
+
+export declare const flagUsageBuffer: FlagUsageBuffer;
+
+export declare interface FlagUsageCoverage {
+    /** Is evaluation being recorded at all? `false` ⇒ every `usage` is `untracked`. */
+    readonly tracking: boolean;
+    /** ISO day of the earliest retained observation, or null when there is none. */
+    readonly observedSince: string | null;
+    /** Whole days between `observedSince` and now. 0 when nothing is observed. */
+    readonly observedDays: number;
+    /** The retention TTL in days — the hard ceiling on `observedDays`. */
+    readonly retentionDays: number;
+    /** The threshold a `stale` verdict is measured against. */
+    readonly staleAfterDays: number;
+}
+
+export declare interface FlagUsageFlushHandle {
+    /** Write whatever is buffered right now. */
+    readonly flushNow: () => Promise<void>;
+    /** Stop the timer AND write the last window — a shutdown that drops it is how
+     *  a flag evaluated only in the final minutes reads as stale. */
+    readonly stop: () => Promise<void>;
+}
+
+export declare interface FlagUsageFlushOptions {
+    readonly store: FlagUsageStore;
+    /** How often the buffer is written. Default 5 min. */
+    readonly intervalMs?: number;
+    readonly log?: {
+        readonly warn?: (message: string, fields?: Record<string, unknown>) => void;
+    };
+}
+
+/** Tunables for evaluation observation + the dead-flag report. Every number the
+ *  framework would otherwise choose on your behalf is a field with a default. */
+export declare interface FlagUsageOptions {
+    /**
+     * Record which flags are evaluated, so the lifecycle report can answer "not
+     * consulted since when".
+     *
+     * Default: ON when `store: 'postgres'`, OFF otherwise — the memory tier has
+     * no store to write to. Setting `true` on the memory tier is refused at
+     * construction rather than silently ignored: a dead-flag report that
+     * quietly observed nothing is the failure mode this whole feature is about.
+     */
+    readonly track?: boolean;
+    /** How often buffered observations are written. Default 5 min — the report's
+     *  resolution is a DAY, so a tighter interval buys nothing. */
+    readonly flushIntervalMs?: number;
+    /** A flag with no server-side read in this many days is reported `stale`.
+     *  Default 30. Must be ≤ `retentionDays`, or staleness is never provable. */
+    readonly staleAfterDays?: number;
+    /** How long observations are kept. Default 90 days; also settable with
+     *  `VOLTRO_FLAG_USAGE_TTL_HOURS`, which wins. This is the report's hard
+     *  observation ceiling, not just a disk bound. */
+    readonly retentionDays?: number;
+}
+
+/** One persisted observation, as the report reads it. */
+export declare interface FlagUsageRow {
+    readonly flag: string;
+    readonly day: string;
+    readonly source: FlagUsageSource;
+    readonly lastAt: Date;
+}
+
+export declare const flagUsageRowId: (flag: string, day: string, source: FlagUsageSource) => string;
+
+/** Which kind of read produced the observation. See the header for why the
+ *  distinction is load-bearing rather than bookkeeping. */
+export declare type FlagUsageSource = 'targeted' | 'bulk';
+
+export declare interface FlagUsageStore {
+    readonly upsertMany: (entries: ReadonlyArray<{
+        readonly flag: string;
+        readonly source: FlagUsageSource;
+        readonly lastAt: Date;
+    }>) => Promise<void>;
+    readonly load: () => Promise<ReadonlyArray<FlagUsageRow>>;
+}
+
+/**
+ * One (flag, UTC day, source) observation.
+ *
+ * `lastAt` is last-writer-wins across replicas, which is exactly right at this
+ * grain — every writer's value falls inside the same day, and the day is the
+ * resolution the report uses.
+ */
+export declare const flagUsageTable: Table<"_voltro_feature_flag_usage", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly flag: ColumnBuilder<string, "text", boolean>;
+    /** UTC calendar day, `YYYY-MM-DD`. */
+    readonly day: ColumnBuilder<string, "text", boolean>;
+    /** `targeted` | `bulk`. */
+    readonly source: ColumnBuilder<string, "text", boolean>;
+    /** The most recent evaluation seen in this bucket. Also the retention clock. */
+    readonly lastAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, "byFlagUsageLastAt" | "byFlagUsageFlag">;
+
+/** What the OBSERVATIONS prove about a flag. Only `stale` is a proof. */
+export declare type FlagUsageVerdict = 'evaluated' | 'stale' | 'neverObserved' | 'untracked';
+
 /** A flag value as authored: bare boolean (kill-switch) OR a rich definition. */
 export declare type FlagValue = boolean | FlagDefinition;
 
+/**
+ * The typed value of a `defineFlag()` flag for the caller.
+ *
+ * Returns `A`, not `unknown` and not a union — the payoff of declaring a value
+ * Schema. The value comes from the LIVE registry (so a postgres-tier override
+ * is reflected), decoded against the flag's own Schema, falling back to the
+ * declared `default`.
+ *
+ * ```ts
+ * const size: number = flagValue(ctx, pageSize)
+ * ```
+ */
+export declare const flagValue: <A>(ctx: GuardCtx, flag: TypedFlag<A>) => A;
+
 /** One multivariate variant: a named value with an optional rollout weight. */
 export declare interface FlagVariant {
     /** Stable variant name (the resolution returns this). */
@@ -253,6 +636,19 @@ export declare interface FlagVariant {
     readonly weight?: number;
 }
 
+/**
+ * The NAME of the variant served to the caller — the arm to persist on a row so
+ * a `defineExperiment({ variantFrom })` can measure it (IN-11).
+ *
+ * ```ts
+ * await ctx.store.insert('orders', { …, checkoutArm: flagVariant(ctx, checkoutButton) })
+ * ```
+ *
+ * Returns `null` when the flag is not in the registry — writing a guessed arm
+ * would put rows in a bucket the flag never served.
+ */
+export declare const flagVariant: (ctx: GuardCtx, flag: AnyTypedFlag) => string | null;
+
 /** A concrete variant value — string / number / boolean / JSON. Kept browser-safe. */
 export declare type FlagVariantValue = string | number | boolean | null | ReadonlyArray<unknown> | Record<string, unknown>;
 
@@ -261,6 +657,27 @@ export declare type FlagVariantValue = string | number | boolean | null | Readon
  *  companion for callers that don't need the old value. */
 export declare const flipFlagEnabled: (key: string, enabled: boolean) => boolean | null;
 
+/**
+ * Gate a merged flag definition for a TYPED flag against its Schema.
+ *
+ * Returns the definition when every variant value decodes, or a refusal.
+ * `mergeOverrides` has already produced one definition from (config baseline ⊕
+ * DB row) by the time this runs, so the question is not "is the row valid" but
+ * "can this flag serve what the merged definition says it serves".
+ *
+ * A partial acceptance is not on offer, and that is the decision worth
+ * defending: dropping the ONE bad variant re-normalises the weights of the rest,
+ * so a typo in a 5% arm silently reallocates the other 95% — a change nobody
+ * asked for, applied to every subject, reported nowhere.
+ */
+export declare const gateOverride: (flag: AnyTypedFlag, merged: FlagDefinition) => {
+    readonly ok: true;
+    readonly definition: FlagDefinition;
+} | {
+    readonly ok: false;
+    readonly refusal: OverrideRefusal;
+};
+
 /** Loose ctx shape: the framework `AppContext` (`ctx.request.subject`) OR a
  *  bare `{ subject }`. */
 declare type GuardCtx = {
@@ -274,15 +691,66 @@ declare type GuardCtx = {
 /** `true` if the flag is on for the caller. */
 export declare const isFlagEnabled: (ctx: GuardCtx, key: string) => boolean;
 
+export declare const isTypedFlag: (value: unknown) => value is AnyTypedFlag;
+
+/** The part of a `defineExperiment` result this check needs. An
+ *  `ExperimentDefinition` from `@voltro/runtime` satisfies it structurally. */
+export declare interface LinkedExperimentLike {
+    readonly name: string;
+    readonly variants: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    /** Non-null ⇒ the experiment READS its arm off the row (the only mode that
+     *  can honestly measure a flag). Null/absent ⇒ it assigns its own. */
+    readonly variantFrom?: unknown;
+    /** Fraction held out of the experiment's OWN assignment. Must be 0 for a
+     *  flag-driven experiment — see the check below. */
+    readonly holdout?: number;
+}
+
 /** Overlay persisted override rows on top of the config baseline. An override
  *  fully replaces the config flag's definition (last-write-wins), so toggling a
  *  flag off in the DB beats the code default. Pure. */
 export declare const mergeOverrides: (config: Record<string, FlagValue>, rows: ReadonlyArray<FlagOverrideRow>) => Record<string, FlagValue>;
 
+/** Why a runtime override was refused — surfaced in the boot/inspect log so a
+ *  dashboard edit that "did nothing" says what it did instead. */
+export declare interface OverrideRefusal {
+    readonly key: string;
+    readonly reason: string;
+}
+
+/** Record one flag evaluation. A no-op (one boolean read) when tracking is off. */
+export declare const recordFlagEvaluation: (flag: string, source: FlagUsageSource, at?: number) => void;
+
+/**
+ * Retention for the observation table.
+ *
+ * Registered together with the table, in the same change, because the two are
+ * one decision: the TTL is also the report's OBSERVATION CEILING. A flag cannot
+ * be shown as "not evaluated in 120 days" when the evidence only reaches back
+ * 90 — `flagLifecycleReport` reads this number and downgrades the finding to
+ * `insufficientHistory` rather than guessing.
+ */
+export declare const registerFlagUsageRetention: (env?: NodeJS.ProcessEnv, defaultDays?: number) => number;
+
 /** Effect-native guard — fails typed `FlagDisabled` when the flag is off for
  *  the caller. Declare `error: FlagDisabled` on the procedure for a typed client. */
 export declare const requireFlag: (ctx: GuardCtx, key: string) => Effect.Effect<void, FlagDisabled>;
 
+/**
+ * A resolved variant as either side sees it: the server gets it from
+ * `evaluateVariant`, the browser from the `flags.variants` wire payload. Both
+ * shapes are `{ name, value, enabled }`, which is why one function can serve
+ * both — and why it must, since a server guard and the component it gates
+ * disagreeing about a flag's value is the exact bug typing this was for.
+ */
+export declare interface ResolvedFlagVariant {
+    readonly name: string;
+    readonly value: unknown;
+    readonly enabled: boolean;
+}
+
 /**
  * Resolve WHICH variant a subject gets — deterministic + stable, weighted by
  * each variant's `weight` (equal split when omitted). Buckets on a `variant`-
@@ -297,9 +765,92 @@ export declare const resolveVariant: (key: string, def: FlagDefinition, subject:
  *  persists only when a postgres overlay store is wired. */
 export declare const setFlagEnabled: (key: string, enabled: boolean) => boolean;
 
+export declare const startFlagUsageFlush: (options: FlagUsageFlushOptions) => FlagUsageFlushHandle;
+
 /** Normalise a bare boolean to a definition. */
 export declare const toDefinition: (value: FlagValue) => FlagDefinition;
 
+/**
+ * A flag with a value type.
+ *
+ * `out A` is load-bearing rather than decorative: the plugin holds these in one
+ * `ReadonlyArray<TypedFlag<unknown>>`, which is only sound while every member
+ * that mentions `A` is a read position. If you add a field that CONSUMES an `A`
+ * (a `(value: A) => …` callback, say), that annotation is what will stop you —
+ * and the fix is to erase it behind a function returning a result, the way
+ * `decode` already does, not to drop the annotation.
+ */
+export declare interface TypedFlag<out A> {
+    /** Brand — lets the plugin discriminate a typed flag from a bare `FlagValue`. */
+    readonly _voltroTypedFlag: true;
+    /** The flag key. Shares the flag namespace with `flags: { … }` entries; a
+     *  duplicate is refused at plugin construction. */
+    readonly key: string;
+    /** Human label of the value Schema (`number`, `"a" | "b"`, …) — for the
+     *  dashboard panel and for the refusal message when an override fails to
+     *  decode. Derived from the Schema's AST, so it cannot drift from it. */
+    readonly valueType: string;
+    /** The value served whenever the flag does not resolve to a variant: it is
+     *  off for this caller, or it declares no variants at all. Compile-checked
+     *  against the Schema. */
+    readonly defaultValue: A;
+    /** The value arms. Empty ⇒ the flag always serves `defaultValue` (which the
+     *  lifecycle report classifies as `constantOn`/`constantOff` — a flag that
+     *  cannot serve anything else is one to delete). */
+    readonly variants: ReadonlyArray<TypedFlagVariant<A>>;
+    /** Decode an untrusted value against the flag's Schema — the runtime half of
+     *  the contract `default` gets at compile time. */
+    readonly decode: (input: unknown) => FlagDecodeResult<A>;
+    /** The evaluator-facing definition. This is what goes into the registry the
+     *  existing `evaluateFlag` / `resolveVariant` already read; nothing about
+     *  evaluation changes because a flag is typed. */
+    readonly definition: FlagDefinition;
+    /**
+     * IN-11 — the `defineExperiment` this flag's variants report uplift for.
+     *
+     * A NAME rather than the definition object, on purpose: `defineExperiment`
+     * lives in `@voltro/runtime`, which is server-only, and this module has to
+     * stay loadable in a browser bundle. The link is validated at BOOT, where
+     * both sides are known (`assertFlagExperimentLinkage`) — a flag naming an
+     * experiment that does not exist, or whose arms disagree with the flag's,
+     * refuses to start rather than reporting uplift for arms nobody is served.
+     */
+    readonly experiment?: string;
+}
+
+/** One named arm of a typed flag. `value` is checked against the flag's Schema
+ *  at COMPILE time. Weights behave exactly as `FlagVariant.weight`. */
+export declare interface TypedFlagVariant<out A> {
+    readonly name: string;
+    readonly value: A;
+    /** Relative allocation weight. Omit ⇒ equal split. */
+    readonly weight?: number;
+}
+
+/**
+ * The typed value for a resolution.
+ *
+ * DECODE FIRST, fall back to `defaultValue` — never branch on `enabled`. That
+ * ordering is what makes every case come out right with one rule:
+ *
+ *   - off, boolean-typed flag  → the resolution's value IS `false`, and `false`
+ *     decodes against `Schema.Boolean`. The caller gets `false`, not whatever
+ *     the author happened to write as `default`.
+ *   - off, value-typed flag    → the resolution's value is the boolean `false`,
+ *     which does NOT decode against `Schema.Number` / a literal union, so the
+ *     caller gets `defaultValue`. Correct, and reached without a special case.
+ *   - on, with variants        → the served variant's value decodes.
+ *   - unknown / not yet loaded → no resolution at all → `defaultValue`.
+ *
+ * A decode failure is silent HERE on purpose: this runs per read, on the hot
+ * path, and the values that can reach it are gated at the point they ENTER the
+ * registry (`gateOverride`), where there is a logger and a boot to fail.
+ */
+export declare const typedValueOf: <A>(flag: TypedFlag<A>, resolution: ResolvedFlagVariant | undefined) => A;
+
+/** UTC calendar day of an instant, `YYYY-MM-DD`. */
+export declare const utcDay: (at: Date) => string;
+
 /** The result of resolving a multivariate flag for a subject. */
 export declare interface VariantResolution {
     /** The resolved variant name. */