Deterministic Feature-Flag Bucketing

Percentage rollouts and multi-variant splits that assign the same subject the same variant in every service and every language.

THE SILENT FAILURE. A rollout assigns users by hashing an id. If two services hash differently -- a different algorithm, salt, concatenation order, or just JavaScript's 32-bit bitwise coercion against a 64-bit hash elsewhere -- the SAME user gets variant A in one service and B in another. Nothing errors. The user sees an inconsistent product, and the experiment's results are silently corrupted because exposure disagrees with assignment. Teams debug this for weeks.

The second silent failure is bucket instability: raising a rollout from 10 to 20 percent should KEEP the original cohort and only add new subjects. A naive implementation reshuffles everyone, users flip mid-experiment, and the analysis is worthless. Monotonicity here is tested, not asserted.

The byte-level composition is specified exactly so an independent implementation in another language can be written from the README and agree.

A REAL BUG FOUND BEFORE RELEASE. NUL is the field separator used to compose the hashed input, and it was not rejected in any input -- so a subject id containing NUL could shift across the separator boundary and land in the SAME bucket as an unrelated triple. Two different inputs both produced bucket 5960. The one character capable of breaking the encoding was unguarded and had zero test coverage. Now refused, with the reason spelled out.

VERIFIED: 102 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateFlag(config: FlagConfig, subject: Subject): Evaluation;
  export function bucketingInput(flagKey: string, salt: string, subjectId: string): string;
  export function digestHex(flagKey: string, salt: string, subjectId: string): string;
  export function computeBucket(flagKey: string, salt: string, subjectId: string): number;
  export function resolveRollout(rollout: RolloutConfig, bucket: number): ResolvedRollout | null;
  export function simulateDistribution( config: FlagConfig, sampleSize: number, options: DistributionOptions = {}, ): DistributionReport;
  export function validateFlagConfig(config: FlagConfig): void;

  export type AttributeValue = string | number | boolean;
  export type RuleOp = "equals" | "in";
  export type RolloutConfig = BooleanRollout | SplitRollout | NoRollout;
  export type AssignmentReason = | { kind: "rule";