> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluation and privacy

> Define, validate, evaluate, inspect, and project Superflag configuration

# Evaluation and privacy

## Define a typed config

```ts theme={null}
import { createEvaluator, defineConfig } from "@superflag-sh/core"

const config = defineConfig({
  schemaVersion: 1,
  source: { app: "store", environment: "prod" },
  configVersion: 42,
  flags: {
    checkout: {
      type: "boolean",
      description: "Enable the new checkout",
      tags: ["checkout"],
      owner: "growth",
      lifecycle: "active",
      enabled: true,
      visibility: "server",
      variations: {
        off: { value: false },
        on: { value: true },
      },
      offVariation: "off",
      fallthrough: { variation: "on" },
    },
  },
} as const)
```

`defineConfig` validates at runtime while preserving literal TypeScript types.
Use `validateConfig` for a list of issues and `parseConfig` when invalid input
should throw.

## Evaluate with an explicit fallback

```ts theme={null}
const details = createEvaluator(config).boolean(
  "checkout",
  {
    targetingKey: "user-123",
    attributes: { plan: "pro" },
  },
  false,
)
```

Evaluation details include the value, variation, reason, source, config version,
timestamp, matched rule and segments, prerequisite results, and stable errors.
Missing flags, invalid context, type mismatches, cycles, and evaluation failures
return the caller's fallback.

## Deterministic rollouts

Weights use integer units out of 100,000. Assignment is stable for a flag,
variation allocation, and targeting key. Allocations may total less than
100,000; unallocated buckets continue to fallthrough. Progressive rollouts
interpolate between two explicit allocations at an explicit instant.

## Inspect before you change

`explainEvaluation` returns ordered eligibility, assignment, evaluation, and
exposure-candidate stages at a caller-supplied time. `dependencyPaths`,
`impactPaths`, `testSegmentMembership`, and `simulateProposedConfig` reuse the
same evaluator so previews do not drift from runtime behavior.

The exposure-candidate stage is advisory. Inspection does not emit telemetry or
prove that the user encountered a feature.

## Project configuration to clients

```ts theme={null}
import { projectClientConfig, sanitizeContext } from "@superflag-sh/core"

const clientConfig = projectClientConfig(config)
const safeContext = sanitizeContext(context, ["plan", "country"])
```

Flags and segments are server-only unless explicitly marked client-visible.
Client projection rejects a visible flag with a server-only prerequisite or
segment. `sanitizeContext` always keeps `targetingKey` and copies only approved
attributes.

Client-side evaluation reveals delivered rules and comparison values. Keep
sensitive rules on the server, use remote evaluation, or produce an evaluated
client snapshot instead.